|
0
|
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> ...
|
