ARM Remote Debug Protocol
=========================


Introduction
------------

The Remote Debug Protocol (RDP) is the communication protocol used between the 
ARM Symbolic Debugger, <armsd>, and a remote debugee, via a debug monitor or 
controlling debug agent. Usually, the RDP is used via <stub> functions 
implementing the Remote Debug Interface (RDI), (for details see "<ARM Remote 
Debug Interface>").

The RDI gives the ARM symbolic debugger (<armsd>) core a uniform way to 
communicate with:

 *  a controlling debug agent or debug monitor linked with the debugger;

 *  a debug agent executing in a separate operating system process;

 *  a debug monitor running on ARM-based hardware accessed via a communication 
    link.

 *  a debug agent controlling an ARM processor via hardware debug support.

The first structure arises in the variant of <armsd> which is linked with ARM's 
standard ARM emulation environment (for the PC- and Sun-hosted 
cross-development variants of <armsd>), and in the self-hosted, single 
address-space variant of <armsd> (for Acorn's RISC OS operating system). No 
direct use of the RDP is involved.

The second structure would arise in an ARM-Unix-hosted variant of <armsd>, if 
<armsd> and the ARM emulator (the <ARMulator>) were run in separate Unix 
processes (perhaps on separate machines). In the second case, the <RDI> would 
consist of two stubs using Unix's remote procedure calls to effect the 
inter-process message passing. Again, no direct use of the RDP is involved.

The third and fourth structures arise when <armsd> is used to control a 
debuggee, executing on ARM-based hardware (for instance on the <Platform 
Independent Evaluation (PIE)> card) connected to <armsd>'s host via a hardware 
debugging channel, (for instance via RS232 as used on the <PIE> card).


Terminology
-----------

PC and <pc> mean <program counter>: the address of the currently executing 
instruction in the debuggee.

An ARM processor can be configured to operate with either <little endian> 
memory (the least significant byte of a word has the lowest address of any byte 
in the word), or <big endian> memory (the most significant byte of a word has 
the lowest address of any byte in the word). The <endian-ness> of a memory 
system and processor configuration is also called its <byte sex>.

In the following sections, pseudo-C declarations are used to specify the 
content of messages and the types of arguments to message functions. In these 
declarations:

 *  <byte> means an 8 bit unsigned value; 

 *  <word> means an unsigned 4-byte value, transmitted least significant byte 
    first (little endian)

The types <bytes> and <words> (plural) mean, respectively, a sequence of bytes 
and a sequence of words.

Values enclosed in { and } are present only in some contexts, as clarified by 
the explanatory text.

Each message of the RDP is encoded as a single function byte, followed 
immediately by its arguments, if any.

The return message acts as an acknowledgement as well as returning values. If 
the request is meaningful and successful, a zero status byte is returned, 
possibly preceded by requested data.

The reply to an unsatisfied request (failed request) is always padded to the 
same length that it would have had, if it had been successful. Then follows a 
non-zero error code byte (see "<Error Codes>").

The RDP is not an entity fixed for all time.  As it evolves, new levels of 
specification are added and within any level of specification there are 
implementation options. This approach is taken so that a variety of minimal 
debug monitors and controlling debug agents can be accommodated without 
excessive overhead and so there can be good compatibility between debuggers and 
debug monitors released at different times. As a result, a debugger using the 
RDP must <negotiate> to establish its debuggee's capabilities and must not use 
capabilities its debuggee does not have. These issues are highlighted in the 
following sections.


Message Summary
---------------

The debugger to debuggee messages are:

    Message Name                    Hexadecimal Function Code

    Open and/or Initialise          00

    Close and Finalise              01

    Read Memory Address             02

    Write Memory Address            03

    Read CPU State                  04

    Write CPU State                 05

    Read Co-Processor State         06

    Write Co-Processor State        07

    Set Breakpoint                  0A

    Clear Breakpoint                0B

    Set Watchpoint                  0C

    Clear Watchpoint                0D

    Execute                         10

    Step                            11

    Info                            12

    OS Operation Reply              13

    Reset                           7F

The debuggee to debugger messages are:

    Message Name                    Hexadecimal Function Code

    Stopped notification message    20

    OS Operation Request            21

    Fatal protocol error            5E

    Return value/status message     5F

    Reset                           7F


Debugger to Debuggee Messages
-----------------------------


Open and/or Initialise Message (00)
...................................

    Open(byte type, word memorysize {,byte speed})
    return(byte status)

Upon receipt of this message a debuggee should prepare itself for an imminent 
debugging session, bootstrapping and/or initialising itself. This message will 
always be the first sent. If for some reason initialisation is impossible, a 
non zero status value should be returned. The <type> argument may be used to 
distinguish between sorts of initialisation:

    bit 0 = 0:  cold start (bootstrap, initialise MMU, etc.);

    bit 0 = 1:  warm start (terminate current execution, clear all breakpoints 
                and watchpoints, etc.);

    bit 1 = 1:  reset the communication link;

    bit 2 = 0:  debugger requires little endian debuggee;

    bit 2 = 1:  debugger requires big endian debuggee;

    bit 3 = 1:  debuggee should return its sex.

The <memorysize> argument is used to specify the minimum number of bytes of 
memory that the debuggee's environment must have. A value of zero can be used 
if the debugger is not concerned with the memory size, (e.g. when the debuggee 
is running under an ARM emulator which allocates memory dynamically, as 
needed).

If bit 1 of the <type> argument is set, then a single byte specifying the debug 
channel speed must follow the <memorysize> argument. A value of zero sets the 
default speed. Other values are target dependent; see "<ARM Debug Monitor>" 
starting on page104 for possible return values.

The return value <RDIError_WrongByteSex> indicates that the debuggee has the 
opposite byte order to that requested in bit 2 of the type argument, and 
therefore the request has failed. If bit 3 of the <type> argument is set, the 
debuggee should ignore bit 2 and return a status of either 
<RDIError_LittleEndian> or <RDIError_BigEndian>.


Close and Finalise Message (01)
...............................

    Close()
    return(byte status)

Receipt of this message indicates the termination of the current debugging 
session. If for some reason the current debugging session cannot be terminated, 
then a non zero status value is returned. Only the Initialisation message may 
follow the Close message.


Read Memory Address Message (02)
................................

    Read(word address, word nbytes)
    return(bytes data, byte status {, word nbytes})

This message is a request for a transfer of memory contents from the debuggee 
to the debugger. The transfer begins at the memory location <address>, and 
transfers <nbytes> of data in increasing address order.

On successful completion, the bytes requested are returned, followed by a zero 
status value.

On unsuccessful completion, the number of bytes requested are returned (some 
are garbage padding), followed by a non-zero error code byte, followed by the 
number of bytes successfully transferred. This number can be added to the base 
address to calculate the address at which the transfer failed.


Write Memory Address Message (03)
.................................

    Write(word address, word nbytes, bytes data)
    return(byte status {, word nbytes})

This message transfers data from the debugger to the debuggee's memory. The 
<address> argument specifies the location at which the first byte of data is to 
be stored, and the <nbytes> argument gives the number of bytes to be 
transferred; there follows the sequence of bytes to transfer.

On successful completion a zero status value is returned.

On failure, a non-zero error code byte is returned, followed by the number of 
bytes successfully transferred, just as with the <Read Memory Address> message.


Read CPU State Message (04)
...........................

    ReadCPU(byte mode, word mask)
    return(words data, byte status)

This message is a request to read the values of registers in the CPU.

The <mode> argument defines the processor mode from which the transfer should 
be made. The mode number is the same as the mode number used by ARM6; a value 
of 255 indicates the current mode.

The <mask> argument indicates which registers should be transferred. Setting a 
bit to 1 will cause the designated register to be transferred.

Bit 0 of the mask word requests register 0, bit 14 the link register, and bit 
15 the Program Counter (including the mode and flag bits in 26-bit modes).

Bit 16 requests transfer of the value of the Program Counter (without the mode 
and flag bits in a 26-bit mode).

Bit 17 requests the address of the currently executing instruction (often, 8 
bytes less than the PC, because of instruction prefetching).

In 32-bit modes, bit 18 requests transfer of the CPSR; in 32-bit processor 
modes with an SPSR (non-user modes), bit 19 requests its transfer.

Bit 20 requests the transfer of the value of the flag and mode bits in a 26-bit 
mode (in the same bit positions as in register 15).

Upon successful completion, the values of the registers will be returned (the 
number depending on the number of bits set in the mask argument), followed by a 
zero status value. The lowest numbered register will be transferred first.

On unsuccessful completion, the number of words specified in the mask is 
returned, followed by a non-zero error code byte.


Write CPU State Message (05)
............................

    WriteCPU(byte mode, word mask, words data)
    return(byte status)

This message is a request to set values of registers in the debuggee's CPU.

The <mode> argument defines the processor mode to which the transfer should be 
made.

The <mask> argument is as for the <ReadCPU> message, and is followed by the 
sequence of word values to be written to the registers specified in <mask>. The 
first value is written to the lowest-numbered register mentioned in <mask>.

The status value returned will be zero if the request was successful, 
otherwise, the error will be specified, (see "<Error Codes>" starting on page
101).


Read Co-Processor State Message (06)
....................................

    ReadCoPro(byte CPnum, word mask)
    return(words data, byte status)

This message is a request to read a co-processor's internal state. Its 
operation is similar to that of <ReadCPU>, except that register values are 
transferred from the co-processor numbered <CPnum>.

The registers to be transferred are specified by the <mask> argument.

The registers transferred, and their sizes, is co-processor-specific; currently 
the following co-processors are understood:

 *  Co-processor 1 (and 2 in the case of FPA) is a floating point unit. Bits 0 
    to 7 of <mask> request the transfer of floating point registers 0 to 7; bit 
    8 requests the FPSR, bit 9 the FPCR.

 *  Co-processor 15 is an MMU, for example ARM3's or ARM600's. Bits 0 to 7 of 
    <mask> request the transfer of internal registers 0 to 7.

On successful completion, the values of the requested registers are returned 
followed by a zero status value. The lowest numbered register is transferred 
first.

On unsuccessful completion, the number of words implied by <mask> are 
transferred, followed by a non-zero error code byte.

Note that not all co-processor registers are the same size. For example, 
floating point registers are 3 words wide, but the FPSR and FPCR each occupy 
only one word.


Write Co-Processor State Message (07)
.....................................

    WriteCoPro(byte CPnum, word mask, words data)
    return(byte status)

This message is a request to write a co-processor's internal state. This 
operation is similar to that of <WriteCPU>, except that register values are 
transferred to the co-processor numbered <CPnum>. The registers to be written 
are specified by the <mask> argument.

The registers transferred, and their sizes, is co-processor-specific; currently 
the following co-processors are understood:

 *  Co-processor 1 (and 2 in the case of FPA) is a floating point unit. Bits 0 
    to 7 of <mask> request the setting of floating point registers 0 to 7; bit 
    8 requests a write to the FPSR, bit 9 a write to the FPCR.

 *  Co-processor 15 is an MMU, for example ARM3's or ARM600's. Bits 0 to 7 of 
    <mask >request the setting of internal registers 0 to 7.

The status value returned will be zero if the request was successful, 
otherwise, the error is specified, (see "<Error Codes>").

Note that not all co-processor registers are the same size. For example, 
floating point registers are 3 words wide, but the FPSR and FPCR each occupy 
only one word.


Set Breakpoint Message (0A)
...........................

    SetBreak(word address, byte type {, word bound})
    return({word pointhandle} byte status)

      or  ({word address{word bound}} byte status)

This message requests the debuggee to set an execution breakpoint at <address>. 
The least significant 4 bits of <type>  define the sort of breakpoint to set:

    0       halt if the pc is equal to <address>.

    1       halt if the pc is greater than <address>. 

    2       halt if the pc is greater than or equal to <address>. 

    3       halt if the pc is less than <address>. 

    4       halt if the pc is less than or equal to <address>.

    5       halt if the pc is in the address range from <address> to
            <bound>, inclusive. 

    6       halt execution if the pc is not in the address range
            <address> to <bound>, inclusive.

    7       halt execution if (pc & <bound>) = <address>.

At RDI/RDP specification levels 1 and above, bits 5, 6 and 7 of <type> have 
further significance.

Bit 5 of <type> set requests that the breakpoint should be conditional 
(execution halts only if the breakpointed instruction is <executed>, not if it 
is conditionally skipped). If bit 5 is not set, execution halts whenever the 
breakpointed instruction is <reached> (whether executed or skipped).

Bit 6 of <type> set requests a dry run: the breakpoint is not set and the 
<address> and, if appropriate, the <bound>, that would be used, are returned 
(for comparision and range breakpoints the <address> and <bound> used need not 
be exactly as requested). A zero status byte indicates that resources are 
currently available to set the breakpoint; <RDIError_NoMorePoints> indicates 
that the required breakpoint resources are not currently available.

Bit 7 of <type> set requests that a handle <pointhandle>  should be returned 
for the breakpoint by which it will be  identified subsequently. If bit 7 is 
set, a handle will be returned, whether the request succeeds or fails (but, 
obviously, it will only be meaningful if the request succeeds).

Bits 6 and 7 shall not be simultaneously set.

Breakpoints are unconditional: execution halts when the breakpoint is reached, 
no matter what the condition field of the breakpointed instruction.

Upon successful completion a zero status byte is returned.

On unsuccessful completion, a non-zero error code byte is returned.

If the request is successful, but there are now no more breakpoint registers 
(of the requested type), then the value <RDIError_NoMorePoints> is returned.

If a breakpoint is set on a location which already has a breakpoint, the first 
breakpoint will be removed before the new breakpoint is set.


Clear Breakpoint Message (0B)
.............................

    ClearBreak(word pointhandle)
    return(byte status)

This message requests the clearing of the execution breakpoint identified by 
<pointhandle> which was set by an earlier <SetBreak> request (at level 0 of the 
RDI/RDP specification, <pointhandle> is the address at which the breakpoint was 
set).

Upon successful completion a zero status byte is returned.

On unsuccessful completion, a non-zero error code byte is returned.


Set Watchpoint Message (0C)
...........................

    SetWatch(word address, byte type, byte datatype {, word bound})
    return({word pointhandle} byte status)

      or  ({word address {,word bound}} byte status)

This message requests the debuggee to set  a data access watchpoint at <address>
. The least significant 4 bits of<type>  define the sort of watchpoint to set:

    0       halt on a data access to the address equal to <address>.

    1       halt on a data access to an address greater than <address>.

    2       halt on a data access to an address greater than or equal to
            <address>.

    3       halt on a data access to an address less than <address>

    4       halt on a data access to an address less than or equal to <address>
    .

    5       halt on a data access to an address in the range from <address>.
            to <bound>, inclusive. 

    6       halt on a data access to an address not in the range from
            <address> to <bound>, inclusive.

    7       halt if (<data-acess-address> & <bound>) = <address>.

At RDI/RDP specification levels 1 and above, bits 6 and 7 of <type>  have 
further significance.

Bit 6 of <type> set requests a dry run: the watchpoint is not set and the 
<address> and, if appropriate, the <bound>, that would be used, are returned 
(for range and comparison watchpoints, the <address> and <bound> used need not 
be exactly as requested). A zero status byte indicates that resources are 
currently available to set the watchpoint; <RDIError_NoMorePoints> indicates 
that the required watchpoint resources are not currently available.

Bit 7 of <type> set requests that a handle should be returned for the 
watchpoint by which it will be  identified subsequently. If bit 7 is set, a 
handle will be returned, whether the request succeeds or fails (but, obviously, 
it will only be meaningful if the request succeeds).

Bits 6 and 7 shall not be simultaneously set.

The <datatype> argument defines the sort of data access to watch for:

    1       watch for byte reads; 

    2       watch for half-word reads; 

    4       watch for word reads; 

    8       watch for byte writes; 

    16      watch for half-word writes; 

    32      watch for word writes.

Values may be summed or ORed together in order to halt on any of a set of sorts 
of memory access. For example:

    8 + 16 + 32

to watch for any write access to the specified location(s).

Upon successful completion a zero status byte is returned.

On unsuccessful completion, a non-zero error code byte is returned.

If the request is successful, but there are now no more watchpoint registers 
(of the requested type), then the value <RDIError_NoMorePoints> is returned.

If a watchpoint is set on a location which already has a watchpoint, the first 
watchpoint will be removed before the new watchpoint is set.


Clear Watchpoint Message (0D)
.............................

    ClearWatch(word pointhandle)
    return(byte status)

This message requests the clearing of the data access watchpoint identified by 
<pointhandle>, which was set by an earlier <SetWatch> request (at level 0 of 
the RDI/RDP specification, <pointhandle> is the address at which the watchpoint 
was set).

Upon successful completion a zero status byte is returned.

On unsuccessful completion, a non-zero error code byte is returned.


Execute Message (10)
....................

    Execute(byte return)
    return({word pointhandle} byte status)

This message requests that the debuggee commence execution at the address 
currently loaded into the CPU Program Counter.

If the least significant bit of<return >is 1, and commencing execution is 
viable, then a return message is sent immediately and execution commences 
asynchronously.

If the least significant bit of <return> is 0, then execution commences 
synchronously, and the return message is not sent until execution suspends:

 *  because the end of the program is reached; 

 *  because a break/watchpoint is reached; 

 *  because an exception occurs; 

 *  because the user interrupts the program.

At RDI/RDP specification levels 1 and above, bit 7 of <return> has further 
significance: if it is set then an extra word will be returned which, if 
execution suspends because of a break- or watch-point, is the identifying 
handle of the  -point causing suspension of execution.

On successful completion of the request, a zero status byte is returned.

On completion of a synchronous request, a non-zero <status> byte may indicate 
the reason the debuggee suspended, as follows:

    Status        Reason for suspension

    2             Undefined Instruction

    3             A SWI happened (only if watching for SWIs - see 
                  "<Info Message (12)>")

    4             Prefetch Abort - instruction fetch from unmapped memory

    5             Data Abort - no memory at the accessed address

    6             Address Exception - 26-bit mode access to address >= 2**26

    7             IRQ

    8             FIQ

    9             Error

    10            Branch through location 0

    143           Breakpoint Reached

    144           Watchpoint Accessed

    147           User pressed Escape

Any other non-zero value indicates failure of the request (see "<Error Codes>" 
starting on page101for details).


Step Message (11)
.................

    Step(byte return, word ninstr)
    return({word pointhandle} byte status)

This message requests the debuggee to execute <ninstr> instructions, starting 
at the address currently loaded into the CPU Program Counter.

If <ninstr> is zero, the debuggee executes instructions up to the next 
instruction that explicitly alters the program counter, (i.e. a branch or ALU 
operation with the program counter as destination).

If  the least significant bit of <return> is 1, and commencing execution is 
viable, then a return message is sent immediately and execution commences 
asynchronously.

If  the least significant bit of <return> is 0, then execution commences 
synchronously, and the return message is not sent until execution suspends:

 *  because the requested number of instructions have been executed;

 *  because a break/watchpoint is reached;

 *  because an exception occurs;

 *  because the user interrupts the program.

At RDI/RDP specification levels 1 and above, bit 7 of <return> has further 
significance: if it is set then an extra word will be returned which, if 
execution suspends because of a break- or watch-point, is the identifying 
handle of the  -point causing suspension of execution.

On successful completion of the request, a zero status byte is returned.

On completion of a synchronous request, a non-zero <status> byte indicates the 
reason the debuggee suspended, exactly as for the Execute message, (see "
<Execute Message (10)>").


Info Message (12)
.................

    Info(word info {, argument})
    return({words returninfo,} byte status)

This message requests the transfer of information between the debugger and the 
debuggee. The information transferred, and the direction of transfer depends on 
the value of <info>. In each case, a non-zero <status> byte indicates an 
unsuccessful request (see "<Error Codes>" for details).

A request with <info> = 0 returns information about the debuggee in the same 
way as:

    return(word data, word model, byte status)

The value of <data> should be interpreted as follows:

 *  bits 8, 9, 10: the minimum RDI specification level (0-7) required of the 
    debugger;

 *  bits 5, 6, 7: the maximum RDI specification level (0-7) implemented by the 
    debuggee;

 *  bit 4 = 0: debuggee is running under a software emulator;

 *  bit 4 = 1: debuggee is running on ARM hardware;

 *  bits 0:3: host speed as 10**(bits 0:3) instruction per second (IPS) (0 => 
    1IPS, 1 => 10IPS, 2 => 100IPS, 3 = 1000IPS, ..., 6 => 1MIPS, ...).

The value of <model> is a unique identifier for the ARM processor or the 
emulator model that the debuggee is running under.

A request with <info> = 1 returns information about the debuggee's 
breakpointing and watchpointing capabilities, in the same way as:

    return(word breakinfo, byte status)

The value of <breakinfo> should be interpreted as a set of bits, as follows:

    bit 0:  comparison breakpoints are supported;

    bit 1:  range breakpoints are supported;

    bit 2:  watchpoints for byte reads are supported;

    bit 3:  watchpoints for half-word reads are supported;

    bit 4:  watchpoints for word reads are supported;

    bit 5:  watchpoints for byte writes are supported;

    bit 6:  watchpoints for half-word writes are supported;

    bit 7:  watchpoints for word writes are supported;

    bit 8:  mask break/watch-points are supported;

    bit 9:  thread-specific breakpoints are supported;

    bit 10: thread-specific watchpoints are supported;

    bit 11: conditional breakpoints are supported.

All debuggee's must support breakpoints of sort RDIPoint_EQ (break at specified 
address).

A request with <info> = 2 returns information about the debuggee's 
single-stepping capabilities, in the same way as:

    return(word stepinfo, byte status)

The value of <stepinfo> should be interpreted as follows:

    bit 0:  single stepping of more than one instruction is supported;

    bit 1:  single stepping to the next direct PC alteration is supported;

    bit 2:  single stepping of a single instruction is supported.

A request with <info> = 3 returns information about the debuggee's memory 
management system (if any), in the same way as:

    return(word meminfo, byte status)

The value of <meminfo> is a unique identifier for the type of memory manager 
used by the debuggee.

A request with <info> = 0x100 requests that the debuggee should immediately 
halt execution. If the debuggee is not executing or is running synchronously 
(see "<Execute Message (10)>"), a Return message and the 
status <RDIError_UserInterrupt> will be returned. If the debuggee is running 
asynchronously, then a <Stopped> message will be returned, with status 
<RDIError_UserInterrupt>.

A request with <info> = 0x180 informs the debuggee which hardware exceptions 
should be reported to the debugger; <argument> is a bit-mask of exceptions to 
be reported, as follows:

    bit 0:  Reset (branch through 0)

    bit 1:  Undefined Instruction

    bit 2:  Software Interrupt (SWI)

    bit 3:  Prefetch Abort

    bit 4:  Data Abort

    bit 5:  Address Exception

    bit 6:  Interrupt (IRQ)

    bit 7:  Fast Interrupt (FIQ)

    bit 8:  Error

A set bit in <argument> indicates that the exception should be reported to the 
debugger; a clear bit indicates the corresponding exception vector should be 
taken. When an exception is reported to the debugger, the state of the debuggee 
is rewound to the state pertaining just before executing the instruction which 
caused the exception.

A request with <info> = 0x200 requests the debuggee to return the number of 
instructions and cycles executed since initialisation, in the same way as:

    return (word ninstr, word S-cycles, word N-cycles, word I-cycles,
    word C-cycles, word F-cycles, byte status)

A request with <info> = 0x201 requests the debuggee to return the error pointer 
associated with the last return to an Execute or Step request with status 
Error. Note that it is returned as a word, rather than a byte.

A request with <info> = 0x300 requests that the debuggee's command line be set 
to <argument>. <argument> must be 0-terminated string of bytes and no longer 
than 256 bytes, including the terminating 0

A request with <info> = 0x301 requests that the RDI specification level be set 
to <argument>, a byte value lying between the limits returned by a call with 
<info> = 0. From receipt of an <open> request with bit 0 of <type>  = 0 (a cold 
start open request) until receipt of this request, the debuggee operates with 
the RDI level set to its lower limit.

A request with <info> = 0x302 requests that the thread context (<SetBreak> and 
<SetWatch> messages) be set to <argument>, a 32 bit handle identifying a thread 
of execution. The distinguished handle <RDINoHandle> requests resetting the 
thread context to be the underlying hardware processor.

A request with <info> = 0x400 describes the registers of a coprocessor. 
<argument> has the form:

    byte cpnum {byte rmin, byte rmax, byte nbytes, byte access,
                byte r0, byte r1, byte w0, byte w1}*
    byte = 0xff

<nbytes> is the size in bytes of the register(s)

<access> is a bitmask:

 *  bit 0 set:   register(s) readable

 *  bit 1 set:   register(s) writeable

 *  bit 2 set:   register(s) read or written via CPDT instructions (else CPRT).

if <access> has bit 2 set, <r0> provides bits 0 to 7 <r1> bits 16 to 23 of a 
CPRT instruction to read the register, <w0> bits 0 to 7 and <w1> bits 16 to 23 
of a CPRT instruction to write the register.

Otherwise, <r0> provides bits 12 to 15 and <r1> bit 22 of CPDT instructions to 
read and write the register (and <w0> and <w1> are junk). 

A request with <info> = 0x401 has as <argument> a byte coprocessor number. It 
requests that the debugee describe the registers of the coprocessor if it is 
known. The description is as by 

    return( {byte rmin, byte rmax, byte nbytes, byte access}*, byte = 0xff)

where <rmin>, <rmax>, <nbytes> and <access> are as above.


OS Operation Reply Message (13)
...............................

    OSOpReply(byte info, {data})
    no reply

This message signals completion of the last requested OS Operation request. 
<info> describes the type of the value returned by the operation:

    0       return value

    1       <data> comprises a single byte, to be placed in the debuggee's r0.

    2       <data> comprises a word, to be placed in the debuggee's r0.

OS Operations which return more complicated values must do so by using the 
appropriate combination of Write Memory and Write CPU state operations.


Reset Message (7F)
..................

    RequestReset()
    no reply

Requests that the debuggee reset itself.


Debuggee to Debugger Messages
-----------------------------

The debugger does not acknowledge debuggee-to-debugger messages, as there is no 
point in trying to handle errors in the debuggee.

All responses to debugger-to-debuggee requests are of the <Retur>n message 
type, described in "<Return Message (5F)>".


Stopped Message (20)
....................

    Stopped({word pointhandle} byte status)

This message is sent to a debugger by an asynchronously executing debuggee, to 
indicate that execution of the debuggee has suspended. Execution of the 
debuggee was previously started by an <Execute(X)> or <Step(X, n)> message bith 
bit 1 of <X> = 1.

The <status> value indicates the type of suspension; for details, see "<Execute 
Message (10)>".

At RDI specification levels 1 and above, if bit 7 of <X> was 1, a word 
<pointhandle> is returned. If execution suspended because a breakpoint was 
reached or a watchpoint was accessed, then the  value of <pointhandle>  
identifies the -point concerned.


OS Operation Request Message (21)
.................................

    OSOp(word op, byte argdesc, {args})

This message is sent by the debuggee to request execution of a call to the host 
operating system. 

<op> identifies which call. <argdesc> allows description of up to 4 arguments 
to the call: if there are more, or their format is more complicated than can be 
described by <argdesc>, their values must be acquired by the appropriate 
combination of Read Memory and Read CPU State operations. <argdesc> is a 
sequence of two-bit fields starting from the least significant end of the word, 
each of which describes the corresponding argument, as follows:

    0       no such argument

    1       a single byte

    2       a word

    3       a string

The format of a string value is determined by its first byte:

    0-32        the string is of this length, and its component bytes follow, 
                (the terminating 0 byte is omitted)

    33-254      the string is of this length. A word containing the address of 
                the string follows. The read memory message can be used to 
                access the string.

    255         a word follows containing the string's length, then a word 
                containing its address. The read memory message can be used to 
                access the string.


Fatal Message (5E)
..................

    Fatal(byte error)

The <Fatal> message indicates that the debuggee could not make sense of the 
last message sent.


Return Message (5F)
...................

    Return(..., byte status)

The <Return> message is used to acknowledge a recognised request message.

A <status> value is always returned, indicating that the syntax of the original 
request was understood, and whether or not it was satisfied.

The arguments to <Return> depend on the message being acknowledged, and are 
described in "<Debugger to Debuggee Messages>".


Reset Message (7F)
..................

This message indicates that the debuggee has reset itself, either because of a 
hardware reset, or in response to a reset request.


Notes
-----


Address Spaces
..............

In debuggee environments that support different address spaces in different 
processor modes, the address space corresponding to the processor mode at the 
time the message is sent, is used by all memory access, breakpoint and 
watchpoint instructions.


Minimum Support
...............

There is a minimum subset of requests that all debuggees must support. The info 
message is used to enquire whether a debuggee can support operations outside 
the minimum subset, consisting of:

    Message                   Function code

    Open and/or Initialise    00

    Close and Finalise        01

    Read Memory Address       02

    Write Memory Address      03

    Read CPU State            04

    Write CPU State           05

    Set Breakpoint            0A (with first argument = 0)

    Clear Breakpoint          0B

    Execute                   10

    Info                      20

    Reset                     7F


Error Codes
-----------

The following error code values indicate debuggee status:

   Code Error Name              Possible cause

      0 No error                Everything worked
      1 Reset                   Debuggee reset
      2 Undefined instruction   Tried to execute the undefined instr
      3 Software interrupt      A SWI happened (when tracing SWIs)
      4 Prefetch abort          Execution ran into unmapped memory
      5 Data abort              No memory at the specified address
      6 Address exception       Accessed > 26 bit address in 26 bit mode
      7 IRQ                     An interrupt occurred
      8 FIQ                     A fast interrupt occurred
      9 Error                   An error occurred
     10 BranchThrough0          Branch through location 0
    142 No more points          That's the last of the break/watchpoints
    143 Breakpoint reached      What Execute and Step can return ...
    144 Watchpoint accessed     ... or this
    146 Program finished        End of the program reached while stepping
    147 User interrupt          User pressed Escape
    148 Cant Set Point          Break / watch point resources exhausted

The following errors indicate misuse of the RDI or similar problem:

   Code Error Name              Possible cause

    128 Not initialised         Open must be the first call
    129 Unable to initialise    The target world is broken
    130 WrongByteSex            The debuggee can't operate with the
                                requested byte sex.
    131 Unable to terminate     Target world was smashed by the debuggee
    132 Bad instruction         It is illegal to execute this instruction
    133 Illegal instruction     The effect of executing this is undefined
    134 Bad CPU state           Tried to set the SPSR of user mode
    135 Unknown co-processor    This co-processor is not connected
    136 Unknown co-proc state   Don't know how to handle this request
    137 Bad co-proc state       Recognisably broken co-proc request
    138 Bad point type          } Misuse of the RDI (user failed to
    139 Unimplemented type      } read the documentation properly?)
    140 Bad point size          }
    141 Unimplemented size      Half words not yet implemented
    145 No such point           Tried to clear an unset break/watchpoint


The following errors are not really errors, but are just a means of passing 
information:

   Code Error Name              Possible cause
   
    240 LittleEndian            The debuggee is little endian   
    241 BigEndian               The debuggee is big endian   


The following errors indicate an internal fault or limitation:

   Code Error Name              Possible cause

    253 InsufficientPrivilege   Supervisor state was not accessible to this
                                debug monitor
    254 Unimplemented message   Debuggee can't honour this RDP request
    255 Undefined message       Garbled RDP request

