Skip to content

Commit 218878a

Browse files
committed
docs: add RTL wrapper reference page linking to training docs
Add a short docs/rtl-wrapper.rst that introduces the RTL wrapper, points to the in-depth usage guide and worked examples in chipflow-training, and demonstrates the new [parameters] table plus Python override. Autoapi continues to generate the full API reference for RTLWrapper, load_wrapper_from_toml, and ExternalWrapConfig.
1 parent 9fff5cb commit 218878a

2 files changed

Lines changed: 64 additions & 0 deletions

File tree

docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ It is developed at https://github.com/chipFlow/chipflow-lib/ and licensed `BSD 2
1515
chipflow-toml-guide
1616
chipflow-commands
1717
using-pin-signatures
18+
rtl-wrapper
1819
platform-api
1920

2021
.. toctree::

docs/rtl-wrapper.rst

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
Wrapping External RTL
2+
=====================
3+
4+
``chipflow.rtl.wrapper`` turns a TOML description of an external Verilog or
5+
SystemVerilog module into an Amaranth :py:class:`~amaranth.lib.wiring.Component`
6+
ready to drop into a design. The TOML specifies the source files, clocks and
7+
resets, bus/pin interfaces, optional preprocessing (sv2v, yosys-slang,
8+
SpinalHDL), and — as of this release — Verilog module ``parameter`` overrides.
9+
10+
This page is an API-level pointer. For the full usage guide, worked examples,
11+
and the TOML reference, see the ChipFlow training material:
12+
13+
- `RTLWrapper: Wrapping External RTL via TOML <https://github.com/ChipFlow/chipflow-training/blob/main/rtl-wrapper.md>`__ — TOML reference, Wishbone-timer example, preprocessing.
14+
- `Wrapping External RTL <https://github.com/ChipFlow/chipflow-training/blob/main/wrapping-external-rtl.md>`__ — manual ``Instance(...)`` path for simple modules.
15+
- `Wrapping CV32E40P <https://github.com/ChipFlow/chipflow-training/blob/main/cv32e40p-example.md>`__ — a worked example with sv2v preprocessing.
16+
17+
Quick reference
18+
---------------
19+
20+
Load a wrapper from a TOML file and instantiate it inside a design:
21+
22+
.. code-block:: python
23+
24+
from chipflow.rtl.wrapper import load_wrapper_from_toml
25+
26+
class MyDesign(wiring.Component):
27+
def elaborate(self, platform):
28+
m = Module()
29+
m.submodules.timer = load_wrapper_from_toml("wb_timer.toml")
30+
return m
31+
32+
Supply Verilog ``parameter`` overrides from TOML, from Python, or both (the
33+
Python kwarg wins on collisions; unmentioned parameters fall back to the TOML
34+
table):
35+
36+
.. code-block:: toml
37+
38+
# wb_timer.toml
39+
name = "wb_timer"
40+
41+
[parameters]
42+
DATA_WIDTH = 32
43+
ADDR_WIDTH = 4
44+
45+
.. code-block:: python
46+
47+
# caller overrides DATA_WIDTH; ADDR_WIDTH=4 still applies
48+
w = load_wrapper_from_toml("wb_timer.toml", parameters={"DATA_WIDTH": 64})
49+
50+
The merged parameters are emitted as ``p_<NAME>=<value>`` kwargs on the
51+
``Instance()`` at elaboration, and are also fed into generator template
52+
substitution (so SpinalHDL / sv2v / yosys-slang see the final values when
53+
producing Verilog).
54+
55+
API
56+
---
57+
58+
- :py:class:`chipflow.rtl.wrapper.RTLWrapper` — the generated component.
59+
- :py:func:`chipflow.rtl.wrapper.load_wrapper_from_toml` — loader that parses
60+
the TOML, runs any configured preprocessing, and returns an
61+
:py:class:`~chipflow.rtl.wrapper.RTLWrapper`.
62+
- :py:class:`chipflow.rtl.wrapper.ExternalWrapConfig` — Pydantic schema for the
63+
TOML configuration.

0 commit comments

Comments
 (0)