module 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. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Types.xdc
DETAILS
This module defines basic constants and types used throughout the xdc.runtime package and, in some cases, in every module.
The 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 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.
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.
      var Memory = xdc.useModule('xdc.runtime.Memory");
      Memory.common$.instanceSection = ".fast";
      Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF
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 Diags modules for additional information.
enum Types_CreatePolicy

Instance creation policy

C synopsis target-domain
typedef enum Types_CreatePolicy {
    Types_STATIC_POLICY,
    // static creation only; no runtime create/delete
    Types_CREATE_POLICY,
    // dynamic creation, but no deletion
    Types_DELETE_POLICY
    // dynamic creation and deletion
} Types_CreatePolicy;
typedef Types_DiagsMask
C synopsis target-domain
typedef Bits16 Types_DiagsMask;
typedef Types_Event

ILogger event encoding

C synopsis target-domain
typedef Bits32 Types_Event;
DETAILS
Whereas a 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 Types_ModuleId

Unique module identifier

C synopsis target-domain
typedef Bits16 Types_ModuleId;
DETAILS
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 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.
      #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");
          }
      }
struct Types_FreqHz

Frequency-in-hertz struct

C synopsis target-domain
typedef struct Types_FreqHz {
    Bits32 hi;
    // most significant 32-bits of frequency
    Bits32 lo;
    // least significant 32-bits of frequency
} Types_FreqHz;
struct Types_Label

Instance label struct

C synopsis target-domain
typedef struct Types_Label {
    Ptr handle;
    // instance object address
    Types_ModuleId modId;
    // corresponding module id
    String iname;
    // name supplied during instance creation
    Bool named;
    // true, if iname is available
} Types_Label;
DETAILS
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.
      HeapMin_Handle heap;
      Types_Label label;
      HeapMin_Handle_label(heap, &label);
Unless you explicitly disable it, 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 the an instance's label.
      System_printf("heap instance name: %$L\n", &label);
SEE
struct Types_RegDesc

Registry module descriptor

C synopsis target-domain
typedef struct Types_RegDesc {
    Types_RegDesc *next;
    String modName;
    Types_ModuleId id;
    Types_DiagsMask mask;
} Types_RegDesc;
struct Types_Site

Error site description struct

C synopsis target-domain
typedef struct Types_Site {
    Types_ModuleId mod;
    // module id of this site
    String file;
    // filename of this site
    Int line;
    // line number of this site
} Types_Site;
FIELDS
mod — the module id of the module containing the call site
file — the name of the file containing the call site or NULL; some call sites omit the file name to save data space.
line — the line number within the file named
DETAILS
This structure describes the location of the line that raised an error.
struct Types_Timestamp64

64-bit timestamp struct

C synopsis target-domain
typedef struct Types_Timestamp64 {
    Bits32 hi;
    // most significant 32-bits of timestamp
    Bits32 lo;
    // least significant 32-bits of timestamp
} Types_Timestamp64;
DETAILS
Some platforms only support 32-bit timestamps. In this case, the most significant 32-bits are always set to 0.
Types_getEventId()  // module-wide

Get event ID of the specified event

C synopsis target-domain
macro Types_RopeId Types_getEventId(Types_Event evt);
ARGUMENTS
evt — an event created via makeEvent
DETAILS
This method is used to get an ID that can be compared to other "known" IDs. For example, after a Types_Event is generated, the following code determines if the event corresponds to a Log.L_create event:
      Bool isCreateEvent(Types_Event evt) {
          return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
      }
RETURNS
This function returns the event ID of a specified event.
Types_getModuleId()  // module-wide

Get the module ID for the specified event

C synopsis target-domain
macro Types_ModuleId Types_getModuleId(Types_Event evt);
ARGUMENTS
evt — an event created via makeEvent
RETURNS
This function returns the module ID of a specified event.
Types_makeEvent()  // module-wide

Make an Event from an Event ID and a module ID

C synopsis target-domain
macro Types_Event Types_makeEvent(Types_RopeId id, Types_ModuleId callSite);
ARGUMENTS
id — ID of the event itself
callSite — the module from which this event originated
RETURNS
This function returns an event.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Types_Module_id();
// Get this module's unique id
 
Bool Types_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Types_Module_heap();
// The heap from which this module allocates memory
 
Bool Types_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Types_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Types_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in xdc/runtime/Types.xdc
var Types = xdc.useModule('xdc.runtime.Types');
module-wide constants & types
        obj.diags_STATUS = Diags.Mode  ...
        obj.fxntab = Bool  ...
        obj.gate// module's gate = IGateProvider.Handle  ...
        obj.gateParams// gate params for module created gates = Ptr  ...
        obj.instanceSection// memory section for module's instances = String  ...
        obj.logger// module's logger = ILogger.Handle  ...
        obj.namedInstance// true => instances have string names = Bool  ...
        obj.namedModule// true => module's name is on target = Bool  ...
        obj.romPatchTable = Bool  ...
        obj.hi// most significant 32-bits of frequency = Bits32  ...
        obj.lo// least significant 32-bits of frequency = Bits32  ...
    var obj = new Types.Label// Instance label struct;
        obj.handle// instance object address = Ptr  ...
        obj.modId// corresponding module id = Bits16  ...
        obj.iname// name supplied during instance creation = String  ...
        obj.named// true, if iname is available = Bool  ...
        obj.next = Types.RegDesc*  ...
        obj.modName = String  ...
        obj.id = Bits16  ...
        obj.mask = Bits16  ...
        obj.mod// module id of this site = Bits16  ...
        obj.file// filename of this site = String  ...
        obj.line// line number of this site = Int  ...
        obj.hi// most significant 32-bits of timestamp = Bits32  ...
        obj.lo// least significant 32-bits of timestamp = Bits32  ...
module-wide config parameters
 
enum Types.CreatePolicy

Instance creation policy

XDCscript usage meta-domain
values of type Types.CreatePolicy
    const Types.STATIC_POLICY;
    // static creation only; no runtime create/delete
    const Types.CREATE_POLICY;
    // dynamic creation, but no deletion
    const Types.DELETE_POLICY;
    // dynamic creation and deletion
C SYNOPSIS
metaonly struct Types.Common$

Common module config struct

XDCscript usage meta-domain
var obj = new Types.Common$;
 
    obj.diags_ASSERT = Diags.Mode  ...
    // module's Diags assert mode
    obj.diags_ENTRY = Diags.Mode  ...
    // module's function entry Diags mode
    obj.diags_EXIT = Diags.Mode  ...
    // module's function exit Diags mode
    obj.diags_INTERNAL = Diags.Mode  ...
    // module's internal assert mode
    obj.diags_LIFECYCLE = Diags.Mode  ...
    // module's instance lifecycle mode
    obj.diags_STATUS = Diags.Mode  ...
    obj.diags_USER1 = Diags.Mode  ...
    // module's user1 Diags mode
    obj.diags_USER2 = Diags.Mode  ...
    // module's user2 Diags mode
    obj.diags_USER3 = Diags.Mode  ...
    // module's user3 Diags mode
    obj.diags_USER4 = Diags.Mode  ...
    // module's user4 Diags mode
    obj.diags_USER5 = Diags.Mode  ...
    // module's user5 Diags mode
    obj.diags_USER6 = Diags.Mode  ...
    // module's user6 Diags mode
    obj.diags_USER7 = Diags.Mode  ...
    // module's user7 Diags mode
    obj.diags_INFO = Diags.Mode  ...
    // module's informational event mode
    obj.diags_USER8 = Diags.Mode  ...
    // module's user8 Diags mode
    obj.diags_ANALYSIS = Diags.Mode  ...
    // module's Diags analysis mode
    obj.fxntab = Bool  ...
    obj.gate = IGateProvider.Handle  ...
    // module's gate
    obj.gateParams = Ptr  ...
    // gate params for module created gates
    obj.instanceHeap = IHeap.Handle  ...
    // module's instance heap
    obj.instanceSection = String  ...
    // memory section for module's instances
    obj.logger = ILogger.Handle  ...
    // module's logger
    obj.memoryPolicy = Types.CreatePolicy  ...
    // module's memory policy
    obj.namedInstance = Bool  ...
    // true => instances have string names
    obj.namedModule = Bool  ...
    // true => module's name is on target
    obj.romPatchTable = Bool  ...
FIELDS
diags_ASSERT — The Diags.ASSERT bit of a module's diagnostics mask.
diags_ENTRY — The Diags.ENTRY category of a module's diagnostics mask.
diags_EXIT — The Diags.EXIT category of a module's diagnostics mask.
diags_INTERNAL — The Diags.INTERNAL bit of a module's diagnostics mask.
diags_LIFECYCLE — The Diags.LIFECYCLE category of a module's diagnostics mask.
diags_STATUS — The Diags.STATUS category of a module's diagnostics mask.
diags_USER1 — The Diags.USER1 category of a module's diagnostics mask.
diags_USER2 — The Diags.USER2 category of a module's diagnostics mask.
diags_USER3 — The Diags.USER3 category of a module's diagnostics mask.
diags_USER4 — The Diags.USER4 category of a module's diagnostics mask.
diags_USER5 — The Diags.USER5 category of a module's diagnostics mask.
diags_USER6 — The Diags.USER6 category of a module's diagnostics mask.
diags_USER7 — The Diags.USER7 category of a module's diagnostics mask. The bit for this category has been repurposed for the Diags.INFO category, so the use of USER7 has been deprecated.
diags_INFO — The Diags.INFO category of a module's diagnostics mask.
diags_USER8 — The Diags.USER8 category of a module's diagnostics mask. The bit for this category has been repurposed for the Diags.ANALYSIS category, so the use of USER8 has been deprecated.
diags_ANALYSIS — The Diags.ANALYSIS category of a module's diagnostics mask.
fxntab — This configurtation 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 Memory module calls methods defined by the 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.
gate — A handle to the module-level IGateProvider instance to be used when this module calls functions from Gate
gateParams — Gate parameters used by this module to create the gates used when this module calls Gate_allocInstance
instanceHeap — Identifies the heap from which this module should allocate memory.
instanceSection — Identifies the section in which instances created by this module should be placed.
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 ILogger for details on the logger interface. See LoggerBuf and LoggerSys for two examples of logger instances provided by the xdc.runtime package.
memoryPolicy — Specifies whether this module should allow static object creation only (STATIC_POLICY), dynamic object creation but not deletion (CREATE_POLICY), or both dynamic object creation and deletion (DELETE_POLICY).
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.
namedModule — If set to true, this module's string name is retained on the target so that it can be displayed as part of Log and 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 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.
DETAILS
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 Defaults.
SEE
struct Types.FreqHz

Frequency-in-hertz struct

XDCscript usage meta-domain
var obj = new Types.FreqHz;
 
    obj.hi = Bits32  ...
    // most significant 32-bits of frequency
    obj.lo = Bits32  ...
    // least significant 32-bits of frequency
C SYNOPSIS
struct Types.Label

Instance label struct

XDCscript usage meta-domain
var obj = new Types.Label;
 
    obj.handle = Ptr  ...
    // instance object address
    obj.modId = Bits16  ...
    // corresponding module id
    obj.iname = String  ...
    // name supplied during instance creation
    obj.named = Bool  ...
    // true, if iname is available
DETAILS
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.
      HeapMin_Handle heap;
      Types_Label label;
      HeapMin_Handle_label(heap, &label);
Unless you explicitly disable it, 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 the an instance's label.
      System_printf("heap instance name: %$L\n", &label);
SEE
C SYNOPSIS
struct Types.RegDesc

Registry module descriptor

XDCscript usage meta-domain
var obj = new Types.RegDesc;
 
    obj.next = Types.RegDesc*  ...
    obj.modName = String  ...
    obj.id = Bits16  ...
    obj.mask = Bits16  ...
C SYNOPSIS
struct Types.Site

Error site description struct

XDCscript usage meta-domain
var obj = new Types.Site;
 
    obj.mod = Bits16  ...
    // module id of this site
    obj.file = String  ...
    // filename of this site
    obj.line = Int  ...
    // line number of this site
FIELDS
mod — the module id of the module containing the call site
file — the name of the file containing the call site or NULL; some call sites omit the file name to save data space.
line — the line number within the file named
DETAILS
This structure describes the location of the line that raised an error.
C SYNOPSIS
struct Types.Timestamp64

64-bit timestamp struct

XDCscript usage meta-domain
var obj = new Types.Timestamp64;
 
    obj.hi = Bits32  ...
    // most significant 32-bits of timestamp
    obj.lo = Bits32  ...
    // least significant 32-bits of timestamp
DETAILS
Some platforms only support 32-bit timestamps. In this case, the most significant 32-bits are always set to 0.
C SYNOPSIS
metaonly config Types.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
Types.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Thu, 03 Feb 2011 19:01:55 GMT