# systemrdl/peakrdl architecture

> Architecture diagram of the GitHub repository systemrdl/peakrdl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/systemrdl/peakrdl
- Repository: https://github.com/systemrdl/peakrdl

## Overview

1. **Repository shape**
   - This is a Python-based CSR toolchain split into a reusable core and a separate CLI distribution.
   - The two main code areas are `peakrdl/` and `peakrdl-cli/`; everything else is documentation, examples, and tests.

2. **Core toolchain layer**
   - `peakrdl/peakrdl_toolchain.py` is the central library-facing entry point for the PeakRDL toolchain.
   - This layer represents the domain around SystemRDL register models and is the likely shared API used by CLI commands and by plugins.

3. **CLI front end**
   - `peakrdl-cli/src/peakrdl/` contains the end-user command-line application.
   - `__main__.py` and `main.py` bootstrap execution, while `subcommand.py` and the `cmd/` package define command dispatch and individual operations.

4. **Input processing pipeline**
   - `process_input.py`, `argfile.py`, and `importer.py` handle the front-end ingestion path.
   - The CLI accepts normal command-line arguments, argument files, and configuration-driven inputs, then turns them into an internal representation suitable for later elaboration or export.

5. **Configuration subsystem**
   - `config/loader.py` and `config/schema.py` implement project configuration loading and validation.
   - The repo supports TOML-based config files such as `peakrdl.toml` and `.peakrdl.toml`, which are exercised heavily in tests and documented in `docs/configuring.rst`.

6. **Plugin architecture**
   - `plugins/entry_points.py`, `plugins/importer.py`, and `plugins/exporter.py` show that PeakRDL is plugin-driven rather than a monolithic generator.
   - External generators/importers are discovered through Python entry points, allowing the CLI to remain generic while third parties provide format-specific functionality.

7. **Import/export boundaries**
   - The toolchain explicitly supports multiple data formats: SystemRDL 2.0, IP-XACT XML, and generated artifacts such as SystemVerilog RTL, C headers, HTML docs, and UVM models.
   - This makes the architecture a translation pipeline: source register specs in, elaborated register model in the middle, and multiple exporters out.

8. **Command surface**
   - The bundled commands visible in `cmd/` are `dump`, `list_globals`, and `preprocess`.
   - These are introspection and preprocessing utilities around the same underlying model, not separate apps.

9. **Documentation and developer guidance**
   - `docs/` is extensive and includes user docs, plugin developer docs, schema docs, and SystemRDL gotchas.
   - The `docs/for-devs/` area suggests a stable plugin contract and clear boundaries between core parsing, configuration, and exporter/importer implementation.

10. **Examples as integration references**
    - `examples/` contains a concrete register block (`atxmega_spi`) in multiple forms: `.rdl`, `.xml`, generated `.sv`, and generated C/UVM artifacts.
    - These files illustrate the full conversion path the architecture is designed to support.

11. **Test strategy**
    - `test/` focuses on configuration loading, argfile handling, plugin discovery, imports, and command behavior.
    - The presence of dummy importer/exporter fixtures indicates the plugin API is a primary architectural seam and is validated independently.

12. **Packaging and distribution**
    - `peakrdl-cli/pyproject.toml` and the top-level `peakrdl/pyproject.toml` indicate separate packaging concerns: CLI distribution versus toolchain library.
    - The repo is structured to publish the command-line entry point and the core package independently while sharing the same conceptual architecture.

13. **Operational/tooling context**
    - GitHub Actions drives CI, and Read the Docs hosts the documentation site.
    - These do not change runtime behavior, but they reinforce that the project is intended as a reusable developer tool with strong documentation and regression coverage.

14. **Mental model for an architecture diagram**
    - Draw the CLI as the top-level entry point.
    - From there, show configuration/argfile loading and input preprocessing feeding a central SystemRDL-oriented model/toolchain.
    - Around that core, show pluggable importers/exporters discovered via entry points, with outputs branching into RTL, software headers, documentation, and other community extensions.

Main entry points: [`test`](https://github.com/systemrdl/peakrdl/tree/main/test) (Tests), [`peakrdl-cli/src/peakrdl/process_input.py`](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/process_input.py) (Input flow), [`peakrdl/peakrdl_toolchain.py`](https://github.com/systemrdl/peakrdl/blob/main/peakrdl/peakrdl_toolchain.py) (Toolchain), [`peakrdl-cli/src/peakrdl/main.py`](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/main.py) (Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI distribution"]
  node_cli_main["Main<br/>bootstrap<br/>[__main__.py]"]
  node_cli_run["Runner<br/>cli orchestration<br/>[main.py]"]
  node_cli_subcmd["Dispatch<br/>command router<br/>[subcommand.py]"]
  node_cli_input["Input flow<br/>ingestion pipeline<br/>[process_input.py]"]
  node_cli_argfile["Argfiles<br/>argfile parser<br/>[argfile.py]"]
  node_cli_cfg_loader["Config load<br/>[loader.py]"]
  node_cli_cfg_schema["Config schema<br/>config validation<br/>[schema.py]"]
  node_cmd_dump["Dump<br/>introspection cmd<br/>[dump.py]"]
  node_cmd_list["List globals<br/>introspection cmd<br/>[list_globals.py]"]
  node_cmd_preprocess["Preprocess<br/>prep cmd<br/>[preprocess.py]"]
  node_cli_importer["Importer bridge<br/>input adapter<br/>[importer.py]"]
end

subgraph group_core["Core toolchain"]
  node_core_toolchain["Toolchain<br/>systemrdl core"]
end

subgraph group_ext["Plugins"]
  node_plugin_points["Entry points<br/>plugin discovery<br/>[entry_points.py]"]
  node_plugin_importer["Import plugins<br/>plugin API<br/>[importer.py]"]
  node_plugin_exporter["Export plugins<br/>plugin API<br/>[exporter.py]"]
end

subgraph group_support["Support material"]
  node_examples["Examples<br/>integration samples"]
  node_docs["Docs"]
  node_tests["Tests<br/>validation suite"]
end

node_cli_main -->|"boot"| node_cli_run
node_cli_run -->|"dispatch"| node_cli_subcmd
node_cli_run -->|"load config"| node_cli_cfg_loader
node_cli_run -->|"prepare input"| node_cli_input
node_cli_input -->|"expand"| node_cli_argfile
node_cli_input -.->|"validate"| node_cli_cfg_schema
node_cli_input -->|"import"| node_cli_importer
node_cli_importer -->|"discover"| node_plugin_points
node_plugin_points -->|"load"| node_plugin_importer
node_plugin_points -->|"load"| node_plugin_exporter
node_plugin_importer -->|"model in"| node_core_toolchain
node_core_toolchain -->|"model out"| node_plugin_exporter
node_cli_subcmd -->|"registers"| node_cmd_dump
node_cli_subcmd -->|"registers"| node_cmd_list
node_cli_subcmd -->|"registers"| node_cmd_preprocess
node_cmd_dump -->|"inspect"| node_core_toolchain
node_cmd_list -->|"inspect"| node_core_toolchain
node_cmd_preprocess -->|"reuse"| node_cli_input
node_docs -.->|"describe"| node_cli_cfg_loader
node_docs -.->|"guide"| node_plugin_importer
node_docs -.->|"guide"| node_plugin_exporter
node_examples -.->|"exercise"| node_core_toolchain
node_tests -.->|"cover"| node_cli_cfg_loader
node_tests -.->|"cover"| node_cli_importer
node_tests -.->|"cover"| node_plugin_importer
node_tests -.->|"cover"| node_plugin_exporter
node_tests -.->|"cover"| node_cmd_dump

click node_cli_main "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/__main__.py"
click node_cli_run "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/main.py"
click node_cli_subcmd "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/subcommand.py"
click node_cli_input "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/process_input.py"
click node_cli_argfile "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/argfile.py"
click node_cli_cfg_loader "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/config/loader.py"
click node_cli_cfg_schema "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/config/schema.py"
click node_cmd_dump "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/dump.py"
click node_cmd_list "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/list_globals.py"
click node_cmd_preprocess "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/preprocess.py"
click node_core_toolchain "https://github.com/systemrdl/peakrdl/blob/main/peakrdl/peakrdl_toolchain.py"
click node_plugin_points "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/entry_points.py"
click node_plugin_importer "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/importer.py"
click node_plugin_exporter "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/exporter.py"
click node_cli_importer "https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/importer.py"
click node_examples "https://github.com/systemrdl/peakrdl/tree/main/examples"
click node_docs "https://github.com/systemrdl/peakrdl/tree/main/docs"
click node_tests "https://github.com/systemrdl/peakrdl/tree/main/test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_main,node_cli_run,node_cli_subcmd,node_cli_input,node_cli_argfile,node_cli_cfg_loader,node_cli_cfg_schema,node_cmd_dump,node_cmd_list,node_cmd_preprocess,node_cli_importer toneBlue
class node_core_toolchain toneAmber
class node_plugin_points,node_plugin_importer,node_plugin_exporter toneMint
class node_examples,node_docs,node_tests toneRose
```

## Components

### CLI distribution

End-user command-line package and execution flow

- [Main](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/__main__.py): bootstrap · CLI startup and entry wiring · `peakrdl-cli/src/peakrdl/__main__.py`
- [Runner](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/main.py): cli orchestration · Top-level command execution and dispatch · `peakrdl-cli/src/peakrdl/main.py`
- [Dispatch](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/subcommand.py): command router · Subcommand registration and routing · `peakrdl-cli/src/peakrdl/subcommand.py`
- [Input flow](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/process_input.py): ingestion pipeline · Argument, argfile, and import preprocessing · `peakrdl-cli/src/peakrdl/process_input.py`
- [Argfiles](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/argfile.py): argfile parser · Argument-file expansion and handling · `peakrdl-cli/src/peakrdl/argfile.py`
- [Config load](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/config/loader.py): config loader · Load project configuration from TOML files · `peakrdl-cli/src/peakrdl/config/loader.py`
- [Config schema](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/config/schema.py): config validation · Configuration schema and validation rules · `peakrdl-cli/src/peakrdl/config/schema.py`
- [Dump](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/dump.py): introspection cmd · Model dump command · `peakrdl-cli/src/peakrdl/cmd/dump.py`
- [List globals](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/list_globals.py): introspection cmd · Global-symbol listing command · `peakrdl-cli/src/peakrdl/cmd/list_globals.py`
- [Preprocess](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/cmd/preprocess.py): prep cmd · Preprocessing command for inputs · `peakrdl-cli/src/peakrdl/cmd/preprocess.py`
- [Importer bridge](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/importer.py): input adapter · CLI-facing importer integration layer · `peakrdl-cli/src/peakrdl/importer.py`

### Core toolchain

Reusable library-facing SystemRDL toolchain layer

- [Toolchain](https://github.com/systemrdl/peakrdl/blob/main/peakrdl/peakrdl_toolchain.py): systemrdl core · Reusable SystemRDL-oriented library entry point · `peakrdl/peakrdl_toolchain.py`

### Plugins

Discovery and extension boundaries for importers and exporters

- [Entry points](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/entry_points.py): plugin discovery · Python entry-point discovery for extensions · `peakrdl-cli/src/peakrdl/plugins/entry_points.py`
- [Import plugins](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/importer.py): plugin API · Pluggable source-format import interface · `peakrdl-cli/src/peakrdl/plugins/importer.py`
- [Export plugins](https://github.com/systemrdl/peakrdl/blob/main/peakrdl-cli/src/peakrdl/plugins/exporter.py): plugin API · Pluggable output-format export interface · `peakrdl-cli/src/peakrdl/plugins/exporter.py`

### Support material

Documentation, examples, and tests that exercise the architecture

- [Examples](https://github.com/systemrdl/peakrdl/tree/main/examples): integration samples · End-to-end conversion examples across source and generated artifacts · `examples`
- [Docs](https://github.com/systemrdl/peakrdl/tree/main/docs): reference docs · User, plugin, and developer documentation · `docs`
- [Tests](https://github.com/systemrdl/peakrdl/tree/main/test): validation suite · Coverage for config, imports, plugins, and commands · `test`

## Connections

- Main → Runner: boot · Entry module starts the CLI runner
- Runner → Dispatch: dispatch · Runner resolves and invokes subcommands
- Runner → Config load: load config · Runner loads project configuration early
- Runner → Input flow: prepare input · Runner feeds arguments into the input pipeline
- Input flow → Argfiles: expand · Input pipeline expands argfiles
- Input flow → Config schema: validate · Input pipeline relies on config schema validation
- Input flow → Importer bridge: import · Input pipeline routes source loading through importer integration
- Importer bridge → Entry points: discover · Importer bridge discovers plugin implementations
- Entry points → Import plugins: load · Entry points resolve importer plugins
- Entry points → Export plugins: load · Entry points resolve exporter plugins
- Import plugins → Toolchain: model in · Import plugins produce the core register model
- Toolchain → Export plugins: model out · Core model is consumed by exporters
- Dispatch → Dump: registers · Dispatch wires the dump command
- Dispatch → List globals: registers · Dispatch wires the global-list command
- Dispatch → Preprocess: registers · Dispatch wires the preprocess command
- Dump → Toolchain: inspect · Dump operates on the shared toolchain model
- List globals → Toolchain: inspect · Global listing reads the shared model state
- Preprocess → Input flow: reuse · Preprocess reuses the common ingestion flow
- Docs → Config load: describe · Documentation explains configuration loading
- Docs → Import plugins: guide · Documentation covers importer plugin development
- Docs → Export plugins: guide · Documentation covers exporter plugin development
- Examples → Toolchain: exercise · Examples demonstrate the central toolchain path
- Tests → Config load: cover · Tests validate configuration loading behavior
- Tests → Importer bridge: cover · Tests validate importer integration and discovery
- Tests → Import plugins: cover · Tests exercise importer plugin seams
- Tests → Export plugins: cover · Tests exercise exporter plugin seams
- Tests → Dump: cover · Tests cover command behavior
