SourceLevelDebugPkg/Library/DebugAgent/DebugAgentCommon/DebugAgent.h

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