Engineering workflow / small verified changes

Contribute to Proton NPU

A map of the source tree, the supported build environment, and the checks that protect the working hardware milestone.

Pinned upstream IPReviewable patchesExplicit verification gates

Find the right layer

Location	Responsibility
`hardware/matrix/`	Our buffers, controller, bus target and command router
`hardware/matrix/vendor/`	Pinned compute RTL with original notices
`patches/ara/`	Reviewable Vector build, decoder and SoC integration changes
`patches/cva6/`	CPU ordering and accelerator bookkeeping changes
`examples/`	C applications, RVV intrinsics, matrix API and test startup
`tests/matrix/`	Independent arithmetic oracle and standalone RTL testbenches
`scripts/`	Provision, build, run and evidence-validation entry points
`verification/`	Small, committed verification records; raw runs stay local
`docs/`	This HTML guide, SVG diagrams and Markdown technical notes

Start with a working baseline

git clone --branch hardware https://github.com/cerebralchips/proton-npu.git
cd proton-npu

# Apple Silicon: create/start the Linux build VM
./scripts/ara vm-start
./scripts/ara provision
./scripts/ara doctor

# Verify the complete hardware and software path
./scripts/ara matrix

The supported tool profile is Ubuntu 24.04 ARM64. Apple Silicon uses Lima; ARM64 Linux can run the wrapper directly. Fresh provisioning builds the pinned runtime toolchain when one is not supplied. Existing users can provide ARA_GCC_ROOT.

Environment and prerequisites ↗Agent and contributor rules ↗Contribution checklist ↗

Keep the verification gates intact

Change one layer at a time. Keep a scalar arithmetic reference independent of the RTL schedule.
Run standalone gates. ./scripts/ara matrix-unit checks arithmetic, bus behavior and routing.
Run the combined ELF. ./scripts/ara matrix checks actual retired instructions and results.
Check integration regressions. Use matrix-smoke, matrix-negative and the original smoke.
Inspect waveforms when changing timing. matrix-wave independently checks every tile from RTL signals.
Update documentation and evidence. Preserve failed logs; state exactly what has passed.

Work on documentation

Edit the HTML files and SVG diagrams directly; no web framework, CDN or JavaScript build is required. Open docs/index.html locally, or serve the repository with python3 -m http.server 8000 and browse /docs/.

python3 tests/repository/check.py
python3 -m http.server 8000

The lightweight repository CI checks source packaging, documentation links and deterministic workload data. Full RTL verification remains a separate, explicit command and is not implied by that CI badge.