SourceLevelDebugPkg/Library/DebugAgent/DebugAgentCommon/DebugAgent.h

   1 /** @file
   2   Command header of for Debug Agent library instance.
   3
   4   Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _DEBUG_AGENT_H_
  10 #define _DEBUG_AGENT_H_
  11
  12 #include <Register/LocalApic.h>
  13 #include <Guid/DebugAgentGuid.h>
  14 #include <Guid/VectorHandoffTable.h>
  15 #include <Ppi/VectorHandoffInfo.h>
  16 #include <Library/BaseLib.h>
  17 #include <Library/BaseMemoryLib.h>
  18 #include <Library/ResetSystemLib.h>
  19 #include <Library/IoLib.h>
  20 #include <Library/HobLib.h>
  21 #include <Library/DebugCommunicationLib.h>
  22 #include <Library/DebugAgentLib.h>
  23 #include <Library/PcdLib.h>
  24 #include <Library/SynchronizationLib.h>
  25 #include <Library/LocalApicLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/TimerLib.h>
  28 #include <Library/PrintLib.h>
  29 #include <Library/PeCoffGetEntryPointLib.h>
  30 #include <Library/PeCoffExtraActionLib.h>
  31 #include <Register/ArchitecturalMsr.h>
  32
  33 #include <TransferProtocol.h>
  34 #include <ImageDebugSupport.h>
  35
  36 #include "DebugMp.h"
  37 #include "DebugTimer.h"
  38 #include "ArchDebugSupport.h"
  39 #include "DebugException.h"
  40
  41 //
  42 // These macros may be already defined in DebugAgentLib.h
  43 //
  44 #define DEBUG_AGENT_INIT_PEI                  9
  45 #define DEBUG_AGENT_INIT_DXE_LOAD             10
  46 #define DEBUG_AGENT_INIT_DXE_UNLOAD           11
  47 #define DEBUG_AGENT_INIT_THUNK_PEI_IA32TOX64  12
  48
  49 #define DEBUG_INT1_VECTOR     DEBUG_EXCEPT_DEBUG
  50 #define DEBUG_INT3_VECTOR     DEBUG_EXCEPT_BREAKPOINT
  51 #define DEBUG_TIMER_VECTOR    32
  52 #define DEBUG_MAILBOX_VECTOR  33
  53
  54 //
  55 //  Timeout value for reading packet (unit is microsecond)
  56 //
  57 #define READ_PACKET_TIMEOUT   (500 * 1000)
  58 #define DEBUG_TIMER_INTERVAL  (100 * 1000)
  59
  60 #define SOFT_INTERRUPT_SIGNATURE  SIGNATURE_32('S','O','F','T')
  61 #define SYSTEM_RESET_SIGNATURE    SIGNATURE_32('S','Y','S','R')
  62 #define MEMORY_READY_SIGNATURE    SIGNATURE_32('M','E','M','R')
  63
  64 extern UINTN                    Exception0Handle;
  65 extern UINTN                    TimerInterruptHandle;
  66 extern UINT32                   ExceptionStubHeaderSize;
  67 extern BOOLEAN                  mSkipBreakpoint;
  68 extern EFI_VECTOR_HANDOFF_INFO  mVectorHandoffInfoDebugAgent[];
  69 extern UINTN                    mVectorHandoffInfoCount;
  70
  71 //
  72 // CPU exception information issued by debug agent
  73 //
  74 typedef struct {
  75   //
  76   // This field is used to save CPU content before executing HOST command
  77   //
  78   BASE_LIBRARY_JUMP_BUFFER             JumpBuffer;
  79   //
  80   // This field returns the exception information issued by the HOST command
  81   //
  82   DEBUG_DATA_RESPONSE_GET_EXCEPTION    ExceptionContent;
  83 } DEBUG_AGENT_EXCEPTION_BUFFER;
  84
  85 #define DEBUG_AGENT_FLAG_HOST_ATTACHED         BIT0
  86 #define DEBUG_AGENT_FLAG_AGENT_IN_PROGRESS     BIT1
  87 #define DEBUG_AGENT_FLAG_MEMORY_READY          BIT2
  88 #define DEBUG_AGENT_FLAG_STEPPING              BIT3
  89 #define DEBUG_AGENT_FLAG_CHECK_MAILBOX_IN_HOB  BIT4
  90 #define DEBUG_AGENT_FLAG_INIT_ARCH             BIT5|BIT6
  91 #define DEBUG_AGENT_FLAG_INTERRUPT_FLAG        BIT7
  92 #define DEBUG_AGENT_FLAG_BREAK_ON_NEXT_SMI     BIT32
  93 #define DEBUG_AGENT_FLAG_PRINT_ERROR_LEVEL     (BIT33|BIT34|BIT35|BIT36)
  94 #define DEBUG_AGENT_FLAG_BREAK_BOOT_SCRIPT     BIT37
  95
  96 #define DEBUG_MAILBOX_DEBUG_FLAG_INDEX                1
  97 #define DEBUG_MAILBOX_DEBUG_PORT_HANDLE_INDEX         2
  98 #define DEBUG_MAILBOX_EXCEPTION_BUFFER_POINTER_INDEX  3
  99 #define DEBUG_MAILBOX_LAST_ACK                        4
 100 #define DEBUG_MAILBOX_SEQUENCE_NO_INDEX               5
 101 #define DEBUG_MAILBOX_HOST_SEQUENCE_NO_INDEX          6
 102 #define DEBUG_MAILBOX_DEBUG_TIMER_FREQUENCY           7
 103
 104 #pragma pack(1)
 105 typedef union {
 106   struct {
 107     //
 108     // Lower 32 bits to store the status of DebugAgent
 109     //
 110     UINT32    HostAttached      : 1; // 1: HOST is attached
 111     UINT32    AgentInProgress   : 1; // 1: Debug Agent is communicating with HOST
 112     UINT32    MemoryReady       : 1; // 1: Memory is ready
 113     UINT32    SteppingFlag      : 1; // 1: Agent is running stepping command
 114     UINT32    CheckMailboxInHob : 1; // 1: Need to check mailbox saved in HOB
 115     UINT32    InitArch          : 2; // value of DEBUG_DATA_RESPONSE_ARCH_MODE
 116     UINT32    InterruptFlag     : 1; // 1: EFLAGS.IF is set
 117     UINT32    Reserved1         : 24;
 118     //
 119     // Higher 32bits to control the behavior of DebugAgent
 120     //
 121     UINT32    BreakOnNextSmi    : 1; // 1: Break on next SMI
 122     UINT32    PrintErrorLevel   : 4; // Bitmask of print error level for debug message
 123     UINT32    BreakOnBootScript : 1; // 1: Break before executing boot script
 124     UINT32    Reserved2         : 26;
 125   } Bits;
 126   UINT64    Uint64;
 127 } DEBUG_AGENT_FLAG;
 128
 129 typedef struct {
 130   DEBUG_AGENT_FLAG    DebugFlag;
 131   UINT64              DebugPortHandle;
 132   //
 133   // Pointer to DEBUG_AGENT_EXCEPTION_BUFFER
 134   //
 135   UINT64              ExceptionBufferPointer;
 136   UINT8               LastAck;             // The last ack packet type
 137   UINT8               SequenceNo;
 138   UINT8               HostSequenceNo;
 139   UINT32              DebugTimerFrequency;
 140   UINT8               CheckSum;            // Mailbox checksum
 141   UINT8               ToBeCheckSum;        // To be Mailbox checksum at the next
 142 } DEBUG_AGENT_MAILBOX;
 143 #pragma pack()
 144
 145 ///
 146 /// Byte packed structure for an IA-32 Interrupt Gate Descriptor.
 147 ///
 148 typedef union {
 149   struct {
 150     UINT32    OffsetLow  : 16; ///< Offset bits 15..0.
 151     UINT32    Selector   : 16; ///< Selector.
 152     UINT32    Reserved_0 : 8;  ///< Reserved.
 153     UINT32    GateType   : 8;  ///< Gate Type.  See #defines above.
 154     UINT32    OffsetHigh : 16; ///< Offset bits 31..16.
 155   } Bits;
 156   UINT64    Uint64;
 157 } IA32_IDT_ENTRY;
 158
 159 typedef union {
 160   struct {
 161     UINT32    LimitLow    : 16;
 162     UINT32    BaseLow     : 16;
 163     UINT32    BaseMid     : 8;
 164     UINT32    Type        : 4;
 165     UINT32    System      : 1;
 166     UINT32    Dpl         : 2;
 167     UINT32    Present     : 1;
 168     UINT32    LimitHigh   : 4;
 169     UINT32    Software    : 1;
 170     UINT32    Reserved    : 1;
 171     UINT32    DefaultSize : 1;
 172     UINT32    Granularity : 1;
 173     UINT32    BaseHigh    : 8;
 174   } Bits;
 175   UINT64    Uint64;
 176 } IA32_GDT;
 177
 178 /**
 179   Initialize IDT entries to support source level debug.
 180
 181 **/
 182 VOID
 183 InitializeDebugIdt (
 184   VOID
 185   );
 186
 187 /**
 188   Read register value from saved CPU context.
 189
 190   @param[in] CpuContext         Pointer to saved CPU context.
 191   @param[in] Index              Register index value.
 192   @param[in] Width              Data width to read.
 193
 194   @return The address of register value.
 195
 196 **/
 197 UINT8 *
 198 ArchReadRegisterBuffer (
 199   IN DEBUG_CPU_CONTEXT  *CpuContext,
 200   IN UINT8              Index,
 201   IN UINT8              *Width
 202   );
 203
 204 /**
 205   Send packet with response data to HOST.
 206
 207   @param[in]      Data        Pointer to response data buffer.
 208   @param[in]      DataSize    Size of response data in byte.
 209   @param[in, out] DebugHeader Pointer to a buffer for creating response packet and receiving ACK packet,
 210                               to minimize the stack usage.
 211
 212   @retval RETURN_SUCCESS      Response data was sent successfully.
 213   @retval RETURN_DEVICE_ERROR Cannot receive DEBUG_COMMAND_OK from HOST.
 214
 215 **/
 216 RETURN_STATUS
 217 SendDataResponsePacket (
 218   IN UINT8                    *Data,
 219   IN UINT16                   DataSize,
 220   IN OUT DEBUG_PACKET_HEADER  *DebugHeader
 221   );
 222
 223 /**
 224   Check if HOST is attached based on Mailbox.
 225
 226   @retval TRUE        HOST is attached.
 227   @retval FALSE       HOST is not attached.
 228
 229 **/
 230 BOOLEAN
 231 IsHostAttached (
 232   VOID
 233   );
 234
 235 /**
 236   Get Debug Agent Mailbox pointer.
 237
 238   @return Mailbox pointer.
 239
 240 **/
 241 DEBUG_AGENT_MAILBOX *
 242 GetMailboxPointer (
 243   VOID
 244   );
 245
 246 /**
 247   Get debug port handle.
 248
 249   @return Debug port handle.
 250
 251 **/
 252 DEBUG_PORT_HANDLE
 253 GetDebugPortHandle (
 254   VOID
 255   );
 256
 257 /**
 258   Read the Attach/Break-in symbols from the debug port.
 259
 260   @param[in]  Handle         Pointer to Debug Port handle.
 261   @param[out] BreakSymbol    Returned break symbol.
 262
 263   @retval EFI_SUCCESS        Read the symbol in BreakSymbol.
 264   @retval EFI_NOT_FOUND      No read the break symbol.
 265
 266 **/
 267 EFI_STATUS
 268 DebugReadBreakSymbol (
 269   IN  DEBUG_PORT_HANDLE  Handle,
 270   OUT UINT8              *BreakSymbol
 271   );
 272
 273 /**
 274   Prints a debug message to the debug port if the specified error level is enabled.
 275
 276   If any bit in ErrorLevel is also set in Mainbox, then print the message specified
 277   by Format and the associated variable argument list to the debug port.
 278
 279   @param[in] ErrorLevel  The error level of the debug message.
 280   @param[in] Format      Format string for the debug message to print.
 281   @param[in] ...         Variable argument list whose contents are accessed
 282                          based on the format string specified by Format.
 283
 284 **/
 285 VOID
 286 EFIAPI
 287 DebugAgentMsgPrint (
 288   IN UINT8  ErrorLevel,
 289   IN CHAR8  *Format,
 290   ...
 291   );
 292
 293 /**
 294   Trigger one software interrupt to debug agent to handle it.
 295
 296   @param[in] Signature       Software interrupt signature.
 297
 298 **/
 299 VOID
 300 TriggerSoftInterrupt (
 301   IN UINT32  Signature
 302   );
 303
 304 /**
 305   Check if debug agent support multi-processor.
 306
 307   @retval TRUE    Multi-processor is supported.
 308   @retval FALSE   Multi-processor is not supported.
 309
 310 **/
 311 BOOLEAN
 312 MultiProcessorDebugSupport (
 313   VOID
 314   );
 315
 316 /**
 317   Find and report module image info to HOST.
 318
 319   @param[in] AlignSize      Image aligned size.
 320
 321 **/
 322 VOID
 323 FindAndReportModuleImageInfo (
 324   IN UINTN  AlignSize
 325   );
 326
 327 /**
 328   Read IDT entry to check if IDT entries are setup by Debug Agent.
 329
 330   @retval  TRUE     IDT entries were setup by Debug Agent.
 331   @retval  FALSE    IDT entries were not setup by Debug Agent.
 332
 333 **/
 334 BOOLEAN
 335 IsDebugAgentInitialzed (
 336   VOID
 337   );
 338
 339 /**
 340   Calculate Mailbox checksum and update the checksum field.
 341
 342   @param[in]  Mailbox  Debug Agent Mailbox pointer.
 343
 344 **/
 345 VOID
 346 UpdateMailboxChecksum (
 347   IN DEBUG_AGENT_MAILBOX  *Mailbox
 348   );
 349
 350 /**
 351   Verify Mailbox checksum.
 352
 353   If checksum error, print debug message and run init dead loop.
 354
 355   @param[in]  Mailbox  Debug Agent Mailbox pointer.
 356
 357 **/
 358 VOID
 359 VerifyMailboxChecksum (
 360   IN DEBUG_AGENT_MAILBOX  *Mailbox
 361   );
 362
 363 /**
 364   Set debug flag in mailbox.
 365
 366   @param[in]  FlagMask      Debug flag mask value.
 367   @param[in]  FlagValue     Debug flag value.
 368
 369 **/
 370 VOID
 371 SetDebugFlag (
 372   IN UINT64  FlagMask,
 373   IN UINT32  FlagValue
 374   );
 375
 376 /**
 377   Get debug flag in mailbox.
 378
 379   @param[in]  FlagMask      Debug flag mask value.
 380
 381   @return Debug flag value.
 382
 383 **/
 384 UINT32
 385 GetDebugFlag (
 386   IN UINT64  FlagMask
 387   );
 388
 389 /**
 390   Update Mailbox content by index.
 391
 392   @param[in]  Mailbox  Debug Agent Mailbox pointer.
 393   @param[in]  Index    Mailbox content index.
 394   @param[in]  Value    Value to be set into mail box.
 395
 396 **/
 397 VOID
 398 UpdateMailboxContent (
 399   IN DEBUG_AGENT_MAILBOX  *Mailbox,
 400   IN UINTN                Index,
 401   IN UINT64               Value
 402   );
 403
 404 /**
 405   Retrieve exception handler from IDT table by ExceptionNum.
 406
 407   @param[in]  ExceptionNum    Exception number
 408
 409   @return Exception handler
 410
 411 **/
 412 VOID *
 413 GetExceptionHandlerInIdtEntry (
 414   IN UINTN  ExceptionNum
 415   );
 416
 417 /**
 418   Set exception handler in IDT table by ExceptionNum.
 419
 420   @param[in]  ExceptionNum      Exception number
 421   @param[in]  ExceptionHandler  Exception Handler to be set
 422
 423 **/
 424 VOID
 425 SetExceptionHandlerInIdtEntry (
 426   IN UINTN  ExceptionNum,
 427   IN VOID   *ExceptionHandler
 428   );
 429
 430 /**
 431   Prints a debug message to the debug output device if the specified error level is enabled.
 432
 433   If any bit in ErrorLevel is also set in DebugPrintErrorLevelLib function
 434   GetDebugPrintErrorLevel (), then print the message specified by Format and the
 435   associated variable argument list to the debug output device.
 436
 437   If Format is NULL, then ASSERT().
 438
 439   @param[in] ErrorLevel  The error level of the debug message.
 440   @param[in] IsSend      Flag of debug message to declare that the data is being sent or being received.
 441   @param[in] Data        Variable argument list whose contents are accessed
 442   @param[in] Length      based on the format string specified by Format.
 443
 444 **/
 445 VOID
 446 EFIAPI
 447 DebugAgentDataMsgPrint (
 448   IN UINT8    ErrorLevel,
 449   IN BOOLEAN  IsSend,
 450   IN UINT8    *Data,
 451   IN UINT8    Length
 452   );
 453
 454 /**
 455   Read remaing debug packet except for the start symbol
 456
 457   @param[in]      Handle        Pointer to Debug Port handle.
 458   @param[in, out] DebugHeader   Debug header buffer including start symbol.
 459
 460   @retval EFI_SUCCESS        Read the symbol in BreakSymbol.
 461   @retval EFI_CRC_ERROR      CRC check fail.
 462   @retval EFI_TIMEOUT        Timeout occurs when reading debug packet.
 463
 464 **/
 465 EFI_STATUS
 466 ReadRemainingBreakPacket (
 467   IN     DEBUG_PORT_HANDLE    Handle,
 468   IN OUT DEBUG_PACKET_HEADER  *DebugHeader
 469   );
 470
 471 /**
 472   Read data from debug channel and save the data in buffer.
 473
 474   Reads NumberOfBytes data bytes from a debug device into the buffer
 475   specified by Buffer. The number of bytes actually read is returned.
 476   If the return value is less than NumberOfBytes, then the rest operation failed.
 477   If NumberOfBytes is zero, then return 0.
 478
 479   @param  Handle           Debug port handle.
 480   @param  Buffer           Pointer to the data buffer to store the data read from the debug device.
 481   @param  NumberOfBytes    Number of bytes which will be read.
 482   @param  Timeout          Timeout value for reading from debug device. It unit is Microsecond.
 483
 484   @retval 0                Read data failed, no data is to be read.
 485   @retval >0               Actual number of bytes read from debug device.
 486
 487 **/
 488 UINTN
 489 DebugAgentReadBuffer (
 490   IN     DEBUG_PORT_HANDLE  Handle,
 491   IN OUT UINT8              *Buffer,
 492   IN     UINTN              NumberOfBytes,
 493   IN     UINTN              Timeout
 494   );
 495
 496 #endif