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