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