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