|
| 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