osfmk/kdp/kdp_protocol.h

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