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