The breakpoint table handler provides the following interface functions:

• void bptinitialize(void)---Initializes the breakpoint table.
• int bptinsert(address_value addr, instruction_value * savedinstr)---Adds a breakpoint to the table. The address is addr and the instruction to be saved is savedinstr. Returns SUCCESS if successful and a negative error code otherwise.
• int bptremove(address_value address, instruction_value * savedinstr)---Removes a breakpoint from the table. If successful, it returns SUCCESS as its result and returns the saved instruction in *savedinst. If it fails to remove the breakpoint, it returns a negative error code as its result.
• int bptgetn(int n, address_value*address, instruction_value * savedinstr)---Finds a breakpoint by breakpoint number. If it finds the breakpoint it returns SUCCESS as its result. It also returns the address of the breakpoint in *address and the saved instruction in *savedinst. If it fails to find the breakpoint it returns a negative error code as its result.
• int bptgeta(address_value address, instruction_value * savedinstr)---Finds a breakpoint by address. If it finds the breakpoint, it returns SUCCESS as its result and returns the saved instruction in *savedinst. If it fails to find the breakpoint, it returns a negative error code as its result.
• int bptisbreakat(address_value address)---Returns true if there is a breakpoint at address.
• int bptfull(void)---Returns true if the breakpoint table is full.

The code for the breakpoint table handler is identical for the two servers. It should not need to change for other server implementations. The source code is in bptable.c. The table is implemented as 3 arrays of 100 entries each. The breakpoint number of a breakpoint is used as an index into these arrays. The three arrays are:

• In-use array
• Breakpoint addresses array
• Saved instructions array

New entries are inserted in the first available entry and entries are found by a linear search.

C.11 Ladebug Remote Debugger Protocol

The Ladebug Remote Debugger Protocol is a request/response protocol running over UDP. The debugger client (Ladebug) initiates all transactions sending a request to the server. On receiving the request, the server acts upon the request and sends a response.

If the client does not receive a response within a time-out, it repeats the request (with an indication that the message is a duplicate). The time-out will vary between a tenth of a second and 10 seconds depending on how long it took to get responses to previous requests.

If the client does not receive a response, after a number of attempts and with increasing retry time-outs, it assumes that the communication path to the server has failed. The server never sends any messages except in response to messages received from the client.

Section C.11.1.1 through Section C.12 describe more about the Ladebug remote debugger protocol:

• Messages and formats
• Order of messages
• How to recover from packet loss
• The transport layer

This section describes the Ladebug Remote Debugger Protocol messages and the format of each message.

C.11.1.1 Message Headers

Table C-3 shows header names, byte numbers, format, and contents of the message headers. Section C.11.1.2 shows the possible values of the messages.

.

Table C-3 Header Format

Name	Byte Number	Format	Content
Protocol Version	0	Integer	Should be 2
Retransmit Count	1	Integer	In requests, 0 the first time a packet is transmitted: each retransmission of packet increments by a one. In responses, The retransmit count of the request.
Command code	2 to 3	Integer in network order, most significant byte first 1	Identifies the type of request or response.
Sequence Number	4 to 7	Integer in network order	Identifies the message.
Process ID	8 to 11	Integer in target machine order, least significant byte first for Alpha targets	Identifies the process being debugged. The value is not defined in load request messages.
Return value	12 to 16	Integer in network order	Ignored in requests. In replies tells the client whether the requested action was successful, and if not why not

Table C-4 explains the values returned by messages.

Table C-4 Message Table

Value	Message	Explanation
0	OK	Request succeeded
1	Bad process ID	The process ID of the message is not that of the debuggee, or, in the case of Connect to Process, the server could not connect to that process.
2	No resources	The server did not have the resources to carry out the request.
3	Not connected	The server is not connected to a debuggee. The request requires that it should be.
4	Not stopped	The debuggee is running. The request can only be carried out with the debuggee stopped.
5	Bad address	The address given in the request is bad. The precise meaning of this varies between the different types of responses that can give this return value.
6	Not implemented	The server does not implement this request.
7	Bad load name	See Section C.11.1.4
8	Already connected	The server is already debugging the requested debuggee.
9	Cannot disconnect from process	See Section C.11.1.8
10	Cannot kill process	See Section C.11.1.10
11	Cannot step	See section Section C.11.1.12

C.11.1.3 Load Process Request and Response

The load process request is a request to the server to load a new process and to start a new debugger session. They are transmitted in the request in the order shown with no unused bytes between the fields. Section C.11.1.4 describes the possible responses to a load process request.

Table C-5 shows the fields of the load process request:

Table C-5 Fields of the Load Process Request Message

Name	Length	Format	Contents
Header	16 bytes	See Table C-3	See Table C-3
Client User Name	Variable	Null terminated character string	Name of the user of the client on the host. This can be used by the server to check that the client is allowed to load the requested process.
Server User Name	Variable	Null terminated character string	User name of user to run the process on the target. This will be ignored by some servers.
Program Name	Variable	Null terminated character string	Name of program to be loaded. The form and interpretation of this name will vary between servers.
Number of arguments	1 byte	Integer	Count of program argument fields
Arguments	Variable	Variable number of null terminated strings. The number of arguments field gives the number of strings.	Arguments to be passed to the loaded process. May be ignored by some servers.
Standard input	Variable	Null terminated string	File name of a file to which standard input is to be redirected. An empty string (just a 0 byte) indicates no redirection: otherwise the interpretation of the file name is server dependent.
Standard output	Variable	Null terminated character string	Name of file to which standard output is to be redirected. This file name is interpreted in the same way as the standard input file name.
Standard error	Variable	Null terminated character string	Name of file to which standard error is to be redirected. This file name is interpreted in the same way as the standard input file name.

C.11.1.4 Responses to the Load Process Request

The command code for a Load Process request is 1. The server should ignore the PID received in a Load Process request.

The fields of a Load Process response are:

• The headers described in Table C-5, with the process ID field set to the process ID of the loaded process.
• A 1-byte processor type. At present the only defined type is 0, meaning an Alpha processor.
• A 1-byte process type. At present the only defined process types are:
  • Kernel process
  • User process
• Possible failure reasons are:
  • No resources---The server does not have the resources it requires to create a new process.
  • Bad load name---The server did not understand the name of the new process, or could not load the named process.
  • Not implemented---This server does not implement the load request.

The command code of a load response is 0x8001.

C.11.1.5 Connect to Process Request and Response

A connect request message requests that the server should start a debugger session by connecting to an existing process on the host. The fields of a connect request are:

• Packet header, as previously described. The process ID field identifies the process to which the server should connect.
• Client user name, as in load requests.
• Server user name, format as in load requests: but only used to check that the client has the correct privileges to debug the requested process.

The command code of a connect request is 2.

The format of a connect response is identical to that of a load response. Possible failure reasons are:

• Bad process ID---The server did not understand the process ID or could not connect to that process.
• No resources---The server does not have the resources it requires to create or debug a new process. A server that can only debug one process at a time will return this error if it is already debugging a process.
• Already connected---There is already a client connected to the same process.
• Not implemented---This server does not implement the connect request.

The command code of a connect response is 0x8002

C.11.1.6 Connect to Process Insist Request and Response

A connect insist request message requests that the server should take over debugging a process to which there may already be a server connected. The formats of connect insist requests and responses are differ from those of connect requests and responses only in the command codes. A Connect to Process Insist request has a command code of 3 and its response has a command code of 0x8003. A server should only return the Already Connected failure reason if it could not terminate the old debugger session.

C.11.1.7 Probe Process Request and Response

The Probe Process request asks the server what the state of the debuggee is. It contains no fields other than the standard header. Its command code is 0x81.

The Probe Process response returns the state of the debuggee. Following the standard header (at byte 16) it contains a 1-byte integer field giving the state of the debuggee. Possible values are:

• The debuggee is running.
• The debuggee has stopped at a breakpoint or following a single step.
• The debuggee has stopped unexpectedly. This might, for example, be as a result of it receiving a signal or executing a bad instruction. This value should also be returned if the debuggee has stopped as a result of a Stop Process request.
• The debuggee has exited.

Possible failure reasons are:

• Bad process ID
• Not connected

The command code of Probe Process response is 0x8081.

C.11.1.8 Disconnect from Process Request and Response

The Disconnect from Process request asks the server to disconnect from both the current debuggee and the client. It will only succeed if the server can disconnect from the debuggee without killing it, or if the debuggee is already dead.

The effect on breakpoints of disconnecting from a process may vary between servers. In particular, the protocol does not define whether disconnecting from a stopped process will allow it to run on, or what happens if the processes reaches a breakpoint after the server has disconnected from it.

The request contains no fields other than the message header. Its command code is 0x82.

The Disconnect from Process response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Cannot Disconnect from Process---The server cannot disconnect from the debuggee without killing it

If the server cannot disconnect from the debuggee it will remain connected to the client and to the debuggee. The command code of Disconnect from Process response is 0x8082.

C.11.1.9 Stop Process Request and Response

The Stop Process request asks the server to stop a running debuggee as soon as possible. It contains no fields other than the message header. Its command code is 0x83.

The Stop Process response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Not implemented---The server cannot stop running processes asynchronously

The command code of Stop Process response is 0x8083.

C.11.1.10 Kill Process Request and Response

The Kill Process request asks the server to kill the current debuggee and disconnect from the client. It will only succeed if the server can kill the debuggee, or if the debuggee is already dead. The request contains no fields other than the message header. Its command code is 0x84.

The Kill Process response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Cannot Kill Process---The server cannot kill the debuggee

If the server cannot kill the debuggee it will remain connected to the client and to the debuggee. The command code of Kill Process response is 0x8084.

C.11.1.11 Continue Process Request and Response

The Continue Process request asks the server to make the debuggee to run on until it hits a breakpoint, terminates, is stopped by the server acting on a Stop Process request, or stops for some other reason (e.g. executing a trap or exception). It contains no fields other than the message header. Its command code is 0xA1.

The Continue Process response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Not stopped

If the debuggee is terminated the request will succeed: but its effect is undefined. The command code of a Continue Process response is 0x80A1.

C.11.1.12 Step Request and Response

The Step request asks the server to make the debuggee execute one instruction. It contains no fields other than the message header. Its command code is 0xA2.

The Step response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Not stopped
• Cannot step---The server cannot single step the debuggee at this point. This might occur if, for example, the server would have to set a temporary breakpoint on an address to which it cannot write to single step the debuggee.

If the debuggee is terminated the request may succeed: but its effect is undefined. The command code of a Step response is 0x80A2.

C.11.1.13 Set Breakpoint Request and Response

The Set Breakpoint request asks the server to set a breakpoint in the code of the debuggee. Although a server is not required to be able to set a breakpoint on any particular address to be useful it must be able set breakpoint on a significant portion of the instructions of the debuggee.

The effect of setting a breakpoint on anything other than an instruction of the debuggee is not defined. Furthermore, the effect of setting a breakpoint on an instruction that the debuggee modifies or reads as data is not defined.

The fields of a Set Breakpoint request are:

• Message header
• Address of breakpoint---This is an 8-byte value sent in target machine byte order

The command code of a Set Breakpoint request is 0xA3.

The Set Breakpoint response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Not stopped
• Bad address---The server cannot set a breakpoint at the given address. The server may also return this failure reason if there is already a breakpoint at that address, although some servers can allow multiple breakpoints at the same address.
• No resources---The server did not have sufficient resources to add another breakpoint. The server may, for example, have a fixed sized breakpoint table that is full.

The command code of a Set Breakpoint response is 0x80A2.

C.11.1.14 Clear Breakpoint Request and Response

The Clear Breakpoint request asks the server to remove a breakpoint from the debuggee. Its fields are:

• Message header
• Address of breakpoint---This is an 8-byte value sent in target machine byte order

The command code of a Clear Breakpoint request is 0xA4.

The Clear Breakpoint response contains no fields other than the message header. Possible failure reasons are:

• Bad process ID
• Not connected
• Not stopped
• Bad address---The address is not the address of a breakpoint

The command code of a Clear Breakpoint response is 0x80A4.

C.11.1.15 Get Next Breakpoint Request and Response

Using Get Next Breakpoint requests the client can get a complete list of the breakpoints known to the server that affect the current debuggee. In some servers this will include breakpoints set in the debuggee by previous remote debugger sessions or through an alternative interface. For example, in the evaluation board server it includes breakpoints set by previous debugger sessions and those set through the local debugger interface.

To get a complete list of breakpoints the client should start by sending a Get Next Breakpoint with a breakpoint address of zero. It should then send further Get Next Breakpoint requests each containing the address returned by the previous Get Next Breakpoint response. A server that receives this sequence of requests with no other requests intervening must return each breakpoint it knows about precisely once. The protocol does not define the order in which the server will return the breakpoints it knows about.

The fields of a Get Next Breakpoint request are:

• Message header
• Address of previous breakpoint or zero if this is a request for the first breakpoint in the list. This is an 8-byte value sent in target machine byte order.

  Note A server must not set a breakpoint on address zero. This is not regarded as a serious restriction.

The command code of a Get Next Breakpoint request is 0xA5.

The fields of a Get Next Breakpoint response are:

• Message header
• Address of breakpoint or zero if there are no more breakpoints to be returned. This is an 8-byte value sent in target machine byte order

Possible failure reasons are:

• Bad process ID
• Not connected
• Not stopped
• Bad address---The address in the request is neither zero nor the address of a breakpoint

The command code of a Get Next Breakpoint response is 0x80A5.