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.
37 #ifdef MACH_KERNEL_PRIVATE
38 #include <mach/vm_prot.h>
42 #ifdef KDP_PROXY_PACK_SUPPORT
46 #define KDP_PACKED __attribute__((packed))
50 * Retransmit parameters
52 #if DDEBUG_DEBUG || DEBUG_DEBUG
53 #define KDP_REXMIT_SECS 20 /* rexmit if no ack in 3 secs */
54 #else /* DDEBUG_DEBUG || DEBUG_DEBUG */
55 #define KDP_REXMIT_SECS 3 /* rexmit if no ack in 3 secs */
56 #endif /* DDEBUG_DEBUG || DEBUG_DEBUG */
57 #define KDP_REXMIT_TRIES 8 /* xmit 8 times, then give up */
61 * (NMI) Attention Max Wait Time
62 * Remote will resume unless KDP requests is received within this
63 * many seconds after an attention (nmi) packet is sent.
65 #define KDP_MAX_ATTN_WAIT 30 /* wait max of 30 seconds */
68 * Well-known UDP port, debugger side.
69 * FIXME: This is what the 68K guys use, but beats me how they chose it...
71 #define KDP_REMOTE_PORT 41139 /* pick one and register it */
74 * UDP ports, KDB side. 5 port numbers are reserved for each port (request
75 * and exception). This allows multiple KDBs to run on one host.
77 #define UDP_HOST_COMM_BASE 41140
78 #define UDP_HOST_EXCEP_BASE 41145
79 #define NUM_UDP_HOST_PORTS 5
85 /* connection oriented requests */
86 KDP_CONNECT
, KDP_DISCONNECT
,
88 /* obtaining client info */
89 KDP_HOSTINFO
, KDP_VERSION
, KDP_MAXBYTES
,
92 KDP_READMEM
, KDP_WRITEMEM
,
95 KDP_READREGS
, KDP_WRITEREGS
,
97 /* executable image info */
98 KDP_LOAD
, KDP_IMAGEPATH
,
100 /* execution control */
101 KDP_SUSPEND
, KDP_RESUMECPUS
,
103 /* exception and termination notification, NOT true requests */
104 KDP_EXCEPTION
, KDP_TERMINATION
,
106 /* breakpoint control */
107 KDP_BREAKPOINT_SET
, KDP_BREAKPOINT_REMOVE
,
112 /* reattach to a connected host */
115 /* remote reboot request */
118 /* memory access (64-bit wide addresses). Version 11 protocol */
119 KDP_READMEM64
, KDP_WRITEMEM64
,
121 /* breakpoint control (64-bit wide addresses). Version 11 protocol */
122 KDP_BREAKPOINT64_SET
, KDP_BREAKPOINT64_REMOVE
,
124 /* kernel version string, like "xnu-1234.5~6". Version 11 protocol */
127 /* physical memory access (64-bit wide addresses). Version 12 protocol */
128 KDP_READPHYSMEM64
, KDP_WRITEPHYSMEM64
,
130 /* ioport access (8-, 16-, and 32-bit) */
131 KDP_READIOPORT
, KDP_WRITEIOPORT
,
133 /* msr access (64-bit) */
134 KDP_READMSR64
, KDP_WRITEMSR64
,
136 /* get/dump panic/corefile info */
144 KDP_DUMPINFO_GETINFO
= 0x00000000,
145 KDP_DUMPINFO_SETINFO
= 0x00000001,
146 KDP_DUMPINFO_CORE
= 0x00000102,
147 KDP_DUMPINFO_PANICLOG
= 0x00000103,
148 KDP_DUMPINFO_SYSTEMLOG
= 0x00000104,
149 KDP_DUMPINFO_DISABLE
= 0x00000105,
150 KDP_DUMPINFO_MASK
= 0x00000FFF,
151 KDP_DUMPINFO_DUMP
= 0x00000100,
153 KDP_DUMPINFO_REBOOT
= 0x10000000,
154 KDP_DUMPINFO_NORESUME
= 0x20000000,
155 KDP_DUMPINFO_RESUME
= 0x00000000, /* default behaviour */
156 KDP_DUMPINFO_NOINTR
= 0x40000000, /* don't interrupt */
157 KDP_DUMPINFO_INTR
= 0x00000000, /* default behaviour */
161 * Common KDP packet header
162 * NOTE: kgmacros has a non-symboled version of kdp_hdr_t so that some basic information.
163 * can be gathered from a kernel without any symbols. changes to this structure
164 * need to be reflected in kgmacros as well.
167 kdp_req_t request
:7; /* kdp_req_t, request type */
168 unsigned is_reply
:1; /* 0 => request, 1 => reply */
169 unsigned seq
:8; /* sequence number within session */
170 unsigned len
:16; /* length of entire pkt including hdr */
171 unsigned key
; /* session key */
172 } KDP_PACKED kdp_hdr_t
;
179 KDPERR_ALREADY_CONNECTED
,
181 KDPERR_BADFLAVOR
, /* bad flavor in w/r regs */
183 KDPERR_MAX_BREAKPOINTS
= 100,
184 KDPERR_BREAKPOINT_NOT_FOUND
= 101,
185 KDPERR_BREAKPOINT_ALREADY_SET
= 102
189 * KDP requests and reply packet formats
195 typedef struct { /* KDP_CONNECT request */
197 uint16_t req_reply_port
; /* udp port which to send replies */
198 uint16_t exc_note_port
; /* udp port which to send exc notes */
199 char greeting
[0]; /* "greetings", nul-terminated */
200 } KDP_PACKED kdp_connect_req_t
;
202 typedef struct { /* KDP_CONNECT reply */
205 } KDP_PACKED kdp_connect_reply_t
;
210 typedef struct { /* KDP_DISCONNECT request */
212 } KDP_PACKED kdp_disconnect_req_t
;
214 typedef struct { /* KDP_DISCONNECT reply */
216 } KDP_PACKED kdp_disconnect_reply_t
;
223 uint16_t req_reply_port
; /* udp port which to send replies */
224 } KDP_PACKED kdp_reattach_req_t
;
229 typedef struct { /* KDP_HOSTINFO request */
231 } KDP_PACKED kdp_hostinfo_req_t
;
234 uint32_t cpus_mask
; /* bit is 1 if cpu present */
236 uint32_t cpu_subtype
;
237 } KDP_PACKED kdp_hostinfo_t
;
239 typedef struct { /* KDP_HOSTINFO reply */
241 kdp_hostinfo_t hostinfo
;
242 } KDP_PACKED kdp_hostinfo_reply_t
;
247 typedef struct { /* KDP_VERSION request */
249 } KDP_PACKED kdp_version_req_t
;
251 #define KDP_FEATURE_BP 0x1 /* local breakpoint support */
253 typedef struct { /* KDP_VERSION reply */
259 } KDP_PACKED kdp_version_reply_t
;
261 #define VM_PROT_VOLATILE ((vm_prot_t) 0x08) /* not cacheable */
262 #define VM_PROT_SPARSE ((vm_prot_t) 0x10) /* sparse addr space */
267 typedef struct { /* KDP_REGIONS request */
269 } KDP_PACKED kdp_regions_req_t
;
274 uint32_t protection
; /* vm_prot_t */
275 } KDP_PACKED kdp_region_t
;
277 typedef struct { /* KDP_REGIONS reply */
280 kdp_region_t regions
[0];
281 } KDP_PACKED kdp_regions_reply_t
;
286 typedef struct { /* KDP_MAXBYTES request */
288 } KDP_PACKED kdp_maxbytes_req_t
;
290 typedef struct { /* KDP_MAXBYTES reply */
293 } KDP_PACKED kdp_maxbytes_reply_t
;
298 typedef struct { /* KDP_READMEM request */
302 } KDP_PACKED kdp_readmem_req_t
;
304 typedef struct { /* KDP_READMEM reply */
308 } KDP_PACKED kdp_readmem_reply_t
;
313 typedef struct { /* KDP_READMEM64 request */
317 } KDP_PACKED kdp_readmem64_req_t
;
319 typedef struct { /* KDP_READMEM64 reply */
323 } KDP_PACKED kdp_readmem64_reply_t
;
328 typedef struct { /* KDP_READPHYSMEM64 request */
333 } KDP_PACKED kdp_readphysmem64_req_t
;
335 typedef struct { /* KDP_READPHYSMEM64 reply */
339 } KDP_PACKED kdp_readphysmem64_reply_t
;
344 typedef struct { /* KDP_WRITEMEM request */
349 } KDP_PACKED kdp_writemem_req_t
;
351 typedef struct { /* KDP_WRITEMEM reply */
354 } KDP_PACKED kdp_writemem_reply_t
;
359 typedef struct { /* KDP_WRITEMEM64 request */
364 } KDP_PACKED kdp_writemem64_req_t
;
366 typedef struct { /* KDP_WRITEMEM64 reply */
369 } KDP_PACKED kdp_writemem64_reply_t
;
374 typedef struct { /* KDP_WRITEPHYSMEM64 request */
380 } KDP_PACKED kdp_writephysmem64_req_t
;
382 typedef struct { /* KDP_WRITEPHYSMEM64 reply */
385 } KDP_PACKED kdp_writephysmem64_reply_t
;
390 typedef struct { /* KDP_WRITEIOPORT request */
396 } KDP_PACKED kdp_writeioport_req_t
;
398 typedef struct { /* KDP_WRITEIOPORT reply */
401 } KDP_PACKED kdp_writeioport_reply_t
;
406 typedef struct { /* KDP_READIOPORT request */
411 } KDP_PACKED kdp_readioport_req_t
;
413 typedef struct { /* KDP_READIOPORT reply */
417 } KDP_PACKED kdp_readioport_reply_t
;
423 typedef struct { /* KDP_WRITEMSR64 request */
428 } KDP_PACKED kdp_writemsr64_req_t
;
430 typedef struct { /* KDP_WRITEMSR64 reply */
433 } KDP_PACKED kdp_writemsr64_reply_t
;
438 typedef struct { /* KDP_READMSR64 request */
442 } KDP_PACKED kdp_readmsr64_req_t
;
444 typedef struct { /* KDP_READMSR64 reply */
448 } KDP_PACKED kdp_readmsr64_reply_t
;
454 typedef struct { /* KDP_READREGS request */
458 } KDP_PACKED kdp_readregs_req_t
;
460 typedef struct { /* KDP_READREGS reply */
462 kdp_error_t error
; /* could be KDPERR_BADFLAVOR */
464 } KDP_PACKED kdp_readregs_reply_t
;
469 typedef struct { /* KDP_WRITEREGS request */
474 } KDP_PACKED kdp_writeregs_req_t
;
476 typedef struct { /* KDP_WRITEREGS reply */
479 } KDP_PACKED kdp_writeregs_reply_t
;
484 typedef struct { /* KDP_LOAD request */
487 } KDP_PACKED kdp_load_req_t
;
489 typedef struct { /* KDP_LOAD reply */
492 } KDP_PACKED kdp_load_reply_t
;
497 typedef struct { /* KDP_IMAGEPATH request */
499 } KDP_PACKED kdp_imagepath_req_t
;
501 typedef struct { /* KDP_IMAGEPATH reply */
504 } KDP_PACKED kdp_imagepath_reply_t
;
509 typedef struct { /* KDP_SUSPEND request */
511 } KDP_PACKED kdp_suspend_req_t
;
513 typedef struct { /* KDP_SUSPEND reply */
515 } KDP_PACKED kdp_suspend_reply_t
;
520 typedef struct { /* KDP_RESUMECPUS request */
523 } KDP_PACKED kdp_resumecpus_req_t
;
525 typedef struct { /* KDP_RESUMECPUS reply */
527 } KDP_PACKED kdp_resumecpus_reply_t
;
530 * KDP_BREAKPOINT_SET and KDP_BREAKPOINT_REMOVE
536 } KDP_PACKED kdp_breakpoint_req_t
;
541 } KDP_PACKED kdp_breakpoint_reply_t
;
544 * KDP_BREAKPOINT64_SET and KDP_BREAKPOINT64_REMOVE
550 } KDP_PACKED kdp_breakpoint64_req_t
;
555 } KDP_PACKED kdp_breakpoint64_reply_t
;
558 * Exception notifications
559 * (Exception notifications are not requests, and in fact travel from
560 * the remote debugger to the gdb agent KDB.)
562 typedef struct { /* exc. info for one cpu */
565 * Following info is defined as
566 * per <mach/exception.h>
571 } KDP_PACKED kdp_exc_info_t
;
573 typedef struct { /* KDP_EXCEPTION notification */
576 kdp_exc_info_t exc_info
[0];
577 } KDP_PACKED kdp_exception_t
;
579 typedef struct { /* KDP_EXCEPTION acknowledgement */
581 } KDP_PACKED kdp_exception_ack_t
;
586 typedef struct { /* KDP_KERNELVERSION request */
588 } KDP_PACKED kdp_kernelversion_req_t
;
590 typedef struct { /* KDP_KERNELVERSION reply */
593 } KDP_PACKED kdp_kernelversion_reply_t
;
597 * Child termination messages
600 KDP_FAULT
= 0, /* child took fault (internal use) */
601 KDP_EXIT
, /* child exited */
602 KDP_POWEROFF
, /* child power-off */
603 KDP_REBOOT
, /* child reboot */
604 KDP_COMMAND_MODE
/* child exit to mon command_mode */
605 } kdp_termination_code_t
;
607 typedef struct { /* KDP_TERMINATION notification */
609 uint32_t term_code
; /* kdp_termination_code_t */
611 } KDP_PACKED kdp_termination_t
;
615 } KDP_PACKED kdp_termination_ack_t
;
620 typedef struct { /* KDP_DUMPINFO request */
627 } KDP_PACKED kdp_dumpinfo_req_t
;
629 typedef struct { /* KDP_DUMPINFO reply */
636 } KDP_PACKED kdp_dumpinfo_reply_t
;
641 kdp_connect_req_t connect_req
;
642 kdp_connect_reply_t connect_reply
;
643 kdp_disconnect_req_t disconnect_req
;
644 kdp_disconnect_reply_t disconnect_reply
;
645 kdp_hostinfo_req_t hostinfo_req
;
646 kdp_hostinfo_reply_t hostinfo_reply
;
647 kdp_version_req_t version_req
;
648 kdp_version_reply_t version_reply
;
649 kdp_maxbytes_req_t maxbytes_req
;
650 kdp_maxbytes_reply_t maxbytes_reply
;
651 kdp_readmem_req_t readmem_req
;
652 kdp_readmem_reply_t readmem_reply
;
653 kdp_readmem64_req_t readmem64_req
;
654 kdp_readmem64_reply_t readmem64_reply
;
655 kdp_readphysmem64_req_t readphysmem64_req
;
656 kdp_readphysmem64_reply_t readphysmem64_reply
;
657 kdp_writemem_req_t writemem_req
;
658 kdp_writemem_reply_t writemem_reply
;
659 kdp_writemem64_req_t writemem64_req
;
660 kdp_writemem64_reply_t writemem64_reply
;
661 kdp_writephysmem64_req_t writephysmem64_req
;
662 kdp_writephysmem64_reply_t writephysmem64_reply
;
663 kdp_readregs_req_t readregs_req
;
664 kdp_readregs_reply_t readregs_reply
;
665 kdp_writeregs_req_t writeregs_req
;
666 kdp_writeregs_reply_t writeregs_reply
;
667 kdp_load_req_t load_req
;
668 kdp_load_reply_t load_reply
;
669 kdp_imagepath_req_t imagepath_req
;
670 kdp_imagepath_reply_t imagepath_reply
;
671 kdp_suspend_req_t suspend_req
;
672 kdp_suspend_reply_t suspend_reply
;
673 kdp_resumecpus_req_t resumecpus_req
;
674 kdp_resumecpus_reply_t resumecpus_reply
;
675 kdp_exception_t exception
;
676 kdp_exception_ack_t exception_ack
;
677 kdp_termination_t termination
;
678 kdp_termination_ack_t termination_ack
;
679 kdp_breakpoint_req_t breakpoint_req
;
680 kdp_breakpoint_reply_t breakpoint_reply
;
681 kdp_breakpoint64_req_t breakpoint64_req
;
682 kdp_breakpoint64_reply_t breakpoint64_reply
;
683 kdp_reattach_req_t reattach_req
;
684 kdp_regions_req_t regions_req
;
685 kdp_regions_reply_t regions_reply
;
686 kdp_kernelversion_req_t kernelversion_req
;
687 kdp_kernelversion_reply_t kernelversion_reply
;
688 kdp_readioport_req_t readioport_req
;
689 kdp_readioport_reply_t readioport_reply
;
690 kdp_writeioport_req_t writeioport_req
;
691 kdp_writeioport_reply_t writeioport_reply
;
692 kdp_readmsr64_req_t readmsr64_req
;
693 kdp_readmsr64_reply_t readmsr64_reply
;
694 kdp_writemsr64_req_t writemsr64_req
;
695 kdp_writemsr64_reply_t writemsr64_reply
;
696 kdp_dumpinfo_req_t dumpinfo_req
;
697 kdp_dumpinfo_reply_t dumpinfo_reply
;
700 #define MAX_KDP_PKT_SIZE 1200 /* max packet size */
701 #define MAX_KDP_DATA_SIZE 1024 /* max r/w data per packet */
704 * Support relatively small request/responses here.
705 * If kgmacros needs to make a larger request, increase
708 #define KDP_MANUAL_PACKET_SIZE 128
709 struct kdp_manual_pkt
{
710 unsigned char data
[KDP_MANUAL_PACKET_SIZE
];
715 #ifdef KDP_PROXY_PACK_SUPPORT
719 #endif // _KDP_PROTOCOL_H_