From RTSC-Pedia
 | [printable version] [offline version] | offline version generated on 04-Aug-2010 21:08 UTC |   |
Using xdc.runtime Errors
How to raise and handle runtime errors
Contents |
Introduction
The xdc.runtime package contains several modules that work together to provide rich application diagnostic support that can be controlled in real-time within deployed systems. This section focuses on those modules that are used to raise and handle errors and provide assertion support: Error and Assert, respectively.
Use of these modules is illustrated below by a series of examples that take advantage of two other distinguished xdc.runtime modules:
- Main - a module whose configuration applies to all code that is not a RTSC module; e.g., existing C code bases, and
- Defaults - a module whose configuration applies to all RTSC modules (including Main), unless explicitly overridden on a per-module basis.
Overview
Each embedded application runs in a unique environment with specific resource requirements and, as a result, adopts application-specific policies for managing runtime errors; e.g., reset-and-reboot, catch-and-retry, log-and-continue, or a combination of these policies for different parts of the system. The xdc.runtime package provides a set of mechanisms for raising and handling runtime errors that enables code to be written once and used in any application - independent of the application's error handling policies.
Architecture
The xdc.runtime package supports two distinct "categories" of error:
- errors that are explicitly checked for and handled by the code, and
- assertion violations that arise when the current application state is inconsistent with the range of states required by a piece of code.
The first category of errors are managed by the Error module and the second category is managed by the Assert module. Rather than use simple fixed-length error numbers, the xdc.runtime package uniformly employs an opaque Error_Block structure to "raise" errors via Error_raise(). Functions that raise errors are passed a pointer to an Error_Block structure which is passed to Error_raise() when an error is detected. When an error is raised, the Error_Block structure records the source of the error, a unique ID for for the error, a message format string, and up to two arguments associated with this particular occurrence.
Using an Error_Block structure has several advantages. Perhaps most importantly, the information about the source of the error as well as data specific to the particular occurrence is efficiently copied into the structure for later processing. In effect, Error_raise() combines the efficiency of a simple error code with the richness of a printf at the site of the error. Since the error information is simply recorded in the Error_Block structure, the application developer can control when and how the information will be formatted and displayed.
Similar to the standard C assert() macro, the Assert module's methods are interspersed with other code to add runtime checks - primarily during early development - that ensure the code is being called in the appropriate context. 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 assertions remain in the final application, if any.
When an assertion violation is detected, an Assert.E_assertFailed error is raised (via Error_raise()) with a NULL Error_Block reference; so, assertions are handled using the same error handling hooks as "normal" errors.
Configuration
Users of libraries that embed xdc.runtime.Assert statements can configure their application to specify:
- on a per-module basis, what assertions should be evaluated and whether these assertions are always enabled (disabled) or whether they can be enabled and disabled at runtime via Diags_setmask()
- on a per application basis whether errors should terminate the application or "unwind" to the caller
- on a per application basis, a custom error handler
These configuration options make it possible for the system integrator to strike a balance between the need for runtime error checking against the overhead required for these checks without making any changes to the code containing embedded Error or Assert statements. Even better, these options are possible without requiring re-compilation of any source code making it possible to (re)configure pre-built binary libraries that utilize xdc.runtime.Error or xdc.runtime.Assert methods.
Examples
In the table below, we provide a series of graduated examples that illustrate the key capabilities of this package and provide links to more advanced topics.
| Example | Description | Purpose |
|---|---|---|
| Example 1 | Using Error to raise and "catch" errors | a minimal example to illustrate using Error in existing code bases |
| Example 2 | Using Assert to perform runtime checks | a minimal example to illustrate using Assert in existing code bases |
| Example 3 | Creating an Error handler | illustrate how to bind a custom error handler |
| Example 4 | Creating new Error Ids | illustrate how to create new Error Descriptors |
| Example 5 | Logging All Errors | illustrate custom error handler that logs all errors |
Performance Considerations
In this section we review the performance impact of using Error and Assert. In addition, we provide techniques for balancing the overhead against increased per error information.
Eliminating File Name Strings
Unless otherwise specified, both Error_raise() and Assert_isTrue() pass the file name of the caller (__FILE__) to the underlying functions that handle errors. As a result, there are a number of static strings that are embedded in any application that uses Error or Assert. To eliminate these strings you can add the following line, before including xdc/runtime/Error.h or xdc/runtime/Assert.h, to each source file.
| | #define xdc_FILE NULL /* eliminate use of __FILE__ in Assert and Error macros */ |
Alternatively, you can add the equivalent -D option to your compiler's command line.
| | cl -Dxdc_FILE=NULL ... |
Eliminating Error and Assert Message Strings
As with the Log module, the strings associated with an error or assertion descriptors can be entirely eliminated from the target's memory. These strings can be stored and used on a "diagnostic" client that has less constrained resources.
To eliminate the runtime strings you must configure the Text module to place all strings in a special section that will not be loaded onto the target.
| | var Text = xdc.module("xdc.runtime.Text"); Text.isLoaded = false; |
In addition to message strings used in Error and Assert descriptors, the Text module maintains the string names of all modules and (optionally) instances are also maintained on the target. Setting Text.isLoaded to false will also eliminate these string names. Again, in systems where space is a precious resource, it is sometimes necessary to eliminate these "conveniences" in favor of other critical data.
| [printable version] [offline version] | offline version generated on 04-Aug-2010 21:08 UTC | |
