mirror of
https://github.com/retroSoC/retroSoC.git
synced 2026-11-04 22:32:36 +00:00
feat: add README files for various directories to document structure and usage
This commit is contained in:
16 files changed
+230
No files matched your search
@@ -0,0 +1,15 @@
|
||||
# GitHub Automation
|
||||
|
||||
This directory owns repository automation metadata: pull-request templates,
|
||||
CODEOWNERS, Dependabot configuration, reusable actions, and CI/release
|
||||
workflows.
|
||||
|
||||
`workflows/quality.yml` runs the fast quality gate. `workflows/regression.yml`
|
||||
and `workflows/nightly.yml` call the reusable regression workflow;
|
||||
`workflows/release.yml` packages tagged releases. `actions/locked-tools/`
|
||||
installs the locked open-source tools used by CI.
|
||||
|
||||
Keep Actions pinned by commit ID and use the dependency lock rather than adding
|
||||
ad-hoc downloads. Validate workflow changes with `yamllint .github .yamllint.yml`,
|
||||
`actionlint`, and both regression dry-runs. See the root
|
||||
[agent contract](../AGENTS.md).
|
||||
@@ -24,6 +24,36 @@ truth wins.
|
||||
Do not guess a profile, tool version, dependency revision, or generated-file
|
||||
location. Inspect the corresponding source of truth first.
|
||||
|
||||
## Top-Level Directory Guides
|
||||
|
||||
Every Git-tracked first-level directory has a README that defines its ownership
|
||||
and validation boundary.
|
||||
|
||||
| Directory | Guide | Role |
|
||||
| --- | --- | --- |
|
||||
| `.github/` | [.github/README.md](.github/README.md) | CI, release automation, reusable actions, and ownership metadata. |
|
||||
| `app/` | [app/README.md](app/README.md) | Firmware applications and integrations. |
|
||||
| `config/` | [config/README.md](config/README.md) | Locked external inputs and checksums. |
|
||||
| `configs/` | [configs/README.md](configs/README.md) | Reproducible build profiles. |
|
||||
| `crt/` | [crt/README.md](crt/README.md) | Freestanding runtime and SDK. |
|
||||
| `docs/` | [docs/README.md](docs/README.md) | Engineering and MISRA policy. |
|
||||
| `fpga/` | [fpga/README.md](fpga/README.md) | FPGA wrapper and board constraints. |
|
||||
| `licenses/` | [licenses/README.md](licenses/README.md) | Third-party notices and license texts. |
|
||||
| `pd/` | [pd/README.md](pd/README.md) | Physical-design entry points. |
|
||||
| `pdk/` | [pdk/README.md](pdk/README.md) | Managed PDK and technology inputs. |
|
||||
| `quality/` | [quality/README.md](quality/README.md) | Executable quality policy and baselines. |
|
||||
| `requirements/` | [requirements/README.md](requirements/README.md) | Pinned Python tool requirements. |
|
||||
| `rtl/` | [rtl/README.md](rtl/README.md) | RTL, testbench, and SoC integration. |
|
||||
| `scripts/` | [scripts/README.md](scripts/README.md) | Build, setup, regression, and quality helpers. |
|
||||
| `sta/` | [sta/README.md](sta/README.md) | Static timing analysis. |
|
||||
| `syn/` | [syn/README.md](syn/README.md) | Synthesis and source export. |
|
||||
| `tests/` | [tests/README.md](tests/README.md) | Host C and Python test suites. |
|
||||
|
||||
Do not create project documentation inside generated/local roots such as
|
||||
`build/`, `.cache/`, `.sw_build/`, or tool caches, or inside managed vendor
|
||||
subtrees. When adding a new Git-tracked first-level directory, add a concise
|
||||
README that states its ownership, source of truth, and validation expectations.
|
||||
|
||||
## Ownership and Architecture
|
||||
|
||||
- `crt/` is the freestanding SDK. Its active layers are `arch/riscv`,
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# Locked Configuration Inputs
|
||||
|
||||
`dependencies.lock.json` is the source of truth for external repositories,
|
||||
archives, checksums, and CI tool bundles. Its digest contributes to every build
|
||||
variant identity.
|
||||
|
||||
Do not add direct downloads to setup scripts or workflow YAML. Update the lock
|
||||
with a full Git revision or verified SHA-256 checksum, validate it with:
|
||||
|
||||
```sh
|
||||
python3 scripts/dependency_lock.py --lock config/dependencies.lock.json
|
||||
```
|
||||
|
||||
Then run the affected setup, doctor, test, and regression flow described in
|
||||
[Engineering Workflow](../docs/engineering.md).
|
||||
@@ -0,0 +1,13 @@
|
||||
# Reproducible Build Profiles
|
||||
|
||||
This directory contains committed Make configuration profiles. Each profile
|
||||
selects SoC, CPU/IP, PDK, ISA, CSR support, application, linker layout, and
|
||||
the supported validation tier.
|
||||
|
||||
`ci/` contains pull-request profiles, `nightly/` adds extended open-source
|
||||
coverage, and `cluster/` contains configurations requiring site tools or PDKs.
|
||||
Start builds from a committed profile rather than setting an unreviewed mix of
|
||||
variables on the command line.
|
||||
|
||||
For supported profiles and commands, see the root [README](../README.md) and
|
||||
[agent contract](../AGENTS.md).
|
||||
@@ -0,0 +1,13 @@
|
||||
# Engineering Documentation
|
||||
|
||||
This directory contains repository-level engineering policy that supplements
|
||||
the root README and subsystem guides.
|
||||
|
||||
- [engineering.md](engineering.md) describes reproducible inputs, build
|
||||
artifacts, result policy, warning baselines, metrics, CI, and releases.
|
||||
- [misra-c-2012.md](misra-c-2012.md) defines the MISRA C:2012 Amendment 2
|
||||
baseline, scope, partial automation, and deviation process.
|
||||
|
||||
Keep policy descriptions here concise and link to executable configuration as
|
||||
the source of truth. Changes that alter process requirements must also update
|
||||
[`AGENTS.md`](../AGENTS.md) when agents need to follow them.
|
||||
@@ -0,0 +1,10 @@
|
||||
# FPGA Integration
|
||||
|
||||
This directory contains FPGA-facing top-level integration for the Mini SoC.
|
||||
`mini/retrosoc_top.sv` is the FPGA top wrapper and
|
||||
`mini/starrysky_v2.xdc` contains board timing and pin constraints.
|
||||
|
||||
FPGA constraints are board-specific implementation inputs, not generic ASIC
|
||||
RTL. Validate changes with the relevant FPGA tool flow and hardware target; do
|
||||
not reuse them as ASIC timing constraints. Follow the RTL and hardware-facing
|
||||
validation requirements in [`AGENTS.md`](../AGENTS.md).
|
||||
@@ -0,0 +1,9 @@
|
||||
# Third-Party License Notices
|
||||
|
||||
This directory stores license texts and notices for bundled third-party source,
|
||||
IP, and tooling dependencies. It complements root-level `LICENSE`, `NOTICE`,
|
||||
and `ATTRIBUTIONS.md`.
|
||||
|
||||
Do not replace, remove, or rewrite a third-party notice when updating a
|
||||
dependency. Add the applicable license and attribution material in the same
|
||||
review as a new bundled component, and preserve upstream license text exactly.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Physical Design Entry Points
|
||||
|
||||
This directory contains physical-design integration entry points. The local
|
||||
Makefile is reserved for implementation flows that require the selected PDK,
|
||||
technology collateral, and often site-specific tools.
|
||||
|
||||
Generated layout, report, and database outputs must remain outside tracked
|
||||
source paths. Treat PDK-dependent physical-design results as toolchain-specific
|
||||
evidence and record the selected profile, PDK, and validation command when
|
||||
handing off a change. See [Engineering Workflow](../docs/engineering.md).
|
||||
@@ -0,0 +1,11 @@
|
||||
# Managed Process Design Kits
|
||||
|
||||
This directory is the integration root for process design kits, technology
|
||||
libraries, SRAM/PLL collateral, and related setup scripts. Most child trees
|
||||
are managed vendor or upstream dependencies rather than ordinary project
|
||||
source.
|
||||
|
||||
Use the dependency lock and PDK setup targets to acquire or update managed
|
||||
inputs. Do not reformat, patch, or delete vendor content as part of unrelated
|
||||
work. PDK changes require the affected synthesis, timing, physical-design, or
|
||||
FPGA validation flow and the ownership review defined by `.github/CODEOWNERS`.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Quality Policy and Baselines
|
||||
|
||||
This directory contains machine-readable quality policy and its supporting
|
||||
documentation.
|
||||
|
||||
- `embedded_c_policy.json` defines self-owned embedded-C exclusions,
|
||||
compatibility files, and prohibited APIs.
|
||||
- `misra/` records approved MISRA deviations; see
|
||||
[MISRA policy](../docs/misra-c-2012.md).
|
||||
- `warnings/` stores reviewed EDA warning baselines.
|
||||
- `metrics/` defines observational metric policy and future gate promotion.
|
||||
|
||||
Do not hand-edit generated warning signatures or promote metric gates without
|
||||
the review process in [Engineering Workflow](../docs/engineering.md). Run the
|
||||
corresponding check after changing quality policy.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Python Tool Requirements
|
||||
|
||||
This directory contains pinned Python requirement sets used by repository
|
||||
automation.
|
||||
|
||||
- `build.txt` provides dependencies for setup, build, and regression helpers.
|
||||
- `ci.txt` provides the fast quality tools, including Python lint and test
|
||||
dependencies.
|
||||
|
||||
Update requirements deliberately and keep their hashes/pins compatible with
|
||||
the repository lock policy. Validate the affected commands locally and in CI;
|
||||
do not add unpinned runtime downloads to scripts.
|
||||
@@ -0,0 +1,14 @@
|
||||
# RTL Design and Simulation
|
||||
|
||||
This directory contains retroSoC SystemVerilog RTL, CPU/IP integration,
|
||||
peripheral and technology wrappers, filelists, testbench support, and the Mini
|
||||
SoC build entry points.
|
||||
|
||||
`mini/` is the active SoC integration flow. `clusterip/` and `ip/` contain
|
||||
managed or generated integration inputs; `filelist/` selects PDK-specific RTL
|
||||
sources; `tech/` contains technology wrappers. Respect managed upstream
|
||||
boundaries and use setup helpers rather than editing generated MPW output.
|
||||
|
||||
RTL changes require an affected firmware build and simulation. Use
|
||||
`make regress-pr` or `make regress-nightly` for supported regression coverage;
|
||||
see [Engineering Workflow](../docs/engineering.md) for results and artifacts.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Build and Quality Scripts
|
||||
|
||||
This directory contains the Python implementation of setup, dependency locking,
|
||||
build manifests, flow execution, simulation checks, regression orchestration,
|
||||
quality checks, metrics, packaging, and cleanup.
|
||||
|
||||
Scripts are part of the build contract. Prefer existing helpers over ad-hoc
|
||||
shell behavior, preserve structured JSON results, and keep setup/download
|
||||
behavior controlled by `config/dependencies.lock.json`.
|
||||
|
||||
Update or add tests in [`../tests`](../tests) for script behavior. Run
|
||||
`ruff check .` and `python3 -m pytest -q`; build-flow changes also require the
|
||||
relevant dry-run or regression profile from [`AGENTS.md`](../AGENTS.md).
|
||||
@@ -0,0 +1,16 @@
|
||||
# Static Timing Analysis
|
||||
|
||||
This directory contains OpenSTA constraints, Tcl setup, and Make integration
|
||||
for retroSoC timing analysis. The selected profile and synthesized netlist
|
||||
define the actual timing context.
|
||||
|
||||
Run synthesis before timing analysis, then invoke the supported OpenSTA flow:
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/hazard3-rv32im-ihp130.mk SYNTH=YOSYS synth
|
||||
make CONFIG=configs/ci/hazard3-rv32im-ihp130.mk STA=OPENSTA sta
|
||||
```
|
||||
|
||||
Review WNS/TNS and warning changes through the generated reports and quality
|
||||
checks. Timing results are PDK/tool/profile dependent; do not compare unrelated
|
||||
variants as a gate.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Synthesis Flows
|
||||
|
||||
This directory contains Yosys synthesis integration, configuration, and source
|
||||
export tooling. `yosys/` owns the supported open-source synthesis flow;
|
||||
`tools/` exports flattened source sets; `demo/` contains examples only.
|
||||
|
||||
Use a committed profile and run the supported flow:
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/hazard3-rv32im-ihp130.mk SYNTH=YOSYS synth
|
||||
```
|
||||
|
||||
Synthesis outputs are generated below `build/` and must not be committed.
|
||||
Review warning and metric changes with `make check-warnings check-metrics` for
|
||||
the affected profile.
|
||||
@@ -0,0 +1,19 @@
|
||||
# Repository Tests
|
||||
|
||||
This directory contains tests for deterministic SDK behavior and build/quality
|
||||
tooling.
|
||||
|
||||
- `c/test_runtime.c` is the host C test program used by `make sw-host-test`.
|
||||
- `test_script_tools.py` covers setup, dependency, filelist, warning, metric,
|
||||
archive, and regression-helper behavior.
|
||||
|
||||
Add a host C test when changing deterministic runtime or media logic; add a
|
||||
Python test when changing scripts or build policy. Run:
|
||||
|
||||
```sh
|
||||
make sw-host-test
|
||||
python3 -m pytest -q
|
||||
```
|
||||
|
||||
These tests complement, but do not replace, firmware builds, RTL simulation,
|
||||
synthesis, timing, or hardware validation.
|
||||
Reference in new issue
Block a user