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   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