Interactive register decoding for Qualcom SoCs

This is a collection of tools for parsing the .FLAT and .per files which are commonly included in Qualcomm chipcode releases. These files include reasonably comprehensive register maps for the main SoC as well as co-processors and PMICs. However, they are intended to be used with proprietary tools like Trace32, having a much higher barrier of entry.

Usage

regdump

The regdump tool implements register decoding for a given JSON register map. It can be used to decode a single register with the decode command, however due to the massive size of the register maps this can be quite slow (on my machine is takes ~750ms to load the SDM845 register map).

Instead, it can be run with no arguments to enter an interactive prompt, in this mode you're prompted for address/value pairs until you quit, this is much faster as the JSON parsing only has to be done once.

Run with no command for interactive mode. This is recommended
to avoid having to reload large JSON files on every invocation

Usage: regdump [OPTIONS] --json <JSON> [COMMAND]

Commands:
  decode    Decode an address/value pair
  parse     Parse a file of address/value pairs each on their own line
  print     Print a list of registers and modules matching the given substring
  codegen  Create a header that can be used to decode registers at runtime (e.g. in U-Boot/Linux) for debugging
  help      Print this message or the help of the given subcommand(s)

Options:
  -j, --json <JSON>            Path to JSON register description (generate with reg2json)
  -d, --debug                  Enable debug logs
  -w, --max-width <MAX_WIDTH>  Override max table width in characters
  -h, --help                   Print help
  -V, --version                Print version

Codegen

Regdump codegen can be used to generate C code for runtime-decoding of register values to assist with driver development. The generated code is written to stdout. At runtime just call regdump_decode(u64 addr, u32 val) or regdump_read_decode(u64 addr).

Due to the size of the register maps, it isn't suitable to include all possible registers in the output, so the list of peripherals to include must be specified on the cmdline.

Some configuration can be adjusted by changing the macros at the top of the generated output, for example to use the correct print function for the platform.

Example usage:

regdump --json socs/example.json codegen DEMO_BLOCK_REGS > example_regdump.c

reg2json

reg2json is a tool for converting the .FLAT and .per file formats into a standard json representation that can be used by other tools in this repo. The schema for the resulting JSON files can be found in schemas/hwio_u64.json.

WARNING: .FLAT file support is known to have bugs, it may miss registers!

Usage: reg2json [OPTIONS] --out <OUT>

Options:
  -f, --flat <FLAT>  Path to FLAT file address map
  -e, --per <PER>    Path to TRACE32 PER file address map
  -o, --out <OUT>    Path to save JSON file as
  -d, --debug        Enable debug logs
  -h, --help         Print help
  -V, --version      Print version

Finding HWIO register maps

The .per files which document the register maps for a given SoC can usually be found in a chipcode release. Do find . -name "*.per" and feed it to reg2json.

Cross Compiling

Install cross

# Build with glibc
cross build --target aarch64-unknown-linux-gnu --release
# OR musl
cross build --target aarch64-unknown-linux-musl --release