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