# Zephyr 嵌入式系统内存与数据结构优化工具链实战指南
## 摘要
本文介绍 Zephyr 项目中用于分析 RAM/ROM 占用、发现数据对齐空洞及生成堆栈使用报告的工具链。内容基于 2026 年 11 月 3 日采集的官方文档资料，涵盖 ram_report、rom_report、pahole、puncover 等构建目标的使用方法、输出解读及配置选项。
## 内存与代码占用分析工具
Zephyr 构建系统提供多个目标以查看和分析生成的镜像中的 RAM、ROM 及堆栈使用情况。这些工具运行在最终镜像上，提供符号和代码在 RAM 与 ROM 中的大小信息。部分工具依据符号的物理组织结构组织输出；对于无法映射到具体文件的符号或缺少元数据的符号，报告会使用特定容器分组：
- **Hidden**：列出所有处理过的符号，但未找到匹配的映射文件。可能原因包括文件未添加到元数据文件、文件为空或符号未定义。
- **No paths**：列出具有相对路径的处理符号，无法将其放置在报告的树结构中的绝对路径下。工具能获取函数名称，但无法确定其来源。
### ram_report 与 rom_report
`ram_report` 目标以表格形式列出所有编译对象及其 RAM 占用情况，包括每个符号的字节数和所占百分比。数据按对象在文件系统中的位置及包含符号的文件进行分组。
使用 `west` 命令示例：
```bash
west build -b reel_board samples/hello_world
west build -t ram_report
```
使用 CMake 和 Ninja 命令示例：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild ram_report
```
`rom_report` 目标类似，但以表格形式列出所有编译对象及其 ROM 占用情况。
使用 `west` 命令示例：
```bash
west build -b reel_board samples/hello_world
west build -t rom_report
```
使用 CMake 和 Ninja 命令示例：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild rom_report
```
输出中类似 `gap` 的条目表示二进制文件中未定义符号的区域，可能对应填充、只读数据或其他编译器未输出符号的区域。
### ram_plot 与 rom_plot
这两个目标生成内存使用报告的太阳burst 图表，作为可视化表示。用户可以点击段以导航目录结构，悬停于段上获取更多详细信息。运行这些目标会先生成 CLI 报告，然后打开浏览器窗口。
使用 `west` 命令示例：
```bash
west build -b reel_board samples/hello_world
west build -t ram_plot
```
使用 CMake 和 Ninja 命令示例：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild ram_plot
```
ROM 使用报告类似。
### puncover 与堆栈分析
`puncover` 目标使用第三方工具 puncover（位于 https://github.com/HBehrens/puncover）。构建此目标时，会启动本地 Web 服务器，允许打开 Web 客户端并浏览文件，查看其 ROM、RAM 和堆栈使用情况。
使用前需安装 puncover Python 模块：
```bash
pip3 install --user puncover
```
使用 `west` 命令示例：
```bash
west build -b reel_board samples/hello_world
west build -t puncover
```
使用 CMake 和 Ninja 命令示例：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild puncover
```
默认情况下，puncover 目标在 localhost:5000 启动本地 Web 服务器。可通过设置环境变量 `PUNCOVER_HOST` 和 `PUNCOVER_PORT` 更改主机 IP 和端口。
要在交互式 Web 应用中查看最坏情况堆栈使用分析，需启用 `CONFIG_STACK_USAGE`：
```bash
west build -b reel_board samples/hello_world -- -DCONFIG_STACK_USAGE=y -DCONFIG_CALLGRAPH_INFO=y
west build -t puncover
```
若要以 JSON 文件格式获取最坏情况堆栈使用报告，而不启动 Web 应用，可添加选项 `--generate-report --non-interactive --report-type json`。还可通过添加每个感兴趣函数作为参数（形式为 `--report-max-static-stack-usage FUNCTION_NAME:::MAXIMAL_STACK_SIZE`）导出特定函数的报告。
示例：
```bash
west build -b reel_board samples/hello_world -- -DCONFIG_STACK_USAGE=y -DCONFIG_CALLGRAPH_INFO=y -DEXTRA_PUNCOVER_ARGS="--generate-report;--non-interactive;--report-type;json;--report-max-static-stack-usage;log_process_thread_func:::832;--report-max-static-stack-usage;shell_thread:::4160;--report-max-static-stack-usage;bg_thread_main:::2112;--report-max-static-stack-usage;work_queue_main:::1088;--report-filename;$PWD/report"
west build -t puncover
```
所有参数也可放入 YAML 配置文件中以便维护：
```yaml
elf_file: ~/zephyrproject/zephyr/samples/net/mqtt_publisher/build/zephyr/zephyr.elf
gcc-tools-base: ~/zephyr-sdk-1.0.1/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-
src_root: ~/zephyrproject/zephyr
build_dir: ~/zephyrproject/zephyr/samples/net/mqtt_publisher/build
generate-report: true
non-interactive: true
report-type: json
report-max-static-stack-usage:
- log_process_thread_func:::832
- shell_thread:::4160
- bg_thread_main:::2112
- work_queue_main:::1088
- mgmt_event_work_handler:::896
```
使用 `west` 命令示例：
```bash
west build -b reel_board samples/hello_world -- -DCONFIG_STACK_USAGE=y -DCONFIG_CALLGRAPH_INFO=y -DEXTRA_PUNCOVER_ARGS="-c puncover_config.yaml"
west build -t puncover
```
## 数据结构分析工具
### pahole
`pahole`（Poke-a-hole）是对象文件分析工具，用于查找数据结构的大小以及因编译器将数据元素与 CPU 字大小对齐而产生的空洞。
使用前需安装 `pahole`。可从 https://git.kernel.org/pub/scm/devel/pahole/pahole.git 获取，或在 Fedora 和 Ubuntu 中通过 `dwarves` 包安装：
```bash
sudo apt-get install dwarves
```
或使用 Fedora：
```bash
sudo dnf install dwarves
```
安装后，使用 `pahole` 目标与板卡：
```bash
west build -b reel_board samples/hello_world
west build -t pahole
```
或使用 CMake 和 Ninja：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild pahole
```
`pahole` 会在控制台生成类似输出，显示数据结构及其对齐情况。
## 综合仪表板
HTML 仪表板可整合各种工具输出和工件到一个简单视图。除构建结果的基本摘要外，还包括：
- 完整内存报告（RAM、ROM）的钻取表格形式及图表（如 footprint、ram_plot、rom_plot 构建目标）。
- Kconfig 符号值和来源（如 traceconfig 构建目标）。
- 初始化级别与函数名称，并报告 sys-init 与设备树之间的任何优先级问题（如 initlevels 构建目标）。
- 可导航的设备树视图，包含属性值及任何绑定详情。
使用 `dashboard` 目标与板卡：
```bash
west build -b reel_board samples/hello_world
west build -t dashboard
```
或使用 CMake 和 Ninja：
```bash
cmake -Bbuild -GNinja -DBOARD=reel_board samples/hello_world
ninja -Cbuild dashboard
```
这将生成输出文件 `build/dashboard/index.html` 并在默认浏览器中打开。
## 结语
Zephyr 提供的优化工具链为嵌入式系统开发者提供了全面的内存与数据结构分析能力。通过合理使用这些工具，可以有效识别资源占用瓶颈、优化代码布局并提升系统性能。