]> git.saurik.com Git - apple/xnu.git/blob - osfmk/kdp/kdp_protocol.h
723382ca5d3404d9aa194923e1a048ca6c5f1b9c
[apple/xnu.git] / osfmk / kdp / kdp_protocol.h
1 /*
2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29 #ifndef _KDP_PROTOCOL_H_
30 #define _KDP_PROTOCOL_H_
31
32 /*
33 * Definition of remote debugger protocol.
34 */
35
36 #include <mach/vm_prot.h>
37 #include <stdint.h>
38
39 /*
40 * Retransmit parameters
41 */
42 #if DDEBUG_DEBUG || DEBUG_DEBUG
43 #define KDP_REXMIT_SECS 20 /* rexmit if no ack in 3 secs */
44 #else /* DDEBUG_DEBUG || DEBUG_DEBUG */
45 #define KDP_REXMIT_SECS 3 /* rexmit if no ack in 3 secs */
46 #endif /* DDEBUG_DEBUG || DEBUG_DEBUG */
47 #define KDP_REXMIT_TRIES 8 /* xmit 8 times, then give up */
48
49 #define KDP_PACKED __attribute__((packed))
50
51 /*
52 * (NMI) Attention Max Wait Time
53 * Remote will resume unless KDP requests is received within this
54 * many seconds after an attention (nmi) packet is sent.
55 */
56 #define KDP_MAX_ATTN_WAIT 30 /* wait max of 30 seconds */
57
58 /*
59 * Well-known UDP port, debugger side.
60 * FIXME: This is what the 68K guys use, but beats me how they chose it...
61 */
62 #define KDP_REMOTE_PORT 41139 /* pick one and register it */
63
64 /*
65 * UDP ports, KDB side. 5 port numbers are reserved for each port (request
66 * and exception). This allows multiple KDBs to run on one host.
67 */
68 #define UDP_HOST_COMM_BASE 41140
69 #define UDP_HOST_EXCEP_BASE 41145
70 #define NUM_UDP_HOST_PORTS 5
71
72 /*
73 * Requests
74 */
75 typedef enum {
76 /* connection oriented requests */
77 KDP_CONNECT, KDP_DISCONNECT,
78
79 /* obtaining client info */
80 KDP_HOSTINFO, KDP_VERSION, KDP_MAXBYTES,
81
82 /* memory access */
83 KDP_READMEM, KDP_WRITEMEM,
84
85 /* register access */
86 KDP_READREGS, KDP_WRITEREGS,
87
88 /* executable image info */
89 KDP_LOAD, KDP_IMAGEPATH,
90
91 /* execution control */
92 KDP_SUSPEND, KDP_RESUMECPUS,
93
94 /* exception and termination notification, NOT true requests */
95 KDP_EXCEPTION, KDP_TERMINATION,
96
97 /* breakpoint control */
98 KDP_BREAKPOINT_SET, KDP_BREAKPOINT_REMOVE,
99
100 /* vm regions */
101 KDP_REGIONS,
102
103 /* reattach to a connected host */
104 KDP_REATTACH,
105
106 /* remote reboot request */
107 KDP_HOSTREBOOT,
108
109 /* memory access (64-bit wide addresses). Version 11 protocol */
110 KDP_READMEM64, KDP_WRITEMEM64,
111
112 /* breakpoint control (64-bit wide addresses). Version 11 protocol */
113 KDP_BREAKPOINT64_SET, KDP_BREAKPOINT64_REMOVE,
114
115 /* kernel version string, like "xnu-1234.5~6". Version 11 protocol */
116 KDP_KERNELVERSION,
117
118 /* physical memory access (64-bit wide addresses). Version 12 protocol */
119 KDP_READPHYSMEM64, KDP_WRITEPHYSMEM64,
120
121 /* ioport access (8-, 16-, and 32-bit) */
122 KDP_READIOPORT, KDP_WRITEIOPORT,
123
124 /* msr access (64-bit) */
125 KDP_READMSR64, KDP_WRITEMSR64,
126
127 /* keep this last */
128 KDP_INVALID_REQUEST
129 } kdp_req_t;
130
131 /*
132 * Common KDP packet header
133 */
134 typedef struct {
135 kdp_req_t request:7; /* kdp_req_t, request type */
136 unsigned is_reply:1; /* 0 => request, 1 => reply */
137 unsigned seq:8; /* sequence number within session */
138 unsigned len:16; /* length of entire pkt including hdr */
139 unsigned key; /* session key */
140 } KDP_PACKED kdp_hdr_t;
141
142 /*
143 * KDP errors
144 */
145 typedef enum {
146 KDPERR_NO_ERROR = 0,
147 KDPERR_ALREADY_CONNECTED,
148 KDPERR_BAD_NBYTES,
149 KDPERR_BADFLAVOR, /* bad flavor in w/r regs */
150 KDPERR_MAX_BREAKPOINTS = 100,
151 KDPERR_BREAKPOINT_NOT_FOUND = 101,
152 KDPERR_BREAKPOINT_ALREADY_SET = 102
153
154 } kdp_error_t;
155
156 /*
157 * KDP requests and reply packet formats
158 */
159
160 /*
161 * KDP_CONNECT
162 */
163 typedef struct { /* KDP_CONNECT request */
164 kdp_hdr_t hdr;
165 uint16_t req_reply_port; /* udp port which to send replies */
166 uint16_t exc_note_port; /* udp port which to send exc notes */
167 char greeting[0]; /* "greetings", nul-terminated */
168 } KDP_PACKED kdp_connect_req_t;
169
170 typedef struct { /* KDP_CONNECT reply */
171 kdp_hdr_t hdr;
172 kdp_error_t error;
173 } KDP_PACKED kdp_connect_reply_t;
174
175 /*
176 * KDP_DISCONNECT
177 */
178 typedef struct { /* KDP_DISCONNECT request */
179 kdp_hdr_t hdr;
180 } KDP_PACKED kdp_disconnect_req_t;
181
182 typedef struct { /* KDP_DISCONNECT reply */
183 kdp_hdr_t hdr;
184 } KDP_PACKED kdp_disconnect_reply_t;
185
186 /*
187 * KDP_REATTACH
188 */
189 typedef struct {
190 kdp_hdr_t hdr;
191 uint16_t req_reply_port; /* udp port which to send replies */
192 } KDP_PACKED kdp_reattach_req_t;
193
194 /*
195 * KDP_HOSTINFO
196 */
197 typedef struct { /* KDP_HOSTINFO request */
198 kdp_hdr_t hdr;
199 } KDP_PACKED kdp_hostinfo_req_t;
200
201 typedef struct {
202 uint32_t cpus_mask; /* bit is 1 if cpu present */
203 uint32_t cpu_type;
204 uint32_t cpu_subtype;
205 } KDP_PACKED kdp_hostinfo_t;
206
207 typedef struct { /* KDP_HOSTINFO reply */
208 kdp_hdr_t hdr;
209 kdp_hostinfo_t hostinfo;
210 } KDP_PACKED kdp_hostinfo_reply_t;
211
212 /*
213 * KDP_VERSION
214 */
215 typedef struct { /* KDP_VERSION request */
216 kdp_hdr_t hdr;
217 } KDP_PACKED kdp_version_req_t;
218
219 #define KDP_FEATURE_BP 0x1 /* local breakpoint support */
220
221 typedef struct { /* KDP_VERSION reply */
222 kdp_hdr_t hdr;
223 uint32_t version;
224 uint32_t feature;
225 uint32_t pad0;
226 uint32_t pad1;
227 } KDP_PACKED kdp_version_reply_t;
228
229 #define VM_PROT_VOLATILE ((vm_prot_t) 0x08) /* not cacheable */
230 #define VM_PROT_SPARSE ((vm_prot_t) 0x10) /* sparse addr space */
231
232 /*
233 * KDP_REGIONS
234 */
235 typedef struct { /* KDP_REGIONS request */
236 kdp_hdr_t hdr;
237 } KDP_PACKED kdp_regions_req_t;
238
239 typedef struct {
240 uint32_t address;
241 uint32_t nbytes;
242 uint32_t protection; /* vm_prot_t */
243 } KDP_PACKED kdp_region_t;
244
245 typedef struct { /* KDP_REGIONS reply */
246 kdp_hdr_t hdr;
247 uint32_t nregions;
248 kdp_region_t regions[0];
249 } KDP_PACKED kdp_regions_reply_t;
250
251 /*
252 * KDP_MAXBYTES
253 */
254 typedef struct { /* KDP_MAXBYTES request */
255 kdp_hdr_t hdr;
256 } KDP_PACKED kdp_maxbytes_req_t;
257
258 typedef struct { /* KDP_MAXBYTES reply */
259 kdp_hdr_t hdr;
260 uint32_t max_bytes;
261 } KDP_PACKED kdp_maxbytes_reply_t;
262
263 /*
264 * KDP_READMEM
265 */
266 typedef struct { /* KDP_READMEM request */
267 kdp_hdr_t hdr;
268 uint32_t address;
269 uint32_t nbytes;
270 } KDP_PACKED kdp_readmem_req_t;
271
272 typedef struct { /* KDP_READMEM reply */
273 kdp_hdr_t hdr;
274 kdp_error_t error;
275 char data[0];
276 } KDP_PACKED kdp_readmem_reply_t;
277
278 /*
279 * KDP_READMEM64
280 */
281 typedef struct { /* KDP_READMEM64 request */
282 kdp_hdr_t hdr;
283 uint64_t address;
284 uint32_t nbytes;
285 } KDP_PACKED kdp_readmem64_req_t;
286
287 typedef struct { /* KDP_READMEM64 reply */
288 kdp_hdr_t hdr;
289 kdp_error_t error;
290 char data[0];
291 } KDP_PACKED kdp_readmem64_reply_t;
292
293 /*
294 * KDP_READPHYSMEM64
295 */
296 typedef struct { /* KDP_READPHYSMEM64 request */
297 kdp_hdr_t hdr;
298 uint64_t address;
299 uint32_t nbytes;
300 uint16_t lcpu;
301 } KDP_PACKED kdp_readphysmem64_req_t;
302
303 typedef struct { /* KDP_READPHYSMEM64 reply */
304 kdp_hdr_t hdr;
305 kdp_error_t error;
306 char data[0];
307 } KDP_PACKED kdp_readphysmem64_reply_t;
308
309 /*
310 * KDP_WRITEMEM
311 */
312 typedef struct { /* KDP_WRITEMEM request */
313 kdp_hdr_t hdr;
314 uint32_t address;
315 uint32_t nbytes;
316 char data[0];
317 } KDP_PACKED kdp_writemem_req_t;
318
319 typedef struct { /* KDP_WRITEMEM reply */
320 kdp_hdr_t hdr;
321 kdp_error_t error;
322 } KDP_PACKED kdp_writemem_reply_t;
323
324 /*
325 * KDP_WRITEMEM64
326 */
327 typedef struct { /* KDP_WRITEMEM64 request */
328 kdp_hdr_t hdr;
329 uint64_t address;
330 uint32_t nbytes;
331 char data[0];
332 } KDP_PACKED kdp_writemem64_req_t;
333
334 typedef struct { /* KDP_WRITEMEM64 reply */
335 kdp_hdr_t hdr;
336 kdp_error_t error;
337 } KDP_PACKED kdp_writemem64_reply_t;
338
339 /*
340 * KDP_WRITEPHYSMEM64
341 */
342 typedef struct { /* KDP_WRITEPHYSMEM64 request */
343 kdp_hdr_t hdr;
344 uint64_t address;
345 uint32_t nbytes;
346 uint16_t lcpu;
347 char data[0];
348 } KDP_PACKED kdp_writephysmem64_req_t;
349
350 typedef struct { /* KDP_WRITEPHYSMEM64 reply */
351 kdp_hdr_t hdr;
352 kdp_error_t error;
353 } KDP_PACKED kdp_writephysmem64_reply_t;
354
355 /*
356 * KDP_WRITEIOPORT
357 */
358 typedef struct { /* KDP_WRITEIOPORT request */
359 kdp_hdr_t hdr;
360 uint16_t lcpu;
361 uint16_t address;
362 uint16_t nbytes;
363 char data[0];
364 } KDP_PACKED kdp_writeioport_req_t;
365
366 typedef struct { /* KDP_WRITEIOPORT reply */
367 kdp_hdr_t hdr;
368 kdp_error_t error;
369 } KDP_PACKED kdp_writeioport_reply_t;
370
371 /*
372 * KDP_READIOPORT
373 */
374 typedef struct { /* KDP_READIOPORT request */
375 kdp_hdr_t hdr;
376 uint16_t lcpu;
377 uint16_t address;
378 uint16_t nbytes;
379 } KDP_PACKED kdp_readioport_req_t;
380
381 typedef struct { /* KDP_READIOPORT reply */
382 kdp_hdr_t hdr;
383 kdp_error_t error;
384 char data[0];
385 } KDP_PACKED kdp_readioport_reply_t;
386
387
388 /*
389 * KDP_WRITEMSR64
390 */
391 typedef struct { /* KDP_WRITEMSR64 request */
392 kdp_hdr_t hdr;
393 uint32_t address;
394 uint16_t lcpu;
395 char data[0];
396 } KDP_PACKED kdp_writemsr64_req_t;
397
398 typedef struct { /* KDP_WRITEMSR64 reply */
399 kdp_hdr_t hdr;
400 kdp_error_t error;
401 } KDP_PACKED kdp_writemsr64_reply_t;
402
403 /*
404 * KDP_READMSR64
405 */
406 typedef struct { /* KDP_READMSR64 request */
407 kdp_hdr_t hdr;
408 uint32_t address;
409 uint16_t lcpu;
410 } KDP_PACKED kdp_readmsr64_req_t;
411
412 typedef struct { /* KDP_READMSR64 reply */
413 kdp_hdr_t hdr;
414 kdp_error_t error;
415 char data[0];
416 } KDP_PACKED kdp_readmsr64_reply_t;
417
418
419 /*
420 * KDP_READREGS
421 */
422 typedef struct { /* KDP_READREGS request */
423 kdp_hdr_t hdr;
424 uint32_t cpu;
425 uint32_t flavor;
426 } KDP_PACKED kdp_readregs_req_t;
427
428 typedef struct { /* KDP_READREGS reply */
429 kdp_hdr_t hdr;
430 kdp_error_t error; /* could be KDPERR_BADFLAVOR */
431 char data[0];
432 } KDP_PACKED kdp_readregs_reply_t;
433
434 /*
435 * KDP_WRITEREGS
436 */
437 typedef struct { /* KDP_WRITEREGS request */
438 kdp_hdr_t hdr;
439 uint32_t cpu;
440 uint32_t flavor;
441 char data[0];
442 } KDP_PACKED kdp_writeregs_req_t;
443
444 typedef struct { /* KDP_WRITEREGS reply */
445 kdp_hdr_t hdr;
446 kdp_error_t error;
447 } KDP_PACKED kdp_writeregs_reply_t;
448
449 /*
450 * KDP_LOAD
451 */
452 typedef struct { /* KDP_LOAD request */
453 kdp_hdr_t hdr;
454 char file_args[0];
455 } KDP_PACKED kdp_load_req_t;
456
457 typedef struct { /* KDP_LOAD reply */
458 kdp_hdr_t hdr;
459 kdp_error_t error;
460 } KDP_PACKED kdp_load_reply_t;
461
462 /*
463 * KDP_IMAGEPATH
464 */
465 typedef struct { /* KDP_IMAGEPATH request */
466 kdp_hdr_t hdr;
467 } KDP_PACKED kdp_imagepath_req_t;
468
469 typedef struct { /* KDP_IMAGEPATH reply */
470 kdp_hdr_t hdr;
471 char path[0];
472 } KDP_PACKED kdp_imagepath_reply_t;
473
474 /*
475 * KDP_SUSPEND
476 */
477 typedef struct { /* KDP_SUSPEND request */
478 kdp_hdr_t hdr;
479 } KDP_PACKED kdp_suspend_req_t;
480
481 typedef struct { /* KDP_SUSPEND reply */
482 kdp_hdr_t hdr;
483 } KDP_PACKED kdp_suspend_reply_t;
484
485 /*
486 * KDP_RESUMECPUS
487 */
488 typedef struct { /* KDP_RESUMECPUS request */
489 kdp_hdr_t hdr;
490 uint32_t cpu_mask;
491 } KDP_PACKED kdp_resumecpus_req_t;
492
493 typedef struct { /* KDP_RESUMECPUS reply */
494 kdp_hdr_t hdr;
495 } KDP_PACKED kdp_resumecpus_reply_t;
496
497 /*
498 * KDP_BREAKPOINT_SET and KDP_BREAKPOINT_REMOVE
499 */
500
501 typedef struct {
502 kdp_hdr_t hdr;
503 uint32_t address;
504 } KDP_PACKED kdp_breakpoint_req_t;
505
506 typedef struct {
507 kdp_hdr_t hdr;
508 kdp_error_t error;
509 } KDP_PACKED kdp_breakpoint_reply_t;
510
511 /*
512 * KDP_BREAKPOINT64_SET and KDP_BREAKPOINT64_REMOVE
513 */
514
515 typedef struct {
516 kdp_hdr_t hdr;
517 uint64_t address;
518 } KDP_PACKED kdp_breakpoint64_req_t;
519
520 typedef struct {
521 kdp_hdr_t hdr;
522 kdp_error_t error;
523 } KDP_PACKED kdp_breakpoint64_reply_t;
524
525 /*
526 * Exception notifications
527 * (Exception notifications are not requests, and in fact travel from
528 * the remote debugger to the gdb agent KDB.)
529 */
530 typedef struct { /* exc. info for one cpu */
531 uint32_t cpu;
532 /*
533 * Following info is defined as
534 * per <mach/exception.h>
535 */
536 uint32_t exception;
537 uint32_t code;
538 uint32_t subcode;
539 } KDP_PACKED kdp_exc_info_t;
540
541 typedef struct { /* KDP_EXCEPTION notification */
542 kdp_hdr_t hdr;
543 uint32_t n_exc_info;
544 kdp_exc_info_t exc_info[0];
545 } KDP_PACKED kdp_exception_t;
546
547 typedef struct { /* KDP_EXCEPTION acknowledgement */
548 kdp_hdr_t hdr;
549 } KDP_PACKED kdp_exception_ack_t;
550
551 /*
552 * KDP_KERNELVERSION
553 */
554 typedef struct { /* KDP_KERNELVERSION request */
555 kdp_hdr_t hdr;
556 } KDP_PACKED kdp_kernelversion_req_t;
557
558 typedef struct { /* KDP_KERNELVERSION reply */
559 kdp_hdr_t hdr;
560 char version[0];
561 } KDP_PACKED kdp_kernelversion_reply_t;
562
563
564 /*
565 * Child termination messages
566 */
567 typedef enum {
568 KDP_FAULT = 0, /* child took fault (internal use) */
569 KDP_EXIT, /* child exited */
570 KDP_POWEROFF, /* child power-off */
571 KDP_REBOOT, /* child reboot */
572 KDP_COMMAND_MODE /* child exit to mon command_mode */
573 } kdp_termination_code_t;
574
575 typedef struct { /* KDP_TERMINATION notification */
576 kdp_hdr_t hdr;
577 uint32_t term_code; /* kdp_termination_code_t */
578 uint32_t exit_code;
579 } KDP_PACKED kdp_termination_t;
580
581 typedef struct {
582 kdp_hdr_t hdr;
583 } KDP_PACKED kdp_termination_ack_t;
584
585 typedef union {
586 kdp_hdr_t hdr;
587 kdp_connect_req_t connect_req;
588 kdp_connect_reply_t connect_reply;
589 kdp_disconnect_req_t disconnect_req;
590 kdp_disconnect_reply_t disconnect_reply;
591 kdp_hostinfo_req_t hostinfo_req;
592 kdp_hostinfo_reply_t hostinfo_reply;
593 kdp_version_req_t version_req;
594 kdp_version_reply_t version_reply;
595 kdp_maxbytes_req_t maxbytes_req;
596 kdp_maxbytes_reply_t maxbytes_reply;
597 kdp_readmem_req_t readmem_req;
598 kdp_readmem_reply_t readmem_reply;
599 kdp_readmem64_req_t readmem64_req;
600 kdp_readmem64_reply_t readmem64_reply;
601 kdp_readphysmem64_req_t readphysmem64_req;
602 kdp_readphysmem64_reply_t readphysmem64_reply;
603 kdp_writemem_req_t writemem_req;
604 kdp_writemem_reply_t writemem_reply;
605 kdp_writemem64_req_t writemem64_req;
606 kdp_writemem64_reply_t writemem64_reply;
607 kdp_writephysmem64_req_t writephysmem64_req;
608 kdp_writephysmem64_reply_t writephysmem64_reply;
609 kdp_readregs_req_t readregs_req;
610 kdp_readregs_reply_t readregs_reply;
611 kdp_writeregs_req_t writeregs_req;
612 kdp_writeregs_reply_t writeregs_reply;
613 kdp_load_req_t load_req;
614 kdp_load_reply_t load_reply;
615 kdp_imagepath_req_t imagepath_req;
616 kdp_imagepath_reply_t imagepath_reply;
617 kdp_suspend_req_t suspend_req;
618 kdp_suspend_reply_t suspend_reply;
619 kdp_resumecpus_req_t resumecpus_req;
620 kdp_resumecpus_reply_t resumecpus_reply;
621 kdp_exception_t exception;
622 kdp_exception_ack_t exception_ack;
623 kdp_termination_t termination;
624 kdp_termination_ack_t termination_ack;
625 kdp_breakpoint_req_t breakpoint_req;
626 kdp_breakpoint_reply_t breakpoint_reply;
627 kdp_breakpoint64_req_t breakpoint64_req;
628 kdp_breakpoint64_reply_t breakpoint64_reply;
629 kdp_reattach_req_t reattach_req;
630 kdp_regions_req_t regions_req;
631 kdp_regions_reply_t regions_reply;
632 kdp_kernelversion_req_t kernelversion_req;
633 kdp_kernelversion_reply_t kernelversion_reply;
634 kdp_readioport_req_t readioport_req;
635 kdp_readioport_reply_t readioport_reply;
636 kdp_writeioport_req_t writeioport_req;
637 kdp_writeioport_reply_t writeioport_reply;
638 kdp_readmsr64_req_t readmsr64_req;
639 kdp_readmsr64_reply_t readmsr64_reply;
640 kdp_writemsr64_req_t writemsr64_req;
641 kdp_writemsr64_reply_t writemsr64_reply;
642 } kdp_pkt_t;
643
644 #define MAX_KDP_PKT_SIZE 1200 /* max packet size */
645 #define MAX_KDP_DATA_SIZE 1024 /* max r/w data per packet */
646
647 #endif // _KDP_PROTOCOL_H_