1 /** @file 2 DebugSupport protocol and supporting definitions as defined in the UEFI2.0 3 specification. 4 5 The DebugSupport protocol is used by source level debuggers to abstract the 6 processor and handle context save and restore operations. 7 8 Copyright (c) 2006 - 2008, Intel Corporation 9 All rights reserved. This program and the accompanying materials 10 are licensed and made available under the terms and conditions of the BSD License 11 which accompanies this distribution. The full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef __DEBUG_SUPPORT_H__ 20 #define __DEBUG_SUPPORT_H__ 21 22 #include <gpxe/efi/ProcessorBind.h> 23 #include <gpxe/efi/IndustryStandard/PeImage.h> 24 25 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL; 26 27 /// 28 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25} 29 /// 30 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \ 31 { \ 32 0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \ 33 } 34 35 /// 36 /// Debug Support definitions 37 /// 38 typedef INTN EFI_EXCEPTION_TYPE; 39 40 // 41 // IA-32 processor exception types 42 // 43 #define EXCEPT_IA32_DIVIDE_ERROR 0 44 #define EXCEPT_IA32_DEBUG 1 45 #define EXCEPT_IA32_NMI 2 46 #define EXCEPT_IA32_BREAKPOINT 3 47 #define EXCEPT_IA32_OVERFLOW 4 48 #define EXCEPT_IA32_BOUND 5 49 #define EXCEPT_IA32_INVALID_OPCODE 6 50 #define EXCEPT_IA32_DOUBLE_FAULT 8 51 #define EXCEPT_IA32_INVALID_TSS 10 52 #define EXCEPT_IA32_SEG_NOT_PRESENT 11 53 #define EXCEPT_IA32_STACK_FAULT 12 54 #define EXCEPT_IA32_GP_FAULT 13 55 #define EXCEPT_IA32_PAGE_FAULT 14 56 #define EXCEPT_IA32_FP_ERROR 16 57 #define EXCEPT_IA32_ALIGNMENT_CHECK 17 58 #define EXCEPT_IA32_MACHINE_CHECK 18 59 #define EXCEPT_IA32_SIMD 19 60 61 /// 62 /// IA-32 processor context definition 63 /// 64 /// 65 /// FXSAVE_STATE 66 /// FP / MMX / XMM registers (see fxrstor instruction definition) 67 /// 68 typedef struct { 69 UINT16 Fcw; 70 UINT16 Fsw; 71 UINT16 Ftw; 72 UINT16 Opcode; 73 UINT32 Eip; 74 UINT16 Cs; 75 UINT16 Reserved1; 76 UINT32 DataOffset; 77 UINT16 Ds; 78 UINT8 Reserved2[10]; 79 UINT8 St0Mm0[10], Reserved3[6]; 80 UINT8 St1Mm1[10], Reserved4[6]; 81 UINT8 St2Mm2[10], Reserved5[6]; 82 UINT8 St3Mm3[10], Reserved6[6]; 83 UINT8 St4Mm4[10], Reserved7[6]; 84 UINT8 St5Mm5[10], Reserved8[6]; 85 UINT8 St6Mm6[10], Reserved9[6]; 86 UINT8 St7Mm7[10], Reserved10[6]; 87 UINT8 Xmm0[16]; 88 UINT8 Xmm1[16]; 89 UINT8 Xmm2[16]; 90 UINT8 Xmm3[16]; 91 UINT8 Xmm4[16]; 92 UINT8 Xmm5[16]; 93 UINT8 Xmm6[16]; 94 UINT8 Xmm7[16]; 95 UINT8 Reserved11[14 * 16]; 96 } EFI_FX_SAVE_STATE_IA32; 97 98 typedef struct { 99 UINT32 ExceptionData; 100 EFI_FX_SAVE_STATE_IA32 FxSaveState; 101 UINT32 Dr0; 102 UINT32 Dr1; 103 UINT32 Dr2; 104 UINT32 Dr3; 105 UINT32 Dr6; 106 UINT32 Dr7; 107 UINT32 Cr0; 108 UINT32 Cr1; /* Reserved */ 109 UINT32 Cr2; 110 UINT32 Cr3; 111 UINT32 Cr4; 112 UINT32 Eflags; 113 UINT32 Ldtr; 114 UINT32 Tr; 115 UINT32 Gdtr[2]; 116 UINT32 Idtr[2]; 117 UINT32 Eip; 118 UINT32 Gs; 119 UINT32 Fs; 120 UINT32 Es; 121 UINT32 Ds; 122 UINT32 Cs; 123 UINT32 Ss; 124 UINT32 Edi; 125 UINT32 Esi; 126 UINT32 Ebp; 127 UINT32 Esp; 128 UINT32 Ebx; 129 UINT32 Edx; 130 UINT32 Ecx; 131 UINT32 Eax; 132 } EFI_SYSTEM_CONTEXT_IA32; 133 134 // 135 // X64 processor exception types 136 // 137 #define EXCEPT_X64_DIVIDE_ERROR 0 138 #define EXCEPT_X64_DEBUG 1 139 #define EXCEPT_X64_NMI 2 140 #define EXCEPT_X64_BREAKPOINT 3 141 #define EXCEPT_X64_OVERFLOW 4 142 #define EXCEPT_X64_BOUND 5 143 #define EXCEPT_X64_INVALID_OPCODE 6 144 #define EXCEPT_X64_DOUBLE_FAULT 8 145 #define EXCEPT_X64_INVALID_TSS 10 146 #define EXCEPT_X64_SEG_NOT_PRESENT 11 147 #define EXCEPT_X64_STACK_FAULT 12 148 #define EXCEPT_X64_GP_FAULT 13 149 #define EXCEPT_X64_PAGE_FAULT 14 150 #define EXCEPT_X64_FP_ERROR 16 151 #define EXCEPT_X64_ALIGNMENT_CHECK 17 152 #define EXCEPT_X64_MACHINE_CHECK 18 153 #define EXCEPT_X64_SIMD 19 154 155 /// 156 /// X64 processor context definition 157 /// 158 /// FXSAVE_STATE 159 /// FP / MMX / XMM registers (see fxrstor instruction definition) 160 /// 161 typedef struct { 162 UINT16 Fcw; 163 UINT16 Fsw; 164 UINT16 Ftw; 165 UINT16 Opcode; 166 UINT64 Rip; 167 UINT64 DataOffset; 168 UINT8 Reserved1[8]; 169 UINT8 St0Mm0[10], Reserved2[6]; 170 UINT8 St1Mm1[10], Reserved3[6]; 171 UINT8 St2Mm2[10], Reserved4[6]; 172 UINT8 St3Mm3[10], Reserved5[6]; 173 UINT8 St4Mm4[10], Reserved6[6]; 174 UINT8 St5Mm5[10], Reserved7[6]; 175 UINT8 St6Mm6[10], Reserved8[6]; 176 UINT8 St7Mm7[10], Reserved9[6]; 177 UINT8 Xmm0[16]; 178 UINT8 Xmm1[16]; 179 UINT8 Xmm2[16]; 180 UINT8 Xmm3[16]; 181 UINT8 Xmm4[16]; 182 UINT8 Xmm5[16]; 183 UINT8 Xmm6[16]; 184 UINT8 Xmm7[16]; 185 // 186 // NOTE: UEFI 2.0 spec definition as follows. 187 // 188 UINT8 Reserved11[14 * 16]; 189 } EFI_FX_SAVE_STATE_X64; 190 191 typedef struct { 192 UINT64 ExceptionData; 193 EFI_FX_SAVE_STATE_X64 FxSaveState; 194 UINT64 Dr0; 195 UINT64 Dr1; 196 UINT64 Dr2; 197 UINT64 Dr3; 198 UINT64 Dr6; 199 UINT64 Dr7; 200 UINT64 Cr0; 201 UINT64 Cr1; /* Reserved */ 202 UINT64 Cr2; 203 UINT64 Cr3; 204 UINT64 Cr4; 205 UINT64 Cr8; 206 UINT64 Rflags; 207 UINT64 Ldtr; 208 UINT64 Tr; 209 UINT64 Gdtr[2]; 210 UINT64 Idtr[2]; 211 UINT64 Rip; 212 UINT64 Gs; 213 UINT64 Fs; 214 UINT64 Es; 215 UINT64 Ds; 216 UINT64 Cs; 217 UINT64 Ss; 218 UINT64 Rdi; 219 UINT64 Rsi; 220 UINT64 Rbp; 221 UINT64 Rsp; 222 UINT64 Rbx; 223 UINT64 Rdx; 224 UINT64 Rcx; 225 UINT64 Rax; 226 UINT64 R8; 227 UINT64 R9; 228 UINT64 R10; 229 UINT64 R11; 230 UINT64 R12; 231 UINT64 R13; 232 UINT64 R14; 233 UINT64 R15; 234 } EFI_SYSTEM_CONTEXT_X64; 235 236 // 237 // IPF processor exception types 238 // 239 #define EXCEPT_IPF_VHTP_TRANSLATION 0 240 #define EXCEPT_IPF_INSTRUCTION_TLB 1 241 #define EXCEPT_IPF_DATA_TLB 2 242 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB 3 243 #define EXCEPT_IPF_ALT_DATA_TLB 4 244 #define EXCEPT_IPF_DATA_NESTED_TLB 5 245 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6 246 #define EXCEPT_IPF_DATA_KEY_MISSED 7 247 #define EXCEPT_IPF_DIRTY_BIT 8 248 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9 249 #define EXCEPT_IPF_DATA_ACCESS_BIT 10 250 #define EXCEPT_IPF_BREAKPOINT 11 251 #define EXCEPT_IPF_EXTERNAL_INTERRUPT 12 252 // 253 // 13 - 19 reserved 254 // 255 #define EXCEPT_IPF_PAGE_NOT_PRESENT 20 256 #define EXCEPT_IPF_KEY_PERMISSION 21 257 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS 22 258 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS 23 259 #define EXCEPT_IPF_GENERAL_EXCEPTION 24 260 #define EXCEPT_IPF_DISABLED_FP_REGISTER 25 261 #define EXCEPT_IPF_NAT_CONSUMPTION 26 262 #define EXCEPT_IPF_SPECULATION 27 263 // 264 // 28 reserved 265 // 266 #define EXCEPT_IPF_DEBUG 29 267 #define EXCEPT_IPF_UNALIGNED_REFERENCE 30 268 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE 31 269 #define EXCEPT_IPF_FP_FAULT 32 270 #define EXCEPT_IPF_FP_TRAP 33 271 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP 34 272 #define EXCEPT_IPF_TAKEN_BRANCH 35 273 #define EXCEPT_IPF_SINGLE_STEP 36 274 // 275 // 37 - 44 reserved 276 // 277 #define EXCEPT_IPF_IA32_EXCEPTION 45 278 #define EXCEPT_IPF_IA32_INTERCEPT 46 279 #define EXCEPT_IPF_IA32_INTERRUPT 47 280 281 /// 282 /// IPF processor context definition 283 /// 284 typedef struct { 285 // 286 // The first reserved field is necessary to preserve alignment for the correct 287 // bits in UNAT and to insure F2 is 16 byte aligned.. 288 // 289 UINT64 Reserved; 290 UINT64 R1; 291 UINT64 R2; 292 UINT64 R3; 293 UINT64 R4; 294 UINT64 R5; 295 UINT64 R6; 296 UINT64 R7; 297 UINT64 R8; 298 UINT64 R9; 299 UINT64 R10; 300 UINT64 R11; 301 UINT64 R12; 302 UINT64 R13; 303 UINT64 R14; 304 UINT64 R15; 305 UINT64 R16; 306 UINT64 R17; 307 UINT64 R18; 308 UINT64 R19; 309 UINT64 R20; 310 UINT64 R21; 311 UINT64 R22; 312 UINT64 R23; 313 UINT64 R24; 314 UINT64 R25; 315 UINT64 R26; 316 UINT64 R27; 317 UINT64 R28; 318 UINT64 R29; 319 UINT64 R30; 320 UINT64 R31; 321 322 UINT64 F2[2]; 323 UINT64 F3[2]; 324 UINT64 F4[2]; 325 UINT64 F5[2]; 326 UINT64 F6[2]; 327 UINT64 F7[2]; 328 UINT64 F8[2]; 329 UINT64 F9[2]; 330 UINT64 F10[2]; 331 UINT64 F11[2]; 332 UINT64 F12[2]; 333 UINT64 F13[2]; 334 UINT64 F14[2]; 335 UINT64 F15[2]; 336 UINT64 F16[2]; 337 UINT64 F17[2]; 338 UINT64 F18[2]; 339 UINT64 F19[2]; 340 UINT64 F20[2]; 341 UINT64 F21[2]; 342 UINT64 F22[2]; 343 UINT64 F23[2]; 344 UINT64 F24[2]; 345 UINT64 F25[2]; 346 UINT64 F26[2]; 347 UINT64 F27[2]; 348 UINT64 F28[2]; 349 UINT64 F29[2]; 350 UINT64 F30[2]; 351 UINT64 F31[2]; 352 353 UINT64 Pr; 354 355 UINT64 B0; 356 UINT64 B1; 357 UINT64 B2; 358 UINT64 B3; 359 UINT64 B4; 360 UINT64 B5; 361 UINT64 B6; 362 UINT64 B7; 363 364 // 365 // application registers 366 // 367 UINT64 ArRsc; 368 UINT64 ArBsp; 369 UINT64 ArBspstore; 370 UINT64 ArRnat; 371 372 UINT64 ArFcr; 373 374 UINT64 ArEflag; 375 UINT64 ArCsd; 376 UINT64 ArSsd; 377 UINT64 ArCflg; 378 UINT64 ArFsr; 379 UINT64 ArFir; 380 UINT64 ArFdr; 381 382 UINT64 ArCcv; 383 384 UINT64 ArUnat; 385 386 UINT64 ArFpsr; 387 388 UINT64 ArPfs; 389 UINT64 ArLc; 390 UINT64 ArEc; 391 392 // 393 // control registers 394 // 395 UINT64 CrDcr; 396 UINT64 CrItm; 397 UINT64 CrIva; 398 UINT64 CrPta; 399 UINT64 CrIpsr; 400 UINT64 CrIsr; 401 UINT64 CrIip; 402 UINT64 CrIfa; 403 UINT64 CrItir; 404 UINT64 CrIipa; 405 UINT64 CrIfs; 406 UINT64 CrIim; 407 UINT64 CrIha; 408 409 // 410 // debug registers 411 // 412 UINT64 Dbr0; 413 UINT64 Dbr1; 414 UINT64 Dbr2; 415 UINT64 Dbr3; 416 UINT64 Dbr4; 417 UINT64 Dbr5; 418 UINT64 Dbr6; 419 UINT64 Dbr7; 420 421 UINT64 Ibr0; 422 UINT64 Ibr1; 423 UINT64 Ibr2; 424 UINT64 Ibr3; 425 UINT64 Ibr4; 426 UINT64 Ibr5; 427 UINT64 Ibr6; 428 UINT64 Ibr7; 429 430 // 431 // virtual registers - nat bits for R1-R31 432 // 433 UINT64 IntNat; 434 435 } EFI_SYSTEM_CONTEXT_IPF; 436 437 // 438 // EBC processor exception types 439 // 440 #define EXCEPT_EBC_UNDEFINED 0 441 #define EXCEPT_EBC_DIVIDE_ERROR 1 442 #define EXCEPT_EBC_DEBUG 2 443 #define EXCEPT_EBC_BREAKPOINT 3 444 #define EXCEPT_EBC_OVERFLOW 4 445 #define EXCEPT_EBC_INVALID_OPCODE 5 // opcode out of range 446 #define EXCEPT_EBC_STACK_FAULT 6 447 #define EXCEPT_EBC_ALIGNMENT_CHECK 7 448 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8 // malformed instruction 449 #define EXCEPT_EBC_BAD_BREAK 9 // BREAK 0 or undefined BREAK 450 #define EXCEPT_EBC_STEP 10 // to support debug stepping 451 /// 452 /// For coding convenience, define the maximum valid EBC exception. 453 /// 454 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP 455 456 /// 457 /// EBC processor context definition 458 /// 459 typedef struct { 460 UINT64 R0; 461 UINT64 R1; 462 UINT64 R2; 463 UINT64 R3; 464 UINT64 R4; 465 UINT64 R5; 466 UINT64 R6; 467 UINT64 R7; 468 UINT64 Flags; 469 UINT64 ControlFlags; 470 UINT64 Ip; 471 } EFI_SYSTEM_CONTEXT_EBC; 472 473 /// 474 /// Universal EFI_SYSTEM_CONTEXT definition 475 /// 476 typedef union { 477 EFI_SYSTEM_CONTEXT_EBC *SystemContextEbc; 478 EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32; 479 EFI_SYSTEM_CONTEXT_X64 *SystemContextX64; 480 EFI_SYSTEM_CONTEXT_IPF *SystemContextIpf; 481 } EFI_SYSTEM_CONTEXT; 482 483 // 484 // DebugSupport callback function prototypes 485 // 486 487 /** 488 Registers and enables an exception callback function for the specified exception. 489 490 @param ExceptionType Exception types in EBC, IA-32, X64, or IPF 491 @param SystemContext Exception content. 492 493 **/ 494 typedef 495 VOID 496 (*EFI_EXCEPTION_CALLBACK)( 497 IN EFI_EXCEPTION_TYPE ExceptionType, 498 IN OUT EFI_SYSTEM_CONTEXT SystemContext 499 ); 500 501 /** 502 Registers and enables the on-target debug agent's periodic entry point. 503 504 @param SystemContext Exception content. 505 506 **/ 507 typedef 508 VOID 509 (*EFI_PERIODIC_CALLBACK)( 510 IN OUT EFI_SYSTEM_CONTEXT SystemContext 511 ); 512 513 /// 514 /// Machine type definition 515 /// 516 typedef enum { 517 IsaIa32 = IMAGE_FILE_MACHINE_I386, ///< 0x014C 518 IsaX64 = IMAGE_FILE_MACHINE_X64, ///< 0x8664 519 IsaIpf = IMAGE_FILE_MACHINE_IA64, ///< 0x0200 520 IsaEbc = IMAGE_FILE_MACHINE_EBC ///< 0x0EBC 521 } EFI_INSTRUCTION_SET_ARCHITECTURE; 522 523 524 // 525 // DebugSupport member function definitions 526 // 527 528 /** 529 Returns the maximum value that may be used for the ProcessorIndex parameter in 530 RegisterPeriodicCallback() and RegisterExceptionCallback(). 531 532 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 533 @param MaxProcessorIndex Pointer to a caller-allocated UINTN in which the maximum supported 534 processor index is returned. 535 536 @retval EFI_SUCCESS The function completed successfully. 537 538 **/ 539 typedef 540 EFI_STATUS 541 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX)( 542 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 543 OUT UINTN *MaxProcessorIndex 544 ); 545 546 /** 547 Registers a function to be called back periodically in interrupt context. 548 549 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 550 @param ProcessorIndex Specifies which processor the callback function applies to. 551 @param PeriodicCallback A pointer to a function of type PERIODIC_CALLBACK that is the main 552 periodic entry point of the debug agent. 553 554 @retval EFI_SUCCESS The function completed successfully. 555 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback 556 function was previously registered. 557 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback 558 function. 559 560 **/ 561 typedef 562 EFI_STATUS 563 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK)( 564 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 565 IN UINTN ProcessorIndex, 566 IN EFI_PERIODIC_CALLBACK PeriodicCallback 567 ); 568 569 /** 570 Registers a function to be called when a given processor exception occurs. 571 572 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 573 @param ProcessorIndex Specifies which processor the callback function applies to. 574 @param PeriodicCallback A pointer to a function of type EXCEPTION_CALLBACK that is called 575 when the processor exception specified by ExceptionType occurs. 576 @param ExceptionType Specifies which processor exception to hook. 577 578 @retval EFI_SUCCESS The function completed successfully. 579 @retval EFI_ALREADY_STARTED Non-NULL PeriodicCallback parameter when a callback 580 function was previously registered. 581 @retval EFI_OUT_OF_RESOURCES System has insufficient memory resources to register new callback 582 function. 583 584 **/ 585 typedef 586 EFI_STATUS 587 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK)( 588 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 589 IN UINTN ProcessorIndex, 590 IN EFI_EXCEPTION_CALLBACK ExceptionCallback, 591 IN EFI_EXCEPTION_TYPE ExceptionType 592 ); 593 594 /** 595 Invalidates processor instruction cache for a memory range. Subsequent execution in this range 596 causes a fresh memory fetch to retrieve code to be executed. 597 598 @param This A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance. 599 @param ProcessorIndex Specifies which processor's instruction cache is to be invalidated. 600 @param Start Specifies the physical base of the memory range to be invalidated. 601 @param Length Specifies the minimum number of bytes in the processor's instruction 602 cache to invalidate. 603 604 @retval EFI_SUCCESS The function completed successfully. 605 606 **/ 607 typedef 608 EFI_STATUS 609 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE)( 610 IN EFI_DEBUG_SUPPORT_PROTOCOL *This, 611 IN UINTN ProcessorIndex, 612 IN VOID *Start, 613 IN UINT64 Length 614 ); 615 616 /// 617 /// This protocol provides the services to allow the debug agent to register 618 /// callback functions that are called either periodically or when specific 619 /// processor exceptions occur. 620 /// 621 struct _EFI_DEBUG_SUPPORT_PROTOCOL { 622 /// 623 /// Declares the processor architecture for this instance of the EFI Debug Support protocol. 624 /// 625 EFI_INSTRUCTION_SET_ARCHITECTURE Isa; 626 EFI_GET_MAXIMUM_PROCESSOR_INDEX GetMaximumProcessorIndex; 627 EFI_REGISTER_PERIODIC_CALLBACK RegisterPeriodicCallback; 628 EFI_REGISTER_EXCEPTION_CALLBACK RegisterExceptionCallback; 629 EFI_INVALIDATE_INSTRUCTION_CACHE InvalidateInstructionCache; 630 }; 631 632 extern EFI_GUID gEfiDebugSupportProtocolGuid; 633 634 #endif 635