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