2 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
29 #ifndef _KDP_PROTOCOL_H_
30 #define _KDP_PROTOCOL_H_
33 * Definition of remote debugger protocol.
36 #include <mach/vm_prot.h>
40 * Retransmit parameters
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 */
49 #define KDP_PACKED __attribute__((packed))
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.
56 #define KDP_MAX_ATTN_WAIT 30 /* wait max of 30 seconds */
59 * Well-known UDP port, debugger side.
60 * FIXME: This is what the 68K guys use, but beats me how they chose it...
62 #define KDP_REMOTE_PORT 41139 /* pick one and register it */
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.
68 #define UDP_HOST_COMM_BASE 41140
69 #define UDP_HOST_EXCEP_BASE 41145
70 #define NUM_UDP_HOST_PORTS 5
76 /* connection oriented requests */
77 KDP_CONNECT
, KDP_DISCONNECT
,
79 /* obtaining client info */
80 KDP_HOSTINFO
, KDP_VERSION
, KDP_MAXBYTES
,
83 KDP_READMEM
, KDP_WRITEMEM
,
86 KDP_READREGS
, KDP_WRITEREGS
,
88 /* executable image info */
89 KDP_LOAD
, KDP_IMAGEPATH
,
91 /* execution control */
92 KDP_SUSPEND
, KDP_RESUMECPUS
,
94 /* exception and termination notification, NOT true requests */
95 KDP_EXCEPTION
, KDP_TERMINATION
,
97 /* breakpoint control */
98 KDP_BREAKPOINT_SET
, KDP_BREAKPOINT_REMOVE
,
103 /* reattach to a connected host */
106 /* remote reboot request */
109 /* memory access (64-bit wide addresses). Version 11 protocol */
110 KDP_READMEM64
, KDP_WRITEMEM64
,
112 /* breakpoint control (64-bit wide addresses). Version 11 protocol */
113 KDP_BREAKPOINT64_SET
, KDP_BREAKPOINT64_REMOVE
,
115 /* kernel version string, like "xnu-1234.5~6". Version 11 protocol */
118 /* physical memory access (64-bit wide addresses). Version 12 protocol */
119 KDP_READPHYSMEM64
, KDP_WRITEPHYSMEM64
,
121 /* ioport access (8-, 16-, and 32-bit) */
122 KDP_READIOPORT
, KDP_WRITEIOPORT
,
124 /* msr access (64-bit) */
125 KDP_READMSR64
, KDP_WRITEMSR64
,
132 * Common KDP packet header
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
;
147 KDPERR_ALREADY_CONNECTED
,
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
157 * KDP requests and reply packet formats
163 typedef struct { /* KDP_CONNECT request */
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
;
170 typedef struct { /* KDP_CONNECT reply */
173 } KDP_PACKED kdp_connect_reply_t
;
178 typedef struct { /* KDP_DISCONNECT request */
180 } KDP_PACKED kdp_disconnect_req_t
;
182 typedef struct { /* KDP_DISCONNECT reply */
184 } KDP_PACKED kdp_disconnect_reply_t
;
191 uint16_t req_reply_port
; /* udp port which to send replies */
192 } KDP_PACKED kdp_reattach_req_t
;
197 typedef struct { /* KDP_HOSTINFO request */
199 } KDP_PACKED kdp_hostinfo_req_t
;
202 uint32_t cpus_mask
; /* bit is 1 if cpu present */
204 uint32_t cpu_subtype
;
205 } KDP_PACKED kdp_hostinfo_t
;
207 typedef struct { /* KDP_HOSTINFO reply */
209 kdp_hostinfo_t hostinfo
;
210 } KDP_PACKED kdp_hostinfo_reply_t
;
215 typedef struct { /* KDP_VERSION request */
217 } KDP_PACKED kdp_version_req_t
;
219 #define KDP_FEATURE_BP 0x1 /* local breakpoint support */
221 typedef struct { /* KDP_VERSION reply */
227 } KDP_PACKED kdp_version_reply_t
;
229 #define VM_PROT_VOLATILE ((vm_prot_t) 0x08) /* not cacheable */
230 #define VM_PROT_SPARSE ((vm_prot_t) 0x10) /* sparse addr space */
235 typedef struct { /* KDP_REGIONS request */
237 } KDP_PACKED kdp_regions_req_t
;
242 uint32_t protection
; /* vm_prot_t */
243 } KDP_PACKED kdp_region_t
;
245 typedef struct { /* KDP_REGIONS reply */
248 kdp_region_t regions
[0];
249 } KDP_PACKED kdp_regions_reply_t
;
254 typedef struct { /* KDP_MAXBYTES request */
256 } KDP_PACKED kdp_maxbytes_req_t
;
258 typedef struct { /* KDP_MAXBYTES reply */
261 } KDP_PACKED kdp_maxbytes_reply_t
;
266 typedef struct { /* KDP_READMEM request */
270 } KDP_PACKED kdp_readmem_req_t
;
272 typedef struct { /* KDP_READMEM reply */
276 } KDP_PACKED kdp_readmem_reply_t
;
281 typedef struct { /* KDP_READMEM64 request */
285 } KDP_PACKED kdp_readmem64_req_t
;
287 typedef struct { /* KDP_READMEM64 reply */
291 } KDP_PACKED kdp_readmem64_reply_t
;
296 typedef struct { /* KDP_READPHYSMEM64 request */
301 } KDP_PACKED kdp_readphysmem64_req_t
;
303 typedef struct { /* KDP_READPHYSMEM64 reply */
307 } KDP_PACKED kdp_readphysmem64_reply_t
;
312 typedef struct { /* KDP_WRITEMEM request */
317 } KDP_PACKED kdp_writemem_req_t
;
319 typedef struct { /* KDP_WRITEMEM reply */
322 } KDP_PACKED kdp_writemem_reply_t
;
327 typedef struct { /* KDP_WRITEMEM64 request */
332 } KDP_PACKED kdp_writemem64_req_t
;
334 typedef struct { /* KDP_WRITEMEM64 reply */
337 } KDP_PACKED kdp_writemem64_reply_t
;
342 typedef struct { /* KDP_WRITEPHYSMEM64 request */
348 } KDP_PACKED kdp_writephysmem64_req_t
;
350 typedef struct { /* KDP_WRITEPHYSMEM64 reply */
353 } KDP_PACKED kdp_writephysmem64_reply_t
;
358 typedef struct { /* KDP_WRITEIOPORT request */
364 } KDP_PACKED kdp_writeioport_req_t
;
366 typedef struct { /* KDP_WRITEIOPORT reply */
369 } KDP_PACKED kdp_writeioport_reply_t
;
374 typedef struct { /* KDP_READIOPORT request */
379 } KDP_PACKED kdp_readioport_req_t
;
381 typedef struct { /* KDP_READIOPORT reply */
385 } KDP_PACKED kdp_readioport_reply_t
;
391 typedef struct { /* KDP_WRITEMSR64 request */
396 } KDP_PACKED kdp_writemsr64_req_t
;
398 typedef struct { /* KDP_WRITEMSR64 reply */
401 } KDP_PACKED kdp_writemsr64_reply_t
;
406 typedef struct { /* KDP_READMSR64 request */
410 } KDP_PACKED kdp_readmsr64_req_t
;
412 typedef struct { /* KDP_READMSR64 reply */
416 } KDP_PACKED kdp_readmsr64_reply_t
;
422 typedef struct { /* KDP_READREGS request */
426 } KDP_PACKED kdp_readregs_req_t
;
428 typedef struct { /* KDP_READREGS reply */
430 kdp_error_t error
; /* could be KDPERR_BADFLAVOR */
432 } KDP_PACKED kdp_readregs_reply_t
;
437 typedef struct { /* KDP_WRITEREGS request */
442 } KDP_PACKED kdp_writeregs_req_t
;
444 typedef struct { /* KDP_WRITEREGS reply */
447 } KDP_PACKED kdp_writeregs_reply_t
;
452 typedef struct { /* KDP_LOAD request */
455 } KDP_PACKED kdp_load_req_t
;
457 typedef struct { /* KDP_LOAD reply */
460 } KDP_PACKED kdp_load_reply_t
;
465 typedef struct { /* KDP_IMAGEPATH request */
467 } KDP_PACKED kdp_imagepath_req_t
;
469 typedef struct { /* KDP_IMAGEPATH reply */
472 } KDP_PACKED kdp_imagepath_reply_t
;
477 typedef struct { /* KDP_SUSPEND request */
479 } KDP_PACKED kdp_suspend_req_t
;
481 typedef struct { /* KDP_SUSPEND reply */
483 } KDP_PACKED kdp_suspend_reply_t
;
488 typedef struct { /* KDP_RESUMECPUS request */
491 } KDP_PACKED kdp_resumecpus_req_t
;
493 typedef struct { /* KDP_RESUMECPUS reply */
495 } KDP_PACKED kdp_resumecpus_reply_t
;
498 * KDP_BREAKPOINT_SET and KDP_BREAKPOINT_REMOVE
504 } KDP_PACKED kdp_breakpoint_req_t
;
509 } KDP_PACKED kdp_breakpoint_reply_t
;
512 * KDP_BREAKPOINT64_SET and KDP_BREAKPOINT64_REMOVE
518 } KDP_PACKED kdp_breakpoint64_req_t
;
523 } KDP_PACKED kdp_breakpoint64_reply_t
;
526 * Exception notifications
527 * (Exception notifications are not requests, and in fact travel from
528 * the remote debugger to the gdb agent KDB.)
530 typedef struct { /* exc. info for one cpu */
533 * Following info is defined as
534 * per <mach/exception.h>
539 } KDP_PACKED kdp_exc_info_t
;
541 typedef struct { /* KDP_EXCEPTION notification */
544 kdp_exc_info_t exc_info
[0];
545 } KDP_PACKED kdp_exception_t
;
547 typedef struct { /* KDP_EXCEPTION acknowledgement */
549 } KDP_PACKED kdp_exception_ack_t
;
554 typedef struct { /* KDP_KERNELVERSION request */
556 } KDP_PACKED kdp_kernelversion_req_t
;
558 typedef struct { /* KDP_KERNELVERSION reply */
561 } KDP_PACKED kdp_kernelversion_reply_t
;
565 * Child termination messages
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
;
575 typedef struct { /* KDP_TERMINATION notification */
577 uint32_t term_code
; /* kdp_termination_code_t */
579 } KDP_PACKED kdp_termination_t
;
583 } KDP_PACKED kdp_termination_ack_t
;
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
;
644 #define MAX_KDP_PKT_SIZE 1200 /* max packet size */
645 #define MAX_KDP_DATA_SIZE 1024 /* max r/w data per packet */
647 #endif // _KDP_PROTOCOL_H_