Hardware Hacking Laboratory Logo
Hardware Hacking Laboratory

pySvdGenerator: generating CMSIS-SVD files from a device tree and a reference manual

H2Lab is releasing pySvdGenerator, a tool dedicated to the generation of CMSIS-SVD files for embedded SoCs. The repository is available on GitHub and the package is published on PyPI.

Why pySvdGenerator

CMSIS-SVD files describe the peripherals, registers, and bit fields of a SoC, and are used by debuggers, disassemblers, and static analyzers to make sense of memory-mapped registers. Vendors do not always publish an SVD for every part, while the information needed to build one is already public: the Linux device tree describes the memory map, the interrupts, and the cores, and the reference manual describes the registers and their bit fields.

pySvdGenerator combines these two public sources to produce a complete SVD file, without requiring proprietary tooling.

How it works

The generation is organized as a pipeline:

  1. device tree analysis: the DTSI is preprocessed and parsed (includes, dt-bindings macros, phandles, address translation), and the peripheral descriptions are read from the kernel’s devicetree bindings documentation;
  2. SVD generation: a CMSIS-SVD skeleton is written with the CPU, the peripherals, their address blocks, and their interrupts;
  3. manual splitting: the reference manual PDF is cut into one document per chapter;
  4. register extraction: the register memory maps and bit field tables are read from each chapter with tabula-py, tables continued over several pages are merged, and peripheral instances (GPT1, GPT2, …) are separated; a local ollama agent consolidates the result by default, and --no-llm restricts the stage to deterministic parsing;
  5. SVD enrichment: the extracted registers and fields are injected into the SVD, keeping only the registers that fall inside the address blocks declared by the device tree.

Usage

pysvdgen \
  --kernel /path/to/linux \
  --dtsi imx8mm \
  --pdf IMX8MDQLQRM.pdf \
  --output build/imx8mm.svd

An existing SVD can also be completed chapter by chapter, filtering on chapter titles or filenames:

pysvdgen --svd build/imx8mm.svd --pdf IMX8MDQLQRM.pdf --chapter Timer

Peripherals missing from the device tree, peripherals missing from the manual, and registers falling outside the device tree address blocks are reported at the end of the run.

Availability

pySvdGenerator is written in Python (3.12 or newer) and distributed under the Apache 2.0 license. It installs with a single command:

pip install pySvdGenerator

The source code, tests, and full documentation are available on the GitHub repository.