This chapter documents the changes to the program environment for RISC OS Pyromaniac.

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.

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 . This new SWI describes the architecture of the system, the instruction lengths, and the layout and size of registers used by the system.

The format of the exception register area is the same as the callback handler register buffer.

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.

Under RISC OS Classic, the command line buffers were fixed in memory. When an 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.

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:

PC at the time of the exception. If this does not match the exception dump, the data in the block is not valid. Base address of the memory region which follows. Size in bytes of the memory region which follows. 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.

32 (reason code)

Pointer to new branch through 0 handler, or 0 to read the current handler

Ignored

Previous branch through 0 handler

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.

33 (reason code)

Ignored

Size of the command line buffer, or 0 to read the current command line size

Pointer to the command line buffer, or 0 to read the current command line buffer

Previous command line buffer length

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.

34 (reason code)

Ignored

Size of the exception dump region buffer, or 0 to read the current size

Pointer to the exception dump region buffer, or 0 to read the current buffer

Previous exception dump region size

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.

64 (reason code)

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:

Architecture identifier:

ARM 32 bit (A32) ARM 64 bit (A64) x86 64 bit (x86-64) Thumb Reserved for future expansion

Minimum instruction length in bytes Maximum instruction length in bytes 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:

Definition type and identifier:

Register identifier. This is a unique identifier for each register value. Values 0-16 are defined to be the registers for Aarch32, plus the CPSR. Other values may be used for different architectures. 0 (definition type: register) Always clear (a set bit indicates the end of the list)

Offset from the start of the header to the name of this register Offset from the start of the register dump to the register data, or -1 if register is not present in the register dump

Flags for register purpose:

size of register value in bits

general purpose register stack pointer link register program counter state flags reserved for future use

bit alignment of register value (for example, 0 for byte alignment, 2 for 4 byte (word) alignment, 4 for 16 byte alignment)

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:

Definition type and identifier:

Base bit number within the flags register (base bits may be 0 to 255) Value described in this entry (if bit 23 set), or 0 (if bit 23 clear) Indicates that no (more) 'value' entries for this field follow this entry. If this is the name of the field, it indicates that there are no values preset. If this is a value of the field, it indicates that this is the final value of the enumeration. Indicates that there are 'value' entries for this field follow this entry Indicates that this entry is the name of the field Indicates that this entry is an enumerated value of the field 1 (definition type: flag) Always clear (a set bit indicates the end of the list)

Offset from the start of the header to the name of this flag's name or enumerated value 0 (has no meaning in this definition type)

Flags for register purpose:

size of field value in bits

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).