osfmk/kdp/kdp_protocol.h

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