Add Memory Map Visualization Tool for Marlin Firmware

[ellensp]

Description

Memory Map Visualization Tool for Marlin Firmware

Overview

This PR introduces a comprehensive memory analysis and visualization tool for Marlin firmware builds. The visualize_memory_map.py script generates interactive HTML reports that provide detailed insights into Flash and RAM memory usage across different firmware modules.

Key Features

🎨 Interactive Visual Memory Map

• Disk-defragmentation style visualization - Visual representation of memory layout showing how Flash and RAM are utilized
• Color-coded modules - 14 distinct categories (UBL, Planner, Stepper, Temperature, Motion, GCode, LCD/UI, Probe, etc.)
• Hover tooltips - Detailed information about each memory segment including symbol name, size, and address
• Multiple zoom levels - 1x, 2x, 4x, and 8x zoom for detailed inspection
• Responsive design - Adapts to different screen sizes with flexible layout

📊 Comprehensive Statistics

• Memory usage summary - Total RAM and Flash usage with percentages
• Module breakdown - Per-module memory consumption
• Symbol count - Total number of symbols analyzed

📋 Data Export Options

• CSV Export (--csv) - Generates flash.csv and ram.csv files with detailed symbol information
• HTML Tables (--list) - Interactive sortable tables with address, size, percentage, and symbol name
• Sortable columns - Click column headers to sort by address, size, percentage, or name (ascending/descending)

🔧 Multi-Architecture Support

• AVR (ATmega2560, ATmega1280, etc.)
• ARM/STM32 (STM32F1, STM32F4, STM32F7, etc.)
• Automatic detection - Reads ELF header to determine architecture
• Cross-platform - Works on Linux, macOS, and Windows (no external dependencies beyond Python)

🔍 Advanced Analysis

• Pattern conflict detection (--warn-conflicts) - Identifies overlapping module categorization patterns
• Special symbol tracking - Detects and highlights vector tables (g_pfnVectors on ARM)
• Address normalization - Properly handles ARM's absolute addressing (0x08000000 for Flash, 0x20000000 for RAM)

Usage Examples

Basic Usage

# AVR (e.g., MEGA2560)
python3 buildroot/bin/visualize_memory_map.py .pio/build/mega2560/firmware.elf map.html

# STM32 with explicit memory sizes
python3 buildroot/bin/visualize_memory_map.py .pio/build/STM32F103RE_creality/firmware.elf \
    stm32_map.html --flash 512KB --ram 20KB

# With sortable data tables
python3 buildroot/bin/visualize_memory_map.py firmware.elf map.html --list

# Generate CSV files for spreadsheet analysis
python3 buildroot/bin/visualize_memory_map.py firmware.elf map.html --csv

# Check for pattern conflicts during development
python3 buildroot/bin/visualize_memory_map.py firmware.elf map.html --warn-conflicts

Command-Line Options

positional arguments:
  elf_file              Path to ELF file to analyze
  output_file           Output HTML file (default: memory_map.html)

optional arguments:
  --flash SIZE          Flash memory size (e.g., 512KB, 256KB, 262144)
                        Default: 256KB for AVR, 512KB for ARM
  --ram SIZE            RAM size (e.g., 20KB, 8KB, 8192)
                        Default: 8KB for AVR, 20KB for ARM
  --arch {avr,arm,auto} Architecture (default: auto-detect from ELF)
  --warn-conflicts      Show pattern matching conflicts in module categorization
  --csv                 Generate flash.csv and ram.csv files
  --list                Add sortable data tables below visualization

Module Categories

The tool categorizes symbols into 14 functional modules with distinct colors:

Module	Color	Examples
UBL	Purple	Unified Bed Leveling
Planner	Blue	Motion planning, trajectory
Stepper	Green	Stepper motor control
Temperature	Red	Hotend/bed temperature management
FT_Motion	Pink	Fixed-Time Motion (separate from Motion)
Motion	Teal	General motion control
GCode	Yellow	G-code parsing and execution
LCD/UI	Orange	Display and user interface
Probe	Magenta	Z-probe, bed leveling sensors
Endstops	Brown	Endstop handling
Serial	Cyan	Serial communication
Settings	Lime	EEPROM, configuration storage
Core	Gray	Core firmware, main loop, startup
Other	Light Gray	Uncategorized symbols

Technical Details

Architecture Detection

• Reads ELF header bytes 18-19 (e_machine field)
• 0x53 = AVR, 0x28 = ARM
• Falls back to AVR if detection fails

Tool Discovery

• Automatically searches for avr-nm or arm-none-eabi-nm in PlatformIO directories
• Searches ~/.platformio/packages/toolchain-*/bin/
• Falls back to system PATH

Memory Categorization

• Flash sections: .text, .rodata, .data, .init, .fini
• RAM sections: .data, .bss, .noinit
• Size calculation includes both symbol size and gaps between symbols

Benefits

1. Optimization Insights - Quickly identify which modules consume the most memory
2. Debugging Aid - Visual representation helps understand memory layout issues
3. Build Validation - Ensure critical modules are properly sized
4. Documentation - Share memory reports with team members or users
5. Regression Detection - Compare builds to track memory usage changes
6. Module Analysis - Sort and filter data to focus on specific areas

Files

• buildroot/share/scripts/visualize_memory_map.py - Main visualization script
• Generated output: memory_map.html - Standalone HTML file (no external dependencies)
• Optional CSV: flash.csv, ram.csv - Spreadsheet-compatible data

Screenshots

Note: This tool is for development and analysis only. It does not modify firmware or affect runtime behavior.

Requirements

the firmware .elf file

[ThomasToka]

Great script.

I have patched it so it works on windows also. my heatmap seems to miss some details. i will have a look in this also in the next days.
stm32_map.html
visualize_memory_map.py

[ellensp]

@ThomasToka if you add --csv it will create csv files and you can lookup what is in that memory/flash location

[oliof]

Overall a very helpful tool!

There are some false matches -- std library calls with double in the signature match UBL.

I also did add some new modules (USB, Neopixel), but it seems that the pattern matching priority is not working as described (or I misunderstand the accompanying comment). I think that patterns lower in the list are preferred to those higher in the list. Is that correct?