# MemBrowse
[](https://badge.fury.io/py/membrowse)
[](https://pypi.org/project/membrowse/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://pepy.tech/project/membrowse)
A tool for analyzing memory footprint in embedded firmware. MemBrowse extracts detailed memory information from ELF files and linker scripts, providing symbol-level analysis with source file mapping for any embedded architecture. Use it standalone for local analysis or integrate with [MemBrowse](https://membrowse.com) for historical analysis and CI integration.
## Features
- **Architecture Agnostic**: Works with any embedded architecture by relying on the DWARF debug format
- **Source File Mapping**: Symbols are automatically mapped to their definition source files using DWARF debug information
- **Memory Region Extraction**: Memory region capacity and layout are extracted from GNU LD linker scripts
- **Intelligent Linker Script Parsing**: Handles complex GNU LD syntax with automatic architecture detection and expression evaluation
- **Cloud Integration**: Upload reports to [MemBrowse](https://membrowse.com) for historical tracking
## Installation
### From PyPI (Recommended)
```bash
pip install membrowse
```
### From GitHub
```bash
# Install directly from GitHub
pip install git+https://github.com/membrowse/membrowse-action.git
```
### For Development
```bash
# Clone and install in editable mode
git clone https://github.com/membrowse/membrowse-action.git
cd membrowse-action
pip install -e .
```
### Verify Installation
After installation, the `membrowse` command will be available:
```bash
membrowse --help # Show main help
membrowse report --help # Help for report subcommand
membrowse onboard --help # Help for onboard subcommand
```
## Quick Start
### Analyze Your Firmware Locally
The simplest way to analyze your firmware (local mode - no upload):
```bash
# Generate a memory report (prints JSON to stdout)
membrowse report \
build/firmware.elf \
"src/linker.ld src/memory.ld"
# With verbose output to see progress
membrowse report \
build/firmware.elf \
"src/linker.ld src/memory.ld" \
--verbose
```
This generates a JSON report with detailed memory analysis and prints it to stdout. Use `--verbose` to see progress messages.
### Upload Reports to MemBrowse Platform
```bash
# Upload mode - uploads report to MemBrowse platform (https://membrowse.com)
membrowse report \
build/firmware.elf \
"src/linker.ld" \
--upload \
--target-name esp32 \
--api-key your-membrowse-api-key
```
### Analyze Historical Commits (Onboarding)
Analyzes memory footprints across multiple commits and uploads them to [MemBrowse](https://membrowse.com):
```bash
# Analyze and upload the last 50 commits
membrowse onboard \
50 \
"make clean && make all" \
build/firmware.elf \
"STM32F746ZGTx_FLASH.ld" \
stm32f4 \
your-membrowse-api-key
```
## CI/CD Integration
### GitHub Actions
MemBrowse provides two composite GitHub Actions for seamless integration.
#### PR/Push Analysis
```yaml
name: Memory Analysis
on: [push, pull_request]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build firmware
run: make all
- name: Analyze memory
uses: membrowse/membrowse-action/pr-action@main
with:
elf: build/firmware.elf
ld: "src/linker.ld"
target_name: stm32f4
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
```
#### Historical Onboarding
```yaml
name: Onboard to MemBrowse
on: workflow_dispatch
jobs:
onboard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Historical analysis
uses: membrowse/membrowse-action/onboard-action@main
with:
num_commits: 50
build_script: "make clean && make"
elf: build/firmware.elf
ld: "linker.ld"
target_name: my-target
api_key: ${{ secrets.MEMBROWSE_API_KEY }}
```
### Other CI/CD
For other CI systems:
```bash
# Install MemBrowse
pip install membrowse
# Build your firmware
make all
# Analyze and upload memory report
membrowse report \
build/firmware.elf \
"linker.ld" \
--upload \
--target-name my-target \
--api-key your-membrowse-api-key
```
## Platform Support
MemBrowse is **platform agnostic** and works with any embedded architecture that produces ELF files and uses GNU LD linker scripts. The tool automatically detects the target architecture and applies appropriate parsing strategies for optimal results.
## Output Format
MemBrowse generates comprehensive JSON reports:
```json
{
"memory_regions": {
"FLASH": {
"address": "0x08000000",
"size": 524288,
"used": 245760,
"utilization": 46.9,
"sections": [".text", ".rodata"],
"symbols": [...]
},
"RAM": {
"address": "0x20000000",
"size": 131072,
"used": 12345,
"utilization": 9.4,
"sections": [".data", ".bss"],
"symbols": [...]
}
},
"symbols": [
{
"name": "main",
"size": 234,
"type": "FUNC",
"address": "0x08001234",
"source_file": "src/main.c",
"region": "FLASH"
}
],
"architecture": "arm",
"sections": [...],
"compilation_units": [...]
}
```
## License
See [LICENSE](LICENSE) file for details.
## Support
- **Issues**: https://github.com/membrowse/membrowse-action/issues
- **Documentation**: This README and inline code documentation
- **MemBrowse Support**: support@membrowse.com
Raw data
{
"_id": null,
"home_page": "https://membrowse.com",
"name": "membrowse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "MemBrowse <support@membrowse.com>",
"keywords": "embedded, firmware, memory, analysis, elf, linker, dwarf, footprint, stm32, esp32, arm, risc-v",
"author": "MemBrowse",
"author_email": "MemBrowse <support@membrowse.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/9a/a7f7fe2669869dc13b796036caef9318a58841f0a0456627b14ed9a2dbca/membrowse-0.0.1.tar.gz",
"platform": null,
"description": "# MemBrowse\n\n[](https://badge.fury.io/py/membrowse)\n[](https://pypi.org/project/membrowse/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://pepy.tech/project/membrowse)\n\nA tool for analyzing memory footprint in embedded firmware. MemBrowse extracts detailed memory information from ELF files and linker scripts, providing symbol-level analysis with source file mapping for any embedded architecture. Use it standalone for local analysis or integrate with [MemBrowse](https://membrowse.com) for historical analysis and CI integration.\n\n\n## Features\n\n- **Architecture Agnostic**: Works with any embedded architecture by relying on the DWARF debug format\n- **Source File Mapping**: Symbols are automatically mapped to their definition source files using DWARF debug information\n- **Memory Region Extraction**: Memory region capacity and layout are extracted from GNU LD linker scripts\n- **Intelligent Linker Script Parsing**: Handles complex GNU LD syntax with automatic architecture detection and expression evaluation\n- **Cloud Integration**: Upload reports to [MemBrowse](https://membrowse.com) for historical tracking\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install membrowse\n```\n\n### From GitHub\n\n```bash\n# Install directly from GitHub\npip install git+https://github.com/membrowse/membrowse-action.git\n```\n\n### For Development\n\n```bash\n# Clone and install in editable mode\ngit clone https://github.com/membrowse/membrowse-action.git\ncd membrowse-action\npip install -e .\n```\n\n### Verify Installation\n\nAfter installation, the `membrowse` command will be available:\n\n```bash\nmembrowse --help # Show main help\nmembrowse report --help # Help for report subcommand\nmembrowse onboard --help # Help for onboard subcommand\n```\n\n## Quick Start\n\n### Analyze Your Firmware Locally\n\nThe simplest way to analyze your firmware (local mode - no upload):\n\n```bash\n# Generate a memory report (prints JSON to stdout)\nmembrowse report \\\n build/firmware.elf \\\n \"src/linker.ld src/memory.ld\"\n\n# With verbose output to see progress\nmembrowse report \\\n build/firmware.elf \\\n \"src/linker.ld src/memory.ld\" \\\n --verbose\n```\n\nThis generates a JSON report with detailed memory analysis and prints it to stdout. Use `--verbose` to see progress messages.\n\n### Upload Reports to MemBrowse Platform\n\n```bash\n# Upload mode - uploads report to MemBrowse platform (https://membrowse.com)\nmembrowse report \\\n build/firmware.elf \\\n \"src/linker.ld\" \\\n --upload \\\n --target-name esp32 \\\n --api-key your-membrowse-api-key\n```\n\n### Analyze Historical Commits (Onboarding)\n\nAnalyzes memory footprints across multiple commits and uploads them to [MemBrowse](https://membrowse.com):\n\n```bash\n# Analyze and upload the last 50 commits\nmembrowse onboard \\\n 50 \\\n \"make clean && make all\" \\\n build/firmware.elf \\\n \"STM32F746ZGTx_FLASH.ld\" \\\n stm32f4 \\\n your-membrowse-api-key\n```\n\n\n## CI/CD Integration\n\n### GitHub Actions\n\nMemBrowse provides two composite GitHub Actions for seamless integration.\n\n#### PR/Push Analysis\n\n```yaml\nname: Memory Analysis\non: [push, pull_request]\n\njobs:\n analyze:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n\n - name: Build firmware\n run: make all\n\n - name: Analyze memory\n uses: membrowse/membrowse-action/pr-action@main\n with:\n elf: build/firmware.elf\n ld: \"src/linker.ld\"\n target_name: stm32f4\n api_key: ${{ secrets.MEMBROWSE_API_KEY }}\n```\n\n#### Historical Onboarding\n\n```yaml\nname: Onboard to MemBrowse\non: workflow_dispatch\n\njobs:\n onboard:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n\n - name: Historical analysis\n uses: membrowse/membrowse-action/onboard-action@main\n with:\n num_commits: 50\n build_script: \"make clean && make\"\n elf: build/firmware.elf\n ld: \"linker.ld\"\n target_name: my-target\n api_key: ${{ secrets.MEMBROWSE_API_KEY }}\n```\n\n### Other CI/CD\n\nFor other CI systems:\n\n```bash\n# Install MemBrowse\npip install membrowse\n\n# Build your firmware\nmake all\n\n# Analyze and upload memory report\nmembrowse report \\\n build/firmware.elf \\\n \"linker.ld\" \\\n --upload \\\n --target-name my-target \\\n --api-key your-membrowse-api-key\n```\n\n## Platform Support\n\nMemBrowse is **platform agnostic** and works with any embedded architecture that produces ELF files and uses GNU LD linker scripts. The tool automatically detects the target architecture and applies appropriate parsing strategies for optimal results.\n\n## Output Format\n\nMemBrowse generates comprehensive JSON reports:\n\n```json\n{\n \"memory_regions\": {\n \"FLASH\": {\n \"address\": \"0x08000000\",\n \"size\": 524288,\n \"used\": 245760,\n \"utilization\": 46.9,\n \"sections\": [\".text\", \".rodata\"],\n \"symbols\": [...]\n },\n \"RAM\": {\n \"address\": \"0x20000000\",\n \"size\": 131072,\n \"used\": 12345,\n \"utilization\": 9.4,\n \"sections\": [\".data\", \".bss\"],\n \"symbols\": [...]\n }\n },\n \"symbols\": [\n {\n \"name\": \"main\",\n \"size\": 234,\n \"type\": \"FUNC\",\n \"address\": \"0x08001234\",\n \"source_file\": \"src/main.c\",\n \"region\": \"FLASH\"\n }\n ],\n \"architecture\": \"arm\",\n \"sections\": [...],\n \"compilation_units\": [...]\n}\n```\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: https://github.com/membrowse/membrowse-action/issues\n- **Documentation**: This README and inline code documentation\n- **MemBrowse Support**: support@membrowse.com\n",
"bugtrack_url": null,
"license": null,
"summary": "Memory footprint analysis tools for embedded firmware",
"version": "0.0.1",
"project_urls": {
"Changelog": "https://github.com/membrowse/membrowse-action/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/membrowse/membrowse-action#readme",
"Homepage": "https://membrowse.com",
"Issues": "https://github.com/membrowse/membrowse-action/issues",
"Repository": "https://github.com/membrowse/membrowse-action"
},
"split_keywords": [
"embedded",
" firmware",
" memory",
" analysis",
" elf",
" linker",
" dwarf",
" footprint",
" stm32",
" esp32",
" arm",
" risc-v"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9c460c8ed0708e9208605aeb258009eaf5ff924fe1a717b1b9f56c0d16b73785",
"md5": "7ae4c767fd8f2c74a864568119b4d832",
"sha256": "0ba9492149db096ec95499ff6db1c1ad7656c1cc0366cc85064d3dc6bada166e"
},
"downloads": -1,
"filename": "membrowse-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ae4c767fd8f2c74a864568119b4d832",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 64050,
"upload_time": "2025-10-24T15:18:55",
"upload_time_iso_8601": "2025-10-24T15:18:55.211727Z",
"url": "https://files.pythonhosted.org/packages/9c/46/0c8ed0708e9208605aeb258009eaf5ff924fe1a717b1b9f56c0d16b73785/membrowse-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c89aa7f7fe2669869dc13b796036caef9318a58841f0a0456627b14ed9a2dbca",
"md5": "9c694ea3c654b905324a69460f5d1541",
"sha256": "def15317f619a8a52455cf036fb8e371044555fc175eca5dfc500830f1b8d5a8"
},
"downloads": -1,
"filename": "membrowse-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9c694ea3c654b905324a69460f5d1541",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 94256,
"upload_time": "2025-10-24T15:18:56",
"upload_time_iso_8601": "2025-10-24T15:18:56.377619Z",
"url": "https://files.pythonhosted.org/packages/c8/9a/a7f7fe2669869dc13b796036caef9318a58841f0a0456627b14ed9a2dbca/membrowse-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 15:18:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "membrowse",
"github_project": "membrowse-action",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "membrowse"
}
JSON
