1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 /*!
18 * ======== IModule ========
19 * Base interface for all modules
20 *
21 * All modules share a common set of configuration parameters and methods.
22 *
23 * @a(internal)
24 * This section provides a terse summary of the methods provided by every
25 * module for use within the module's implementation. Each method's
26 * prototype is shown along with a brief summary of its behavior.
27 * These methods are declared in the module's internal header which should
28 * always be included in any file referencing these functions. For a
29 * module named `Mod` the following statement includes this header.
30 * @p(code)
31 * #include "package/internal/Mod.xdc.h"
32 * @p
33 *
34 * In the protypes below, `Mod` refers to the module being implemented,
35 * `embeddedObj` is the name of field in the module's state structure that
36 * is either an embedded object field or an array of such objects, and
37 * `fld` is the name of a field declared in the module's state structure.
38 *
39 * @p(code)
40 * // enter the module's gate
41 * IArg Mod_Module_enter(Gate_Handle gate);
42 *
43 * // leave the module's gate
44 * Mod_Module_leave(Gate_Handle, IArg);
45 *
46 * // return a pointer to the embeddedObj field
47 * Ptr Mod_Module_State_embeddedObj();
48 *
49 * // the value of the fld field of the module's state structure
50 * Mod_module->fld; // fld is declared in module's .xdc file
51 * @p
52 *
53 * @a(external)
54 * This section provides a terse summary of the methods provided by every
55 * module for use by an application or other modules. Each method's
56 * prototype is shown along with a brief summary of its behavior.
57 * These methods are declared in the module's header which should always
58 * be included in any file referencing these functions. For a module named
59 * `Mod` in the package named `a.b.c`, the following statement includes this
60 * header.
61 * @p(code)
62 * #include <a/b/c/Mod.h>
63 * @p
64 *
65 * In the protypes below, `IMod` referes to some interface, `Mod` refers to
66 * a module that (optionally) inherits from `IMod`, and `pkgName` is the
67 * name of the package containing the interface `IMod`.
68 * @p(code)
69 *
70 * // methods to operate on modules
71 *
72 * // return heap associated with this module
73 * IHeap_Handle Mod_Module_heap();
74 *
75 * // get Mod's module ID
76 * Types_ModuleId Mod_Module_id();
77 *
78 * // return TRUE if Mod's startup is complete
79 * Bool Mod_Module_startupDone();
80 *
81 * // type-safe conversion from an interface to an inheriting module
82 * // Returns NULL if the conversion is not valid
83 * Mod_Handle Mod_Handle_downCast(IMod_Handle handle);
84 *
85 * // type-safe conversion from a module to an interface it inherits from
86 * // Returns NULL if the conversion is not valid
87 * IMod_Handle Mod_Handle_upCast(Mod_Module_Handle handle);
88 *
89 * // methods to access the instances managed by Mod
90 *
91 * // return heap used to create instances
92 * IHeap_Handle Mod_Object_heap();
93 *
94 * // return count of static instances
95 * Int Mod_Object_count();
96 *
97 * // get the i'th instance object of an array of instance objects
98 * //
99 * // If the array reference is NULL, get the i'th statically created
100 * // instance object.
101 * Mod_Object *Mod_Object_get(Mod_Object *array, Int i);
102 *
103 * // get the first "live" runtime instance
104 * Mod_Object *Mod_Object_first();
105 *
106 * // get the next "live" runtime instance
107 * Mod_Object *Mod_Object_next(Mod_Object *obj);
108 *
109 * // methods that operate on instance handles
110 *
111 * // fill in buf structure with instance's label info, returns buf
112 * Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);
113 *
114 * // returns name of the instance inst, if it has one (otherwise NULL)
115 * String Mod_Handle_name(Mod_Handle inst);
116 *
117 * // type-safe conversion of module handle to interface handle
118 * // Returns NULL if the conversion is not valid
119 * IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);
120 *
121 * // type-safe conversion of interface handle to module handle
122 * // Returns NULL if the conversion is not valid
123 * Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);
124 *
125 * // get the module that created the handle
126 * Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
127 * @p
128 */
129 interface IModule {
130
131 /*!
132 * ======== common$ ========
133 * Common module configuration parameters
134 *
135 * All modules have this configuration parameter. Its name
136 * contains the '$' character to ensure it does not conflict with
137 * configuration parameters declared by the module. This allows
138 * new configuration parameters to be added in the future without
139 * any chance of breaking existing modules.
140 */
141 metaonly config Types.Common$ common$;
142
143 /*!
144 * ======== viewNameMap$ ========
145 * Specifies the ROV views for the module.
146 * @_nodoc
147 *
148 * Maps the view name to the RovView descriptor.
149 */
150 metaonly config Types.ViewInfo viewNameMap$[string];
151
152 /*!
153 * ======== rovShowRawTab$ ========
154 * @_nodoc
155 */
156 metaonly config Bool rovShowRawTab$ = true;
157
158 /*!
159 * ======== configNameMap$ ========
160 * @_nodoc
161 */
162 metaonly readonly config Types.ViewInfo configNameMap$[string] = [
163 ["xdc.runtime/Memory", {viewType: "module", fields: [
164 "common$.instanceHeap", "common$.instanceSection",
165 "common$.memoryPolicy",
166 "common$.namedModule", "common$.namedInstance",
167 "common$.fxntab", "common$.romPatchTable"
168 ]}],
169 ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
170 "common$.logger",
171 "common$.diags_ASSERT", "common$.diags_ENTRY",
172 "common$.diags_EXIT", "common$.diags_INTERNAL",
173 "common$.diags_LIFECYCLE",
174 "common$.diags_STATUS",
175 "common$.diags_USER1",
176 "common$.diags_USER2", "common$.diags_USER3",
177 "common$.diags_USER4", "common$.diags_USER5",
178 "common$.diags_USER6", "common$.diags_INFO",
179 "common$.diags_ANALYSIS"
180 ]}],
181 ["xdc.runtime/Concurrency", {viewType: "module", fields: [
182 "common$.gate", "common$.gateParams"
183 ]}],
184 ["xdc.runtime/Log Events", {viewType: "module", fields: [
185 "Log.Event"]}],
186 ["xdc.runtime/Log Events", {viewType: "instance", fields: [
187 "Log.Event"]}],
188 ["xdc.runtime/Asserts", {viewType: "module", fields: [
189 "Assert.Id"]}],
190 ["xdc.runtime/Asserts", {viewType: "instance", fields: [
191 "Assert.Id"]}],
192 ["xdc.runtime/Errors", {viewType: "module", fields: [
193 "Error.Id"]}],
194 ["xdc.runtime/Errors", {viewType: "instance", fields: [
195 "Error.Id"]}],
196 ];
197
198 /*! @_nodoc */
199 @System config Bits32 Module__diagsEnabled = 0;
200 /*! @_nodoc */
201 @System config Bits32 Module__diagsIncluded = 0;
202 /*! @_nodoc */
203 @System config Bits16* Module__diagsMask = null;
204
205 /*! @_nodoc */
206 @System config Ptr Module__gateObj = null;
207 /*! @_nodoc */
208 @System config Ptr Module__gatePrms = null;
209
210 /*! @_nodoc */
211 @System config Types.ModuleId Module__id = 0;
212
213 /*! @_nodoc */
214 @System config Bool Module__loggerDefined = false;
215 /*! @_nodoc */
216 @System config Ptr Module__loggerObj = null;
217 /*! @_nodoc */
218 @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
219 /*! @_nodoc */
220 @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
221 /*! @_nodoc */
222 @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
223 /*! @_nodoc */
224 @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
225 /*! @_nodoc */
226 @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
227
228 /*! @_nodoc
229 * This parameter is not used, but we keep it for forward compatibility.
230 * If we can ever break the forward compatibility for a release, we
231 * should remove this parameter.
232 *
233 * Once we remove it, header files built with those tools would break
234 * older tools.
235 */
236 @System config Bool (*Module__startupDoneFxn)() = null;
237
238 /*! @_nodoc */
239 @System config Int Object__count = 0;
240 /*! @_nodoc */
241 @System config IHeap.Handle Object__heap = null;
242 /*! @_nodoc */
243 @System config SizeT Object__sizeof = 0;
244 /*! @_nodoc */
245 @System config Ptr Object__table = null;
246
247 /*!
248 * ======== Handle__label ========
249 * Initialize a `Types.Label` from an instance handle
250 * @_nodoc
251 *
252 * @param(obj) input instance handle
253 * @param(lab) pointer to `Label` struct to initialize from `obj`
254 */
255 @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
256
257 /*! @_nodoc */
258 @System Bool Module__startupDone();
259
260 /*! @_nodoc */
261 @System Ptr Object__create(Ptr __oa, SizeT __osz, Ptr __aa,
262 const UChar *__pa, SizeT __psz, Error.Block *__eb);
263 /*! @_nodoc */
264 @System Void Object__delete(Ptr instp);
265 /*! @_nodoc */
266 @System Void Object__destruct(Ptr objp);
267
268 /*! @_nodoc */
269 @System Ptr Object__get(Ptr oarr, Int i);
270
271 /*!
272 * ======== Object__first ========
273 * Return the first member of a list of dynamically created instances
274 * @_nodoc
275 *
276 * @a(warning) The methods `first()` and `next()` are not thread-safe.
277 * The caller must ensure that no instances are removed or
278 * added while the list is being traversed.
279 *
280 * @a(returns)
281 * Returns a handle to a first instance or `NULL` if there are no
282 * instances in the list.
283 */
284 @System Ptr Object__first();
285
286 /*!
287 * ======== Object__next ========
288 * Return the next instance from the list of dynamically created instances
289 * @_nodoc
290 *
291 * @param(obj) handle to a dynamically created instance
292 *
293 * @a(returns)
294 * Returns a handle to a first instance or `NULL` if there are no
295 * instances in the list
296 */
297 @System Ptr Object__next(Ptr obj);
298
299 /*! @_nodoc */
300 @System Void Params__init(Ptr dst, const void *src, SizeT psz, SizeT isz);
301
302 /*! @_nodoc */
303 @System Bool Proxy__abstract();
304 /*! @_nodoc */
305 @System Ptr Proxy__delegate();
306
307 }
308 309 310
311