osfmk/kdp/kdp_protocol.h

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