From 7874224a414cd23e40994c6e709f270890ab7e46 Mon Sep 17 00:00:00 2001 From: Daniel Keller Date: Thu, 11 Jun 2026 13:36:50 +0200 Subject: [PATCH 1/3] docs: Scaffold aligning the Starlight site with generated hierarchy graphs Add an architecture/hierarchy page wired to the ast2dot-generated graphs and an idma_doc_site target that copies doc/fig/graph PNGs into the site. Starting point for refreshing the docs to the current repo state. --- doc/site/.gitignore | 2 ++ .../content/docs/architecture/hierarchy.md | 27 +++++++++++++++++++ idma.mk | 8 ++++++ 3 files changed, 37 insertions(+) create mode 100644 doc/site/.gitignore create mode 100644 doc/site/src/content/docs/architecture/hierarchy.md diff --git a/doc/site/.gitignore b/doc/site/.gitignore new file mode 100644 index 00000000..357d6d44 --- /dev/null +++ b/doc/site/.gitignore @@ -0,0 +1,2 @@ +# Generated hierarchy graphs (copied in by `make idma_doc_site`) +public/fig/graph/ diff --git a/doc/site/src/content/docs/architecture/hierarchy.md b/doc/site/src/content/docs/architecture/hierarchy.md new file mode 100644 index 00000000..bed0e664 --- /dev/null +++ b/doc/site/src/content/docs/architecture/hierarchy.md @@ -0,0 +1,27 @@ +--- +title: Module Hierarchy +description: Generated module-hierarchy graphs for the synthesizable iDMA tops. +--- + +These graphs are generated from the bender-pickle syntax tree (`util/ast2dot.py`) +for each synthesizable top, so they always reflect the current RTL. Regenerate +them with `make idma_doc_all`, then `make idma_doc_site` copies them into this +site under `public/fig/graph/`. + +:::note[Draft] +This page is a starting point for aligning the site with the regenerated +hierarchy graphs — the figures and prose are still being brought up to date with +the latest repository state. +::: + +## Backend — `rw_axi` + +![idma_backend_synth_rw_axi](/fig/graph/idma_backend_synth_rw_axi.png) + +## ND Midend + +![idma_nd_midend_synth](/fig/graph/idma_nd_midend_synth.png) + +## Descriptor Frontend + +![idma_desc64_synth](/fig/graph/idma_desc64_synth.png) diff --git a/idma.mk b/idma.mk index 3654a6e7..674cb631 100644 --- a/idma.mk +++ b/idma.mk @@ -423,6 +423,14 @@ idma_spinx_doc: $(IDMA_RTL_DOC_ALL) idma_spinx_doc_clean: rm -rf $(IDMA_DOC_OUT_DIR) +.PHONY: idma_doc_site + +IDMA_SITE_DIR := $(IDMA_ROOT)/doc/site + +idma_doc_site: $(IDMA_RTL_DOC_ALL) + mkdir -p $(IDMA_SITE_DIR)/public/fig/graph + cp -f $(IDMA_DOC_FIG_DIR)/graph/*.png $(IDMA_SITE_DIR)/public/fig/graph/ + # -------------- # Nonfree From 7719cdd9357abaac36596f483cb61af7cc938447 Mon Sep 17 00:00:00 2001 From: Daniel Keller Date: Tue, 16 Jun 2026 11:32:54 +0200 Subject: [PATCH 2/3] docs: Document building the generated RTL with uv --- .../src/content/docs/guides/quickstart.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/site/src/content/docs/guides/quickstart.md b/doc/site/src/content/docs/guides/quickstart.md index 53a460a3..eebbd34f 100644 --- a/doc/site/src/content/docs/guides/quickstart.md +++ b/doc/site/src/content/docs/guides/quickstart.md @@ -7,6 +7,25 @@ description: Minimal steps to integrate iDMA and run a transfer. This guide shows the shortest path to an end-to-end iDMA transfer: choose a backend, define types, wire modules, and launch a request. It assumes a single clock domain and a 1D transfer flow. +## Build the Generated RTL + +iDMA's SystemVerilog is generated from templates, so the first step in any checkout is to render it. + +**Prerequisites:** [`bender >= 0.32.0`](https://github.com/pulp-platform/bender) and [`Python >= 3.11`](https://www.python.org/downloads/) with [`uv`](https://docs.astral.sh/uv/). + +```bash +uv sync # install the generator deps (mako, peakrdl, …) into .venv +uv run make idma_hw_all # render the templates into target/rtl/ +``` + +`uv run` executes inside the synced environment, so no manual `source .venv/bin/activate` is needed. The generated sources land in `target/rtl/` and are what Bender exposes through its `rtl` and `synth` targets. + +When iDMA is pulled as a Bender dependency, regenerate its RTL from the consuming repo with the same environment, e.g.: + +```bash +make -C $(bender path idma) idma_hw_all +``` + ## 1. Choose a Backend Variant Pick the backend variant that matches your read/write protocols. For AXI-to-AXI systems, start with `rw_axi`. From ee05893463e91b7d7644e28605f64647282110b2 Mon Sep 17 00:00:00 2001 From: Daniel Keller Date: Tue, 16 Jun 2026 13:25:47 +0200 Subject: [PATCH 3/3] docs: Simplify the RTL build step to bare make idma_hw_all --- doc/site/src/content/docs/guides/quickstart.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/site/src/content/docs/guides/quickstart.md b/doc/site/src/content/docs/guides/quickstart.md index eebbd34f..92df04e7 100644 --- a/doc/site/src/content/docs/guides/quickstart.md +++ b/doc/site/src/content/docs/guides/quickstart.md @@ -14,13 +14,12 @@ iDMA's SystemVerilog is generated from templates, so the first step in any check **Prerequisites:** [`bender >= 0.32.0`](https://github.com/pulp-platform/bender) and [`Python >= 3.11`](https://www.python.org/downloads/) with [`uv`](https://docs.astral.sh/uv/). ```bash -uv sync # install the generator deps (mako, peakrdl, …) into .venv -uv run make idma_hw_all # render the templates into target/rtl/ +make idma_hw_all ``` -`uv run` executes inside the synced environment, so no manual `source .venv/bin/activate` is needed. The generated sources land in `target/rtl/` and are what Bender exposes through its `rtl` and `synth` targets. +On first run this provisions a local `uv` environment (`uv sync --locked`) — no manual venv setup or activation needed — and renders the templates into `target/rtl/`, which Bender exposes through its `rtl` and `synth` targets. -When iDMA is pulled as a Bender dependency, regenerate its RTL from the consuming repo with the same environment, e.g.: +When iDMA is pulled as a Bender dependency, regenerate its RTL from the consuming repo the same way: ```bash make -C $(bender path idma) idma_hw_all