314 lines
8.4 KiB
Markdown
314 lines
8.4 KiB
Markdown
# FastLED Symbol Analysis
|
|
|
|
This document describes the new generic symbol analysis functionality that works across all supported platforms including UNO, ESP32, and others.
|
|
|
|
## Overview
|
|
|
|
The symbol analysis tool provides comprehensive analysis of compiled ELF files to help identify optimization opportunities and understand binary size allocation. Unlike the previous ESP32-specific implementation, this tool:
|
|
|
|
- ✅ **Works on ALL platforms** (UNO, ESP32, Teensy, STM32, etc.)
|
|
- ✅ **Pulls ALL symbols** without filtering or classification
|
|
- ✅ **No FastLED-specific filtering** - analyzes everything
|
|
- ✅ **Generic and extensible** for any platform with build_info.json
|
|
|
|
## Quick Start
|
|
|
|
### Analyze a specific platform
|
|
|
|
```bash
|
|
cd ci
|
|
uv run symbol_analysis.py --board uno
|
|
uv run symbol_analysis.py --board esp32dev
|
|
```
|
|
|
|
### Run analysis on all available platforms
|
|
|
|
```bash
|
|
uv run demo_symbol_analysis.py
|
|
```
|
|
|
|
### Use in GitHub Actions
|
|
|
|
```bash
|
|
uv run symbol_analysis_runner.py --board uno --example Blink
|
|
```
|
|
|
|
## Files
|
|
|
|
- **`symbol_analysis.py`** - Main generic symbol analysis tool
|
|
- **`symbol_analysis_runner.py`** - GitHub Actions wrapper
|
|
- **`demo_symbol_analysis.py`** - Demonstration script for multiple platforms
|
|
- **`SYMBOL_ANALYSIS.md`** - This documentation file
|
|
|
|
## Example Output
|
|
|
|
### UNO Platform Results
|
|
|
|
```
|
|
================================================================================
|
|
UNO SYMBOL ANALYSIS REPORT
|
|
================================================================================
|
|
|
|
SUMMARY:
|
|
Total symbols: 51
|
|
Total symbol size: 3767 bytes (3.7 KB)
|
|
|
|
LARGEST SYMBOLS (all symbols, sorted by size):
|
|
1. 1204 bytes - ClocklessController<...>::showPixels(...)
|
|
2. 572 bytes - CFastLED::show(unsigned char) [clone .constprop.18]
|
|
3. 460 bytes - main
|
|
4. 204 bytes - CPixelLEDController<...>::show(...)
|
|
5. 168 bytes - CPixelLEDController<...>::showColor(...)
|
|
|
|
SYMBOL TYPE BREAKDOWN:
|
|
t: 19 symbols, 2710 bytes (2.6 KB)
|
|
T: 14 symbols, 904 bytes (0.9 KB)
|
|
b: 15 symbols, 89 bytes (0.1 KB)
|
|
d: 3 symbols, 64 bytes (0.1 KB)
|
|
```
|
|
|
|
### ESP32 Platform Results
|
|
|
|
```
|
|
================================================================================
|
|
ESP32DEV SYMBOL ANALYSIS REPORT
|
|
================================================================================
|
|
|
|
SUMMARY:
|
|
Total symbols: 2503
|
|
Total symbol size: 237092 bytes (231.5 KB)
|
|
|
|
LARGEST SYMBOLS (all symbols, sorted by size):
|
|
1. 12009 bytes - _vfprintf_r
|
|
2. 11813 bytes - _svfprintf_r
|
|
3. 8010 bytes - _vfiprintf_r
|
|
4. 7854 bytes - _svfiprintf_r
|
|
5. 4192 bytes - port_IntStack
|
|
|
|
SYMBOL TYPE BREAKDOWN:
|
|
T: 1240 symbols, 156230 bytes (152.6 KB)
|
|
t: 371 symbols, 45841 bytes (44.8 KB)
|
|
d: 475 symbols, 13032 bytes (12.7 KB)
|
|
D: 60 symbols, 9421 bytes (9.2 KB)
|
|
W: 126 symbols, 5209 bytes (5.1 KB)
|
|
```
|
|
|
|
### ESP32S3 Platform Results
|
|
|
|
```
|
|
================================================================================
|
|
ESP32S3 SYMBOL ANALYSIS REPORT
|
|
================================================================================
|
|
|
|
SUMMARY:
|
|
Total symbols: 2831
|
|
Total symbol size: 260710 bytes (254.6 KB)
|
|
|
|
LARGEST SYMBOLS (all symbols, sorted by size):
|
|
1. 11309 bytes - _vfprintf_r
|
|
2. 11118 bytes - _svfprintf_r
|
|
3. 7337 bytes - _svfiprintf_r
|
|
4. 7265 bytes - _vfiprintf_r
|
|
5. 4192 bytes - port_IntStack
|
|
6. 1164 bytes - printBeforeSetupInfo()
|
|
7. 828 bytes - fl::RmtController5::loadPixelData(PixelIterator&)
|
|
|
|
SYMBOL TYPE BREAKDOWN:
|
|
T: 1416 symbols, 172591 bytes (168.5 KB)
|
|
t: 429 symbols, 48854 bytes (47.7 KB)
|
|
d: 529 symbols, 14189 bytes (13.9 KB)
|
|
D: 72 symbols, 9831 bytes (9.6 KB)
|
|
W: 122 symbols, 5457 bytes (5.3 KB)
|
|
```
|
|
|
|
## Output Files
|
|
|
|
The tool generates JSON files with complete symbol data:
|
|
|
|
- `.build/{board}_symbol_analysis.json` - Complete analysis results
|
|
|
|
### JSON Structure
|
|
|
|
```json
|
|
{
|
|
"summary": {
|
|
"board": "uno",
|
|
"total_symbols": 51,
|
|
"total_size": 3767,
|
|
"largest_symbols": [...],
|
|
"type_breakdown": {...},
|
|
"dependencies": {...}
|
|
},
|
|
"all_symbols_sorted_by_size": [
|
|
{
|
|
"address": "00001240",
|
|
"size": 1204,
|
|
"type": "t",
|
|
"name": "_ZN19ClocklessController...",
|
|
"demangled_name": "ClocklessController<...>::showPixels(...)"
|
|
},
|
|
...
|
|
],
|
|
"dependencies": {
|
|
"module.cpp.o": ["symbol1", "symbol2", ...]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Supported Platforms
|
|
|
|
The tool automatically detects and works with any platform that has:
|
|
- A `build_info.json` file in `.build/{platform}/`
|
|
- Standard toolchain tools (nm, c++filt) in the build info aliases
|
|
|
|
Successfully tested platforms:
|
|
- ✅ **UNO** (AVR) - 51 symbols, 3.7 KB
|
|
- ✅ **ESP32DEV** (Xtensa) - 2503 symbols, 231.5 KB
|
|
- ✅ **ESP32S3** (Xtensa) - 2831 symbols, 254.6 KB
|
|
- ✅ **TEENSY31** (ARM Cortex-M4) - 238 symbols, 10.9 KB
|
|
- ✅ **TEENSYLC** (ARM Cortex-M0+) - 241 symbols, 9.1 KB
|
|
- ✅ **DIGIX** (ARM Cortex-M3) - 298 symbols, 17.9 KB
|
|
- ✅ **STM32** (ARM Cortex-M3) - 311 symbols, 15.6 KB
|
|
|
|
## Key Improvements
|
|
|
|
### From ESP32-specific to Generic
|
|
|
|
**Before (ESP32 only):**
|
|
```python
|
|
# Hard-coded ESP32 board detection
|
|
esp32_boards = ["esp32dev", "esp32", "esp32s2", ...]
|
|
|
|
# FastLED-specific filtering
|
|
if any(keyword in search_text for keyword in [
|
|
"fastled", "cfastled", "crgb", "hsv", ...]):
|
|
fastled_symbols.append(symbol_info)
|
|
```
|
|
|
|
**After (Generic):**
|
|
```python
|
|
# Auto-detect any platform with build_info.json
|
|
for item in build_dir.iterdir():
|
|
if item.is_dir() and (item / "build_info.json").exists():
|
|
available_boards.append((build_info_file, item.name))
|
|
|
|
# No filtering - analyze ALL symbols
|
|
symbols.append(symbol_info) # Everything included
|
|
```
|
|
|
|
### Symbol Analysis Improvements
|
|
|
|
1. **No Classification** - All symbols are included without filtering
|
|
2. **Complete Demangling** - All C++ symbols are properly demangled
|
|
3. **Platform Agnostic** - Works with any toolchain (AVR, ARM, Xtensa, etc.)
|
|
4. **Size-based Sorting** - All results sorted by symbol size for easy optimization targeting
|
|
|
|
## GitHub Actions Integration
|
|
|
|
The `symbol_analysis_runner.py` script provides GitHub Actions compatibility:
|
|
|
|
```yaml
|
|
- name: Run Symbol Analysis
|
|
run: python ci/symbol_analysis_runner.py --board uno --example Blink
|
|
```
|
|
|
|
This runner:
|
|
- Validates build_info.json exists
|
|
- Handles errors gracefully with `--skip-on-failure`
|
|
- Provides proper exit codes for CI/CD
|
|
|
|
## Migration from ESP32 Analysis
|
|
|
|
If you were using the old ESP32-specific analysis:
|
|
|
|
**Old command:**
|
|
```bash
|
|
cd ci/ci && python esp32_symbol_analysis.py
|
|
```
|
|
|
|
**New command:**
|
|
```bash
|
|
cd ci && uv run symbol_analysis.py --board esp32dev
|
|
```
|
|
|
|
The new tool provides all the same information plus:
|
|
- Support for more platforms
|
|
- ALL symbols instead of just FastLED ones
|
|
- Better error handling
|
|
- Cleaner output format
|
|
|
|
## Advanced Usage
|
|
|
|
### Analyzing Custom Platforms
|
|
|
|
To add support for a new platform:
|
|
|
|
1. Ensure the platform builds correctly with PlatformIO
|
|
2. Verify `build_info.json` is generated in `.build/{platform}/`
|
|
3. Run: `uv run symbol_analysis.py --board {platform}`
|
|
|
|
### Batch Analysis
|
|
|
|
```bash
|
|
# Analyze all available platforms
|
|
uv run demo_symbol_analysis.py
|
|
|
|
# Analyze specific platforms in sequence
|
|
for board in uno esp32dev teensy31; do
|
|
uv run symbol_analysis.py --board $board
|
|
done
|
|
```
|
|
|
|
### Integration with Build Systems
|
|
|
|
```python
|
|
# In your Python build script
|
|
from ci.ci.symbol_analysis import main as analyze_symbols
|
|
import sys
|
|
|
|
# Override arguments
|
|
sys.argv = ["symbol_analysis.py", "--board", "uno"]
|
|
analyze_symbols()
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **"build_info.json not found"**
|
|
- Solution: Compile the platform first: `uv run ci/ci-compile.py {board} --examples Blink`
|
|
|
|
2. **"KeyError: 'board_name'"**
|
|
- Solution: The board name in the directory doesn't match the key in build_info.json
|
|
- Check: `cat .build/{board}/build_info.json | jq 'keys'`
|
|
|
|
3. **"Tool not found"**
|
|
- Solution: The toolchain isn't installed or path is incorrect in build_info.json
|
|
|
|
### Debug Mode
|
|
|
|
To debug issues, run with verbose Python output:
|
|
```bash
|
|
uv run python -v symbol_analysis.py --board uno
|
|
```
|
|
|
|
## Contributing
|
|
|
|
When adding new features:
|
|
|
|
1. Maintain platform independence
|
|
2. Don't add filtering logic
|
|
3. Test on multiple platforms
|
|
4. Update this documentation
|
|
5. Add tests to verify functionality
|
|
|
|
## Performance
|
|
|
|
Platform analysis times (approximate):
|
|
- **UNO**: < 1 second (51 symbols)
|
|
- **Teensy**: < 2 seconds (238-241 symbols)
|
|
- **STM32**: < 3 seconds (311 symbols)
|
|
- **ESP32**: < 10 seconds (2503 symbols)
|
|
|
|
The tool scales well with symbol count and provides progress feedback during demangling.
|