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 2007-09-03.05 Copyright c 1990-2013 Free Software Foundation, Inc. Contributed by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan Shebs. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 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 Summary :::::::::::::::::::::::::::::::::::::::: 1 1.1 Requirements :::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.2 Contributors ::::::::::::::::::::::::::::::::::::::::::::::::::: 1 2 Overall Structure ::::::::::::::::::::::::::::::: 2 2.1 The Symbol Side ::::::::::::::::::::::::::::::::::::::::::::::: 2 2.2 The Target Side :::::::::::::::::::::::::::::::::::::::::::::::: 2 2.3 Configurations ::::::::::::::::::::::::::::::::::::::::::::::::: 2 2.4 Source Tree Structure :::::::::::::::::::::::::::::::::::::::::: 3 3 Algorithms :::::::::::::::::::::::::::::::::::::: 4 3.1 Prologue Analysis :::::::::::::::::::::::::::::::::::::::::::::: 4 3.2 Breakpoint Handling ::::::::::::::::::::::::::::::::::::::::::: 6 3.3 Single Stepping :::::::::::::::::::::::::::::::::::::::::::::::: 7 3.4 Signal Handling :::::::::::::::::::::::::::::::::::::::::::::::: 7 3.5 Thread Handling ::::::::::::::::::::::::::::::::::::::::::::::: 7 3.6 Inferior Function Calls ::::::::::::::::::::::::::::::::::::::::: 7 3.7 Longjmp Support :::::::::::::::::::::::::::::::::::::::::::::: 7 3.8 Watchpoints ::::::::::::::::::::::::::::::::::::::::::::::::::: 8 3.8.1 Watchpoints and Threads :::::::::::::::::::::::::::::::: 10 3.8.2 x86 Watchpoints ::::::::::::::::::::::::::::::::::::::::: 10 3.9 Checkpoints::::::::::::::::::::::::::::::::::::::::::::::::::: 13 3.10 Observing changes in gdb internals :::::::::::::::::::::::::: 13 4 User Interface:::::::::::::::::::::::::::::::::: 14 4.1 Command Interpreter ::::::::::::::::::::::::::::::::::::::::: 14 4.2 UI-Independent Output|the ui_out Functions:::::::::::::::: 14 4.2.1 Overview and Terminology ::::::::::::::::::::::::::::::: 14 4.2.2 General Conventions ::::::::::::::::::::::::::::::::::::: 15 4.2.3 Table, Tuple and List Functions :::::::::::::::::::::::::: 15 4.2.4 Item Output Functions ::::::::::::::::::::::::::::::::::: 17 4.2.5 Utility Output Functions ::::::::::::::::::::::::::::::::: 19 4.2.6 Examples of Use of ui_out functions ::::::::::::::::::::: 20 4.3 Console Printing :::::::::::::::::::::::::::::::::::::::::::::: 23 4.4 TUI :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 ii 5 libgdb :::::::::::::::::::::::::::::::::::::::::: 23 5.1 libgdb 1.0 ::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 5.2 libgdb 2.0 ::::::::::::::::::::::::::::::::::::::::::::::::::::: 23 5.3 The libgdb Model :::::::::::::::::::::::::::::::::::::::::::: 23 5.4 CLI support :::::::::::::::::::::::::::::::::::::::::::::::::: 24 5.5 libgdb components ::::::::::::::::::::::::::::::::::::::::::: 24 6 Values :::::::::::::::::::::::::::::::::::::::::: 25 6.1 Values :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 25 7 Stack Frames :::::::::::::::::::::::::::::::::: 26 7.1 Selecting an Unwinder :::::::::::::::::::::::::::::::::::::::: 26 7.2 Unwinding the Frame ID :::::::::::::::::::::::::::::::::::::: 27 7.3 Unwinding Registers :::::::::::::::::::::::::::::::::::::::::: 27 8 Symbol Handling :::::::::::::::::::::::::::::: 28 8.1 Symbol Reading :::::::::::::::::::::::::::::::::::::::::::::: 28 8.2 Partial Symbol Tables::::::::::::::::::::::::::::::::::::::::: 29 8.3 Types::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 Fundamental Types (e.g., FT_VOID, FT_BOOLEAN). :::::::::::::::: 31 Type Codes (e.g., TYPE_CODE_PTR, TYPE_CODE_ARRAY). :::::::::: 31 Builtin Types (e.g., builtin_type_void, builtin_type_char). :: 31 8.4 Object File Formats::::::::::::::::::::::::::::::::::::::::::: 31 8.4.1 a.out ::::::::::::::::::::::::::::::::::::::::::::::::::::: 31 8.4.2 COFF ::::::::::::::::::::::::::::::::::::::::::::::::::: 31 8.4.3 ECOFF :::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.4.4 XCOFF :::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.4.5 PE::::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.4.6 ELF ::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.4.7 SOM::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.5 Debugging File Formats ::::::::::::::::::::::::::::::::::::::: 32 8.5.1 stabs::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.5.2 COFF ::::::::::::::::::::::::::::::::::::::::::::::::::: 32 8.5.3 Mips debug (Third Eye) :::::::::::::::::::::::::::::::::: 33 8.5.4 DWARF 2 ::::::::::::::::::::::::::::::::::::::::::::::: 33 8.5.5 Compressed DWARF 2 ::::::::::::::::::::::::::::::::::: 33 8.5.6 DWARF 3 ::::::::::::::::::::::::::::::::::::::::::::::: 33 8.5.7 SOM::::::::::::::::::::::::::::::::::::::::::::::::::::: 33 8.6 Adding a New Symbol Reader to gdb ::::::::::::::::::::::::: 33 8.7 Memory Management for Symbol Files :::::::::::::::::::::::: 34 9 Language Support ::::::::::::::::::::::::::::: 34 9.1 Adding a Source Language to gdb :::::::::::::::::::::::::::: 34 iii 10 Host Definition ::::::::::::::::::::::::::::::: 36 10.1 Adding a New Host :::::::::::::::::::::::::::::::::::::::::: 36 10.2 Host Conditionals:::::::::::::::::::::::::::::::::::::::::::: 36 11 Target Architecture Definition :::::::::::::: 37 11.1 Operating System ABI Variant Handling ::::::::::::::::::::: 37 11.2 Initializing a New Architecture ::::::::::::::::::::::::::::::: 40 11.2.1 How an Architecture is Represented ::::::::::::::::::::: 40 11.2.2 Looking Up an Existing Architecture :::::::::::::::::::: 40 11.2.3 Creating a New Architecture :::::::::::::::::::::::::::: 41 11.3 Registers and Memory ::::::::::::::::::::::::::::::::::::::: 42 11.4 Pointers Are Not Always Addresses :::::::::::::::::::::::::: 42 11.5 Address Classes :::::::::::::::::::::::::::::::::::::::::::::: 44 11.6 Register Representation :::::::::::::::::::::::::::::::::::::: 45 11.6.1 Raw and Cooked Registers :::::::::::::::::::::::::::::: 45 11.6.2 Functions and Variables Specifying the Register Architecture :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 45 11.6.3 Functions Giving Register Information::::::::::::::::::: 47 11.6.4 Using Different Register and Memory Data Representations :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 48 11.6.5 Register Caching :::::::::::::::::::::::::::::::::::::::: 49 11.7 Frame Interpretation ::::::::::::::::::::::::::::::::::::::::: 50 11.7.1 All About Stack Frames ::::::::::::::::::::::::::::::::: 50 11.7.2 Frame Handling Terminology :::::::::::::::::::::::::::: 51 11.7.3 Prologue Caches :::::::::::::::::::::::::::::::::::::::: 52 11.7.4 Functions and Variable to Analyze Frames::::::::::::::: 53 11.7.5 Functions to Access Frame Data::::::::::::::::::::::::: 54 11.7.6 Analyzing Stacks|Frame Sniffers ::::::::::::::::::::::: 55 11.8 Inferior Call Setup ::::::::::::::::::::::::::::::::::::::::::: 56 11.8.1 About Dummy Frames :::::::::::::::::::::::::::::::::: 56 11.8.2 Functions Creating Dummy Frames ::::::::::::::::::::: 56 11.9 Adding support for debugging core files :::::::::::::::::::::: 58 11.10 Defining Other Architecture Features:::::::::::::::::::::::: 58 11.11 Adding a New Target ::::::::::::::::::::::::::::::::::::::: 67 12 Target Descriptions :::::::::::::::::::::::::: 68 12.1 Target Descriptions Implementation :::::::::::::::::::::::::: 68 12.2 Adding Target Described Register Support ::::::::::::::::::: 68 13 Target Vector Definition::::::::::::::::::::: 69 13.1 Managing Execution State ::::::::::::::::::::::::::::::::::: 69 13.2 Existing Targets ::::::::::::::::::::::::::::::::::::::::::::: 70 13.2.1 File Targets ::::::::::::::::::::::::::::::::::::::::::::: 70 13.2.2 Standard Protocol and Remote Stubs:::::::::::::::::::: 70 13.2.3 ROM Monitor Interface ::::::::::::::::::::::::::::::::: 70 13.2.4 Custom Protocols ::::::::::::::::::::::::::::::::::::::: 70 13.2.5 Transport Layer::::::::::::::::::::::::::::::::::::::::: 70 13.2.6 Builtin Simulator ::::::::::::::::::::::::::::::::::::::: 70 iv 14 Native Debugging :::::::::::::::::::::::::::: 71 14.1 ptrace ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 71 14.2 /proc :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 14.3 win32:::::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 14.4 shared libraries :::::::::::::::::::::::::::::::::::::::::::::: 72 14.5 Native Conditionals :::::::::::::::::::::::::::::::::::::::::: 72 15 Support Libraries :::::::::::::::::::::::::::: 72 15.1 BFD::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 72 15.2 opcodes:::::::::::::::::::::::::::::::::::::::::::::::::::::: 73 15.3 readline:::::::::::::::::::::::::::::::::::::::::::::::::::::: 73 15.4 libiberty ::::::::::::::::::::::::::::::::::::::::::::::::::::: 73 15.4.1 obstacks in gdb:::::::::::::::::::::::::::::::::::::::: 73 15.5 gnu-regex :::::::::::::::::::::::::::::::::::::::::::::::::::: 74 15.6 Array Containers :::::::::::::::::::::::::::::::::::::::::::: 74 15.7 include :::::::::::::::::::::::::::::::::::::::::::::::::::::: 77 16 Coding Standards :::::::::::::::::::::::::::: 77 16.1 gdb C Coding Standards