Repository navigation
Description
Timing and utilisation hints in the editor: show what a line of a hardware spec costs in LUTs, flip-flops and DSPs and where the long path is, without leaving the file. No language server does this today; it is an open lane. t27 has the numbers: Yosys reports per-cell LUT counts (skill yosys baseline) and the FPGA lanes (AX7203, xc7a200t) report critical paths. The module turns those reports into code lenses and inlay hints and says plainly which are measured, which are estimated, and which are unknown. Part of the LSP epic, Refs #12209 (wave 3, hardware). Only .t27: no code in any other language, not even scratch probes or a loader; see skill only-t27.
Depends on specs/lsp/lens.t27, specs/lsp/inlay.t27 and specs/lsp/hdl_hierarchy.t27. Synthesis runs on the lab or in CI, never on the Mac; this module only reads the reports.
Prior art:
- Sigasi Studio: design hierarchy and some resource hints: https://www.sigasi.com/
- TerosHDL: schematic viewer and FSM viewer from the synthesised design: https://terostechnology.github.io/terosHDLdoc/
- Vivado utilisation and timing reports as the source numbers: https://docs.amd.com/
Boundary
- specs/lsp/hw_hints.t27
User Scenarios
- Given a synthesis report for a module is available, when the lens request arrives, then the module header shows
LUT 5767 | FF 812 | DSP 0and each label saysmeasuredwith the report's commit. - Given no report exists, when the lens request arrives, then the lens says
not measuredwith the command that would produce one, and no number is shown. - Given a timing report names the critical path, when the file is opened, then the cells on that path get an inlay hint
+1.8 nsand the slack is shown at the top. - Given the source changed after the report was made, when the lens is shown, then every number is marked
staleand the report's content hash is compared to the spec's. - Given an estimate rule (a multiplier of width w costs about w*w/4 LUTs, flagged
estimate), when no measurement exists and the settinghw.estimatesis on, then the number is shown with the labelestimate, never without it.
Requirements
- FR-001: Each number MUST carry one of the labels
measured,estimateorunknown, and a test asserts that no code path produces a number without a label. - FR-002: The module MUST read the report format the repository already produces (a
.t27data record or JSON written byt27c), through a seam so tests use a fixture, and MUST NOT run synthesis. - FR-003: The module MUST map report cells to source ranges through the generated source map, and MUST report the fraction of cells it could map.
- FR-004: Staleness MUST be decided by comparing the content hash recorded in the report to the hash of the spec at the cell's module, not by file times.
- FR-005: Estimates MUST be off by default, and each estimate rule MUST cite the measurement that justified it.
Success Criteria
- At least 25 tests in
specs/lsp/hw_hints.t27pass, run on the lab witht27c test-report(exit 0), including the stale case and the no-label-no-number test. - On the lab the module runs against one real report; the mapped-cell fraction and the command are pasted in the issue.
git diff --name-only masterlists onlyspecs/lsp/hw_hints.t27(0 files in other languages).
Activity
gHashTag commentedon Nov 17, 2026
LSP spec created (typecheck OK, tests pass).