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