| /* --COPYRIGHT--,ESD |
| * Copyright (c) 2008 Texas Instruments. All rights reserved. |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v1.0 and Eclipse Distribution License |
| * v. 1.0 which accompanies this distribution. The Eclipse Public License is |
| * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse |
| * Distribution License is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * Contributors: |
| * Texas Instruments - initial implementation |
| * --/COPYRIGHT--*/ |
| /* |
| * ======== Types.xdc ======== |
| */ |
| |
| package xdc.runtime; |
| |
| /*! |
| * ======== Types ======== |
| * Basic constants and types |
| * |
| * This module defines basic constants and types used throughout the |
| * `xdc.runtime` package and, in some cases, in every module. |
| * |
| * The `{@link #Common$ Common$}` structure defined by the `Types` module |
| * is available for (or common to) all modules. Every field of the |
| * `Common$` structure is a configuration parameter that may be set within |
| * a configuration script for any module (not just the |
| * `xdc.runtime` modules). The fields of this structure are typically read |
| * by the modules in the `xdc.runtime` package at configuration time to |
| * control the generation of data structures that are embedded in the |
| * application and referenced by these modules at runtime. |
| * |
| * Every module has a configuration parameter named |
| * `{@link #common$ common$}` that is of type `Common$`. This allows the user |
| * of any module to control the module's diagnostics, where its instances |
| * are allocated, how they are allocated, and (for gated modules) what |
| * gate it should use to protect critical sections. |
| * |
| * @a(Examples) |
| * Configuration example: The following configuration script specifies |
| * that the instance objects managed by the `Memory` module in the |
| * `xdc.runtime` package should be placed in the ".fast" memory section |
| * and that `ENTRY` diagnostics should be available at runtime. |
| * |
| * @p(code) |
| * var Memory = xdc.useModule('xdc.runtime.Memory"); |
| * Memory.common$.instanceSection = ".fast"; |
| * Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF |
| * @p |
| * |
| * Note that by setting `Memory.common$.diags_ENTRY` to `Diags.RUNTIME_OFF` |
| * we are both enabling `ENTRY` events and specifying that they are initially |
| * disabled; they must be explicitly enabled at runtime. See the |
| * `{@link Diags}` modules for additional information. |
| */ |
| |
| @CustomHeader |
| |
| module Types { |
| |
| /*! |
| * ======== ModuleId ======== |
| * Unique module identifier |
| * |
| * Module IDs are assigned at configuration time based in the set |
| * of modules that are "used" in the application. So, although each |
| * module has a unique 16-bit ID at runtime this ID may vary between |
| * configurations of the application. |
| * |
| * To save precious data space, module names are managed by the |
| * `{@link Text}` module and it is this table that is used to assign |
| * module IDs. If the table is maintained on the target, the module ID |
| * is an "index" into this table; otherwise, the module ID is simply |
| * a unique integer less than the total number of modules in the |
| * application. |
| * |
| * Although module IDs are not independent of an application's |
| * configuration, a module's ID may be compared to a runtime value |
| * symbolically. Every module has a (generated) method that returns |
| * the module's ID; e.g., a module named `Task` has a method named |
| * `Task_Module_id()` which returns `Task`'s module ID. |
| * |
| * @p(code) |
| * #include <xdc/runtime/Types.h> |
| * #include <ti/sysbios/knl/Task.h> |
| * : |
| * void checkId(Types_ModuleId modId) { |
| * if (Task_Module_id() == modId) { |
| * System_printf("Task module"); |
| * } |
| * } |
| * @p |
| */ |
| typedef Bits16 ModuleId; |
| |
| typedef Bits16 DiagsMask; |
| |
| /*! |
| * ======== Event ======== |
| * `{@link ILogger}` event encoding |
| * |
| * Whereas a `{@link Log#Event}` encodes an event ID and a mask, a |
| * `Types_Event` encodes the same event ID and the module ID of the |
| * module containing the call site that generated the `Types_Event`. |
| */ |
| typedef Bits32 Event; |
| |
| /*! |
| * ======== getEventId ======== |
| * Get event ID of the specified event |
| * |
| * This method is used to get an ID that can be compared to other |
| * "known" IDs. For example, after a `{@link #Event Types_Event}` is |
| * generated, the following code determines if the event |
| * corresponds to a `{@link Log#L_create}` event: |
| * @p(code) |
| * Bool isCreateEvent(Types_Event evt) { |
| * return (Log_getEventId(Log_L_create) == Types_getEventId(evt)); |
| * } |
| * @p |
| * |
| * @param(evt) an event created via `{@link #makeEvent}` |
| * |
| * @a(returns) This function returns the event ID of a specified event. |
| */ |
| @Macro RopeId getEventId(Event evt); |
| |
| /*! |
| * ======== getModuleId ======== |
| * Get the module ID for the specified event |
| * |
| * @param(evt) an event created via `{@link #makeEvent}` |
| * |
| * @a(returns) This function returns the module ID of a specified event. |
| */ |
| @Macro ModuleId getModuleId(Event evt); |
| |
| /*! |
| * ======== makeEvent ======== |
| * Make an Event from an Event ID and a module ID |
| * |
| * @param(id) ID of the event itself |
| * @param(callSite) the module from which this event originated |
| * |
| * @a(returns) This function returns an event. |
| */ |
| @Macro Event makeEvent(RopeId id, ModuleId callSite); |
| |
| /*! |
| * ======== EventId ======== |
| * @_nodoc |
| * |
| * Deprecated name for `Types.Event`; ids are often encoded as a field |
| * in the event itself. |
| */ |
| typedef Event EventId; |
| |
| /*! @_nodoc */ |
| struct CordAddr__; |
| |
| /*! @_nodoc */ |
| typedef CordAddr__ *CordAddr; |
| |
| /*! @_nodoc */ |
| struct GateRef__; |
| |
| /*! @_nodoc */ |
| typedef GateRef__ *GateRef; |
| |
| /*! @_nodoc */ |
| typedef Bits16 RopeId; |
| |
| /*! |
| * ======== CreatePolicy ======== |
| * Instance creation policy |
| */ |
| enum CreatePolicy { |
| STATIC_POLICY, /*! static creation only; no runtime create/delete */ |
| CREATE_POLICY, /*! dynamic creation, but no deletion */ |
| DELETE_POLICY /*! dynamic creation and deletion */ |
| }; |
| |
| /*! |
| * ======== OutputPolicy ======== |
| * Destination file for module's functions |
| */ |
| enum OutputPolicy { |
| COMMON_FILE, /*! functions are in the common C file */ |
| SEPARATE_FILE, /*! module has its own separate file */ |
| NO_FILE /*! functions are not generated */ |
| }; |
| |
| /*! |
| * ======== Label ======== |
| * Instance label struct |
| * |
| * Label structures are used to provide human readable names for |
| * instance handles. |
| * |
| * It is possible to initialize a `Label` from any instance handle. All |
| * modules that support instances provide a method named |
| * `Mod_Handle_label()` which, given an instance handle and a pointer to |
| * a `Label` structure, initializes the structure with all available |
| * information. For example, the following code fragment initializes a |
| * `Label` from an instance of the `HeapMin` module. |
| * @p(code) |
| * HeapMin_Handle heap; |
| * Types_Label label; |
| * HeapMin_Handle_label(heap, &label); |
| * @p |
| * |
| * Unless you explicitly disable it, `{@link System#printf System_printf}` |
| * can be used to convert a pointer to a `Label` into an human readable |
| * "instance name". Continuing with the example above, the following |
| * line can be used to print an instance's label. |
| * @p(code) |
| * System_printf("heap instance name: %$L\n", &label); |
| * @p |
| * |
| * @see System#printf, System#extendedFormats |
| * @see Text#putLabel |
| */ |
| struct Label { |
| Ptr handle; /*! instance object address */ |
| ModuleId modId; /*! corresponding module id */ |
| String iname; /*! name supplied during instance creation */ |
| Bool named; /*! true, if `iname` is available */ |
| }; |
| |
| /*! |
| * ======== Site ======== |
| * Error site description struct |
| * |
| * This structure describes the location of the line that raised |
| * an error. |
| * |
| * @field(mod) the module id of the module containing the call site |
| * @field(file) the name of the file containing the call site or `NULL`; |
| * some call sites omit the file name to save data space. |
| * @field(line) the line number within the file named |
| */ |
| struct Site { |
| ModuleId mod; /*! module id of this site */ |
| CString file; /*! filename of this site */ |
| Int line; /*! line number of this site */ |
| }; |
| |
| /*! |
| * ======== Timestamp64 ======== |
| * 64-bit timestamp struct |
| * |
| * Some platforms only support 32-bit timestamps. In this case, |
| * the most significant 32-bits are always set to 0. |
| */ |
| struct Timestamp64 { |
| Bits32 hi; /*! most significant 32-bits of timestamp */ |
| Bits32 lo; /*! least significant 32-bits of timestamp */ |
| }; |
| |
| /*! |
| * ======== FreqHz ======== |
| * Frequency-in-hertz struct |
| */ |
| struct FreqHz { |
| Bits32 hi; /*! most significant 32-bits of frequency */ |
| Bits32 lo; /*! least significant 32-bits of frequency */ |
| }; |
| |
| /*! |
| * ======== RegDesc ======== |
| * Registry module descriptor |
| */ |
| struct RegDesc { |
| RegDesc *next; |
| CString modName; |
| Types.ModuleId id; |
| DiagsMask mask; |
| }; |
| |
| /*! |
| * ======== Common$ ======== |
| * Common module config struct |
| * |
| * Every module contains this structure during the configuration |
| * phase. The fields of this structure are set in configuration scripts |
| * and referenced by the modules in the `xdc.runtime` package. For default |
| * values of these fields, see `{@link Defaults}`. |
| * |
| * @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_ENTRY) The `{@link Diags#ENTRY}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_EXIT) The `{@link Diags#EXIT}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` category of a |
| * module's diagnostics mask. |
| * |
| * @field(diags_STATUS) The `{@link Diags#STATUS}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER1) The `{@link Diags#USER1}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER2) The `{@link Diags#USER2}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER3) The `{@link Diags#USER3}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER4) The `{@link Diags#USER4}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER5) The `{@link Diags#USER5}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER6) The `{@link Diags#USER6}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER7) The `{@link Diags#USER7}` category of a module's |
| * diagnostics mask. The bit for this category has been repurposed for the |
| * `{@link Diags#INFO}` category, so the use of USER7 has been deprecated. |
| * |
| * @field(diags_INFO) The `{@link Diags#INFO}` category of a module's |
| * diagnostics mask. |
| * |
| * @field(diags_USER8) The `{@link Diags#USER8}` category of a module's |
| * diagnostics mask. The bit for this category has been repurposed for the |
| * `{@link Diags#ANALYSIS}` category, so the use of USER8 has been |
| * deprecated. |
| * |
| * @field(diags_ANALYSIS) The `{@link Diags#ANALYSIS}` category of a |
| * module's diagnostics mask. |
| * |
| * @field(fxntab) |
| * This configuration parameter is only applicable to modules that |
| * inherit an interface and have instance objects. Setting `fxntab` |
| * to `false` can save some data space but also prevents the |
| * application from using instance objects through abstract interfaces. |
| * |
| * Function tables are used whenever it's necessary to call a module's |
| * methods via an abstract interface; e.g., the `{@link Memory}` module |
| * calls methods defined by the `{@link IHeap}` interface but there may |
| * be several distinct modules that implement this interface. In order |
| * for this type of call to be possible, instance objects contain a |
| * reference to a function table containing the instance module's |
| * functions; the caller gets the module's function from the instance |
| * object and calls through a function pointer. Every module that |
| * inherits an interface has such a table and modules that do not |
| * inherit an interface do not have a function table. |
| * |
| * If this configuration parameter is set to `false`, the module's |
| * instance objects will NOT be initialized with a reference to their |
| * module's function table and, since the function table will not |
| * be referenced by the application, the resulting executable will be |
| * smaller. However, if this parameter is `false` you must never |
| * attempt to use this module's instance objects via reference this |
| * module through an abstract interface. Since this is often hard to |
| * determine, especially as an application evolves over time, you should |
| * only set this parameter to `false` when you are absolutely sure that |
| * the module's functions are always only being directly called and you |
| * need to absolutely minimize the data footprint of your application. |
| * |
| * The default for this parameter is `true`. |
| * |
| * @field(gate) A handle to the module-level `{@link IGateProvider}` |
| * instance to be used when this module calls functions from |
| * `{@link Gate}` |
| * |
| * @field(gateParams) `Gate` parameters used by this module to create |
| * the gates used when this module calls |
| * `{@link Gate#allocInstance() Gate_allocInstance}` |
| * |
| * @field(instanceHeap) Identifies the heap from which this module |
| * should allocate memory. |
| * |
| * @field(instanceSection) Identifies the section in which instances |
| * created by this module should be placed. |
| * |
| * @field(logger) The handle of the logger instance used by the module. |
| * All log events generated by the module are routed to this logger |
| * instance. See `{@link ILogger}` for details on the logger interface. |
| * See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of |
| * logger modules provided by the `{@link xdc.runtime}` package. |
| * |
| * @field(memoryPolicy) Specifies whether this module should allow |
| * static object creation only (`{@link #CreatePolicy STATIC_POLICY}`), |
| * dynamic object creation but not deletion |
| * (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object |
| * creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`). |
| * |
| * @field(namedInstance) If set to `true`, each instance object is |
| * given an additional field to hold a string name that is used |
| * when displaying information about an instance. Setting this to |
| * `true` increases the size of the module's instance objects by a |
| * single word but improves the usability of tools that display |
| * instance objects. If set to `false`, assignments of instance |
| * names are silently ignored. This allows one to remove instance |
| * name support to save space without having to change any source code. |
| * See `{@link xdc.runtime.IInstance#name IInstance.name}` for details. |
| * |
| * @field(namedModule) If set to `true`, this module's string name |
| * is retained on the target so that it can be displayed as part |
| * of `{@link Log}` and `{@link Error}` events. Setting this to `false` |
| * saves data space in the application at the expense of readability |
| * of log and error messages associated with this module. |
| * |
| * Note: setting this to `false` also prevents one from controlling the |
| * module's diagnostics at runtime via `{@link Diags#setMask()}`. |
| * This method uses the module's name to lookup the module's |
| * diagnostics mask. It is still possible to control the module's |
| * diagnostics at design-time from a configuration script. |
| * |
| * @see Diags, Defaults |
| */ |
| metaonly struct Common$ { |
| Diags.Mode diags_ASSERT; /*! module's Diags assert mode */ |
| Diags.Mode diags_ENTRY; /*! module's function entry Diags mode */ |
| Diags.Mode diags_EXIT; /*! module's function exit Diags mode */ |
| Diags.Mode diags_INTERNAL; /*! module's internal assert mode */ |
| Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */ |
| Diags.Mode diags_STATUS; /*! module's errors and warnings */ |
| Diags.Mode diags_USER1; /*! module's user1 Diags mode */ |
| Diags.Mode diags_USER2; /*! module's user2 Diags mode */ |
| Diags.Mode diags_USER3; /*! module's user3 Diags mode */ |
| Diags.Mode diags_USER4; /*! module's user4 Diags mode */ |
| Diags.Mode diags_USER5; /*! module's user5 Diags mode */ |
| Diags.Mode diags_USER6; /*! module's user6 Diags mode */ |
| Diags.Mode diags_USER7; /*! module's user7 Diags mode */ |
| Diags.Mode diags_INFO; /*! module's informational event mode */ |
| Diags.Mode diags_USER8; /*! module's user8 Diags mode */ |
| Diags.Mode diags_ANALYSIS; /*! module's Diags analysis mode */ |
| Bool fxntab; /*! @_nodoc enable function tables */ |
| IGateProvider.Handle gate; /*! module's gate */ |
| Ptr gateParams; /*! gate params for module created gates */ |
| IHeap.Handle instanceHeap; /*! module's instance heap */ |
| String instanceSection; /*! memory section for module's instances*/ |
| ILogger.Handle logger; /*! module's logger */ |
| OutputPolicy outPolicy; /*! destination file for module's code */ |
| CreatePolicy memoryPolicy; /*! module's memory policy */ |
| Bool namedInstance; /*! true => instances have string names */ |
| Bool namedModule; /*! true => module's name is on target */ |
| Bool romPatchTable; /*! @_nodoc */ |
| } |
| |
| /*! |
| * ======== RtaDecoderData ======== |
| * @_nodoc |
| * |
| * loggers |
| * name - Used to identify the logger in GUI |
| * bufferSym - For stop-mode; symbol at which the logger's entry |
| * buffer can be found |
| * bufferLen - For stop-mode; length of the logger's entry buffer in |
| * MAUs |
| */ |
| @XmlDtd metaonly struct RtaDecoderData { |
| String targetName; |
| String binaryParser; |
| String endian; |
| Int bitsPerChar; |
| Int argSize; |
| Int eventSize; |
| String dataTransportClassName; |
| String controlTransportClassName; |
| struct { |
| String name; |
| String type; |
| Any metaArgs; |
| } loggers[ ]; |
| struct { |
| Int id; |
| String logger; |
| String diagsMask; |
| } modMap[string]; |
| struct { |
| Int id; |
| String msg; |
| } evtMap[string]; |
| }; |
| |
| /*! |
| * ======== ViewInfo ======== |
| * @_nodoc |
| * XGconf view descriptor. |
| */ |
| metaonly struct ViewInfo { |
| String viewType; |
| String viewFxn; |
| String fields[]; |
| } |
| |
| internal: |
| |
| typedef Bits32 LogEvent; |
| |
| typedef Void (*LoggerFxn0)(Ptr, LogEvent, ModuleId); |
| typedef Void (*LoggerFxn1)(Ptr, LogEvent, ModuleId, IArg); |
| typedef Void (*LoggerFxn2)(Ptr, LogEvent, ModuleId, IArg, IArg); |
| typedef Void (*LoggerFxn4)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg); |
| typedef Void (*LoggerFxn8)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg, |
| IArg, IArg, IArg, IArg); |
| |
| struct Vec { |
| Int len; |
| Ptr arr; |
| }; |
| |
| /* |
| * ======== Link ======== |
| * Link used to maintain atomic linked lists |
| */ |
| struct Link { |
| Link *next; |
| Link *prev; |
| }; |
| |
| /* |
| * ======== InstHdr ======== |
| * Header for all runtime created instance objects |
| */ |
| struct InstHdr { |
| Link link; |
| } |
| |
| /* |
| * ======== PrmsHdr ======== |
| * Header for all _Params structures |
| */ |
| struct PrmsHdr { |
| SizeT size; /* size of the entire parameter structure */ |
| Ptr self; /* pointer to self; used to check params are init'd */ |
| Ptr modFxns; |
| Ptr instPrms; |
| } |
| |
| /* |
| * ======== Base ======== |
| * Header for all module vtables |
| */ |
| struct Base { |
| //490928 const Base *base; /* points to inherited interface base */ |
| Base *base; /* points to inherited interface base */ |
| } |
| |
| /* |
| * ======== SysFxns ======== |
| * Deprecated. Use SysFxns2 instead |
| */ |
| struct SysFxns { |
| Ptr (*__create)(Ptr, SizeT, Ptr, const Ptr, SizeT, Error.Block*); |
| Void (*__delete)(Ptr); |
| Label *(*__label)(Ptr, Label *); |
| ModuleId __mid; |
| } |
| |
| /* |
| * ======== SysFxns2 ======== |
| * System data embedded in module's vtable |
| */ |
| struct SysFxns2 { |
| |
| /* |
| * ======== __create ======== |
| * Signature of configuration generated module instance constructor |
| * |
| * This function calls Core_createObject(). |
| * |
| * Params: |
| * Ptr - pointer to inststance object |
| * SizeT - size of instance object |
| * CPtr - pointer to struct of required create args |
| * const UChar * - pointer to struct of default create parameters |
| * SizeT - size of default params structure |
| * Error_Block * - caller's error block pointer |
| */ |
| Ptr (*__create)(Ptr, SizeT, Ptr, const UChar *, SizeT, Error.Block *); |
| // 490928 Ptr (*__create)(Ptr, SizeT, CPtr, const UChar *, SizeT, Error.Block *); |
| |
| Void (*__delete)(Ptr); |
| Label *(*__label)(Ptr, Label *); |
| ModuleId __mid; |
| } |
| } |
