gdb Internals A guide to the internals of the GNU debugger John Gilmore Cygnus Solutions Second Edition: Stan Shebs Cygnus Solutions Cygnus Solutions Revision TEXinfo 2004-02-19.09 Copyright c 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”. i Table of Contents Scope of this Document ....................... 1 1 Requirements.............................. 1 2 Overall Structure .......................... 1 2.1 The Symbol Side ............................................ 2 2.2 The Target Side ............................................. 2 2.3 Configurations .............................................. 2 3 Algorithms ................................ 2 3.1 Frames ..................................................... 2 3.2 Breakpoint Handling ........................................ 3 3.3 Single Stepping ............................................. 4 3.4 Signal Handling ............................................. 4 3.5 Thread Handling ............................................ 4 3.6 Inferior Function Calls ....................................... 4 3.7 Longjmp Support ........................................... 4 3.8 Watchpoints ................................................ 4 3.8.1 x86 Watchpoints ........................................ 6 3.9 Observing changes in gdb internals ........................... 9 4 User Interface ............................. 9 4.1 Command Interpreter........................................ 9 4.2 UI-Independent Output—the ui_out Functions............... 10 4.2.1 Overview and Terminology ............................. 10 4.2.2 General Conventions ................................... 11 4.2.3 Table, Tuple and List Functions ........................ 11 4.2.4 Item Output Functions ................................. 13 4.2.5 Utility Output Functions ............................... 15 4.2.6 Examples of Use of ui_out functions .................... 15 4.3 Console Printing ........................................... 18 4.4 TUI ....................................................... 18 5 libgdb.................................... 19 5.1 libgdb 1.0.................................................. 19 5.2 libgdb 2.0.................................................. 19 5.3 The libgdb Model ......................................... 19 5.4 CLI support ............................................... 19 5.5 libgdb components ........................................ 20 ii 6 Symbol Handling ......................... 20 6.1 Symbol Reading............................................ 20 6.2 Partial Symbol Tables ...................................... 22 6.3 Types ..................................................... 23 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). ............... 23 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). .......... 23 Builtin Types (e.g., builtin_type_void, builtin_type_char)... 23 6.4 Object File Formats ........................................ 23 6.4.1 a.out ................................................. 23 6.4.2 COFF ................................................ 23 6.4.3 ECOFF ............................................... 24 6.4.4 XCOFF ............................................... 24 6.4.5 PE ................................................... 24 6.4.6 ELF .................................................. 24 6.4.7 SOM ................................................. 24 6.4.8 Other File Formats .................................... 24 6.5 Debugging File Formats .................................... 24 6.5.1 stabs ................................................. 25 6.5.2 COFF ................................................ 25 6.5.3 Mips debug (Third Eye)................................ 25 6.5.4 DWARF 1 ............................................ 25 6.5.5 DWARF 2 ............................................ 25 6.5.6 SOM ................................................. 25 6.6 Adding a New Symbol Reader to gdb ....................... 25 7 Language Support ........................ 26 7.1 Adding a Source Language to gdb........................... 26 8 Host Definition ........................... 27 8.1 Adding a New Host ........................................ 28 8.2 Host Conditionals .......................................... 28 9 Target Architecture Definition ............. 31 9.1 Operating System ABI Variant Handling ..................... 31 9.2 Registers and Memory ...................................... 33 9.3 Pointers Are Not Always Addresses .......................... 33 9.4 Address Classes ............................................ 35 9.5 Raw and Virtual Register Representations.................... 36 9.6 Using Different Register and Memory Data Representations ... 37 9.7 Frame Interpretation ....................................... 38 9.8 Inferior Call Setup ......................................... 39 9.9 Compiler Characteristics .................................... 39 9.10 Target Conditionals ....................................... 39 9.11 Adding a New Target...................................... 54 9.12 Converting an existing Target Architecture to Multi-arch ..... 55 9.12.1 Preparation .......................................... 55 9.12.2 Add the multi-arch initialization code .................. 55 iii 9.12.3 Update multi-arch incompatible mechanisms ............ 56 9.12.4 Prepare for multi-arch level to one ..................... 56 9.12.5 Set multi-arch level one ............................... 56 9.12.6 Convert remaining macros ............................. 56 9.12.7 Set multi-arch level to two............................. 57 9.12.8 Delete the TM file .................................... 57 10 Target Vector Definition ................. 57 10.1 File Targets............................................... 57 10.2 Standard Protocol and Remote Stubs ....................... 57 10.3 ROM Monitor Interface.................................... 57 10.4 Custom Protocols ......................................... 58 10.5 Transport Layer........................................... 58 10.6 Builtin Simulator.......................................... 58 11 Native Debugging ....................... 58 11.1 Native core file Support.................................... 59 11.2 ptrace .................................................... 59 11.3 /proc..................................................... 60 11.4 win32 .................................................... 60 11.5 shared libraries............................................ 60 11.6 Native Conditionals ....................................... 60 12 Support Libraries ........................ 62 12.1 BFD ..................................................... 62 12.2 opcodes .................................................. 62 12.3 readline .................................................. 62 12.4 mmalloc .................................................. 62 12.5 libiberty .................................................. 63 12.5.1 obstacks in gdb ..................................... 63 12.6 gnu-regex ................................................. 63 12.7 include ................................................... 64 13 Coding.................................. 64 13.1 Cleanups ................................................. 64 13.2 Per-architecture module data............................... 65 13.3 Wrapping Output Lines.................................... 67 13.4 gdb Coding Standards .................................... 67 13.4.1 ISO C ............................................... 67 13.4.2 Memory Management ................................. 67 13.4.3 Compiler Warnings ................................... 68 13.4.4 Formatting ........................................... 69 13.4.5 Comments ........................................... 69 13.4.6 C Usage ............................................. 70 13.4.7 Function Prototypes .................................. 70 13.4.8 Internal Error Recovery ............................... 70 13.4.9 File Names ........................................... 70 iv 13.4.10 Include Files ........................................ 71 13.4.11 Clean Design and Portable Implementation ............ 71 14 Porting gdb ............................. 73 15 Versions and Branches ................... 74 15.1 Versions .................................................. 74 15.2 Release Branches .......................................... 75 15.3 Vendor Branches .......................................... 75 15.4 Experimental Branches .................................... 75 15.4.1 Guidelines ........................................... 75 15.4.2 Tags ................................................. 76 16 Releasing gdb ........................... 77 16.1 Branch Commit Policy .................................... 77 16.2 Obsoleting code ........................................... 77 16.3 Before the Branch ......................................... 78 16.3.1 Review the bug data base ............................. 78 16.3.2 Check all cross targets build ........................... 78 16.4 Cut the Branch ........................................... 78 16.5 Stabilize the branch ......................................