| 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 Diags_EventLevel | |
macro Bool | |
Void | |
Functions common to all target modules | |
|
Diags_Module_getMask// Returns the diagnostics mask for this module,
Diags_Module_hasMask// Test whether this module has a diagnostics mask,
Diags_Module_heap// The heap from which this module allocates memory,
Diags_Module_id// Get this module's unique id,
Diags_Module_setMask// Set the diagnostics mask for this module,
Diags_Module_startupDone// Test if this module has completed startup
|
Defines |
#define | |
#define | |
#define | |
#define | |
#define | |
#define | |
#define | |
#define | |
#define | Diags_EXIT// Function exit (Diags_Mask)0x0002 |
#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 |
| const Diags_ALL_LOGGING |
|
Mask of all logging diagnostic categories (does not include asserts)
| C synopsis | target-domain |
| const Diags_ANALYSIS |
|
Analysis (e.g., benchmark) event
| C synopsis | target-domain |
| const Diags_ASSERT |
|
Assert checking
| C synopsis | target-domain |
| const Diags_CRITICAL |
|
A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'
| C synopsis | target-domain |
DETAILS
See 'EMERGENCY' for details.
| const Diags_EMERGENCY |
|
A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'
| C synopsis | target-domain |
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 |
| const Diags_ERROR |
|
A 'LEVEL3' 'STATUS' event is defined as 'ERROR'
| C synopsis | target-domain |
DETAILS
See 'EMERGENCY' for details.
| const Diags_EXIT |
|
Function exit
| C synopsis | target-domain |
| const Diags_INFO |
|
Informational event
| C synopsis | target-domain |
| const Diags_INTERNAL |
|
Internal diagnostics
| C synopsis | target-domain |
| const Diags_LIFECYCLE |
|
Object life-cycle
| C synopsis | target-domain |
| const Diags_STATUS |
|
Warning or error event
| C synopsis | target-domain |
| const Diags_USER1 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER2 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER3 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER4 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER5 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER6 |
|
User defined diagnostics
| C synopsis | target-domain |
| const Diags_USER7 |
|
Alias for informational event
| C synopsis | target-domain |
| const Diags_USER8 |
|
Alias for analysis event
| C synopsis | target-domain |
| const Diags_WARNING |
|
A 'LEVEL4' 'STATUS' event is defined as 'WARNING'
| C synopsis | target-domain |
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 |
| Diags_compareLevels() // module-wide |
|
Returns false if levelA is lower than levelB
| C synopsis | target-domain |
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 |
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 |
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(String 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. In addition, the
Diags.setMaskEnabled configuration
parameter must be set to true in order to load this function onto
the target. Finally, the following configuration parameters must
have the values indicated (which are their default values):
- <module>.common$.namedModule = true;
- Text.isLoaded = true;
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
| usage | meta-domain | sourced in xdc/runtime/Diags.xdc |
var Diags = xdc.useModule('xdc.runtime.Diags');
module-wide constants & types
const Diags.ALL_LOGGING// Mask of all logging diagnostic categories (does not include asserts) = Diags.ALL & (~Diags.ASSERT) & (~Diags.INTERNAL);
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.USER7// Alias for informational event = 0x4000;
const Diags.USER8// Alias for analysis event = 0x8000;
values of type Diags.EventLevel// The level of an event
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
| usage | meta-domain |
const Diags.ALL = 0xFF9F;
C SYNOPSIS
| const Diags.ALL_LOGGING |
|
Mask of all logging diagnostic categories (does not include asserts)
| usage | meta-domain |
C SYNOPSIS
| const Diags.ANALYSIS |
|
Analysis (e.g., benchmark) event
| usage | meta-domain |
C SYNOPSIS
| const Diags.ASSERT |
|
Assert checking
| usage | meta-domain |
const Diags.ASSERT = 0x0010;
C SYNOPSIS
| const Diags.CRITICAL |
|
A 'LEVEL2' 'STATUS' event is defined as 'CRITICAL'
| usage | meta-domain |
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
| const Diags.EMERGENCY |
|
A 'LEVEL1' 'STATUS' event is defined as 'EMERGENCY'
| usage | meta-domain |
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
| usage | meta-domain |
const Diags.ENTRY = 0x0001;
C SYNOPSIS
| const Diags.ERROR |
|
A 'LEVEL3' 'STATUS' event is defined as 'ERROR'
| usage | meta-domain |
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
| const Diags.EXIT |
|
Function exit
| usage | meta-domain |
const Diags.EXIT = 0x0002;
C SYNOPSIS
| const Diags.INFO |
|
Informational event
| usage | meta-domain |
C SYNOPSIS
| const Diags.INTERNAL |
|
Internal diagnostics
| usage | meta-domain |
const Diags.INTERNAL = 0x0008;
C SYNOPSIS
| const Diags.LIFECYCLE |
|
Object life-cycle
| usage | meta-domain |
const Diags.LIFECYCLE = 0x0004;
C SYNOPSIS
| const Diags.STATUS |
|
Warning or error event
| usage | meta-domain |
const Diags.STATUS = 0x0080;
C SYNOPSIS
| const Diags.USER1 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER1 = 0x0100;
C SYNOPSIS
| const Diags.USER2 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER2 = 0x0200;
C SYNOPSIS
| const Diags.USER3 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER3 = 0x0400;
C SYNOPSIS
| const Diags.USER4 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER4 = 0x0800;
C SYNOPSIS
| const Diags.USER5 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER5 = 0x1000;
C SYNOPSIS
| const Diags.USER6 |
|
User defined diagnostics
| usage | meta-domain |
const Diags.USER6 = 0x2000;
C SYNOPSIS
| const Diags.USER7 |
|
Alias for informational event
| usage | meta-domain |
const Diags.USER7 = 0x4000;
C SYNOPSIS
| const Diags.USER8 |
|
Alias for analysis event
| usage | meta-domain |
const Diags.USER8 = 0x8000;
C SYNOPSIS
| const Diags.WARNING |
|
A 'LEVEL4' 'STATUS' event is defined as 'WARNING'
| usage | meta-domain |
DETAILS
See 'EMERGENCY' for details.
C SYNOPSIS
| enum Diags.EventLevel |
|
The level of an event
| usage | meta-domain |
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
| usage | meta-domain |
values of type Diags.Mode
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
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
| usage | meta-domain |
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
| usage | meta-domain |
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 Fri, 19 Nov 2010 23:52:23 GMT