1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 package xdc.runtime;
18
19 /*!
20 * ======== Types ========
21 * Basic constants and types
22 *
23 * This module defines basic constants and types used throughout the
24 * `xdc.runtime` package and, in some cases, in every module.
25 *
26 * The `{@link #Common$ Common$}` structure defined by the `Types` module
27 * is available for (or common to) all modules. Every field of the
28 * `Common$` structure is a configuration parameter that may be set within
29 * a configuration script for any module (not just the
30 * `xdc.runtime` modules). The fields of this structure are typically read
31 * by the modules in the `xdc.runtime` package at configuration time to
32 * control the generation of data structures that are embedded in the
33 * application and referenced by these modules at runtime.
34 *
35 * Every module has a configuration parameter named
36 * `{@link #common$ common$}` that is of type `Common$`. This allows the user
37 * of any module to control the module's diagnostics, where its instances
38 * are allocated, how they are allocated, and (for gated modules) what
39 * gate it should use to protect critical sections.
40 *
41 * @a(Examples)
42 * Configuration example: The following configuration script specifies
43 * that the instance objects managed by the `Memory` module in the
44 * `xdc.runtime` package should be placed in the ".fast" memory section
45 * and that `ENTRY` diagnostics should be available at runtime.
46 *
47 * @p(code)
48 * var Memory = xdc.useModule('xdc.runtime.Memory");
49 * Memory.common$.instanceSection = ".fast";
50 * Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF
51 * @p
52 *
53 * Note that by setting `Memory.common$.diags_ENTRY` to `Diags.RUNTIME_OFF`
54 * we are both enabling `ENTRY` events and specifying that they are initially
55 * disabled; they must be explicitly enabled at runtime. See the
56 * `{@link Diags}` modules for additional information.
57 */
58
59 @CustomHeader
60
61 module Types {
62
63 /*!
64 * ======== ModuleId ========
65 * Unique module identifier
66 *
67 * Module IDs are assigned at configuration time based in the set
68 * of modules that are "used" in the application. So, although each
69 * module has a unique 16-bit ID at runtime this ID may vary between
70 * configurations of the application.
71 *
72 * To save precious data space, module names are managed by the
73 * `{@link Text}` module and it is this table that is used to assign
74 * module IDs. If the table is maintained on the target, the module ID
75 * is an "index" into this table; otherwise, the module ID is simply
76 * a unique integer less than the total number of modules in the
77 * application.
78 *
79 * Although module IDs are not independent of an application's
80 * configuration, a module's ID may be compared to a runtime value
81 * symbolically. Every module has a (generated) method that returns
82 * the module's ID; e.g., a module named `Task` has a method named
83 * `Task_Module_id()` which returns `Task`'s module ID.
84 *
85 * @p(code)
86 * #include <xdc/runtime/Types.h>
87 * #include <ti/sysbios/knl/Task.h>
88 * :
89 * void checkId(Types_ModuleId modId) {
90 * if (Task_Module_id() == modId) {
91 * System_printf("Task module");
92 * }
93 * }
94 * @p
95 */
96 typedef Bits16 ModuleId;
97
98 /*!
99 * ======== Event ========
100 * `{@link ILogger}` event encoding
101 *
102 * Whereas a `{@link Log#Event}` encodes an event ID and a mask, a
103 * `Types_Event` encodes the same event ID and the module ID of the
104 * module containing the call site that generated the `Types_Event`.
105 */
106 typedef Bits32 Event;
107
108 /*!
109 * ======== getEventId ========
110 * Get event ID of the specified event
111 *
112 * This method is used to get an ID that can be compared to other
113 * "known" IDs. For example, after a `{@link #Event Types_Event}` is
114 * generated, the following code determines if the event
115 * corresponds to a `{@link Log#L_create}` event:
116 * @p(code)
117 * Bool isCreateEvent(Types_Event evt) {
118 * return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
119 * }
120 * @p
121 *
122 * @param(evt) an event created via `{@link #makeEvent}`
123 *
124 * @a(returns) This function returns the event ID of a specified event.
125 */
126 @Macro RopeId getEventId(Event evt);
127
128 /*!
129 * ======== getModuleId ========
130 * Get the module ID for the specified event
131 *
132 * @param(evt) an event created via `{@link #makeEvent}`
133 *
134 * @a(returns) This function returns the module ID of a specified event.
135 */
136 @Macro ModuleId getModuleId(Event evt);
137
138 /*!
139 * ======== makeEvent ========
140 * Make an Event from an Event ID and a module ID
141 *
142 * @param(id) ID of the event itself
143 * @param(callSite) the module from which this event originated
144 *
145 * @a(returns) This function returns an event.
146 */
147 @Macro Event makeEvent(RopeId id, ModuleId callSite);
148
149 /*!
150 * ======== EventId ========
151 * @_nodoc
152 *
153 * Deprecated name for `Types.Event`; ids are often encoded as a field
154 * in the event itself.
155 */
156 typedef Event EventId;
157
158 /*! @_nodoc */
159 struct CordAddr__;
160
161 /*! @_nodoc */
162 typedef CordAddr__ *CordAddr;
163
164 /*! @_nodoc */
165 struct GateRef__;
166
167 /*! @_nodoc */
168 typedef GateRef__ *GateRef;
169
170 /*! @_nodoc */
171 typedef Bits16 RopeId;
172
173 /*!
174 * ======== CreatePolicy ========
175 * Instance creation policy
176 */
177 enum CreatePolicy {
178 STATIC_POLICY, /*! static creation only; no runtime create/delete */
179 CREATE_POLICY, /*! dynamic creation, but no deletion */
180 DELETE_POLICY /*! dynamic creation and deletion */
181 };
182
183 /*!
184 * ======== Label ========
185 * Instance label struct
186 *
187 * Label structures are used to provide human readable names for
188 * instance handles.
189 *
190 * It is possible to initialize a `Label` from any instance handle. All
191 * modules that support instances provide a method named
192 * `Mod_Handle_label()` which, given an instance handle and a pointer to
193 * a `Label` structure, initializes the structure with all available
194 * information. For example, the following code fragment initializes a
195 * `Label` from an instance of the `HeapMin` module.
196 * @p(code)
197 * HeapMin_Handle heap;
198 * Types_Label label;
199 * HeapMin_Handle_label(heap, &label);
200 * @p
201 *
202 * Unless you explicitly disable it, `{@link System#printf System_printf}`
203 * can be used to convert a pointer to a `Label` into an human readable
204 * "instance name". Continuing with the example above, the following
205 * line can be used to print the an instance's label.
206 * @p(code)
207 * System_printf("heap instance name: %$L\n", &label);
208 * @p
209 *
210 * @see System#printf, System#extendedFormats
211 * @see Text#putLabel
212 */
213 struct Label {
214 Ptr handle; /*! instance object address */
215 ModuleId modId; /*! corresponding module id */
216 String iname; /*! name supplied during instance creation */
217 Bool named; /*! true, if `iname` is available */
218 };
219
220 /*!
221 * ======== Site ========
222 * Error site description struct
223 *
224 * This structure describes the location of the line that raised
225 * an error.
226 *
227 * @field(mod) the module id of the module containing the call site
228 * @field(file) the name of the file containing the call site or `NULL`;
229 * some call sites omit the file name to save data space.
230 * @field(line) the line number within the file named
231 */
232 struct Site {
233 ModuleId mod; /*! module id of this site */
234 String file; /*! filename of this site */
235 Int line; /*! line number of this site */
236 };
237
238 /*!
239 * ======== Timestamp64 ========
240 * 64-bit timestamp struct
241 *
242 * Some platforms only support 32-bit timestamps. In this case,
243 * the most significant 32-bits are always set to 0.
244 */
245 struct Timestamp64 {
246 Bits32 hi; /*! most significant 32-bits of timestamp */
247 Bits32 lo; /*! least significant 32-bits of timestamp */
248 };
249
250 /*!
251 * ======== FreqHz ========
252 * Frequency-in-hertz struct
253 */
254 struct FreqHz {
255 Bits32 hi; /*! most significant 32-bits of frequency */
256 Bits32 lo; /*! least significant 32-bits of frequency */
257 };
258
259 /*!
260 * ======== Common$ ========
261 * Common module config struct
262 *
263 * Every module contains this structure during the configuration
264 * phase. The fields of this structure are set in configuration scripts
265 * and referenced by the modules in the `xdc.runtime` package. For default
266 * values of these fields, see `{@link Defaults}`.
267 *
268 * @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's
269 * diagnostics mask.
270 *
271 * @field(diags_ENTRY) The `{@link Diags#ENTRY}` bit of a module's
272 * diagnostics mask.
273 *
274 * @field(diags_EXIT) The `{@link Diags#EXIT}` bit of a module's
275 * diagnostics mask.
276 *
277 * @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's
278 * diagnostics mask.
279 *
280 * @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` bit of a module's
281 * diagnostics mask.
282 *
283 * @field(diags_USER1) The `{@link Diags#USER1}` bit of a module's
284 * diagnostics mask.
285 *
286 * @field(diags_USER2) The `{@link Diags#USER2}` bit of a module's
287 * diagnostics mask.
288 *
289 * @field(diags_USER3) The `{@link Diags#USER3}` bit of a module's
290 * diagnostics mask.
291 *
292 * @field(diags_USER4) The `{@link Diags#USER4}` bit of a module's
293 * diagnostics mask.
294 *
295 * @field(diags_USER5) The `{@link Diags#USER5}` bit of a module's
296 * diagnostics mask.
297 *
298 * @field(diags_USER6) The `{@link Diags#USER6}` bit of a module's
299 * diagnostics mask.
300 *
301 * @field(diags_USER7) The `{@link Diags#USER7}` bit of a module's
302 * diagnostics mask.
303 *
304 * @field(diags_USER8) The `{@link Diags#USER8}` bit of a module's
305 * diagnostics mask.
306 *
307 * @field(fxntab)
308 * This configurtation parameter is only applicable to modules that
309 * inherit an interface and have instance objects. Setting `fxntab`
310 * to `false` can save some data space but also prevents the
311 * application from using instance objects through abstract interfaces.
312 *
313 * Function tables are used whenever it's necessary to call a module's
314 * methods via an abstract interface; e.g., the `{@link Memory}` module
315 * calls methods defined by the `{@link IHeap}` interface but there may
316 * be several distinct modules that implement this interface. In order
317 * for this type of call to be possible, instance objects contain a
318 * reference to a function table containing the instance module's
319 * functions; the caller gets the module's function from the instance
320 * object and calls through a function pointer. Every module that
321 * inherits an interface has such a table and modules that do not
322 * inherit an interface do not have a function table.
323 *
324 * If this configuration parameter is set to `false`, the module's
325 * instance objects will NOT be initialized with a reference to their
326 * module's function table and, since the function table will not
327 * be referenced by the application, the resulting executable will be
328 * smaller. However, if this parameter is `false` you must never
329 * attempt to use this module's instance objects via reference this
330 * module through an abstract interface. Since this is often hard to
331 * determine, especially as an application evolves over time, you should
332 * only set this parameter to `false` when you are absolutely sure that
333 * the module's functions are always only being directly called and you
334 * need to absolutely minimize the data footprint of your application.
335 *
336 * The default for this parameter is `true`.
337 *
338 * @field(gate) A handle to the module-level `{@link IGateProvider}`
339 * instance to be used when this module calls functions from
340 * `{@link Gate}`
341 *
342 * @field(gateParams) `Gate` parameters used by this module to create
343 * the gates used when this module calls
344 * `{@link Gate#allocInstance() Gate_allocInstance}`
345 *
346 * @field(instanceHeap) Identifies the heap from which this module
347 * should allocate memory.
348 *
349 * @field(instanceSection) Identifies the section in which instances
350 * created by this module should be placed.
351 *
352 * @field(logger) The handle of the logger instance used by the module.
353 * All log events generated by the module are routed to this logger
354 * instance. See `{@link ILogger}` for details on the logger interface.
355 * See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of
356 * logger instances provided by the `{@link xdc.runtime}` package.
357 *
358 * @field(memoryPolicy) Specifies whether this module should allow
359 * static object creation only (`{@link #CreatePolicy STATIC_POLICY}`),
360 * dynamic object creation but not deletion
361 * (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object
362 * creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`).
363 *
364 * @field(namedInstance) If set to `true`, each instance object is
365 * given an additional field to hold a string name that is used
366 * when displaying information about an instance. Setting this to
367 * true increases the size of the module's instance objects by a
368 * single word but improves the usability of tools that display
369 * instance objects.
370 *
371 * @field(namedModule) If set to `true`, this module's string name
372 * is retained on the target so that it can be displayed as part
373 * of `{@link Log}` and `{@link Error}` events. Setting this to `false`
374 * saves data space in the application at the expense of readability
375 * of log and error messages associated with this module.
376 *
377 * Note: setting this to `false` also prevents one from controlling the
378 * module's diagnostics at runtime via `{@link Diags#setMask()}`.
379 * This method uses the module's name to lookup the module's
380 * diagnostics mask. It is still possible to control the module's
381 * diagnostics at design-time from a configuration script.
382 *
383 * @see Diags, Defaults
384 */
385 metaonly struct Common$ {
386 Diags.Mode diags_ASSERT; /*! module's Diags assert mode */
387 Diags.Mode diags_ENTRY; /*! module's function entry Diags mode */
388 Diags.Mode diags_EXIT; /*! module's function exit Diags mode */
389 Diags.Mode diags_INTERNAL; /*! module's internal assert mode */
390 Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */
391 Diags.Mode diags_USER1; /*! module's user1 Diags mode */
392 Diags.Mode diags_USER2; /*! module's user2 Diags mode */
393 Diags.Mode diags_USER3; /*! module's user3 Diags mode */
394 Diags.Mode diags_USER4; /*! module's user4 Diags mode */
395 Diags.Mode diags_USER5; /*! module's user5 Diags mode */
396 Diags.Mode diags_USER6; /*! module's user6 Diags mode */
397 Diags.Mode diags_USER7; /*! module's user7 Diags mode */
398 Diags.Mode diags_USER8; /*! module's user8 Diags mode */
399 Bool fxntab; /*! @_nodoc enable function tables */
400 IGateProvider.Handle gate; /*! module's gate */
401 Ptr gateParams; /*! gate params for module created gates */
402 IHeap.Handle instanceHeap; /*! module's instance heap */
403 String instanceSection; /*! memory section for module's instances*/
404 ILogger.Handle logger; /*! module's logger */
405 CreatePolicy memoryPolicy; /*! module's memory policy */
406 Bool namedInstance; /*! true => instances have string names */
407 Bool namedModule; /*! true => module's name is on target */
408 Bool romPatchTable; /*! @_nodoc */
409 }
410
411 /*!
412 * ======== RtaDecoderData ========
413 * @_nodoc
414 */
415 @XmlDtd metaonly struct RtaDecoderData {
416 String targetName;
417 String binaryParser;
418 String endian;
419 Int bitsPerChar;
420 Int argSize;
421 Int eventSize;
422 String loggers[];
423 struct {
424 Int id;
425 String logger;
426 String diagsMask;
427 } modMap[string];
428 struct {
429 Int id;
430 String msg;
431 } evtMap[string];
432 };
433
434 /*!
435 * ======== ViewInfo ========
436 * @_nodoc
437 * XGconf view descriptor.
438 */
439 metaonly struct ViewInfo {
440 String viewType;
441 String viewFxn;
442 String fields[];
443 }
444
445 internal:
446
447 typedef Void (*LoggerFxn4)(Ptr, EventId, IArg, IArg, IArg, IArg);
448 typedef Void (*LoggerFxn8)(Ptr, EventId, IArg, IArg, IArg, IArg,
449 IArg, IArg, IArg, IArg);
450
451 struct Vec {
452 Int len;
453 Ptr arr;
454 };
455
456 struct Link {
457 Link *next;
458 Link *prev;
459 };
460
461 struct ModHdr {
462 Link link;
463 UChar *instArrBeg;
464 UChar *instArrEnd;
465 SizeT instSize;
466 UChar *curInst;
467 Bits16 diagsMask;
468 };
469
470 struct ModHdrS {
471 Bits16 diagsMask;
472 }
473
474 struct InstHdr {
475 Link link;
476 }
477
478 struct PrmsHdr {
479 SizeT size;
480 Ptr self;
481 Ptr modFxns;
482 Ptr instPrms;
483 }
484
485 struct Base {
486 Base *base;
487 }
488
489 struct SysFxns {
490 Ptr (*__create)(Ptr, SizeT, const Ptr, const Ptr, SizeT, Error.Block*);
491 Void (*__delete)(Ptr);
492 Label *(*__label)(Ptr, Label *);
493 ModuleId __mid;
494 }
495
496 struct SysFxns2 {
497 Ptr (*__create)(Ptr, SizeT, const Ptr, const UChar *, SizeT, Error.Block *);
498 Void (*__delete)(Ptr);
499 Label *(*__label)(Ptr, Label *);
500 ModuleId __mid;
501 }
502
503 }
504 505 506
507