]> git.saurik.com Git - apple/xnu.git/blob - osfmk/kdp/kdp_protocol.h
xnu-792.6.70.tar.gz
[apple/xnu.git] / osfmk / kdp / kdp_protocol.h
1 /*
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * The contents of this file constitute Original Code as defined in and
7 * are subject to the Apple Public Source License Version 1.1 (the
8 * "License"). You may not use this file except in compliance with the
9 * License. Please obtain a copy of the License at
10 * http://www.apple.com/publicsource and read it before using this file.
11 *
12 * This Original Code and all software distributed under the License are
13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
17 * License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * @APPLE_LICENSE_HEADER_END@
21 */
22
23 /*
24 * Definition of remote debugger protocol.
25 */
26
27 #include <mach/vm_prot.h>
28
29 /*
30 * Retransmit parameters
31 */
32 #if DDEBUG_DEBUG || DEBUG_DEBUG
33 #define KDP_REXMIT_SECS 20 /* rexmit if no ack in 3 secs */
34 #else /* DDEBUG_DEBUG || DEBUG_DEBUG */
35 #define KDP_REXMIT_SECS 3 /* rexmit if no ack in 3 secs */
36 #endif /* DDEBUG_DEBUG || DEBUG_DEBUG */
37 #define KDP_REXMIT_TRIES 8 /* xmit 8 times, then give up */
38
39 /*
40 * (NMI) Attention Max Wait Time
41 * Remote will resume unless KDP requests is received within this
42 * many seconds after an attention (nmi) packet is sent.
43 */
44 #define KDP_MAX_ATTN_WAIT 30 /* wait max of 30 seconds */
45
46 /*
47 * Well-known UDP port, debugger side.
48 * FIXME: This is what the 68K guys use, but beats me how they chose it...
49 */
50 #define KDP_REMOTE_PORT 41139 /* pick one and register it */
51
52 /*
53 * UDP ports, KDB side. 5 port numbers are reserved for each port (request
54 * and exception). This allows multiple KDBs to run on one host.
55 */
56 #define UDP_HOST_COMM_BASE 41140
57 #define UDP_HOST_EXCEP_BASE 41145
58 #define NUM_UDP_HOST_PORTS 5
59
60 /*
61 * Requests
62 */
63 typedef enum {
64 /* connection oriented requests */
65 KDP_CONNECT, KDP_DISCONNECT,
66
67 /* obtaining client info */
68 KDP_HOSTINFO, KDP_VERSION, KDP_MAXBYTES,
69
70 /* memory access */
71 KDP_READMEM, KDP_WRITEMEM,
72
73 /* register access */
74 KDP_READREGS, KDP_WRITEREGS,
75
76 /* executable image info */
77 KDP_LOAD, KDP_IMAGEPATH,
78
79 /* execution control */
80 KDP_SUSPEND, KDP_RESUMECPUS,
81
82 /* exception and termination notification, NOT true requests */
83 KDP_EXCEPTION, KDP_TERMINATION,
84
85 /* breakpoint control */
86 KDP_BREAKPOINT_SET, KDP_BREAKPOINT_REMOVE,
87
88 /* vm regions */
89 KDP_REGIONS,
90
91 /* reattach to a connected host */
92 KDP_REATTACH,
93
94 /* remote reboot request */
95 KDP_HOSTREBOOT
96 } kdp_req_t;
97
98 /*
99 * Common KDP packet header
100 */
101 typedef struct {
102 kdp_req_t request:7; /* request type */
103 unsigned is_reply:1; /* 0 => request, 1 => reply */
104 unsigned seq:8; /* sequence number within session */
105 unsigned len:16; /* length of entire pkt including hdr */
106 unsigned key; /* session key */
107 } kdp_hdr_t;
108
109 /*
110 * KDP errors
111 */
112 typedef enum {
113 KDPERR_NO_ERROR = 0,
114 KDPERR_ALREADY_CONNECTED,
115 KDPERR_BAD_NBYTES,
116 KDPERR_BADFLAVOR /* bad flavor in w/r regs */
117 } kdp_error_t;
118
119 /*
120 * KDP requests and reply packet formats
121 */
122
123 /*
124 * KDP_CONNECT
125 */
126 typedef struct { /* KDP_CONNECT request */
127 kdp_hdr_t hdr;
128 unsigned short req_reply_port; /* udp port which to send replies */
129 unsigned short exc_note_port; /* udp port which to send exc notes */
130 char greeting[0]; /* "greetings", null-terminated */
131 } kdp_connect_req_t;
132
133 typedef struct { /* KDP_CONNECT reply */
134 kdp_hdr_t hdr;
135 kdp_error_t error;
136 } kdp_connect_reply_t;
137
138 /*
139 * KDP_DISCONNECT
140 */
141 typedef struct { /* KDP_DISCONNECT request */
142 kdp_hdr_t hdr;
143 } kdp_disconnect_req_t;
144
145 typedef struct { /* KDP_DISCONNECT reply */
146 kdp_hdr_t hdr;
147 } kdp_disconnect_reply_t;
148
149 /*
150 * KDP_REATTACH
151 */
152 typedef struct {
153 kdp_hdr_t hdr;
154 unsigned short req_reply_port; /* udp port which to send replies */
155 } kdp_reattach_req_t;
156
157 /*
158 * KDP_HOSTINFO
159 */
160 typedef struct { /* KDP_HOSTINFO request */
161 kdp_hdr_t hdr;
162 } kdp_hostinfo_req_t;
163
164 typedef struct {
165 unsigned cpus_mask; /* bit is 1 if cpu present */
166 int cpu_type;
167 int cpu_subtype;
168 } kdp_hostinfo_t;
169
170 typedef struct { /* KDP_HOSTINFO reply */
171 kdp_hdr_t hdr;
172 kdp_hostinfo_t hostinfo;
173 } kdp_hostinfo_reply_t;
174
175 /*
176 * KDP_VERSION
177 */
178 typedef struct { /* KDP_VERSION request */
179 kdp_hdr_t hdr;
180 } kdp_version_req_t;
181
182 #define KDP_FEATURE_BP 0x1 /* local breakpoint support */
183
184 typedef struct { /* KDP_REGIONS reply */
185 kdp_hdr_t hdr;
186 unsigned version;
187 unsigned feature;
188 unsigned pad0;
189 unsigned pad1;
190 } kdp_version_reply_t;
191
192 /*
193 * KDP_REGIONS
194 */
195 typedef struct { /* KDP_REGIONS request */
196 kdp_hdr_t hdr;
197 } kdp_regions_req_t;
198
199 #define VM_PROT_VOLATILE ((vm_prot_t) 0x08) /* not cacheable */
200 #define VM_PROT_SPARSE ((vm_prot_t) 0x10) /* sparse addr space */
201
202 typedef struct {
203 void *address;
204 unsigned nbytes;
205 vm_prot_t protection;
206 } kdp_region_t;
207
208 typedef struct { /* KDP_REGIONS reply */
209 kdp_hdr_t hdr;
210 unsigned nregions;
211 kdp_region_t regions[0];
212 } kdp_regions_reply_t;
213
214 /*
215 * KDP_MAXBYTES
216 */
217 typedef struct { /* KDP_MAXBYTES request */
218 kdp_hdr_t hdr;
219 } kdp_maxbytes_req_t;
220
221 typedef struct { /* KDP_MAXBYTES reply */
222 kdp_hdr_t hdr;
223 unsigned max_bytes;
224 } kdp_maxbytes_reply_t;
225
226 /*
227 * KDP_READMEM
228 */
229 typedef struct { /* KDP_READMEM request */
230 kdp_hdr_t hdr;
231 void *address;
232 unsigned nbytes;
233 } kdp_readmem_req_t;
234
235 typedef struct { /* KDP_READMEM reply */
236 kdp_hdr_t hdr;
237 kdp_error_t error;
238 char data[0];
239 } kdp_readmem_reply_t;
240
241 /*
242 * KDP_WRITEMEM
243 */
244 typedef struct { /* KDP_WRITEMEM request */
245 kdp_hdr_t hdr;
246 void *address;
247 unsigned nbytes;
248 char data[0];
249 } kdp_writemem_req_t;
250
251 typedef struct { /* KDP_WRITEMEM reply */
252 kdp_hdr_t hdr;
253 kdp_error_t error;
254 } kdp_writemem_reply_t;
255
256 /*
257 * KDP_READREGS
258 */
259 typedef struct { /* KDP_READREGS request */
260 kdp_hdr_t hdr;
261 unsigned cpu;
262 unsigned flavor;
263 } kdp_readregs_req_t;
264
265 typedef struct { /* KDP_READREGS reply */
266 kdp_hdr_t hdr;
267 kdp_error_t error; /* could be KDPERR_BADFLAVOR */
268 char data[0];
269 } kdp_readregs_reply_t;
270
271 /*
272 * KDP_WRITEREGS
273 */
274 typedef struct { /* KDP_WRITEREGS request */
275 kdp_hdr_t hdr;
276 unsigned cpu;
277 unsigned flavor;
278 char data[0];
279 } kdp_writeregs_req_t;
280
281 typedef struct { /* KDP_WRITEREGS reply */
282 kdp_hdr_t hdr;
283 kdp_error_t error;
284 } kdp_writeregs_reply_t;
285
286 /*
287 * KDP_LOAD
288 */
289 typedef struct { /* KDP_LOAD request */
290 kdp_hdr_t hdr;
291 char file_args[0];
292 } kdp_load_req_t;
293
294 typedef struct { /* KDP_LOAD reply */
295 kdp_hdr_t hdr;
296 kdp_error_t error;
297 } kdp_load_reply_t;
298
299 /*
300 * KDP_IMAGEPATH
301 */
302 typedef struct { /* KDP_IMAGEPATH request */
303 kdp_hdr_t hdr;
304 } kdp_imagepath_req_t;
305
306 typedef struct { /* KDP_IMAGEPATH reply */
307 kdp_hdr_t hdr;
308 char path[0];
309 } kdp_imagepath_reply_t;
310
311 /*
312 * KDP_SUSPEND
313 */
314 typedef struct { /* KDP_SUSPEND request */
315 kdp_hdr_t hdr;
316 } kdp_suspend_req_t;
317
318 typedef struct { /* KDP_SUSPEND reply */
319 kdp_hdr_t hdr;
320 } kdp_suspend_reply_t;
321
322 /*
323 * KDP_RESUMECPUS
324 */
325 typedef struct { /* KDP_RESUMECPUS request */
326 kdp_hdr_t hdr;
327 unsigned cpu_mask;
328 } kdp_resumecpus_req_t;
329
330 typedef struct { /* KDP_RESUMECPUS reply */
331 kdp_hdr_t hdr;
332 } kdp_resumecpus_reply_t;
333
334 typedef struct {
335 kdp_hdr_t hdr;
336 unsigned long address;
337 } kdp_breakpoint_req_t;
338
339 typedef struct {
340 kdp_hdr_t hdr;
341 kdp_error_t error;
342 } kdp_breakpoint_reply_t;
343
344 /*
345 * Exception notifications
346 * (Exception notifications are not requests, and in fact travel from
347 * the remote debugger to the gdb agent KDB.)
348 */
349 typedef struct { /* exc. info for one cpu */
350 unsigned cpu;
351 /*
352 * Following info is defined as
353 * per <mach/exception.h>
354 */
355 unsigned exception;
356 unsigned code;
357 unsigned subcode;
358 } kdp_exc_info_t;
359
360 typedef struct { /* KDP_EXCEPTION notification */
361 kdp_hdr_t hdr;
362 unsigned n_exc_info;
363 kdp_exc_info_t exc_info[0];
364 } kdp_exception_t;
365
366 typedef struct { /* KDP_EXCEPTION acknowledgement */
367 kdp_hdr_t hdr;
368 } kdp_exception_ack_t;
369
370 /*
371 * Child termination messages
372 */
373 typedef enum {
374 KDP_FAULT = 0, /* child took fault (internal use) */
375 KDP_EXIT, /* child exited */
376 KDP_POWEROFF, /* child power-off */
377 KDP_REBOOT, /* child reboot */
378 KDP_COMMAND_MODE /* child exit to mon command_mode */
379 } kdp_termination_code_t;
380
381 typedef struct { /* KDP_TERMINATION notification */
382 kdp_hdr_t hdr;
383 kdp_termination_code_t term_code;
384 unsigned exit_code;
385 } kdp_termination_t;
386
387 typedef struct {
388 kdp_hdr_t hdr;
389 } kdp_termination_ack_t;
390
391 typedef union {
392 kdp_hdr_t hdr;
393 kdp_connect_req_t connect_req;
394 kdp_connect_reply_t connect_reply;
395 kdp_disconnect_req_t disconnect_req;
396 kdp_disconnect_reply_t disconnect_reply;
397 kdp_hostinfo_req_t hostinfo_req;
398 kdp_hostinfo_reply_t hostinfo_reply;
399 kdp_version_req_t version_req;
400 kdp_version_reply_t version_reply;
401 kdp_maxbytes_req_t maxbytes_req;
402 kdp_maxbytes_reply_t maxbytes_reply;
403 kdp_readmem_req_t readmem_req;
404 kdp_readmem_reply_t readmem_reply;
405 kdp_writemem_req_t writemem_req;
406 kdp_writemem_reply_t writemem_reply;
407 kdp_readregs_req_t readregs_req;
408 kdp_readregs_reply_t readregs_reply;
409 kdp_writeregs_req_t writeregs_req;
410 kdp_writeregs_reply_t writeregs_reply;
411 kdp_load_req_t load_req;
412 kdp_load_reply_t load_reply;
413 kdp_imagepath_req_t imagepath_req;
414 kdp_imagepath_reply_t imagepath_reply;
415 kdp_suspend_req_t suspend_req;
416 kdp_suspend_reply_t suspend_reply;
417 kdp_resumecpus_req_t resumecpus_req;
418 kdp_resumecpus_reply_t resumecpus_reply;
419 kdp_exception_t exception;
420 kdp_exception_ack_t exception_ack;
421 kdp_termination_t termination;
422 kdp_termination_ack_t termination_ack;
423 kdp_breakpoint_req_t breakpoint_req;
424 kdp_breakpoint_reply_t breakpoint_reply;
425 kdp_reattach_req_t reattach_req;
426 kdp_regions_req_t regions_req;
427 kdp_regions_reply_t regions_reply;
428 } kdp_pkt_t;
429
430 #define MAX_KDP_PKT_SIZE 1200 /* max packet size */
431 #define MAX_KDP_DATA_SIZE 1024 /* max r/w data per packet */