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 ... ]
XDCspec summary sourced in xdc/runtime/Types.xdc
module Types {  ...
// inherits xdc.runtime.IModule
C synopsis target-domain
#include <xdc/runtime/Types.h>
module-wide constants & types
    } Types_CreatePolicy;
 
    typedef Bits32 Types_Event// ILogger event encoding;
 
    } Types_FreqHz;
 
    typedef struct Types_Label// Instance label struct {
        Ptr handle// instance object address;
        Bool named// true, if iname is available;
    } Types_Label;
 
        String file// filename of this site;
        Int line// line number of this site;
    } Types_Site;
 
    } Types_Timestamp64;
module-wide functions
module-wide built-ins
 
XDCscript usage meta-domain
var Types = xdc.useModule('xdc.runtime.Types');
module-wide constants & types
 
        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.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
 
XDCspec declarations sourced in xdc/runtime/Types.xdc
package xdc.runtime;
 
module Types {
module-wide constants & types
    };
 
    typedef Bits32 Event// ILogger event encoding;
    typedef Bits16 ModuleId// Unique module identifier;
 
    metaonly struct Common$// Common module config struct {
        Bool fxntab;
        Bool romPatchTable;
    };
 
    };
 
        Ptr handle// instance object address;
        Bool named// true, if iname is available;
    };
 
        String file// filename of this site;
        Int line// line number of this site;
    };
 
    };
module-wide config parameters
module-wide functions
}
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

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 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.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");
          }
      }
 
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_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_USER8 = Diags.Mode  ...
    // module's user8 Diags 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 bit of a module's diagnostics mask.
diags_EXIT — The Diags.EXIT bit of a module's diagnostics mask.
diags_INTERNAL — The Diags.INTERNAL bit of a module's diagnostics mask.
diags_LIFECYCLE — The Diags.LIFECYCLE bit of a module's diagnostics mask.
diags_USER1 — The Diags.USER1 bit of a module's diagnostics mask.
diags_USER2 — The Diags.USER2 bit of a module's diagnostics mask.
diags_USER3 — The Diags.USER3 bit of a module's diagnostics mask.
diags_USER4 — The Diags.USER4 bit of a module's diagnostics mask.
diags_USER5 — The Diags.USER5 bit of a module's diagnostics mask.
diags_USER6 — The Diags.USER6 bit of a module's diagnostics mask.
diags_USER7 — The Diags.USER7 bit of a module's diagnostics mask.
diags_USER8 — The Diags.USER8 bit 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 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

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
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.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
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

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
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.
 
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.
 
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
generated on Tue, 01 Sep 2009 00:36:17 GMT