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