Miscelaneous reverse-engineering scripts

This repository contains scripts that I use to figure stuff out while mainlining.

Register dumping

• libdump - Python library for parsing reg/val dumps in the dump format
• tools-ondev/devmem-read-block.sh - Bash script to automate dumping an entire MMIO block with devmem2.
• tools-ondev/i2c-read-block.sh - Bash script to automate dumping all bytes from an I2C device with i2cget; requires i2c-tools.
• visualizers/diff.py - Python script, creates a HTML diff of two register dumps. Requires jinja2. Run as python3 -m visualizers.diff (file_a) (file_b).
• split-dumpall-dumps.py - Script to split up individual dumps from a mass-dump file generated by the script generated by libdump.ext.doc_bcm_kona.gen_dump_commands
• dump-diff-to-commands.py - Takes two dump files and converts them to a list of commands to run to dump the differing registers.

All of the above Python scripts have built-in help; pass the --help parameter to find out more about the parameters you can pass to them.

Dump format

The dump files are text files with key/value pairs and unix-style line breaks (\n).

The file starts with a header:

fmt dump
type mmio
base_addr 0x0000f000
size 0x...
addr_bits 32
val_bits 8
--- header_end ---

• fmt: must be set to dump.
• type: one of mmio, i2c, unknown
• base_addr: base address of the block as a hex number
• size: size of the block (i.e. the last address, inclusive); either hex or decimal number
• addr_bits: amount of bits in address
• val_bits: amount of bits in values

Below the header are reg/value pairs, with the reg and value both being hex numbers. The reg starts at the base_addr.

0x0000f000 0x01
0x0000f004 0x02

If a value is unreadable, it is set to -:

0x0000f020 -

Register documentation

There is some support for reading out documentation for registers; this is primarily used by generate-dump-diff.py to provide names for addresses/bit ranges. The relevant library code and the dfmt parser is in libdump.doc; alternative documentation parsers are in libdump.ext.doc_*.

Doc format/dfmt

Internally referred to as dfmt. (It wouldn't surprise me if this name was already taken; alas, I'm not good at naming things. Rest assured, if you see dfmt mentioned in this repo, it refers to this here format.)

The file starts with a header:

fmt doc
type mmio
base_addr 0x0000f000
size 0x...
addr_bits 32
val_bits 8
--- header_end ---

This header is exactly the same as the dump header, except that fmt must be set to doc.

The contents below the header are as follows:

0x0000f004 ADDR_NAME
! Description

  b 0 0 BIT_NAME
  ! Description for bit 0

  b 1 2 BIT_NAME
  ! Description for bit range 1-2 (inclusive)
  ! Descriptions can also be multiline.

A line starting with a hex offset is treated as an address; the parameter after the space is the name of the address.

Below the address are lines representing bit ranges within the address; they follow the format of b <start_bit> <end_bit> RANGE_NAME.

Descriptions can be added by placing a line (or multiple lines) starting with ! after the relevant line (either offset or bit range). Currently these are not parsed by the library, but will be eventually.

Indentation is ignored when parsing. It is included here for readability.

Miscelaneous scripts

Other scripts are located in tools-misc. Some require libdump from the main folder of the repo - you can move them back into the repository root if needed.

• tools-misc/kona-symbol-map-gen.py - generates symbol maps from RDB headers in a format understood by Ghidra's ImportSymbolsScript.py. Note that the RDB location is hardcoded, change it to point to your own repo.