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.
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.
This document describes the side effects of the implementation of the BTS chain used by modern versions of RISC OS.
Technical Details
Stack usage
The SVC and IRQ stacks contain a word which is used to point to the head of the BTS chain. The SVC stack contains a word which is used as the head of the BTS chain itself. These words are stored at the base of the stack. This means that the 4 words at the base of the SVC and IRQ stacks are reserved for system purposes.
The use of these words on the SVC stack is as follows:
| Offset | Name | Contents |
|---|---|---|
| 0 | C library offset | APCS module C library static data offset |
| 4 | User static offset | APCS module user static data offset |
| 8 | Chain pointer | Pointer to head of BTS chain |
| 12 | Chain head | Head of BTS chain |
On the IRQ stack the use of the words is as follows:
| Offset | Name | Contents |
|---|---|---|
| 0 | Reserved | Reserved |
| 4 | Reserved | Reserved |
| 8 | Chain pointer | Pointer to head of BTS chain |
| 12 | Reserved | Reserved |
Because BTS structures are stored within the stack, the amount of space used by routines will be changed. Most operations will be unaffected as the space requirements for BTS are not great compared to many component uses of the stack.
Similarly, the presence of BTS structures on the stack means that previous attempts to access data stored above the entry point on the stack, such as the SWI or IRQ entry parameters or similar, will fail. Such behaviour is strongly discouraged where it is reliant on internal behaviour within components which are outside the author's control.
Aside from following the path of control between components, the stack content above the entry should be considered private except where pointers are passed to structures which have been constructed upon the stack.
Chain and stack corruption
During the operation of the BTS system the operations will, where possible, check for corruption of the internal BTS structures. This is achieved by the 'return' from a BTS-active function checking that the head of the chain and the current stack pointer being the same. Where this is not the case there are 3 possible failures which could have taken place:
- Corruption of the BTS chain head value
- Corruption of the BTS structure within the stack
- Stack imbalance
All 3 failures appear identical to the checks and will be reported in the same way. Under development versions of the Kernel, this was reported as a branch through zero. The failure is reported through an undefined instruction (&17FFFFFE) which is trapped by the Kernel undefined instruction handler. The undefined instruction handler converts this into a report that the system stack has become corrupt. It is reported as a hardware error, number Error_SystemStackCorrupt.
Error Messages
Reported as a hardware error when the Kernel undefined instruction handler traps the instruction &17FFFFFE, which a BTS-active function executes on return if the head of the BTS chain and the stack pointer disagree. This indicates corruption of the BTS chain head, corruption of a BTS structure within the stack, or a stack imbalance.