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