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