module xdc.runtime.Assert
index URL

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 ... ]
C synopsis target-domain sourced in xdc/runtime/Assert.xdc
#include <xdc/runtime/Assert.h>
Functions
macro Void 
Assert_isTrue// Test an assertion(Bool expr, Assert_Id id);
Functions common to all target modules
Assert_Module_getMask// Returns the diagnostics mask for this module, Assert_Module_hasMask// Test whether this module has a diagnostics mask, Assert_Module_heap// The heap from which this module allocates memory, Assert_Module_id// Get this module's unique id, Assert_Module_setMask// Set the diagnostics mask for this module, Assert_Module_startupDone// Test if this module has completed startup
Typedefs
typedef opaque
Assert_Id// Assert identifier;
Constants
extern const Error_Id 
Assert_E_assertFailed// The Error.Id raised when an assertion violation is detected;
 
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
index URL

Assert identifier

C synopsis target-domain
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
index URL

The Error.Id raised when an assertion violation is detected

C synopsis target-domain
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
isTrue, Error.Id
 
Assert_isTrue()  // module-wide
index URL

Test an assertion

C synopsis target-domain
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
index URL

C synopsis target-domain
Types_ModuleId Assert_Module_id();
// Get this module's unique id
 
Bool Assert_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Assert_Module_heap();
// 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
 
Configuration settings sourced in xdc/runtime/Assert.xdc
var Assert = xdc.useModule('xdc.runtime.Assert');
module-wide constants & types
    var obj = new Assert.Desc// Assert descriptor;
        obj.mask = Bits16  ...
        obj.msg = String  ...
module-wide config parameters
    const Assert.E_assertFailed// The Error.Id raised when an assertion violation is detected = Error.Desc {
        msg: "assertion failure%s%s"
    };
 
    Assert.common$// Common module configuration parameters = Types.Common$ undefined;
 
 
metaonly struct Assert.Desc
index URL

Assert descriptor

Configuration settings
var obj = new Assert.Desc;
 
    obj.mask = Bits16  ...
    obj.msg = String  ...
 
FIELDS
mask — Specifies which bits enable the assert.
msg — The message printed when the assert fails.
DETAILS
Each public assert is defined with an assert descriptor. This structure defines which bits in the module's diagnostics mask control this assert, and the message raised when the assert fails. The mask property is optional, it defaults to the Diags.ASSERT bit.
 
config Assert.E_assertFailed  // module-wide
index URL

The Error.Id raised when an assertion violation is detected

Configuration settings
const Assert.E_assertFailed = Error.Desc {
    msg: "assertion failure%s%s"
};
 
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
isTrue, Error.Id
C SYNOPSIS
Assert_E_assertFailed
 
metaonly config Assert.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
Assert.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.
generated on Thu, 23 May 2019 00:24:44 GMT