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