> ## 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.

# Parse RAM dumps using RAMParser

Linux RAM dump parser (RAMParser) is an open-source tool that parses RAM dumps on Qualcomm Linux devices. The RAMParser processes the RAM dump using the Linux kernel symbol file, which includes vmlinux and kernel object modules, and extracts useful information such as process stacks, IRQ, and work queues.

**Note**

The RAMParser tool is built and verified for Windows only.

## **Prerequisites**

* RAM dump and the corresponding `vmlinux` file.
* Software images and scripts:
  * Windows PC
  * Python 3.7 or a later version
    ```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 package:
  1. Download Pyelftools package from [Github-Pyelftools](https://www.github.com/eliben/pyelftools).
  2. Unzip the downloaded file and look for `pyelftools-master>elftools` directory.
  3. Copy elftools directory to `<installed Python path>\Lib\site-packages`.
* RAMParser software: Download the RAMParser software from [Git-Codelinaro](https://git.codelinaro.org/clo/la/platform/vendor/qcom-opensource/tools/-/tree/opensource-tools.lnx.1.0).
  **Note**
  The RAMParser software must always be present in the C drive on a Windows host computer.
* TRACE32 software 2023.12 or a later version on C drive (`C:\T32`). This is optional. The TRACE32 software loads the RAM dump in the TRACE32 simulator using the RAMParser output files.

## **Set up toolchains**

The RAMParser requires access to gdb and nm tools. You can specify the paths to the gdb and nm tools in one of the following ways:

* Using `--gdb-path` and `--nm-path` to specify the absolute path
* Using `CROSS_COMPILE` to specify the prefix
* Using `local_settings.py` file

<Note>
  Availability of only `gdb` or `nm` commands in the system path isn't supported because there are too many variations in the tool names to invoke them.
</Note>

To set up toolchains using the `local_settings.py` file, do the following:

1. Create the `ramparser_utils\utils` directory in the root directory.
2. Download the toolchain (aarch64-none-linux-gnu) into the `ramparser_utils\utils` directory from [Arm GNU toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).

**local\_settings.py**

The RAMParser automatically determines most of the settings. However, some settings are unique to the runtime environment. You specify these unique settings in the `local_settings.py` file. As `local_settings.py` is a Python file, it can leverage Python features.

**Note**

For RAMParser to pick the correct path for toolchain utilities, add the `local_settings.py` file to the path `<root>/tools/linux-ramdump-parser-v2` directory.

The format of the `local_settings.py` file is:

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

The `local_settings.py` file supports the following features:

**Table: Supported features in local\_settings.py file**

|    **Feature**   |                        **Description**                        |
| :--------------: | :-----------------------------------------------------------: |
|    `gdb_path`    |         Absolute path to the gdb tool for the RAM dump        |
|     `nm_path`    |         Absolute path to the nm tool for the RAM dump         |
|   `gdb64_path`   |     Absolute path to the 64‑bit gdb tool for the RAM dump     |
|    `nm64_path`   |      Absolute path to the 64‑bit nm tool for the RAM dump     |
|  `objdump_path`  |     Absolute path to the object dump tool for the RAM dump    |
| `objdump64_path` | Absolute path to the 64‑bit object dump tool for the RAM dump |

**Example: 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 commands**

* To parse dumps using RAMParser, run the following command in the 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>`: This string specifies the hardware ID of the chipset. See the following table and use the appropriate value.
  >   | **Chipset** | **Hardware name** |
  >   | :---------: | :---------------: |
  >   |   QCS6490   |     `qcm6490`     |
  >   |   QCS5430   |                   |
  >   |   IQ-8275   |     `qcs8300`     |
  >   |   IQ-9075   |     `qcs9100`     |
  >   |    IQ-615   |      `qcs615`     |
  > * `python ramparse.py`: This file invokes the RAMParser.
  > * `mod_path`: Specify this option to copy all the unstripped kernel modules into a directory and reference it as the symbol path for the `--mod_path` option.
  > * `<parser options>`: Specify parser options to extract specific data from the RAM dump. Additionally, you can pass subparser options in the command to extract the relevant data. For example, to extract ftrace information, pass `--dump-ftrace` along with the related arguments and run the command:
  >   ```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>
  >   ```
  >   Similarly, to extract the kconfig information, pass `--print-kconfig`. There are many options available to parse the dumps and store the output in a directory.
  > * To view all the available commands and options, run the following command:
  >   > ```text theme={null}
  >   > python ramparse.py --help
  >   > ```

## **View RAMParser logs**

The RAMParser generates an extensive amount of data regarding work queues, processes states, and call stacks. The following table lists the important files generated during RAMParser execution.

**Table: Files generated by RAMParser**

|   **Filename**   |                                **Description**                                |
| :--------------: | :---------------------------------------------------------------------------: |
|  `dmesg_TZ.txt`  |  This file includes kernel logs, run queues, work queues, and IRQ statistics. |
|  `mem_stat.txt`  |               This file provides statistics about system memory.              |
|   `memory.txt`   |                                                                               |
|    `tasks.txt`   |        This file provides a kernel space call stack for all processes.        |
| `devicetree.dtb` |             This file is the device tree blob used by the kernel.             |
| `launch_t32.bat` | This file launches the TRACE32 simulator launcher file for loading RAM dumps. |
|  `timerlist.txt` |                 This file provides the list of active timers.                 |

The following images show sample data generated by the RAMParser:

<Frame caption="Figure: Run queue (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="Figure: IRQ state (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="Figure: Sample kernel crash (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="Figure: Timer list of cores (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="Figure: Work queue (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="Figure: Memory statistics (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="Figure: CPU frequency (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="Figure: TRACE32 simulator launcher (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>