Repository navigation
Closed
Labels
area/specs.t27 spec files and conformance.t27 spec files and conformanceenhancementNew feature or requestNew feature or requestspec
Description
Hardware designs are trees of module instances, and an editor for them needs that tree: which module is instantiated where, what drives this signal, what does this signal reach. slang-server has a hierarchy view, VHDL-LS has instance navigation, Sigasi has a full design view and signal tracing. t27 compiles to Verilog, so the instance tree of a design and the cone of a signal are questions the language service can answer from the same snapshot. 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/hierarchy.t27 (call and type hierarchy) and specs/lsp/index.t27.
Prior art:
- slang-server: hierarchy view, expand module instances, drivers and loads of a signal: https://hudson-trading.github.io/slang-server/features/features/
- VHDL-LS: entity and instance navigation: https://github.com/VHDL-LS/rust_hdl
- Sigasi Studio: design hierarchy, signal tracing, quick outline: https://www.sigasi.com/
- Verible: module instantiation completion: https://chipsalliance.github.io/verible/
Boundary
- specs/lsp/hdl_hierarchy.t27
User Scenarios
- Given a top module that instantiates
alutwice andregfileonce, when the client sendst27/instanceTreefor the top, then the answer is a tree of 3 children with instance names, module names and the range of each instantiation. - Given a signal, when the user asks
t27/drivers, then the answer lists every assignment and every port connection that writes it, across instance boundaries. - Given a signal, when the user asks
t27/loads, then the answer lists every read of it, across instance boundaries. - Given a port connection
.clk(sys_clk), when the user sendstextDocument/definitiononclk, then the answer is the port in the child module; onsys_clkit is the signal in the parent. - Given a cycle of instantiation, when the tree is built, then it stops at the repeat with a marker and a diagnostic, and does not loop.
- Given the cursor in an instantiation, when completion is requested after
., then the unconnected ports of the child are offered.
Requirements
- FR-001: The module MUST build the instance tree from the snapshot as a lazy structure: children are produced on request, with a depth limit and a total node limit (default 5000).
- FR-002: Drivers and loads MUST be computed through ports, wires and registers, crossing instance boundaries in both directions, and each answer entry MUST say through which instance path it was reached.
- FR-003: The module MUST register
t27/instanceTree,t27/driversandt27/loadsinspecs/lsp/methods.t27as extension methods (the router issue owns that table), and MUST gate them on the client announcing support. - FR-004: The module MUST NOT guess: a signal whose driver it cannot resolve is reported as
unknown driverwith the reason, never silently dropped. - FR-005: The Verilog side (a
.vfile generated byt27c gen-verilog) MUST map back to the.t27instance through the source map, so the same questions work from generated code.
Success Criteria
- At least 30 tests in
specs/lsp/hdl_hierarchy.t27pass, run on the lab witht27c test-report(exit 0), including the instantiation cycle and the unknown-driver case. - On the lab the module runs over the biggest hardware spec in
specs/and prints the node count and the time; both are pasted in the issue. git diff --name-only masterlists onlyspecs/lsp/hdl_hierarchy.t27(0 files in other languages).
Metadata
Metadata
Assignees
Labels
area/specs.t27 spec files and conformance.t27 spec files and conformanceenhancementNew feature or requestNew feature or requestspec
Activity
gHashTag commentedon Nov 17, 2026
LSP spec created (typecheck OK, tests pass).