GDR - GDB Enhanced Features for RTOS

GDR is a comprehensive GDB debugging framework that provides advanced debugging capabilities for Real-Time Operating Systems (RTOS). Currently featuring complete RT-Thread support with plans for FreeRTOS and other RTOS platforms.

🚀 Features

✅ RT-Thread Support (Complete)

• Multi-version compatibility: RT-Thread 3.x, 4.x, 5.x
• Comprehensive object inspection: Threads, semaphores, mutexes, timers, queues, memory pools
• Advanced debugging: Stack analysis, corruption detection, deadlock analysis
• System monitoring: Performance metrics, heap analysis, interrupt context tracking
• Robust error handling: Graceful handling of corrupted data and missing symbols

🚧 Planned Features

• FreeRTOS support: Full debugging capabilities for FreeRTOS
• Multi-core debugging: SMP and heterogeneous multi-core systems
• Performance profiling: Real-time performance analysis and bottleneck detection
• Additional RTOS: Zephyr, embOS, and other popular RTOS platforms

📦 Installation

Prerequisites

1. Python-enabled GDB: Verify with gdb --configuration that Python support is enabled

   • For ARM/RISC-V: Download from xpack
   • For other platforms: Build from source with ./configure --target="<target-triple>" --enable-targets=all --with-python
   • Reference: Installing GDB for ARM | Interrupt

2. Debug symbols: Ensure build your target includes debug symbols (-ggdb3 option)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd gdr

2. Add to your GDB initialization file (~/.gdbinit):

   source /path/to/gdr/gdr.py

3. Or load manually in GDB:

   (gdb) source /path/to/gdr/gdr.py

🎯 Usage

RT-Thread Debugging

After connecting to your RT-Thread target, then fetch symbols by loading the ELF file, then sourcing gdr.py, GDR automatically detects the RTOS and provides comprehensive debugging commands:

(gdb) target remote localhost:3333
(gdb) load <paht-to-elf-file>
(gdb) source /path/to/gdr/gdr.py
GDR: Initializing GDB Enhanced Features for RTOS...
GDR: Detecting RTOS...
GDR: RT-Thread debugging support enabled (version: 4.1.0)

System Information

(gdb) rtthread info
=== RT-Thread System Information ===
RTOS: RT-Thread
Version: 4.1.0
Capabilities:
  ✓ Threads
  ✓ Semaphores
  ✓ Mutexes
  ✓ Timers
  ...

Thread Analysis

# List all threads with stack usage
(gdb) rtthread threads
Name             State      Prio Stack Usage  Entry Point  Status
--------------------------------------------------------------------------------
main             RUNNING    10   23.4%        0x8001234    OK
idle             READY      31   12.1%        0x8005678    OK
timer            READY      4    45.2%        0x8009abc    WARN

# Detailed thread inspection
(gdb) rtthread thread main
=== Thread: main ===
Address: 0x20001000
State: RUNNING
Priority: 10
Stack Base: 0x20002000
Stack Size: 2048 bytes
Stack Usage: 23.4%
Stack Watermark: 31.2%
Entry Point: 0x8001234
...

Object Inspection

# List all kernel objects
(gdb) rtthread objects
# Or specific object types
(gdb) rtthread objects semaphores
(gdb) rtthread semaphores
(gdb) rtthread timers

System Monitoring

(gdb) rtthread system
=== RT-Thread System Monitor ===
Current Thread: main
Interrupt Nest Level: 0
System Tick: 12345678
Object Statistics:
  Threads: 5
  Semaphores: 3
  Mutexes: 2
  Timers: 4

Available Commands

Command	Description
rtthread info	Show RT-Thread system information and capabilities
rtthread threads	List all threads with stack analysis
rtthread thread <name>	Show detailed thread information
rtthread objects [type]	List kernel objects by type
rtthread semaphores	List semaphores with status
rtthread timers	List timers with callback information
rtthread system	Show system monitoring information
rtthread heap	Analyze heap usage (if available)

🏗️ Architecture

GDR follows a modular architecture with a single entry point:

gdr/
├── gdr.py          # 🎯 Main entry point (source this file)
├── gdr/            # Abstract RTOS interfaces and base classes
├── rtthread/       # RT-Thread specific implementation
├── freertos/       # FreeRTOS support (planned)
├── tools.py        # Utility functions for GDB operations
└── tests/          # Test suite

Key Principle: One file to rule them all - gdr.py contains the detection logic, command registration, and initialization. The modular components are automatically loaded as needed.

Key Components

• Core Abstractions: Platform-independent RTOS object interfaces
• RTOS Modules: Specific implementations for each RTOS
• Detector System: Automatic RTOS detection and validation
• Command Framework: Extensible GDB command system
• Error Handling: Robust error recovery and corruption detection

🧪 Development Status

• ✅ Core Framework: Complete with comprehensive abstractions
• ✅ RT-Thread Support: Production-ready with advanced features
• 🚧 Testing: Unit tests needed
• 🚧 Documentation: API docs and examples needed
• ❌ FreeRTOS: Not yet implemented
• ❌ CI/CD: Automated testing setup needed

See TASKS.md for detailed development status and roadmap.

🤝 Contributing

Contributions are welcome! Please see TASKS.md for current priorities and planned features.

Development Guidelines

1. Follow the existing modular architecture
2. Add comprehensive error handling
3. Include type hints and documentation
4. Test with multiple RTOS versions
5. Maintain compatibility with different GDB versions

📚 References

• GDB Python API
• GEF Project - Inspiration for GDB enhancement
• RT-Thread Documentation

🙏 Acknowledgements

Many implementation techniques in GDR are inspired by GEF. We're grateful to the GEF maintainers for their contributions to the GDB community and for providing valuable reference implementations.