LinuxDig.com Request For Comments

RFC Number : 909 Title : Loader Debugger Protocol. Loader Debugger Protocol RFC-909 Christopher Welles BBN Communications Corporation Walter Milliken BBN Laboratories July 1984 Status of This Memo This RFC specifies a proposed protocol for the ARPA Internet community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited.   Table of Contents 1 Introduction.......................................... 1 1.1 Purpose of This Document............................ 1 1.2 Summary of Features................................. 2 2 General Description................................... 3 2.1 Motivation.......................................... 3 2.2 Relation to Other Protocols......................... 4 2.2.1 Transport Service Requirements.................... 5 3 Protocol Operation.................................... 9 3.1 Overview............................................ 9 3.2 Session Management.................................. 9 3.3 Command Sequencing................................. 10 3.4 Data Packing and Transmission...................... 10 3.5 Implementations.................................... 12 4 Commands and Formats................................. 15 4.1 Packet Format...................................... 15 4.2 Command Format..................................... 16 4.2.1 Command Header................................... 16 4.3 Addressing......................................... 19 4.3.1 Long Address Format.............................. 20 4.3.2 Short Address Format............................. 25 5 Protocol Commands.................................... 29 5.1 HELLO Command...................................... 29 5.2 HELLO_REPLY........................................ 29 5.3 SYNCH Command...................................... 33 5.4 SYNCH_REPLY........................................ 34 5.5 ABORT Command...................................... 35 5.6 ABORT_DONE Reply................................... 35 5.7 ERROR Reply........................................ 36 5.8 ERRACK Acknowledgement............................. 39 6 Data Transfer Commands............................... 41 6.1 WRITE Command...................................... 42 6.2 READ Command....................................... 43 6.3 READ_DATA Response................................. 45 6.4 READ_DONE Reply.................................... 47 6.5 MOVE Command....................................... 48 6.6 MOVE_DATA Response................................. 50 Page i  6.7 MOVE_DONE Reply.................................... 52 6.8 REPEAT_DATA........................................ 53 6.9 WRITE_MASK Command (Optional)...................... 54 7 Control Commands..................................... 59 7.1 START Command...................................... 59 7.2 STOP Command....................................... 61 7.3 CONTINUE Command................................... 62 7.4 STEP Command....................................... 62 7.5 REPORT Command..................................... 63 7.6 STATUS Reply....................................... 64 7.7 EXCEPTION Trap..................................... 66 8 Management Commands.................................. 69 8.1 CREATE Command..................................... 69 8.2 CREATE_DONE Reply.................................. 74 8.3 DELETE Command..................................... 75 8.4 DELETE_DONE Reply.................................. 76 8.5 LIST_ADDRESSES Command............................. 76 8.6 ADDRESS_LIST Reply................................. 77 8.7 LIST_BREAKPOINTS Command........................... 79 8.8 BREAKPOINT_LIST Reply.............................. 80 8.9 LIST_PROCESSES Command............................. 82 8.10 PROCESS_LIST Reply................................ 83 8.11 LIST_NAMES Command................................ 84 8.12 NAME_LIST Reply................................... 85 8.13 GET_PHYS_ADDR Command............................. 87 8.14 GOT_PHYS_ADDR Reply............................... 88 8.15 GET_OBJECT Command................................ 90 8.16 GOT_OBJECT Reply.................................. 91 9 Breakpoints and Watchpoints.......................... 93 9.1 BREAKPOINT_DATA Command............................ 95 10 Conditional Commands................................ 99 10.1 Condition Command Format......................... 100 10.2 COUNT Conditions................................. 101 10.3 CHANGED Condition................................ 102 10.4 COMPARE Condition................................ 103 10.5 TEST Condition................................... 105 11 Breakpoint Commands................................ 109 11.1 INCREMENT Command................................ 109 11.2 INC_COUNT Command................................ 110 11.3 OR Command....................................... 111 11.4 SET_PTR Command.................................. 112 11.5 SET_STATE Command................................ 113 Page ii  A Diagram Conventions................................. 115 B Command Summary..................................... 117 C Commands, Responses and Replies..................... 121 D Glossary............................................ 123 Page iii  FIGURES 1 Relation to Other Protocols............................ 4 2 Form of Data Exchange Between Layers................... 6 3 Packing of 16-bit Words............................... 11 4 Packing of 20-bit Words............................... 12 5 Network Packet Format................................. 15 6 LDP Command Header Format............................. 16 7 Command Classes....................................... 17 8 Command Types......................................... 18 9 Long Address Format................................... 20 10 Long Address Modes................................... 21 11 Short Address Format................................. 26 12 Short Address Modes.................................. 27 13 HELLO Command Format................................. 29 14 HELLO_REPLY Format................................... 30 15 System Types......................................... 31 16 Target Address Codes................................. 31 17 Feature Levels....................................... 32 18 Options.............................................. 33 19 SYNCH Command Format................................. 33 20 SYNCH_REPLY Format................................... 34 21 ABORT Command Format................................. 35 22 ABORT_DONE Reply Format.............................. 36 23 ERROR Reply Format................................... 37 24 ERROR Codes.......................................... 38 25 ERRACK Command Format................................ 40 26 WRITE Command Format................................. 42 27 READ Command Format.................................. 44 28 DATA Response Format................................. 46 29 READ_DONE Reply Format............................... 47 30 MOVE Command Format.................................. 49 31 MOVE_DATA Response Format............................ 51 32 MOVE_DONE Reply Format............................... 52 33 REPEAT_DATA Command Format........................... 54 34 WRITE_MASK Format.................................... 56 35 START Command Format................................. 60 36 STOP Command Format.................................. 61 37 CONTINUE Command Format.............................. 62 38 STEP Command Format.................................. 63 39 REPORT Command Format................................ 64 40 STATUS Reply Format.................................. 65 41 EXCEPTION Format..................................... 66 42 CREATE Command Format................................ 70 Page iv  43 Create Types......................................... 71 44 CREATE BREAKPOINT Format............................. 71 45 CREATE MEMORY_OBJECT Format.......................... 73 46 CREATE_DONE Reply Format............................. 74 47 DELETE Command Format................................ 75 48 DELETE_DONE Reply Format............................. 76 49 LIST_ADDRESSES Command Format........................ 77 50 ADDRESS_LIST Reply Format............................ 78 51 LIST_BREAKPOINTS Command Format...................... 80 52 BREAKPOINT_LIST Reply Format......................... 81 53 LIST_PROCESSES Command Format........................ 82 54 PROCESS_LIST Reply Format............................ 84 55 LIST_NAMES Command Format............................ 85 56 NAME_LIST Reply Format............................... 86 57 GET_PHYS_ADDR Command Format......................... 88 58 GOT_PHYS_ADDR Reply Format........................... 89 59 GET_OBJECT Command Format............................ 90 60 GOT_OBJECT Reply Format.............................. 91 61 Commands to Manipulate Breakpoints................... 93 62 Breakpoint Conditional Command Lists................. 95 63 BREAKPOINT_DATA Command Format....................... 96 64 Breakpoint Data Stream Format........................ 97 65 Conditional Command Summary.......................... 99 66 Condition Command Header............................ 101 67 COUNT Condition Format.............................. 101 68 CHANGED Condition................................... 102 69 COMPARE Condition................................... 104 70 TEST Condition...................................... 106 71 Breakpoint Command Summary.......................... 109 72 INCREMENT Command Format............................ 110 73 INC_COUNT Command Format............................ 111 74 OR Command Format................................... 111 75 SET_PTR Command Format.............................. 112 76 SET_STATE Command Format............................ 113 77 Sample Diagram...................................... 115 78 Command Summary..................................... 118 79 Commands, Responses and Replies..................... 122 Page v   CHAPTER 1 Introduction The Loader-Debugger Protocol (LDP) is an application layer protocol for loading, dumping and debugging target machines from hosts in a network environment. This protocol is designed to accommodate a variety of target cpu types. It provides a powerful set of debugging services. At the same time, it is structured so that a simple subset may be implemented in applications like boot loading where efficiency and space are at a premium. The authors would like to thank Dan Franklin and Peter Cudhea for providing many of the ideas on which this protocol is based. 1.1 Purpose of This Document This is a technical specification for the LDP protocol. It is intended to be comprehensive enough to be used by implementors of the protocol. It contains detailed descriptions of the formats and usage of over forty commands. Readers interested in an overview of LDP should read the Summary of Features, below, and skim Sections 2 through 3.1. Also see Appendix B, the Command Summary. The remainder of the document reads best when accompanied by strong coffee or tea. Page 1  RFC-909 July 1984 1.2 Summary of Features LDP has the following features: o commands to perform loading, dumping and debugging o support for multiple connections to a single target o reliable performance in an internet environment o a small protocol subset for target loaders o addressing modes and commands to support multiple machine types o breakpoints and watchpoints which run in the target machine. Page 2  LDP Specification General Description CHAPTER 2 General Description 2.1 Motivation LDP is an application protocol that provides a set of commands used by application programs for loading, dumping and debugging target machines across a network. The goals of this protocol are shown in the following list: o The protocol should support various processor types and operating systems. Overhead and complexity should be minimized for simpler cases. o The protocol should provide support for applications in which more than one user can debug the same target machine. This implies an underlying transport mechanism that supports multiple connections between a host-target pair. o LDP should have a minimal subset of commands for boot loading and dumping. Target machine implementations of these applications are often restricted in the amount of code-space they may take. The services needed for loading and dumping should be provided in a small, easily implemented set of commands. o There should be a means for communicating exceptions and errors from the target LDP process to the host process. o LDP should allow the application to implement a full set of debugging functions without crippling the performance of the target's application (i.e., PSN, PAD, gateway). For example, a breakpoint mechanism that halts the target machine while breakpoint commands are sent from the host to the target is of limited usefulness, since the target will be unable to service the real-time Page 3  RFC-909 July 1984 demands of its application. 2.2 Relation to Other Protocols LDP is an application protocol that fits into the layered internet protocol environment. Figure 1 illustrates the place of LDP in the protocol hierarchy. +------------------------------+ | LDP | Application +------------------------------+ Layer | | | | | | +---------+ +---------+ | RDP | or | TCP | Transport Layer +---------+ +---------+ | or | | | | | | +--------------------+ | | Internet Protocol | Internetwork | +--------------------+ Layer | | +------------------------------+ | Network Access Protocol | Network Layer +------------------------------+ Relation to Other Protocols Figure 1 Page 4  LDP Specification General Description 2.2.1 Transport Service Requirements LDP requires that the underlying transport layer: o allow connections to be opened by specifying a network (or internet) address. Support passive and active opens. o for each connection, specify the maximum message size. o provide a mechanism for sending and receiving messages over an open connection. o deliver messages reliably and in sequence o support multiple connections, and distinguish messages associated with different connections. This is only a requirement where LDP is expected to support several users at the same time. o explictly return the outcome (success/failure) of each request (open, send, receive), and provide a means of querying the status of a connection (unacknowledged message count, etc.). Data is passed from the application program to the LDP user process in the form of commands. In the case of an LDP server process, command responses originate in LDP itself. Below LDP is the transport protocol. The Reliable Data Protocol (RDP -- RFC 908) is the recommended transport procotol. Data is passed across the LDP/RDP interface in the form of messages. (TCP may be used in place of RDP, but it will be less efficient and it will require more resources to implement.) An internet layer (IP) normally comes between RDP and the network layer, but RDP may exchange data packets directly with the network layer. Figure 2 shows the flow of data across the protocol interfaces: Page 5  RFC-909 July 1984 +------+ | | |Appli-| |cation| | | +------+ ^ Commands | V +------+ | | | LDP | | | +------+ ^ Messages | V +-----+ | | | RDP | | | +-----+ ^ Segments | V +----+ | | | IP | | | +----+ ^ Datagrams | V ? * ! $ = ^ + * > Internet , ? ! ) * % $ Form of Data Exchange Between Layers Figure 2 Page 6  LDP Specification General Description Page 7  RFC-909 July 1984 Page 8  LDP Specification Protocol Operation CHAPTER 3 Protocol Operation 3.1 Overview An LDP session consists of an exchange of commands and responses between an LDP user process and an LDP server process. Normally, the user process resides on a host machine (a timesharing computer used for network monitoring and control), and the server process resides on a target machine (PSN, PAD, gateway, etc.). Throughout this document, host and target are used as synonyms for user process and server process, respectively, although in some implementations (the Butterfly, for example) this correspondence may be reversed. The host controls the session by sending commands to the target. Some commands elicit responses, and all commands may elicit an error reply. The protocol contains five classes of commands: protocol, data transfer, management, control and breakpoint. Protocol commands are used to verify the command sequencing mechanism and to handle erroneous commands. Data transfer commands involve the transfer of data from one place to another, such as for memory examine/deposit, or loading. Management commands are used for creating and deleting objects (processes, breakpoints, watchpoints, etc.) in the target machine. Control commands are used to control the execution of target code and breakpoints. Breakpoint commands are used to control the execution of commands inside breakpoints and watchpoints. 3.2 Session Management An LDP session consists of a series of commands sent from a host LDP to a target LDP, some of which may be followed by responses from the target. A session begins when a host opens a transport connection to a target listening on a well known port. LDP uses RDP port number zzz or TCP port number yyy. When the connection has been established, the host sends a HELLO command, and the target replies with a HELLO_REPLY. The HELLO_REPLY contains parameters that describe the target's implementation of LDP, including protocol version, implementation level, system Page 9  RFC-909 July 1984 type, and address format. The session terminates when the host closes the underlying transport connection. When the target detects that the transport connection has been closed, it should deallocate any resources dedicated to the session. The target process is the passive partner in an LDP session, and it waits for the host process to terminate the session. As an implementation consideration, either LDP or the underlying transport protocol in the target should have a method for detecting if the host process has died. Otherwise, an LDP target that supported only one connection could be rendered useless by a host that crashed in the middle of a session. The problem of detecting half-dead connections can be avoided by taking a different tack: the target could allow new connections to usurp inactive connections. A connection with no activity could be declared 'dead', but would not be usurped until the connection resource was needed. However, this would still require the transport layer to support two connection channels: one to receive connection requests, and another to use for an active connection. 3.3 Command Sequencing Each command sent from the host to the target has a sequence number. The sequence number is used by the target to refer to the command in normal replies and error replies. To save space, these numbers are not actually included in host commands. Instead, each command sent from the host is assigned an implicit sequence number. The sequence number starts at zero at the beginning of the LDP session and increases by one for each command sent. The host and target each keep track of the current number. The SYNCH command may be used by the host to synchronize the sequence number. 3.4 Data Packing and Transmission The convention for the order of data packing was chosen for its simplicity: data are packed most significant bit first, in order of increasing target address, into eight-bit octets. The octets of packed data are transmitted in sequential order. Page 10  LDP Specification Protocol Operation Data are always packed according to the address format of the target machine. For example, in an LDP session between a 20-bit host and a 16-bit target, 16-bit words (packed into octets) are transmitted in both directions. For ease of discussion, targets are treated here as if they have uniform address spaces. In practice, the size of address units may vary within a target -- 16-bit macromemory, 32-bit micromemory, 10-bit dispatch memory, etc. Data packing between host and target is tailored to the units of the current target address space. Figures showing the packing of data for targets with various address unit sizes are given below. The order of transmission with respect to the diagrams is top to bottom. Bit numbering in the following diagrams refers to significance in the octet: bit zero is the least significant bit in an octet. For an explanation of the bit numbering convention that applies in the rest of this document, please see Appendix A. The packing of data for targets with word lengths that are multiples of 8 is straightforward. The following diagram illustrates 16-bit packing: 7 0 --------------------------------- Octet 0 | WORD 0 bits 15-08 | --------------------------------- Octet 1 | WORD 0 bits 07-00 | --------------------------------- Octet 2 | WORD 1 bits 15-08 | --------------------------------- Octet 3 | WORD 1 bits 07-00 | --------------------------------- * * * --------------------------------- Octet 2n-1 | WORD n bits 07-00 | --------------------------------- Packing of 16-bit Words Figure 3 Page 11  RFC-909 July 1984 Packing for targets with peculiar word lengths is more complicated. For 20-bit machines, 2 words of data are packed into 5 octets. When an odd number of 20-bit words are transmitted, the partially used octet is included in the length of the command, and the octet is padded to the right with zeroes. 7 0 --------------------------------- Octet 0 | WORD 0 bits 19-12 | --------------------------------- Octet 1 | WORD 0 bits 11-04 | --------------------------------- Octet 2 | WORD 0 03-00 | WORD 1 19-16 | --------------------------------- Octet 3 | WORD 1 bits 15-08 | --------------------------------- Octet 4 | WORD 1 bits 07-00 | --------------------------------- Packing of 20-bit Words Figure 4 3.5 Implementations A subset of LDP commands may be implemented in targets where machine resources are limited and the full capabilities of LDP are not needed. There are three basic levels of target implementations: LOADER_DUMPER, BASIC_DEBUGGER and FULL_DEBUGGER. The target communicates its LDP implementation level to the host during session initiation. The implementation levels are described below: Page 12  LDP Specification Protocol Operation LOADER_DUMPER Used for loading/dumping of the target machine. Includes all protocol class commands and replies; data transfer commands READ, WRITE, MOVE and their responses; control command START and control reply EXCEPTION. Understands at least PHYS_MACRO and HOST addressing modes; others if desired. BASIC_DEBUGGER Implements LOADER_DUMPER commands, all control commands, all addressing modes appropriate to the target machine, but does not have finite state machine (FSM) breakpoints or watchpoints. Default breakpoints are implemented. The target understands long addressing mode. FULL_DEBUGGER Implements all commands and addressing modes appropriate to the target machine, and includes breakpoint commands, conditional commands and BREAKPOINT_DATA. Watchpoints are optional. Page 13  RFC-909 July 1984 Page 14  LDP Specification Commands and Formats CHAPTER 4 Commands and Formats 4.1 Packet Format LDP commands are enclosed in RDP transport messages. An RDP message may contain more than one command, but each command must fit entirely within a single message. Network packets containing LDP commands have the format shown in Figure 5. +----------------+ | Local Network | | Header(s) | +----------------+ | IP Header | +----------------+ | RDP Header | +----------------+ +-+ | LDP Command | | | Header | | +----------------+ | | Optional | | . LDP . | LDP Command . Data . | Format | | | +----------------+ | | LDP Padding | | +----------------+ +-+ | Additional | . LDP . . Commands . . . +----------------+ Network Packet Format Figure 5 Page 15  RFC-909 July 1984 4.2 Command Format LDP commands consist of a standard two-word header followed optionally by additional data. To facilitate parsing of multi- command messages, all commands contain an even number of octets. Commands that contain an odd number of data octets must be padded with a null octet. The commands defined by the LDP specification are intended to be of universal application to provide a common basis for all implementations. Command class and type codes from 0 to 63. are reserved by the protocol. Codes above 63. are available for the implementation of target-specific commands. 4.2.1 Command Header LDP commands begin with a fixed length header. The header specifies the type of command and its length in octets. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length (octets) | +---------------+---------------+ 1 | Command Class | Command Type | +---------------+---------------+ LDP Command Header Format Figure 6 HEADER FIELDS: Command Length The command length gives the total number of octets in the command, including the length field and data, and excluding padding. Command Class Command Type Page 16  LDP Specification Commands and Formats The command class and type together specify a particular command. The class selects one of six command categories, and the type gives the command within that category. All codes are decimal. The symbols given in Figures 7 and 8 for command classes and types are used in the remainder of this document for reference. The command classes that have been defined are: Command Class | Symbol ----------------+----------- 1 | PROTOCOL 2 | DATA_TRANSFER 3 | CONTROL 4 | MANAGEMENT 5 | BREAKPOINT 6 | CONDITION 7 - 63 | Command Classes Figure 7 Command type codes are assigned in order of expected frequency of use. Commands and their responses/replies are numbered sequentially. The command types, ordered by command class, are: Page 17  RFC-909 July 1984 Command Class | Command Type | Symbol ----------------+---------------+---------- PROTOCOL | 1 | HELLO | 2 | HELLO_REPLY | 3 | SYNCH | 4 | SYNCH_REPLY | 5 | ERROR | 6 | ERRACK | 7 | ABORT | 8 | ABORT_DONE | 9 - 63 | | | DATA_TRANSFER | 1 | WRITE | 2 | READ | 3 | READ_DONE | 4 | READ_DATA | 5 | MOVE | 6 | MOVE_DONE | 7 | MOVE_DATA | 8 | REPEAT_DATA | 9 | BREAKPOINT_DATA | 10 | WRITE_MASK | 11 - 63 | | | CONTROL | 1 | START | 2 | STOP | 3 | CONTINUE | 4 | STEP | 5 | REPORT | 6 | STATUS | 7 | EXCEPTION | 8 - 63 | | | MANAGEMENT | 1 | CREATE | 2 | CREATE_DONE | 3 | DELETE | 4 | DELETE_DONE | 5 | LIST_ADDRESSES | 6 | ADDRESS_LIST | 7 | GET_PHYS_ADDRESS | 8 | GOT_PHYS_ADDRESS | 9 | GET_OBJECT | 10 | GOT_OBJECT | 11 | LIST_BREAKPOINTS | 12 | BREAKPOINT_LIST Page 18  LDP Specification Commands and Formats | 13 | LIST_NAMES | 14 | NAME_LIST | 15 | LIST_PROCESSES | 16 | PROCESS_LIST | 17 - 63 | | | BREAKPOINT | 1 | INCREMENT | 2 | INC_COUNT | 3 | OR | 4 | SET_PTR | 5 | SET_STATE | 6 - 63 | | | CONDITION | 1 | CHANGED | 2 | COMPARE | 3 | COUNT_EQ | 4 | COUNT_GT | 5 | COUNT_LT | 6 | TEST | 7 - 63 | Command Types Figure 8 4.3 Addressing Addresses are used in LDP commands to refer to memory locations, processes, buffers, breakpoints and other entities. Many of these entities are machine-dependent; some machines have named objects, some machines have multiple address spaces, the size of address spaces varies, etc. The format for specifying addresses needs to be general enough to handle all of these cases. This speaks for a large, hierarchically structured address format. However, the disadvantage of a large format is that it imposes extra overhead on communication with targets that have simpler address schemes. LDP resolves this conflict by employing two address formats: a short three-word format for addressing simpler targets, and a long five-word format for others. Each target LDP is required to implement at least one of these formats. At the start of an LDP session, the target specifies the address format(s) it uses in Page 19  RFC-909 July 1984 the Flag field of the HELLO_REPLY message. In each address, the first bit of the mode octet is a format flag: 0 indicates LONG address format, and 1 indicates SHORT format. 4.3.1 Long Address Format The long address format is five words long and consists of a three-word address descriptor and a two-word offset (see Figure 9). The descriptor specifies an address space to which the offset is applied. The descriptor is subdivided into several fields, as described below. The structuring of the descriptor is designed to support complex addressing modes. For example, on targets with multiple processes, descriptors may reference virtual addresses, registers, and other entities within a particular process. The addressing modes defined below are intended as a base to which target-specific modes may be added. Modes up to 63. are reserved by the protocol. The range 64. to 127. may be used for target-specific address modes. Long Format - Format bit is LONG=0 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-------------------------------+ +-+ |0| Mode | Mode Arg | | +-------------------------------+ | | (31-16) | | Descriptor +---- ID ---+ | | (15-0) | | +-------------------------------+ +-+ | (31-16) | | +---- Offset ---+ | Offset | (15-0) | | +-------------------------------+ +-+ Long Address Format Figure 9 LONG ADDRESS FIELDS: Page 20  LDP Specification Commands and Formats Mode The address mode identifies the type of address space being referenced. The mode is qualified by the mode argument and the ID field. Implementation of modes other than physical and host is machine-dependent. Currently defined modes and the address space they reference are shown in Figure 10. Mode | Symbol | Address space -----+----------------------+--------------------------- 0 HOST Host 1 PHYS_MACRO Macromemory 2 PHYS_MICRO Micromemory 3 PHYS_I/O I/O space 4 PHYS_MACRO_PTR Macro contains a pointer 5 PHYS_REG Register 6 PHYS_REG_OFFSET Register plus offset 7 PHYS_REG_INDIRECT Register contains address of a pointer 8 PROCESS_CODE Process code space 9 PROCESS_DATA Process data space 10 PROCESS_DATA_PTR Process data contains a ptr 11 PROCESS_REG Process virtual register 12 PROCESS_REG_OFFSET Process register plus offset 13 PROCESS_REG_INDIRECT Process register contains address of a pointer 14 OBJECT_OFFSET Memory object (queue, pool) 15 OBJECT_HEADER System header for an object 16 BREAKPOINT Breakpoint 17 WATCHPOINT Watchpoint 18 BPT_PTR_OFFSET Breakpoint ptr plus offset 19 BPT_PTR_INDIRECT Breakpoint ptr plus offset gives address of a pointer 20 - 63 Long Address Modes Figure 10 Mode Argument Page 21  RFC-909 July 1984 Provides a numeric argument to the mode field. Specifies the register in physical and process REG and REG_OFFSET modes. ID Field Identifies a particular process, buffer or object. Offset The offset into the linear address space defined by the mode. The size of the machine word determines the number of significant bits in the offset. Likewise, the addressing units of the target are the units of the offset. The interpretation of the mode argument, ID field and offset for each address mode is given below: HOST The ID and offset fields are numbers assigned arbitrarily by the host side of the debugger. These numbers are used in MOVE and MOVE_DATA messages. MOVE_DATA responses containing this mode as the destination are sent by the target to the host. This may occur in debugging when data is sent to the host from the target breakpoint. PHYS_MACRO The offset contains the 32-bit physical address of a location in macromemory. The mode argument and ID field are not used. For example, mode=PHYS_MACRO and offset=1000 specifies location 1000 in physical memory. PHYS_MICRO Like PHYS_MACRO, but the location is in micromemory. PHYS_I/O Like PHYS_MACRO, but the location is in I/O space. PHYS_MACRO_PTR The offset contains the address of a pointer in macromemory. The location pointed to (the effective address) is also in macromemory. The mode argument and ID field are unused. Page 22  LDP Specification Commands and Formats PHYS_REG The mode argument gives the physical register. If the register is used by the LDP target process, then the saved copy from the previous context is used. This comment applies to PHYS_REG_OFFSET mode as well. The ID field is not used. PHYS_REG_OFFSET The offset is added to the contents of a register given as the mode argument. The result is used as a physical address in macromemory. ID is unused. PHYS_REG_INDIRECT The register specified in the mode arg contains the address of a pointer in macromemory. The effective address is the macromemory location specified in the pointer, plus the offset. The ID field is unused. PROCESS_CODE The ID is a process ID, the offset is into the code space for this process. Mode argument is not used. PROCESS_DATA The ID is a process ID, the offset is into the data space for this process. Mode argument is not used. On systems that do not distinguish between code and data space, these two modes are equivalent, and reference the virtual address space of the process. PROCESS_DATA_PTR The offset contains the address of a pointer in the data space of the process specified by the ID. The location pointed to (the effective address) is also in the data space. The mode argument is not used. PROCESS_REG Accesses the registers (and other system data) of the process given by the ID field. Mode argument 0 starts the registers. After the registers, the mode argument is an offset into the system area for the process. Page 23  RFC-909 July 1984 PROCESS_REG_OFFSET The offset plus the contents of the register given in the mode argument specifies a location in the data space of the process specified by the ID. PROCESS_REG_INDIRECT The register specified in the mode arg contains the address of a pointer in the data space of the process given by the ID. The effective address is the location in process data space specified in the pointer, plus the offset. OBJECT_OFFSET (optional) The offset is into the memory space defined by the object ID in ID. Recommended for remote control of parameter segments. OBJECT_HEADER (optional) The offset is into the system header for the object specified by the ID. Intended for use with the Butterfly. BREAKPOINT The descriptor specifies a breakpoint. The offset is never used, this type is only used in descriptors referring to breakpoints. (See Breakpoints and Watchpoints, below, for an explanation of breakpoint descriptors.) WATCHPOINT The descriptor specifies a watchpoint. The offset is never used, this type is only used in descriptors referring to watchpoints. (See Breakpoints and Watchpoints, below, for an explanation of watchpoint descriptors). BPT_PTR_OFFSET For this mode and BPT_PTR_INDIRECT, the mode argument specifies one of two breakpoint pointer variables local to the breakpoint in which this address occurs. These pointers and the SET_PTR command which manipulates them provide for an arbitrary amount of address indirection. They are intended for use in traversing data structures: for example, chasing queues. In BPT_PTR_OFFSET, the offset is added to Page 24  LDP Specification Commands and Formats the pointer variable to give the effective address. In targets which support multiple processes, the location is in the data space of the process given by the ID. Otherwise, the location is a physical address in macro-memory. BPT_PTR.* modes are valid only in breakpoints and watchpoints. BPT_PTR_INDIRECT Like BPT_PTR_OFFSET, except that it uses one more level of indirection. The pointer variable given by the mode argument plus the offset specify an address which points to the effective address. See the description of BPT_PTR_OFFSET for a discussion of usage, limitations and address space. 4.3.2 Short Address Format The short address format is intended for use in implementations where protocol overhead must be minimized. This format is a subset of the long address format: it contains the same fields except for the ID field. Therefore, the short addressing format supports only HOST and PHYS_* address modes. Only the LOADER_DUMPER implementation level commands may be used with the short addressing format. The short address format is three words long, consisting of a 16-bit word describing the address space, and a 32-bit offset. Page 25  RFC-909 July 1984 Short Format - Format bit is SHORT=1 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-------------------------------+ |1| Mode | Mode Argument | +-------------------------------+ +-+ | (31-16) | | +---- Offset ---+ | Offset | (15-0) | | +-------------------------------+ +-+ Short Address Format Figure 11 SHORT ADDRESS FIELDS: Mode The high-order bit is 1, indicating the short address format. A list of the address modes supported is given below. The interpretation of the remaining fields is as described above for the long addressing format. Page 26  LDP Specification Commands and Formats Mode | Symbol | Address space -----+--------------------+--------------------------- 0 HOST Host 1 PHYS_MACRO Macro-memory 2 PHYS_MICRO Micro-memory 3 PHYS_I/O I/O space 4 PHYS_MACRO_PTR Macro contains a pointer 5 PHYS_REG Register 6 PHYS_REG_OFFSET Register plus offset 7 PHYS_REG_INDIRECT Register contains address of a pointer 8 - 32 Short Address Modes Figure 12 Page 27  RFC-909 July 1984 Page 28  LDP Specification Protocol Commands CHAPTER 5 Protocol Commands Protocol commands are used for error handling, for synchronizing the command sequence number, and for communicating protocol implementation parameters. Every protocol command has a corresponding reply. All protocol commands are sent from the host to the target, with replies flowing in the opposite direction. 5.1 HELLO Command The HELLO command is sent by the host to signal the start of an LDP session. The target responds with HELLO_REPLY. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | PROTOCOL | HELLO | +---------------+---------------+ HELLO Command Format Figure 13 5.2 HELLO_REPLY A HELLO_REPLY is sent by the target in response to the HELLO command at the start of an LDP session. This reply is used to inform the host about the target's implementation of LDP. Page 29  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 10 | +---------------+---------------+ 1 | PROTOCOL | HELLO_REPLY | +---------------+---------------+ 2 | LDP Version | System Type | +---------------+---------------+ 3 | Options |W|S| Implementation| +---------------+---------------+ 4 | Address Code | Reserved | +---------------+---------------+ HELLO_REPLY Format Figure 14 HELLO_REPLY FIELDS: LDP Version The target's LDP protocol version. If the current host protocol version does not agree with the target's protocol version, the host may terminate the session, or may continue it, at the discretion of the implementor. The current version number is 2. System Type The type of system running on the target. This is used as a check against what the host thinks the target is. The host is expected to have a table of target system types with information about target address spaces, target-specific commands and addressing modes, and so forth. Currently defined system types are shown in Figure 15. This list includes some systems normally thought of as 'hosts' (e.g. C70, VAX), for implementations where targets actively initiate and direct a load of themselves. Page 30  LDP Specification Protocol Commands Code | System | Description --------+---------------+--------------------------- 1 C30_16_BIT BBN 16-bit C30 2 C30_20_BIT BBN 20-bit C30 3 H316 Honeywell-316 4 BUTTERFLY BBN Butterfly 5 PDP-11 DEC PDP-11 6 C10 BBN C10 7 C50 BBN C50 8 PLURIBUS BBN Pluribus 9 C70 BBN C70 10 VAX DEC VAX 11 MACINTOSH Apple MacIntosh System Types Figure 15 Address Code The address code indicates which LDP address format(s) the target is prepared to use. Address codes are show in Figure 16. Address Code | Symbol | Description --------------+---------------+----------------------------- 1 LONG_ADDRESS Five word address format. Supports all address modes and commands. 2 SHORT_ADDRESS Three word address format. Supports only physical and host address modes. Only the LOADER_DUMPER set of commands are supported. Target Address Codes Figure 16 Implementation Page 31  RFC-909 July 1984 The implementation level specifies which features of the protocol are implemented in the target. There are three levels of protocol implementation. These levels are intended to correspond to the three most likely applications of LDP: simple loading and dumping, basic debugging, and full debugging. (Please see Implementations, above, for a detailed description of implementation levels.) There are are also several optional features that are not included in any particular level. Implementation levels are cumulative, that is, each higher level includes the features of all previous levels. The levels are shown in Figure 17. Feature Level | Symbol | Description --------------+---------------+----------------------------- 1 LOADER_DUMPER Loader/dumper subset of LDP 2 BASIC_DEBUGGER Control commands, CREATE 3 FULL_DEBUGGER FSM breakpoints Feature Levels Figure 17 Options The options field (see Figure 18) is an eight-bit flag field. Bit flags are used to indicate if the target has implemented particular optional commands. Not all optional commands are referenced in this field. Commands whose implementation depends on target machine features are omitted. The LDP application is expected to 'know' about target features that are not intrinsic to the protocol. Examples of target-dependent commands are commands that refer to named objects (CREATE, LIST_NAMES). Page 32  LDP Specification Protocol Commands Mask | Symbol | Description ------+-------------+---------------+----------------- 1 STEP The STEP command is implemented 2 WATCHPOINTS Watchpoints are implemented Options Figure 18 5.3 SYNCH Command The SYNCH command is sent by the host to the target. The target responds with a SYNCH_REPLY. The SYNCH - SYNCH_REPLY exchange serves two functions: it synchronizes the host-to-target implicit sequence number and acts as a cumulative acknowledgement of the receipt and execution of all host commands up to the SYNCH. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 6 | +---------------+---------------+ 1 | PROTOCOL | SYNCH | +---------------+---------------+ 2 | Sequence Number | +---------------+---------------+ SYNCH Command Format Figure 19 SYNCH FIELDS: Sequence Number Page 33  RFC-909 July 1984 The sequence number of this command. If this is not what the target is expecting, the target will reset to it and respond with an ERROR reply. 5.4 SYNCH_REPLY A SYNCH_REPLY is sent by the target in reponse to a valid SYNCH command. A SYNCH command is valid if its sequence number agrees with the sequence number the target is expecting. Otherwise, the target will reset its sequence number to the SYNCH command and send an ERROR reply. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 6 | +---------------+---------------+ 1 | PROTOCOL | SYNCH_REPLY | +---------------+---------------+ 2 | Sequence Number | +---------------+---------------+ SYNCH_REPLY Format Figure 20 SYNCH_REPLY FIELDS: Sequence Number The sequence number of the SYNCH command to which this SYNCH_REPLY is the response. Page 34  LDP Specification Protocol Commands 5.5 ABORT Command The ABORT command is sent from the host to abort all pending operations at the target. The target responds with ABORT_DONE. This is primarily intended to stop large data transfers from the target. A likely application would be during a debugging session when the user types an interrupt to abort a large printout of data from the target. The ABORT command has no effect on any breakpoints or watchpoints that may be enabled in the target. As a practical matter, the ABORT command may be difficult to implement on some targets. Its ability to interrupt command processing on the target depends on the target being able to look ahead at incoming commands and receive an out-of-band signal from the host. However, the effect of an ABORT may be achieved by simply closing and reopening the transport connection. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | PROTOCOL | ABORT | +---------------+---------------+ ABORT Command Format Figure 21 5.6 ABORT_DONE Reply The ABORT_DONE reply is sent from the target to the host in response to an ABORT command. This indicates that the target has terminated all operations that were pending when the ABORT command was received. The sequence number of the ABORT command is included in the reply. Page 35  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | PROTOCOL | ABORT_DONE | +---------------+---------------+ 2 | Sequence Number | +---------------+---------------+ ABORT_DONE Reply Format Figure 22 ABORT_DONE FIELDS: Sequence Number The sequence number of the ABORT command that elicited this reply. This enables the host to distinguish between replies to multiple aborts. 5.7 ERROR Reply The ERROR reply is sent by the target in response to a bad command. The ERROR reply gives the sequence number of the offending command and a reason code. The target ignores further commands until an ERRACK command is received. The reason for ignoring commands is that the proper operation of outstanding commands may be predicated on the execution of the erroneous command. Page 36  LDP Specification Protocol Commands 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | PROTOCOL | ERROR | +---------------+---------------+ 2 | Command Sequence Number | +---------------+---------------+ 3 | Error code | +---------------+---------------+ 4 | Optional Data | +---------------+---------------+ * * * +---------------+---------------+ n | Optional Data | +---------------+---------------+ ERROR Reply Format Figure 23 ERROR Reply FIELDS: Command Sequence Number The implicit sequence number of the erroneous command. Error Code A code specifying what error has taken place. The currently defined codes are shown in Figure 24. Page 37  RFC-909 July 1984 Error Code | Symbol -----------+------------------------ 1 BAD_COMMAND 2 BAD_ADDRESS_MODE 3 BAD_ADDRESS_ID 4 BAD_ADDRESS_OFFSET 5 BAD_CREATE_TYPE 6 NO_RESOURCES 7 NO_OBJECT 8 OUT_OF_SYNCH 9 IN_BREAKPOINT ERROR Codes Figure 24 An explanation of each of these error codes follows: BAD_COMMAND The command was not meaningful to the target machine. This includes commands that are valid but unimplemented in this target. Also, the command was not valid in this context. For example, a command given by the host that is only legal in a breakpoint (e.g. IF, SET_STATE). BAD_ADDRESS_MODE The mode of an address given in the command is not meaningful to this target system. For example, a PROCESS address mode on a target that does not support multi-processing. BAD_ADDRESS_ID The ID field of an address didn't correspond to an appropriate thing. For example, for a PROCESS address mode, the ID of a non-existent process. BAD_ADDRESS_OFFSET The offset field of the address was outside the legal range for the thing addressed. For example, an offset of 200,000 in PHYS_MACRO mode on a target with 64K of Page 38  LDP Specification Protocol Commands macro-memory. BAD_CREATE_TYPE The object type in a CREATE command was unknown. NO_RESOURCES A CREATE command failed due to lack of necessary resources. NO_OBJECT A GET_OBJECT command failed to find the named object. OUT_OF_SYNCH The sequence number of the SYNCH command was not expected by the target. The target has resynchronized to it. IN_BREAKPOINT [] An error occurred within a breakpoint command list. The given 16-bit sequence-number refers to the sequence number of the CREATE command that created the breakpoint, while breakpoint-sequence# refers to the sequence number of the command within the breakpoint given by . 5.8 ERRACK Acknowledgement An ERRACK is sent by the host in response to an ERROR reply from the target. The ERRACK is used to acknowledge that the host has received the ERROR reply. Page 39  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | PROTOCOL | ERRACK | +---------------+---------------+ ERRACK Command Format Figure 25 Page 40  LDP Specification Data Transfer Commands CHAPTER 6 Data Transfer Commands Data transfer commands transfer data between the host and the target. These commands are used for loading and dumping the target, and examining and depositing locations on the target. The READ command reads data from the target, the MOVE command moves data within the target or from the target to another entity, and the WRITE command writes data to the target. REPEAT_DATA makes copies of a pattern to the target -- it is useful for zeroing memory. WRITE_MASK writes data with a mask, and is intended for modifying target parameter tables. Data transmitted to and from the target always contains a target address. In writes to the target, this is used as the destination of the data. In reads from the target, the target address is used by the host to identify where in the target the data came from. In addition, the MOVE command may contain a 'host' address as its destination; this permits the host to further discriminate between possible sources of data from the target -- from different breakpoints, debugging windows, etc. A read request to the target may generate one or more response messages. In particular, responses to requests for large amounts of data -- core dumps, for example -- must be broken up into multiple messages, if the block of data requested plus the LDP header exceeds the transport layer message size. In commands which contain data (WRITE, READ_DATA, MOVE_DATA and REPEAT_DATA), if there are an odd number of data octets, then a null octet is appended. This is so that the next command in the message, if any, will begin on an even octet. The command length is the sum of the number of octets in the command header and the number of octets of data, excluding the null octet, if any. The addressing formats which may be used with data transfer commands are specified for each LDP session at the start of the session by the target in the HELLO_REPLY response. See the section entitled 'Addressing', above, for a description of LDP addressing formats and modes. In the command diagrams given below, the short addressing format is illustrated. For LDP sessions using long addressing, addresses are five words long, Page 41  RFC-909 July 1984 instead of three words, as shown here. In both addressing modes, descriptors are three words and offsets are two words. 6.1 WRITE Command The WRITE command is used to send octets of data from the host to the target. This command specifies the address in the target where the data is to be stored, followed by a stream of data octets. If the data stream contains an odd number of octets, then a null octet is appended so that the next command, if any, will begin on an even octet. Since LDP must observe message size limitations imposed by the underlying transport layer, a single logical write may need to be broken up into multiple WRITEs in separate transport messages. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | WRITE | +---------------+---------------+ 2 | | +-- Target --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ 5 | Data Octet | Data Octet | +---------------+---------------+ * * * +---------------+---------------+ n | Data Octet | Data or Null | +---------------+---------------+ WRITE Command Format Figure 26 Page 42  LDP Specification Data Transfer Commands WRITE FIELDS: Command Length The command length gives the number of octets in the command, including data octets, but excluding the padding octet, if any. Target Start Address This is the address to begin storing data in the target. The length of the data to be stored may be inferred by the target from the command length. An illegal address or range will generate an ERROR reply. Data Octets Octets of data to be stored in the target. Data are packed according to the packing convention described above. Ends with a null octet if there are an odd number of data octets. 6.2 READ Command The host uses the READ command to ask the target to send back a contiguous block of data. The data is specified by a target starting address and a count. The target returns the data in one or more READ_DATA commands, which give the starting address (in the target) of each segment of returned data. When the transfer is completed, the target sends a READ_DONE command to the host. Page 43  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 14 | +---------------+---------------+ 1 | DATA_TRANSFER | READ | +---------------+---------------+ 2 | | +-- Target --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ 5 | Address | +-- Unit --+ 6 | Count | +---------------+---------------+ READ Command Format Figure 27 READ FIELDS: Target Start Address The starting address of the requested block of target data. The target sends an ERROR reply if the starting address is illegal, if the ending address computed from the sum of the start and the count is illegal, or if holes are encountered in the middle of the range. Address Unit Count The count of the number of target indivisibly-addressable units to be transferred. For example, if the address space is PHYS_MACRO, a count of two and a start address of 1000 selects the contents of locations 1000 and 1001. 'Count' is used instead of 'length' to avoid the problem of determining units the length should be denominated in (octets, words, etc.). The size and type of the unit will vary depending on the address space selected by the target start address. The target should reply with an error (if it is able to Page 44  LDP Specification Data Transfer Commands determine in advance of a transfer) if the inclusive range of addresses specified by the start address and the count contains an illegal or nonexistent address. 6.3 READ_DATA Response The target uses the READ_DATA response to transmit data requested by a host READ command. One or more READ_DATA responses may be needed to fulfill a given READ command, depending on the size of the data block requested and the transport layer message size limits. Each READ_DATA response gives the target starting address of its segment of data. If the response contains an odd number of data octets, the target ends the response with a null octet. Page 45  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | READ_DATA | +---------------+---------------+ 2 | | +-- Target --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ +-+ 5 | Data Octet | Data Octet | | +---------------+---------------+ | * | * | Data * | +---------------+---------------+ | n | Data Octet | Data or Null | | +---------------+---------------+ +-+ DATA Response Format Figure 28 READ_DATA FIELDS: Command Length The command length gives the number of octets in the command, including data octets, but excluding the padding octet, if any. The host can calculate the length of the data by subtracting the header length from the command length. Since the target address may be either three words (short format) or five words (long format), the address mode must be checked to determine which is being used. Target Start Address This is the starting address of the data segment in this message. The host may infer the length of the data from the command length. The address format (short or long) is the Page 46  LDP Specification Data Transfer Commands same as on the initial READ command. Data Octets Octets of data from the target. Data are packed according to the packing convention described above. Ends with a null octet if there are an odd number of data octets. 6.4 READ_DONE Reply The target sends a READ_DONE reply to the host after it has finished transferring the data requested by a READ command. READ_DONE specifies the sequence number of the READ command. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 6 | +---------------+---------------+ 1 | DATA_TRANSFER | READ_DONE | +---------------+---------------+ 2 | READ Sequence Number | +---------------+---------------+ READ_DONE Reply Format Figure 29 READ_DONE FIELDS: READ Sequence Number The sequence number of the READ command this is a reply to. Page 47  RFC-909 July 1984 6.5 MOVE Command The MOVE command is sent by the host to move a block of data from the target to a specified destination. The destination address may specify a location in the target, in the host, or in another target (for loading one target from another). The data is specified by a target starting address and an address unit count. The target sends an ERROR reply if the starting address is illegal, if the ending address computed from the sum of the start and the count is illegal, or if holes are encountered in the middle of the range. If the MOVE destination is off-target, the target moves the data in one or MOVE_DATAs. Other commands arriving at the target during the transfer should be processed in a timely fashion, particularly the ABORT command. When the data has been moved, the target sends a MOVE_DONE to the host. However, a MOVE within a breakpoint will not generate a MOVE_DONE. A MOVE with a host destination differs from a READ in that it contains a host address. This field is specified by the host in the MOVE command and copied by the target into the responding MOVE_DATA(s). The address may be used by the host to differentiate data returned from multiple MOVE requests. This information may be useful in breakpoints, in multi-window debugging and in communication with targets with multiple processors. For example, the host sends the MOVE command to the target to be executed during a breakpoint. The ID field in the host address might be an index into a host breakpoint table. When the breakpoint executes, the host would use the ID to associate the returning MOVE_DATA with this breakpoint. Page 48  LDP Specification Data Transfer Commands 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | MOVE | +---------------+---------------+ 2 | | +-- Source --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ 5 | Address | +-- Unit --+ 6 | Count | +---------------+---------------+ 7 | | +-- Destination --+ 8 | Start | +-- Address --+ 9 | | +---------------+---------------+ MOVE Command Format Figure 30 MOVE FIELDS: Source Start Address The starting address of the requested block of target data. An illegal address type will generate an error reply. Address Unit Count The count of the number of target indivisibly-addressable units to be transferred. For example, if the address space is PHYS_MACRO, a count of two and a start address of 1000 selects the contents of locations 1000 and 1001. 'Count' is used instead of 'length' to avoid the problem of determining units the length should be denominated in (octets, words, Page 49  RFC-909 July 1984 etc.). The size and type of the unit will vary depending on the address space selected by the target start address. The target should reply with an error (if it is able to determine in advance of a transfer) if the inclusive range of addresses specified by the start address and the count contains an illegal or nonexistent address. Destination Address The destination of the MOVE. If the address space is on the target, the address unit size should agree with that of the source address space. If the address mode is HOST, the values and interpretations of the remaining address fields are arbitrary, and are determined by the host implementation. For example, the mode argument might specify a table (breakpoint, debugging window, etc.) and the ID field an index into the table. 6.6 MOVE_DATA Response The target uses the MOVE_DATA responses to transmit data requested by a host MOVE command. One or more MOVE_DATA responses may be needed to fulfill a given MOVE command, depending on the size of the data block requested and the transport layer message size limits. Each MOVE_DATA response gives the target starting address of its segment of data. If the response contains an odd number of data octets, the target should end the response with a null octet. Page 50  LDP Specification Data Transfer Commands 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | MOVE_DATA | +---------------+---------------+ 2 | | +-- Source --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ 5 | | +-- Destination --+ 6 | Start | +-- Address --+ 7 | | +---------------+---------------+ +-+ 8 | Data Octet | Data Octet | | +---------------+---------------+ | * | * | Data * | +---------------+---------------+ | n | Data Octet | Data or Null | | +---------------+---------------+ +-+ MOVE_DATA Response Format Figure 31 MOVE_DATA FIELDS: Command Length The command length gives the number of octets in the command, including data octets, but excluding the padding octet, if any. Source Start Address This is the starting address of the data segment in this Page 51  RFC-909 July 1984 message. The host may infer length of the data from the command length. Destination Address The destination address copied from the MOVE command that initiated this transfer. In the case of HOST MOVEs, this is used by the host to identify the source of the data. Data Octets Octets of data from the target. Data are packed according to the packing convention described above. Ends with a null octet if there are an odd number of data octets. 6.7 MOVE_DONE Reply The target sends a MOVE_DONE reply to the host after it has finished transferring the data requested by a MOVE command. MOVE_DONE specifies the sequence number of the MOVE command. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 6 | +---------------+---------------+ 1 | DATA_TRANSFER | MOVE_DONE | +---------------+---------------+ 2 | MOVE Sequence Number | +---------------+---------------+ MOVE_DONE Reply Format Figure 32 MOVE_DONE FIELDS: MOVE Sequence Number The sequence number of the MOVE command this is a reply to. Page 52  LDP Specification Data Transfer Commands 6.8 REPEAT_DATA The REPEAT_DATA command is sent by the host to write copies of a specified pattern into the target. This provides an efficient way of zeroing target memory and initializing target data structures. The command specifies the target starting address, the number of copies of the pattern to be made, and a stream of octets that constitutes the pattern. This command differs from the other data transfer commands in that the effect of a REPEAT_DATA with a large pattern cannot be duplicated by sending the data in smaller chunks over several commands. Therefore, the maximum size of a pattern that can be copied with REPEAT_DATA will depend on the message size limits of the transport layer. 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | REPEAT_DATA | +---------------+---------------+ 2 | | +-- Target --+ 3 | Start | +-- Address --+ 4 | | +---------------+---------------+ 6 | Repeat Count | +---------------+---------------+ +-+ 7 | Data Octet | Data Octet | | +---------------+---------------+ | * | * | Pattern * | +---------------+---------------+ | n | Data Octet | Data or Null | | +---------------+---------------+ +-+ REPEAT_DATA Command Format Figure 33 Page 53  RFC-909 July 1984 REPEAT_DATA FIELDS: Command Length The command length gives the number of octets in the command, including data octets in the pattern, but excluding the padding octet, if any. Target Start Address This is the starting address where the first copy of the pattern should be written in the target. Successive copies of the pattern are made contiguously starting at this address. Repeat Count The repeat count specifies the number of copies of the pattern that should be made in the target. The repeat count should be greater than zero. Pattern The pattern to be copied into the target, packed into a stream of octets. Data are packed according to the packing convention described above. Ends with a null octet if there are an odd number of data octets. 6.9 WRITE_MASK Command (Optional) The host sends a WRITE_MASK command to the target to write one or more masked values. The command uses an address to specify a target base location, followed by one or more offset- mask-value triplets. Each triplet gives an offset from the base, a value, and a mask indicating which bits in the location at the offset are to be changed. This optional command is intended for use in controlling the target by changing locations in a table. For example, it may be used to change entries in a target parameter table. The operation of modifying a specified location with a masked value is intended to be atomic. In other words, another target process should not be able to access the location to be modified between Page 54  LDP Specification Data Transfer Commands the start and the end of the modification. Page 55  RFC-909 July 1984 0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | Command Length | +---------------+---------------+ 1 | DATA_TRANSFER | WRITE_MASK | +---------------+---------------+ 2 | | +-- Target --+ 3 | Base | +-- Address --+ 4 | | +---------------+---------------+ +-+ 5 | | | +-- Offset --+ | 6 | | | +---------------+---------------+ | Offset-Mask-Value 7 | | | Triplet +-- Mask --+ | 8 | | | +---------------+---------------+ | 9 | | | +-- Value --+ | 10| | | +---------------+---------------+ +-+ * * * +---------------+---------------+ +-+ | | | +-- Offset --+ | | | | +---------------+---------------+ | Offset-Mask-Value | | | Triplet +-- Mask --+ | | | | +---------------+---------------+ | | | | +-- Value --+ | | | | +---------------+---------------+ +-+ WRITE_MASK Format Figure 34 Page 56  LDP Specification Data Transfer Commands WRITE_MASK FIELDS: Command Length The command length gives the number of octets in the command. The number of offset-value pairs may be calculated from this, since the command header is either 10 or 12 octets long (short or long address format), and each offset-mask-value triplet is 12 octets long. Target Base Address Specifies the target location to which the offset is added to yield the location to be modified. Offset An offset to be added to the base to select a location to be modified. Mask Specifies which bits in the value are to be copied into the location. Value A value to be stored at the specified offset from the base. The set bits in the mask determine which bits in the value are applied to the location. The following algorithm will achieve the intended result: take the one's complement of the mask and AND it with the location, leaving the result in the location. Then AND the mask and the value, and OR the result into the location. Page 57  RFC-909 July 1984 Page 58  LDP Specification Control Commands CHAPTER 7 Control Commands Control commands are used to control the execution of target code, breakpoints and watchpoints. They are also used to read and report the state of these objects. The object to be controlled or reported on is specified with a descriptor. Valid descriptor modes include PHYS_* (for some commands) PROCESS_CODE, BREAKPOINT and WATCHPOINT. Control commands which change the state of the target are START, STOP, CONTINUE and STEP. REPORT requests a STATUS report on a target object. EXCEPTION is a spontaneous report on an object, used to report asynchronous events such as hardware traps. The host may verify the action of a START, STOP, STEP or CONTINUE command by following it with a REPORT command. 7.1 START Command The START command is sent by the host to start execution of a specified object in the target. For targets which support multiple processes, a PROCESS_CODE address specifies the process to be started. Otherwise, one of the PHYS_* modes may specify a location in macro-memory where execution is to continue. Applied to a breakpoint or watchpoint, START sets the value of the object's state variable, and activates the breakpoint. The breakpoint counter and pointer variables are initialized to zero. Page 59  RFC-909