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

![example output](images/example.jpg)

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

```txt
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:

```sh
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](/schemas/hwio_u64.json).

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

```txt
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](https://github.com/cross-rs/cross)

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