1 This debug server uses a largely text-based protocol, except for
2 certain bulk data transfer operations. All text is in single-byte
3 US-ASCII except for the strings returned in "proclist".
4
5 NOTE that the character '|' (vertical bar) is used as an escape
6 character to switch the incoming data stream to the debug server into
7 binary mode, so no text command may contain that character.
8
9 Commands understood:
10
11 ascii <EOL> ::=
12
13 Changes to ASCII mode. This affects all outgoing strings. At
14 startup the system is in unicode mode.
15
16 unicode <EOL> ::=
17
18 Changes to UNICODE mode. This affects all outgoing strings. This
19 is the default mode upon startup.
20
21 proclist <EOL> ::=
22 <int num> [<unsigned int pid> <int charSize> <int numChars> [<binary char_t name>]...]... <EOL>
23
24 Returns integer indicating number of processes to follow, followed
25 by (pid, name) pairs. Names are given by (charSize, numChars,
26 [char_t]...) tuples; charSize indicates the size of each character
27 in bytes, numChars the number of characters in the string, and
28 name the raw data for the string. Each individual character of the
29 string, if multi-byte, is transmitted in network byte order.
30 numChars and name are guaranteed to be separated by precisely one
31 US-ASCII space. If process list is not available because of
32 limitations of the underlying operating system, number of
33 processes returned is 0.
34
35 attach <int pid> <EOL> ::= <bool result> <EOL>
36
37 Attempts to attach to the specified process. Returns 1 if
38 successful, 0 if not. Will fail if already attached or if the
39 process ID does not exist. Attaching to a process causes the
40 process to be suspended.
41
42 detach <EOL> ::= <bool result> <EOL>
43
44 Detaches from the given process. Attaching and detaching multiple
45 times during a debugging session is allowed. Detaching causes the
46 process to resume execution.
47
48 libinfo <EOL> ::=
49 <int numLibs> [<int charSize> <int numChars> [<binary char_t name>]... <address baseAddr>]... <EOL>
50
51 May only be called once attached and the target process must be
52 suspended; otherwise, returns 0. Returns list of the full path
53 names of all of the loaded modules (including the executable
54 image) in the target process, as well as the base address at which
55 each module was relocated. See proclist for format of strings, but
56 NOTE that charSize is ALWAYS 1 for this particular routine,
57 regardless of the setting of ASCII/UNICODE.
58
59 peek <address addr> <unsigned int numBytes> <EOL> ::=
60 B<binary char success>
61 [<binary unsigned int len> <binary char isMapped> [<binary char data>]...]...
62
63 NOTE that the binary portion of this message is prefixed by the
64 uppercase US-ASCII letter 'B', allowing easier synchronization by
65 clients. There is no data between the 'B' and the rest of the
66 message.
67
68 May only be called once attached. Reads the address space of the
69 target process starting at the given address (see below for format
70 specifications) and extending the given number of bytes. Whether
71 the read succeeded is indicated by a single byte containing a 1 or
72 0 (success or failure). If successful, the return result is given
73 in a sequence of ranges. _len_, the length of each range, is
74 indicated by a 32-bit unsigned integer transmitted with big-endian
75 byte ordering (i.e., most significant byte first). _isMapped_
76 indicates whether the range is mapped or unmapped in the target
77 process's address space, and will contain the value 1 or 0 for
78 mapped or unmapped, respectively. If the range is mapped,
79 _isMapped_ is followed by _data_, containing the raw binary data
80 for the range. The sum of all ranges' lengths is guaranteed to be
81 equivalent to the number of bytes requested.
82
83 poke <address addr> |[<binary unsigned int len> [<binary char data>]] <EOL> ::=
84 <bool result> <EOL>
85
86 NOTE that the binary portion of this message is prefixed by the
87 uppercase US-ASCII character '|' (vertical bar), allowing easier
88 synchronization by the server. There is no data between the '|'
89 and the rest of the message. ('B' is not used here because
90 addresses can contain that letter; no alphanumeric characters are
91 used because some of the parsing routines are used by the Solaris
92 SA port, and in that port any alphanumeric character can show up
93 as a part of a symbol being looked up.)
94
95 May only be called once attached. Writes the address space of the
96 target process starting at the given address (see below for format
97 specifications), extending the given number of bytes, and
98 containing the given data. The number of bytes is a 32-bit
99 unsigned integer transmitted with big-endian byte ordering (i.e.,
100 most significant byte first). This is followed by the raw binary
101 data to be placed at that address. The number of bytes of data
102 must match the number of bytes specified in the message.
103
104 Returns true if the write succeeded; false if it failed, for
105 example because a portion of the region was not mapped in the
106 target address space.
107
108 threadlist <EOL> ::= <int numThreads> [<address threadHandle>...] <EOL>
109
110 May only be called once attached and the target process must be
111 suspended; otherwise, returns 0. If available, returns handles for
112 all of the threads in the target process. These handles may be
113 used as arguments to the getcontext and selectorentry
114 commands. They do not need to be (and should not be) duplicated
115 via the duphandle command and must not be closed via the
116 closehandle command.
117
118 duphandle <address handle> <EOL> ::=
119 <bool success> [<address duplicate>] <EOL>
120
121 Duplicates a HANDLE read from the target process's address space.
122 HANDLE is a Windows construct (typically typedef'd to void *).
123 The returned handle should ultimately be closed via the
124 closehandle command; failing to do so can cause resource leaks.
125
126 The purpose of this command is to allow the debugger to read the
127 value of a thread handle from the target process and query its
128 register set and thread selector entries via the getcontext and
129 selectorentry commands, below; such use implies that the target
130 program has its own notion of the thread list, and further, that
131 the debugger has a way of locating that thread list.
132
133 closehandle <address handle> <EOL> ::=
134
135 Closes a handle retrieved via the duphandle command, above.
136
137 getcontext <address threadHandle> <EOL> ::= <bool success> [<context>] <EOL>
138
139 Returns the context for the given thread. The handle must either
140 be one of the handles returned from the threadlist command or the
141 result of duplicating a thread handle out of the target process
142 via the duphandle command. The target process must be suspended.
143
144 The context is returned as a series of hex values which represent
145 the following x86 registers in the following order:
146 EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP, DS, ES, FS, GS,
147 CS, SS, EFLAGS, DR0, DR1, DR2, DR3, DR6, DR7
148
149 FIXME: needs to be generalized and/or specified for other
150 architectures.
151
152 setcontext <address threadHandle> <context> ::= <bool success> <EOL>
153
154 Sets the context of the given thread. The target process must be
155 suspended. See the getcontext command for the ordering of the
156 registers in the context.
157
158 Even if the setcontext command succeeds, some of the bits in some
159 of the registers (like the global enable bits in the debug
160 registers) may be overridden by the operating system. To ensure
161 the debugger's notion of the register set is up to date, it is
162 recommended to follow up a setcontext with a getcontext.
163
164 selectorentry <address threadHandle> <int selector> <EOL> ::=
165 <bool success>
166 [<address limitLow> <address baseLow>
167 <address baseMid> <address flags1>
168 <address flags2> <address baseHi>] <EOL>
169
170 Retrieves a descriptor table entry for the given thread and
171 selector. This data structure allows conversion of a
172 segment-relative address to a linear virtual address. It is most
173 useful for locating the Thread Information Block for a given
174 thread handle to be able to find that thread's ID, to be able to
175 understand whether two different thread handles in fact refer to
176 the same underlying thread.
177
178 This command will only work on the X86 architecture and will
179 return false for the success flag (with no additional information
180 sent) on other architectures.
181
182 suspend ::=
183
184 Suspends the target process. Must be attached to a target process.
185 A process is suspended when attached to via the attach command. If
186 the target process is already suspended then this command has no
187 effect.
188
189 resume ::=
190
191 Resumes the target process without detaching from it. Must be
192 attached to a target process. After resuming a target process, the
193 debugger client must be prepared to poll for events from the
194 target process fairly frequently in order for execution in the
195 target process to proceed normally. If the target process is
196 already resumed then this command has no effect.
197
198 pollevent ::=
199 <bool eventPresent> [<address threadHandle> <unsigned int eventCode>]
200
201 Additional entries in result for given eventCode:
202
203 LOAD/UNLOAD_DLL_DEBUG_EVENT: <address baseOfDLL>
204 EXCEPTION_DEBUG_EVENT: <unsigned int exceptionCode> <address faultingPC>
205
206 Additional entries for given exceptionCode:
207
208 EXCEPTION_ACCESS_VIOLATION: <bool wasWrite> <address faultingAddress>
209
210 <EOL>
211
212 Polls once to see whether a debug event has been generated by the
213 target process. If none is present, returns 0 immediately.
214 Otherwise, returns 1 along with a series of textual information
215 about the event. The event is not cleared, and the thread resumed,
216 until the continueevent command is sent, or the debugger client
217 detaches from the target process.
218
219 Typically a debugger client will suspend the target process upon
220 reception of a debug event. Otherwise, it is not guaranteed that
221 all threads will be suspended upon reception of a debug event, and
222 any operations requiring that threads be suspended (including
223 fetching the context for the thread which generated the event)
224 will fail.
225
226 continueevent <bool passEventToClient> ::= <bool success> <EOL>
227
228 Indicates that the current debug event has been used by the
229 debugger client and that the target process should be resumed. The
230 passEventToClient flag indicates whether the event should be
231 propagated to the target process. Breakpoint and single-step
232 events should not be propagated to the target. Returns false if
233 there was no pending event, true otherwise.
234
235 exit <EOL>
236
237 Exits this debugger session.
238
239 Format specifications:
240
241 // Data formats and example values:
242 <EOL> ::= end of line (typically \n on Unix platforms, or \n\r on Windows)
243 <address> ::= 0x12345678[9ABCDEF0] /* up to 64-bit hex value */
244 <unsigned int> ::= 5 /* up to 32-bit integer number; no leading sign */
245 <bool> ::= 1 /* ASCII '0' or '1' */
246 <context> ::= <address> ...