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 @RomConsts
61
62
63 module Types {
64
65 /*!
66 * ======== ModuleId ========
67 * Unique module identifier
68 *
69 * Module IDs are assigned at configuration time based in the set
70 * of modules that are "used" in the application. So, although each
71 * module has a unique 16-bit ID at runtime this ID may vary between
72 * configurations of the application.
73 *
74 * To save precious data space, module names are managed by the
75 * `{@link Text}` module and it is this table that is used to assign
76 * module IDs. If the table is maintained on the target, the module ID
77 * is an "index" into this table; otherwise, the module ID is simply
78 * a unique integer less than the total number of modules in the
79 * application.
80 *
81 * Although module IDs are not independent of an application's
82 * configuration, a module's ID may be compared to a runtime value
83 * symbolically. Every module has a (generated) method that returns
84 * the module's ID; e.g., a module named `Task` has a method named
85 * `Task_Module_id()` which returns `Task`'s module ID.
86 *
87 * @p(code)
88 * #include <xdc/runtime/Types.h>
89 * #include <ti/sysbios/knl/Task.h>
90 * :
91 * void checkId(Types_ModuleId modId) {
92 * if (Task_Module_id() == modId) {
93 * System_printf("Task module");
94 * }
95 * }
96 * @p
97 */
98 typedef Bits16 ModuleId;
99
100 typedef Bits16 DiagsMask;
101
102 /*!
103 * ======== Event ========
104 * `{@link ILogger}` event encoding
105 *
106 * Whereas a `{@link Log#Event}` encodes an event ID and a mask, a
107 * `Types_Event` encodes the same event ID and the module ID of the
108 * module containing the call site that generated the `Types_Event`.
109 */
110 typedef Bits32 Event;
111
112 /*!
113 * ======== getEventId ========
114 * Get event ID of the specified event
115 *
116 * This method is used to get an ID that can be compared to other
117 * "known" IDs. For example, after a `{@link #Event Types_Event}` is
118 * generated, the following code determines if the event
119 * corresponds to a `{@link Log#L_create}` event:
120 * @p(code)
121 * Bool isCreateEvent(Types_Event evt) {
122 * return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
123 * }
124 * @p
125 *
126 * @param(evt) an event created via `{@link #makeEvent}`
127 *
128 * @a(returns) This function returns the event ID of a specified event.
129 */
130 @Macro RopeId getEventId(Event evt);
131
132 /*!
133 * ======== getModuleId ========
134 * Get the module ID for the specified event
135 *
136 * @param(evt) an event created via `{@link #makeEvent}`
137 *
138 * @a(returns) This function returns the module ID of a specified event.
139 */
140 @Macro ModuleId getModuleId(Event evt);
141
142 /*!
143 * ======== makeEvent ========
144 * Make an Event from an Event ID and a module ID
145 *
146 * @param(id) ID of the event itself
147 * @param(callSite) the module from which this event originated
148 *
149 * @a(returns) This function returns an event.
150 */
151 @Macro Event makeEvent(RopeId id, ModuleId callSite);
152
153 /*!
154 * ======== EventId ========
155 * @_nodoc
156 *
157 * Deprecated name for `Types.Event`; ids are often encoded as a field
158 * in the event itself.
159 */
160 typedef Event EventId;
161
162 /*! @_nodoc */
163 struct CordAddr__;
164
165 /*! @_nodoc */
166 typedef CordAddr__ *CordAddr;
167
168 /*! @_nodoc */
169 struct GateRef__;
170
171 /*! @_nodoc */
172 typedef GateRef__ *GateRef;
173
174 /*! @_nodoc */
175 typedef Bits16 RopeId;
176
177 /*!
178 * ======== CreatePolicy ========
179 * Instance creation policy
180 */
181 enum CreatePolicy {
182 STATIC_POLICY, /*! static creation only; no runtime create/delete */
183 CREATE_POLICY, /*! dynamic creation, but no deletion */
184 DELETE_POLICY /*! dynamic creation and deletion */
185 };
186
187 /*!
188 * ======== OutputPolicy ========
189 * Destination file for module's functions
190 */
191 enum OutputPolicy {
192 COMMON_FILE, /*! functions are in the common C file */
193 SEPARATE_FILE, /*! module has its own separate file */
194 NO_FILE /*! functions are not generated */
195 };
196
197 /*!
198 * ======== Label ========
199 * Instance label struct
200 *
201 * Label structures are used to provide human readable names for
202 * instance handles.
203 *
204 * It is possible to initialize a `Label` from any instance handle. All
205 * modules that support instances provide a method named
206 * `Mod_Handle_label()` which, given an instance handle and a pointer to
207 * a `Label` structure, initializes the structure with all available
208 * information. For example, the following code fragment initializes a
209 * `Label` from an instance of the `HeapMin` module.
210 * @p(code)
211 * HeapMin_Handle heap;
212 * Types_Label label;
213 * HeapMin_Handle_label(heap, &label);
214 * @p
215 *
216 * Unless you explicitly disable it, `{@link System#printf System_printf}`
217 * can be used to convert a pointer to a `Label` into an human readable
218 * "instance name". Continuing with the example above, the following
219 * line can be used to print an instance's label.
220 * @p(code)
221 * System_printf("heap instance name: %$L\n", &label);
222 * @p
223 *
224 * @see System#printf, System#extendedFormats
225 * @see Text#putLabel
226 */
227 struct Label {
228 Ptr handle; /*! instance object address */
229 ModuleId modId; /*! corresponding module id */
230 String iname; /*! name supplied during instance creation */
231 Bool named; /*! true, if `iname` is available */
232 };
233
234 /*!
235 * ======== Site ========
236 * Error site description struct
237 *
238 * This structure describes the location of the line that raised
239 * an error.
240 *
241 * @field(mod) the module id of the module containing the call site
242 * @field(file) the name of the file containing the call site or `NULL`;
243 * some call sites omit the file name to save data space.
244 * @field(line) the line number within the file named
245 */
246 struct Site {
247 ModuleId mod; /*! module id of this site */
248 CString file; /*! filename of this site */
249 Int line; /*! line number of this site */
250 };
251
252 /*!
253 * ======== Timestamp64 ========
254 * 64-bit timestamp struct
255 *
256 * Some platforms only support 32-bit timestamps. In this case,
257 * the most significant 32-bits are always set to 0.
258 */
259 struct Timestamp64 {
260 Bits32 hi; /*! most significant 32-bits of timestamp */
261 Bits32 lo; /*! least significant 32-bits of timestamp */
262 };
263
264 /*!
265 * ======== FreqHz ========
266 * Frequency-in-hertz struct
267 */
268 struct FreqHz {
269 Bits32 hi; /*! most significant 32-bits of frequency */
270 Bits32 lo; /*! least significant 32-bits of frequency */
271 };
272
273 /*!
274 * ======== RegDesc ========
275 * Registry module descriptor
276 */
277 struct RegDesc {
278 RegDesc *next;
279 CString modName;
280 Types.ModuleId id;
281 DiagsMask mask;
282 };
283
284 /*!
285 * ======== Common$ ========
286 * Common module config struct
287 *
288 * Every module contains this structure during the configuration
289 * phase. The fields of this structure are set in configuration scripts
290 * and referenced by the modules in the `xdc.runtime` package. For default
291 * values of these fields, see `{@link Defaults}`.
292 *
293 * @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's
294 * diagnostics mask.
295 *
296 * @field(diags_ENTRY) The `{@link Diags#ENTRY}` category of a module's
297 * diagnostics mask.
298 *
299 * @field(diags_EXIT) The `{@link Diags#EXIT}` category of a module's
300 * diagnostics mask.
301 *
302 * @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's
303 * diagnostics mask.
304 *
305 * @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` category of a
306 * module's diagnostics mask.
307 *
308 * @field(diags_STATUS) The `{@link Diags#STATUS}` category of a module's
309 * diagnostics mask.
310 *
311 * @field(diags_USER1) The `{@link Diags#USER1}` category of a module's
312 * diagnostics mask.
313 *
314 * @field(diags_USER2) The `{@link Diags#USER2}` category of a module's
315 * diagnostics mask.
316 *
317 * @field(diags_USER3) The `{@link Diags#USER3}` category of a module's
318 * diagnostics mask.
319 *
320 * @field(diags_USER4) The `{@link Diags#USER4}` category of a module's
321 * diagnostics mask.
322 *
323 * @field(diags_USER5) The `{@link Diags#USER5}` category of a module's
324 * diagnostics mask.
325 *
326 * @field(diags_USER6) The `{@link Diags#USER6}` category of a module's
327 * diagnostics mask.
328 *
329 * @field(diags_USER7) The `{@link Diags#USER7}` category of a module's
330 * diagnostics mask. The bit for this category has been repurposed for the
331 * `{@link Diags#INFO}` category, so the use of USER7 has been deprecated.
332 *
333 * @field(diags_INFO) The `{@link Diags#INFO}` category of a module's
334 * diagnostics mask.
335 *
336 * @field(diags_USER8) The `{@link Diags#USER8}` category of a module's
337 * diagnostics mask. The bit for this category has been repurposed for the
338 * `{@link Diags#ANALYSIS}` category, so the use of USER8 has been
339 * deprecated.
340 *
341 * @field(diags_ANALYSIS) The `{@link Diags#ANALYSIS}` category of a
342 * module's diagnostics mask.
343 *
344 * @field(fxntab)
345 * This configuration parameter is only applicable to modules that
346 * inherit an interface and have instance objects. Setting `fxntab`
347 * to `false` can save some data space but also prevents the
348 * application from using instance objects through abstract interfaces.
349 *
350 * Function tables are used whenever it's necessary to call a module's
351 * methods via an abstract interface; e.g., the `{@link Memory}` module
352 * calls methods defined by the `{@link IHeap}` interface but there may
353 * be several distinct modules that implement this interface. In order
354 * for this type of call to be possible, instance objects contain a
355 * reference to a function table containing the instance module's
356 * functions; the caller gets the module's function from the instance
357 * object and calls through a function pointer. Every module that
358 * inherits an interface has such a table and modules that do not
359 * inherit an interface do not have a function table.
360 *
361 * If this configuration parameter is set to `false`, the module's
362 * instance objects will NOT be initialized with a reference to their
363 * module's function table and, since the function table will not
364 * be referenced by the application, the resulting executable will be
365 * smaller. However, if this parameter is `false` you must never
366 * attempt to use this module's instance objects via reference this
367 * module through an abstract interface. Since this is often hard to
368 * determine, especially as an application evolves over time, you should
369 * only set this parameter to `false` when you are absolutely sure that
370 * the module's functions are always only being directly called and you
371 * need to absolutely minimize the data footprint of your application.
372 *
373 * The default for this parameter is `true`.
374 *
375 * @field(gate) A handle to the module-level `{@link IGateProvider}`
376 * instance to be used when this module calls functions from
377 * `{@link Gate}`
378 *
379 * @field(gateParams) `Gate` parameters used by this module to create
380 * the gates used when this module calls
381 * `{@link Gate#allocInstance() Gate_allocInstance}`
382 *
383 * @field(instanceHeap) Identifies the heap from which this module
384 * should allocate memory.
385 *
386 * @field(instanceSection) Identifies the section in which instances
387 * created by this module should be placed.
388 *
389 * @field(logger) The handle of the logger instance used by the module.
390 * All log events generated by the module are routed to this logger
391 * instance. See `{@link ILogger}` for details on the logger interface.
392 * See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of
393 * logger modules provided by the `{@link xdc.runtime}` package.
394 *
395 * @field(memoryPolicy) Specifies whether this module should allow
396 * static object creation only (`{@link #CreatePolicy STATIC_POLICY}`),
397 * dynamic object creation but not deletion
398 * (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object
399 * creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`).
400 *
401 * @field(namedInstance) If set to `true`, each instance object is
402 * given an additional field to hold a string name that is used
403 * when displaying information about an instance. Setting this to
404 * `true` increases the size of the module's instance objects by a
405 * single word but improves the usability of tools that display
406 * instance objects. If set to `false`, assignments of instance
407 * names are silently ignored. This allows one to remove instance
408 * name support to save space without having to change any source code.
409 * See `{@link xdc.runtime.IInstance#name IInstance.name}` for details.
410 *
411 * @field(namedModule) If set to `true`, this module's string name
412 * is retained on the target so that it can be displayed as part
413 * of `{@link Log}` and `{@link Error}` events. Setting this to `false`
414 * saves data space in the application at the expense of readability
415 * of log and error messages associated with this module.
416 *
417 * Note: setting this to `false` also prevents one from controlling the
418 * module's diagnostics at runtime via `{@link Diags#setMask()}`.
419 * This method uses the module's name to lookup the module's
420 * diagnostics mask. It is still possible to control the module's
421 * diagnostics at design-time from a configuration script.
422 *
423 * @see Diags, Defaults
424 */
425 metaonly struct Common$ {
426 Diags.Mode diags_ASSERT; /*! module's Diags assert mode */
427 Diags.Mode diags_ENTRY; /*! module's function entry Diags mode */
428 Diags.Mode diags_EXIT; /*! module's function exit Diags mode */
429 Diags.Mode diags_INTERNAL; /*! module's internal assert mode */
430 Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */
431 Diags.Mode diags_STATUS; /*! module's errors and warnings */
432 Diags.Mode diags_USER1; /*! module's user1 Diags mode */
433 Diags.Mode diags_USER2; /*! module's user2 Diags mode */
434 Diags.Mode diags_USER3; /*! module's user3 Diags mode */
435 Diags.Mode diags_USER4; /*! module's user4 Diags mode */
436 Diags.Mode diags_USER5; /*! module's user5 Diags mode */
437 Diags.Mode diags_USER6; /*! module's user6 Diags mode */
438 Diags.Mode diags_USER7; /*! module's user7 Diags mode */
439 Diags.Mode diags_INFO; /*! module's informational event mode */
440 Diags.Mode diags_USER8; /*! module's user8 Diags mode */
441 Diags.Mode diags_ANALYSIS; /*! module's Diags analysis mode */
442 Bool fxntab; /*! @_nodoc enable function tables */
443 IGateProvider.Handle gate; /*! module's gate */
444 Ptr gateParams; /*! gate params for module created gates */
445 IHeap.Handle instanceHeap; /*! module's instance heap */
446 String instanceSection; /*! memory section for module's instances*/
447 ILogger.Handle logger; /*! module's logger */
448 OutputPolicy outPolicy; /*! destination file for module's code */
449 CreatePolicy memoryPolicy; /*! module's memory policy */
450 Bool namedInstance; /*! true => instances have string names */
451 Bool namedModule; /*! true => module's name is on target */
452 Bool romPatchTable; /*! @_nodoc */
453 }
454
455 /*!
456 * ======== RtaDecoderData ========
457 * @_nodoc
458 *
459 * loggers
460 * name - Used to identify the logger in GUI
461 * bufferSym - For stop-mode; symbol at which the logger's entry
462 * buffer can be found
463 * bufferLen - For stop-mode; length of the logger's entry buffer in
464 * MAUs
465 */
466 @XmlDtd metaonly struct RtaDecoderData {
467 String targetName;
468 String binaryParser;
469 String endian;
470 Int bitsPerChar;
471 Int argSize;
472 Int eventSize;
473 String dataTransportClassName;
474 String controlTransportClassName;
475 struct {
476 String name;
477 String type;
478 Any metaArgs;
479 } loggers[ ];
480 struct {
481 Int id;
482 String logger;
483 String diagsMask;
484 } modMap[string];
485 struct {
486 Int id;
487 String msg;
488 } evtMap[string];
489 };
490
491 /*!
492 * ======== ViewInfo ========
493 * @_nodoc
494 * XGconf view descriptor.
495 */
496 metaonly struct ViewInfo {
497 String viewType;
498 String viewFxn;
499 String fields[];
500 }
501
502 internal:
503
504 typedef Bits32 LogEvent;
505
506 typedef Void (*LoggerFxn0)(Ptr, LogEvent, ModuleId);
507 typedef Void (*LoggerFxn1)(Ptr, LogEvent, ModuleId, IArg);
508 typedef Void (*LoggerFxn2)(Ptr, LogEvent, ModuleId, IArg, IArg);
509 typedef Void (*LoggerFxn4)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg);
510 typedef Void (*LoggerFxn8)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg,
511 IArg, IArg, IArg, IArg);
512
513 struct Vec {
514 Int len;
515 Ptr arr;
516 };
517
518 519 520 521
522 struct Link {
523 Link *next;
524 Link *prev;
525 };
526
527 528 529 530
531 struct InstHdr {
532 Link link;
533 }
534
535 536 537 538
539 struct PrmsHdr {
540 SizeT size;
541 Ptr self;
542 Ptr modFxns;
543 Ptr instPrms;
544 }
545
546 547 548 549
550 struct Base {
551
552 Base *base;
553 }
554
555 556 557 558
559 struct SysFxns {
560 Ptr (*__create)(Ptr, SizeT, Ptr, const Ptr, SizeT, Error.Block*);
561 Void (*__delete)(Ptr);
562 Label *(*__label)(Ptr, Label *);
563 ModuleId __mid;
564 }
565
566 567 568 569
570 struct SysFxns2 {
571
572 573 574 575 576 577 578 579 580 581 582 583 584 585
586 Ptr (*__create)(Ptr, SizeT, Ptr, const UChar *, SizeT, Error.Block *);
587
588
589 Void (*__delete)(Ptr);
590 Label *(*__label)(Ptr, Label *);
591 ModuleId __mid;
592 }
593 }
594 595 596
597