module xdc.runtime.Error

Runtime error manager

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation
DETAILS
EXAMPLES

The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters. [ more ... ]

XDCspec summary sourced in xdc/runtime/Error.xdc

module Error { ...

// inherits xdc.runtime.IModule

C synopsis target-domain

#include <xdc/runtime/Error.h>

module-wide constants & types

#define Error_NUMARGS// Maximum number of arguments supported by an error (Int)2

typedef enum Error_Policy// Error handling policies {

Error_TERMINATE,

Error_UNWIND

} Error_Policy;

typedef opaque Error_Id// Error identifier;

typedef struct Error_Block// Error block Error_Block;

typedef struct Error_Data// Error args {

IArg arg[Error_NUMARGS];

} Error_Data;

module-wide config parameters

extern const Error_Id Error_E_generic// Generic error;

extern const Error_Id Error_E_memory// Out of memory error;

extern const UInt16 Error_maxDepth// Maximum number of concurrent calls to raiseHook;

extern const Error_Policy Error_policy// System-wide error handling policy;

extern const Void (*Error_raiseHook// The function to call whenever an error is raised)(Error_Block*);

module-wide functions

Bool Error_check// Return TRUE if an error was raised( Error_Block *eb );

UInt16 Error_getCode// Get an error's code( Error_Block *eb );

Error_Data *Error_getData// Get an error's argument list( Error_Block *eb );

Error_Id Error_getId// Get an error's id( Error_Block *eb );

String Error_getMsg// Get an error's "printf" format string( Error_Block *eb );

Types_Site *Error_getSite// Get an error's call site info( Error_Block *eb );

Void Error_init// Put an error block into its initial state( Error_Block *eb );

Void Error_print// Print error using System.printf()( Error_Block *eb );

macro Void Error_raise// Raise an error( Error_Block *eb, Error_Id id, IArg arg1, IArg arg2 );

module-wide built-ins

Types_ModuleId Error_Module_id// Get this module's unique id( );

Bool Error_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle Error_Module_heap// The heap from which this module allocates memory( );

Bool Error_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 Error_Module_getMask// Returns the diagnostics mask for this module( );

Void Error_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

XDCscript usage meta-domain

var Error = xdc.useModule('xdc.runtime.Error');

module-wide constants & types

const Error.NUMARGS// Maximum number of arguments supported by an error = 2;

values of type Error.Policy// Error handling policies

const Error.TERMINATE;

const Error.UNWIND;

var obj = new Error.Data// Error args;

obj.arg = IArg[Error.NUMARGS] ...

var obj = new Error.Desc// Error descriptor;

obj.msg = String ...

obj.code = UInt16 ...

module-wide config parameters

Error.E_generic// Generic error = Error.Desc {

msg: "generic error: %s"

};

Error.E_memory// Out of memory error = Error.Desc {

msg: "out of memory: heap=0x%x, size=%u"

};

Error.maxDepth// Maximum number of concurrent calls to raiseHook = UInt16 16;

Error.policy// System-wide error handling policy = Error.Policy Error.UNWIND;

Error.raiseHook// The function to call whenever an error is raised = Void(*)(Error.Block*) Error.print;

Error.common$// Common module configuration parameters = Types.Common$ undefined;

XDCspec declarations sourced in xdc/runtime/Error.xdc

package xdc.runtime;

module Error {

module-wide constants & types

const Int NUMARGS// Maximum number of arguments supported by an error = 2;

enum Policy// Error handling policies {

TERMINATE,

UNWIND

};

@Encoded typedef Error.Desc Id// Error identifier;

@Opaque struct Block// Error block;

struct Data// Error args {

IArg arg[Error.NUMARGS];

};

metaonly struct Desc// Error descriptor {

String msg;

UInt16 code;

};

module-wide config parameters

config Error.Id E_generic// Generic error = {

msg: "generic error: %s"

};

config Error.Id E_memory// Out of memory error = {

msg: "out of memory: heap=0x%x, size=%u"

};

config UInt16 maxDepth// Maximum number of concurrent calls to raiseHook = 16;

config Error.Policy policy// System-wide error handling policy = Error.UNWIND;

config Void (*raiseHook// The function to call whenever an error is raised)(Error.Block*) = Error.print;

metaonly config Types.Common$ common$// Common module configuration parameters;

module-wide functions

Bool check// Return TRUE if an error was raised( Error.Block *eb );

UInt16 getCode// Get an error's code( Error.Block *eb );

Error.Data *getData// Get an error's argument list( Error.Block *eb );

Error.Id getId// Get an error's id( Error.Block *eb );

String getMsg// Get an error's "printf" format string( Error.Block *eb );

Types.Site *getSite// Get an error's call site info( Error.Block *eb );

Void init// Put an error block into its initial state( Error.Block *eb );

Void print// Print error using System.printf()( Error.Block *eb );

@Macro Void raise// Raise an error( Error.Block *eb, Error.Id id, IArg arg1, IArg arg2 );

}

DETAILS

The Error module provides mechanisms for raising, checking, and handling errors in a program. You can configure it via the Error.policy and Error.raiseHook configuration parameters.

Modules may define specific error types and reference these when raising an error. Each error type has a custom error message and can be parameterized with up to NUMARGS arguments. A generic error type is provided for raising errors when not in a module.

Use the Error_check() function to determine if an error has been raised. It is important to understand that it is the caller's responsibility to check the error block after calling a function that takes an error block as an argument. Otherwise, a raised error may go undetected, which could compromise the integrity of the system. For example:

  Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }

The Error.raiseHook configuration parameter allows a configured function to be invoked when any error is raised. This function is passed a pointer to the error's error block and makes it easy to manage all errors from a common point. For example, you can trap any error (fatal or not) by simply setting a breakpoint in this function. You can use the following functions to extract information from an error block.

EXAMPLES

Example 1: The following example shows how a module, named ModA, defines a custom error type and shows how this error is raised by the module. The module defines an Id of E_notEven in its module specification file (in this case, ModA.xdc). The error's message string takes only one argument. The module also defines a mayFail() function that takes an error block. In the module's C source file, the function checks for the error condition and raises the error if needed.

This is part of ModA's XDC specification file for the module:

  config xdc.runtime.Error.Id E_notEven = {
      msg: "expected an even number (%d)"
  };

  Void mayFail(Int x, xdc.runtime.Error.Block *eb);

This is part of the C code for the module:

  Void ModA_mayFail(Int x, Error_Block *eb)
  {
      if ((x % 2) != 0) {
          Error_raise(eb, ModA_E_notEven, x, 0);
          ...add error handling code here...
          return;
      }
      ...
  }

Example 2: The following C code supplies an error block to a function that requires one and tests the error block to see if the function raised an error. Note that an error block must be initialized before it can be used and same error block may be passed to several functions.

  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>
  Error_Block eb;
  Task_Handle tsk;

  Error_init(&eb);
  tsk = Task_create(..., &eb);

  if (Error_check(&eb)) {
      ...an error has been raised...
  }

Example 3: The following C code shows that you may pass NULL to a function requiring an error block. In this case, if the function raises an error, the program is aborted (via xdc_runtime_System_abort()), thus execution control will never return to the caller.

  #include <xdc/runtime/Error.h>
  #include <ti/sysbios/knl/Task.h>

  tsk = Task_create(..., NULL);
  ...will never get here if an error was raised in Task_create...

Example 4: The following C code shows how to write a function that is not part of a module and that takes an error block and raises the generic error type provided by the Error module. Note, if the caller passes NULL for the error block or if the error policy is TERMINATE, then the call to Error_raise() will call xdc_runtime_System_abort() and never return.

  #include <xdc/runtime/Error.h>

  Void myFunc(..., Error_Block *eb)
  {
      ...

      if (...error condition detected...) {
          String  myErrorMsg = "my custom error message";
          Error_raise(eb, Error_E_generic, myErrorMsg, 0);
          ...add error handling code here...
          return;
      }
  }

const Error.NUMARGS