Debugger Exception Dumps (changes)

Showing changes from revision #2 to #3: Added | Removed | Changed

Debugger

» Exception Dumps

Overview

Exception dumps are a new feature introduced with version 1.92 of the Debugger module. The primary aim of an exception dump is to collect an accurate snapshot of the system state at the time of an unhandled exception or other serious error (e.g. data abort). The secondary aim is for the exception dump to contain enough information that a developer who does not have access to the originating machine will be able to easily identify the function call and parameters that caused the error.

Quick start guide

Entering the following two commands will enable output of annotated exception dumps to the file $.excdump:

*Set Debugger$AnnotatedFile $.excdump
*Set Debugger$DumpOptions -file annotated

Details

The exception dump implementation offers the following features:

• Capture of the following machine state:
  • Capture of the core ARM registers at the time of the exception (R0-R15 and CPSR, and banked registers for USR, SVC, IRQ, ABT and UND modes)
    • FIQ registers are not currently captured
  • Full capture of the default IRQ, SVC, ABT and UND mode stacks
    • FIQ mode has no default stack and is not captured
    • Auxiliary SVC stacks (e.g. as used by RTSupport) are not currently captured
  • Capture of the error block that’s associated with the exception
  • Capture of important kernel workspace values, such as the current IRQsema value
• The ability to output the captured dump in either raw (binary) or annotated (text) format
  • The annotated output makes use of additional machine state in order to produce much richer output than that which is currently available in the binary format. For example, the annotated output will attempt to label key code addresses by the module and function they belong to, and it will also include a partial USR mode stack dump.

Note that exception dump functionality is considered to be a work-in-progress, and so its function or the method of configuration may change in future OS versions.

Configuration

Exception dump collection and processing currently defaults to disabled on machine startup. The following system variables can be configured in order to enable it.

Debugger$DumpOptions

This is a code variable which acts as the primary configuration interface. When set to an empty string, the Debugger will not be registered with SeriousErrorV and there will be no effect on the processing of exceptions/serious errors by the kernel. When set to a valid non-empty value, the Debugger will register with SeriousErrorV and the appropriate features will be enabled.SeriousErrorV and the appropriate features will be enabled.

The basic syntax of the variable is that of a space-delimited sequence of options and values, similar to the way command line arguments are specified for programs. The following options are supported:

Valid formats are raw and annotated, for the raw (binary) and annotated (text) forms respectively.

File output will cause the dump files to be saved to files on disc; the filenames must be specified in the Debugger$RawFile and Debugger$AnnotatedFile variables as appropriate.

HAL output is sent to the HAL via HAL_DebugTX, and so will typically require a connection to a remote machine via a serial cable. This allows collection of logs in situations where the filesystem is unusable. Also note that raw output via the HAL is currently sent as a hex dump rather than true binary.

Any combination of output destinations and formats can be enabled at the same time. For example, -file raw,annotated -hal raw,annotated will enable all output destinations and formats. Raw output is produced before annotated output, so if the annotation crashes then you will still have at least some information to go by.

Debugger$DumpOptions can also be set to a value of -none, which will cause the Debugger to collect exception dumps but not process them. This allows other software such as ZeroPain to request manual processing via the SeriousErrorV_CustomReport reason code.

Debugger$RawFile

This must be set to the filename to save raw binary dumps to when the -file raw option is used.

Debugger$AnnotatedFile

This must be set to the filename to save annotated text dumps to when the -file annotated option is used.

Events that cause exception dumps to be collected

Within the kernel, unhandled data aborts, prefetch aborts, or undefined instructions for which a serious error is about to be raised will result in calls being made to SeriousErrorV. If exception dump processing is enabled in the Debugger then the exception dumps will be collected and output. A branch through zero will also trigger an exception dump via the same mechanism.SeriousErrorV. If exception dump processing is enabled in the Debugger then the exception dumps will be collected and output. A branch through zero will also trigger an exception dump via the same mechanism.

Note that if a program deliberately triggers an exception with the intent of catching it via an Error Handler, this will result in a “false-positive” exception dump being produced.

The ZeroPain module also contains logic to allow it to manually trigger the collection and processing of an exception dump whenever a zero page access is caught. This involves manually calling SeriousErrorV from ABT mode, something which is not currently supported by standard OS APIs (using OS_CallAVector would result in a switch to SVC mode, potentially overwriting important SVC stack content or triggering a stack overflow). Developers who are interested in triggering exception dumps from their own code are encouraged to get in touch with ROOL so that official APIs can be devised.

File formats

Please see Raw Exception Dumps and Annotated Exception Dumps for details of the file formats.