initial commit
This commit is contained in:
313
libraries/FastLED/ci/SYMBOL_ANALYSIS.md
Normal file
313
libraries/FastLED/ci/SYMBOL_ANALYSIS.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user