memory-analysis

name	memory-analysis
description	当需要解析 .map 文件或 ELF 获取固件内存使用报告、符号大小排名或版本对比时使用。

固件内存分析

适用场景

• 构建完成后需要了解固件的 Flash/RAM 使用情况。
• 需要找出占用空间最大的函数或变量。
• 需要对比两次构建的内存变化，追踪代码膨胀。
• 需要确认固件是否即将超出芯片内存限制。
• 需要解析链接脚本获取芯片 Flash/RAM 总容量。

必要输入

• .map 文件路径（GCC/ARM 链接器生成），或 ELF 文件路径。
• 可选的链接脚本路径（用于计算使用率百分比）。
• 可选的告警阈值和 Top-N 符号数量。

自动探测

• --scan 模式自动搜索构建目录中的 .map 和 ELF 文件。
• 解析 .map 文件中的 Memory Configuration 块获取 FLASH/RAM 总容量。
• 若提供链接脚本，从 MEMORY {} 块解析容量信息。
• 自动检测 arm-none-eabi-size 和 arm-none-eabi-readelf 可用性。

执行步骤

1. 先阅读 references/usage.md，确认本次是环境探测、构建目录扫描，还是执行分析。
2. 若不确定工具是否可用，先运行 scripts/memory_analyzer.py 的 --detect 模式确认。
3. 使用 --scan <build_dir> 自动查找可分析的文件。
4. 使用 --map-file 或 --elf 执行内存分析。
5. 可选使用 --linker-script 获取总容量并计算使用率。
6. 使用 --top <N> 查看占用最大的符号。
7. 使用 --compare 对比两个 .map 文件的差异。

失败分流

• 当 arm-none-eabi-size 或 arm-none-eabi-readelf 不可用且需要 ELF 分析时，返回 environment-missing。
• 当指定的 .map 或 ELF 文件不存在时，返回 artifact-missing。
• 当 .map 文件格式无法识别或解析失败时，返回 project-config-error。
• 当内存使用率超过告警阈值时，在成功结果中附带告警信息。

平台说明

• .map 文件解析使用纯正则，无需外部工具，全平台可用。
• ELF 分析需要 arm-none-eabi-size，通常随交叉编译工具链安装。
• 链接脚本解析使用纯正则，支持 GCC LD 格式。

输出约定

• 输出各 section（.text, .rodata, .data, .bss）的大小和地址。
• 输出 Flash 使用量（.text + .rodata + .data）和 RAM 使用量（.data + .bss）。
• 若有总容量信息，输出使用率百分比和告警状态。
• 输出按大小排序的 Top-N 符号列表。
• 对比模式输出各 section 和符号的增减变化。

交接关系

• 当内存即将溢出需要优化时，建议用户审查 Top-N 大符号。
• 当需要定位具体函数在代码中的位置时，可配合 IDE 或 grep 使用。