vortex
AGENTS.md2.4k starsChanged 7 days agoApache-2.0View on GitHub
This is the canonical entry point for both human contributors and AI coding agents working on Vortex. It captures the rules — invariants, conventions, and footguns — that every change should respect. Build/test/debug recipes live in the topic docs linked below. See docs/install_vortex.md for the full recipe. The non-negotiable rules:
Trending
More talk lately.thin dataabout the whole repository
Who's talking about vortexgpgpu/vortex
- A Hacker News story“Open source RISC-V GPGPU”Hacker News · Nov 30, 2021 · 207 points
- A Hacker News story“Vortex RISC-V Gpgpu”Hacker News · Oct 22, 2021 · 3 points
- hughperkins/VeriGPU“Network on a Chip (NoC) implementation”GitHub · Apr 7, 2022 · 1 reactions
- vortexgpgpu/mesa“Clarifying current gfx status and some graphic driver issues”GitHub · Nov 10, 2026
- Luminous-Dynamics/symthaea“docs(computers): define shared phone laptop CPU GPU frontier”GitHub · Oct 22, 2026
The biggest 5 of 13 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 13
Talked about on GitHub and Hacker News (13 times).
On GitHub · 11
- Apr 7, 2022Network on a Chip (NoC) implementation — hughperkins/VeriGPU1 reaction · 3 comments
- Nov 10, 2026Clarifying current gfx status and some graphic driver issues — vortexgpgpu/mesa0 reactions
- Oct 22, 2026docs(computers): define shared phone laptop CPU GPU frontier — Luminous-Dynamics/symthaea0 reactions
- Sep 15, 2026Support Vortex RISC-V GPGPU — vishruth-thimmaiah/segfault260 reactions · 1 comment
- Jul 7, 2026Assigment 4 Unable to Locate Files — vortexgpgpu/vortex_tutorials0 reactions
6 more on GitHub
- May 9, 2026Vortex 相关 — cisen/blog0 reactions
- Mar 4, 2026Add Vortex GPGPU — VLSIDA/HighTide0 reactions
- Oct 21, 2025Conflicting names between Matrix Jobs — Udit8348/gha-workflows0 reactions
- Oct 18, 2025[GPGPU] SIMT-based accelerator thread — squeakbug/soc-build0 reactions
- Oct 16, 2025Build PoCL for vortex from source — vortexgpgpu/pocl0 reactions · 2 comments
- Oct 12, 2024Any link_design equivalent or alternative? — YosysHQ/yosys0 reactions · 2 comments
On Hacker News · 2
- Nov 30, 2021Open source RISC-V GPGPU207 points · 58 comments
- Oct 22, 2021Vortex RISC-V Gpgpu3 points
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository4 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- code-reviewSkill
- rtl-reviewSkill
- simx-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 87
Keep smoke/regression runs lean: Don't enable debug or perf collection unless the run is explicitly for debug or measurement.
- Very specific: line 88
RTL coverage path is
xrt, notrtlsim: When discussing or planning RTL verification, xrt is the canonical path — rtlsim bypasses the AFU … - Distinctive: line 156
Default to no comment: Add one only when the *why* is non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific …
- Very specific: line 162
No
// removed codeor stale-rename breadcrumbs: If something is unused, delete it. - Distinctive: line 170
Add a rule: when you discover a footgun the next contributor will hit.
- Distinctive: line 173
Branch-specific addenda are forbidden: No branch-local AGENTS.md variants: if a rule is general, promote it here.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS Guide for Vortex GPGPU Development
This is the canonical entry point for both human contributors and AI coding agents working on Vortex. It captures the rules — invariants, conventions, and footguns — that every change should respect. Build/test/debug recipes live in the topic docs linked below.
1. Documentation Map
Setup & build
- docs/install_vortex.md — initial install + build setup
- docs/building_toolchain.md — building Verilator, RISC-V GNU, LLVM, compiler-rt, musl, POCL, CIRCT, Foldsim from source
- docs/environment_setup.md — environment variables and toolchain layout
- docs/fpga_setup.md — FPGA target setup
Codebase orientation
- docs/codebase.md — repo file-tree map
- docs/designs/microarchitecture.md — pipeline & cache architecture
- docs/designs/cache_subsystem.md — cache subsystem details
- docs/hardware_library.md —
hw/rtl/libs/reference
Coding conventions
- docs/coding_guidelines_cpp.md — C++ style
- docs/coding_guidelines_verilog.md — Verilog/SystemVerilog style
Simulation & test
- docs/simulation.md — driver modes (simx, rtlsim, opae, xrt) and blackbox usage
- docs/testing.md — test and regression flow
- docs/debugging.md — debug traces (
--debug), VCD (--vcd), scope, trace_csv - docs/kernel_debugging.md — debug-mode hardware support (GDB/OpenOCD)
- docs/perfetto_analysis.md — Perfetto trace and analysis
- docs/synthesis_analysis.md — synthesis/PPA analysis
Process
- CONTRIBUTING.md — public fork/PR contribution flow and the
<type>/<name>branch naming types - docs/bug_fixes.md — bug-fix discipline (root-cause vs patch)
- docs/review/code-review-policy.md — change-impact classes (R0-R3), review obligations and waivers
- docs/continuous_integration.md — CI pipeline
- docs/designs/ — accepted designs (implemented)
2. Build & Toolchain Rules
See docs/install_vortex.md for the full recipe. The non-negotiable rules:
- Out-of-tree. From the repo root:
mkdir -p build && cd build ../configure --xlen=32 --tooldir=$HOME/tools # or --xlen=64 ./ci/toolchain_install.sh # first time only make -s - Separate build dirs per major variant (
build32/,build64/,build_fpga64/, ...) to avoid config/tool contamination. Never reuse one build dir for incompatible configurations. configuregenerates a runnable tree by copying and instantiatingci/,runtime/,sim/, andtests/intobuild/. For execution and test automation, always prefer the generated scripts/Makefiles underbuild/over the source-tree.infiles.- Re-
../configurefrombuild/whenever yougit pull, edit source Makefiles, editVX_config.toml/ any*.toml, or add/remove a build-participating directory. Symptom of forgetting this: stale binaries, missing targets, or "I edited this Makefile and nothing happened." - Always ensure the build is current before running any test or app — re-run
../configurefrombuild/first.configureregenerates<build>/sw/VX_config.hand<build>/hw/*.vhfromVX_config.toml, but only when the toml is newer (it guards on mtime). The simx/RTL cores#includethis generated header, so a stale header makes a core compile against old config values and silently diverge from the toml — and from the runtime/RTL, which re-expand the config every build. This is a real footgun: a staleVX_config.honce made SimX run a write-back D-cache while the toml/RTL were write-through, producing SimX-only wrong results. Never work around such a divergence by injecting-DVX_CFG_*overrides into a Makefile — that masks the stale artifact and fights the config system. The toml is the single source of truth; fix it by re-configure-ing. ccachecan serve stale objects onfmt-version mismatches (typical symptom:fmt::v8undefined-reference link errors in sim builds). Before deep-diving, retry withCCACHE_DISABLE=1.- Toolchain changes must ship through
vortex-toolchain-prebuilt. Vortex never builds its toolchain components from source:ci/toolchain_install.sh(used by CI and by every freshTOOLDIR) downloads prebuilt binary tarballs from thevortex-toolchain-prebuiltrepository at the tag pinned inVERSION(TOOLCHAIN_REV), resolved at run time. So any change to a component packaged there (mesa, pocl, LLVM, RISC-V GNU, libc/libcrt, Verilator, ...) is invisible to Vortex until the corresponding tarball is repackaged, committed tovortex-toolchain-prebuilt, and the pinned tag is moved — pushing the component's source repo alone does nothing for CI. Landing order for a coupled change: component source repos first, then the prebuilt refresh (tarballs + tag push), then the Vortex push last, immediately after, so the CI run the Vortex push triggers already downloads matching binaries.
3. Bug-Fix Rules
See docs/bug_fixes.md for the full rationale and examples. The rules:
- Fix root causes, not symptoms. Diagnose before patching.
- Don't paper over upstream regressions or mask bugs with fallback paths and suppressed warnings.
- A perf, area or timing regression is fixed in the commit that caused it, or justified on that commit's terms with proof that the cost is inherent; never by improving another part of the system. Attribute every regressed case to a commit before writing any fix (docs/bug_fixes.md §6).
- Don't add legacy API compatibility or fallback code unless it is explicitly required for the change.
- If a patch is genuinely unavoidable (e.g. blocked by an external dep), label it as a patch explicitly in the commit message and pair it with a follow-up to do the proper fix.
4. Testing & Verification Rules
See docs/testing.md and docs/debugging.md for recipes. The rules:
- All test commands run from
build/. The generatedci/scripts assume it. CONFIGSmust match on both sides.blackbox.shonly rebuilds the driver. If your test was compiled with-DVX_CFG_NUM_THREADS=4, blackbox can't fix that — rebuild the app first:make -C tests/regression/<app> clean CONFIGS="-DVX_CFG_NUM_THREADS=8 -DVX_CFG_EXT_TCU_ENABLE" make -C tests/regression/<app> CONFIGS="-DVX_CFG_EXT_TCU_ENABLE" ./ci/blackbox.sh --driver=simx --app=<app> --threads=8make tests/make -C tests/regressionbuild with default macros. UseCONFIGS+ explicit per-app rebuild for non-default configurations.- There is no
--rebuildoption.blackbox.shre-makes the driver on every run, and make rebuilds it on any source or flag change. - Keep smoke/regression runs lean. Don't enable debug or perf collection unless the run is explicitly for debug or measurement.
- RTL coverage path is
xrt, notrtlsim. When discussing or planning RTL verification,xrtis the canonical path —rtlsimbypasses the AFU surface.rtlsimremains useful for fast iteration on processor RTL;xrtis what proves the full integration. ci/regression.shis the canonical source of tested configurations. Use it to discover supported parameter combinations before inventing ad hoc ones.- Perf-regression baselines (
ci/baselines/perf/*.json) are golden data — never hand-edit them, and never "fix" a red perf gate by bumping the number. They are regenerated only bypytest ci -m perf_gate --update-baselines(a human-run, reviewed step), and CI must never pass that flag. Aperf_gatefailure means real cycles moved: root-cause it, or — if the change is intended — regenerate the baseline so the diff shows the perf delta for review. Same rule as image goldens andknown_issue:. - Synthesis baselines (
ci/baselines/synthesis/{xilinx,yosys,beacon}/*.json) are golden data under the same rule — never hand-edited, regenerated only by a human runningci/fpga_gate.py --update-baseline/ci/asic_gate.py --update-baseline/ci/logic_gate.py --update-baseline, never by CI. A redfpga_gate/asic_gatemeans real Fmax or area moved; a redlogic_gatemeans a unit got deeper or the design's area grew past 5 %, and its reasons name the unit or the resource (beacon_area.txthas the area by unit and each memory's placement). Note the two gates measure the samehw/unittest/*/VX_*_top.svwrappers through different flows, so a divergence between them is a finding, not noise — keephw/syn/{xilinx,yosys}/dut/catalog.mkin step when you add or rename a DUT. See docs/designs/continuous_integration.md §3.5. - Beacon first for any RTL change that can move timing; synthesis only to confirm. A change to a pipeline, arbiter, queue, interface or datapath can add logic levels that only the nightly
fpga_gatewould find, hours later. Beacon finds them in minutes, so iterate on it, not on Vivado or Yosys: runci/logic_gate.py -b <dut>on the parent revision once (its own build tree, e.g.git worktree add ../ref HEADand--build-dir build32_beacon_ref), thenci/logic_gate.py -b <dut> --against build32_beacon_refafter each edit, and fix what<build>/beacon_diff.txtreports until nothing fails (ci/beacon.py pathsshows a deep unit's paths op by op). Run synthesis once per change, on the DUTs whose depth moved, and feed the result back withci/beacon.py validate. A change to the cluster, socket, L2 or anything only the whole GPU assembles also runs thegpugroup (ci/logic_gate.py -b gpu -j 1, ~30 min and ~95 GB per build). A unit that gets deeper is fixed or, if intended, re-recorded with the reason in the commit message.beacon_diff.txtalso lists each resource of the design (LUT, FF, distributed and block RAM, DSP) and the units whose area moved, so a memory that leaves block RAM shows in minutes. Beacon does not see wires, placement or congestion; a change that moves those still needs synthesis. See docs/designs/beacon.md §6.3. logic_gateruns withperf_gate, and is treated the same way. CI plans its cell whenever it plans perf_gate's rtlsim cells (every pull request, every push that touches the RTL or the config): perf_gate guards cycles, logic_gate guards logic depth and area. A red logic_gate means a unit got deeper or the design grew; fix it, or re-record withci/logic_gate.py --update-baselineon the final tree, with the reason in the commit message. A change of CIRCT or foldsim readsSTALEand needs the same re-record.- SimX is the RTL's timing model — keep them in lockstep. Any change that moves RTL cycles (pipeline structure, arbitration, queue depths, cache/memory behavior) must land together with the matching SimX timing-model update, and vice-versa. The
model_parityCI gate enforces this: acheck: model_paritycase (ci/testcases/core.yaml+ per-extension parity categories) runs the same app/args/configs on simx and rtlsim and asserts exact retired-instruction match plus cycle agreement within the case tolerance (default 5%). Never widen a tolerance to absorb a divergence — model the behavior. When adding a hardware feature, add or extend a parity case that exercises it. - When RTL debugging stalls, switch to the SimX-as-oracle pattern. For numerical bugs, deep pipeline races, or any failure mode where rtlsim is "close but wrong": (1) build/extend the SimX C++ model so it mirrors the new RTL architecture and gets to PASS; (2) add matching trace dumps to both SimX and RTL (cycle, FU events, SRAM addresses+data, hazards) — same CSV format on both sides; (3) diff trace files — the first divergence is the bug. Don't keep guessing from output values; localize via trace diff. See docs/debugging.md.
Smoke tests
./ci/blackbox.sh --driver=simx --app=demo
./ci/blackbox.sh --driver=simx --app=sgemm --args="-n16"Regression suites
make -C tests/regression run-simx
make -C tests/regression run-rtlsim
make -C tests/opencl run-simx
make -C tests/opencl run-rtlsimArchitecture overrides
blackbox.sh exposes the common knobs directly: --clusters=, --cores=, --warps=, --threads=, --l2cache, --l3cache, --debug=, --vcd, --perf=. For anything not exposed as a flag, use CONFIGS="-D..." (all parameters take the VX_CFG_* prefix — e.g. -DVX_CFG_NUM_THREADS=8, -DVX_CFG_EXT_TCU_ENABLE). Baseline parameters live in VX_config.toml and VX_types.toml at the repo root — edit those only when an override is needed for all builds, and re-configure afterward.
./ci/blackbox.sh --driver=simx --app=sgemm --clusters=1 --cores=2 --warps=4 --threads=4 --l2cacheOR
CONFIGS="-DVX_CFG_NUM_THREADS=4 -DVX_CFG_EXT_TCU_ENABLE -DVX_CFG_TCU_TYPE_TFR -DITYPE=bf16 -DOTYPE=fp32" ./ci/blackbox.sh --driver=rtlsim --app=sgemm_tcuRoofline Analysis
ci/roofline.py runs a kernel via blackbox.sh, optionally sweeps microarchitecture knobs to maximize IPC (--config=fast|random|best, comma-lists as search spaces), and plots a FLOP/cycle roofline. Run it from a configured build directory. --perf=7 (the default) is required for the memory-traffic counters that place the measured point; pass the kernel's total FLOPs via --flops. The default compute roof models the scalar FPU — for TCU kernels pass --peak-flops explicitly.
python3 ci/roofline.py --app=sgemm --driver=simx --args="-n128" --flops=4194304 \
--cores=1 --warps=4 --threads=8 --issue-width=2 --plot --output=sgemm_roofline.png5. Design & Architecture Rules
- Align with mainstream CUDA, HIP, OpenCL, and Vulkan API and driver stacks. For any design question — driver surface, command-processor model, memory model, scheduling — pick the solution those stacks would use. This keeps Vortex's externals familiar to mainstream software and avoids one-off abstractions.
- Vivado floating-point IP latency is an Fmax knob, and it is already at its maximum.
hw/scripts/xilinx_ip_gen.tclsets eachfloating_pointIP'sC_Latency. More cycles means more internal pipelining, up to a per-operation maximum; Vivado rejects any value above it.- The single-precision maxima on V80 and U55C are: FMA 16 (
Medium_Usage; 19 withFull_Usage), divide 28, square root 28, multiply 8, add 11.xil_fma,xil_fdiv,xil_fsqrtand the TCU'sxil_fmul/xil_faddalready use them, so FMA withFull_Usage(more DSPs) is the only headroom left. - A change must move together:
C_Latency, the matchingVX_CFG_*_LATENCYinVX_config.toml(checked by theSTATIC_ASSERTs inhw/rtl/fpu/VX_f*_unit.sv), and the SimX timing that reads it. - This applies only to
FPU_TYPE_DSP. The STD FPU's div/sqrt latency is fixed by its SRT stage count, and only its FMA latency is configurable.
- SimX Cardinal Rule — modules communicate only through channels. A
SimObjectmay observe or mutate another module's state only via its boundSimChannelports (MemReq/MemRsp,result_if, …). Never reach across the ownership hierarchy to touch another object directly (core_->processor()->memsim(),parent()->child()->field, a leaf unit grabbing the globalMemory). See docs/designs/simobject.md.
6. Coding Conventions
See docs/coding_guidelines_cpp.md and docs/coding_guidelines_verilog.md for full style. Cross-cutting comment rules:
sw/{kernel,runtime}/andsim//hw/are bidirectionally isolated. Source files undersw/kernel/andsw/runtime/MUST NOT reference anything inhw/*orsim/*. Equally, source files undersim/*andhw/*MUST NOT reference anything insw/kernel/orsw/runtime/. If the layers genuinely need to share host-side helper code or an on-wire ABI definition, put it insw/common/— vortex-internal, never installed, accessible from all four layers. Enforced by ci/check_sw_sim_boundary.sh.- Default to no comment. Add one only when the why is non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific bug, a surprising behavior.
- Comments explain why, not what. Well-named identifiers carry the what.
- Never reference the current task, PR, caller, issue number, or fix. Those belong in the commit message and rot in code. Don't write
// used by foo(),// added for the X flow,// handles issue #123. RTL_PKGSis forVX_*_pkg.svonly. Verilog interfaces are illegal there. If an interface isn't being discovered, fix it via include paths or file naming — not by stuffing it intoRTL_PKGS.- Library RTL defaults to
TRACING_OFF. Modules underhw/rtl/libs/are excluded from VCD by default to keep waveform size manageable. Toggle per-file withTRACING_ON/TRACING_OFF, or globally withCONFIGS="-DTRACING_ALL". - No multi-paragraph docstrings or multi-line block comments for trivial code. One short line is the ceiling unless the logic genuinely needs more.
- No
// removed codeor stale-rename breadcrumbs. If something is unused, delete it.
7. Living Document Policy
This file is versioned alongside the code and evolves with it. Both humans and agents are expected to update it:
- Add a rule when you discover a footgun the next contributor will hit. Include the why.
- Update or remove a rule that's gone stale. A stale rule is worse than no rule.
- Don't duplicate content from the topic docs in
docs/. AGENTS.md links; the topic doc explains. - Branch-specific addenda are forbidden. No branch-local
AGENTS.mdvariants: if a rule is general, promote it here; project-tracking details stay out of the repo docs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

