docs: Add Starlight documentation site with architecture diagrams#103
Open
DanielKellerM wants to merge 9 commits into
Open
docs: Add Starlight documentation site with architecture diagrams#103DanielKellerM wants to merge 9 commits into
DanielKellerM wants to merge 9 commits into
Conversation
Add an Astro Starlight documentation site covering all iDMA architecture layers, frontend variants, and guides. Ten pages: landing, backend, midend, frontend hub, register/snitch/descriptor frontends, system integration, error handling, and verification. Update doc/.gitignore to track site sources while ignoring node_modules, dist, and .astro cache.
Fix descriptor frontend flags bitfield to match reshaper RTL (bit 6 is decouple_aw, not serialize; bit 7 is reduce_len, not deburst). Add TileLink to legalizer splitting rules, document axi_options_t, expand code generation section, restructure landing page for clarity, add build prerequisites to verification guide, and improve cross-links.
Reorder sidebar to pipeline order (Frontend, Midend, Backend), add missing explanations before code blocks, expand parameter descriptions, document conf bitfield and next_id side-effect, add use-case context for midend variants and protocol table, reorganize verification job files by category, and add error visibility and debugging guidance.
Improve documentation flow and usefulness across all Starlight pages: expand backend_options_t and axi_options_t field descriptions, add legalizer worked example, add register frontend driver example, add error handling worked scenario, convert conf bitfield to table, define terms on first use, add intro sentences before code blocks, integrate Snitch note boxes into body text, add parameter presets rationale and misconfiguration caution, add multi-transfer job file example.
Replace generic '## Overview' with descriptive headings (Backend Role, Descriptor Frontend Role, etc.) across 15 docs/site .md files. Improves sidebar TOC readability and avoids same-titled subsections on each page.
12 SVG figures + their Excalidraw sources for diagrams referenced from doc/site Starlight pages. Sources are kept alongside the SVGs so the figures can be re-exported.
There was a problem hiding this comment.
Pull request overview
This PR bundles a Starlight-based documentation site, rendered architecture SVGs (with Excalidraw sources), a heading-rename pass across markdown files, and—as a side-effect of its base branch—a pre-existing rw_obi backend test configuration. The diffs supplied to this review only include the rw_obi portion (a new entry in jobs/jobs.json plus its corresponding test stimulus files); the documentation additions described in the PR body are not present in the reviewable hunks.
Changes:
- Add
rw_obiconfiguration block tojobs/jobs.jsonmirroring existing backend entries (e.g.,rw_axi_rw_axis) - Add stimulus files under
jobs/backend_rw_obi/(simple,same_dst,linear,huge,zero_transfer, etc.) used by the newrw_obijob - Per the PR description, also adds a Starlight docs site and architecture SVGs under
doc/(not included in the diffs reviewed here)
Reviewed changes
Copilot reviewed 34 out of 52 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| jobs/jobs.json | Adds the rw_obi job entry with params, proc_id, testbench and synth top — consistent with the existing rw_axi_rw_axis block above it |
| jobs/backend_rw_obi/simple.txt | Minimal 2-transfer stimulus for rw_obi |
| jobs/backend_rw_obi/zero_transfer.txt | Zero-transfer stimulus to exercise RejectZeroTransfers=1 |
| jobs/backend_rw_obi/linear.txt | Large single-transfer linear stimulus |
| jobs/backend_rw_obi/huge.txt | 500-line large randomized stimulus |
| jobs/backend_rw_obi/same_dst.txt | 1280-line randomized stimulus exercising the rw_obi backend |
Notes from review:
- The new
rw_obiblock structurally matches the existingrw_axi_rw_axisblock (including the same minor indentation quirk on the closing}of the"jobs"map at line 214 vs. line 181), so it does not introduce a new inconsistency. - Stimulus files match the column counts used elsewhere in the repo for backend stimulus.
- The PR description states the changes are "purely additive under
doc/", but the diffs presented are entirely underjobs/. The PR author explicitly calls this out as a base-branch side-effect commit (e618e4d) that is also carried by PRs #100 and #101, so this discrepancy is intentional and acknowledged in the PR body.
Comments suppressed due to low confidence (2)
jobs/jobs.json:214
- The closing brace of the
"jobs"object is indented less than its opening, breaking the consistent indentation used elsewhere in this file (e.g. the surrounding variants close their"jobs"block aligned with the"jobs"key). It parses fine but is inconsistent with the rest of the file. Consider re-indenting the closing}on line 214 to match the opening on line 203.
doc/site/astro.config.mjs:10 - Starlight 0.32 changed the
socialconfig schema: the object-literal form (social: { github: '...' }) was removed and replaced by an array of{ icon, label, href }entries. With"@astrojs/starlight": "^0.32.0"inpackage.json, this configuration will fail schema validation and causenpm run buildto error out. Convert this to the array form, e.g. an entry withicon: 'github', alabel, and the repo URL ashref.
social: {
github: 'https://github.com/pulp-platform/iDMA',
},
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+8
to
+10
| social: { | ||
| github: 'https://github.com/pulp-platform/iDMA', | ||
| }, |
| sidebar: [ | ||
| { | ||
| label: 'Overview', | ||
| slug: '', |
Comment on lines
+202
to
+234
| "rw_obi": { | ||
| "jobs" : { | ||
| "simple" : "backend_rw_obi/simple.txt", | ||
| "same_dst" : "backend_rw_obi/same_dst.txt", | ||
| "linear" : "backend_rw_obi/linear.txt", | ||
| "huge" : "backend_rw_obi/huge.txt", | ||
| "large" : "backend_rw_obi/large.txt", | ||
| "medium" : "backend_rw_obi/medium.txt", | ||
| "mixed" : "backend_rw_obi/mixed.txt", | ||
| "small" : "backend_rw_obi/small.txt", | ||
| "tiny" : "backend_rw_obi/tiny.txt", | ||
| "zero_transfer" : "backend_rw_obi/zero_transfer.txt" | ||
| }, | ||
| "params" : { | ||
| "DataWidth" : 32, | ||
| "AddrWidth" : 32, | ||
| "UserWidth" : 1, | ||
| "AxiIdWidth" : 12, | ||
| "NumAxInFlight" : 3, | ||
| "BufferDepth" : 3, | ||
| "TFLenWidth" : 32, | ||
| "MemSysDepth" : 0, | ||
| "CombinedShifter" : 0, | ||
| "MaskInvalidData" : 1, | ||
| "RAWCouplingAvail" : 0, | ||
| "HardwareLegalizer" : 1, | ||
| "RejectZeroTransfers" : 1, | ||
| "ErrorHandling" : 0 | ||
| }, | ||
| "proc_id" : "rw_obi", | ||
| "testbench" : "tb_idma_backend_rw_obi", | ||
| "synth_top" : "idma_backend_synth_rw_obi" | ||
| }, |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds the Starlight-based documentation site and rendered architecture diagrams under
doc/.This bundles the local doc work that has been sitting on my
develfor a few weeks, plus two small follow-ups:docs/site— Starlight site with architecture / frontend / midend / backend / system-integration pages, plus guides (quickstart, verification, error-handling, performance-limitations, system-integration, docs-verification).doc/fig/— 12 rendered SVGs + their Excalidraw sources for the figures referenced from the site pages. Sources kept alongside the SVGs so they can be re-exported.## Overviewwith section-specific headings (Backend Role,Descriptor Frontend Role, etc.) across 15 .md files for a cleaner sidebar TOC.Test plan
cd doc/site && npm install && npm run buildsucceedsNotes
develper the branch policy in ci: Add branch policy enforcement and PR template #102 (the samedevel-first staging workflow that's currently up for review).doc/.