module xdc.runtime.Diags

Diagnostics manager

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation
DETAILS
EXAMPLES

Every XDC module has a "diagnostics mask" that allows clients to enable or disable diagnostics on a per module basis both at configuration time and at runtime. The Diags module manages a module's diagnostics mask. [ more ... ]

XDCspec summary sourced in xdc/runtime/Diags.xdc

module Diags { ...

// inherits xdc.runtime.IModule

C synopsis target-domain

#include <xdc/runtime/Diags.h>

module-wide constants & types

#define Diags_ALL// Turn on all diagnostics (Diags_Mask)0xFFFF

#define Diags_ASSERT// Assert checking (Diags_Mask)0x0010

#define Diags_ENTRY// Function entry (Diags_Mask)0x0001

#define Diags_EXIT// Function exit (Diags_Mask)0x0002

#define Diags_INTERNAL// Internal diagnostics (Diags_Mask)0x0008

#define Diags_LIFECYCLE// Object life-cycle (Diags_Mask)0x0004

#define Diags_USER1// User defined diagnostics (Diags_Mask)0x0100

#define Diags_USER2// User defined diagnostics (Diags_Mask)0x0200

#define Diags_USER3// User defined diagnostics (Diags_Mask)0x0400

#define Diags_USER4// User defined diagnostics (Diags_Mask)0x0800

#define Diags_USER5// User defined diagnostics (Diags_Mask)0x1000

#define Diags_USER6// User defined diagnostics (Diags_Mask)0x2000

#define Diags_USER7// User defined diagnostics (Diags_Mask)0x4000

#define Diags_USER8// User defined diagnostics (Diags_Mask)0x8000

typedef Bits16 Diags_Mask// Type used to specify bits in the diags mask;

module-wide functions

macro Bool Diags_query// Query the module's diagnostics mask against the given mask( Diags_Mask mask );

Void Diags_setMask// Set a module's diagnostics mask at runtime( String control );

module-wide built-ins

Types_ModuleId Diags_Module_id// Get this module's unique id( );

Bool Diags_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle Diags_Module_heap// The heap from which this module allocates memory( );

Bool Diags_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 Diags_Module_getMask// Returns the diagnostics mask for this module( );

Void Diags_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

XDCscript usage meta-domain

var Diags = xdc.useModule('xdc.runtime.Diags');

module-wide constants & types

const Diags.ALL// Turn on all diagnostics = 0xFFFF;

const Diags.ASSERT// Assert checking = 0x0010;

const Diags.ENTRY// Function entry = 0x0001;

const Diags.EXIT// Function exit = 0x0002;

const Diags.INTERNAL// Internal diagnostics = 0x0008;

const Diags.LIFECYCLE// Object life-cycle = 0x0004;

const Diags.USER1// User defined diagnostics = 0x0100;

const Diags.USER2// User defined diagnostics = 0x0200;

const Diags.USER3// User defined diagnostics = 0x0400;

const Diags.USER4// User defined diagnostics = 0x0800;

const Diags.USER5// User defined diagnostics = 0x1000;

const Diags.USER6// User defined diagnostics = 0x2000;

const Diags.USER7// User defined diagnostics = 0x4000;

const Diags.USER8// User defined diagnostics = 0x8000;

values of type Diags.Mode// Diagnostics mask bit value used at configuration time

const Diags.ALWAYS_OFF// Bit is permanently cleared;

const Diags.ALWAYS_ON// Bit is permanently set;

const Diags.RUNTIME_OFF// Bit is cleared and modifiable at run-time;

const Diags.RUNTIME_ON// Bit is set and modifiable at run-time;

module-wide config parameters

Diags.common$// Common module configuration parameters = Types.Common$ undefined;

module-wide functions

Diags.setMaskMeta// Set the module's diagnostics mask at config time( Any pattern, Bits16 mask, Diags.Mode mode ) returns Void

XDCspec declarations sourced in xdc/runtime/Diags.xdc

package xdc.runtime;

module Diags {

module-wide constants & types

const Diags.Mask ALL// Turn on all diagnostics = 0xFFFF;

const Diags.Mask ASSERT// Assert checking = 0x0010;

const Diags.Mask ENTRY// Function entry = 0x0001;

const Diags.Mask EXIT// Function exit = 0x0002;

const Diags.Mask INTERNAL// Internal diagnostics = 0x0008;

const Diags.Mask LIFECYCLE// Object life-cycle = 0x0004;

const Diags.Mask USER1// User defined diagnostics = 0x0100;

const Diags.Mask USER2// User defined diagnostics = 0x0200;

const Diags.Mask USER3// User defined diagnostics = 0x0400;

const Diags.Mask USER4// User defined diagnostics = 0x0800;

const Diags.Mask USER5// User defined diagnostics = 0x1000;

const Diags.Mask USER6// User defined diagnostics = 0x2000;

const Diags.Mask USER7// User defined diagnostics = 0x4000;

const Diags.Mask USER8// User defined diagnostics = 0x8000;

enum Mode// Diagnostics mask bit value used at configuration time {

ALWAYS_OFF// Bit is permanently cleared,

ALWAYS_ON// Bit is permanently set,

RUNTIME_OFF// Bit is cleared and modifiable at run-time,

RUNTIME_ON// Bit is set and modifiable at run-time

};

typedef Bits16 Mask// Type used to specify bits in the diags mask;

module-wide config parameters

metaonly config Types.Common$ common$// Common module configuration parameters;

module-wide functions

@Macro Bool query// Query the module's diagnostics mask against the given mask( Diags.Mask mask );

Void setMask// Set a module's diagnostics mask at runtime( String control );

metaonly Void setMaskMeta// Set the module's diagnostics mask at config time( Any pattern, Diags.Mask mask, Diags.Mode mode );

}

DETAILS

You use the Diags module to set and clear bits in a module's diagnostics mask for the purpose of controlling diagnostics within that module. Each bit corresponds to a "type" of diagnostic that can be individually enabled or disabled.

A module's diagnostics mask controls both Assert and Log statements within that module. A module's diagnostics mask may also be used to conditionally execute blocks of code using the Diags_query() runtime function.

A module's diagnostics mask can be set at configuration time and at runtime. The implementation of diagnostics is such that when they are permanently turned off at configuration time (Mode.ALWAYS_OFF), an optimizer can completely eliminate the diagnostics code from the program. Similarly, if diagnostics are permanently turned on at configuration time (Mode.ALWAYS_ON), the optimizer can eliminate all runtime conditional checking and simply invoke the diagnostics code directly. Runtime checking of the diagnostics mask is performed only when the diagnostics are configured to be runtime modifiable (Mode.RUNTIME_OFF or Mode.RUNTIME_ON).

Each bit of the diagnostics mask is controlled by one of the following constants.

  Constant    Meaning
  --------------------------
  ENTRY       Function entry
  EXIT        Function exit
  LIFECYCLE   Object life-cycle
  INTERNAL    Internal diagnostics
  ASSERT      Assert checking
  USER1       User defined diagnostics
  USER2       User defined diagnostics
  USER3       User defined diagnostics
  USER4       User defined diagnostics
  USER5       User defined diagnostics
  USER6       User defined diagnostics
  USER7       User defined diagnostics
  USER8       User defined diagnostics

These constants can be used from either JavaScript configuration scripts or C code and, therefore, have two "names". For example, to reference the ENTRY constant from JavaScript you must use Diags.ENTRY whereas from C you would use Diags_ENTRY.

The ENTRY and EXIT bits control Log statements at the entry and exit points, respectively, to each function within a module. This is useful for tracking the execution flow of your program.

The LIFECYCLE bit controls Log statements at the create/construct and delete/destruct points of each instance object for the module. This is useful for tracking the life-cycle of a module instance object.

The ASSERT bit controls Assert statements in a module. There are two classes of asserts:

Public asserts, which have an Assert_Id and are documented in the module's reference pages. These asserts are on by default and are meant to help developers validate code that invokes a module's functions.
Internal asserts, which have no Assert_Id. These asserts are off by default and are typically used only when developing code. That is, like the standard C assert() mechanism, these asserts are not part of a deployed application.

When a module has the ASSERT bit set (which is set by default) in its diagnostics mask, the module executes all of its public assert statements. To enable internal asserts, you must set both the ASSERT and INTERNAL bits.

The INTERNAL bit is used to classify diagnostic code as being internal. That is to say, this class of diagnostics is undocumented and typically not used by client software.

The USER1-8 bits are available to each module writer to use as he or she wishes.

EXAMPLES

Configuration example: The following XDC configuration statements set a module's diagnostics mask in a configuration script. (In this case, the Task module of the ti.sysbios.knl package is used.) In this example, the ENTRY bit is turned on and the EXIT bit is turned off. Both bits are configured to be runtime modifiable.

  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Task = xdc.useModule('ti.sysbios.knl.Task');

  Task.common$.diags_ENTRY = Diags.RUNTIME_ON;
  Task.common$.diags_EXIT = Diags.RUNTIME_OFF;

Runtime example: The following C code shows how to disable and reenable ENTER diagnostics at runtime for the ti.sysbios.knl.Task module configured in the previous example. The first call to Diag_setMask() enables entry diagnostics ("+E") for just the ti.sysbios.knl.Task module; any call to any Task method in the application causes an "entry" Log event to be generated. The second call disables ("-E") the generation of these events. See Diags_setMask() for a complete description of the strings accepted by this function.

  #include <xdc/runtime/Diags.h>
  :
  Diags_setMask("ti.sysbios.knl.Task+E");
  :
  Diags_setMask("ti.sysbios.knl.Task-E");

Configuration example: The following XDC configuration statements turn on asserts in the entire program.

  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Defaults = xdc.useModule('xdc.runtime.Defaults');

  Defaults.diags_ASSERT = Diags.ALWAYS_ON;

Configuration example: Using the Diags.setMaskMeta() function, the following XDC configuration statements turn on asserts in all of the modules whose name begins with "ti.sysbios." In this case, no change to the application code is necessary to enable these events. It is important to note that, while the configuration step must be re-run and the application must be re-linked, no application sources need to be recompiled.

  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.%", Diags.ASSERT, Diags.ALWAYS_ON);

const Diags.ALL