agentleFS
vortexgpgpuvortexgpgpu/vortex/AGENTS.md

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

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 1 mentionApr 2026: 0 mentionsMay 2026: 1 mentionJun 2026: 0 mentionsJul 2026: 1 mentionAug 2026: 0 mentionsSep 2026: 1 mentionOct 2026: 1 mentionNov 2026: 1 mention
Dec 2025Jun 2026Nov 2026
Mentions a month of the vortexgpgpu/vortex repository that our weekly crawl found: only 13 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Who's talking about vortexgpgpu/vortex

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

6 more on GitHub

On Hacker News · 2

  • 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.

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
  1. Distinctive:

    Keep smoke/regression runs lean: Don't enable debug or perf collection unless the run is explicitly for debug or measurement.

    line 87
  2. Very specific:

    RTL coverage path is xrt, not rtlsim: When discussing or planning RTL verification, xrt is the canonical path — rtlsim bypasses the AFU …

    line 88
  3. Distinctive:

    Default to no comment: Add one only when the *why* is non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific …

    line 156
  4. Very specific:

    No // removed code or stale-rename breadcrumbs: If something is unused, delete it.

    line 162
  5. Distinctive:

    Add a rule: when you discover a footgun the next contributor will hit.

    line 170
  6. Distinctive:

    Branch-specific addenda are forbidden: No branch-local AGENTS.md variants: if a rule is general, promote it here.

    line 173

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.
  • configure generates a runnable tree by copying and instantiating ci/, runtime/, sim/, and tests/ into build/. For execution and test automation, always prefer the generated scripts/Makefiles under build/ over the source-tree .in files.
  • Re-../configure from build/ whenever you git pull, edit source Makefiles, edit VX_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 ../configure from build/ first. configure regenerates <build>/sw/VX_config.h and <build>/hw/*.vh from VX_config.toml, but only when the toml is newer (it guards on mtime). The simx/RTL cores #include this 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 stale VX_config.h once 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.
  • ccache can serve stale objects on fmt-version mismatches (typical symptom: fmt::v8 undefined-reference link errors in sim builds). Before deep-diving, retry with CCACHE_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 fresh TOOLDIR) downloads prebuilt binary tarballs from the vortex-toolchain-prebuilt repository at the tag pinned in VERSION (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 to vortex-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 generated ci/ scripts assume it.
  • CONFIGS must match on both sides. blackbox.sh only 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=8
  • make tests / make -C tests/regression build with default macros. Use CONFIGS + explicit per-app rebuild for non-default configurations.
  • There is no --rebuild option. blackbox.sh re-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, not rtlsim. When discussing or planning RTL verification, xrt is the canonical path — rtlsim bypasses the AFU surface. rtlsim remains useful for fast iteration on processor RTL; xrt is what proves the full integration.
  • ci/regression.sh is 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 by pytest ci -m perf_gate --update-baselines (a human-run, reviewed step), and CI must never pass that flag. A perf_gate failure 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 and known_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 running ci/fpga_gate.py --update-baseline / ci/asic_gate.py --update-baseline / ci/logic_gate.py --update-baseline, never by CI. A red fpga_gate/asic_gate means real Fmax or area moved; a red logic_gate means a unit got deeper or the design's area grew past 5 %, and its reasons name the unit or the resource (beacon_area.txt has the area by unit and each memory's placement). Note the two gates measure the same hw/unittest/*/VX_*_top.sv wrappers through different flows, so a divergence between them is a finding, not noise — keep hw/syn/{xilinx,yosys}/dut/catalog.mk in 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_gate would find, hours later. Beacon finds them in minutes, so iterate on it, not on Vivado or Yosys: run ci/logic_gate.py -b <dut> on the parent revision once (its own build tree, e.g. git worktree add ../ref HEAD and --build-dir build32_beacon_ref), then ci/logic_gate.py -b <dut> --against build32_beacon_ref after each edit, and fix what <build>/beacon_diff.txt reports until nothing fails (ci/beacon.py paths shows a deep unit's paths op by op). Run synthesis once per change, on the DUTs whose depth moved, and feed the result back with ci/beacon.py validate. A change to the cluster, socket, L2 or anything only the whole GPU assembles also runs the gpu group (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.txt also 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_gate runs with perf_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 with ci/logic_gate.py --update-baseline on the final tree, with the reason in the commit message. A change of CIRCT or foldsim reads STALE and 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_parity CI gate enforces this: a check: model_parity case (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-rtlsim

Architecture 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 --l2cache

OR

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_tcu

Roofline 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.png

5. 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.tcl sets each floating_point IP's C_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 with Full_Usage), divide 28, square root 28, multiply 8, add 11. xil_fma, xil_fdiv, xil_fsqrt and the TCU's xil_fmul/xil_fadd already use them, so FMA with Full_Usage (more DSPs) is the only headroom left.
    • A change must move together: C_Latency, the matching VX_CFG_*_LATENCY in VX_config.toml (checked by the STATIC_ASSERTs in hw/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 SimObject may observe or mutate another module's state only via its bound SimChannel ports (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 global Memory). 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}/ and sim//hw/ are bidirectionally isolated. Source files under sw/kernel/ and sw/runtime/ MUST NOT reference anything in hw/* or sim/*. Equally, source files under sim/* and hw/* MUST NOT reference anything in sw/kernel/ or sw/runtime/. If the layers genuinely need to share host-side helper code or an on-wire ABI definition, put it in sw/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_PKGS is for VX_*_pkg.sv only. Verilog interfaces are illegal there. If an interface isn't being discovered, fix it via include paths or file naming — not by stuffing it into RTL_PKGS.
  • Library RTL defaults to TRACING_OFF. Modules under hw/rtl/libs/ are excluded from VCD by default to keep waveform size manageable. Toggle per-file with TRACING_ON/TRACING_OFF, or globally with CONFIGS="-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 code or 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.md variants: if a rule is general, promote it here; project-tracking details stay out of the repo docs.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.