1 /* 2 * kdd.h -- Structures, constants and descriptions of the Windows 3 * kd serial debugger protocol, for the kdd debugging stub. 4 * 5 * Tim Deegan <Tim.Deegan@citrix.com> 6 * 7 * Copyright (c) 2007-2010, Citrix Systems Inc. 8 * All rights reserved. 9 * 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions 12 * are met: 13 * 14 * Redistributions of source code must retain the above copyright 15 * notice, this list of conditions and the following disclaimer. 16 * 17 * Redistributions in binary form must reproduce the above copyright 18 * notice, this list of conditions and the following disclaimer in the 19 * documentation and/or other materials provided with the distribution. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 27 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 29 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 31 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32 * POSSIBILITY OF SUCH DAMAGE. 33 */ 34 35 #ifndef _KDD_H_ 36 #define _KDD_H_ 37 38 #include <stdint.h> 39 40 #define PACKED __attribute__((packed)) 41 42 /* We define our page related constants here in order to specifically 43 * avoid using the Xen page macros (this is a restriction for the code 44 * in kdd.c which should not include any Xen headers) and to add 45 * consistency for code in both kdd.c and kdd-xen.c. */ 46 #define KDD_PAGE_SHIFT 12 47 #define KDD_PAGE_SIZE (1U << KDD_PAGE_SHIFT) 48 49 /***************************************************************************** 50 * Serial line protocol: Sender sends a 16-byte header with an optional 51 * payload following it. Receiver responds to each packet with an 52 * acknowledgment (16-byte header only). 53 * 54 * Packet headers start with ASCII "0000" and there is a trailing byte 55 * 0xAA after the (optional) payload. Ack headers start with ASCII 56 * "iiii"; no trailing byte). Each packet and ack has a major type in 57 * the packet header; for packets with payload, a minor type is encoded 58 * in ASCII in the first four bytes of the payload. 59 * 60 * Packet IDs seem to start at 0x80800000 and alternate between that and 61 * 0x80800001; not clear whether the client's ID is always the ID of the 62 * last packet from the kernel or whether they're just oscillating in 63 * phase. Either way there's clearly some state machine in the kernel 64 * that requires this exact behaviour from the client. 65 * 66 * All acks have length 0, id = id of the packet they ack. 67 */ 68 69 #define KDD_DIR_PKT 0x30303030 /* "0000" */ 70 #define KDD_DIR_ACK 0x69696969 /* "iiii" */ 71 72 typedef struct { 73 uint32_t dir; /* KDD_DIR_PKT or KDD_DIR_ACK */ 74 uint16_t type; /* Major type. */ 75 uint16_t len; /* Payload length, excl. header and trailing byte */ 76 uint32_t id; /* Echoed in responses */ 77 uint32_t sum; /* Unsigned sum of all payload bytes */ 78 } PACKED kdd_hdr; 79 80 #define KDD_PKT_CMD 0x0002 /* Debugger commands (and replies to them) */ 81 #define KDD_PKT_MSG 0x0003 /* Kernel messages for the user */ 82 #define KDD_PKT_STC 0x0007 /* State change notification */ 83 #define KDD_PKT_REG 0x000b /* Registry change notification (?) */ 84 #define KDD_PKT_MAX 0x000b 85 86 #define KDD_ACK_OK 0x0004 /* Checksum, ID and type all fine */ 87 #define KDD_ACK_BAD 0x0005 /* Something is bogus */ 88 #define KDD_ACK_RST 0x0006 /* Not really an ack; one each way to resync */ 89 90 91 /***************************************************************************** 92 * Debugger commands, carried over the serial line. In this protocol, 93 * we ignore the serial-level acking; when we talk about a response, 94 * it's another packet, sent after the request was acked, and which will 95 * itself be acked. 96 * 97 * The debugger client sends commands to the kernel, all of which have 98 * major type 2 and are 56 bytes long (not including the serial header). 99 * Not all the 56 bytes are used in every command, but the client 100 * doesn't bother to zero unused fields. Most commands are responded to 101 * by a packet with the same subtype, containing at least a status code 102 * to indicate success or failure. 103 */ 104 105 #define KDD_STATUS_SUCCESS 0x00000000 106 #define KDD_STATUS_FAILURE 0xc0000001 107 #define KDD_STATUS_PENDING 0x00000103 108 109 /* Memory access. Read commands are echoed in the response with the 110 * status and length_rsp fields updated, and the read data appended to the 111 * packet. Writes are the same, but with the data appended to the 112 * write command, not the response. */ 113 114 #define KDD_CMD_READ_VA 0x00003130 /* "01" */ 115 #define KDD_CMD_WRITE_VA 0x00003131 /* "11" */ 116 #define KDD_CMD_READ_CTRL 0x00003137 /* "71" */ 117 #define KDD_CMD_WRITE_CTRL 0x00003138 /* "81" */ 118 #define KDD_CMD_READ_PA 0x0000313D /* "=1" */ 119 #define KDD_CMD_WRITE_PA 0x0000313E /* ">1" */ 120 121 /* Not sure what this is, but it doesn't require a response */ 122 #define KDD_CMD_WRITE_Z 0x0000315A /* "Z1" */ 123 124 typedef struct { 125 uint32_t u1; 126 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 127 uint32_t u2; 128 uint64_t addr; /* IN: address of start of read/write */ 129 uint32_t length_req; /* IN: bytes to read/write */ 130 uint32_t length_rsp; /* OUT: bytes successfully read/written */ 131 } PACKED kdd_cmd_mem; 132 133 /* CPU register access. As for memory accesses, but the data is a 134 * fixed-length block of register info. */ 135 136 #define KDD_CMD_READ_REGS 0x00003132 /* "21" */ 137 #define KDD_CMD_WRITE_REGS 0x00003133 /* "31" */ 138 139 typedef struct { 140 uint16_t u1; 141 uint16_t cpu; /* IN: Zero-based processor ID */ 142 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 143 } PACKED kdd_cmd_regs; 144 145 #define KDD_CMD_READ_MSR 0x00003152 /* "R1" */ 146 #define KDD_CMD_WRITE_MSR 0x00003153 /* "S1" */ 147 148 typedef struct { 149 uint32_t u1; 150 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 151 uint32_t u2; 152 uint32_t msr; /* IN/OUT: MSR number */ 153 uint64_t val; /* IN/OUT: MSR contents */ 154 } PACKED kdd_cmd_msr; 155 156 /* Breakpoint commands. */ 157 158 #define KDD_CMD_SOFT_BP 0x00003135 /* "51" */ 159 160 typedef struct { 161 uint32_t u1; 162 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 163 uint32_t u2; 164 uint32_t bp; /* IN: ID of breakpoint to operate on */ 165 } PACKED kdd_cmd_soft_bp; 166 167 #define KDD_CMD_HARD_BP 0x0000315C /* "\1" */ 168 169 typedef struct { 170 uint32_t u1; 171 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 172 uint32_t u2; 173 uint64_t address; /* IN: Address to trap on */ 174 uint64_t u3; 175 uint64_t u4; 176 uint64_t u5; 177 uint64_t u6; 178 } PACKED kdd_cmd_hard_bp; 179 180 /* Flow control commands. These commands are _not_ responded to. */ 181 182 #define KDD_CMD_CONT1 0x00003136 /* "61" */ 183 #define KDD_CMD_CONT2 0x0000313c /* "<1" */ 184 185 #define KDD_DBG_EXCEPTION_HANDLED 0x00010001 186 #define KDD_DBG_CONTINUE 0x00010002 187 188 typedef struct { 189 uint32_t u1; 190 uint32_t reason1; /* IN: KDD_DBG_* */ 191 uint32_t u2; 192 uint64_t reason2; /* IN: always same as reason1 */ 193 } PACKED kdd_cmd_cont; 194 195 /* Handshake command. */ 196 197 #define KDD_CMD_SHAKE 0x00003146 /* "F1" */ 198 199 #define KDD_MACH_x32 0x014c 200 #define KDD_MACH_x64 0x8664 201 202 #define KDD_FLAGS_MP 0x0001 203 #define KDD_FLAGS_64 0x0008 204 205 typedef struct { 206 uint32_t u1; 207 uint32_t status; /* IN: STATUS_PENDING; OUT: result status. */ 208 uint32_t u2; 209 uint16_t v_major; /* OUT: OS major version (0xf for NT) */ 210 uint16_t v_minor; /* OUT: OS minor version (NT build number) */ 211 uint16_t proto; /* OUT: Protocol version (6) */ 212 uint16_t flags; /* OUT: Some flags (at least 0x3) */ 213 uint16_t machine; /* OUT: Machine type */ 214 uint8_t pkts; /* OUT: Number of packet types understood */ 215 uint8_t states; /* OUT: Number of state-change types used */ 216 uint8_t manips; /* OUT: number of "manipulation" types used */ 217 uint8_t u3[3]; 218 int64_t kern_addr; /* OUT: KernBase */ 219 int64_t mods_addr; /* OUT: PsLoadedModuleList */ 220 int64_t data_addr; /* OUT: DebuggerDataList */ 221 } PACKED kdd_cmd_shake; 222 223 /* Change active CPU. This command is _not_ responded to */ 224 225 #define KDD_CMD_SETCPU 0x00003150 /* "P1" */ 226 227 typedef struct { 228 uint16_t u1; 229 uint16_t cpu; /* IN: Zero-based processor ID */ 230 uint32_t status; /* IN: STATUS_PENDING */ 231 } PACKED kdd_cmd_setcpu; 232 233 typedef struct { 234 uint32_t subtype; /* IN: KDD_CMD_x */ 235 union { 236 kdd_cmd_mem mem; 237 kdd_cmd_regs regs; 238 kdd_cmd_msr msr; 239 kdd_cmd_soft_bp sbp; 240 kdd_cmd_hard_bp hbp; 241 kdd_cmd_cont cont; 242 kdd_cmd_shake shake; 243 kdd_cmd_setcpu setcpu; 244 uint8_t pad[52]; 245 }; 246 uint8_t data[0]; 247 } PACKED kdd_cmd; 248 249 250 /***************************************************************************** 251 * Kernel messages to the debugger. The debugger does not respond to these 252 * beyond ACKing them and printing approprate things on the debugger 253 * console. 254 */ 255 256 /* Messages for the console */ 257 258 #define KDD_MSG_PRINT 0x00003230 /* "02" */ 259 260 typedef struct { 261 uint32_t subtype; /* KDD_MSG_PRINT */ 262 uint32_t u1; 263 uint32_t length; /* Length in bytes of trailing string */ 264 uint32_t u2; 265 uint8_t string[0]; /* Non-terminated character string */ 266 } PACKED kdd_msg; 267 268 /* Registry updates (Hive loads?) */ 269 270 #define KDD_REG_CHANGE 0x00003430 /* "04" */ 271 272 typedef struct { 273 uint32_t subtype; /* KDD_REG_CHANGE */ 274 uint32_t u1[15]; 275 uint16_t string[0]; /* Null-terminated wchar string */ 276 } PACKED kdd_reg; 277 278 /* State changes. After sending a state-change message the kernel halts 279 * until it receives a continue command from the debugger. */ 280 281 #define KDD_STC_STOP 0x00003030 /* "00" : Bug-check */ 282 #define KDD_STC_LOAD 0x00003031 /* "01" : Loaded a module */ 283 284 #define KDD_STC_STATUS_BREAKPOINT 0x80000003 285 286 typedef struct { 287 uint16_t u1; 288 uint16_t cpu; /* Zero-based processor ID */ 289 uint32_t ncpus; /* Number of processors */ 290 uint32_t u2; 291 int64_t kthread; /* Kernel thread structure */ 292 int64_t rip1; /* Instruction pointer, sign-extended */ 293 uint64_t status; /* KDD_STC_STATUS_x */ 294 uint64_t u3; 295 int64_t rip2; /* Same as rip1 */ 296 uint64_t nparams; /* Number of stopcode parameters */ 297 uint64_t params[15]; /* Stopcode parameters */ 298 uint64_t first_chance; /* OS exn handlers not yet been run? */ 299 uint32_t u4[2]; 300 uint32_t ilen; /* Number of bytes of instruction following */ 301 uint8_t inst[36]; /* VA contents from %eip onwards */ 302 } PACKED kdd_stc_stop; 303 304 typedef struct { 305 uint32_t u1[3]; 306 uint64_t u2; 307 uint64_t rip; /* Instruction pointer, sign-extended */ 308 uint64_t u3[26]; 309 uint8_t path[0]; /* Null-terminated ASCII path to loaded mod. */ 310 } PACKED kdd_stc_load; 311 312 typedef struct { 313 uint32_t subtype; /* KDD_STC_x */ 314 union { 315 kdd_stc_stop stop; 316 kdd_stc_load load; 317 }; 318 } PACKED kdd_stc; 319 320 321 /***************************************************************************** 322 * Overall packet type 323 */ 324 325 typedef struct { 326 kdd_hdr h; /* Major type disambiguates union below */ 327 union { 328 kdd_cmd cmd; 329 kdd_msg msg; 330 kdd_reg reg; 331 kdd_stc stc; 332 uint8_t payload[65536]; 333 }; 334 } PACKED kdd_pkt; 335 336 337 /***************************************************************************** 338 * Processor state layouts 339 */ 340 341 /* User-visible register files */ 342 typedef union { 343 uint32_t pad[179]; 344 struct { 345 uint32_t u1[7]; /* Flags, DRx?? */ 346 uint8_t fp[112]; /* FP save state (why 112 not 108?) */ 347 int32_t gs; 348 int32_t fs; 349 int32_t es; 350 int32_t ds; 351 int32_t edi; 352 int32_t esi; 353 int32_t ebx; 354 int32_t edx; 355 int32_t ecx; 356 int32_t eax; 357 int32_t ebp; 358 int32_t eip; 359 int32_t cs; 360 int32_t eflags; 361 int32_t esp; 362 int32_t ss; 363 uint32_t sp2[37]; /* More 0x20202020. fp? */ 364 uint32_t sp3; /* 0x00202020 */ 365 }; 366 } PACKED kdd_regs_x86_32; 367 368 typedef union { 369 uint64_t pad[154]; 370 struct { 371 372 uint64_t u1[7]; 373 374 uint16_t cs; //2*1c 375 uint16_t ds; 376 uint16_t es; 377 uint16_t fs; 378 uint16_t gs; 379 uint16_t ss; 380 uint32_t rflags; 381 uint64_t dr0; 382 uint64_t dr1; 383 uint64_t dr2; 384 uint64_t dr3; 385 uint64_t dr6; 386 uint64_t dr7; 387 int64_t rax; 388 int64_t rcx; 389 int64_t rdx; 390 int64_t rbx; 391 int64_t rsp; 392 int64_t rbp; 393 int64_t rsi; 394 int64_t rdi; 395 int64_t r8; 396 int64_t r9; 397 int64_t r10; 398 int64_t r11; 399 int64_t r12; 400 int64_t r13; 401 int64_t r14; 402 int64_t r15; 403 int64_t rip; //2*7c 404 405 uint64_t u2[32]; 406 407 uint8_t fp[512]; // fp @2*100 .. 150 (+ more??) 408 409 uint64_t u3[26]; 410 }; 411 } PACKED kdd_regs_x86_64; 412 413 typedef union { 414 kdd_regs_x86_32 r32; 415 kdd_regs_x86_64 r64; 416 } PACKED kdd_regs; 417 418 /* System registers */ 419 typedef struct { 420 uint32_t cr0; 421 uint32_t cr2; 422 uint32_t cr3; 423 uint32_t cr4; 424 uint32_t dr0; 425 uint32_t dr1; 426 uint32_t dr2; 427 uint32_t dr3; 428 uint32_t dr6; 429 uint32_t dr7; 430 uint16_t gdt_pad; 431 uint16_t gdt_limit; 432 uint32_t gdt_base; 433 uint16_t idt_pad; 434 uint16_t idt_limit; 435 uint32_t idt_base; 436 uint16_t tss_sel; 437 uint16_t ldt_sel; 438 uint8_t u1[24]; 439 } PACKED kdd_ctrl_x86_32; 440 441 typedef struct { 442 uint64_t cr0; 443 uint64_t cr2; 444 uint64_t cr3; 445 uint64_t cr4; 446 uint64_t dr0; 447 uint64_t dr1; 448 uint64_t dr2; 449 uint64_t dr3; 450 uint64_t dr6; 451 uint64_t dr7; 452 uint8_t gdt_pad[6]; 453 uint16_t gdt_limit; 454 uint64_t gdt_base; 455 uint8_t idt_pad[6]; 456 uint16_t idt_limit; 457 uint64_t idt_base; 458 uint16_t tss_sel; 459 uint16_t ldt_sel; 460 uint8_t u1[44]; 461 uint64_t cr8; 462 uint8_t u2[40]; 463 uint64_t efer; // XXX find out where EFER actually goes 464 } PACKED kdd_ctrl_x86_64; 465 466 typedef union { 467 kdd_ctrl_x86_32 c32; 468 kdd_ctrl_x86_64 c64; 469 } kdd_ctrl; 470 471 /***************************************************************************** 472 * Functions required from the emulator/hypervisor for the stub to work. 473 */ 474 475 typedef struct kdd_guest kdd_guest; 476 477 /* Init and teardown guest-specific state */ 478 extern kdd_guest *kdd_guest_init(char *arg, FILE *log, int verbosity); 479 extern void kdd_guest_teardown(kdd_guest *g); 480 extern char *kdd_guest_identify(kdd_guest *g); 481 482 /* Halt and restart the running guest */ 483 extern void kdd_halt(kdd_guest *g); 484 extern void kdd_run(kdd_guest *g); 485 486 /* How many CPUs are there? */ 487 extern int kdd_count_cpus(kdd_guest *g); 488 489 /* Accessor for guest physical memory, returning bytes read/written */ 490 extern uint32_t kdd_access_physical(kdd_guest *g, uint64_t addr, 491 uint32_t len, uint8_t *buf, int write); 492 493 /* Accessors for guest registers, returning 0 for success */ 494 extern int kdd_get_regs(kdd_guest *g, int cpuid, kdd_regs *r, int w64); 495 extern int kdd_set_regs(kdd_guest *g, int cpuid, kdd_regs *r, int w64); 496 497 /* Accessors for guest control registers, returning 0 for success */ 498 extern int kdd_get_ctrl(kdd_guest *g, int cpuid, kdd_ctrl *ctrl, int w64); 499 extern int kdd_set_ctrl(kdd_guest *g, int cpuid, kdd_ctrl *ctrl, int w64); 500 501 /* Accessors for guest MSRs, returning 0 for success */ 502 extern int kdd_wrmsr(kdd_guest *g, int cpuid, uint32_t msr, uint64_t value); 503 extern int kdd_rdmsr(kdd_guest *g, int cpuid, uint32_t msr, uint64_t *value); 504 505 506 /***************************************************************************** 507 * Logfile usefulness 508 */ 509 510 /* Verbosity: 511 * 0: errors (default) 512 * 1: operations 513 * 2: packets 514 * 3: _everything_ */ 515 516 #define KDD_LOG_IF(_v, _s, _fmt, _a...) do { \ 517 if ((_s)->verbosity >= (_v)) { \ 518 fprintf((_s)->log, (_fmt), ##_a); \ 519 (void) fflush((_s)->log); \ 520 } \ 521 } while (0) 522 523 #define KDD_LOG(_s, _fmt, _a...) KDD_LOG_IF(1, (_s), (_fmt), ##_a) 524 #define KDD_DEBUG(_s, _fmt, _a...) KDD_LOG_IF(3, (_s), (_fmt), ##_a) 525 526 #endif /* _KDD_H_ */ 527