> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 RAMParser 解析 RAM 转储

Linux RAM 转储解析器（RAMParser）是一款开源工具，用于解析 Qualcomm Linux 设备上的 RAM 转储。RAMParser 使用 Linux 内核符号文件（包括 vmlinux 和内核对象模块）处理 RAM 转储，并提取有用信息，例如进程堆栈、IRQ 和工作队列。

**注意**

RAMParser 工具仅针对 Windows 构建和验证。

## **前提条件**

* RAM 转储及对应的 `vmlinux` 文件。
* 软件镜像和脚本：
  * Windows PC
  * Python 3.7 或更高版本
    ```text theme={null}
    python -m pip install --trusted-host files.pythonhosted.org --trusted-host pypi.org --trusted-host pypi.python.org prettytable
    ```
    ```text theme={null}
    python -m pip install --trusted-host files.pythonhosted.org --trusted-host pypi.org --trusted-host pypi.python.org pyelftools
    ```
* Pyelftools 软件包：
  1. 从 [Github-Pyelftools](https://www.github.com/eliben/pyelftools) 下载 Pyelftools 软件包。
  2. 解压下载的文件，找到 `pyelftools-master>elftools` 目录。
  3. 将 elftools 目录复制到 `<installed Python path>\Lib\site-packages`。
* RAMParser 软件：从 [Git-Codelinaro](https://git.codelinaro.org/clo/la/platform/vendor/qcom-opensource/tools/-/tree/opensource-tools.lnx.1.0) 下载 RAMParser 软件。
  **注意**
  RAMParser 软件必须始终位于 Windows 主机的 C 盘上。
* C 盘（`C:\T32`）上安装 TRACE32 软件 2023.12 或更高版本。此项为可选。TRACE32 软件使用 RAMParser 输出文件将 RAM 转储加载到 TRACE32 模拟器中。

## **设置工具链**

RAMParser 需要访问 gdb 和 nm 工具。您可以通过以下方式之一指定 gdb 和 nm 工具的路径：

* 使用 `--gdb-path` 和 `--nm-path` 指定绝对路径
* 使用 `CROSS_COMPILE` 指定前缀
* 使用 `local_settings.py` 文件

<Note>
  不支持仅在系统路径中提供 `gdb` 或 `nm` 命令，因为工具名称的变体太多，无法直接调用。
</Note>

要使用 `local_settings.py` 文件设置工具链，请执行以下操作：

1. 在根目录中创建 `ramparser_utils\utils` 目录。
2. 从 [Arm GNU toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) 将工具链（aarch64-none-linux-gnu）下载到 `ramparser_utils\utils` 目录中。

**local\_settings.py**

RAMParser 会自动确定大多数设置。但是，某些设置与运行时环境相关，是独有的。您可以在 `local_settings.py` 文件中指定这些独有设置。由于 `local_settings.py` 是一个 Python 文件，它可以利用 Python 的特性。

**注意**

为了让 RAMParser 获取工具链实用程序的正确路径，请将 `local_settings.py` 文件添加到 `<root>/tools/linux-ramdump-parser-v2` 目录路径中。

`local_settings.py` 文件的格式为：

```text theme={null}
<setting name> = <string identifying the feature>
```

`local_settings.py` 文件支持以下功能：

**表：local\_settings.py 文件支持的功能**

|      **功能**      |            **描述**           |
| :--------------: | :-------------------------: |
|    `gdb_path`    |    用于 RAM 转储的 gdb 工具的绝对路径   |
|     `nm_path`    |    用于 RAM 转储的 nm 工具的绝对路径    |
|   `gdb64_path`   | 用于 RAM 转储的 64 位 gdb 工具的绝对路径 |
|    `nm64_path`   |  用于 RAM 转储的 64 位 nm 工具的绝对路径 |
|  `objdump_path`  |    用于 RAM 转储的对象转储工具的绝对路径    |
| `objdump64_path` |  用于 RAM 转储的 64 位对象转储工具的绝对路径 |

**示例：local\_settings.py**

> ```text theme={null}
> import parser_util,os,sys
> path = os.path.abspath(os.path.dirname(__file__))
> ramparser_utils_path = os.path.abspath(os.path.join(path, "../../ramparser_utils"))
> nm_path =  ramparser_utils_path + "\\utils\\arm-none-eabi-nm.exe"
> gdb_path = ramparser_utils_path + "\\utils\\arm-none-eabi-gdb.exe"
> objdump_path =  ramparser_utils_path + "\\utils\\objdump.exe"
> nm64_path = ramparser_utils_path + "\\utils\\aarch64-linux-gnu-nm.exe"
> gdb64_path = ramparser_utils_path + "\\utils\\mingw64\\bin\\gdb-multiarch.exe"
> objdump64_path = ramparser_utils_path + "\\utils\\all-objdump.exe"
> ```

## **RAMParser 命令**

* 要使用 RAMParser 解析转储，请在 Windows Shell 中运行以下命令：
  > ```text theme={null}
  > python ramparse.py --vmlinux <vmlinux path> --auto-dump <dump path> --force-hardware <hw name> <parser options>  --mod_path <symbol path> -o <output path>
  > ```
  >
  > * `<hw name>`：此字符串指定芯片组的硬件 ID。请参见下表并使用相应的值。
  >   | **芯片组** |  **硬件名称** |
  >   | :-----: | :-------: |
  >   | QCS6490 | `qcm6490` |
  >   | QCS5430 |           |
  >   | IQ-8275 | `qcs8300` |
  >   | IQ-9075 | `qcs9100` |
  >   |  IQ-615 |  `qcs615` |
  > * `python ramparse.py`：此文件用于调用 RAMParser。
  > * `mod_path`：指定此选项，将所有未剥离（unstripped）的内核模块复制到一个目录中，并将其作为 `--mod_path` 选项引用的符号路径。
  > * `<parser options>`：指定解析器选项以从 RAM 转储中提取特定数据。此外，您还可以在命令中传递子解析器选项以提取相关数据。例如，要提取 ftrace 信息，请传递 `--dump-ftrace` 及相关参数并运行以下命令：
  >   ```text theme={null}
  >   python <root>\tools\linux-ramdump-parser-v2\ramparse.py --vmlinux <vmlinux path> --auto-dump <dump path> --force-hardware <hw name> --dump-ftrace --ftrace-args=rwmmio --ftrace_buffer_size_kb 4096  --mod_path <symbol path> -o <output path>
  >   ```
  >   同样，要提取 kconfig 信息，请传递 `--print-kconfig`。有许多可用选项可以解析转储并将输出存储到目录中。
  > * 要查看所有可用命令和选项，请运行以下命令：
  >   > ```text theme={null}
  >   > python ramparse.py --help
  >   > ```

## **查看 RAMParser 日志**

RAMParser 会生成关于工作队列、进程状态和调用堆栈的大量数据。下表列出了 RAMParser 执行期间生成的重要文件。

**表：RAMParser 生成的文件**

|      **文件名**     |                **描述**                |
| :--------------: | :----------------------------------: |
|  `dmesg_TZ.txt`  |    此文件包含内核日志、运行队列、工作队列和 IRQ 统计信息。    |
|  `mem_stat.txt`  |            此文件提供系统内存的统计信息。           |
|   `memory.txt`   |                                      |
|    `tasks.txt`   |          此文件提供所有进程的内核空间调用堆栈。         |
| `devicetree.dtb` |          此文件是内核使用的设备树 blob。          |
| `launch_t32.bat` | 此文件用于启动 TRACE32 模拟器启动器文件，以加载 RAM 转储。 |
|  `timerlist.txt` |            此文件提供活动定时器的列表。            |

下图显示了 RAMParser 生成的示例数据：

<Frame caption="图：运行队列（dmesg\_TZ.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/Runqueue.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=ea8944ad31cb7034570920dbdba86ae0" alt="" width="673" height="904" data-path="System/Debug-Subsystem/media/qli-support/Runqueue.png" />
</Frame>

<Frame caption="图：IRQ 状态（dmesg\_TZ.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/IRQstate.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=02414bd5574f4b105ddea1b22ca79a75" alt="" width="1653" height="883" data-path="System/Debug-Subsystem/media/qli-support/IRQstate.png" />
</Frame>

<Frame caption="图：内核崩溃示例（dmesg\_TZ.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/sample-kernel-crash.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=5df9d4d35696372c32483a1f52cba6e3" alt="" width="797" height="710" data-path="System/Debug-Subsystem/media/qli-support/sample-kernel-crash.png" />
</Frame>

<Frame caption="图：各核心的定时器列表（timerlist.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/timer-list-cores.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=a9732789f0ae26130245bc584bbcd548" alt="" width="1122" height="869" data-path="System/Debug-Subsystem/media/qli-support/timer-list-cores.png" />
</Frame>

<Frame caption="图：工作队列（dmesg\_TZ.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/workqueue.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=266d7eaaa701feebc7e42ec7459ded84" alt="" width="1423" height="939" data-path="System/Debug-Subsystem/media/qli-support/workqueue.png" />
</Frame>

<Frame caption="图：内存统计信息（mem\_stat.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/memory-stats.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=9afffd1b5429432be09c688f7bb3b8c8" alt="" width="633" height="462" data-path="System/Debug-Subsystem/media/qli-support/memory-stats.png" />
</Frame>

<Frame caption="图：CPU 频率（dmesg\_TZ.txt）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/CPU-freq-info.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=60e3cfaadde776fb225456a1ef590f84" alt="" width="872" height="421" data-path="System/Debug-Subsystem/media/qli-support/CPU-freq-info.png" />
</Frame>

<Frame caption="图：TRACE32 模拟器启动器（launch\_t32.bat）">
  <img src="https://mintcdn.com/qualcomm-prod/rpHTx_a6zriKQll9/System/Debug-Subsystem/media/qli-support/TRACE32-simulator-launcher.png?fit=max&auto=format&n=rpHTx_a6zriKQll9&q=85&s=f82b7cb6d71ff20fd6f4a8f8a56e901d" alt="" width="614" height="376" data-path="System/Debug-Subsystem/media/qli-support/TRACE32-simulator-launcher.png" />
</Frame>