Back Trace Structure Dump tool


The Back Trace Structure (BTS) chain is a feature provided by some Kernels and components to allow failures within the system to be diagnosed. Usually this is most useful during development, but it is envisaged that support will remain within the distributed release systems. The implementation of the BTS is not addressed here.

There are three categories of Kernel :

  • BTS-unaware Kernels - these are Kernels which know nothing of BTS and upon which BTS-active components will FAIL. All Kernels prior to 7.94 are BTS-unaware.
  • BTS-aware Kernels - these are Kernels which know that BTS is available to developers and will provide the necessary support for it. However, they do not include the BTS details for the kernel operations themselves. Thus only client-provided BTS details will be provided. All Kernels from 7.94 onward are BTS-aware.
  • BTS-active Kernels - these are Kernels which record details using the BTS for their own activities. Kernels after 7.94 can be optionally built with this option.

The BTSDump tool can, therefore, be used on BTS-aware and BTS-active Kernels. It will report a failure on BTS-unaware Kernels.


The tool provides a number of command line switches to determine the amount of information which is decoded and displayed. The information is displayed in a standard manner:

  • The top of the output contains the most recent event.
  • The bottom of the output contains the initiating event.
  • Related sections are indented to similar levels.
  • Hexadecimal values, such as addresses, are displayed preceded by an ampersand ('&') or '0x' sequence.
  • Decimal values, such as indices, are displayed unprefixed.
  • Register names are displayed together with the APCS-R binding where appropriate. (APCS-A is not used within the BTSDump tool).
Reading the output

It is recommended that the trace output be read from the bottom toward the top. This will provide an indication of the path through the operating system and extension components. Each un-indented line indicates a BTS marker which has been decoded.

The BTS marker decoding has a standard format :

    <BTS-adddress> (<stack>) : <type>    <arguments>        {<region> }

<BTS-address>  Describes the place on the stack (IRQ or SVC) at which the
               BTS was placed
<stack>        The stack type on which it was placed, which implies the
               processor mode at that time.
<type>         The general operation type which is being recorded.
<arguments>    Describes the operation further, usually indicating the
               parameters in force at the time, any source location and
               any destination location.
               Source locations are usually described by the phrase 'called
               by <addr>', and indicate how the control reached this point.
               Destination locations are usually described by the phrase
               'called <addr>', and indicate where control is going after
               leaving this point.
<region>       If present, indicates a named region within which the source
               and destination reside. The source will be listed first if
               present and a named region is known. The destination will
               be listed second if present and a named region is known.
               the destination is always preceded by a '->' to distinguish
               it from the source.
               If the destination has been given an address which has a
               function signature, the name will be given, preceded by an

For example, the following pair of lines may have been displayed :

&01c07ef0 (SVC) : Vector &04      called &03824a30
                                 {- > Module UtilityModule Code=RdchV_Code}
&01c07f14 (SVC) : SWI &20004        called by &023e3770
                                       {lineeditor Code}

This indicates that a SWI &20004 was called by the LineEditor module, from &023e770. Subsequently this resulted in a vector call being made to vector &04, which was then dispatched to &3824a30. This was within the UtilityModule, and refers to the named function 'RdchV_Code'.

APCS backtraces

Certain types of BTS may have recorded information about the APCS stack frame at the time of the operation. Details about the APCS stack frame will be given below the BTS marker which recorded it. This indicates that it describes the state before the BTS marker was placed on the stack. By default, the C backtrace is not displayed and a reminder will instead be shown :

   C-environment present, but not displayed (use -c)

When enabled the APCS (C language, usually) backtrace will be displayed. This will be surrounded by two lines describing the APCS state, in the form:

   Leave C-environment: FP was <fp-on-leaving>
   Enter C-environment: SP was <sp-on-entry>, PC was <caller>  {<region> }

<fp-on-leaving>  Gives the frame pointer value that was stored with the BTS,
                 and which was the starting point of the backtrace.
<backtrace>      Describes the APCS function calls which were active at the
                 time of the fault. See below for more details.
                 If present, indicates that the register set passed in to
                 the veneer which was entered is available. Not all entry
                 sequences are able to be decoded by the BTSDump, but a
                 best-effort will be made. By default the register set will
                 not be displayed.
<sp-on-entry>    Gives the stack pointer value at the time of the entry into
                 the APCS-tracing environment.
<caller>         Indicates the caller which initiated the transition into
                 the APCS-tracing environment.

The backtrace itself consists of a number of grouped function descriptions. Because the details about the parameters are much greater than those for the BTS the description of a single function spans multiple lines. It is important to recognise that the backtrace dump differs from the standard SharedCLibrary backtrace in that arguments for functions are displayed after the functions rather than before them. Conceptually this is because the arguments are set up before the function call is made. Visually, this makes it much easier to read.

The format of the function descriptions is simpler than that of the BTS markers :

   <address>: <function-name>
                 Arg <arg-number>: <hex-value> <decoded-content>

<address>        Describes the point at which control left this point
<function-name>  Describes the function which was called to reach this
                 point. <address> may lie outside the named function if
                 the function called other functions which do not place
                 frame information upon the stack.
<arg-number>     The argument number for this function. Not all function
                 arguments may be determined by the backtrace. In
                 particular, functions with more than 5 arguments will
                 most likely not be recognised.
<hex-value>      The value of the argument. On rare occassions this may
                 consist of multiple values, such as when the argument
                 is a double.
                 The content of the argument will be guessed at by the
                 backtracer. String pointers are usually recognised,
                 although only the first 16 characters will be displayed.
                 Signatured function pointer will be recognised.
                 Word-aligned pointers to valid memory will have the
                 first four words displayed.

For example, the following lines might be displayed :

  385dc70: mm_lookup_by_ftname
           Arg 1: 0xffffffff -1
           Arg 2: 0x00000001 1
  3b8c43c: mm_translate
           Arg 1: 0x01c07f9c 29392796 -> [0x00000001] [0xffffffff] [0x00000001] [0xffffffff]

This indicates that the 'mm_translate' function was called with a single argument. It was probably a pointer to some data, of which the first four values were 1,-1,1,-1.

This then called the 'mm_lookup_by_ftname' function, passing two parameters, a -1 and a 1.

Register sets

Some BTS types, for example the 'Exception' type, as well as the APCS backtrace, can display a 'register set'. The meaning of these registers is dependent on where it is being displayed. For the Exception type, the register set indicates the registers which were in place at the time of the exception. For the CMHG register set, it indicates the 10 registers which were passed to the entry point, and which may have been subsequently updated.

By default, register sets are not displayed and a reminder notice is instead shown. The register dump takes a simple form:

    <register>=<value> <hex-value> <decoded-content>

<register>       Names the register, or the PSR in the case of full register
<hex-value>      Value of this register in the register-set
                 As described above

In the case of the PSR, the decoded content will describe the flags which are set and the mode of the processor :

     <mode> <instruction-set> <mask-flags> <condition-flags>

<mode>           Gives the name of the mode, or its binary equivalent
                 Describes the instruction set in force - ARM, or Thumb.
<mask-flags>     Indicates which masking flags are set, lower case indicating
                 an unset flag, upper case indicating a set flag:
                     i  IRQ
                     f  FIQ
                 Indicates which condition flags are set, lower case
                 indicating an unset flag, upper case indicating a set flag:
                     v  Overflow
                     c  Carry
                     z  Zero
                     n  Negative

Disassembly dumps

The BTS types which include a source location can display a disassembly dump of the preceding instructions prior to the operation. By default these are disabled and a reminder will be shown instead. The disassembly will be familiar to most developers :

    <address> : <ascii> : <hex-value> : <disassembly>

<address>        Gives the address of this value and instruction
<ascii>          Shows the ASCII representation of the 4 bytes which make up
                 the hex-value
<hex-value>      The value of the word at the address
<disassembly>    The ARM disassembly of the code at that address

Note: Thumb is not supported yet; not all interfaces provide a PSR to be able to select the correct mode for this. And of course, RISC OS does not function in Thumb mode.

The disassembly may include indications of function signatures, and branching instructions may give the name of the function if it is present.

Interactive interface

The tool may be invoked with an interactive interface. In this mode, the system can be examined by commands issued to the tool. The commands can be listed typing 'help'. Most commands supply syntax messages when they are invoked incorrectly. The current commands available are :

dump Dump the BTS chain
processor Display processor details
osversion Display OS version details
time Display time of failure
help Display list of commands
quit Exit the shell
disassemble Disassemble a chunk of memory
dis (as above)
memoryi (as above)
areas Display areas list
savearea Force the saving of an area to a file
modules Display modules list
savemodule Force the saving of a module to a file
knownmemory Display known memory regions
stacks Display stack details
platform Display platform details
version Display command version
whereis Locate an address
option Set options

The interactive interface is most useful when dumps have been obtained from remote systems to display details about the environment in which the failure took place.

Modules list

The modules list is recorded both to ensure that an accurate record of the version numbers is retained and to identify the location in memory of the code in case it is referenced. Each line of the modules definition follows the following format :

   <title>    <code-range> <workspace-range> <help-text>

<title>            The module title
<code-range>       The range of the module code
<workspace-range>  If given, defines the range of the workspace as read
                   from the private word.
<help-text>        The module help text, which includes the version and date

Areas list

The areas list contains the named areas on the system (Dynamic Areas). Each area has a record of the extent which is allocated and flags, as well as the total memory covered by the area. This description takes one of two forms, the first of which is the most common, and the second is only used for the lower half doubly mapped dynamic areas :

start>            The start address of the dynamic areas.
<mapped-end>       The limit of the assigned memory for the dynamic area
<maximum-end>      The full extent of the dynamic area.
<minimum-start>    The full lower extent of the doubly mapped dynamic area.
<mapped-lower>     The start of the lower mapped region of a doubly mapped
                   dynamic area.
<name>             The dynamic area name.
<access>           Indicates the type of access which is possible on the
<flags>            Specifies any special flags that the area has.

The access attributes for the area are described in terms of the user-mode
access which is possible:
  User R/W         All access is allowed
  User R/O         User mode writing disallowed
  User fault       User mode access (read or write) disallowed
  Unmapped         All access disallowed (both user and privileged)
                   because no memory is mapped

The flags indicates certain special flags that the area has:
  Double-lo        The area is doubly mapped, and this is the lower section.
  Double-hi        The area is doubly mapped, and this is the upper section.
  Sparse           The area is sparse. The details for sparse-mapped
                   areas may not be accurate.
  Heap             The area contains an OS_Heap managed by OS_DynamicArea.
  Physical         The area contains physically mapped memory.
  Abortable        The area can handle aborts.
  Domain           The area has a domain allocated to it.

Preserving a record of state

The BTSDump tool may be used to write a record of the system state after an abort has happened. This record can then be transmitted to other developers, or recorded for later diagnosis. To do this, the tool records, as it performs and displays the backtrace, the accesses it makes to memory. This record, the memory it refers to, and some system information can then be written to a file. In order that the most information is recorded, it is necessary to enable as many of the options as possible. All the features which are available during direct debugging of a 'live' system are available when displaying the preserved record.

Command line options

The command line options allow the operation of the tool to be modified. Most enable options which would otherwise clutter the output on a 'live' system. The options available for the tool are :

-h Display this help message
-a Enable all options
-c Enable the processing of APCS stack frames
-r Enable the processing of register details
-d Enable disassembly of surrounding regions
-q Quieten some reminder messages
-i Launch interactive shell
-e Execute a command without invoking the shell
-W Write a record of the details for later playback
-R Read a recorded list of the details written by -W

The recommended command for recording the system's state before sending the file to another user would be :

 *BTSDump -aW <filename>

This enables all the features and writes the results to a file.

Private use BTS types, and extending BTSDump

The BTSDump tool can be used to interpret any correctly formed BTS details. The tool knows only about the types which were registered and in use when it was built. Unknown types will be displayed using a generic form indicating the type number and any known parameters. This description can be replaced by setting a system variable to indicate the use of new BTS types. For each unknown type, a system variable will be looked up in the form 'BTS$Type_#####' where '#####' indicates a 5-character, 0 padded, hexadecimal type number. The value of this variable will be interpreted and displayed. In order to align the text sensibly in the output, a vertical bar ('|') is used to separate the type name from its arguments. The '%' character is used to escape a special value which is read from the arguments.

The '%' character is followed by an single character argument number (0-9) to which this special value relates. This may, optionally, be followed by a number (1-9) indicating the number of characters of padding which should be used to display the value. This is then followed be the type of the argument which is usually single character.

More succinctly, the special values take the following form :

   %<argument>[<pad>]<type>  : Display special value
   <argument> is the argument number (0-9)
   <pad> is an optional field padding
   <type> is the type of argument being displayed

The types of arguments which can be interpreted are :

     x = a hex value
     s = a control-terminated string
     P = a PSR value
     d = a decimal value
     f = the address of the caller
         (this will be used as a means for providing a caller disassembly,
         and described within the <region> in the output)
     t = the address of the callee
         (this will be described within the <region> in the output)
     [ = an enumeration of named types (see below)
     r = a register dump at the given argument offset (r0-r15)
         (this may be followed by a string enclosed in [] giving details
         about the dump)
     R = a register dump at the given argument offset (r0-r15, PSR)
         (this may be followed by a string enclosed in [] giving details
         about the dump)

The enumeration set consists of a list of comma separated values which the argument value means, each of which is associated with an incrementing value (starting at 0). The value may be prefixed by a hex value and an '=' character to explicitly state the value associated with the given name. Enumerations are usually used to describe reason codes. For example, the Code variable type uses '%0[read,write]' to indicate that a value of 0 means 'read' and a value of 1 means 'write'. See the FileSwitch type form more details.

When assigning values to variables it should be remembered that that '|' character in a *Set command must be escaped as '||' to avoid GSTrans expansion, and within Obey files, the '%' character must be escaped as '%%' to avoid argument substitution.

Built in BTS type definitions

The BTSDump tool has a number of built in type definitions, as described in the above section. As a reference for the present commands, and to provide examples for the above description format, the current definitions are :

00002 Exception|called by %1f, CPSR %0P%2R[Exception]
00003 IRQ device %0d|when at %1f, called %2t
00004 SWI %05x|called by %1f
00005 SWI %15x|called %0t
00006 Vector %12x|called %0t
00007 Transient-CB|called %0t, r12=%1x
00008 Ticker event|called %0t, r12=%1x
00009 Service %16x|called %2t, r0=%1x
0000A Event
0000B Code-var %0[read,write]|called %1t
0000C Aborting|called by %1f, CPSR %0P
0000D Abort trap|flags %02x, addr %1x+%22d, called %3t, r12=%4x
0000E Module init|called %1t, r11=%2x, title='%0s'
0000F Module final|called %1t, r11=%2x, title='%0s'

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015