SourceLevelDebugPkg/Library/DebugAgent/DebugAgentCommon/DebugAgent.h

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