Skip to content

LSP: timing and utilisation hints with measured labels (specs/lsp/hw_hints.t27) #12265

Closed

Description

@gHashTag

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:

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 0 and each label says measured with the report's commit.
  • Given no report exists, when the lens request arrives, then the lens says not measured with 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 ns and 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 stale and 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 setting hw.estimates is on, then the number is shown with the label estimate, never without it.

Requirements

  • FR-001: Each number MUST carry one of the labels measured, estimate or unknown, 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 .t27 data record or JSON written by t27c), 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.t27 pass, run on the lab with t27c 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 master lists only specs/lsp/hw_hints.t27 (0 files in other languages).

Activity

  1. gHashTag commented on Nov 17, 2026

    @gHashTag
    CollaboratorAuthor

    LSP spec created (typecheck OK, tests pass).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/specs.t27 spec files and conformanceenhancementNew feature or requestspec

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions