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.
Each bit of the diagnostics mask is controlled by one of the following
constants.
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.
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.
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.
Configuration example: The following XDC configuration statements
turn on asserts in the entire program.
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.
const Diags.ALL |
|
Turn on all diagnostics
XDCscript usage |
meta-domain |
const Diags.ALL = 0xFFFF;
const Diags.ASSERT |
|
Assert checking
XDCscript usage |
meta-domain |
const Diags.ASSERT = 0x0010;
const Diags.ENTRY |
|
Function entry
XDCscript usage |
meta-domain |
const Diags.ENTRY = 0x0001;
const Diags.EXIT |
|
Function exit
XDCscript usage |
meta-domain |
const Diags.EXIT = 0x0002;
const Diags.INTERNAL |
|
Internal diagnostics
XDCscript usage |
meta-domain |
const Diags.INTERNAL = 0x0008;
const Diags.LIFECYCLE |
|
Object life-cycle
XDCscript usage |
meta-domain |
const Diags.LIFECYCLE = 0x0004;
const Diags.USER1 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER1 = 0x0100;
const Diags.USER2 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER2 = 0x0200;
const Diags.USER3 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER3 = 0x0400;
const Diags.USER4 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER4 = 0x0800;
const Diags.USER5 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER5 = 0x1000;
const Diags.USER6 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER6 = 0x2000;
const Diags.USER7 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER7 = 0x4000;
const Diags.USER8 |
|
User defined diagnostics
XDCscript usage |
meta-domain |
const Diags.USER8 = 0x8000;
metaonly enum Diags.Mode |
|
Diagnostics mask bit value used at configuration time
XDCscript 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.
typedef Diags.Mask |
|
Type used to specify bits in the diags mask
typedef Bits16 Diags_Mask;
metaonly config Diags.common$ // module-wide |
|
Common module configuration parameters
XDCscript 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.
Diags.query( ) // module-wide |
|
Query the module's diagnostics mask against the given 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
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
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):
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");
metaonly Diags.setMaskMeta( ) // module-wide |
|
Set the module's diagnostics mask at config time
XDCscript usage |
meta-domain |
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
module-wide built-ins |
|
// Get this module's unique id
Bool Diags_Module_startupDone( );
// Test if this module has completed startup
// 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