Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (80 loc) · 4.87 KB

AGENTS.md

File metadata and controls

100 lines (80 loc) · 4.87 KB
Raw

AGENTS.md

Instructions for AI coding agents working in this repository. Keep answers and changes consistent with the rules below. When a rule here conflicts with the current state of the code, trust the code, flag the discrepancy, and update this file.

Project overview

X-HEEP is an open-source, configurable RISC-V microcontroller described in SystemVerilog. The RTL is generated: Python scripts (util/xheep_gen/) expand a configuration (configs/) into Mako templates (*.tpl) that produce the final .sv files. FuseSoC orchestrates hardware builds and simulation; software is built with Make + CMake using a RISC-V cross-compiler.

Repository map

  • configs/ — MCU configuration (HJSON files or Python scripts). Entry point for customization.
  • hw/ — RTL: core-v-mini-mcu/ (SoC top), ip/, ip_examples/, fpga/, asic/, simulation/, system/ (SoC + pad ring), vendor/ (vendored third-party IPs).
  • sw/ — Software: applications, drivers, SDK, linker scripts.
  • tb/ — Testbench (tb_top.sv, testharness.sv) and C++ simulation driver (tb_top.cpp).
  • test/ — Test scripts: test_apps/ (app compile+sim suite), test_x_heep_gen/, verifheep/.
  • util/ — Python tooling: xheep_gen/ (the generator, vendored), vendor.py, c_gen.py, Docker, profiling.
  • scripts/ — Build/simulation helper scripts.
  • docs/ — Sphinx documentation (docs/source/).
  • build/, sw/build/ — Generated build outputs.

Critical rules

  1. Never edit generated files. If a file has a .tpl sibling, it is regenerated by make mcu-gen and edits will be lost. Edit the .tpl instead.
  2. Never edit register-generated files: *_reg_top.sv, *_reg_pkg.sv (generated by OpenTitan regtool from data/*.hjson during FuseSoC runs, not committed) and *_regs.h / *_structs.h in sw/device/lib/drivers/ (generated from the same HJSON or mcu-gen). Edit the data/*.hjson or config instead.
  3. Configuration changes go in configs/, not in generated RTL or headers. After changing any .tpl, config, or configs/ file, re-run make mcu-gen — many files depend on it.

Environment

  • Python deps live in a conda env named x-heep (create once with make conda, then conda activate x-heep). A venv flow also exists via Makefile.venv.
  • RISCV_XHEEP must point to the RISC-V toolchain directory without /bin .
  • There is a Docker image available: make -C util/docker docker-pull && make -C util/docker docker-run (the container provides init_gcc / init_clang / init_corev shell shortcuts that set COMPILER/COMPILER_PREFIX/ARCH).

Common commands

Run make help for the authoritative, up-to-date list of targets and parameters (the Makefile is self-documenting). The essentials:

make mcu-gen                 # generate RTL from config; run after any .tpl/config change
make app PROJECT=hello_world # compile an app (RISC-V cross-compile via CMake)
make verilator-build         # build the Verilator model (once, or after RTL changes)
make verilator-run           # run sw/build/main.hex on the Verilator model
make test                    # synthesize verilator, compile+simulate all apps
make test TEST_FLAGS=--compile-only  # fast: compile all apps only
make compare-mcu-gen         # diff mcu-gen output vs main for testing config/generator changes
make verible                 # format SystemVerilog
make format-python           # format Python (black)

Useful outputs:

  • Firmware: sw/build/main.*
  • App UART output: uart0.log in the sim-verilator directory

Notes

  • Access registers via mmio + generated <name>_regs.h/<name>_structs.h (never hardcode addresses); prefer the SDK layer (sw/device/lib/sdk/) in applications when available.
  • FuseSoC .core files describe filesets/dependencies; the main one is core-v-mini-mcu.core. Do not list generated files in .core filesets.

Vendored code

Vendored code (copies of other repositories) lives in hw/vendor/, sw/vendor/, util/xheep_gen/, hw/fpga/xheep_fpga_support/, each described by a *.vendor.hjson file pinning the upstream URL and commit.

  • For quick testing/debugging you may edit vendored files in place, but tell the user to transfer the change upstream (or to a patch) before merging. Then update the rev in the *.vendor.hjson and run make vendor-update. CI re-vendors and rejects any uncommitted in-place edits.
  • Small change in a repo we don't control (hard to upstream): add a patch under hw/vendor/patches/<org>_<repo>/ and set patch_dir in the *.vendor.hjson.
  • Never edit *.lock.hjson (generated by util/vendor.py).

Documentation

  • Getting started / setup: docs/source/GettingStarted/
  • Configuration (xheep_gen): docs/source/Configuration/
  • How-to guides (simulators, debugging, FPGA, flash): docs/source/How_to/
  • Extending HW/SW: docs/source/Extending/
  • Testing: docs/source/Testing/