]> git.proxmox.com Git - mirror_edk2.git/blob - EmbeddedPkg/GdbStub/GdbStubInternal.h
UefiCpuPkg: Move AsmRelocateApLoopStart from Mpfuncs.nasm to AmdSev.nasm
[mirror_edk2.git] / EmbeddedPkg / GdbStub / GdbStubInternal.h
1 /** @file
2 Private include file for GDB stub
3
4 Copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
5
6 SPDX-License-Identifier: BSD-2-Clause-Patent
7
8 **/
9
10 #ifndef __GDB_STUB_INTERNAL__
11 #define __GDB_STUB_INTERNAL__
12
13 #include <Uefi.h>
14 #include <Library/BaseLib.h>
15 #include <Library/BaseMemoryLib.h>
16 #include <Library/MemoryAllocationLib.h>
17 #include <Library/DebugLib.h>
18 #include <Library/UefiLib.h>
19 #include <Library/UefiBootServicesTableLib.h>
20 #include <Library/PcdLib.h>
21 #include <Library/GdbSerialLib.h>
22 #include <Library/PrintLib.h>
23
24 #include <Protocol/DebugSupport.h>
25 #include <Protocol/SerialIo.h>
26 #include <Protocol/LoadedImage.h>
27 #include <Protocol/LoadedImage.h>
28 #include <Guid/DebugImageInfoTable.h>
29 #include <IndustryStandard/PeImage.h>
30
31 extern CONST CHAR8 mHexToStr[];
32
33 // maximum size of input and output buffers
34 // This value came from the show remote command of the gdb we tested against
35 #define MAX_BUF_SIZE 2000
36
37 // maximum size of address buffer
38 #define MAX_ADDR_SIZE 32
39
40 // maximum size of register number buffer
41 #define MAX_REG_NUM_BUF_SIZE 32
42
43 // maximum size of length buffer
44 #define MAX_LENGTH_SIZE 32
45
46 // maximum size of T signal members
47 #define MAX_T_SIGNAL_SIZE 64
48
49 // the mask used to clear all the cache
50 #define TF_BIT 0x00000100
51
52
53 //
54 // GDB Signal definitions - generic names for interrupts
55 //
56 #define GDB_SIGILL 4 // Illegal instruction
57 #define GDB_SIGTRAP 5 // Trace Trap (Breakpoint and SingleStep)
58 #define GDB_SIGEMT 7 // Emulator Trap
59 #define GDB_SIGFPE 8 // Floating point exception
60 #define GDB_SIGSEGV 11 // Segment violation, page fault
61
62
63 //
64 // GDB File I/O Error values, zero means no error
65 // Includes all general GDB Unix like error values
66 //
67 #define GDB_EBADMEMADDRBUFSIZE 11 // the buffer that stores memory Address to be read from/written to is not the right size
68 #define GDB_EBADMEMLENGBUFSIZE 12 // the buffer that stores Length is not the right size
69 #define GDB_EBADMEMLENGTH 13 // Length, the given number of bytes to read or write, is not the right size
70 #define GDB_EBADMEMDATA 14 // one of the bytes or nibbles of the memory is less than 0
71 #define GDB_EBADMEMDATASIZE 15 // the memory data, 'XX..', is too short or too long
72 #define GDB_EBADBUFSIZE 21 // the buffer created is not the correct size
73 #define GDB_EINVALIDARG 31 // argument is invalid
74 #define GDB_ENOSPACE 41 //
75 #define GDB_EINVALIDBRKPOINTTYPE 51 // the breakpoint type is not recognized
76 #define GDB_EINVALIDREGNUM 61 // given register number is not valid: either <0 or >=Number of Registers
77 #define GDB_EUNKNOWN 255 // unknown
78
79
80 //
81 // These devices are open by GDB so we can just read and write to them
82 //
83 #define GDB_STDIN 0x00
84 #define GDB_STDOUT 0x01
85 #define GDB_STDERR 0x02
86
87 //
88 //Define Register size for different architectures
89 //
90 #if defined (MDE_CPU_IA32)
91 #define REG_SIZE 32
92 #elif defined (MDE_CPU_X64)
93 #define REG_SIZE 64
94 #elif defined (MDE_CPU_ARM)
95 #define REG_SIZE 32
96 #endif
97
98 #define GDB_SERIAL_DEV_SIGNATURE SIGNATURE_32 ('g', 'd', 'b', 's')
99
100 typedef struct {
101 VENDOR_DEVICE_PATH VendorDevice;
102 UINT32 Index; // Support more than one
103 EFI_DEVICE_PATH_PROTOCOL End;
104 } GDB_SERIAL_DEVICE_PATH;
105
106 //
107 // Name: SERIAL_DEV
108 // Purpose: To provide device specific information
109 // Fields:
110 // Signature UINTN: The identity of the serial device
111 // SerialIo SERIAL_IO_PROTOCOL: Serial I/O protocol interface
112 // SerialMode SERIAL_IO_MODE:
113 // DevicePath EFI_DEVICE_PATH_PROTOCOL *: Device path of the serial device
114 //
115 typedef struct {
116 UINTN Signature;
117 EFI_HANDLE Handle;
118 EFI_SERIAL_IO_PROTOCOL SerialIo;
119 EFI_SERIAL_IO_MODE SerialMode;
120 GDB_SERIAL_DEVICE_PATH DevicePath;
121 INTN InFileDescriptor;
122 INTN OutFileDescriptor;
123 } GDB_SERIAL_DEV;
124
125
126 #define GDB_SERIAL_DEV_FROM_THIS(a) CR (a, GDB_SERIAL_DEV, SerialIo, GDB_SERIAL_DEV_SIGNATURE)
127
128
129 typedef struct {
130 EFI_EXCEPTION_TYPE Exception;
131 UINT8 SignalNo;
132 } EFI_EXCEPTION_TYPE_ENTRY;
133
134
135 #if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64)
136
137 //
138 // Byte packed structure for DR6
139 // 32-bits on IA-32
140 // 64-bits on X64. The upper 32-bits on X64 are reserved
141 //
142 typedef union {
143 struct {
144 UINT32 B0:1; // Breakpoint condition detected
145 UINT32 B1:1; // Breakpoint condition detected
146 UINT32 B2:1; // Breakpoint condition detected
147 UINT32 B3:1; // Breakpoint condition detected
148 UINT32 Reserved_1:9; // Reserved
149 UINT32 BD:1; // Debug register access detected
150 UINT32 BS:1; // Single step
151 UINT32 BT:1; // Task switch
152 UINT32 Reserved_2:16; // Reserved
153 } Bits;
154 UINTN UintN;
155 } IA32_DR6;
156
157 //
158 // Byte packed structure for DR7
159 // 32-bits on IA-32
160 // 64-bits on X64. The upper 32-bits on X64 are reserved
161 //
162 typedef union {
163 struct {
164 UINT32 L0:1; // Local breakpoint enable
165 UINT32 G0:1; // Global breakpoint enable
166 UINT32 L1:1; // Local breakpoint enable
167 UINT32 G1:1; // Global breakpoint enable
168 UINT32 L2:1; // Local breakpoint enable
169 UINT32 G2:1; // Global breakpoint enable
170 UINT32 L3:1; // Local breakpoint enable
171 UINT32 G3:1; // Global breakpoint enable
172 UINT32 LE:1; // Local exact breakpoint enable
173 UINT32 GE:1; // Global exact breakpoint enable
174 UINT32 Reserved_1:3; // Reserved
175 UINT32 GD:1; // Global detect enable
176 UINT32 Reserved_2:2; // Reserved
177 UINT32 RW0:2; // Read/Write field
178 UINT32 LEN0:2; // Length field
179 UINT32 RW1:2; // Read/Write field
180 UINT32 LEN1:2; // Length field
181 UINT32 RW2:2; // Read/Write field
182 UINT32 LEN2:2; // Length field
183 UINT32 RW3:2; // Read/Write field
184 UINT32 LEN3:2; // Length field
185 } Bits;
186 UINTN UintN;
187 } IA32_DR7;
188
189 #endif /* if defined (MDE_CPU_IA32) || defined (MDE_CPU_X64) */
190
191 typedef enum {
192 InstructionExecution, //Hardware breakpoint
193 DataWrite, //watch
194 DataRead, //rwatch
195 DataReadWrite, //awatch
196 SoftwareBreakpoint, //Software breakpoint
197 NotSupported
198 } BREAK_TYPE;
199
200 //
201 // Array of exception types that need to be hooked by the debugger
202 //
203 extern EFI_EXCEPTION_TYPE_ENTRY gExceptionType[];
204
205 //
206 // Set TRUE if F Reply package signals a ctrl-c. We can not process the Ctrl-c
207 // here we need to wait for the periodic callback to do this.
208 //
209 extern BOOLEAN gCtrlCBreakFlag;
210
211 //
212 // If the periodic callback is called while we are processing an F packet we need
213 // to let the callback know to not read from the serial stream as it could steal
214 // characters from the F response packet
215 //
216 extern BOOLEAN gProcessingFPacket;
217
218
219 // The offsets of registers SystemContext.
220 // The fields in the array are in the gdb ordering.
221 //
222 extern UINTN gRegisterOffsets[];
223
224 /**
225 Return the number of entries in the gExceptionType[]
226
227 @retval UINTN, the number of entries in the gExceptionType[] array.
228 **/
229 UINTN
230 MaxEfiException (
231 VOID
232 );
233
234
235 /**
236 Return the number of entries in the gRegisters[]
237
238 @retval UINTN, the number of entries (registers) in the gRegisters[] array.
239 **/
240 UINTN
241 MaxRegisterCount (
242 VOID
243 );
244
245
246 /**
247 Check to see if the ISA is supported.
248 ISA = Instruction Set Architecture
249
250 @retval TRUE if Isa is supported,
251 FALSE otherwise.
252 **/
253 BOOLEAN
254 CheckIsa (
255 IN EFI_INSTRUCTION_SET_ARCHITECTURE Isa
256 );
257
258
259 /**
260 Send the T signal with the given exception type (in gdb order) and possibly with n:r pairs related to the watchpoints
261
262 @param SystemContext Register content at time of the exception
263 @param GdbExceptionType GDB exception type
264 **/
265
266 VOID
267 GdbSendTSignal (
268 IN EFI_SYSTEM_CONTEXT SystemContext,
269 IN UINT8 GdbExceptionType
270 );
271
272
273 /**
274 Translates the EFI mapping to GDB mapping
275
276 @param EFIExceptionType EFI Exception that is being processed
277 @retval UINTN that corresponds to EFIExceptionType's GDB exception type number
278 **/
279 UINT8
280 ConvertEFItoGDBtype (
281 IN EFI_EXCEPTION_TYPE EFIExceptionType
282 );
283
284
285 /**
286 Empties the given buffer
287 @param *Buf pointer to the first element in buffer to be emptied
288 **/
289 VOID
290 EmptyBuffer (
291 IN CHAR8 *Buf
292 );
293
294
295 /**
296 Converts an 8-bit Hex Char into a INTN.
297
298 @param Char - the hex character to be converted into UINTN
299 @retval a INTN, from 0 to 15, that corresponds to Char
300 -1 if Char is not a hex character
301 **/
302 INTN
303 HexCharToInt (
304 IN CHAR8 Char
305 );
306
307
308 /** 'E NN'
309 Send an error with the given error number after converting to hex.
310 The error number is put into the buffer in hex. '255' is the biggest errno we can send.
311 ex: 162 will be sent as A2.
312
313 @param errno the error number that will be sent
314 **/
315 VOID
316 EFIAPI
317 SendError (
318 IN UINT8 ErrorNum
319 );
320
321
322 /**
323 Send 'OK' when the function is done executing successfully.
324 **/
325 VOID
326 EFIAPI
327 SendSuccess (
328 VOID
329 );
330
331
332 /**
333 Send empty packet to specify that particular command/functionality is not supported.
334 **/
335 VOID
336 EFIAPI
337 SendNotSupported (
338 VOID
339 );
340
341 /** ‘p n’
342 Reads the n-th register's value into an output buffer and sends it as a packet
343 @param SystemContext Register content at time of the exception
344 @param InBuffer This is the input buffer received from gdb server
345 **/
346 VOID
347 ReadNthRegister (
348 IN EFI_SYSTEM_CONTEXT SystemContext,
349 IN CHAR8 *InBuffer
350 );
351
352
353 /** ‘g’
354 Reads the general registers into an output buffer and sends it as a packet
355 @param SystemContext Register content at time of the exception
356 **/
357 VOID
358 EFIAPI
359 ReadGeneralRegisters (
360 IN EFI_SYSTEM_CONTEXT SystemContext
361 );
362
363
364 /** ‘P n...=r...’
365 Writes the new value of n-th register received into the input buffer to the n-th register
366 @param SystemContext Register content at time of the exception
367 @param InBuffer This is the input buffer received from gdb server
368 **/
369 VOID
370 EFIAPI
371 WriteNthRegister (
372 IN EFI_SYSTEM_CONTEXT SystemContext,
373 IN CHAR8 *InBuffer
374 );
375
376
377 /** ‘G XX...’
378 Writes the new values received into the input buffer to the general registers
379 @param SystemContext Register content at time of the exception
380 @param InBuffer Pointer to the input buffer received from gdb server
381 **/
382
383 VOID
384 EFIAPI
385 WriteGeneralRegisters (
386 IN EFI_SYSTEM_CONTEXT SystemContext,
387 IN CHAR8 *InBuffer
388 );
389
390
391 /** ‘m addr,length ’
392 Find the Length of the area to read and the start address. Finally, pass them to
393 another function, TransferFromMemToOutBufAndSend, that will read from that memory space and
394 send it as a packet.
395
396 @param *PacketData Pointer to Payload data for the packet
397 **/
398 VOID
399 EFIAPI
400 ReadFromMemory (
401 IN CHAR8 *PacketData
402 );
403
404
405 /** ‘M addr,length :XX...’
406 Find the Length of the area in bytes to write and the start address. Finally, pass them to
407 another function, TransferFromInBufToMem, that will write to that memory space the info in
408 the input buffer.
409
410 @param PacketData Pointer to Payload data for the packet
411 **/
412 VOID
413 EFIAPI
414 WriteToMemory (
415 IN CHAR8 *PacketData
416 );
417
418
419 /** ‘c [addr ]’
420 Continue. addr is Address to resume. If addr is omitted, resume at current
421 Address.
422
423 @param SystemContext Register content at time of the exception
424 @param *PacketData Pointer to PacketData
425 **/
426
427 VOID
428 EFIAPI
429 ContinueAtAddress (
430 IN EFI_SYSTEM_CONTEXT SystemContext,
431 IN CHAR8 *PacketData
432 );
433
434
435 /** ‘s [addr ]’
436 Single step. addr is the Address at which to resume. If addr is omitted, resume
437 at same Address.
438
439 @param SystemContext Register content at time of the exception
440 @param PacketData Pointer to Payload data for the packet
441 **/
442 VOID
443 EFIAPI
444 SingleStep (
445 IN EFI_SYSTEM_CONTEXT SystemContext,
446 IN CHAR8 *PacketData
447 );
448
449 /**
450 Insert Single Step in the SystemContext
451
452 @param SystemContext Register content at time of the exception
453 **/
454 VOID
455 AddSingleStep (
456 IN EFI_SYSTEM_CONTEXT SystemContext
457 );
458
459 /**
460 Remove Single Step in the SystemContext
461
462 @param SystemContext Register content at time of the exception
463 **/
464 VOID
465 RemoveSingleStep (
466 IN EFI_SYSTEM_CONTEXT SystemContext
467 );
468
469
470 /**
471 ‘Z1, [addr], [length]’
472 ‘Z2, [addr], [length]’
473 ‘Z3, [addr], [length]’
474 ‘Z4, [addr], [length]’
475
476 Insert hardware breakpoint/watchpoint at address addr of size length
477
478 @param SystemContext Register content at time of the exception
479 @param *PacketData Pointer to the Payload data for the packet
480
481 **/
482 VOID
483 EFIAPI
484 InsertBreakPoint(
485 IN EFI_SYSTEM_CONTEXT SystemContext,
486 IN CHAR8 *PacketData
487 );
488
489
490 /**
491 ‘z1, [addr], [length]’
492 ‘z2, [addr], [length]’
493 ‘z3, [addr], [length]’
494 ‘z4, [addr], [length]’
495
496 Remove hardware breakpoint/watchpoint at address addr of size length
497
498 @param SystemContext Register content at time of the exception
499 @param *PacketData Pointer to the Payload data for the packet
500
501 **/
502 VOID
503 EFIAPI
504 RemoveBreakPoint(
505 IN EFI_SYSTEM_CONTEXT SystemContext,
506 IN CHAR8 *PacketData
507 );
508
509
510 /**
511 Exception Handler for GDB. It will be called for all exceptions
512 registered via the gExceptionType[] array.
513
514 @param ExceptionType Exception that is being processed
515 @param SystemContext Register content at time of the exception
516
517 **/
518 VOID
519 EFIAPI
520 GdbExceptionHandler (
521 IN EFI_EXCEPTION_TYPE ExceptionType,
522 IN OUT EFI_SYSTEM_CONTEXT SystemContext
523 );
524
525
526 /**
527 Periodic callback for GDB. This function is used to catch a ctrl-c or other
528 break in type command from GDB.
529
530 @param SystemContext Register content at time of the call
531
532 **/
533 VOID
534 EFIAPI
535 GdbPeriodicCallBack (
536 IN OUT EFI_SYSTEM_CONTEXT SystemContext
537 );
538
539
540 /**
541 Make two serial consoles: 1) StdIn and StdOut via GDB. 2) StdErr via GDB.
542
543 These console show up on the remote system running GDB
544
545 **/
546
547 VOID
548 GdbInitializeSerialConsole (
549 VOID
550 );
551
552
553 /**
554 Send a GDB Remote Serial Protocol Packet
555
556 $PacketData#checksum PacketData is passed in and this function adds the packet prefix '$',
557 the packet terminating character '#' and the two digit checksum.
558
559 If an ack '+' is not sent resend the packet, but timeout eventually so we don't end up
560 in an infinite loop. This is so if you unplug the debugger code just keeps running
561
562 @param PacketData Payload data for the packet
563
564 @retval Number of bytes of packet data sent.
565
566 **/
567 UINTN
568 SendPacket (
569 IN CHAR8 *PacketData
570 );
571
572
573 /**
574 Receive a GDB Remote Serial Protocol Packet
575
576 $PacketData#checksum PacketData is passed in and this function adds the packet prefix '$',
577 the packet terminating character '#' and the two digit checksum.
578
579 If host re-starts sending a packet without ending the previous packet, only the last valid packet is processed.
580 (In other words, if received packet is '$12345$12345$123456#checksum', only '$123456#checksum' will be processed.)
581
582 If an ack '+' is not sent resend the packet
583
584 @param PacketData Payload data for the packet
585
586 @retval Number of bytes of packet data received.
587
588 **/
589 UINTN
590 ReceivePacket (
591 OUT CHAR8 *PacketData,
592 IN UINTN PacketDataSize
593 );
594
595
596 /**
597 Read data from a FileDescriptor. On success number of bytes read is returned. Zero indicates
598 the end of a file. On error -1 is returned. If count is zero, GdbRead returns zero.
599
600 @param FileDescriptor Device to talk to.
601 @param Buffer Buffer to hold Count bytes that were read
602 @param Count Number of bytes to transfer.
603
604 @retval -1 Error
605 @retval {other} Number of bytes read.
606
607 **/
608 INTN
609 GdbRead (
610 IN INTN FileDescriptor,
611 OUT VOID *Buffer,
612 IN UINTN Count
613 );
614
615
616 /**
617 Write data to a FileDescriptor. On success number of bytes written is returned. Zero indicates
618 nothing was written. On error -1 is returned.
619
620 @param FileDescriptor Device to talk to.
621 @param Buffer Buffer to hold Count bytes that are to be written
622 @param Count Number of bytes to transfer.
623
624 @retval -1 Error
625 @retval {other} Number of bytes written.
626
627 **/
628 INTN
629 GdbWrite (
630 IN INTN FileDescriptor,
631 OUT CONST VOID *Buffer,
632 IN UINTN Count
633 );
634
635 UINTN *
636 FindPointerToRegister (
637 IN EFI_SYSTEM_CONTEXT SystemContext,
638 IN UINTN RegNumber
639 );
640
641 CHAR8 *
642 BasicReadRegister (
643 IN EFI_SYSTEM_CONTEXT SystemContext,
644 IN UINTN RegNumber,
645 IN CHAR8 *OutBufPtr
646 );
647
648 VOID
649 TransferFromInBufToMem (
650 IN UINTN Length,
651 IN UINT8 *Address,
652 IN CHAR8 *NewData
653 );
654
655 VOID
656 TransferFromMemToOutBufAndSend (
657 IN UINTN Length,
658 IN UINT8 *Address
659 );
660
661 CHAR8 *
662 BasicWriteRegister (
663 IN EFI_SYSTEM_CONTEXT SystemContext,
664 IN UINTN RegNumber,
665 IN CHAR8 *InBufPtr
666 );
667
668 VOID
669 PrintReg (
670 EFI_SYSTEM_CONTEXT SystemContext
671 );
672
673 UINTN
674 ParseBreakpointPacket (
675 IN CHAR8 *PacketData,
676 OUT UINTN *Type,
677 OUT UINTN *Address,
678 OUT UINTN *Length
679 );
680
681 UINTN
682 GetBreakpointDataAddress (
683 IN EFI_SYSTEM_CONTEXT SystemContext,
684 IN UINTN BreakpointNumber
685 );
686
687 UINTN
688 GetBreakpointDetected (
689 IN EFI_SYSTEM_CONTEXT SystemContext
690 );
691
692 BREAK_TYPE
693 GetBreakpointType (
694 IN EFI_SYSTEM_CONTEXT SystemContext,
695 IN UINTN BreakpointNumber
696 );
697
698 UINTN
699 ConvertLengthData (
700 IN UINTN Length
701 );
702
703 EFI_STATUS
704 FindNextFreeDebugRegister (
705 IN EFI_SYSTEM_CONTEXT SystemContext,
706 OUT UINTN *Register
707 );
708
709 EFI_STATUS
710 EnableDebugRegister (
711 IN EFI_SYSTEM_CONTEXT SystemContext,
712 IN UINTN Register,
713 IN UINTN Address,
714 IN UINTN Length,
715 IN UINTN Type
716 );
717
718 EFI_STATUS
719 FindMatchingDebugRegister (
720 IN EFI_SYSTEM_CONTEXT SystemContext,
721 IN UINTN Address,
722 IN UINTN Length,
723 IN UINTN Type,
724 OUT UINTN *Register
725 );
726
727 EFI_STATUS
728 DisableDebugRegister (
729 IN EFI_SYSTEM_CONTEXT SystemContext,
730 IN UINTN Register
731 );
732
733 VOID
734 InitializeProcessor (
735 VOID
736 );
737
738 BOOLEAN
739 ValidateAddress (
740 IN VOID *Address
741 );
742
743 BOOLEAN
744 ValidateException (
745 IN EFI_EXCEPTION_TYPE ExceptionType,
746 IN OUT EFI_SYSTEM_CONTEXT SystemContext
747 );
748
749 #endif