<< Previous | Index | Next >>

8. Run-Time Errors

Compiled code generated by Dynamic C calls an exception handling routine for run-time errors. The exception handler supplied with Dynamic C prints internally defined error messages to a Windows message box when run-time errors are detected during a debugging session. When software runs stand-alone (disconnected from Dynamic C), such a run-time error will cause a watchdog timeout and reset. Starting with Dynamic C 7.05, run-time error logging is available for Rabbit-based target systems with battery-backed RAM.

8.1 Run-Time Error Handling

When a run-time error occurs, a call is made to exception(). The run-time error type is passed to exception(), which then pushes various parameters on the stack, and calls the installed error handler. The default error handler places information on the stack, disables interrupts, and enters an endless loop by calling the _xexit function in the BIOS. Dynamic C notices this and halts execution, reporting a run-time error to the user.

8.1.1 Error Code Ranges

The table below shows the range of error codes used by Dynamic C and the range available for a custom error handler to use. Please see section 8.2 on page 93 for more information on replacing the default error handler with a custom one.

Table 8-11. Dynamic C Error Types Ranges

Error Type	Meaning
0-127	Reserved for user-defined error codes.
128-255	Reserved for use by Dynamic C.

8.1.2 Fatal Error Codes

This table lists the fatal errors generated by Dynamic C.

Table 8-12. Dynamic C Fatal Errors

Error Type	Meaning
127 - 227	not used
228	Pointer store out of bounds
229	Array index out of bounds
230 - 233	not used
234	Domain error (for example, acos(2))
235	Range error (for example, tan(pi/2))
236	Floating point overflow
237	Long divide by zero
238	Long modulus, modulus zero
239	not used
240	Integer divide by zero
241	Unexpected interrupt
242	not used
243	Codata structure corrupted
244	Virtual watchdog timeout
245	XMEM allocation failed (xalloc call)
246	Stack allocation failed
247	Stack deallocation failed
248	not used
249	Xmem allocation initialization failed
250	No virtual watchdog timers available
251	No valid MAC address for board
252	Invalid cofunction instance
253	Socket passed as auto variable while running µC/OS-II
254	not used
255

8.2 User-Defined Error Handler

Dynamic C allows replacement of the default error handler with a custom error handler. This is needed to add run-time error handling that would require treatment not supported by the default handler.

A custom error handler can also be used to change how existing run-time errors are handled. For example, the floating-point math libraries included with Dynamic C are written to allow for execution to continue after a domain or range error, but the default error handler halts with a run-time error if that state occurs. If continued execution is desired (the function in question would return a value of INF or whatever value is appropriate), then a simple error handler could be written to pass execution back to the program when a domain or range error occurs, and pass any other run-time errors to Dynamic C.

8.2.1 Replacing the Default Handler

To tell the BIOS to use a custom error handler, call this function:

void defineErrorHandler(void *errfcn)

This function sets the BIOS function pointer for run-time errors to the one passed to it.

When a run-time error occurs, exception() pushes onto the stack the information detailed in the table below.

Table 8-13. Stack setup for run-time errors

Address	Data at address
SP+0	Return address for error handler
SP+2	Error code
SP+4	Additional data (user-defined)
SP+6	XPC when exception() was called (upper byte)
SP+8	Address where exception() was called from

.

Then exception() calls the installed error handler. If the error handler passes the run-time error to Dynamic C (i.e. it is a fatal error and the system needs to be halted or reset), then registers must be loaded appropriately before calling the _xexit function.

Dynamic C expects the following values to be loaded:

Table 8-14. Register contents loaded by error handler before passing the error to Dynamic C

Register	Expected Value
H	XPC when exception() was called
L	Run-time error code
HL'	Address where exception() was called from

8.3 Run-Time Error Logging

Starting with Dynamic C 7.05, error logging is available as a BIOS enhancement for storing run-time exception history. It can be useful diagnosing problems in deployed Rabbit targets. To support error logging, the target must have battery-backed RAM.

8.3.1 Error Log Buffer

A circular buffer in extended RAM will be filled with the following information for each run-time error that occurs:

• The value of SEC_TIMER at the time of the error. This variable contains the number of seconds since 00:00:00 on January 1st 1980 if the real-time clock has been set correctly. This variable is updated by the periodic timer which is enabled by default. Z-World sets the real-time clock in the factory. When the BIOS starts on boards with batteries, it initializes SEC_TIMER to the value in the real-time clock.

• The address where the exception was called from. This can be traced to a particular function using the MAP file generated when a Dynamic C program is compiled.

• The exception type. Please see Table 8-12 on page 92 for a list of exception types.

• The value of all registers. This includes alternate registers, SP and XPC. This is a global option that is enabled by default.

• An 8 byte message. This is a global option that is disabled by default. The default error handler does nothing with this.

• A user-definable length of stack dump. This is a global option that is enabled by default.

• A one byte checksum of the entry.

8.3.1.1 Error Log Buffer Size

The size of the error log buffer is determined by the number of entries, the size of an entry, and the header information at the beginning of the buffer. The number of entries is determined by the macro ERRLOG_NUM_ENTRIES (default is 78). The size of each entry is dependent on the settings of the global options for stack dump, register dump and error message. The default size of the buffer is about 4K in extended RAM.

8.3.2 Initialization and Defaults

An initialization of the error log occurs when the BIOS is compiled, when cloning takes place or when the BIOS is loaded via the Rabbit Field Utility (RFU). By default, error logging is enabled with messages turned off, stack and register dumps turned on, and an error log buffer big enough for 78 entries.

The error log buffer contains header information as well as an entry for each run-time error. A debug start-up will zero out this header structure, but the run-time error entries can still be examined from Dynamic C using the static information in flash. The header is at the start of the error log buffer and contains:

• A status byte
• The number of errors since deployment
• The index of the last error
• The number of hardware resets since deployment
• The number of watchdog time-outs since deployment
• The number of software resets since deployment
• A checksum byte.

"Deployment" is defined as the first power up without the programming cable attached. Reprogramming the board through the programming cable, RFU, or RabbitLink and starting the program again without the programming cable attached is a new deployment.

8.3.3 Configuration Macros

These macros are defined at the top of Bios/RabbitBios.c.

ENABLE_ERROR_LOGGING

Default: 0. Disables error logging. Changing this to one in the BIOS enables error logging.

ERRLOG_USE_REG_DUMP

Default: 1. Include a register dump in log entries. Changing this to zero in the BIOS excludes the register dump in log entries.

ERRLOG_STACKDUMP_SIZE

Default: 16. Include a stack dump of size ERRLOG_STACKDUMP_SIZE in log entries. Changing this to zero in the BIOS excludes the stack dump in log entries.

ERRLOG_NUM_ENTRIES

Default: 78. This is the number of entries allowed in the log buffer.

ERRLOG_USE_MESSAGE

Default: 0. Exclude error messages from log entries. Changing this to one in the BIOS includes error messages in log entries The default error handler makes no use of this feature.

8.3.4 Error Logging Functions

The run-time error logging API consists of the following functions:

errlogGetHeaderInfo	Reads error log header and formats output.
errlogGetNthEntry	Loads errLogEntry structure with the Nth entry from the error log buffer. errLogEntry is a pre-allocated global structure.
errlogGetMessage	Returns a NULL-terminated string containing the 8 byte error message in errLogEntry.
errlogFormatEntry	Returns a NULL-terminated string containing basic information in errLogEntry.
errlogFormatRegDump	Returns a NULL-terminated string containing the register dump in errLogEntry.
errlogFormatStackDump	Returns a NULL-terminated string containing the stack dump in errLogEntry.
errlogReadHeader	Reads error log header into the structure errlogInfo.
ResetErrorLog	Resets the exception and restart type counts in the error log buffer header.

8.3.5 Examples of Error Log Use

To try error logging, follow the instructions at the top of the sample programs:

samples\ErrorHandling\Generate_runtime_errors.c 

and

samples\ErrorHandling\Display_errorlog.c