Inside the Debugger: Building a Source-Level Debugger in Rust

A Deep Dive into Processes, Memory, Breakpoints, and DWARF Debug Information

Introduction

1. Why Build a Debugger?
2. What This Book Covers
3. Prerequisites
4. How to Read This Book
5. What About the Code?

Chapter 1: What Is a Debugger, Really?

1. The Debugger as an Operating System Feature
2. The Debugging Loop
3. What We Will Build
4. Why Rust for a Debugger?
5. The Architecture of Our Debugger
6. A Brief History of Debuggers

Chapter 2: The Building Blocks: Processes, Memory, and the CPU

1. Processes and the Process Table
2. Virtual Memory and Address Spaces
3. The CPU Registers and Program Counter
4. How Programs Start: Loading and Entry Points
5. System Calls and the Kernel Boundary
6. Putting It All Together: A Process in Motion

Chapter 3: The ptrace System Call: Your Gateway to Debugging

1. ptrace Fundamentals
2. Process Stop States and Wait
3. Reading and Writing Registers
4. Reading and Writing Memory
5. Single Stepping and Instruction Control
6. ptrace Security and Permissions
7. The Complete ptrace Workflow

Chapter 4: Executable Formats and DWARF Debug Information

1. The ELF File Format
2. Symbol Tables and Relocations
3. DWARF Debug Information Overview
4. Line Number Program
5. Variable Locations and Expressions
6. Reading DWARF in Rust with gimli
7. DWARF Version Differences
8. Putting It Together: From Address to Source Line

Chapter 5: Project Setup and the Debugger Shell

1. Project Structure and Dependencies
2. The Debugger Core Trait and Architecture
3. Command Parsing
4. Process Fork and Trace
5. The First Debug Session
6. The First Debug Session

Chapter 6: Breakpoints: Stopping at Will

1. Software Breakpoints and INT3
2. The Breakpoint Lifecycle
3. Breakpoint Data Structures
4. Handling Breakpoint Hits
5. Multiple Breakpoints and Conditional Execution
6. Testing Breakpoints
7. Common Pitfalls

Chapter 7: Single Stepping and Register Inspection

1. Single Stepping with PTRACE_SINGLESTEP
2. The x86_64 Register File
3. Reading Registers After a Stop
4. Writing Registers
5. The Step Over Problem
6. Register Display Formatting

Chapter 8: Memory Inspection and Modification

1. Reading Process Memory
2. Memory Display Formats
3. Handling Page Faults and Invalid Addresses
4. The /proc/[pid]/mem Alternative
5. Memory Region Discovery
6. Writing Memory Safely

Chapter 9: Symbol Resolution and Source-Level Debugging

1. Symbol Lookup
2. Demangling C++ and Rust Symbols
3. Source File Discovery
4. Displaying Source Code with Current Line Highlighting
5. Step Over at the Source Level
6. Frame Pointer Omission and Its Consequences

Chapter 10: Stack Unwinding and Call Frames

1. The Call Stack Explained
2. Frame Pointer-Based Unwinding
3. DWARF Call Frame Information
4. Displaying the Backtrace
5. Local Variable Inspection

Chapter 11: Watchpoints, Hardware Breakpoints, and Advanced Tracing

1. Hardware Debug Registers
2. Setting Hardware Breakpoints
3. The PTRACE_GETREGSET and NT_X86_DEBUGREGS Interface
4. Limitations and Fallback Strategies
5. Watchpoint Manager
6. Tracepoints and Logging

Chapter 12: Multithreaded Debugging and Shared Libraries

1. Thread Groups and ptrace
2. PTRACE_SEIZE and Group Stop
3. Debugging Existing Processes
4. Shared Library Loading Events
5. Symbol Resolution Across Shared Libraries
6. Thread-Specific Data and Stack Layout

Chapter 13: Expression Evaluation and Variable Modification

1. The Expression Evaluation Problem
2. Building a Simple Expression Parser
3. Type Resolution from DWARF
4. The Set Command
5. Limitations and Pragmatic Choices

Chapter 14: Signals, Exceptions, and Error Handling

1. Signal Delivery During Tracing
2. Distinguishing Breakpoint Signals from Real SIGTRAPs
3. Signal Masking and Filtering
4. Handling Common Signals
5. Crash Dump Generation
6. Debugger Error Handling

Chapter 15: Architecture, Testing, and Going Further

1. The Complete Debugger Architecture
2. Testing a Debugger
3. Performance Considerations
4. Portability: macOS ptrace and Windows Debug Active Process API
5. Remote Debugging Concepts
6. Extending Your Debugger

Conclusion: What We Built and What It Teaches Us

1. The Layers of Understanding
2. What Makes a Good Debugger?
3. The Bigger Picture
4. Final Thoughts

Appendix A: Complete Project Structure

1. Directory Layout
2. Module Dependencies
3. Shared Types and Conventions
4. Building and Running
5. Testing Strategy
6. Companion Repository

References