Skip to main content
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 
      python -m pip install --trusted-host files.pythonhosted.org --trusted-host pypi.org --trusted-host pypi.python.org prettytable

      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.
    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. 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
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.
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.
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: 
<setting name> = <string identifying the feature>
The local_settings.py file supports the following features: Table: Supported features in local_settings.py file
FeatureDescription
gdb_pathAbsolute path to the gdb tool for the RAM dump
nm_pathAbsolute path to the nm tool for the RAM dump
gdb64_pathAbsolute path to the 64‑bit gdb tool for the RAM dump
nm64_pathAbsolute path to the 64‑bit nm tool for the RAM dump
objdump_pathAbsolute path to the object dump tool for the RAM dump
objdump64_pathAbsolute path to the 64‑bit object dump tool for the RAM dump
Example: local_settings.py 
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: 
    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.
      ChipsetHardware name
      QCS6490qcm6490
      QCS5430
      IQ-8275qcs8300
      IQ-9075qcs9100
      IQ-615qcs615
    • 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: 
      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: 
      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
FilenameDescription
dmesg_TZ.txtThis file includes kernel logs, run queues, work queues, and IRQ statistics.
mem_stat.txtThis file provides statistics about system memory.
memory.txt
tasks.txtThis file provides a kernel space call stack for all processes.
devicetree.dtbThis file is the device tree blob used by the kernel.
launch_t32.batThis file launches the TRACE32 simulator launcher file for loading RAM dumps.
timerlist.txtThis file provides the list of active timers.
The following images show sample data generated by the RAMParser: