module xdc.runtime.Assert |
|
|
|
Runtime assertion manager
The
Assert module provides configurable diagnostics to the program.
Similar to the standard C
assert() macro,
Assert methods are
interspersed with other code to add diagnostics to a program. Unlike
the standard C assert support, the
Assert module provides greater
flexibility in managing the messages displayed, the message string
space overhead, and the runtime handling of failures. In addition,
because the
Assert methods build atop the Diags module, you can
precisely control which asserts remain in the final application, if any.
[
more ... ]
#include <xdc/runtime/Assert.h>
Functions |
macro Void | |
Functions common to all target modules |
|
|
Typedefs |
typedef opaque | |
Constants |
| |
DETAILS
The Assert module provides configurable diagnostics to the program.
Similar to the standard C assert() macro, Assert methods are
interspersed with other code to add diagnostics to a program. Unlike
the standard C assert support, the Assert module provides greater
flexibility in managing the messages displayed, the message string
space overhead, and the runtime handling of failures. In addition,
because the Assert methods build atop the Diags module, you can
precisely control which asserts remain in the final application, if any.
The
Assert module works in conjunction with the
Diags module.
Assert statements are added to the code using the
Assert_isTrue() function. Execution of assert
statements is controlled by the
Diags.ASSERT and
Diags.INTERNAL bits in a module's diagnostics mask. By default,
all module's
Diags_ASSERT bit is enabled and the
Diags_INTERNAL bit
is disabled. See
Types.Common$ for the
declaration of the bits in the diagnostics mask and
Default.common$ for the default module settings.
Two types of asserts are supported: public asserts and internal asserts.
- Public asserts have an assert ID and are, by default, controlled
by the Diags.ASSERT bit.
- Internal asserts don't have an assert ID (other than NULL) and
are active only when both the Diags.ASSERT and
Diags.INTERNAL bits of the module's diagnostics mask are set.
Assert IDs are small integer values that index into a table of
assertion descriptors. These descriptors hold an error message
and a diagnostics mask that is used to enable and disable the
assertion at runtime.
You can remap individual public asserts to different bits in the
diagnostics mask, or can disable the assert altogether. This is
done by setting the mask property of the assert ID. Setting the
mask to 0 disables the assert. In all other cases, the Diags.ASSERT
bit is OR'd together with the mask to define the controlling bits.
For example, the module's diagnostics mask must have the Diags.ASSERT
bit set and any other bit specified in the mask property of the
assert ID in order to activate the assert.
EXAMPLES
Example 1: The following C code adds an assert to application code
which is not in a module. This assert does not have an assert
identifier (the second argument is NULL); this makes it an internal
assert.
// file.c
#include <xdc/runtime/Assert.h>
Assert_isTrue(count > 0, NULL);
The following XDC configuration statements set both the ASSERT and
INTERNAL bits in the diagnostics mask to enable the internal assert
created in the previous C code. Since the C code is not in a module,
you must set the bits in the diagnostics mask of the
xdc.runtime.Main module. The Main module
is used to control all
Log and
Assert statements that are
not part of the implementation of a module; for example, top-level
application code or any existing sources that simply call the
Log or
Assert methods.
// program.cfg
var Assert = xdc.useModule('xdc.runtime.Assert');
var Diags = xdc.useModule('xdc.runtime.Diags');
var Main = xdc.useModule('xdc.runtime.Main');
Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;
Example 2: The following example shows how to use and configure an
assert ID that is declared by a module. It adds that assert to the
application's C source code, and configures the application to
execute the assert.
This is part of the XDC file for the module that declares an Assert Id:
// Mod.xdc
import xdc.runtime.Assert;
import xdc.runtime.Diags;
config Assert.Id A_nonZero = {
msg: "A_nonZero: value must be non-zero"
};
This is part of the C code for the application:
// Mod.c
#include <xdc/runtime/Assert.h>
Assert_isTrue(x != 0, Mod_A_nonZero);
This is part of the XDC configuration file for the application:
// program.cfg
var Diags = xdc.useModule('xdc.runtime.Diags');
var Mod = xdc.useModule('my.pkg.Mod');
Mod.common$.diags_ASSERT = Diags.ALWAYS_ON;
The Assert calls can also be completely removed by defining the symbol
xdc_runtime_Assert_DISABLE_ALL. This can be done on the compile line, e.g.
-Dxdc_runtime_Assert_DISABLE_ALL. This will completely remove the Assert
statements from any code compiled with this flag, regardless of the
application's configuration or your compiler's optimization settings.
It is also possible to remove all conditions from Assert calls. As explained
above, Assert calls are executed only if certain bits in the module's
Diags mask are set. However, if the symbol
xdc_runtime_Assert_DISABLE_CONDITIONAL_ASSERT is defined, the module's Diags
mask is not queried at all, and all Assert calls are unconditionally
executed.
The symbol xdc_runtime_Assert_DISABLE_ALL has a precedence, and if it's
set, no Assert calls are executed regardless of any definition of
xdc_runtime_Assert_DISABLE_CONDITIONAL_ASSERT.
typedef Assert_Id |
|
Assert identifier
typedef opaque Assert_Id;
DETAILS
Each metaonly assert descriptor is encoded into a target accessable
assert Id type which can be passed to the
isTrue function.
config Assert_E_assertFailed // module-wide |
|
The Error.Id raised when an assertion violation is detected
extern const Error_Id Assert_E_assertFailed;
DETAILS
When an assertion violation is triggered, an error is raised via
Error_raise().
E_assert_Failed is the
Error.Id passed
to
Error_raise().
The first string argument (%s) will be either "", if the assertion Id
is
NULL (for internal asserts), or ": " (for public asserts).
The second string argument (%s) is the
Assert.Desc.msg string associated with the assertion Id; if the
Id is
NULL (an internal assert) or if text is not loaded
(
!Text.isLoaded()), this string is "".
SEE
Assert_isTrue() // module-wide |
|
Test an assertion
macro Void Assert_isTrue(
Bool expr,
Assert_Id id);
ARGUMENTS
expr
the expression which should evaluate to true
id
identifies the assert being raised
DETAILS
Assert_isTrue() statements may be conditionally enabled (disabled)
on a per module basis by setting the calling module's
$common.diags_ASSERT configuration
parameter. If
the
Assert_isTrue() statement is not in a module, the calling
module is the
Main module. You must enable the
Diags.ASSERT bit in the module's diagnostics mask for this
call to be enabled. If a
NULL assert id is specified, then you
must enable the
Diags.INTERNAL in addition to the
ASSERT bit.
If the
Assert_isTrue() statement is enabled and
expr evaluates to
false, the assert specified by
id is raised; i.e., the
E_assertFailed error is raised with a
NULL
error block. In other words, the standard
Error.raise
handling hooks will be run,
System.abort() will be called,
and control does not return to the caller. The
id may be
null, in
which case you will get a generic assert message.
EXAMPLES
C Code
#include <xdc/runtime/Assert.h>
Assert_isTrue(count > 0, NULL);
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Assert_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Assert_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Assert_Module_getMask();
// Returns the diagnostics mask for this module
Void Assert_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
var Assert = xdc.useModule('xdc.runtime.Assert');
module-wide constants & types
module-wide config parameters
msg: "assertion failure%s%s"
};
generated on Fri, 10 Jun 2016 23:31:27 GMT