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