Skip to content

LSP: module instances, hierarchy and signal cone tracing (specs/lsp/hdl_hierarchy.t27) #12264

Closed

Description

@gHashTag

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:

Boundary

  • specs/lsp/hdl_hierarchy.t27

User Scenarios

  • Given a top module that instantiates alu twice and regfile once, when the client sends t27/instanceTree for 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 sends textDocument/definition on clk, then the answer is the port in the child module; on sys_clk it 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/drivers and t27/loads in specs/lsp/methods.t27 as 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 driver with the reason, never silently dropped.
  • FR-005: The Verilog side (a .v file generated by t27c gen-verilog) MUST map back to the .t27 instance through the source map, so the same questions work from generated code.

Success Criteria

  • At least 30 tests in specs/lsp/hdl_hierarchy.t27 pass, run on the lab with t27c 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 master lists only specs/lsp/hdl_hierarchy.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