module xdc.runtime.Diags

Diagnostics manager

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 ... ]
C synopsis target-domain sourced in xdc/runtime/Diags.xdc
#include <xdc/runtime/Diags.h>
Functions
macro Bool 
macro Bool 
Void 
Functions common to all target modules
Defines
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
#define
Typedefs
typedef enum
typedef Types_DiagsMask 
 
DETAILS
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.
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 "category" 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
  STATUS      Warning or Error events
  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
  INFO        Informational event
  USER8       User defined diagnostics
  ANALYSIS    Analysis event
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 categories are for 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 category is for log events 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.
ASSERT and INTERNAL are unique in that they are not related to logging, but instead control the Assert statements in a module. These categories control the 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 enabled the ASSERT category (which is enabled by default) in its diagnostics mask, the module executes all of its public assert statements. To enable internal asserts, you must enable both the ASSERT and INTERNAL categories.
The ASSERT and INTERNAL categories are not intended for use as log event categories. If an event is defined with either of these categories, you will receive a validation error during configuration.
The STATUS category is used for error and warning type events. The four event levels within the STATUS category have defined meanings, see EMERGENCY
The INFO category is used for generic informational events. Any event which does not belong to a more specific category of events may simply be an INFO event.
The ANALYSIS category is used for events related to benchmarks and performance analysis.
The USER1-6 categories are available to each module writer to use as he or she wishes.
The USER7 and USER8 categories are still defined, but their bits have been repurposed for the INFO and ANALYSIS categories, respectively, so the use of USER7 and USER8 has been deprecated.
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

Mask of all diagnostics categories, including both logging and asserts

C synopsis target-domain
#define Diags_ALL (Diags_Mask)0xFF9F
 
 
const Diags_ALL_LOGGING

Mask of all logging diagnostic categories (does not include asserts)

C synopsis target-domain
#define Diags_ALL_LOGGING (Diags_Mask)Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL)
 
 
const Diags_ANALYSIS

Analysis (e.g., benchmark) event

C synopsis target-domain
#define Diags_ANALYSIS (Diags_Mask)Diags.USER8
 
 
const Diags_ASSERT

Assert checking

C synopsis target-domain
#define Diags_ASSERT (Diags_Mask)0x0010
 
 
const Diags_CRITICAL

A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'

C synopsis target-domain
#define Diags_CRITICAL (Diags_EventLevel)Diags.LEVEL2
 
DETAILS
See 'EMERGENCY' for details.
 
const Diags_EMERGENCY

A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'

C synopsis target-domain
#define Diags_EMERGENCY (Diags_EventLevel)Diags.LEVEL1
 
DETAILS
For STATUS events only, the meaning of the four EventLevels has been defined. These constants are simply aliases for the four event levels.
The highest three levels are different severities of an error event. For example, an EMERGENCY event may represent an unrecoverable system failure, a CRITICAL event may require notification of an operator, and an ERROR may be a recoverable error.
The lowest level is reserved for warnings, such as when a resource becomes dangerously low.
 
const Diags_ENTRY

Function entry

C synopsis target-domain
#define Diags_ENTRY (Diags_Mask)0x0001
 
 
const Diags_ERROR

A 'LEVEL3' 'STATUS' event is defined as 'ERROR'

C synopsis target-domain
#define Diags_ERROR (Diags_EventLevel)Diags.LEVEL3
 
DETAILS
See 'EMERGENCY' for details.
 
const Diags_EXIT

Function exit

C synopsis target-domain
#define Diags_EXIT (Diags_Mask)0x0002
 
 
const Diags_INFO

Informational event

C synopsis target-domain
#define Diags_INFO (Diags_Mask)Diags.USER7
 
 
const Diags_INTERNAL

Internal diagnostics

C synopsis target-domain
#define Diags_INTERNAL (Diags_Mask)0x0008
 
 
const Diags_LIFECYCLE

Object life-cycle

C synopsis target-domain
#define Diags_LIFECYCLE (Diags_Mask)0x0004
 
 
const Diags_STATUS

Warning or error event

C synopsis target-domain
#define Diags_STATUS (Diags_Mask)0x0080
 
 
const Diags_USER1

User defined diagnostics

C synopsis target-domain
#define Diags_USER1 (Diags_Mask)0x0100
 
 
const Diags_USER2

User defined diagnostics

C synopsis target-domain
#define Diags_USER2 (Diags_Mask)0x0200
 
 
const Diags_USER3

User defined diagnostics

C synopsis target-domain
#define Diags_USER3 (Diags_Mask)0x0400
 
 
const Diags_USER4

User defined diagnostics

C synopsis target-domain
#define Diags_USER4 (Diags_Mask)0x0800
 
 
const Diags_USER5

User defined diagnostics

C synopsis target-domain
#define Diags_USER5 (Diags_Mask)0x1000
 
 
const Diags_USER6

User defined diagnostics

C synopsis target-domain
#define Diags_USER6 (Diags_Mask)0x2000
 
 
const Diags_USER7

Alias for informational event

C synopsis target-domain
#define Diags_USER7 (Diags_Mask)0x4000
 
 
const Diags_USER8

Alias for analysis event

C synopsis target-domain
#define Diags_USER8 (Diags_Mask)0x8000
 
 
const Diags_WARNING

A 'LEVEL4' 'STATUS' event is defined as 'WARNING'

C synopsis target-domain
#define Diags_WARNING (Diags_EventLevel)Diags.LEVEL4
 
DETAILS
See 'EMERGENCY' for details.
 
enum Diags_EventLevel

The level of an event

C synopsis target-domain
typedef enum Diags_EventLevel {
    Diags_LEVEL1,
    Diags_LEVEL2,
    Diags_LEVEL3,
    Diags_LEVEL4
} Diags_EventLevel;
 
DETAILS
The diagnostics bits each represent a different category of event, for example: an analysis event, a lifecycle event, or an informational event. Within each of these categories, events may have one of four levels to enable filtering based on the level of information desired.
The meaning of these levels and the distinction between them is left open to the user. Depending on the meaning given, different terminology may be used to describe them--they may be levels of detail, priority, severity, etc. The heirarchy of the events is set such that LEVEL1 is the highest priority and LEVEL4 is the lowest. That is, enabling LEVEL4 events implies that events of all four levels will be logged.
LEVEL1
Least detail, highest priority, most severe, etc.
LEVEL2
LEVEL3
LEVEL4
Most detail, lowest priority, least severe, etc.
The STATUS bit is the only category where the levels are given explicit meaning to ensure consistency. Within the STATUS category, the meaning of the levels is defined by the constants EMERGENCY, CRITICAL, ERROR, and WARNING.
Events which don't define a level will receive LEVEL1 by default.
 
typedef Diags_Mask

Type used to specify bits in the diags mask

C synopsis target-domain
typedef Types_DiagsMask Diags_Mask;
 
 
Diags_compareLevels()  // module-wide

Returns false if levelA is lower than levelB

C synopsis target-domain
macro Bool Diags_compareLevels(Diags_EventLevel levelA, Diags_EventLevel levelB);
 
DETAILS
This API is intended to be used to determine if a given event passes a filtering threshold and should be logged. Conceptually (though not necessarily in implementation), this API is equivalent to the expression (levelA < levelB). The values of the EventLevels have internal meaning, so a direct comparison of two levels should not done; this API must be used to correctly compare them.
LEVEL1 is the highest level and LEVEL4 is the lowest. So LEVEL4 is less than LEVEL3, which is less than LEVEL2, which is less than LEVEL1.
 
Diags_getLevel()  // module-wide

Get the event level set in the given mask

C synopsis target-domain
macro Diags_EventLevel Diags_getLevel(Diags_Mask mask);
 
ARGUMENTS
mask — mask of diagnostics bits to read filter level from.
DETAILS
See 'EventLevel' for a description of event levels.
 
Diags_query()  // module-wide

Query the module's diagnostics mask against the given mask

C synopsis target-domain
macro Bool Diags_query(Diags_Mask mask);
 
ARGUMENTS
mask — mask of diagnostics bits to test
This given mask is constructed by OR'ing together the desired bits of the diagnostics mask using the constants listed in the Mask Summary above. The module's diagnostics mask will be logically AND'ed with the given mask, and return true if the result is non-zero and false otherwise.
      if (Diags_query(Diags_USER1 | Diags_USER4)) {
          :
      }
DETAILS
Use this query function to test the state of a module's diagnostics mask at runtime. This function will perform a logical AND operation on the module's diagnostics mask and the given mask. If any bits survive the operation, the function returns true.
  result = moduleMask & givenMask ? true : false;
This query function has a compile-time binding to the module's diagnostics mask. If the query function is part of the C code implementation of a module, then it will use that module's diagnostics mask. Otherwise, it will use the diagnostics mask of the xdc.runtime.Main module.
The implementation of the diagnostics mask and the query function is such that an optimizer can take advantage of dead code elimination and/or constant folding to eliminate or reduce code size. For example, if the query function is used in a conditional test, and the given mask contains only bits which have been configured to be permanently off, then the code for the entire conditional statement can be removed at link time. If the bits in the given mask have been configured to be permanently on, then the conditional code can be removed leaving the body of the conditional as direct in-line code.
EXAMPLES
In the following example, the USER1 bit of the module's diagnostics mask has been configured to be permanently off, thus the entire conditional code block can be removed at link time. Note, the C code below is part of the module itself.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var ModA = xdc.useModule('my.package.ModuleA');
  ModA.common$.diags_USER1 = Diags.ALWAYS_OFF;
C Code, ModA.c
  if (Diags_query(Diags_USER1)) {         // this code removed
      ...additional code here...          // this code removed
  }                                       // this code removed

In the following example, the USER1 bit of the module's diagnostics mask has been configured to be permanently on, thus the conditional code can be removed leaving the code contained within the conditional statement. Note, the C code below is part of the module itself.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var ModA = xdc.useModule('my.package.ModuleA');
  ModA.common$.diags_USER1 = Diags.ALWAYS_ON;
C Code, ModA.c
  if (Diags_query(Diags_USER1) {          // this code removed
      ...additional code here...          // this code remains
  }                                       // this code removed
 
Diags_setMask()  // module-wide

Set a module's diagnostics mask at runtime

C synopsis target-domain
Void Diags_setMask(CString control);
 
ARGUMENTS
control — diagnostic mask control string
This control string defines one or more actions where each action consists of a module name, an operator character, and a list of bit specifiers. Use the % character as a wildcard to turn the module name into a prefix matching pattern for a set of modules. Multiple actions are separated with the ; character.
The control string has the following format:
  <module[%]><op><bits>[;<module[%]><op><bits>]
Specify individual module names explicitly (e.g. ti.sysbios.knl.Task), or match multiple modules using a prefix matching pattern specified with the % character (e.g. ti.sysbios.knl.%).
The operator is specified with a single character from the following table.
  Operator    Description
  --------------------------------------------------
  +           Set only the specified bits (other bits preserved)
  -           Clear only the specified bits (other bits preserved)
  =           Assign the entire mask to the given value where the
              specified bits are set and all other bits are cleared
The bits are specified with a list of characters from the following table. Refer to the Mask Summary for a list of each bit of the diagnostics mask.
  Control     Diagnostics
  Character   Constant        Description
  --------------------------------------------------
  E           ENTRY           Function entry
  X           EXIT            Function exit
  L           LIFECYCLE       Object life-cycle
  I           INTERNAL        Internal diagnostics
  A           ASSERT          Assert checking
  Z           ANALYSIS        Analysis event
  F           INFO            Informational event
  S           STATUS          Status (error, warning) event
  1           USER1           User defined diagnostics
  2           USER2           User defined diagnostics
  3           USER3           User defined diagnostics
  4           USER4           User defined diagnostics
  5           USER5           User defined diagnostics
  6           USER6           User defined diagnostics
  7           USER7           User defined diagnostics
  8           USER8           User defined diagnostics
DETAILS
Use the given control string to set or clear bits in a module's diagnostics mask. The control string defines one or more actions where each action modifies the diagnostics mask in one or more modules. Each action can either set, clear, or assign a module's diagnostics mask. To both set and clear bits in the same diagnostics mask requires two actions, or you can assign the entire mask explicitly in one action. Each action can specify a given module or a set of modules using name prefix matching.
WARNING
Each bit of a module's diagnostics mask that is to be modified at runtime, must be configured to be runtime modifiable in the program's configuration script. Use either RUNTIME_OFF or RUNTIME_ON as the configuration value for the desired bit in the diagnostics mask. Also, the following configuration parameters must have the values indicated (which are their default values):
Note: any error that occurs during the parsing of the control string causes Diags_setMask() to return without processing the remainder of the control string.
EXAMPLES
The following example demonstrates how to set a module's diagnostics mask (the Task module in this case) at runtime. In this example, the USER1 bit is turned on. Note that the module's USER1 diagnostics bit must be configured to be runtime modifiable. In this instance, the bit is initialized to off.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Task = xdc.useModule('ti.sysbios.knl.Task');
  Task.common$.diags_USER1 = Diags.RUNTIME_OFF;
C Code
  Diags_setMask("ti.sysbios.knl.Task+1");

The following example demonstrates the use of the % wildcard character to set the USER1 bit at runtime for all modules in the ti.sysbios.knl package. The meta-only Diags.setMaskMeta function is used to configure the USER1 bit to be runtime modifiable. The setMask function is used to actually set the USER1 bit at runtime in all the ti.sysbios.knl modules. Note the use of the % character in both functions to match all the module names within the given package.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.knl.%", Diags.USER1, Diags.RUNTIME_OFF);
C Code
  Diags_setMask("ti.sysbios.knl.%+1");

In the following example, the ENTRY, EXIT and LIFECYCLE trace is enabled for all modules in the ti.sysbios.knl package but is initially off; i.e., no events will occur until explicitly turned on at runtime.
At runtime the call to Diags_setMask turns on ENTRY and EXIT trace and turns off LIFECYCLE trace for all modules in the application for which trace has been enabled during configuration. In this case, the only modules that can generate events are those in the ti.sysbios.knl package.
Configuration Script
  var Diags = xdc.useModule('xdc.runtime.Diags');
  Diags.setMaskMeta("ti.sysbios.knl.%",
      Diags.ENTRY | Diags.EXIT | Diags.LIFECYCLE, Diags.RUNTIME_OFF);
C Code
  Diags_setMask("%+EX;%-L");
Module-Wide Built-Ins

C synopsis target-domain
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(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in xdc/runtime/Diags.xdc
var Diags = xdc.useModule('xdc.runtime.Diags');
module-wide constants & types
    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.STATUS// Warning or error event = 0x0080;
    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.USER8// Alias for analysis event = 0x8000;
 
        const Diags.LEVEL1;
        const Diags.LEVEL2;
        const Diags.LEVEL3;
        const Diags.LEVEL4;
 
module-wide config parameters
module-wide functions
    Diags.setMaskMeta// Set the module's diagnostics mask at config time(Any pattern, Bits16 mask, Diags.Mode mode) returns Void
 
 
const Diags.ALL

Mask of all diagnostics categories, including both logging and asserts

Configuration settings
const Diags.ALL = 0xFF9F;
 
C SYNOPSIS
 
const Diags.ALL_LOGGING

Mask of all logging diagnostic categories (does not include asserts)

Configuration settings
const Diags.ALL_LOGGING = Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL);
 
C SYNOPSIS
 
const Diags.ANALYSIS

Analysis (e.g., benchmark) event

Configuration settings
const Diags.ANALYSIS = Diags.USER8;
 
C SYNOPSIS
 
const Diags.ASSERT

Assert checking

Configuration settings
const Diags.ASSERT = 0x0010;
 
C SYNOPSIS
 
const Diags.CRITICAL

A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'

Configuration settings
const Diags.CRITICAL = Diags.LEVEL2;
 
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
 
const Diags.EMERGENCY

A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'

Configuration settings
const Diags.EMERGENCY = Diags.LEVEL1;
 
DETAILS
For STATUS events only, the meaning of the four EventLevels has been defined. These constants are simply aliases for the four event levels.
The highest three levels are different severities of an error event. For example, an EMERGENCY event may represent an unrecoverable system failure, a CRITICAL event may require notification of an operator, and an ERROR may be a recoverable error.
The lowest level is reserved for warnings, such as when a resource becomes dangerously low.
C SYNOPSIS
 
const Diags.ENTRY

Function entry

Configuration settings
const Diags.ENTRY = 0x0001;
 
C SYNOPSIS
 
const Diags.ERROR

A 'LEVEL3' 'STATUS' event is defined as 'ERROR'

Configuration settings
const Diags.ERROR = Diags.LEVEL3;
 
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
 
const Diags.EXIT

Function exit

Configuration settings
const Diags.EXIT = 0x0002;
 
C SYNOPSIS
 
const Diags.INFO

Informational event

Configuration settings
const Diags.INFO = Diags.USER7;
 
C SYNOPSIS
 
const Diags.INTERNAL

Internal diagnostics

Configuration settings
const Diags.INTERNAL = 0x0008;
 
C SYNOPSIS
 
const Diags.LIFECYCLE

Object life-cycle

Configuration settings
const Diags.LIFECYCLE = 0x0004;
 
C SYNOPSIS
 
const Diags.STATUS

Warning or error event

Configuration settings
const Diags.STATUS = 0x0080;
 
C SYNOPSIS
 
const Diags.USER1

User defined diagnostics

Configuration settings
const Diags.USER1 = 0x0100;
 
C SYNOPSIS
 
const Diags.USER2

User defined diagnostics

Configuration settings
const Diags.USER2 = 0x0200;
 
C SYNOPSIS
 
const Diags.USER3

User defined diagnostics

Configuration settings
const Diags.USER3 = 0x0400;
 
C SYNOPSIS
 
const Diags.USER4

User defined diagnostics

Configuration settings
const Diags.USER4 = 0x0800;
 
C SYNOPSIS
 
const Diags.USER5

User defined diagnostics

Configuration settings
const Diags.USER5 = 0x1000;
 
C SYNOPSIS
 
const Diags.USER6

User defined diagnostics

Configuration settings
const Diags.USER6 = 0x2000;
 
C SYNOPSIS
 
const Diags.USER7

Alias for informational event

Configuration settings
const Diags.USER7 = 0x4000;
 
C SYNOPSIS
 
const Diags.USER8

Alias for analysis event

Configuration settings
const Diags.USER8 = 0x8000;
 
C SYNOPSIS
 
const Diags.WARNING

A 'LEVEL4' 'STATUS' event is defined as 'WARNING'

Configuration settings
const Diags.WARNING = Diags.LEVEL4;
 
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
 
enum Diags.EventLevel

The level of an event

Configuration settings
values of type Diags.EventLevel
    const Diags.LEVEL1;
    const Diags.LEVEL2;
    const Diags.LEVEL3;
    const Diags.LEVEL4;
 
DETAILS
The diagnostics bits each represent a different category of event, for example: an analysis event, a lifecycle event, or an informational event. Within each of these categories, events may have one of four levels to enable filtering based on the level of information desired.
The meaning of these levels and the distinction between them is left open to the user. Depending on the meaning given, different terminology may be used to describe them--they may be levels of detail, priority, severity, etc. The heirarchy of the events is set such that LEVEL1 is the highest priority and LEVEL4 is the lowest. That is, enabling LEVEL4 events implies that events of all four levels will be logged.
LEVEL1
Least detail, highest priority, most severe, etc.
LEVEL2
LEVEL3
LEVEL4
Most detail, lowest priority, least severe, etc.
The STATUS bit is the only category where the levels are given explicit meaning to ensure consistency. Within the STATUS category, the meaning of the levels is defined by the constants EMERGENCY, CRITICAL, ERROR, and WARNING.
Events which don't define a level will receive LEVEL1 by default.
C SYNOPSIS
 
metaonly enum Diags.Mode

Diagnostics mask bit value used at configuration time

Configuration settings
values of type Diags.Mode
    const Diags.ALWAYS_OFF;
    // permanently disabled
    const Diags.ALWAYS_ON;
    // permanently enabled
    const Diags.RUNTIME_OFF;
    // run-time settable, initially disabled
    const Diags.RUNTIME_ON;
    // run-time settable, initially enabled
 
DETAILS
At run-time a module's diagnostics mask is an ordinary data word with each bit value being 0 or 1 indicating whether or not the corresponding diagnostic is disabled or enabled. At configuration time, however, each bit of the diagnostics mask can be placed in one of several Modes; these modes determine its initial runtime value and whether or not the bit is modifiable at runtime.
When setting a module's diagnostics mask at configuration time, use one of the enumerated values of type Mode. These values will either set or clear a bit in the mask and also define if the bit can be changed at run-time. For example, using ALWAYS_OFF as the bit value means that bit cannot be set at run-time. This fact can be used by an optimizer to perform constant-folding and dead-code elimination.
 
metaonly config Diags.common$  // module-wide

Common module configuration parameters

Configuration settings
Diags.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.
 
metaonly Diags.setMaskMeta()  // module-wide

Set the module's diagnostics mask at config time

Configuration settings
Diags.setMaskMeta(Any pattern, Bits16 mask, Diags.Mode mode) returns Void
 
ARGUMENTS
pattern — module prefix or regular expression
The pattern is used to match a module's name. If pattern is specified as a string, then name prefix matching is used. The pattern may also be a regular expression. Only the masks of the modules matching pattern are set.
mask — diagnostic fields to modify
The mask is used to determine which fields in the diags mask are modified. Each field specified in the mask is set to the given mode value.
mode — mode to assign to the specified mask fields
generated on Tue, 14 Feb 2017 20:01:27 GMT