![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and Overview
This chapter documents the changes to the program environment for RISC OS Pyromaniac.
Technical details
Largely, the program environment in RISC OS Pyromaniac is as documented within the Program Environment Chapter. However, certain interfaces are slightly different to make extensions to the system simpler.
Handler 7: Callback handler
On 26bit systems, the register buffer in the callback handler is 16 words (64 bytes) long. This area stores the registers at the time of a call to the callback (threading back to user mode).
On 32bit systems, the register buffer is 17 words (68 bytes) long. This is the same layout as the 26bit system, but with the value of the CSPR in the final word.
The size of the exception register area, and its layout is described by SWI OS_PlatformFeatures 64. This new SWI describes the architecture of the system, the instruction lengths, and the layout and size of registers used by the system.
Handler 13: Exception register area
The format of the exception register area is the same as the callback handler register buffer.
Handler 32: Branch through 0 handler
Under RISC OS Classic, the handling of a branch through 0 (calling address 0) was performed within the Kernel as an implicit part of abort handling. For RISC OS Select 3, the handling of branch through zero moved to the undefined instruction handler. In either case, the only action possible was for an error to be raised.
Under RISC OS Pyromaniac, the Branch through 0 handler is called when code is executed at address 0. This handler stores registers in the abort area, just as the abort handler would. The default action for this handler is to raise the 'Branch through 0' error.
Handler 33: Command line area
Under RISC OS Classic, the command line buffers were fixed in memory. When an SWI OS_WriteEnv is issued the command line supplied is copied into the Kernel command line buffer. The length of this buffer was extended in RISC OS 4, but there was no defined mechanism to read the length of the buffer used by the system.
The buffer length in RISC OS 4 and later is 1024 bytes. Prior to RISC OS 4, the length was 256 bytes.
Under RISC OS Pyromaniac, the area that the Kernel will use to store the command line is a part of the program environment, and the size of the buffer is able to be read or changed. The handler buffer, supplied in R3, reports the command line buffer location. The size of the buffer is reported in R2.
The default buffer length under RISC OS Pyromaniac is 1024 bytes but is configurable through the system configuration.
Handler 34: Exception dump region
It can be useful to know what was being executed at the time of an exception. The exception dump area records the registers at the time of the exception, but what was actually being run is not clear. The exception dump region will be written to at the time of the exception, with a copy of the data that was written. If the memory is subsequently erased, or memory moved around, this data will have been preserved in the exception area.
The format of the block is:
| Offset | Contents |
|---|---|
| 0 | PC at the time of the exception. If this does not match the exception dump, the data in the block is not valid. |
| 4 | Base address of the memory region which follows. |
| 8 | Size in bytes of the memory region which follows. |
| 12 | Data from the base address. |
The default dump region size under RISC OS Pyromaniac is 21 words; 17 words before, and 3 after the faulting instruction.
SWI calls
| R0 | = | 32 (reason code) |
| R1 | = | Pointer to new branch through 0 handler, or 0 to read the current handler |
| R2 | = | Ignored |
| R3 | = | Ignored |
| R0 | preserved | |
| R1 | = | Previous branch through 0 handler |
| R2 | preserved | |
| R3 | preserved | |
This SWI is used to read or update the address of the handler used when a call is made to address 0.
The handler will be entered in SVC mode. The registers will be preserved from the time of call. This means that the banked SVC registers will be in the state they were when the call was made, even when called in USR mode. The registers and CPSR at the time of the call will be stored in the Exception registers area.
| R0 | = | 33 (reason code) |
| R1 | = | Ignored |
| R2 | = | Size of the command line buffer, or 0 to read the current command line size |
| R3 | = | Pointer to the command line buffer, or 0 to read the current command line buffer |
| R0 | preserved | |
| R1 | preserved | |
| R2 | = | Previous command line buffer length |
| R3 | = | Previous command line buffer address |
This SWI is used to read or update the address and size of the area of memory used to store the command line buffer.
| R0 | = | 34 (reason code) |
| R1 | = | Ignored |
| R2 | = | Size of the exception dump region buffer, or 0 to read the current size |
| R3 | = | Pointer to the exception dump region buffer, or 0 to read the current buffer |
| R0 | preserved | |
| R1 | preserved | |
| R2 | = | Previous exception dump region size |
| R3 | = | Previous exception dump region buffer |
This SWI is used to read or update the address and size of the area of memory used to instructions around the last exception.
| R0 | = | 64 (reason code) |
| R0 | = | Pointer to a static block describing the CPU register layout |
This SWI is used to read a table describing the layout of registers within the register dump area. The layout has changed through different iterations of RISC OS, and it has been necessary to be aware of the system configuration to infer the layout of registers in the register dump areas. This SWI describes the layout in an architecture agnostic manner, to allow code to determine that system layout programatically.
The information returned in this block may be used by the Debugger module to describe the layout of recent abort.
The structure returned contains information about the CPU architecture, instruction lengths, the length of the register dump area, and details of the layout of the registers within the area. The structure has a header with the following layout:
| Offset | Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Architecture identifier:
| ||||||||||||
| 4 | Minimum instruction length in bytes | ||||||||||||
| 8 | Maximum instruction length in bytes | ||||||||||||
| 12 | Total length of the register dump block |
This information should allow diagnostic tools to decide whether and how to debug code on the system. It is followed by repeated entries which describe the content of the register dump block. Each entry is 16 bytes long. The entries describe features of the register block. There are currently 2 definition types defined. The list is terminated by a word which contains -1 as the first word of the entry.
Registers within the dump block are defined with an entry for type 0:
| Offset | Contents | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Definition type and identifier:
| |||||||||||||||||||||||||||||
| 4 | Offset from the start of the header to the name of this register | |||||||||||||||||||||||||||||
| 8 | Offset from the start of the register dump to the register data, or -1 if register is not present in the register dump | |||||||||||||||||||||||||||||
| 12 | Flags for register purpose:
| |||||||||||||||||||||||||||||
Registers which contain system state in flags, which have register type 4, may be further defined with entries which immediate follow them. The entries may describe the layout of the flags, identified as a type 1 definition:
| Offset | Contents | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Definition type and identifier:
| |||||||||||||||||||||||||||
| 4 | Offset from the start of the header to the name of this flag's name or enumerated value | |||||||||||||||||||||||||||
| 8 | 0 (has no meaning in this definition type) | |||||||||||||||||||||||||||
| 12 | Flags for register purpose:
| |||||||||||||||||||||||||||
Flag values may be described in diagnostic software by interpreting this table. Some fields which have multiple values may be enumerated to give names to the values of the field. They will be described first as a field name (bit 22+23 set to 00), followed by 0 or more enumerated values (bit 22+23 set to 11), terminating with a final enumerated value (bit 22+23 set to 01).