Pyromaniac

Pyromaniac PRM: Program Environment (supplement for Pyromaniac)

Pyromaniac PRM: Program Environment (supplement for Pyromaniac)

RISC OS PyromaniacProgram Environment (supplement for Pyromaniac)

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:

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

OS_ChangeEnvironment 32BranchThrough0HandlerSWI &40
Install or read the Branch through 0 handler
R0=32 (reason code)
R1=Pointer to new branch through 0 handler, or 0 to read the current handler
R2=Ignored
R3=Ignored
R0preserved
R1=Previous branch through 0 handler
R2preserved
R3preserved
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.

RISC OS Pyromaniac7.08
Supported
OS_ChangeEnvironment 33CommandLineAreaSWI &40
Set or read the area used for the command line
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
R0preserved
R1preserved
R2=Previous command line buffer length
R3=Previous command line buffer address
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to read or update the address and size of the area of memory used to store the command line buffer.

RISC OS Pyromaniac7.00
Supported
OS_ChangeEnvironment 34ExceptionDumpRegionSWI &40
Set or read the area used to store memory around the faulting instructions
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
R0preserved
R1preserved
R2=Previous exception dump region size
R3=Previous exception dump region buffer
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to read or update the address and size of the area of memory used to instructions around the last exception.

RISC OS Pyromaniac7.60
Supported
OS_PlatformFeatures 64DescribeCPURegistersSWI &6D
Describe CPU architecture and register layout
R0=64 (reason code)
R0=Pointer to a static block describing the CPU register layout
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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:

OffsetContents
0

Architecture identifier:

ValueMeaning
0ARM 32 bit (A32)
1ARM 64 bit (A64)
2x86 64 bit (x86-64)
3Thumb
otherReserved for future expansion
4Minimum instruction length in bytes
8Maximum instruction length in bytes
12Total 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:

OffsetContents
0

Definition type and identifier:

Bit(s)Meaning
0-23Register 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.
24-300 (definition type: register)
31Clear:Always clear (a set bit indicates the end of the list)
4Offset from the start of the header to the name of this register
8Offset 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:

Bit(s)Meaning
0-11size of register value in bits
12-15

register type:

ValueMeaning
0general purpose register
1stack pointer
2link register
3program counter
4state flags
5-15reserved for future use
16-23bit alignment of register value (for example, 0 for byte alignment, 2 for 4 byte (word) alignment, 4 for 16 byte alignment)
24-31Reserved, must be zero

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:

OffsetContents
0

Definition type and identifier:

Bit(s)Meaning
0-7Base bit number within the flags register (base bits may be 0 to 255)
8-21Value described in this entry (if bit 23 set), or 0 (if bit 23 clear)
22Clear: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.
Set:Indicates that there are 'value' entries for this field follow this entry
23Clear:Indicates that this entry is the name of the field
Set:Indicates that this entry is an enumerated value of the field
24-301 (definition type: flag)
31Clear:Always clear (a set bit indicates the end of the list)
4Offset from the start of the header to the name of this flag's name or enumerated value
80 (has no meaning in this definition type)
12

Flags for register purpose:

Bit(s)Meaning
0-7size of field value in bits
8-31Reserved, must be zero

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

RISC OS Pyromaniac7.55
Supported