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 */