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 prototypes 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 prototypes 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 that create and destruct runtime Mod instances
90 *
91 * // create a heap-based runtime instance
92 * // The number and type of other parameters is module-specific
93 * Mod_Handle Mod_create( ..., Mod_Params *prms, Error_Block *eb)
94 *
95 * // destroy a heap-based runtime instance
96 * // Can be safely called only for instances created by Mod_create()
97 * Void Mod_delete(Mod_Handle *hPtr)
98 *
99 * // create a stack-based or a static runtime instance
100 * // The number and type of other parameters is module-specific
101 * Void Mod_construct(Mod_Struct *obj, ..., Mod_Params *prms, Error_Block *eb)
102 *
103 * // destroy a stack-based or a static runtime instance
104 * // Can be safely called only for instances created by Mod_construct()
105 * Void Mod_destruct(Mod_Struct *obj)
106 *
107 * // methods to access the instances managed by Mod
108 *
109 * // return heap used to create instances
110 * IHeap_Handle Mod_Object_heap();
111 *
112 * // return count of static instances
113 * Int Mod_Object_count();
114 *
115 * // get the i'th instance object of an array of instance objects
116 * //
117 * // If the array reference is NULL, get the i'th statically created
118 * // instance object.
119 * Mod_Object *Mod_Object_get(Mod_Object *array, Int i);
120 *
121 * // get the first "live" runtime instance
122 * Mod_Object *Mod_Object_first();
123 *
124 * // get the next "live" runtime instance
125 * Mod_Object *Mod_Object_next(Mod_Object *obj);
126 *
127 * // methods that operate on instance handles
128 *
129 * // fill in buf structure with instance's label info, returns buf
130 * Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);
131 *
132 * // returns name of the instance inst, if it has one (otherwise NULL)
133 * String Mod_Handle_name(Mod_Handle inst);
134 *
135 * // type-safe conversion of module handle to interface handle
136 * // Returns NULL if the conversion is not valid
137 * IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);
138 *
139 * // type-safe conversion of interface handle to module handle
140 * // Returns NULL if the conversion is not valid
141 * Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);
142 *
143 * // get the module that created the handle
144 * Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
145 * @p
146 */
147 interface IModule {
148
149 /*!
150 * ======== common$ ========
151 * Common module configuration parameters
152 *
153 * All modules have this configuration parameter. Its name contains the '$'
154 * character to ensure it does not conflict with configuration parameters
155 * declared by the module. This allows new configuration parameters to be
156 * added in the future without any chance of breaking existing modules.
157 */
158 metaonly config Types.Common$ common$;
159
160 /*!
161 * ======== viewNameMap$ ========
162 * Specifies the ROV views for the module.
163 * @_nodoc
164 *
165 * Maps the view name to the RovView descriptor.
166 */
167 metaonly config Types.ViewInfo viewNameMap$[string];
168
169 /*!
170 * ======== rovShowRawTab$ ========
171 * @_nodoc
172 */
173 metaonly config Bool rovShowRawTab$ = true;
174
175 /*!
176 * ======== configNameMap$ ========
177 * @_nodoc
178 */
179 metaonly readonly config Types.ViewInfo configNameMap$[string] = [
180 ["xdc.runtime/Memory", {viewType: "module", fields: [
181 "common$.instanceHeap", "common$.instanceSection",
182 "common$.memoryPolicy",
183 "common$.namedModule", "common$.namedInstance",
184 "common$.fxntab", "common$.romPatchTable"
185 ]}],
186 ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
187 "common$.logger",
188 "common$.diags_ASSERT", "common$.diags_ENTRY",
189 "common$.diags_EXIT", "common$.diags_INTERNAL",
190 "common$.diags_LIFECYCLE",
191 "common$.diags_STATUS",
192 "common$.diags_USER1",
193 "common$.diags_USER2", "common$.diags_USER3",
194 "common$.diags_USER4", "common$.diags_USER5",
195 "common$.diags_USER6", "common$.diags_INFO",
196 "common$.diags_ANALYSIS"
197 ]}],
198 ["xdc.runtime/Concurrency", {viewType: "module", fields: [
199 "common$.gate", "common$.gateParams"
200 ]}],
201 ["xdc.runtime/Log Events", {viewType: "module", fields: [
202 "Log.Event"]}],
203 ["xdc.runtime/Log Events", {viewType: "instance", fields: [
204 "Log.Event"]}],
205 ["xdc.runtime/Asserts", {viewType: "module", fields: [
206 "Assert.Id"]}],
207 ["xdc.runtime/Asserts", {viewType: "instance", fields: [
208 "Assert.Id"]}],
209 ["xdc.runtime/Errors", {viewType: "module", fields: [
210 "Error.Id"]}],
211 ["xdc.runtime/Errors", {viewType: "instance", fields: [
212 "Error.Id"]}],
213 ];
214
215 /*! @_nodoc */
216 @System config Bits32 Module__diagsEnabled = 0;
217 /*! @_nodoc */
218 @System config Bits32 Module__diagsIncluded = 0;
219 /*! @_nodoc */
220 @System config Bits16* Module__diagsMask = null;
221
222 /*! @_nodoc */
223 @System config Ptr Module__gateObj = null;
224 /*! @_nodoc */
225 @System config Ptr Module__gatePrms = null;
226
227 /*! @_nodoc */
228 @System config Types.ModuleId Module__id = 0;
229
230 /*! @_nodoc */
231 @System config Bool Module__loggerDefined = false;
232 /*! @_nodoc */
233 @System config Ptr Module__loggerObj = null;
234 /*! @_nodoc */
235 @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
236 /*! @_nodoc */
237 @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
238 /*! @_nodoc */
239 @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
240 /*! @_nodoc */
241 @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
242 /*! @_nodoc */
243 @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
244
245 /*! @_nodoc */
246 @System config Int Object__count = 0;
247 /*! @_nodoc */
248 @System config IHeap.Handle Object__heap = null;
249 /*! @_nodoc */
250 @System config SizeT Object__sizeof = 0;
251 /*! @_nodoc */
252 @System config Ptr Object__table = null;
253
254 /*!
255 * ======== Handle__label ========
256 * Initialize a `Types.Label` from an instance handle
257 * @_nodoc
258 *
259 * @param(obj) input instance handle
260 * @param(lab) pointer to `Label` struct to initialize from `obj`
261 */
262 @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
263
264 /*! @_nodoc */
265 @System Bool Module__startupDone();
266
267 /*! @_nodoc
268 * aa - address of "required" create args structure
269 * pa - address of instance parameter structure
270 * psz - sizeof of parameter structure
271 * eb - error block pointer
272 *
273 * Currently, we keep Object__create and Object__delete because these are
274 * the functions used in virtual tables. All Object__create functions have
275 * the same signature so we can use SysFxns2 to define a type for virtual
276 * tables instead of using a different type for each module. we could
277 * delete these two functions.
278 */
279 @System Ptr Object__create(CPtr aa, const UChar *pa, SizeT psz,
280 Error.Block *eb);
281
282 /*! @_nodoc */
283 @System Void Object__delete(Ptr instp);
284
285 /*! @_nodoc */
286 @System Ptr Object__get(Ptr oarr, Int i);
287
288 /*!
289 * ======== Object__first ========
290 * Return the first member of a list of dynamically created instances
291 * @_nodoc
292 *
293 * @a(warning) The methods `first()` and `next()` are not thread-safe.
294 * The caller must ensure that no instances are removed or
295 * added while the list is being traversed.
296 *
297 * @a(returns)
298 * Returns a handle to a first instance or `NULL` if there are no
299 * instances in the list.
300 */
301 @System Ptr Object__first();
302
303 /*!
304 * ======== Object__next ========
305 * Return the next instance from the list of dynamically created instances
306 * @_nodoc
307 *
308 * @param(obj) handle to a dynamically created instance
309 *
310 * @a(returns)
311 * Returns a handle to a first instance or `NULL` if there are no
312 * instances in the list
313 */
314 @System Ptr Object__next(Ptr obj);
315
316 /*! @_nodoc */
317 @System Void Params__init(Ptr dst, const void *src, SizeT psz, SizeT isz);
318
319 /*! @_nodoc */
320 @System Bool Proxy__abstract();
321
322 /*! @_nodoc */
323 @System CPtr Proxy__delegate();
324 }
325 326 327
328