How systemrdl/peakrdl works
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 Tests · process_input.py Input flow · peakrdl_toolchain.py Toolchain · main.py Runner
Components 18
CLI distribution
End-user command-line package and execution flow
- Main · CLI startup and entry wiring
peakrdl-cli/src/peakrdl/__main__.py - Runner · Top-level command execution and dispatch
peakrdl-cli/src/peakrdl/main.py - Dispatch · Subcommand registration and routing
peakrdl-cli/src/peakrdl/subcommand.py - Input flow · Argument, argfile, and import preprocessing
peakrdl-cli/src/peakrdl/process_input.py - Argfiles · Argument-file expansion and handling
peakrdl-cli/src/peakrdl/argfile.py - Config load · Load project configuration from TOML files
peakrdl-cli/src/peakrdl/config/loader.py - Config schema · Configuration schema and validation rules
peakrdl-cli/src/peakrdl/config/schema.py - Dump · Model dump command
peakrdl-cli/src/peakrdl/cmd/dump.py - List globals · Global-symbol listing command
peakrdl-cli/src/peakrdl/cmd/list_globals.py - Preprocess · Preprocessing command for inputs
peakrdl-cli/src/peakrdl/cmd/preprocess.py - Importer bridge · CLI-facing importer integration layer
peakrdl-cli/src/peakrdl/importer.py
Core toolchain
Reusable library-facing SystemRDL toolchain layer
- Toolchain · Reusable SystemRDL-oriented library entry point
peakrdl/peakrdl_toolchain.py
Plugins
Discovery and extension boundaries for importers and exporters
- Entry points · Python entry-point discovery for extensions
peakrdl-cli/src/peakrdl/plugins/entry_points.py - Import plugins · Pluggable source-format import interface
peakrdl-cli/src/peakrdl/plugins/importer.py - Export plugins · Pluggable output-format export interface
peakrdl-cli/src/peakrdl/plugins/exporter.py
Connections 27
- 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