EmbeddedPkg: Fix various typos
[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 SendSuccess (
327 VOID
328 );
329
330
331 /**
332 Send empty packet to specify that particular command/functionality is not supported.
333 **/
334 VOID
335 SendNotSupported (
336 VOID
337 );
338
339 /** ‘p n’
340 Reads the n-th register's value into an output buffer and sends it as a packet
341 @param SystemContext Register content at time of the exception
342 @param InBuffer This is the input buffer received from gdb server
343 **/
344 VOID
345 ReadNthRegister (
346 IN EFI_SYSTEM_CONTEXT SystemContext,
347 IN CHAR8 *InBuffer
348 );
349
350
351 /** ‘g’
352 Reads the general registers into an output buffer and sends it as a packet
353 @param SystemContext Register content at time of the exception
354 **/
355 VOID
356 ReadGeneralRegisters (
357 IN EFI_SYSTEM_CONTEXT SystemContext
358 );
359
360
361 /** ‘P n...=r...’
362 Writes the new value of n-th register received into the input buffer to the n-th register
363 @param SystemContext Register content at time of the exception
364 @param InBuffer This is the input buffer received from gdb server
365 **/
366 VOID
367 WriteNthRegister (
368 IN EFI_SYSTEM_CONTEXT SystemContext,
369 IN CHAR8 *InBuffer
370 );
371
372
373 /** ‘G XX...’
374 Writes the new values received into the input buffer to the general registers
375 @param SystemContext Register content at time of the exception
376 @param InBuffer Pointer to the input buffer received from gdb server
377 **/
378
379 VOID
380 WriteGeneralRegisters (
381 IN EFI_SYSTEM_CONTEXT SystemContext,
382 IN CHAR8 *InBuffer
383 );
384
385
386 /** ‘m addr,length ’
387 Find the Length of the area to read and the start address. Finally, pass them to
388 another function, TransferFromMemToOutBufAndSend, that will read from that memory space and
389 send it as a packet.
390
391 @param *PacketData Pointer to Payload data for the packet
392 **/
393 VOID
394 ReadFromMemory (
395 IN CHAR8 *PacketData
396 );
397
398
399 /** ‘M addr,length :XX...’
400 Find the Length of the area in bytes to write and the start address. Finally, pass them to
401 another function, TransferFromInBufToMem, that will write to that memory space the info in
402 the input buffer.
403
404 @param PacketData Pointer to Payload data for the packet
405 **/
406 VOID
407 WriteToMemory (
408 IN CHAR8 *PacketData
409 );
410
411
412 /** ‘c [addr ]’
413 Continue. addr is Address to resume. If addr is omitted, resume at current
414 Address.
415
416 @param SystemContext Register content at time of the exception
417 @param *PacketData Pointer to PacketData
418 **/
419
420 VOID
421 ContinueAtAddress (
422 IN EFI_SYSTEM_CONTEXT SystemContext,
423 IN CHAR8 *PacketData
424 );
425
426
427 /** ‘s [addr ]’
428 Single step. addr is the Address at which to resume. If addr is omitted, resume
429 at same Address.
430
431 @param SystemContext Register content at time of the exception
432 @param PacketData Pointer to Payload data for the packet
433 **/
434 VOID
435 SingleStep (
436 IN EFI_SYSTEM_CONTEXT SystemContext,
437 IN CHAR8 *PacketData
438 );
439
440 /**
441 Insert Single Step in the SystemContext
442
443 @param SystemContext Register content at time of the exception
444 **/
445 VOID
446 AddSingleStep (
447 IN EFI_SYSTEM_CONTEXT SystemContext
448 );
449
450 /**
451 Remove Single Step in the SystemContext
452
453 @param SystemContext Register content at time of the exception
454 **/
455 VOID
456 RemoveSingleStep (
457 IN EFI_SYSTEM_CONTEXT SystemContext
458 );
459
460
461 /**
462 ‘Z1, [addr], [length]’
463 ‘Z2, [addr], [length]’
464 ‘Z3, [addr], [length]’
465 ‘Z4, [addr], [length]’
466
467 Insert hardware breakpoint/watchpoint at address addr of size length
468
469 @param SystemContext Register content at time of the exception
470 @param *PacketData Pointer to the Payload data for the packet
471
472 **/
473 VOID
474 EFIAPI
475 InsertBreakPoint(
476 IN EFI_SYSTEM_CONTEXT SystemContext,
477 IN CHAR8 *PacketData
478 );
479
480
481 /**
482 ‘z1, [addr], [length]’
483 ‘z2, [addr], [length]’
484 ‘z3, [addr], [length]’
485 ‘z4, [addr], [length]’
486
487 Remove hardware breakpoint/watchpoint at address addr of size length
488
489 @param SystemContext Register content at time of the exception
490 @param *PacketData Pointer to the Payload data for the packet
491
492 **/
493 VOID
494 EFIAPI
495 RemoveBreakPoint(
496 IN EFI_SYSTEM_CONTEXT SystemContext,
497 IN CHAR8 *PacketData
498 );
499
500
501 /**
502 Exception Handler for GDB. It will be called for all exceptions
503 registered via the gExceptionType[] array.
504
505 @param ExceptionType Exception that is being processed
506 @param SystemContext Register content at time of the exception
507
508 **/
509 VOID
510 EFIAPI
511 GdbExceptionHandler (
512 IN EFI_EXCEPTION_TYPE ExceptionType,
513 IN OUT EFI_SYSTEM_CONTEXT SystemContext
514 );
515
516
517 /**
518 Periodic callback for GDB. This function is used to catch a ctrl-c or other
519 break in type command from GDB.
520
521 @param SystemContext Register content at time of the call
522
523 **/
524 VOID
525 EFIAPI
526 GdbPeriodicCallBack (
527 IN OUT EFI_SYSTEM_CONTEXT SystemContext
528 );
529
530
531 /**
532 Make two serial consoles: 1) StdIn and StdOut via GDB. 2) StdErr via GDB.
533
534 These console show up on the remote system running GDB
535
536 **/
537
538 VOID
539 GdbInitializeSerialConsole (
540 VOID
541 );
542
543
544 /**
545 Send a GDB Remote Serial Protocol Packet
546
547 $PacketData#checksum PacketData is passed in and this function adds the packet prefix '$',
548 the packet terminating character '#' and the two digit checksum.
549
550 If an ack '+' is not sent resend the packet, but timeout eventually so we don't end up
551 in an infinite loop. This is so if you unplug the debugger code just keeps running
552
553 @param PacketData Payload data for the packet
554
555 @retval Number of bytes of packet data sent.
556
557 **/
558 UINTN
559 SendPacket (
560 IN CHAR8 *PacketData
561 );
562
563
564 /**
565 Receive a GDB Remote Serial Protocol Packet
566
567 $PacketData#checksum PacketData is passed in and this function adds the packet prefix '$',
568 the packet terminating character '#' and the two digit checksum.
569
570 If host re-starts sending a packet without ending the previous packet, only the last valid packet is processed.
571 (In other words, if received packet is '$12345$12345$123456#checksum', only '$123456#checksum' will be processed.)
572
573 If an ack '+' is not sent resend the packet
574
575 @param PacketData Payload data for the packet
576
577 @retval Number of bytes of packet data received.
578
579 **/
580 UINTN
581 ReceivePacket (
582 OUT CHAR8 *PacketData,
583 IN UINTN PacketDataSize
584 );
585
586
587 /**
588 Read data from a FileDescriptor. On success number of bytes read is returned. Zero indicates
589 the end of a file. On error -1 is returned. If count is zero, GdbRead returns zero.
590
591 @param FileDescriptor Device to talk to.
592 @param Buffer Buffer to hold Count bytes that were read
593 @param Count Number of bytes to transfer.
594
595 @retval -1 Error
596 @retval {other} Number of bytes read.
597
598 **/
599 INTN
600 GdbRead (
601 IN INTN FileDescriptor,
602 OUT VOID *Buffer,
603 IN UINTN Count
604 );
605
606
607 /**
608 Write data to a FileDescriptor. On success number of bytes written is returned. Zero indicates
609 nothing was written. On error -1 is returned.
610
611 @param FileDescriptor Device to talk to.
612 @param Buffer Buffer to hold Count bytes that are to be written
613 @param Count Number of bytes to transfer.
614
615 @retval -1 Error
616 @retval {other} Number of bytes written.
617
618 **/
619 INTN
620 GdbWrite (
621 IN INTN FileDescriptor,
622 OUT CONST VOID *Buffer,
623 IN UINTN Count
624 );
625
626 UINTN *
627 FindPointerToRegister (
628 IN EFI_SYSTEM_CONTEXT SystemContext,
629 IN UINTN RegNumber
630 );
631
632 CHAR8 *
633 BasicReadRegister (
634 IN EFI_SYSTEM_CONTEXT SystemContext,
635 IN UINTN RegNumber,
636 IN CHAR8 *OutBufPtr
637 );
638
639 VOID
640 TransferFromInBufToMem (
641 IN UINTN Length,
642 IN UINT8 *Address,
643 IN CHAR8 *NewData
644 );
645
646 VOID
647 TransferFromMemToOutBufAndSend (
648 IN UINTN Length,
649 IN UINT8 *Address
650 );
651
652 CHAR8 *
653 BasicWriteRegister (
654 IN EFI_SYSTEM_CONTEXT SystemContext,
655 IN UINTN RegNumber,
656 IN CHAR8 *InBufPtr
657 );
658
659 VOID
660 PrintReg (
661 EFI_SYSTEM_CONTEXT SystemContext
662 );
663
664 UINTN
665 ParseBreakpointPacket (
666 IN CHAR8 *PacketData,
667 OUT UINTN *Type,
668 OUT UINTN *Address,
669 OUT UINTN *Length
670 );
671
672 UINTN
673 GetBreakpointDataAddress (
674 IN EFI_SYSTEM_CONTEXT SystemContext,
675 IN UINTN BreakpointNumber
676 );
677
678 UINTN
679 GetBreakpointDetected (
680 IN EFI_SYSTEM_CONTEXT SystemContext
681 );
682
683 BREAK_TYPE
684 GetBreakpointType (
685 IN EFI_SYSTEM_CONTEXT SystemContext,
686 IN UINTN BreakpointNumber
687 );
688
689 UINTN
690 ConvertLengthData (
691 IN UINTN Length
692 );
693
694 EFI_STATUS
695 FindNextFreeDebugRegister (
696 IN EFI_SYSTEM_CONTEXT SystemContext,
697 OUT UINTN *Register
698 );
699
700 EFI_STATUS
701 EnableDebugRegister (
702 IN EFI_SYSTEM_CONTEXT SystemContext,
703 IN UINTN Register,
704 IN UINTN Address,
705 IN UINTN Length,
706 IN UINTN Type
707 );
708
709 EFI_STATUS
710 FindMatchingDebugRegister (
711 IN EFI_SYSTEM_CONTEXT SystemContext,
712 IN UINTN Address,
713 IN UINTN Length,
714 IN UINTN Type,
715 OUT UINTN *Register
716 );
717
718 EFI_STATUS
719 DisableDebugRegister (
720 IN EFI_SYSTEM_CONTEXT SystemContext,
721 IN UINTN Register
722 );
723
724 VOID
725 InitializeProcessor (
726 VOID
727 );
728
729 BOOLEAN
730 ValidateAddress (
731 IN VOID *Address
732 );
733
734 BOOLEAN
735 ValidateException (
736 IN EFI_EXCEPTION_TYPE ExceptionType,
737 IN OUT EFI_SYSTEM_CONTEXT SystemContext
738 );
739
740 #endif