1 /*
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * */
13 /*
14 * ======== Types.xdc ========
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 * It is possible to initialize a `Label` from any instance handle. All
188 * modules that support instances provide a method named
189 * `Mod_Handle_label()` which, given an instance handle and a pointer to
190 * a `Label` structure, initializes the structure with all available
191 * information. For example, the following code fragment initializes a
192 * `Label` from an instance of the `HeapMin` module.
193 * @p(code) 194 * HeapMin_Handle heap;
195 * Types_Label label;
196 * HeapMin_Handle_label(heap, &label);
197 * @p 198 */
199 struct Label {
200 Ptr handle; /*! instance object address */
201 ModuleId modId; /*! corresponding module id */
202 String iname; /*! name supplied during instance creation */
203 Bool named; /*! true, if `iname` is available */
204 };
205
206 /*!
207 * ======== Site ========
208 * Error site description struct
209 *
210 * This structure describes the location of the line that raised
211 * an error.
212 *
213 * @field(mod) the module id of the module containing the call site
214 * @field(file) the name of the file containing the call site or `NULL`;
215 * some call sites omit the file name to save data space.
216 * @field(line) the line number within the file named
217 */
218 struct Site {
219 ModuleId mod; /*! module id of this site */
220 String file; /*! filename of this site */
221 Int line; /*! line number of this site */
222 };
223
224 /*!
225 * ======== Timestamp64 ========
226 * 64-bit timestamp struct
227 *
228 * Some platforms only support 32-bit timestamps. In this case,
229 * the most significant 32-bits are always set to 0.
230 */
231 struct Timestamp64 {
232 Bits32 hi; /*! most significant 32-bits of timestamp */
233 Bits32 lo; /*! least significant 32-bits of timestamp */
234 };
235
236 /*!
237 * ======== FreqHz ========
238 * Frequency-in-hertz struct
239 */
240 struct FreqHz {
241 Bits32 hi; /*! most significant 32-bits of frequency */
242 Bits32 lo; /*! least significant 32-bits of frequency */
243 };
244
245 /*!
246 * ======== Common$ ========
247 * Common module config struct
248 *
249 * Every module contains this structure during the configuration
250 * phase. The fields of this structure are set in configuration scripts
251 * and referenced by the modules in the `xdc.runtime` package. For default
252 * values of these fields, see `{@link Defaults}`.
253 *
254 * @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's
255 * diagnostics mask.
256 *
257 * @field(diags_ENTRY) The `{@link Diags#ENTRY}` bit of a module's
258 * diagnostics mask.
259 *
260 * @field(diags_EXIT) The `{@link Diags#EXIT}` bit of a module's
261 * diagnostics mask.
262 *
263 * @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's
264 * diagnostics mask.
265 *
266 * @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` bit of a module's
267 * diagnostics mask.
268 *
269 * @field(diags_USER1) The `{@link Diags#USER1}` bit of a module's
270 * diagnostics mask.
271 *
272 * @field(diags_USER2) The `{@link Diags#USER2}` bit of a module's
273 * diagnostics mask.
274 *
275 * @field(diags_USER3) The `{@link Diags#USER3}` bit of a module's
276 * diagnostics mask.
277 *
278 * @field(diags_USER4) The `{@link Diags#USER4}` bit of a module's
279 * diagnostics mask.
280 *
281 * @field(diags_USER5) The `{@link Diags#USER5}` bit of a module's
282 * diagnostics mask.
283 *
284 * @field(diags_USER6) The `{@link Diags#USER6}` bit of a module's
285 * diagnostics mask.
286 *
287 * @field(diags_USER7) The `{@link Diags#USER7}` bit of a module's
288 * diagnostics mask.
289 *
290 * @field(diags_USER8) The `{@link Diags#USER8}` bit of a module's
291 * diagnostics mask.
292 *
293 * @field(fxntab) 294 * This configurtation parameter is only applicable to modules that
295 * inherit an interface and have instance objects. Setting `fxntab`
296 * to `false` can save some data space but also prevents the
297 * application from using instance objects through abstract interfaces.
298 *
299 * Function tables are used whenever it's necessary to call a module's
300 * methods via an abstract interface; e.g., the `{@link Memory}` module
301 * calls methods defined by the `{@link IHeap}` interface but there may
302 * be several distinct modules that implement this interface. In order
303 * for this type of call to be possible, instance objects contain a
304 * reference to a function table containing the instance module's
305 * functions; the caller gets the module's function from the instance
306 * object and calls through a function pointer. Every module that
307 * inherits an interface has such a table and modules that do not
308 * inherit an interface do not have a function table.
309 *
310 * If this configuration parameter is set to `false`, the module's
311 * instance objects will NOT be initialized with a reference to their
312 * module's function table and, since the function table will not
313 * be referenced by the application, the resulting executable will be
314 * smaller. However, if this parameter is `false` you must never
315 * attempt to use this module's instance objects via reference this
316 * module through an abstract interface. Since this is often hard to
317 * determine, especially as an application evolves over time, you should
318 * only set this parameter to `false` when you are absolutely sure that
319 * the module's functions are always only being directly called and you
320 * need to absolutely minimize the data footprint of your application.
321 *
322 * The default for this parameter is `true`.
323 *
324 * @field(gate) A handle to the module-level `{@link IGateProvider}`
325 * instance to be used when this module calls functions from
326 * `{@link Gate}`
327 *
328 * @field(gateParams) `Gate` parameters used by this module to create
329 * the gates used when this module calls
330 * `{@link Gate#allocInstance() Gate_allocInstance}`
331 *
332 * @field(instanceHeap) Identifies the heap from which this module
333 * should allocate memory.
334 *
335 * @field(instanceSection) Identifies the section in which instances
336 * created by this module should be placed.
337 *
338 * @field(logger) The handle of the logger instance used by the module.
339 * All log events generated by the module are routed to this logger
340 * instance. See `{@link ILogger}` for details on the logger interface.
341 * See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of
342 * logger instances provided by the `{@link xdc.runtime}` package.
343 *
344 * @field(memoryPolicy) Specifies whether this module should allow
345 * static object creation only (`{@link #CreatePolicy STATIC_POLICY}`),
346 * dynamic object creation but not deletion
347 * (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object
348 * creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`).
349 *
350 * @field(namedInstance) If set to `true`, each instance object is
351 * given an additional field to hold a string name that is used
352 * when displaying information about an instance. Setting this to
353 * true increases the size of the module's instance objects by a
354 * single word but improves the usability of tools that display
355 * instance objects.
356 *
357 * @field(namedModule) If set to `true`, this module's string name
358 * is retained on the target so that it can be displayed as part
359 * of `{@link Log}` and `{@link Error}` events. Setting this to `false`
360 * saves data space in the application at the expense of readability
361 * of log and error messages associated with this module.
362 *
363 * Note: setting this to `false` also prevents one from controlling the
364 * module's diagnostics at runtime via `{@link Diags#setMask()}`.
365 * This method uses the module's name to lookup the module's
366 * diagnostics mask. It is still possible to control the module's
367 * diagnostics at design-time from a configuration script.
368 *
369 * @see Diags, Defaults
370 */
371 metaonlystruct Common$ {
372 Diags.Mode diags_ASSERT; /*! module's Diags assert mode */
373 Diags.Mode diags_ENTRY; /*! module's function entry Diags mode */
374 Diags.Mode diags_EXIT; /*! module's function exit Diags mode */
375 Diags.Mode diags_INTERNAL; /*! module's internal assert mode */
376 Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */
377 Diags.Mode diags_USER1; /*! module's user1 Diags mode */
378 Diags.Mode diags_USER2; /*! module's user2 Diags mode */
379 Diags.Mode diags_USER3; /*! module's user3 Diags mode */
380 Diags.Mode diags_USER4; /*! module's user4 Diags mode */
381 Diags.Mode diags_USER5; /*! module's user5 Diags mode */
382 Diags.Mode diags_USER6; /*! module's user6 Diags mode */
383 Diags.Mode diags_USER7; /*! module's user7 Diags mode */
384 Diags.Mode diags_USER8; /*! module's user8 Diags mode */
385 Bool fxntab; /*! @_nodoc enable function tables */
386 IGateProvider.Handle gate; /*! module's gate */
387 Ptr gateParams; /*! gate params for module created gates */
388 IHeap.Handle instanceHeap; /*! module's instance heap */
389 String instanceSection; /*! memory section for module's instances*/
390 ILogger.Handle logger; /*! module's logger */
391 CreatePolicy memoryPolicy; /*! module's memory policy */
392 Bool namedInstance; /*! true => instances have string names */
393 Bool namedModule; /*! true => module's name is on target */
394 Bool romPatchTable; /*! @_nodoc */
395 }
396
397 /*!
398 * ======== RtaDecoderData ========
399 * @_nodoc 400 */
401 @XmlDtd metaonlystruct RtaDecoderData {
402 String targetName;
403 String binaryParser;
404 String endian;
405 Int bitsPerChar;
406 Int argSize;
407 Int eventSize;
408 String loggers[];
409 struct {
410 Int id;
411 String logger;
412 String diagsMask;
413 } modMap[string];
414 struct {
415 Int id;
416 String msg;
417 } evtMap[string];
418 };
419
420 /*!
421 * ======== ViewInfo ========
422 * @_nodoc 423 * XGconf view descriptor.
424 */
425 metaonlystruct ViewInfo {
426 String viewType;
427 String viewFxn;
428 String fields[];
429 }
430
431 internal:
432
433 typedef Void (*LoggerFxn4)(Ptr, EventId, IArg, IArg, IArg, IArg);
434 typedef Void (*LoggerFxn8)(Ptr, EventId, IArg, IArg, IArg, IArg,
435 IArg, IArg, IArg, IArg);
436
437 struct Vec {
438 Int len;
439 Ptr arr;
440 };
441
442 struct Link {
443 Link *next;
444 Link *prev;
445 };
446
447 struct ModHdr {
448 Link link;
449 UChar *instArrBeg;
450 UChar *instArrEnd;
451 SizeT instSize;
452 UChar *curInst;
453 Bits16 diagsMask;
454 };
455
456 struct ModHdrS {
457 Bits16 diagsMask;
458 }
459
460 struct InstHdr {
461 Link link;
462 }
463
464 struct PrmsHdr {
465 SizeT size; /* size of the entire parameter structure */
466 Ptr self; /* pointer to self; used to check params are init'd */
467 Ptr modFxns;
468 Ptr instPrms;
469 }
470
471 struct Base {
472 Base *base;
473 }
474
475 struct SysFxns {
476 Ptr (*__create)(Ptr, SizeT, const Ptr, const Ptr, SizeT, Error.Block*);
477 Void (*__delete)(Ptr);
478 Label *(*__label)(Ptr, Label *);
479 ModuleId __mid;
480 }
481
482 struct SysFxns2 {
483 Ptr (*__create)(Ptr, SizeT, const Ptr, const UChar *, SizeT, Error.Block *);
484 Void (*__delete)(Ptr);
485 Label *(*__label)(Ptr, Label *);
486 ModuleId __mid;
487 }
488
489 }
490 /*
491 * @(#) xdc.runtime; 2, 0, 0, 0,207; 6-9-2009 20:10:20; /db/ztree/library/trees/xdc-t50x/src/packages/
492 */
493