GSys LibreCore — a source-available RISC-V core and agentic build platform, derived from OpenHW CVA6. Explore the layered architecture.
sv-timingOverview

sv-timing

sv-timing/ is a project-independent Rust package that compiles an explicit list of SystemVerilog sources into a timing-oriented intermediate representation (IR), ranks combinational paths against a FO4-style budget and a caller-supplied target frequency, and optionally applies allowlisted auto-correct transforms that re-emit SystemVerilog with edit traces.

It exists to give designers early, source-level structural feedback before synthesis and static timing analysis (STA). Functionally correct RTL can still be hostile to a high-frequency target; long combinational clouds, expensive operators, and weakly explicit sequencing typically surface only after STA, when restructuring is expensive.

Disclaimer: FO4 numbers and path ranks are structural estimates only. They do not replace STA, SDF, place-and-route, or foundry sign-off. See sv-timing/architecture/STA-HANDOFF.md for the handoff contract.

Independence (hard requirement)

The package builds, tests, and analyzes with only the sv-timing/ tree and its fixtures. It has no compile- or link-time dependency on CVA6 RTL, build-platform, monorepo flists, edaEnv, or SoC config packages.

Hosts (optional)                    Package (standalone)
─────────────────                   ────────────────────
flist / defines / MHz               parse → IR → FO4
param-map / cache path         →    path rank / report
spawn CLI / rehydrate JSON     ←    optional correct + emit

Hosts prepare inputs and consume outputs. They never pull monorepo code into the crate graph. The CVA6 monorepo adapter is the build-platform timings command; see Host Integration and Build Platform · Timings.

What it owns vs what hosts own

Package ownsHosts own
Parse (vendored sv-parser) → timing IRProject discovery (Bender, FuseSoC, EDA flists)
FO4 cost model (resources/fo4-v1.toml)Defines, include dirs, target MHz
Path ranking, opportunitiesModule roots / --all-modules
Optional auto-correct + emitFlatten env-heavy flists → portable .f
SQLite CRC cache (caller-chosen path)Where to put reports / corrected trees
Versioned JSON schemaReview before pointing sim/synth at emit

Entry points

From sv-timing/ (Python-first tooling under tools/):

python tools/svt.py setup      # contained rustup/cargo + venv
python tools/svt.py doctor
python tools/svt.py build
python tools/svt.py test
python tools/svt.py check      # independence + fmt + clippy + test
python tools/svt.py run -- --help   # cargo run -p sv-timing-cli

Thin wrappers svt.sh / svt.ps1 only invoke tools/svt.py; business logic stays in Python and Rust.

From the monorepo (host):

./build.sh timings status
./build.sh timings flist --target <cfg>
./build.sh timings analyze --modules alu --target-mhz 1250
./build.sh timings correct --modules alu --allow-latency --emit

Non-goals

  • Replacing STA or foundry sign-off
  • Full IEEE 1800 elaboration in v1
  • Synthesis, place, or route
  • Auto-merging corrected RTL into core/ without human review
  • Absolute FO4 CI gates as hard fails until the model is trusted
  • Owning monorepo flist expansion inside the crates

Authority and deeper reading

ArtifactRole
sv-timing/AGENTS.mdAgent entry + invariants
sv-timing/ALGORITHMS-EXPERTS.mdPer-algorithm expert manual
sv-timing/architecture/DESIGN.mdFull architecture (IR, cache, hosts)
sv-timing/architecture/OPTIMIZATION-LEVELS.md-O0..-O3/-Os/-Oz + dials
sv-timing/architecture/PERF-CACHE.mdThroughput + pre-compiled cache
sv-timing/AGENTS-host.mdHost boundary
sv-timing/AGENTS-todo.mdLive implementation phase
architecture/sv-timing/Monorepo pointer only

Reading order for contributors

  1. sv-timing/AGENTS.md — the package map and its invariants (independence, host boundary, no monorepo deps).
  2. sv-timing/ALGORITHMS-EXPERTS.md — the expert manual. Part 0 defines the architectural objects (Budget, Path, Class, Lane, Pass stage), the strategic / emit / remaining-gap invariants, and an implementation file map. Part I covers the timing basis: A1 budget FO4, A2 the fo4-v1 cost table, A3 inverse max-frequency, A4 measurement versioning. Later parts repeat one skeleton per algorithm: summary, low-level basics, high-level basis, purpose, mutations, behavioural study, maintenance.
  3. The architecture docs — DESIGN.md, OPTIMIZATION-LEVELS.md, RELOCATION-ANALYSIS.md, FREQUENCY-CLOSURE.md, PERF-CACHE.md, STA-HANDOFF.md.

The budget model is budget_fo4 = (1000/target_mhz × 1000/fo4_ps) × (1 − margin); with the defaults fo4_ps=20 and margin=0.2 that is ~32 FO4 at 1250 MHz and ~20 FO4 at 2000 MHz. --fo4-ps is a process input — quote it with every frequency claim, since it scales the whole budget linearly.

Pages in this section

Extending the PlatformPipeline & IR