RFC 909
Loader Debugger Protocol
RFC-909: Loader Debugger Protocol 🎀
okay bestie, welcome to RFC-909 💖 This one is the Loader Debugger Protocol, and it's literally a whole protocol for debugging loaders over a network 🧚
The authors are Christopher Welles (BBN Communications Corporation) and Walter Milliken (BBN Laboratories). It was published in July 1984 🌸
The category is a proposed protocol for the ARPA Internet community. The title block doesn't list anything this document obsoletes or updates, so there's no older RFC it's replacing or patching 🦋
Status of This Memo ✨
ok so this RFC is a proposed protocol for the ARPA Internet community 💅 It's asking people to talk about it and send over ideas for making it better 🫶 Anyone can distribute this memo, with no limits 🌈
Table of Contents 🧚
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 iiiFigures 🌸
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 v1. Introduction ✨
the chapter 1 body picks up in the next part, so stay tuned bestie 💜
The Loader-Debugger Protocol (LDP) is the app-layer protocol that lets a host load, dump, and debug target machines across a network 💖 It's built to work with a bunch of different target CPU types, and it has seriously powerful debugging services. ✨ The clever part is that you can strip it down to a tiny subset for things like boot loading, where space and efficiency matter most 🧚
Huge thanks to Dan Franklin and Peter Cudhea 🫶 for bringing so many of the ideas this protocol is built on!
1.1. Purpose of This Document
This is the real-deal technical spec for LDP 📜 It's detailed enough that implementors can build from it, with full descriptions of the formats and usage for over forty commands. If you just want the big picture, read the Summary of Features below and skim Sections 2 through 3.1. Also check out Appendix B, the Command Summary 🍓 The rest of it reads best with strong coffee or tea ☕
Page 1
1.2. Summary of Features
LDP has the following features:
- commands to perform loading, dumping and debugging 💅
- support for multiple connections to a single target 🦋
- reliable performance in an internet environment 🌈
- a small protocol subset for target loaders 🎀
- addressing modes and commands to support multiple machine types 👑
- breakpoints and watchpoints which run in the target machine 🔥
Page 2
2. General Description ✨
2.1. Motivation
LDP is an application protocol that gives application programs a set of commands for loading, dumping and debugging target machines across a network 🌸
Here are the goals LDP is going for:
- The protocol should support various processor types and operating systems. Overhead and complexity should be minimized for simpler cases. 💖
- The protocol should support applications where more than one user can debug the same target machine. That implies an underlying transport mechanism that supports multiple connections between a host-target pair. 👯♀️
- LDP should have a minimal subset of commands for boot loading and dumping. Target machine implementations of these applications are often limited in how much code-space they can take, so the services needed for loading and dumping should live in a small, easy-to-implement set of commands 🧚
- There should be a way to communicate exceptions and errors from the target LDP process to the host process 🙈
- LDP should let the application 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 won't be able to keep up with the real-time demands of its application 💀
Page 3
2.2. Relation to Other Protocols
LDP is an application protocol that fits right into the layered internet protocol environment 🦋 Figure 1 shows where LDP sits 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
2.2.1. Transport Service Requirements
Here's what LDP needs from the transport layer underneath it 🫧
- allow connections to be opened by specifying a network (or internet) address. Support passive and active opens.
- for each connection, specify the maximum message size.
- provide a mechanism for sending and receiving messages over an open connection.
- deliver messages reliably and in sequence.
- 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.
- explicitly 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 goes from the application program to the LDP user process in the form of commands. On an LDP server process, command responses come from LDP itself. Below LDP is the transport protocol, and the Reliable Data Protocol (RDP -- RFC 908) is the recommended one 💅 Data crosses the LDP/RDP interface in the form of messages. (TCP may be used in place of RDP, but it will be less efficient and will require more resources to implement.) An internet layer (IP) normally sits 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
+------+
| |
|Appli-|
|cation|
| |
+------+
^
Commands |
V
+------+
| |
| LDP |
| |
+------+
^
Messages |
V
+-----+
| |
| RDP |
| |
+-----+
^
Segments |
V
+----+
| |
| IP |
| |
+----+
^
Datagrams |
V
? * !
$ = ^ +
*
> Internet
, ?
! )
* % $Form of Data Exchange Between Layers Figure 2
Page 6
Page 7
Page 8
3. Protocol Operation ✨
3.1. Overview
An LDP session is an exchange of commands and responses between an LDP user process and an LDP server process 🧚 Usually the user process lives on a host machine (a timesharing computer used for network monitoring and control), and the server process lives 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 runs the show by sending commands to the target. Some commands get responses, and all commands may get an error reply 👑
The protocol has five classes of commands: protocol, data transfer, management, control and breakpoint. Protocol commands verify the command sequencing mechanism and handle erroneous commands. Data transfer commands move data from one place to another, like memory examine/deposit or loading. Management commands create and delete objects (processes, breakpoints, watchpoints, etc.) in the target machine. Control commands control the execution of target code and breakpoints. Breakpoint commands control the execution of commands inside breakpoints and watchpoints 🌸
3.2. Session Management
An LDP session is 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. Once the connection is up, 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 type, and address format. The session ends 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 💜
Page 9
The target process is the passive partner in an LDP session 🦋. It just waits for the host process to be the one that ends things. As an implementation thing, either LDP or the transport protocol underneath should have a way to notice when the host process has died 💀. Otherwise, a target that only supports one connection could get totally stuck because a host crashed in the middle of a session 😭. You can dodge the half-dead connection problem with a different move: the target could let new connections usurp inactive ones. A connection with no activity could be declared 'dead', but it wouldn't get usurped until the connection resource was actually needed 👑. Still, this means the transport layer needs to support two connection channels: one for receiving connection requests, and another for the active connection ✨.
3.3. Command Sequencing
Every command the host sends gets a sequence number 🔢. The target uses that number to refer to the command in normal replies and error replies. To save space, the numbers aren't actually included in host commands. Instead, each command sent from the host gets an implicit sequence number. It starts at zero at the beginning of the LDP session and goes up by one for each command sent. The host and target each keep track of the current number. The host can use the SYNCH <sequence number> command to synchronize the sequence number 🫶.
3.4. Data Packing and Transmission
Okay, the order for packing data was picked for its simplicity 🍓. Data gets 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.
Data is 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, like 16-bit macromemory, 32-bit micromemory, 10-bit dispatch memory, and so on. 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 matches the diagrams, 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, 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 3Packing for targets with peculiar word lengths is trickier 🙈. For 20-bit machines, 2 words of data are packed into 5 octets. When an odd number of 20-bit words is 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 43.5. Implementations
A subset of LDP commands may be implemented in targets where machine resources are limited and the full capabilities of LDP aren't needed 🌸. There are three basic levels of target implementations: LOADER_DUMPER, BASIC_DEBUGGER and FULL_DEBUGGER. The target tells the host which LDP implementation level it has during session initiation. The levels are described below:
LOADER_DUMPER
Used for loading and dumping of the target machine. It includes all protocol class commands and replies, data transfer commands READ, WRITE, MOVE and their responses, control command START, and control reply EXCEPTION. It understands at least PHYS_MACRO and HOST addressing modes. Others are fine if desired 💜.
BASIC_DEBUGGER
It implements LOADER_DUMPER commands, all control commands, and all addressing modes appropriate to the target machine. However, it does not have finite state machine (FSM) breakpoints or watchpoints. Default breakpoints are implemented. The target understands long addressing mode 🔍.
FULL_DEBUGGER
It implements all commands and addressing modes appropriate to the target machine, and includes breakpoint commands, conditional commands and BREAKPOINT_DATA. Watchpoints are optional 👑.
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 54.2. Command Format
LDP commands consist of a standard two-word header followed optionally by additional data 🎀. To make parsing multi-command messages easier, 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 meant to be of universal application, giving 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 6Header 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 and Command Type
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 rest 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 | <reserved>
Command Classes
Figure 7Command type codes are assigned in order of expected frequency of use. Commands and their responses or replies are numbered sequentially. The command types, ordered by command class, are:
Okay bestie, the big command table is up next 🦋 Every command class, type, and symbol is listed below, so you can see the whole family tree at once ✨
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 | <reserved>
| |
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 | <reserved>
| |
CONTROL | 1 | START
| 2 | STOP
| 3 | CONTINUE
| 4 | STEP
| 5 | REPORT
| 6 | STATUS
| 7 | EXCEPTION
| 8 - 63 | <reserved>
| |
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
| 13 | LIST_NAMES
| 14 | NAME_LIST
| 15 | LIST_PROCESSES
| 16 | PROCESS_LIST
| 17 - 63 | <reserved>
| |
BREAKPOINT | 1 | INCREMENT
| 2 | INC_COUNT
| 3 | OR
| 4 | SET_PTR
| 5 | SET_STATE
| 6 - 63 | <reserved>
| |
CONDITION | 1 | CHANGED
| 2 | COMPARE
| 3 | COUNT_EQ
| 4 | COUNT_GT
| 5 | COUNT_LT
| 6 | TEST
| 7 - 63 | <reserved>
Command Types
Figure 84.3. Addressing 📍
Addresses are the little pins that LDP commands use to point at memory locations, processes, buffers, breakpoints, and other entities 🗺️ Here's the tea: many of these things depend on the machine. Some machines have named objects, some have multiple address spaces, and the size of those spaces varies all over the place. So the format for specifying addresses needs to be general enough to handle all of those cases 💅 That points toward a large, hierarchically structured address format. The catch? A big format means extra overhead when you're talking to targets with simpler address schemes 😭
LDP handles this conflict by using two address formats 🎀 There's a short three-word format for simpler targets, and a long five-word format for everyone else. Each target LDP is required to implement at least one of these formats. At the start of an LDP session, the target tells you which address format(s) it uses, and it does that in the Flag field of the HELLO_REPLY message. Inside each address, the first bit of the mode octet is the format flag: 0 means LONG address format, and 1 means SHORT format ✨
Page 19
4.3.1. Long Address Format 🌈
The long address format is five words long. It's made of a three-word address descriptor plus a two-word offset (see Figure 9) 🧚 The descriptor picks out the address space that the offset gets applied to. It's broken into several fields, and the structure is designed to support complex addressing modes. On targets with multiple processes, for example, descriptors can point at virtual addresses, registers, and other entities inside a particular process 🤯
The addressing modes defined below are a base that target-specific modes can be added to. 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 9LONG ADDRESS FIELDS: 🍓
Page 20
Mode 🔥
The address mode tells you what type of address space is being referenced. The mode is qualified by the mode argument and the ID field. Implementing modes other than physical and host is machine-dependent. The currently defined modes, and the address space each one references, 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 - <reserved>
63
Long Address Modes
Figure 10Mode Argument 💖
Page 21
Provides a numeric argument to the mode field. It specifies the register in the 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 how many significant bits the offset has. 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 that have this mode as the destination are sent by the target to the host. This may happen 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
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, and the offset points into the code space for that process. ✨ The mode argument isn't used here, so you can ignore it. 🧚
PROCESS_DATA 💖
The ID is a process ID, and the offset points into the data space for that process. The mode argument isn't used. On systems that don't distinguish between code and data space, these two modes are equivalent and both reference the process's virtual address space. 🌸
PROCESS_DATA_PTR 🎀
The offset holds the address of a pointer in the data space of the process named by the ID. The location it points to, which is the effective address, is also in the data space. The mode argument isn't used. 🦋
PROCESS_REG 💅
This one accesses the registers, plus other system data, of the process named 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. 👑
PROCESS_REG_OFFSET 🫶
The offset plus the contents of the register named in the mode argument gives a location in the data space of the process named by the ID. ⭐
PROCESS_REG_INDIRECT 🔥
The register named in the mode argument 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 by that pointer, plus the offset. 🌈
OBJECT_OFFSET (optional) 🍓
The offset is into the memory space defined by the object ID in ID. This is recommended for remote control of parameter segments. 🧚
OBJECT_HEADER (optional) 💜
The offset is into the system header for the object named by the ID. This is intended for use with the Butterfly. 🦋
BREAKPOINT 🙈
The descriptor specifies a breakpoint. The offset is never used. This type is only used in descriptors that refer 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 that refer 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 that manipulates them, give you an arbitrary amount of address indirection. They're meant for traversing data structures, like chasing queues. In BPT_PTR_OFFSET, the offset is added to the pointer variable to give the effective address. On targets that 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. The BPT_PTR.* modes are valid only in breakpoints and watchpoints. 🧠💅
BPT_PTR_INDIRECT 🌸
This is like BPT_PTR_OFFSET, except it uses one more level of indirection. The pointer variable given by the mode argument, plus the offset, specifies an address that 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 meant for implementations where protocol overhead has to be kept as small as possible. 🍓 It's a subset of the long address format. It contains the same fields except for the ID field, so the short address 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, made up of a 16-bit word describing the address space and a 32-bit offset. 💜
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, which indicates the short address format. The supported address modes are listed below. The rest of the fields are interpreted the same way as described above for the long addressing format. 💖
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 <reserved>Short Address Modes (Figure 12)
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, and replies flow 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 tells the host about the target's implementation of LDP. ✨
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 doesn't 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. 🦋
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 MacIntoshSystem Types (Figure 15)
Address Code 🫶
The address code indicates which LDP address format(s) the target is prepared to use. Address codes are shown 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 🔥
The implementation level is basically the feature menu a target supports 💅 There are three levels of protocol implementation, and they're built around the three most likely LDP use cases: simple loading and dumping, basic debugging, and full debugging 🎀 (For the full breakdown, check the Implementations section above 📖) BUT there are also a few optional features that don't belong to any level, so they just float on their own ✨
Levels stack, bestie 🥞 Each higher level includes everything from the levels below it. Here's the lineup 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 breakpointsFeature Levels, Figure 17 🦋
Options
The options field (Figure 18) is an eight-bit flag field 🚩 Each bit tells you whether the target has implemented a particular optional command. Not every optional command gets a flag here, though. Commands that depend on target machine features are left out. The LDP application is expected to know about target features that aren't intrinsic to the protocol itself 🧠 Examples of these target-dependent commands are the ones that refer to named objects, like CREATE and LIST_NAMES 👀
Mask | Symbol | Description
------+-------------+---------------+-----------------
1 STEP The STEP command is implemented
2 WATCHPOINTS Watchpoints are implementedOptions, Figure 18 💚
5.3 SYNCH Command ✨
Okay, the SYNCH command is sent by the host to the target, and the target answers with a SYNCH_REPLY 💌 This back-and-forth does two jobs at once: it syncs up the host-to-target implicit sequence number, and it works as a cumulative acknowledgement that the target got and ran every host command up to that 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: this is the sequence number of this command. If it isn't what the target is expecting, the target resets to it and replies with an ERROR reply 😬
5.4 SYNCH_REPLY ✨
A SYNCH_REPLY is sent by the target in response to a valid SYNCH command 💖 A SYNCH command counts as valid only if its sequence number matches the one the target is expecting. If it doesn't match, the target resets its sequence number to the one in the SYNCH command and sends back 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 this SYNCH_REPLY is responding to 🧚
5.5 ABORT Command ✨
The ABORT command is sent from the host to abort all pending operations at the target 🛑 The target replies with ABORT_DONE. This is mainly for stopping big data transfers coming from the target 📦 Picture this: you're debugging, you hit interrupt to kill a massive printout of data from the target, and ABORT is what makes that happen 😭 ABORT has no effect on any breakpoints or watchpoints that are enabled in the target, so those stay put 🦋
ngl, ABORT can be a real pain to implement on some targets 💀 Whether it works depends on the target being able to look ahead at incoming commands and catch an out-of-band signal from the host. BUT the same effect can 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 🫡 It tells the host that the target has finished every operation that was pending when the ABORT arrived. The sequence number of the ABORT command is included in the reply too 🧾
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 triggered this reply. This is how the host tells replies apart when there are multiple aborts going on 🙌
5.7 ERROR Reply ✨
The ERROR reply is sent by the target in response to a bad command 🚨 It includes the sequence number of the offending command and a reason code. The target ignores any further commands until it receives an ERRACK command 🙅♀️ Why? Because the proper operation of outstanding commands might depend on that erroneous command having run 🧩
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 that specifies what error happened. The currently defined codes are in Figure 24 🗂️
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_BREAKPOINTERROR Codes, Figure 24 💜
Here's what each error code means 🕵️♀️
BAD_COMMAND: the command wasn't meaningful to the target machine. That includes commands that are valid but not implemented on this target, and commands that aren't valid in this context. For example, a command from the host that's only legal inside a breakpoint, like IF or SET_STATE 🙃
BAD_ADDRESS_MODE <offending-address>: the mode of an address in the command isn't meaningful to this target system. For example, a PROCESS address mode on a target that doesn't support multi-processing 🧵
BAD_ADDRESS_ID <offending-address>: the ID field of an address didn't match an appropriate thing. For example, with a PROCESS address mode, the ID of a process that doesn't exist 👻
BAD_ADDRESS_OFFSET <offending-address>: the offset field of the address is outside the legal range for the thing being addressed. For example, an offset of 200,000 in PHYS_MACRO mode on a target with 64K of macro-memory 📏
BAD_CREATE_TYPE: the object type in a CREATE command was unknown 🤷♀️
NO_RESOURCES: a CREATE command failed because it didn't have the resources it needed 🪫
NO_OBJECT: a GET_OBJECT command couldn't find the named object 🔍
OUT_OF_SYNCH: the sequence number of the SYNCH command wasn't the one the target expected. The target has resynchronized to it 🔁
IN_BREAKPOINT <breakpoint-descriptor> <breakpoint-sequence#> <reason-code> [<optional-info>]: this is the format for the IN_BREAKPOINT error 📋
An error happened inside a breakpoint command list 💀 The given 16-bit sequence-number points to the sequence number of the CREATE command that made the breakpoint. breakpoint-sequence# points to the sequence number of the command inside that breakpoint, the one given by <breakpoint-descriptor>. So you can tell exactly which command caused the problem 🔍✨
5.8. ERRACK Acknowledgement ✨
An ERRACK is sent by the host in response to an ERROR reply from the target. Its whole job is to say "yep, I got your ERROR reply" 💅 It's the host acknowledging that it received that ERROR 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 | ERRACK |
+---------------+---------------+
ERRACK Command Format
Figure 256. Data Transfer Commands 🦋
Data transfer commands are how data moves between the host and the target, and they're literally the reason anyone is debugging anything 🔥 They're used for loading and dumping the target, and for examining and depositing locations on it. READ pulls data from the target. MOVE moves data within the target or from the target to another entity. WRITE writes data to the target. REPEAT_DATA makes copies of a pattern to the target, which is useful for zeroing memory 🧹 WRITE_MASK writes data with a mask, and it's meant for modifying target parameter tables 🎀
Data sent to and from the target always contains a target address 📍 For writes to the target, that address is the destination. For reads from the target, the host uses the address to figure out where in the target the data came from. The MOVE command can also include a 'host' address as its destination, which lets the host tell apart different sources of data from the target, like different breakpoints, debugging windows, and so on 👑
A read request to the target may generate one or more response messages 📬 Responses to big requests, like core dumps, must be broken up into multiple messages if the requested block of data plus the LDP header is bigger than the transport layer message size 🌊
In commands that contain data (WRITE, READ_DATA, MOVE_DATA and REPEAT_DATA), if there's an odd number of data octets, a null octet gets added at the end. This makes sure the next command in the message, if there is one, starts on an even octet 🧠 The command length is the number of octets in the command header plus the number of data octets. It doesn't count the null octet, if there is one 🙈
The addressing formats you can use with data transfer commands are set for each LDP session at the start, when the target sends them in the HELLO_REPLY response. Check the section called 'Addressing' above for the full scoop on LDP addressing formats and modes 📖 In the command diagrams below, the short addressing format is shown. LDP sessions using long addressing have addresses that are five words long instead of three. Either way, descriptors are three words and offsets are two words 🌸
6.1. WRITE Command 💖
The WRITE command sends octets of data from the host to the target. It specifies the address in the target where the data should be stored, followed by a stream of data octets. If the data stream has an odd number of octets, a null octet gets appended so that the next command, if there is one, starts on an even octet 🍓 LDP has to respect the message size limits of the underlying transport layer, so one logical write might need to be split into multiple WRITEs sent 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 26WRITE FIELDS
Command Length
The command length tells you how many octets are in the command, counting the data octets but not the padding octet, if there is one ✨
Target Start Address
This is the address where the target should start storing data 📍 The target can work out how long the data is from the command length. If the address or range is illegal, the target sends back an ERROR reply 🚨
Data Octets
These are the octets of data to be stored in the target. The data is packed according to the packing convention described above 🧃 If there's an odd number of data octets, it ends with a null octet 💅
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, and each one gives the starting address (in the target) of its segment of returned data 🧩 When the transfer is done, the target sends a READ_DONE command to the host 🏁
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 27READ FIELDS
Target Start Address
This is 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 there are holes in the middle of the range 🙅♀️
Address Unit Count
This is the count 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 select the contents of locations 1000 and 1001 💕 Count is used instead of length to avoid the headache of figuring out what units the length should be in (octets, words, etc.) 🤯 The size and type of the unit depend on the address space picked by the target start address. If the target can tell ahead of time that the inclusive range of addresses, from the start address through the count, has an illegal or nonexistent address in it, it should reply with an error 🫠
6.3. READ_DATA Response 🌈
The target uses the READ_DATA response to send back data that the host asked for with a READ command 📤 Depending on how big the requested block is and what the transport layer's message size limits are, one or more READ_DATA responses might be needed to fill one READ command 🧃 Each READ_DATA response gives the target starting address of its segment of data 📍 If the response has an odd number of data octets, the target ends it with a null octet 🫶
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 28READ_DATA FIELDS
Command Length
The command length counts every octet in the command, including data octets, but not the padding octet if there is one 🎀. The host can work out the data length by subtracting the header length from the command length 🧮. The target address can be three words (short format) or five words (long format), so the host has to check the address mode to know which one it's getting 👀.
Target Start Address 🌸
This is the starting address of the data segment in this message. The host can figure out the data length from the command length. The address format (short or long) is the same as on the initial READ command 💅.
Page 46
Data Octets 🍓
These are the data octets from the target, packed using the packing convention we covered above. If there's an odd number of data octets, it ends with a null octet 🫶.
6.4. READ_DONE Reply
The target sends a READ_DONE reply to the host once it has finished transferring the data that a READ command asked for. READ_DONE includes the sequence number of that 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 29READ_DONE FIELDS ✨
READ Sequence Number 🔥
This is the sequence number of the READ command this reply belongs to 💜.
Page 47
6.5. MOVE Command
The host sends the MOVE command to move a block of data from the target to a destination you pick 🚀. The destination can be somewhere on the target, on the host, or on another target (handy for loading one target from another) 🧚. The data gets specified by a target starting address and an address unit count. If the starting address is illegal, or the ending address (start plus count) is illegal, or there are holes in the middle of the range, the target sends an ERROR reply 💀. If the MOVE destination is off-target, the target moves the data in one or more MOVE_DATAs 🌈. Other commands that show up during the transfer should get handled in a timely fashion, especially ABORT 👑. Once the data has been moved, the target sends a MOVE_DONE to the host ✨. The one exception: a MOVE inside a breakpoint will not generate a MOVE_DONE 🙈.
A MOVE with a host destination is different from a READ because it has a host address in it. The host sets this field in the MOVE command, and the target copies it into the matching MOVE_DATA response(s) 🍓. The host can use the address to tell apart data coming back from multiple MOVE requests. This is useful for breakpoints, multi-window debugging, and talking to targets that have multiple processors 💖. For example, the host sends a MOVE command to the target to run during a breakpoint. The ID field in the host address might be an index into a host breakpoint table. When the breakpoint runs, the host uses that ID to match the returning MOVE_DATA with this breakpoint 🦋.
Page 48
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 30MOVE FIELDS 🎀
Source Start Address 🌸
This is the starting address of the requested block of target data. If the address type is illegal, the target sends an error reply 💅.
Address Unit Count 🧮
This is how many target indivisibly-addressable units get transferred. For example, if the address space is PHYS_MACRO, a count of two with a start address of 1000 selects the contents of locations 1000 and 1001 🔥. We say "count" instead of "length" so nobody has to guess what units the length is measured in (octets, words,
Page 49
etc.) 🫶. The size and type of the unit change depending on the address space picked by the target start address. If the target can tell ahead of time that the inclusive range covered by the start address and the count contains an illegal or nonexistent address, it should reply with an error 🙈.
Destination Address 🦋
This is the destination of the MOVE. If the address space is on the target, the address unit size should match the source address space's. If the address mode is HOST, the values and meanings of the other address fields are arbitrary and get decided by the host implementation 💜. For example, the mode argument might name a table (breakpoint, debugging window, etc.), and the ID field could be an index into that table 🧚.
6.6. MOVE_DATA Response
The target uses MOVE_DATA responses to send data that a host MOVE command asked for 🚀. One or more MOVE_DATA responses might be needed to finish a given MOVE command. That depends on how big the requested data block is and on the transport layer's message size limits 🌈. Each MOVE_DATA response includes the target starting address of its data segment 💖. If the response has an odd number of data octets, the target should end the response with a null octet 🫶.
Page 50
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 31MOVE_DATA FIELDS 💅
Command Length 🔥
The command length is how many octets are in the command, including data octets, but not the padding octet if there is one 🎀.
Source Start Address 🌸
This is the starting address of the data segment in this
Page 51
message. The host can infer the data length from the command length 🧮.
Destination Address 🦋
This is the destination address copied from the MOVE command that started this transfer. For HOST MOVEs, the host uses it to figure out where the data came from 🧚.
Data Octets 💖
These are the data octets from the target, packed using the packing convention described above. If there's an odd number of data octets, it ends with a null octet 🫶.
6.7. MOVE_DONE Reply
The target sends a MOVE_DONE reply to the host once it has finished transferring the data that a MOVE command asked for 🌈. MOVE_DONE includes the sequence number of that 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 32MOVE_DONE FIELDS 👑
MOVE Sequence Number 💜
This is the sequence number of the MOVE command this reply belongs to 🙈.
Page 52
6.8. REPEAT_DATA
The host sends the REPEAT_DATA command to write copies of a specified pattern into the target 🌸. It's a super efficient way to zero out target memory and set up target data structures 🔥. The command gives the target starting address, how many copies of the pattern to make, and a stream of octets that makes up the pattern 💅.
the thing about this one is it's like a sneaky loophole, bestie 👀. REPEAT_DATA with a big pattern can't be faked by just splitting the data into little pieces across a bunch of commands. so the biggest pattern you can copy with it depends on how big a message the transport layer is willing to carry 🧚
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 33Page 53
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)
okay so the host sends a WRITE_MASK command to the target to write one or more masked values 🔥. it uses an address to specify a target base location, and then it's followed by one or more offset-mask-value triplets. each triplet gives an offset from the base, a value, and a mask that shows which bits in the location at that offset are gonna get changed 💜
this one is optional, and it's built for controlling the target by changing locations in a table. like, it may be used to change entries in a target parameter table 🧚. the big deal is that modifying a 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
the start and the end of the modification. no sneaking in mid-edit, periodt 🙈
Page 55
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 34Page 56
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
Page 58
7. Control Commands 👑
okay chapter 7 is all about control commands 🫶. they're used to control the execution of target code, breakpoints and watchpoints. they're 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
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 14 |
+---------------+---------------+
1 | CONTROL | START |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | |
+-- ID --+ |
4 | Field | | Address
+-------------------------------+ |
5 | | |
+-- Offset --+ |
6 | | |
+-------------------------------+ +-+
START Command Format
Figure 35START FIELDS: 💫
Address
The descriptor specifies the object to be started. If the mode is PROCESS_CODE, ID specifies the process to be started, and offset gives the process virtual address to start at. If the mode is PHYS_*, execution of the target is continued at the specified address. 🎯
For modes of BREAKPOINT and WATCHPOINT, the offset specifies the new value of the FSM state variable. This is for FSM breakpoints and watchpoints. 🧠
Page 60
7.2 STOP Command
the STOP command is sent by the host to stop execution of a specified object in the target. a descriptor specifies the object. applied to a breakpoint or watchpoint, STOP deactivates it. the breakpoint/watchpoint may be re-activated by issuing a START or a CONTINUE command for it. 🛑💅
Okay bestie, so STOP is the command that pauses things, and it's kinda iconic 💅
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | CONTROL | STOP |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+-------------------------------+ +-+
STOP Command Format
Figure 36STOP FIELDS:
Descriptor
The descriptor is how you point at the object you want to stop or disarm. If the mode is PROCESS_CODE, the ID tells you which process gets stopped. For the BREAKPOINT and WATCHPOINT modes, that specific breakpoint or watchpoint gets deactivated 🛑. Good news though: it can be re-activated by a CONTINUE or START command 🔄
Page 61
7.3 CONTINUE Command
CONTINUE is the host's "okay, go!" energy 🚀 It's how the host resumes execution of a specified object in the target, and the descriptor is what picks the object. When you apply it to a breakpoint or watchpoint, CONTINUE activates it ✨
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | CONTROL | CONTINUE |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+-------------------------------+ +-+
CONTINUE Command Format
Figure 37CONTINUE FIELDS:
Descriptor
The descriptor specifies the object to be resumed or armed. If the mode is PROCESS_CODE, the ID specifies the process to be resumed. For modes of BREAKPOINT and WATCHPOINT, the specified breakpoint or watchpoint is armed 🎀
7.4 STEP Command
STEP is giving one-tiny-move energy 👣 The host sends it to the target, and it requests the execution of one instruction (or appropriate operation) in the object specified by the descriptor 💖
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | CONTROL | STEP |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+-------------------------------+ +-+
STEP Command Format
Figure 38STEP FIELDS:
Descriptor
The descriptor specifies the object to be stepped. If the mode is PROCESS_CODE, the ID specifies a process 🧚
7.5 REPORT Command
REPORT is the host asking for the tea on a target object 🍓 The host sends it to request a status report on a specified target object, and the status comes back in a STATUS reply 📋
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | CONTROL | REPORT |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+-------------------------------+ +-+
REPORT Command Format
Figure 39REPORT FIELDS:
Descriptor
The descriptor specifies the object for which a STATUS report is requested. For a mode of PROCESS_CODE, the ID specifies a process. Other valid modes are PHYS_MACRO, to query the status of the target application, and BREAKPOINT and WATCHPOINT, to get the status of a breakpoint or watchpoint 🔍
7.6 STATUS Reply
STATUS is the target spilling the tea back to the host 💜 The target sends a STATUS reply in response to a REPORT command from the host. It gives the state of a specified object. For example, it may tell whether a particular target process is running or stopped 🌈
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 | CONTROL | STATUS |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+-------------------------------+ +-+
5 | Status |
+-------------------------------+ +-+
* |
* |
* | Other Data
+-------------------------------+ |
n | Other Data | |
+-------------------------------+ +-+
STATUS Reply Format
Figure 40STATUS FIELDS:
Descriptor
The descriptor specifies the object whose status is being given. If the mode is PROCESS_CODE, then the ID specifies a process. If the mode is PHYS_MACRO, then the status is that of the target application 💅
Status
The status code describes the status of the object. Status codes are 0=STOPPED and 1=RUNNING. For breakpoints and watchpoints, STOPPED means disarmed and RUNNING means armed ✨
Other Data
For breakpoints and watchpoints, Other Data consists of a
Page 65
16-bit word giving the current value of the FSM state variable 🫶
7.7 EXCEPTION Trap
Okay, this one is the drama 😭 An EXCEPTION is a spontaneous message sent from the target, indicating a target-machine exception associated with a particular object. The object is specified by an address 💀
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 | CONTROL | EXCEPTION |
+---------------+---------------+ +-+
2 | Mode | 0 | |
+---------------+---------------+ |
3 | | |
+-- ID --+ |
4 | Field | | Address
+-------------------------------+ |
5 | | |
+-- Offset --+ |
6 | | |
+-------------------------------+ +-+
7 | Type |
+-------------------------------+ +-+
* |
* |
* | Other Data
+-------------------------------+ |
n | Other Data | |
+-------------------------------+ +-+
EXCEPTION Format
Figure 41EXCEPTION FIELDS:
Address
Page 66
The address specifies the object the exception is for 🙈
Type
The type of exception. Values are target-dependent 🌸
Other Data
Values are target-dependent 💜
Page 67
Page 68
CHAPTER 8 Management Commands ✨
Management commands are how you control resources in the target machine 🎀 There are two kinds: the ones that interrogate the remote machine about resources, and the ones that allocate and free resources. There are management commands to create, list and delete breakpoints. All commands have corresponding replies, and those replies include the sequence number of the request command. Failing requests produce ERROR replies 💅
There are two resource allocation commands, CREATE and DELETE, which create and delete objects in the remote machine 🦋 There are also a number of listing commands for listing a variety of target objects: breakpoints, watchpoints, processes, and names 📋 The amount of data returned by listing commands may vary in length, depending on the state of the target. If a list is too large to fit in a single message, the target will send it in several list replies. A flag in each reply specifies whether more messages are to follow 🧚
8.1 CREATE Command
CREATE is bringing new objects to life, literally 🌈 The CREATE command is sent from the host to the target to create a target object. If the CREATE is successful, the target returns a CREATE_DONE reply, which contains a descriptor associated with the CREATEd object. The types of objects that may be specified in a CREATE include breakpoints, processes, memory objects and descriptors. All are optional except for breakpoints 👑
Page 69
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 | MANAGEMENT | CREATE |
+---------------+---------------+
2 | Create Type |
+---------------+---------------+ +-+
* |
* | Create
* | Arguments
+---------------+---------------+ |
n | Create Arguments | |
+---------------+---------------+ +-+
CREATE Command Format
Figure 42CREATE FIELDS 💅
Create Type 🎀
okay so the CREATE command is how the host asks the target to make something new 🧚 and the Create Type field tells the target what kind of thing to build. the arguments change depending on the type, bestie. only BREAKPOINT is required, everything else is optional 💖 here are the currently defined types:
Create Type | Symbol
-------------+----------------
0 BREAKPOINT
1 WATCHPOINT
2 PROCESS
3 MEMORY_OBJECT
4 DESCRIPTOR
Create Types
Figure 43Page 70
Create Arguments ✨
the create arguments depend on which type of object you're making, and each type has its own format. literally one format per type, so no mixing them up 🙈
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 22 |
+---------------+---------------+
1 | MANAGEMENT | CREATE |
+---------------+---------------+
2 | BREAKPOINT |
+---------------+---------------+ +-+
3 | Mode | Mode Argument | |
+---------------+---------------+ |
4 | | |
+-- ID --+ | Create
5 | Field | | BREAKPOINT
+-------------------------------+ | Arguments
6 | | |
+-- Offset --+ |
7 | | |
+-------------------------------+ |
8 | Maximum States | |
+---------------+---------------+ |
9 | Maximum Size | |
+---------------+---------------+ |
10| Maximum Local Variables | |
+---------------+---------------+ +-+
CREATE BREAKPOINT Format
Figure 44BREAKPOINT and WATCHPOINT 🦋
the format is the same for CREATE BREAKPOINT and CREATE WATCHPOINT, so it's giving déjà vu but make it efficient 💜 in the rest of this bit, "breakpoint" can mean either a breakpoint or a watchpoint, no cap.
the address is where the breakpoint gets set. for watchpoints, it's the location being watched, which is kind of iconic 👀
valid modes are any PHYS_* mode that addresses macro-memory, PROCESS_CODE for breakpoints, and PROCESS_DATA for watchpoints 🌈
"maximum states" is how many states the finite state machine for this breakpoint will have. a value of zero means a default breakpoint, which is for targets that don't implement finite state machine (FSM) breakpoints 🍓 a default breakpoint is basically an FSM with one state, made of a STOP command and a REPORT command for the process holding the breakpoint. simple and cute 🫶
"maximum size" is the total size, in octets, of the breakpoint data that gets sent later through BREAKPOINT_DATA commands. it only counts the data itself, so the LDP command headers and breakpoint descriptors don't get included 🙅♀️
"maximum local variables" is how many 32-bit longs to reserve for local variables for this breakpoint. normally that's just zero, lowkey 🤍
Page 71
PROCESS 🧚
creates a new process. the arguments are target-dependent, so it depends on the target 💫
Page 72
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 | MANAGEMENT | CREATE |
+---------------+---------------+
2 | MEMORY_OBJECT |
+---------------+---------------+
3 | Object Size |
+---------------+---------------+
4 | Name Size |
+-------------------------------+ +-+
5 | Name char | Name char | |
+-------------------------------+ |
* | Object
* | Name
* |
+---------------+---------------+ |
n | 0 or Name char| 0 | |
+---------------+---------------+ +-+
CREATE MEMORY_OBJECT Format
Figure 45MEMORY_OBJECT 🌸
this one creates an object of size Object Size, with the given name. Object Size is in target dependent units, so again the target decides the vibe 🎀 the name can be the null string if you want an unnamed object. Name Size tells you how many characters are in Object Name, and it must be even. it always ends with a null octet, periodt 💅
DESCRIPTOR 💜
this is for getting descriptors from IDs on target systems where the IDs are longer than 32 bits 👑 there's a single argument, Long ID, and its length is target dependent.
Page 73
8.2 CREATE_DONE Reply ✨
the target sends a CREATE_DONE reply to the host whenever a CREATE command goes through successfully 🎉 the reply carries the sequence number of the CREATE request, plus a descriptor for the object that got created. the host then uses that descriptor to point at the object in later commands. commands that refer to created objects include LIST_* commands, DELETE, and BREAKPOINT_DATA. for example, if the host wants to delete a CREATEd object, it sends a DELETE command that names the descriptor from the CREATE_DONE reply 🗝️
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 12 |
+---------------+---------------+
1 | MANAGEMENT | CREATE_DONE |
+---------------+---------------+
2 | Create Sequence Number |
+---------------+---------------+ +-+
3 | Mode | Mode Argmuent | |
+---------------+---------------+ | Created
4 | | | Object
+-- ID --+ | Descriptor
5 | Field | |
+---------------+---------------+ +-+
CREATE_DONE Reply Format
Figure 46CREATE_DONE FIELDS 🧁
Create Sequence Number 🍒
this is the sequence number of the CREATE command that this reply is answering 💖
Created Object Descriptor 🦄
this is a descriptor the target gives to the created object. the contents of the descriptor fields are arbitrarily assigned by the target, whenever it feels like it 🙈
Page 74
the host treats the descriptor as one unitary object, and it uses it to refer to the created object in later commands. it's the object's ID card, bestie 🪪
8.3 DELETE Command 🗑️
the host sends a DELETE command to remove an object that an earlier CREATE command made 💨 the object gets specified with a descriptor, and that descriptor comes from the CREATE_DONE reply to the original CREATE command.
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | MANAGEMENT | DELETE |
+---------------+---------------+ +-+
2 | Mode | Mode Argument | |
+---------------+---------------+ |
3 | | | Created
+-- ID --+ | Object
4 | Field | | Descriptor
+---------------+---------------+ +-+
DELETE Command Format
Figure 47DELETE FIELDS 🫧
Created Object Descriptor 🌷
this specifies the object to be deleted. it's the descriptor the target returned in the CREATE_DONE reply to the original CREATE command, so you always know exactly who you're deleting 😤
Page 75
8.4 DELETE_DONE Reply 🎀
the target sends a DELETE_DONE reply to the host when a DELETE command succeeds 🥳 the reply carries the sequence number of the DELETE request.
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 6 |
+---------------+---------------+
1 | MANAGEMENT | DELETE_DONE |
+---------------+---------------+
2 | Delete Sequence Number |
+---------------+---------------+
DELETE_DONE Reply Format
Figure 48DELETE_DONE FIELDS 💜
Request Sequence Number 🍓
this is the sequence number of the DELETE command that this reply is answering. short and sweet, just like that 💅
8.5 LIST_ADDRESSES Command 🌸
Okay so we're picking up right where LIST_ADDRESSES leaves off, and bestie, this one is lowkey about asking the target for its memory map 🗺️✨
The host sends a LIST_ADDRESSES command to ask for the valid address ranges of one specific object, and that object is named by a descriptor 🎀 Typical objects are a target process or the whole target physical machine 💻 The target answers with an ADDRESS_LIST reply. This command is the go-to for finding out how big a dynamic address space is and for figuring out which dump ranges to grab 🦋
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 10 |
+---------------+---------------+
1 | MANAGEMENT | LIST_ADDRESSES|
+---------------+---------------+ +-+
2 | Mode | Mode Argument | |
+---------------+---------------+ | Object
3 | | | Descriptor
+-- ID --+ |
4 | Field | |
+---------------+---------------+ +-+LIST_ADDRESSES Command Format Figure 49
Page 76
LIST_ADDRESSES FIELDS:
Object Descriptor: this one says which object's address ranges you want listed 🫶 The valid modes here are PHYS_MACRO, PHYS_MICRO, PROCESS_CODE, and PROCESS_DATA 💅
8.6 ADDRESS_LIST Reply 🌸
The target sends an ADDRESS_LIST reply to the host whenever a LIST_ADDRESSES command succeeds 🎉 The reply carries the sequence number of the LIST_ADDRESSES request, the descriptor of the object being listed, and a list of the valid address ranges inside that object 🔥
Page 77
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 | MANAGEMENT | ADDRESS_LIST |
+---------------+---------------+
2 | List Sequence Number |
+---------------+---------------+
3 | Flags |M| Item Count |
+---------------+---------------+
4 | |
+-- --+
5 | Descriptor |
+-- --+
6 | |
+---------------+---------------+ +-+
7 | | |
+-- First Address --+ | First
8 | | | Address
+-------------------------------+ | Range
9 | | |
+-- Last Address --+ |
10 | | |
+-------------------------------+ +-+
*
*
*
+---------------+---------------+ +-+
| | |
+-- First Address --+ | Last
| | | Address
+-------------------------------+ | Range
| | |
+-- Last Address --+ |
| | |
+-------------------------------+ +-+ADDRESS_LIST Reply Format Figure 50
Page 78
ADDRESS_LIST FIELDS:
List Sequence Number: this is the sequence number of the LIST_ADDRESSES command that this reply answers 🧚
Flags: if M=1, the address list keeps going in one or more later ADDRESS_LIST replies 🌈 If M=0, this one is the final ADDRESS_LIST 🏁
Item Count: how many address ranges this command describes 🔢
Descriptor: the descriptor of the object being listed 🎀
Address Range: each range is a pair of 32-bit addresses, the first and the last addresses of that range ✨ If the object's address space has 'holes' in it, you use multiple address ranges to describe the valid space 🕳️ 💜
8.7 LIST_BREAKPOINTS Command 🦋
The host sends a LIST_BREAKPOINTS command to request a list of all breakpoints associated with the current connection 🙈 The target replies with BREAKPOINT_LIST 💖
Page 79
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 4 |
+---------------+---------------+
1 | MANAGEMENT |LIST_BREAKPOINTS
+---------------+---------------+LIST_BREAKPOINTS Command Format Figure 51
8.8 BREAKPOINT_LIST Reply ⭐
The target sends a BREAKPOINT_LIST reply to the host in response to a LIST_BREAKPOINTS command 🎀 The reply has the sequence number of the LIST_BREAKPOINTS request and a list of all breakpoints tied to the current connection 🫶 For each breakpoint, the descriptor and address are listed 📍
Page 80
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 | MANAGEMENT |BREAKPOINT_LIST|
+---------------+---------------+
2 | List Sequence Number |
+---------------+---------------+
3 | Flags |M| Item Count |
+---------------+---------------+ +-+
4 | Mode | 0 | |
+---------------+---------------+ |
5 | | | Breakpoint
+-- ID --+ | Descriptor
6 | Field | |
+---------------+---------------+ +-+
7 | Mode | Mode Argument | |
+---------------+---------------+ |
8 | | |
+-- ID --+ | Breakpoint
9 | Field | | Address
+-------------------------------+ |
10 | | |
+-- Offset --+ |
11 | | |
+-------------------------------+ +-+
* | Additional
* | Descriptor-Address
* | Pairs
+-+BREAKPOINT_LIST Reply Format Figure 52
BREAKPOINT_LIST FIELDS:
List Sequence Number: the sequence number of the LIST_BREAKPOINTS command that this reply answers 💅
Page 81
Flags: if M=1, the breakpoint list keeps going in one or more later BREAKPOINT_LIST replies 🌸 If M=0, this one is the final BREAKPOINT_LIST 🏁
Item Count: how many breakpoints this list describes 🔢
Breakpoint Descriptor: a descriptor the target assigns to this breakpoint 🦋 The host uses it to point at this breakpoint in BREAKPOINT_DATA and DELETE commands 💜
Breakpoint Address: the address where this breakpoint is set 📍
8.9 LIST_PROCESSES Command 🧚
The host sends a LIST_PROCESSES command to ask for a list of descriptors for every process on the target 🌈 The target replies with PROCESS_LIST 💖
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 4 |
+---------------+---------------+
1 | MANAGEMENT |LIST_PROCESSES |
+---------------+---------------+LIST_PROCESSES Command Format Figure 53
Page 82
8.10 PROCESS_LIST Reply 👑
The target sends a PROCESS_LIST reply to the host in response to a LIST_PROCESSES command 🎀 The reply has the sequence number of the LIST_PROCESSES request and a list of all processes on the target 🫶 For each process, you get a descriptor and a target-dependent amount of process data 🍓
Okay so the PROCESS_LIST reply is where the process info comes home 🏠✨ Here's the layout, bestie 💅
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 | MANAGEMENT | PROCESS_LIST |
+---------------+---------------+
2 | List Sequence Number |
+---------------+---------------+
3 | Flags |M| Item Count |
+---------------+---------------+ +-+
4 | PROCESS_CODE | 0 | |
+---------------+---------------+ |
5 | | | Process
+-- ID --+ | Descriptor
6 | Field | |
+---------------+---------------+ +-+
7 | Process data count | |
+---------------+---------------+ |
8 | Process data | Process data | |
+-------------------------------+ | Process
* | Data
* |
* |
+---------------+---------------+ |
n | Process data | Process data | |
+-------------------------------+ +-+
* | Additional
* | Descriptor-Data
* | Pairs
+-+
PROCESS_LIST Reply Format
Figure 54Page 83
PROCESS_LIST FIELDS 🎀
List Sequence Number is the sequence number of the LIST_PROCESSES command that this is the reply to. Cute, right? 🧚
Flags is where the magic is 🪄 If M=1, the process list keeps going in one or more later PROCESS_LIST replies. If M=0, this is the last PROCESS_LIST, so you can stop waiting, bestie 😭
Item Count is how many processes this list describes. Every process gets a descriptor plus a variable number of octets of process data 💜
Process Descriptor is a descriptor the target gives to this process. The host uses it to name this PROCESS in a DELETE command 🦋
Process Data Count is the number of octets of process data for this process. It must be even 🙈
Process Data is target-dependent info about the process. The number of octets is whatever the process data count says 🌸
8.11 LIST_NAMES Command
The host sends a LIST_NAMES command to ask for a list of available names as strings. The target answers with NAME_LIST. Simple and iconic 💅
Page 84
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 4 |
+---------------+---------------+
1 | MANAGEMENT | LIST_NAMES |
+---------------+---------------+
LIST_NAMES Command Format
Figure 558.12 NAME_LIST Reply
The target sends a NAME_LIST reply to the host in response to a LIST_NAMES command. The reply has the sequence number of the LIST_NAMES request, plus a list of every target name as strings. The whole list, served 🍓
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 | MANAGEMENT | NAME_LIST |
+---------------+---------------+
2 | List Sequence Number |
+---------------+---------------+
3 | Flags |M| Item Count |
+---------------+---------------+ +-+
4 | Name Size | |
+---------------+---------------+ |
5 | Name Char | Name Char | | Name
+---------------+---------------+ | String
* |
* |
* |
+---------------+---------------+ |
n | 0 or Name Char| 0 | |
+---------------+---------------+ +-+
* | Additional
* | Name
* | Strings
+-+
NAME_LIST Reply Format
Figure 56
NAME_LIST FIELDS ✨
List Sequence Number is the sequence number of the LIST_NAMES command that this is the reply to 🫶
Page 86
Flags works just like before: if M=1, the name list continues in one or more later NAME_LIST replies, and if M=0, this is the final NAME_LIST 🌈
Item Count is the number of name strings in this list. Each name string is a character count followed by a null-terminated string of characters 🧁
Name Size is the number of octets in this name string. It must be even 💖
Name Characters is a string of octets that makes up the name. It ends with a null octet. The number of characters must be even, so if the terminating null lands on an odd octet, another null gets added on the end 🫠 (the null-padding glow-up is so real)
Page 87
8.13 GET_PHYS_ADDR Command
The host sends a GET_PHYS_ADDR command to turn an address into physical form. The target sends the physical address back in a GOT_PHYS_ADDR reply. For example, the host could send a GET_PHYS_ADDR command with a register-offset address, and the target would return the physical address that comes from it in a GOT_PHYS_ADDR reply 🦋
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 14 |
+---------------+---------------+
1 | MANAGEMENT | GET_PHYS_ADDR |
+---------------+---------------+ +-+
2 | Mode | Mode Argument | |
+---------------+---------------+ |
3 | ID | |
+-- Field --+ |
4 | | | Address
+---------------+---------------+ |
5 | | |
+-- Offset --+ |
6 | | |
+---------------+---------------+ +-+
GET_PHYS_ADDR Command Format
Figure 57GET_PHYS_ADDR FIELDS 🌸
Address is the address to be converted into a physical address. The mode can be one of PHYS_REG_OFFSET, PHYS_REG_INDIRECT, PHYS_MACRO_PTR, any OBJECT_* mode, and any PROCESS_* mode except for PROCESS_REG. Lots of options, all valid 🍓
Page 88
8.14 GOT_PHYS_ADDR Reply
The target sends a GOT_PHYS_ADDR reply to the host in response to a successful GET_PHYS_ADDR command. The reply has the sequence number of the GET_PHYS_ADDR request, plus the specified address converted into a physical address. Glow up complete 💅✨
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 16 |
+---------------+---------------+
1 | MANAGEMENT | GOT_PHYS_ADDR |
+---------------+---------------+
2 | Get Sequence Number |
+---------------+---------------+ +-+
3 | PHYS_MACRO | 0 | |
+---------------+---------------+ |
4 | | |
+-- 0 --+ |
5 | | | Address
+---------------+---------------+ |
6 | | |
+-- Offset --+ |
7 | | |
+---------------+---------------+ +-+
GOT_PHYS_ADDR Reply Format
Figure 58GOT_PHYS_ADDR FIELDS 🧚
Get Sequence Number is the sequence number of the GET_PHYS_ADDR command that this is the reply to 🫶
Address is the address that results from translating the address given in the GET_PHYS_ADDR command into a physical address. The mode is always PHYS_MACRO, and the ID and mode argument are always zero. The offset gives the 32-bit physical address. Main character energy for real 👑
Page 89
8.15 GET_OBJECT Command
The host sends a GET_OBJECT command to turn a name string into a descriptor. The target sends the descriptor back in a GOT_OBJECT reply. It's meant for finding control parameter objects 🔍💜
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 | MANAGEMENT | GET_OBJECT |
+---------------+---------------+ +-+
2 | Name Size | |
+---------------+---------------+ |
3 | Name Char | Name Char | | Name
+---------------+---------------+ | String
* |
* |
* |
+---------------+---------------+ |
n | 0 or Name Char| 0 | |
+---------------+---------------+ +-+
GET_OBJECT Command Format
Figure 59GET_OBJECT FIELDS 🌈
Name String is the name of an object 🎀
Name Size is the number of octets in this name string. It must be even 💅
8.15. Name Characters (continued) 🎀
The name is a string of octets, and it ends with a null octet. Here's the fun bit: the total number of characters has to be even. So if your terminating null lands on an odd octet, you tack on one more null to even things out. Very tidy, very intentional. 💅
8.16. GOT_OBJECT Reply 🦋
Okay so the target sends a GOT_OBJECT reply back to the host, but only when a GET_OBJECT command actually succeeds. The reply carries the sequence number of that GET_OBJECT request, plus the object name you asked for, now converted into a descriptor. Iconic glow-up, honestly. ✨
0 0 0 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---------------+---------------+
0 | 12 |
+---------------+---------------+
1 | MANAGEMENT | GOT_OBJECT |
+---------------+---------------+
2 | Get Sequence Number |
+---------------+---------------+ +-+
3 | Mode | Mode Argument | |
+---------------+---------------+ |
4 | | |
+-- ID --+ | Object
5 | | | Descriptor
+---------------+---------------+ +-+
GOT_OBJECT Reply Format
Figure 60GOT_OBJECT FIELDS:
Get Sequence Number 🌸
This is the sequence number of the GET_OBJECT command that this reply is answering. It's how the host knows which request the reply belongs to. Main character organization, bestie. 📋
Descriptor 🧚
This is the descriptor of the object that was named in the GET_OBJECT command. ✨
9. Breakpoints and Watchpoints ✨
Okay, debugging energy incoming. 🔍 Breakpoints and watchpoints are what you use when you're debugging applications. Each one is tied to one debugger connection and one address. When a breakpoint or watchpoint gets triggered, the target runs one or more commands attached to it. A breakpoint triggers when its address is executed, and a watchpoint triggers when its address is modified. Both use the same mechanism to structure their commands. Just so you know, for brevity's sake, this document uses 'breakpoint' to mean either a breakpoint or a watchpoint from here on. Cute and efficient. 💖
The host uses the commands for manipulating breakpoints listed in Figure 61, in the order they're normally used. Every one of these commands goes from the host to the target, and each one names the descriptor of a breakpoint. 🎀
Command Description
---------------------+------------------------------------
CREATE Create a breakpoint
BREAKPOINT_DATA Send commands to be executed in an
FSM breakpoint
START Activate a breakpoint, set state
and initialize breakpoint variables
STOP Deactivate a breakpoint
CONTINUE Activate a breakpoint
LIST_BREAKPOINTS List all breakpoints
REPORT Report the status of a breakpoint
DELETE Delete a breakpoint
Commands to Manipulate Breakpoints
Figure 61There are two kinds of breakpoints, and they're different mainly in how they use commands: default breakpoints and finite state machine (FSM) breakpoints. 🧠
Default breakpoints don't have any commands at all. When one is triggered, it stops the target object (meaning the target process or application) it lives in. A STATUS report on the stopped object then goes to the host, and from that point the host may send more commands to debug the target. 🛑
An FSM breakpoint is a bit more elaborate. It has one or more conditional command lists arranged into a finite state machine. When you create an FSM breakpoint, you specify the total number of states. After that, the host sends commands (using BREAKPOINT_DATA) to attach to each state. The target keeps a state variable for each breakpoint, and that variable decides which command list runs when the breakpoint triggers. When the breakpoint is created, its state variable starts at zero, since zero is the first state. A breakpoint command called SET_STATE can change the state variable from inside a breakpoint. And if you send a REPORT command to a breakpoint descriptor, you get back its address, whether it's armed or disarmed, and the current value of its state variable. Very informative. 📊
Breakpoints can include all the implemented data transfer and control commands, a set of conditional commands, and a set of breakpoint commands. The conditional commands and the breakpoint commands both act on a set of local breakpoint variables. Those variables are the state variable, a counter, and two pointer variables. Conditional commands decide whether a breakpoint command list runs, based on the contents of one of the breakpoint variables. The breakpoint commands set the values of those variables: SET_STATE sets the state variable, SET_PTR sets one of the pointer variables, and INC_COUNT increments the breakpoint counter. Also, an implementation might have restrictions on how many breakpoints, states, conditions, and command list sizes it allows. Management commands and protocol commands are not allowed in breakpoints at all. 🚫
Here's how execution works in FSM breakpoints. When a breakpoint triggers, its state variable picks out one particular state. One or more conditional command lists are attached to that state. Each conditional command list is a list of conditions followed by a list of commands, and those commands only run if the condition list is satisfied. The debugger starts a breakpoint by running the first of these lists. If the condition list is satisfied, the debugger runs the associated command list and leaves the breakpoint. If the condition list fails, the debugger skips ahead to the next conditional command list. This keeps going until the debugger either hits a successful condition list or runs out of conditional command lists for that state. Here's the relationship between commands, lists, and states, shown in Figure 62. (The IFs, THENs, and ELSEs below are just there to make the logical structure of a state clear. They aren't part of the protocol, so don't go looking for them on the wire. 🙈)
State 0
IF <condition list 0>
THEN <command list 0>
ELSE IF <condition list 1>
THEN <command list 1>
*
*
*
ELSE IF <condition list n>
THEN <command list n>
ELSE <exit>
*
*
*
State n
Breakpoint Conditional Command Lists
Figure 629.1. BREAKPOINT_DATA Command 🌈
BREAKPOINT_DATA is a data transfer command the host uses to send commands that get executed in breakpoints and watchpoints. It names the descriptor of the breakpoint or watchpoint, plus a stream of commands. That stream gets appended to the end of the breakpoint's command list. BREAKPOINT_DATA gets applied in order across successive breakpoint states, and across successive command lists within each state. You can send multiple BREAKPOINT_DATA commands for a single breakpoint. Here's the wild part: the breaks between BREAKPOINT_DATA commands can fall anywhere in the data stream, even in the middle of an individual command. Space to hold the data has to be allocated up front, using the maximum size field in the CREATE BREAKPOINT/WATCHPOINT command. Plan ahead, bestie. 📦
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 |BREAKPOINT_DATA|
+---------------+---------------+ +-+
2 | Mode | Mode Argument | |
+---------------+---------------+ | Breakpoint or
3 | | | Watchpoint
+-- ID --+ | Descriptor
4 | Field | |
+-------------------------------+ +-+
5 | Data | Data | |
+-------------------------------+ |
* |
* | Data
* |
+---------------+---------------+ |
n | Data | Data or 0 | |
+---------------+---------------+ +-+
BREAKPOINT_DATA Command Format
Figure 63
BREAKPOINT_DATA FIELDS:
Command Length
Total length of this command in octets, including data,
excluding the final padding octet, if any.
Data
A stream of data to be appended to the data for this
breakpoint or watchpoint. This stream has the form of one
or more states, each containing one or more conditional
command lists. The first BREAKPOINT_DATA command sent for a
breakpoint contains data starting with state zero. The data
for each state starts with the state size. A conditional
command list is composed of two parts: a condition list, and
a command list. Each list begins with a word that gives its
size in octets.
<state 0 size>
<condition list 0 size> <condition list 0>
<command list 0 size> <command list 0>
*
*
*
<condition list n size> <condition list n>
<command list n size> <command list n>
<state 1 size>
<etc>
*
*
*
<state n size>
Breakpoint Data Stream Format
Figure 64
### Sizes
# 10. Conditional Commands ✨
Conditional commands are the ones that decide whether breakpoint commands actually run 👑 You line up one or more conditions in a row and that's a condition list. If the list is satisfied (it evaluates to TRUE), the breakpoint command list right after it gets executed. (Check out Breakpoints and Watchpoints, above, for the logic flow of conditional and command lists 🧚.) These commands test local breakpoint variables and other locations too. Every condition comes out as either TRUE or FALSE. Figure 65 has the whole summary 💖
Command Description -----------------------------+------------------------------------
CHANGED <loc> Determine if a location has changed COMPARE <loc1> <mask> <loc2> Compare two locations, using a mask COUNT_[EQ | GT | LT] <value> Compare the counter to a value TEST <loc> <mask> <value> Compare a location to a value
Conditional Command Summary Figure 65
Here are the rules for building and evaluating condition lists, bestie 📝
- Consecutive conditions have an implicit logical AND between them. A run of these is called an `and_list`. and_lists get split up by an OR command and by the end of the condition list.
- The breakpoint OR command can go between any pair of conditions.
- AND takes precedence over OR.
- Nested condition lists are not supported. A condition list is just one or more and_lists, separated by ORs.
- The condition list gets evaluated in sequence until either a TRUE and_list is found (`condition list <- TRUE`) or the end of the condition list is reached (`condition list <- FALSE`). An and_list is TRUE if all of its conditions are TRUE.
The distillation of all that into BNF looks like this 🤓
<condition_list> :== <and_list> [OR <and_list>]* <and_list> :== <condition> [AND <condition>]* <condition> :== CHANGED | COMPARE | COUNT | TEST
where: OR is a breakpoint command AND is implicit for any pair of consecutive conditions
Here's an example. Take this condition list, with one command per line 👀
COUNT_EQ 1 OR COUNT_GT 10 COUNT_LT 20
It evaluates to this 🦋
(COUNT = 1) OR (COUNT > 10 AND COUNT < 20)
So the command list that follows it runs if the counter is equal to one, or if it's between 10 and 20. Iconic logic, honestly 💅
## 10.1. Condition Command Format
Condition commands start with the standard four-octet command header 🎀 The high-order bit of the command type byte is the negate flag. If that bit is set, the boolean value of the condition gets flipped. This flag only applies to that one condition and not to the other conditions in the condition list, so be careful with it 🙈
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 | CONDITION |N| Type | +---------------+---------------+
Condition Command Header Figure 66
## 10.2. COUNT Conditions
The COUNT conditions (COUNT_EQ, COUNT_GT and COUNT_LT) compare the breakpoint counter to a value you specify 🔥 The counter gets set to zero when the breakpoint is STARTed, and the INC_COUNT breakpoint command bumps it up. All three COUNT conditions share the same format.
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 8 | +---------------+---------------+ 1 | CONDITION |N| Type | +---------------+---------------+ 2 | | +-- Value --+ 3 | | +---------------+---------------+
COUNT Condition Format Figure 67
### COUNT_* Condition FIELDS 🧚
`Type`
One of COUNT_EQ, COUNT_LT and COUNT_GT. The condition is TRUE if the breakpoint counter is [EQ | LT | GT] the specified value.
`Value`
A 32-bit value to be compared to the counter.
## 10.3. CHANGED Condition
The CHANGED condition is TRUE if the contents of the specified location have changed since the last time this breakpoint occurred 🌸 Only one location can be the object of CHANGED conditions per breakpoint. Also, the CHANGED condition is always FALSE the first time the breakpoint occurs, so don't panic when it's FALSE on the first hit 😭
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 14 | +---------------+---------------+ 1 | CONDITION |N| CHANGED | +---------------+---------------+ 2 | | +-- --+ 3 | Address | +-- --+ 4 | | +-- --+ 5 | | +-- --+ 6 | | +---------------+---------------+
CHANGED Condition Figure 68
### CHANGED FIELDS 🦋
`Address`
The full 5-word address of the location the CHANGED command tests.
## 10.4. COMPARE Condition
The COMPARE condition compares two locations using a mask 💜 It's TRUE if (`<loc1>` & `<mask>`) = (`<loc2>` & `<mask>`). Masking is how you pick out only the bits you care about, so it's giving precision 🎯
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 28 | +---------------+---------------+ 1 | CONDITION |N| COMPARE | +---------------+---------------+ 2 | | +-- --+ 3 | Address 1 | +-- --+ 4 | | +-- --+ 5 | | +-- --+ 6 | | +---------------+---------------+ 7 | | +-- Mask --+ 8 | | +-------------------------------+ 9 | | +-- --+ 10| Address 2 | +-- --+ 11| | +-- --+ 12| | +-- --+ 13| | +-------------------------------+
COMPARE Condition Figure 69
### COMPARE FIELDS 🌈
`Address 1` and `Address 2`
The 5-word addresses of the locations to be compared.
`Mask`
A 32-bit mask that specifies which bits in the locations should be compared.
## 10.5. TEST Condition
The TEST condition compares a location to a value, using a mask 🍓 It's TRUE if (`<loc>` & `<mask>`) = `<value>`. Same vibe as COMPARE, just with a fixed value instead of a second location ✨
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 22 | +---------------+---------------+ 1 | CONDITION |N| TEST | +---------------+---------------+ 2 | | +-- --+ 3 | Address | +-- --+ 4 | | +-- --+ 5 | | +-- --+ 6 | | +---------------+---------------+ 7 | | +-- Mask --+ 8 | | +-------------------------------+ 9 | | +-- Value --+ 10| | +-------------------------------+
TEST Condition Figure 70
### TEST FIELDS 💅
`Address`
The 5-word address of the location to be compared to the value.
`Mask`
A 32-bit mask that specifies which bits in the location should be compared.
`Value`
A 32-bit value to compare against the masked location.
# 11. Breakpoint Commands ✨
okay bestie, breakpoint commands are the ones that set the value of **breakpoint variables** 💅 they only work inside breakpoints and watchpoints (no cap, they're not valid anywhere else 🙈). the host sends them to the target as data inside `BREAKPOINT_DATA` commands. here's the whole lineup, Figure 71 🎀:
Command Description ------------------------+-------------------------------------
INCREMENT <location> Increment the specified location INC_COUNT Increment the breakpoint counter OR OR two breakpoint condition lists SET_PTR <n> <location> Set pointer <n> to the contents of <location> SET_STATE <n> Set the breakpoint state variable to <n>
Breakpoint Command Summary Figure 71
---
## 11.1. INCREMENT Command
the `INCREMENT` command bumps up the contents of a specified location 📈 the location can be in any address space that `LDP` is allowed to write to, so it's giving flexibility 🦋
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 14 | +---------------+---------------+ 1 | BREAKPOINT | INCREMENT | +---------------+---------------+ 2 | | +-- --+ 3 | Address | +-- --+ 4 | | +-- --+ 5 | | +-- --+ 6 | | +---------------+---------------+
INCREMENT Command Format Figure 72
`INCREMENT` FIELDS: 🌸
Address
> the full address of the location whose contents are to be incremented. that's the only field, so keep it simple, bestie 💖
---
## 11.2. INC_COUNT Command
the `INC_COUNT` command increments the breakpoint counter 🔢 every breakpoint gets its own counter variable, and it gets reset to zero in three situations: when the breakpoint is created, when it's armed with the `START` command, and whenever the breakpoint state changes. the `COUNT_*` conditions are the ones that check this counter 👀
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | BREAKPOINT | INC_COUNT | +---------------+---------------+
INC_COUNT Command Format Figure 73
---
## 11.3. OR Command
the `OR` command splits a breakpoint condition list into two and_lists ✂️ the list counts as TRUE if *any* of the OR-separated and_lists inside it are TRUE. a breakpoint condition list can have zero, one, or many `OR` commands, so it's really flexible 🌈 if you want the full scoop on condition lists, check out 'Condition Commands' 🧚
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 4 | +---------------+---------------+ 1 | BREAKPOINT | OR | +---------------+---------------+
OR Command Format Figure 74
---
## 11.4. SET_PTR Command
the `SET_PTR` command loads a breakpoint pointer with the contents of a location 🎯 the pointer variables and `SET_PTR` together give you a basic but unlimited indirect addressing ability, which is lowkey iconic 👑 there are two addressing modes for referencing the breakpoint pointers, `BPT_PTR_OFFSET` and `BPT_PTR_INDIRECT`. for example, if you want to follow a linked list, use `SET_PTR` to load a pointer with the start of the list, then send successive `SET_PTR` commands using the `BPT_PTR_OFFSET` addressing mode to grab each element one by one 🔗
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 16 | +---------------+---------------+ 1 | BREAKPOINT | SET_PTR | +---------------+---------------+ 2 | Pointer | +---------------+---------------+ 3 | | +-- --+ 4 | Address | +-- --+ 5 | | +-- --+ 6 | | +-- --+ 7 | | +---------------+---------------+
SET_PTR Command Format Figure 75
`SET_PTR` FIELDS: 🎀
Pointer
> the pointer to be changed. allowable values are 0 and 1, so pick your fighter 🥊
Address
the full address of the location whose contents are to be loaded into the given pointer variable 📍
---
## 11.5. SET_STATE Command
the `SET_STATE` command sets the breakpoint state variable to whatever value you specify 🎛️ this is the *only* way to change a breakpoint's state from inside a breakpoint 🙅♀️ the host can also change it using a `START` command, so there are two routes, but only one from the inside. the state variable starts at zero when the breakpoint is created 🍓
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 | 6 | +---------------+---------------+ 1 | BREAKPOINT | SET_STATE | +---------------+---------------+ 2 | State Value | +-------------------------------+
SET_STATE Command Format Figure 76
`SET_STATE` FIELDS: 💜
State Value
> the new value for the breakpoint state variable. it must not be greater than the maximum state value specified in the `CREATE BREAKPOINT` command that created this breakpoint. no going over the limit, bestie 🚫
---
# Appendix A. Diagram Conventions ✨
okay so, this part explains how to read all the diagrams in this document 🧚 command and message diagrams show the format of these things, and words are listed in order of transmission, going down the page. the first word is word zero. bits inside a word run left to right, from most significant to least significant 🌈 but here's the twist: like other protocol docs, bits are numbered in the order they're transmitted, so the most significant bit in a word goes out first. the bit labelled '0' is the most significant bit 💅
0 0 0 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +---------------+---------------+ 0 |M| |L| +---------------+---------------+ 1 | Most Sig Octet| Least S. Octet| +---------------+---------------+
M = most significant bit in word zero, transmitted first L = least significant bit in word zero, transmitted last
Sample Diagram Figure 77
# APPENDIX B ✨ Command Summary
okay bestie, this is the cheat sheet 🫶 The table below lists every LDP command that isn't a breakpoint command, sorted alphabetically, with a quick line on what each one does 💖
*Page 117*
Sender Command | Host Target | Function -------------------+-------------+---------------------------
ABORT X Abort outstanding commands ABORT_DONE X Acknowledge ABORT ADDRESS_LIST X Return valid address ranges BREAKPOINT_DATA X Send breakpoint commands BREAKPOINT_LIST X Return list of breakpoints CONTINUE X Resume execution CREATE X Create target object CREATE_DONE X Acknowledge CREATE DELETE X Delete target object DELETE_DONE X Acknowledge DELETE EXCEPTION X Report target exception ERROR X Report error with a host command ERRACK X Acknowledge ERROR GET_OBJECT X Get object descriptor from name GET_PHYS_ADDRESS X Get address in physical form GOT_OBJECT X Return object descriptor GOT_PHYS_ADDRESS X Return physical address HELLO X Initiate LDP session HELLO_REPLY X Return LDP parameters LIST_ADDRESSES X Request valid address ranges LIST_BREAKPOINTS X Request breakpoint list LIST_NAMES X Request name list LIST_PROCESSES X Request process list MOVE X Read data from target MOVE_DONE X Acknowledge MOVE completion MOVE_DATA X Send data request by MOVE NAME_LIST X Return name list PROCESS_LIST X Return process list READ X Read data from target READ_DATA X Return data requested by READ READ_DONE X Acknowledge READ completion REPEAT_DATA X Write copies of data REPORT X Request status of object START X Start target object STATUS X Return status of object STEP X Step execution of target object STOP X Stop target object SYNCH X Check sequence number SYNCH_REPLY X Confirm sequence number WRITE X Write data WRITE_MASK X Write data with mask
*Page 118*
*Command Summary, Figure 78*
*Page 119*
*Page 120*
*LDP Specification: Commands, Responses and Replies*
# APPENDIX C ✨ Commands, Responses and Replies
this one is all about who says what 💅 Commands always go from the host to the target. Some commands get responses and/or replies back from the target. Responses and replies both travel from the target to the host, and the difference is that the target sends only one reply to a command, but it can send multiple responses 🦋 Responses always carry data, while replies may or may not 🌸
*Page 121*
Command | Response | Reply -------------------+--------------+------------------
ABORT ABORT_DONE BREAKPOINT_DATA CONTINUE CREATE CREATE_DONE DELETE DELETE_DONE GET_OBJECT GOT_OBJECT GET_PHYS_ADDRESS GOT_PHYS_ADDRESS HELLO HELLO_REPLY LIST_ADDRESSES ADDRESS_LIST LIST_BREAKPOINTS BREAKPOINT_LIST LIST_NAMES NAME_LIST LIST_PROCESSES PROCESS_LIST MOVE MOVE_DATA MOVE_DONE READ READ_DATA READ_DONE REPEAT_DATA REPORT STATUS START STEP STOP SYNCH SYNCH_REPLY WRITE WRITE_MASK
*Commands, Responses and Replies, Figure 79*
*Page 122*
*LDP Specification: Glossary*
# APPENDIX D ✨ Glossary
here's the vocab list, so nothing gets lost in translation 📚🧚
## FSM
Finite state machine. Commands of each breakpoint or watchpoint are implemented as part of a finite state machine. A list of breakpoint commands is associated with each state. There are several breakpoint commands to change from one state to another. 🔥
## host
The 'host' in an LDP session is the timesharing system on which the user process runs. 💻
## long
A long is a 32-bit quantity. 🔢
## octet
An octet is an eight-bit quantity. 🍓
## RDP
The Reliable Data Protocol (RDP) is a transport layer protocol designed as a low-overhead alternative to TCP. RDP is a connection oriented protocol that provides reliable, sequenced message delivery. 🦋
## server process
The LDP server process is the passive participant in an LDP session. The server process usually resides on a target machine such as a PAD, PSN or gateway. The server process waits for a user process to initiate a session, and responds to commands from the user process. In response to user commands, the server may perform services on the target like reading and writing memory locations or setting breakpoints. 'Server' is sometimes employed as a shorthand for 'server process'. 🧚
*Page 123*
## target
The 'target' in an LDP session is the PSN, PAD or gateway that is being loaded, dumped or debugged by the host. Normally, LDP will be implemented in the target as a server process. However, in some targets with strange requirements, notably the Butterfly, the target LDP may be a user process. 🎯
## user process
The LDP user process is the active participant in an LDP session. The user process initiates and terminates the session and sends commands to the server process which control the session. The user process usually resides on a timesharing host and is driven by a higher-level entity (e.g., an application program like an interactive debugger). 'User' is sometimes employed as a shorthand for 'user process'. 👑
## word
A word is a sixteen-bit quantity. 💜
*Page 124*
# INDEX 🧚✨
ABORT command............................................ 35 ABORT_DONE reply......................................... 36 address.............................................. 60, 66 address descriptor....................................... 20 address format................................... 19, 25, 31 address ID............................................... 22 address mode......................................... 20, 22 address mode argument.................................... 21 address offset........................................... 20 addressing............................................... 19 ADDRESS_LIST reply................................... 76, 77 BASIC_DEBUGGER....................................... 12, 32 breakpoint... 9, 13, 57, 60, 71, 79, 92, 93, 95, 96, 99, 107 breakpoint commands.......................... 9, 94, 95, 107 breakpoint counter........................ 94, 100, 101, 110 breakpoint data...................................... 97, 99 breakpoint state variable........................... 94, 107 breakpoint variables..................................... 94 BREAKPOINT_DATA command..................... 73, 94, 95, 107 BREAKPOINT_LIST reply................................ 79, 80 CHANGED condition....................................... 102 command class............................................ 16 command length field..................................... 16 COMPARE Condition....................................... 103 condition command header................................ 101 conditional commands................................. 94, 99 CONTINUE command......................................... 62 control commands...................................... 9, 57 COUNT condition.................................... 110, 111 COUNT_EQ condition...................................... 101 COUNT_GT condition...................................... 101 COUNT_LT condition...................................... 101 CREATE command............................... 69, 70, 73, 75 create types............................................. 70 CREATE_DONE reply.................................... 73, 75 data octets...................................... 43, 47, 52 data packing............................................. 10 data transfer commands................................ 9, 41 data transmission........................................ 10 datagrams................................................. 5 debugging.............................................. 1, 3
Page 125
default breakpoint................................... 71, 92 DELETE command....................................... 73, 75 DELETE_DONE reply........................................ 75 descriptor........... 20, 57, 61, 62, 63, 64, 65, 73, 75, 93 dumping................................................... 3 ERRACK............................................... 10, 39 ERROR codes.............................................. 38 ERROR reply.......................................... 37, 67 EXCEPTION trap........................................... 66 finite state machine................................. 60, 93 FSM breakpoint................................... 71, 92, 94 FULL-DEBUGGER............................................ 12 FULL_DEBUGGER............................................ 32 gateway................................................ 3, 9 GET_OBJECT command................................... 89, 91 GET_PHYS_ADDR command................................ 87, 88 GOT_OBJECT reply..................................... 89, 91 GOT_PHYS_ADDR reply.................................. 87, 88 HELLO command......................................... 9, 29 HELLO_REPLY....................................... 9, 19, 30 host descriptor.......................................... 41 implementation....................................... 12, 31 INC_COUNT command......................... 94, 107, 110, 111 INCREMENT command....................................... 109 internet.................................................. 5 internet protocols........................................ 4 IP........................................................ 5 LDP command formats...................................... 15 LDP header........................................... 15, 16 LDP Version.............................................. 30 LIST commands............................................ 73 LIST_ADDRESSES command............................... 76, 77 LIST_BREAKPOINTS command............................. 79, 80 LIST_NAMES command................................... 84, 85 LIST_PROCESSES command................................... 82 LOADER_DUMPER........................................ 12, 32 loading................................................ 1, 3 long address format...................................... 20 management commands...................................... 67 memory object............................................ 73 MOVE command................................. 22, 41, 47, 49 MOVE sequence number..................................... 52 MOVE_DATA response................................... 22, 51 MOVE_DONE reply.......................................... 52 NAME_LIST reply...................................... 84, 85 offset............................................... 20, 22 OR command.............................................. 111
Page 126 PAD.................................................... 3, 9 pattern.................................................. 54 PHYS_ADDRESS............................................. 57 PHYS_MACRO............................................... 60 PROCESS.................................................. 57 PROCESS_CODE............................................. 60 PROCESS_LIST reply....................................... 82 protocol commands......................................... 9 PSN.................................................... 3, 9 RDP................................................... 5, 15 READ command..................................... 41, 43, 44 READ sequence number..................................... 47 READ_DATA response................................... 45, 46 READ_DONE reply.......................................... 47 repeat count............................................. 54 REPEAT_DATA command.................................. 41, 53 REPORT command................................... 63, 64, 94 sequence number...................................... 10, 39 session................................................... 9 SET_PTR command................................ 94, 111, 112 SET_STATE command.............................. 94, 107, 113 short address format..................................... 25 START command........................................ 59, 60 STATUS reply..................................... 64, 65, 94 STEP command......................................... 62, 63 STOP command......................................... 60, 61 SYNCH.................................................... 10 SYNCH command............................................ 33 SYNCH_REPLY.............................................. 34 system type.............................................. 30 target start address......................... 43, 44, 46, 54 transport................................................. 9 watchpoint.......... 13, 57, 60, 71, 92, 93, 95, 96, 99, 107 WRITE command........................................ 41, 42 WRITE_MASK command....................................... 56
Page 127
Page 128
📦 where this page comes from
- ietf: rfc909 1984-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms