|
Back Trace Structure Dump tool
Introduction
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.
Output
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>
<backtrace>
<cmhg-register-set>
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.
<cmhg-register-set>
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.
<decoded-content>
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
dumps.
<hex-value> Value of this register in the register-set
<decoded-content>
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
<instruction-set>
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
<condition-flags>
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
area.
<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' |
|
![[Select]](../imgs/seldoc.png)
