From RTSC-Pedia

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC

Using xdc.runtime Errors/Example 2

How to use the Assert module

Using the Assert module

As with the Log_print and Log_write statements, Assert_isTrue assertions are

1. enabled and disabled on a per module basis, and
2. can be permanently enabled or disabled or even enabled and disabled at runtime.

In addition, a distinction is made between "internal" assertions (which are typically "compiled out" of released binary objects) and "public" assertions which are explicitly declared in module specification files, remain in production binary code, and are intended to be individually controllable by the system integrator.

Internal assertions

Similar to Log_write(), Assert_isTrue() takes an "event id" argument which allows one to provide additional information about the error - beyond the normal file and line number of the assertion statement itself. Unlike Log_write(), however, the "event id" passed may be NULL; in this case, the assert statement behaves like the an ordinary C assert() statement. Assertion statements that pass NULL as the event id are called "internal" assertions and can be enabled and disabled as a group separate from those assertions that pass an event id declared in a module specification file.

Since "internal" assertions do not require an event id, they can be used without creating or modifying a module specification file. In the example below, line 1 illustrates the use of an "internal" assert; it's an "internal" assert because the second argument to Assert_isTrure() is NULL.

#include <xdc/std.h>
 
#include <xdc/runtime/Assert.h>
#include <xdc/runtime/System.h>
 
/* ======== half ======== */
static Int half(Int num)
{
    Assert_isTrue((num & 0x1) == 0, NULL);
 
    return (num / 2);
}
 
/* ======== main ======== */
Int main(Int argc, String argv[])
{
    System_printf("half returned %d\n", half(16));
 
    /* trigger an assertion violation */
    System_printf("half returned %d\n", half(17));
 
    return (0);
}

var Assert  = xdc.useModule("xdc.runtime.Assert");
var System = xdc.useModule("xdc.runtime.System");

half returned 8
half returned 8

Why didn't the assertion on line 1 execute? By default, "internal" assertions are disabled for all modules. To enable the evaluation of these assertions, you must set the module's common$.diags_INTERNAL configuration parameter to either Diags.ALWAYS_ON, Diags.RUNTIME_ON, or Diags.RUNTIME_OFF (and enable it at runtime via the Diags_setMask() function).

We can enable or disable the evaluation of assertions through configuration alone; it is not necessary to recompile any sources.

var Assert  = xdc.useModule("xdc.runtime.Assert");
var System = xdc.useModule("xdc.runtime.System");
 
var Diags  = xdc.useModule("xdc.runtime.Diags");
var Main = xdc.useModule("xdc.runtime.Main");
 
Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;

half returned 8
xdc.runtime.Main: "main.c", line 8: assertion failure
xdc.runtime.Error.raise: terminating execution

Runtime control of assertions

Unlike the normal ANSI C assert() mechanism, it is possible to enable and disable Assert_isTrue() assertions at runtime. Even though it is common practice to "compile out" assertions in production code, it is sometimes desirable to have a single binary image in which assertions can be optionally enabled (disabled) via a runtime variable. In the example below, there are two calls to half() that should trigger an assertion violation. Notice, however, that the first call to half() does not terminate the executable. Instead, this call simply returns to the caller with a value that is printed via System_printf. The call to Diags_setMask() enables assertion checking for the xdc.runtime.Main module (the module "containing" half()) and the next call to half() with an odd argument triggers an assertion which terminates the executable.

#include <xdc/std.h>
 
#include <xdc/runtime/Assert.h>
#include <xdc/runtime/System.h>
#include <xdc/runtime/Diags.h>
 
/* ======== half ======== */
static Int half(Int num)
{
    Assert_isTrue((num & 0x1) == 0, NULL);
 
    return (num / 2);
}
 
/* ======== main ======== */
Int main(Int argc, String argv[])
{
    /* call a function that raises an assertion */
    System_printf("half returned %d\n", half(17));
 
    /* enable internal assertions for Main */
    Diags_setMask("xdc.runtime.Main+I");
 
    /* call a function that raises an assertion */
    System_printf("half returned %d\n", half(17));
 
    return (0);
}

var Assert  = xdc.useModule("xdc.runtime.Assert");
var System = xdc.useModule("xdc.runtime.System");
var Diags  = xdc.useModule("xdc.runtime.Diags");
 
var Main = xdc.useModule("xdc.runtime.Main");
Main.common$.diags_INTERNAL = Diags.RUNTIME_OFF;

half returned 8
xdc.runtime.Main: "enable.c", line 9: assertion failure
xdc.runtime.Error.raise: terminating execution

See also

[printable version]

offline version generated on 04-Aug-2010 21:08 UTC