MdePkg/Include/Protocol/DebugSupport.h

   1 /** @file
   2   DebugSupport protocol and supporting definitions as defined in the UEFI2.4
   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 - 2010, Intel Corporation. All rights reserved.<BR>
   9 Portions copyright (c) 2011 - 2013, ARM Ltd. All rights reserved.<BR>
  10
  11 This program and the accompanying materials are licensed and made available under
  12 the terms and conditions of the BSD License that accompanies this distribution.
  13 The full text of the license may be found at
  14 http://opensource.org/licenses/bsd-license.php.
  15
  16 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  17 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  18
  19 **/
  20
  21 #ifndef __DEBUG_SUPPORT_H__
  22 #define __DEBUG_SUPPORT_H__
  23
  24 #include <IndustryStandard/PeImage.h>
  25
  26 typedef struct _EFI_DEBUG_SUPPORT_PROTOCOL EFI_DEBUG_SUPPORT_PROTOCOL;
  27
  28 ///
  29 /// Debug Support protocol {2755590C-6F3C-42FA-9EA4-A3BA543CDA25}.
  30 ///
  31 #define EFI_DEBUG_SUPPORT_PROTOCOL_GUID \
  32   { \
  33     0x2755590C, 0x6F3C, 0x42FA, {0x9E, 0xA4, 0xA3, 0xBA, 0x54, 0x3C, 0xDA, 0x25 } \
  34   }
  35
  36 ///
  37 /// Processor exception to be hooked.
  38 /// All exception types for IA32, X64, Itanium and EBC processors are defined.
  39 ///
  40 typedef INTN  EFI_EXCEPTION_TYPE;
  41
  42 ///
  43 ///  IA-32 processor exception types.
  44 ///
  45 #define EXCEPT_IA32_DIVIDE_ERROR    0
  46 #define EXCEPT_IA32_DEBUG           1
  47 #define EXCEPT_IA32_NMI             2
  48 #define EXCEPT_IA32_BREAKPOINT      3
  49 #define EXCEPT_IA32_OVERFLOW        4
  50 #define EXCEPT_IA32_BOUND           5
  51 #define EXCEPT_IA32_INVALID_OPCODE  6
  52 #define EXCEPT_IA32_DOUBLE_FAULT    8
  53 #define EXCEPT_IA32_INVALID_TSS     10
  54 #define EXCEPT_IA32_SEG_NOT_PRESENT 11
  55 #define EXCEPT_IA32_STACK_FAULT     12
  56 #define EXCEPT_IA32_GP_FAULT        13
  57 #define EXCEPT_IA32_PAGE_FAULT      14
  58 #define EXCEPT_IA32_FP_ERROR        16
  59 #define EXCEPT_IA32_ALIGNMENT_CHECK 17
  60 #define EXCEPT_IA32_MACHINE_CHECK   18
  61 #define EXCEPT_IA32_SIMD            19
  62
  63 ///
  64 /// FXSAVE_STATE.
  65 /// FP / MMX / XMM registers (see fxrstor instruction definition).
  66 ///
  67 typedef struct {
  68   UINT16  Fcw;
  69   UINT16  Fsw;
  70   UINT16  Ftw;
  71   UINT16  Opcode;
  72   UINT32  Eip;
  73   UINT16  Cs;
  74   UINT16  Reserved1;
  75   UINT32  DataOffset;
  76   UINT16  Ds;
  77   UINT8   Reserved2[10];
  78   UINT8   St0Mm0[10], Reserved3[6];
  79   UINT8   St1Mm1[10], Reserved4[6];
  80   UINT8   St2Mm2[10], Reserved5[6];
  81   UINT8   St3Mm3[10], Reserved6[6];
  82   UINT8   St4Mm4[10], Reserved7[6];
  83   UINT8   St5Mm5[10], Reserved8[6];
  84   UINT8   St6Mm6[10], Reserved9[6];
  85   UINT8   St7Mm7[10], Reserved10[6];
  86   UINT8   Xmm0[16];
  87   UINT8   Xmm1[16];
  88   UINT8   Xmm2[16];
  89   UINT8   Xmm3[16];
  90   UINT8   Xmm4[16];
  91   UINT8   Xmm5[16];
  92   UINT8   Xmm6[16];
  93   UINT8   Xmm7[16];
  94   UINT8   Reserved11[14 * 16];
  95 } EFI_FX_SAVE_STATE_IA32;
  96
  97 ///
  98 ///  IA-32 processor context definition.
  99 ///
 100 typedef struct {
 101   UINT32                 ExceptionData;
 102   EFI_FX_SAVE_STATE_IA32 FxSaveState;
 103   UINT32                 Dr0;
 104   UINT32                 Dr1;
 105   UINT32                 Dr2;
 106   UINT32                 Dr3;
 107   UINT32                 Dr6;
 108   UINT32                 Dr7;
 109   UINT32                 Cr0;
 110   UINT32                 Cr1;  /* Reserved */
 111   UINT32                 Cr2;
 112   UINT32                 Cr3;
 113   UINT32                 Cr4;
 114   UINT32                 Eflags;
 115   UINT32                 Ldtr;
 116   UINT32                 Tr;
 117   UINT32                 Gdtr[2];
 118   UINT32                 Idtr[2];
 119   UINT32                 Eip;
 120   UINT32                 Gs;
 121   UINT32                 Fs;
 122   UINT32                 Es;
 123   UINT32                 Ds;
 124   UINT32                 Cs;
 125   UINT32                 Ss;
 126   UINT32                 Edi;
 127   UINT32                 Esi;
 128   UINT32                 Ebp;
 129   UINT32                 Esp;
 130   UINT32                 Ebx;
 131   UINT32                 Edx;
 132   UINT32                 Ecx;
 133   UINT32                 Eax;
 134 } EFI_SYSTEM_CONTEXT_IA32;
 135
 136 ///
 137 ///  x64 processor exception types.
 138 ///
 139 #define EXCEPT_X64_DIVIDE_ERROR    0
 140 #define EXCEPT_X64_DEBUG           1
 141 #define EXCEPT_X64_NMI             2
 142 #define EXCEPT_X64_BREAKPOINT      3
 143 #define EXCEPT_X64_OVERFLOW        4
 144 #define EXCEPT_X64_BOUND           5
 145 #define EXCEPT_X64_INVALID_OPCODE  6
 146 #define EXCEPT_X64_DOUBLE_FAULT    8
 147 #define EXCEPT_X64_INVALID_TSS     10
 148 #define EXCEPT_X64_SEG_NOT_PRESENT 11
 149 #define EXCEPT_X64_STACK_FAULT     12
 150 #define EXCEPT_X64_GP_FAULT        13
 151 #define EXCEPT_X64_PAGE_FAULT      14
 152 #define EXCEPT_X64_FP_ERROR        16
 153 #define EXCEPT_X64_ALIGNMENT_CHECK 17
 154 #define EXCEPT_X64_MACHINE_CHECK   18
 155 #define EXCEPT_X64_SIMD            19
 156
 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 ///
 192 ///  x64 processor context definition.
 193 ///
 194 typedef struct {
 195   UINT64                ExceptionData;
 196   EFI_FX_SAVE_STATE_X64 FxSaveState;
 197   UINT64                Dr0;
 198   UINT64                Dr1;
 199   UINT64                Dr2;
 200   UINT64                Dr3;
 201   UINT64                Dr6;
 202   UINT64                Dr7;
 203   UINT64                Cr0;
 204   UINT64                Cr1;  /* Reserved */
 205   UINT64                Cr2;
 206   UINT64                Cr3;
 207   UINT64                Cr4;
 208   UINT64                Cr8;
 209   UINT64                Rflags;
 210   UINT64                Ldtr;
 211   UINT64                Tr;
 212   UINT64                Gdtr[2];
 213   UINT64                Idtr[2];
 214   UINT64                Rip;
 215   UINT64                Gs;
 216   UINT64                Fs;
 217   UINT64                Es;
 218   UINT64                Ds;
 219   UINT64                Cs;
 220   UINT64                Ss;
 221   UINT64                Rdi;
 222   UINT64                Rsi;
 223   UINT64                Rbp;
 224   UINT64                Rsp;
 225   UINT64                Rbx;
 226   UINT64                Rdx;
 227   UINT64                Rcx;
 228   UINT64                Rax;
 229   UINT64                R8;
 230   UINT64                R9;
 231   UINT64                R10;
 232   UINT64                R11;
 233   UINT64                R12;
 234   UINT64                R13;
 235   UINT64                R14;
 236   UINT64                R15;
 237 } EFI_SYSTEM_CONTEXT_X64;
 238
 239 ///
 240 ///  Itanium Processor Family Exception types.
 241 ///
 242 #define EXCEPT_IPF_VHTP_TRANSLATION       0
 243 #define EXCEPT_IPF_INSTRUCTION_TLB        1
 244 #define EXCEPT_IPF_DATA_TLB               2
 245 #define EXCEPT_IPF_ALT_INSTRUCTION_TLB    3
 246 #define EXCEPT_IPF_ALT_DATA_TLB           4
 247 #define EXCEPT_IPF_DATA_NESTED_TLB        5
 248 #define EXCEPT_IPF_INSTRUCTION_KEY_MISSED 6
 249 #define EXCEPT_IPF_DATA_KEY_MISSED        7
 250 #define EXCEPT_IPF_DIRTY_BIT              8
 251 #define EXCEPT_IPF_INSTRUCTION_ACCESS_BIT 9
 252 #define EXCEPT_IPF_DATA_ACCESS_BIT        10
 253 #define EXCEPT_IPF_BREAKPOINT             11
 254 #define EXCEPT_IPF_EXTERNAL_INTERRUPT     12
 255 //
 256 // 13 - 19 reserved
 257 //
 258 #define EXCEPT_IPF_PAGE_NOT_PRESENT           20
 259 #define EXCEPT_IPF_KEY_PERMISSION             21
 260 #define EXCEPT_IPF_INSTRUCTION_ACCESS_RIGHTS  22
 261 #define EXCEPT_IPF_DATA_ACCESS_RIGHTS         23
 262 #define EXCEPT_IPF_GENERAL_EXCEPTION          24
 263 #define EXCEPT_IPF_DISABLED_FP_REGISTER       25
 264 #define EXCEPT_IPF_NAT_CONSUMPTION            26
 265 #define EXCEPT_IPF_SPECULATION                27
 266 //
 267 // 28 reserved
 268 //
 269 #define EXCEPT_IPF_DEBUG                          29
 270 #define EXCEPT_IPF_UNALIGNED_REFERENCE            30
 271 #define EXCEPT_IPF_UNSUPPORTED_DATA_REFERENCE     31
 272 #define EXCEPT_IPF_FP_FAULT                       32
 273 #define EXCEPT_IPF_FP_TRAP                        33
 274 #define EXCEPT_IPF_LOWER_PRIVILEGE_TRANSFER_TRAP  34
 275 #define EXCEPT_IPF_TAKEN_BRANCH                   35
 276 #define EXCEPT_IPF_SINGLE_STEP                    36
 277 //
 278 // 37 - 44 reserved
 279 //
 280 #define EXCEPT_IPF_IA32_EXCEPTION 45
 281 #define EXCEPT_IPF_IA32_INTERCEPT 46
 282 #define EXCEPT_IPF_IA32_INTERRUPT 47
 283
 284 ///
 285 ///  IPF processor context definition.
 286 ///
 287 typedef struct {
 288   //
 289   // The first reserved field is necessary to preserve alignment for the correct
 290   // bits in UNAT and to insure F2 is 16 byte aligned.
 291   //
 292   UINT64  Reserved;
 293   UINT64  R1;
 294   UINT64  R2;
 295   UINT64  R3;
 296   UINT64  R4;
 297   UINT64  R5;
 298   UINT64  R6;
 299   UINT64  R7;
 300   UINT64  R8;
 301   UINT64  R9;
 302   UINT64  R10;
 303   UINT64  R11;
 304   UINT64  R12;
 305   UINT64  R13;
 306   UINT64  R14;
 307   UINT64  R15;
 308   UINT64  R16;
 309   UINT64  R17;
 310   UINT64  R18;
 311   UINT64  R19;
 312   UINT64  R20;
 313   UINT64  R21;
 314   UINT64  R22;
 315   UINT64  R23;
 316   UINT64  R24;
 317   UINT64  R25;
 318   UINT64  R26;
 319   UINT64  R27;
 320   UINT64  R28;
 321   UINT64  R29;
 322   UINT64  R30;
 323   UINT64  R31;
 324
 325   UINT64  F2[2];
 326   UINT64  F3[2];
 327   UINT64  F4[2];
 328   UINT64  F5[2];
 329   UINT64  F6[2];
 330   UINT64  F7[2];
 331   UINT64  F8[2];
 332   UINT64  F9[2];
 333   UINT64  F10[2];
 334   UINT64  F11[2];
 335   UINT64  F12[2];
 336   UINT64  F13[2];
 337   UINT64  F14[2];
 338   UINT64  F15[2];
 339   UINT64  F16[2];
 340   UINT64  F17[2];
 341   UINT64  F18[2];
 342   UINT64  F19[2];
 343   UINT64  F20[2];
 344   UINT64  F21[2];
 345   UINT64  F22[2];
 346   UINT64  F23[2];
 347   UINT64  F24[2];
 348   UINT64  F25[2];
 349   UINT64  F26[2];
 350   UINT64  F27[2];
 351   UINT64  F28[2];
 352   UINT64  F29[2];
 353   UINT64  F30[2];
 354   UINT64  F31[2];
 355
 356   UINT64  Pr;
 357
 358   UINT64  B0;
 359   UINT64  B1;
 360   UINT64  B2;
 361   UINT64  B3;
 362   UINT64  B4;
 363   UINT64  B5;
 364   UINT64  B6;
 365   UINT64  B7;
 366
 367   //
 368   // application registers
 369   //
 370   UINT64  ArRsc;
 371   UINT64  ArBsp;
 372   UINT64  ArBspstore;
 373   UINT64  ArRnat;
 374
 375   UINT64  ArFcr;
 376
 377   UINT64  ArEflag;
 378   UINT64  ArCsd;
 379   UINT64  ArSsd;
 380   UINT64  ArCflg;
 381   UINT64  ArFsr;
 382   UINT64  ArFir;
 383   UINT64  ArFdr;
 384
 385   UINT64  ArCcv;
 386
 387   UINT64  ArUnat;
 388
 389   UINT64  ArFpsr;
 390
 391   UINT64  ArPfs;
 392   UINT64  ArLc;
 393   UINT64  ArEc;
 394
 395   //
 396   // control registers
 397   //
 398   UINT64  CrDcr;
 399   UINT64  CrItm;
 400   UINT64  CrIva;
 401   UINT64  CrPta;
 402   UINT64  CrIpsr;
 403   UINT64  CrIsr;
 404   UINT64  CrIip;
 405   UINT64  CrIfa;
 406   UINT64  CrItir;
 407   UINT64  CrIipa;
 408   UINT64  CrIfs;
 409   UINT64  CrIim;
 410   UINT64  CrIha;
 411
 412   //
 413   // debug registers
 414   //
 415   UINT64  Dbr0;
 416   UINT64  Dbr1;
 417   UINT64  Dbr2;
 418   UINT64  Dbr3;
 419   UINT64  Dbr4;
 420   UINT64  Dbr5;
 421   UINT64  Dbr6;
 422   UINT64  Dbr7;
 423
 424   UINT64  Ibr0;
 425   UINT64  Ibr1;
 426   UINT64  Ibr2;
 427   UINT64  Ibr3;
 428   UINT64  Ibr4;
 429   UINT64  Ibr5;
 430   UINT64  Ibr6;
 431   UINT64  Ibr7;
 432
 433   //
 434   // virtual registers - nat bits for R1-R31
 435   //
 436   UINT64  IntNat;
 437
 438 } EFI_SYSTEM_CONTEXT_IPF;
 439
 440 ///
 441 ///  EBC processor exception types.
 442 ///
 443 #define EXCEPT_EBC_UNDEFINED            0
 444 #define EXCEPT_EBC_DIVIDE_ERROR         1
 445 #define EXCEPT_EBC_DEBUG                2
 446 #define EXCEPT_EBC_BREAKPOINT           3
 447 #define EXCEPT_EBC_OVERFLOW             4
 448 #define EXCEPT_EBC_INVALID_OPCODE       5   ///< Opcode out of range.
 449 #define EXCEPT_EBC_STACK_FAULT          6
 450 #define EXCEPT_EBC_ALIGNMENT_CHECK      7
 451 #define EXCEPT_EBC_INSTRUCTION_ENCODING 8   ///< Malformed instruction.
 452 #define EXCEPT_EBC_BAD_BREAK            9   ///< BREAK 0 or undefined BREAK.
 453 #define EXCEPT_EBC_STEP                 10  ///< To support debug stepping.
 454 ///
 455 /// For coding convenience, define the maximum valid EBC exception.
 456 ///
 457 #define MAX_EBC_EXCEPTION EXCEPT_EBC_STEP
 458
 459 ///
 460 ///  EBC processor context definition.
 461 ///
 462 typedef struct {
 463   UINT64  R0;
 464   UINT64  R1;
 465   UINT64  R2;
 466   UINT64  R3;
 467   UINT64  R4;
 468   UINT64  R5;
 469   UINT64  R6;
 470   UINT64  R7;
 471   UINT64  Flags;
 472   UINT64  ControlFlags;
 473   UINT64  Ip;
 474 } EFI_SYSTEM_CONTEXT_EBC;
 475
 476
 477
 478 ///
 479 ///  ARM processor exception types.
 480 ///
 481 #define EXCEPT_ARM_RESET                    0
 482 #define EXCEPT_ARM_UNDEFINED_INSTRUCTION    1
 483 #define EXCEPT_ARM_SOFTWARE_INTERRUPT       2
 484 #define EXCEPT_ARM_PREFETCH_ABORT           3
 485 #define EXCEPT_ARM_DATA_ABORT               4
 486 #define EXCEPT_ARM_RESERVED                 5
 487 #define EXCEPT_ARM_IRQ                      6
 488 #define EXCEPT_ARM_FIQ                      7
 489
 490 ///
 491 /// For coding convenience, define the maximum valid ARM exception.
 492 ///
 493 #define MAX_ARM_EXCEPTION EXCEPT_ARM_FIQ
 494
 495 ///
 496 ///  ARM processor context definition.
 497 ///
 498 typedef struct {
 499   UINT32  R0;
 500   UINT32  R1;
 501   UINT32  R2;
 502   UINT32  R3;
 503   UINT32  R4;
 504   UINT32  R5;
 505   UINT32  R6;
 506   UINT32  R7;
 507   UINT32  R8;
 508   UINT32  R9;
 509   UINT32  R10;
 510   UINT32  R11;
 511   UINT32  R12;
 512   UINT32  SP;
 513   UINT32  LR;
 514   UINT32  PC;
 515   UINT32  CPSR;
 516   UINT32  DFSR;
 517   UINT32  DFAR;
 518   UINT32  IFSR;
 519   UINT32  IFAR;
 520 } EFI_SYSTEM_CONTEXT_ARM;
 521
 522
 523 ///
 524 ///  AARCH64 processor exception types.
 525 ///
 526 #define EXCEPT_AARCH64_SYNCHRONOUS_EXCEPTIONS    0
 527 #define EXCEPT_AARCH64_IRQ                       1
 528 #define EXCEPT_AARCH64_FIQ                       2
 529 #define EXCEPT_AARCH64_SERROR                    3
 530
 531 ///
 532 /// For coding convenience, define the maximum valid ARM exception.
 533 ///
 534 #define MAX_AARCH64_EXCEPTION EXCEPT_AARCH64_SERROR
 535
 536 typedef struct {
 537   // General Purpose Registers
 538   UINT64  X0;
 539   UINT64  X1;
 540   UINT64  X2;
 541   UINT64  X3;
 542   UINT64  X4;
 543   UINT64  X5;
 544   UINT64  X6;
 545   UINT64  X7;
 546   UINT64  X8;
 547   UINT64  X9;
 548   UINT64  X10;
 549   UINT64  X11;
 550   UINT64  X12;
 551   UINT64  X13;
 552   UINT64  X14;
 553   UINT64  X15;
 554   UINT64  X16;
 555   UINT64  X17;
 556   UINT64  X18;
 557   UINT64  X19;
 558   UINT64  X20;
 559   UINT64  X21;
 560   UINT64  X22;
 561   UINT64  X23;
 562   UINT64  X24;
 563   UINT64  X25;
 564   UINT64  X26;
 565   UINT64  X27;
 566   UINT64  X28;
 567   UINT64  FP;   // x29 - Frame pointer
 568   UINT64  LR;   // x30 - Link Register
 569   UINT64  SP;   // x31 - Stack pointer
 570
 571   // FP/SIMD Registers
 572   UINT64  V0[2];
 573   UINT64  V1[2];
 574   UINT64  V2[2];
 575   UINT64  V3[2];
 576   UINT64  V4[2];
 577   UINT64  V5[2];
 578   UINT64  V6[2];
 579   UINT64  V7[2];
 580   UINT64  V8[2];
 581   UINT64  V9[2];
 582   UINT64  V10[2];
 583   UINT64  V11[2];
 584   UINT64  V12[2];
 585   UINT64  V13[2];
 586   UINT64  V14[2];
 587   UINT64  V15[2];
 588   UINT64  V16[2];
 589   UINT64  V17[2];
 590   UINT64  V18[2];
 591   UINT64  V19[2];
 592   UINT64  V20[2];
 593   UINT64  V21[2];
 594   UINT64  V22[2];
 595   UINT64  V23[2];
 596   UINT64  V24[2];
 597   UINT64  V25[2];
 598   UINT64  V26[2];
 599   UINT64  V27[2];
 600   UINT64  V28[2];
 601   UINT64  V29[2];
 602   UINT64  V30[2];
 603   UINT64  V31[2];
 604
 605   UINT64  ELR;  // Exception Link Register
 606   UINT64  SPSR; // Saved Processor Status Register
 607   UINT64  FPSR; // Floating Point Status Register
 608   UINT64  ESR;  // Exception syndrome register
 609   UINT64  FAR;  // Fault Address Register
 610 } EFI_SYSTEM_CONTEXT_AARCH64;
 611
 612
 613 ///
 614 /// Universal EFI_SYSTEM_CONTEXT definition.
 615 ///
 616 typedef union {
 617   EFI_SYSTEM_CONTEXT_EBC  *SystemContextEbc;
 618   EFI_SYSTEM_CONTEXT_IA32 *SystemContextIa32;
 619   EFI_SYSTEM_CONTEXT_X64  *SystemContextX64;
 620   EFI_SYSTEM_CONTEXT_IPF  *SystemContextIpf;
 621   EFI_SYSTEM_CONTEXT_ARM  *SystemContextArm;
 622   EFI_SYSTEM_CONTEXT_AARCH64  *SystemContextAArch64;
 623 } EFI_SYSTEM_CONTEXT;
 624
 625 //
 626 // DebugSupport callback function prototypes
 627 //
 628
 629 /**
 630   Registers and enables an exception callback function for the specified exception.
 631
 632   @param  ExceptionType         Exception types in EBC, IA-32, x64, or IPF.
 633   @param  SystemContext         Exception content.
 634
 635 **/
 636 typedef
 637 VOID
 638 (EFIAPI *EFI_EXCEPTION_CALLBACK)(
 639   IN     EFI_EXCEPTION_TYPE               ExceptionType,
 640   IN OUT EFI_SYSTEM_CONTEXT               SystemContext
 641   );
 642
 643 /**
 644   Registers and enables the on-target debug agent's periodic entry point.
 645
 646   @param  SystemContext         Exception content.
 647
 648 **/
 649 typedef
 650 VOID
 651 (EFIAPI *EFI_PERIODIC_CALLBACK)(
 652   IN OUT EFI_SYSTEM_CONTEXT               SystemContext
 653   );
 654
 655 ///
 656 /// Machine type definition
 657 ///
 658 typedef enum {
 659   IsaIa32 = IMAGE_FILE_MACHINE_I386,           ///< 0x014C
 660   IsaX64  = IMAGE_FILE_MACHINE_X64,            ///< 0x8664
 661   IsaIpf  = IMAGE_FILE_MACHINE_IA64,           ///< 0x0200
 662   IsaEbc  = IMAGE_FILE_MACHINE_EBC,            ///< 0x0EBC
 663   IsaArm  = IMAGE_FILE_MACHINE_ARMTHUMB_MIXED, ///< 0x01c2
 664   IsaAArch64  = IMAGE_FILE_MACHINE_ARM64       ///< 0xAA64
 665 } EFI_INSTRUCTION_SET_ARCHITECTURE;
 666
 667
 668 //
 669 // DebugSupport member function definitions
 670 //
 671
 672 /**
 673   Returns the maximum value that may be used for the ProcessorIndex parameter in
 674   RegisterPeriodicCallback() and RegisterExceptionCallback().
 675
 676   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
 677   @param  MaxProcessorIndex     Pointer to a caller-allocated UINTN in which the maximum supported
 678                                 processor index is returned.
 679
 680   @retval EFI_SUCCESS           The function completed successfully.
 681
 682 **/
 683 typedef
 684 EFI_STATUS
 685 (EFIAPI *EFI_GET_MAXIMUM_PROCESSOR_INDEX)(
 686   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
 687   OUT UINTN                              *MaxProcessorIndex
 688   );
 689
 690 /**
 691   Registers a function to be called back periodically in interrupt context.
 692
 693   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
 694   @param  ProcessorIndex        Specifies which processor the callback function applies to.
 695   @param  PeriodicCallback      A pointer to a function of type PERIODIC_CALLBACK that is the main
 696                                 periodic entry point of the debug agent.
 697
 698   @retval EFI_SUCCESS           The function completed successfully.
 699   @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
 700                                 function was previously registered.
 701   @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
 702                                 function.
 703
 704 **/
 705 typedef
 706 EFI_STATUS
 707 (EFIAPI *EFI_REGISTER_PERIODIC_CALLBACK)(
 708   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
 709   IN UINTN                               ProcessorIndex,
 710   IN EFI_PERIODIC_CALLBACK               PeriodicCallback
 711   );
 712
 713 /**
 714   Registers a function to be called when a given processor exception occurs.
 715
 716   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
 717   @param  ProcessorIndex        Specifies which processor the callback function applies to.
 718   @param  ExceptionCallback     A pointer to a function of type EXCEPTION_CALLBACK that is called
 719                                 when the processor exception specified by ExceptionType occurs.
 720   @param  ExceptionType         Specifies which processor exception to hook.
 721
 722   @retval EFI_SUCCESS           The function completed successfully.
 723   @retval EFI_ALREADY_STARTED   Non-NULL PeriodicCallback parameter when a callback
 724                                 function was previously registered.
 725   @retval EFI_OUT_OF_RESOURCES  System has insufficient memory resources to register new callback
 726                                 function.
 727
 728 **/
 729 typedef
 730 EFI_STATUS
 731 (EFIAPI *EFI_REGISTER_EXCEPTION_CALLBACK)(
 732   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
 733   IN UINTN                               ProcessorIndex,
 734   IN EFI_EXCEPTION_CALLBACK              ExceptionCallback,
 735   IN EFI_EXCEPTION_TYPE                  ExceptionType
 736   );
 737
 738 /**
 739   Invalidates processor instruction cache for a memory range. Subsequent execution in this range
 740   causes a fresh memory fetch to retrieve code to be executed.
 741
 742   @param  This                  A pointer to the EFI_DEBUG_SUPPORT_PROTOCOL instance.
 743   @param  ProcessorIndex        Specifies which processor's instruction cache is to be invalidated.
 744   @param  Start                 Specifies the physical base of the memory range to be invalidated.
 745   @param  Length                Specifies the minimum number of bytes in the processor's instruction
 746                                 cache to invalidate.
 747
 748   @retval EFI_SUCCESS           The function completed successfully.
 749
 750 **/
 751 typedef
 752 EFI_STATUS
 753 (EFIAPI *EFI_INVALIDATE_INSTRUCTION_CACHE)(
 754   IN EFI_DEBUG_SUPPORT_PROTOCOL          *This,
 755   IN UINTN                               ProcessorIndex,
 756   IN VOID                                *Start,
 757   IN UINT64                              Length
 758   );
 759
 760 ///
 761 /// This protocol provides the services to allow the debug agent to register
 762 /// callback functions that are called either periodically or when specific
 763 /// processor exceptions occur.
 764 ///
 765 struct _EFI_DEBUG_SUPPORT_PROTOCOL {
 766   ///
 767   /// Declares the processor architecture for this instance of the EFI Debug Support protocol.
 768   ///
 769   EFI_INSTRUCTION_SET_ARCHITECTURE  Isa;
 770   EFI_GET_MAXIMUM_PROCESSOR_INDEX   GetMaximumProcessorIndex;
 771   EFI_REGISTER_PERIODIC_CALLBACK    RegisterPeriodicCallback;
 772   EFI_REGISTER_EXCEPTION_CALLBACK   RegisterExceptionCallback;
 773   EFI_INVALIDATE_INSTRUCTION_CACHE  InvalidateInstructionCache;
 774 };
 775
 776 extern EFI_GUID gEfiDebugSupportProtocolGuid;
 777
 778 #endif