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 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 contains the '$'
136 * character to ensure it does not conflict with configuration parameters
137 * declared by the module. This allows new configuration parameters to be
138 * added in the future without any chance of breaking existing modules.
139 */
140 metaonly config Types.Common$ common$;
141
142 /*!
143 * ======== viewNameMap$ ========
144 * Specifies the ROV views for the module.
145 * @_nodoc
146 *
147 * Maps the view name to the RovView descriptor.
148 */
149 metaonly config Types.ViewInfo viewNameMap$[string];
150
151 /*!
152 * ======== rovShowRawTab$ ========
153 * @_nodoc
154 */
155 metaonly config Bool rovShowRawTab$ = true;
156
157 /*!
158 * ======== configNameMap$ ========
159 * @_nodoc
160 */
161 metaonly readonly config Types.ViewInfo configNameMap$[string] = [
162 ["xdc.runtime/Memory", {viewType: "module", fields: [
163 "common$.instanceHeap", "common$.instanceSection",
164 "common$.memoryPolicy",
165 "common$.namedModule", "common$.namedInstance",
166 "common$.fxntab", "common$.romPatchTable"
167 ]}],
168 ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
169 "common$.logger",
170 "common$.diags_ASSERT", "common$.diags_ENTRY",
171 "common$.diags_EXIT", "common$.diags_INTERNAL",
172 "common$.diags_LIFECYCLE",
173 "common$.diags_STATUS",
174 "common$.diags_USER1",
175 "common$.diags_USER2", "common$.diags_USER3",
176 "common$.diags_USER4", "common$.diags_USER5",
177 "common$.diags_USER6", "common$.diags_INFO",
178 "common$.diags_ANALYSIS"
179 ]}],
180 ["xdc.runtime/Concurrency", {viewType: "module", fields: [
181 "common$.gate", "common$.gateParams"
182 ]}],
183 ["xdc.runtime/Log Events", {viewType: "module", fields: [
184 "Log.Event"]}],
185 ["xdc.runtime/Log Events", {viewType: "instance", fields: [
186 "Log.Event"]}],
187 ["xdc.runtime/Asserts", {viewType: "module", fields: [
188 "Assert.Id"]}],
189 ["xdc.runtime/Asserts", {viewType: "instance", fields: [
190 "Assert.Id"]}],
191 ["xdc.runtime/Errors", {viewType: "module", fields: [
192 "Error.Id"]}],
193 ["xdc.runtime/Errors", {viewType: "instance", fields: [
194 "Error.Id"]}],
195 ];
196
197 /*! @_nodoc */
198 @System config Bits32 Module__diagsEnabled = 0;
199 /*! @_nodoc */
200 @System config Bits32 Module__diagsIncluded = 0;
201 /*! @_nodoc */
202 @System config Bits16* Module__diagsMask = null;
203
204 /*! @_nodoc */
205 @System config Ptr Module__gateObj = null;
206 /*! @_nodoc */
207 @System config Ptr Module__gatePrms = null;
208
209 /*! @_nodoc */
210 @System config Types.ModuleId Module__id = 0;
211
212 /*! @_nodoc */
213 @System config Bool Module__loggerDefined = false;
214 /*! @_nodoc */
215 @System config Ptr Module__loggerObj = null;
216 /*! @_nodoc */
217 @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
218 /*! @_nodoc */
219 @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
220 /*! @_nodoc */
221 @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
222 /*! @_nodoc */
223 @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
224 /*! @_nodoc */
225 @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
226
227 /*! @_nodoc */
228 @System config Int Object__count = 0;
229 /*! @_nodoc */
230 @System config IHeap.Handle Object__heap = null;
231 /*! @_nodoc */
232 @System config SizeT Object__sizeof = 0;
233 /*! @_nodoc */
234 @System config Ptr Object__table = null;
235
236 /*!
237 * ======== Handle__label ========
238 * Initialize a `Types.Label` from an instance handle
239 * @_nodoc
240 *
241 * @param(obj) input instance handle
242 * @param(lab) pointer to `Label` struct to initialize from `obj`
243 */
244 @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
245
246 /*! @_nodoc */
247 @System Bool Module__startupDone();
248
249 /*! @_nodoc
250 * aa - address of "required" create args structure
251 * pa - address of instance parameter structure
252 * psz - sizeof of parameter structure
253 * eb - error block pointer
254 *
255 * Currently, we keep Object__create and Object__delete because these are
256 * the functions used in virtual tables. All Object__create functions have
257 * the same signature so we can use SysFxns2 to define a type for virtual
258 * tables instead of using a different type for each module. we could
259 * delete these two functions.
260 */
261 @System Ptr Object__create(CPtr aa, const UChar *pa, SizeT psz,
262 Error.Block *eb);
263
264 /*! @_nodoc */
265 @System Void Object__delete(Ptr instp);
266
267 /*! @_nodoc */
268 @System Ptr Object__get(Ptr oarr, Int i);
269
270 /*!
271 * ======== Object__first ========
272 * Return the first member of a list of dynamically created instances
273 * @_nodoc
274 *
275 * @a(warning) The methods `first()` and `next()` are not thread-safe.
276 * The caller must ensure that no instances are removed or
277 * added while the list is being traversed.
278 *
279 * @a(returns)
280 * Returns a handle to a first instance or `NULL` if there are no
281 * instances in the list.
282 */
283 @System Ptr Object__first();
284
285 /*!
286 * ======== Object__next ========
287 * Return the next instance from the list of dynamically created instances
288 * @_nodoc
289 *
290 * @param(obj) handle to a dynamically created instance
291 *
292 * @a(returns)
293 * Returns a handle to a first instance or `NULL` if there are no
294 * instances in the list
295 */
296 @System Ptr Object__next(Ptr obj);
297
298 /*! @_nodoc */
299 @System Void Params__init(Ptr dst, const void *src, SizeT psz, SizeT isz);
300
301 /*! @_nodoc */
302 @System Bool Proxy__abstract();
303
304 /*! @_nodoc */
305 @System CPtr Proxy__delegate();
306 }
307 308 309
310