Qscope

Qscope is a Visual Studio Code viewer for system designs — Intel Platform Designer systems and IP components (.qsys, exported system .tcl, and component *_hw.tcl files) and Q-Sys Designer .qsys designs — drawn as compact layered graphs. It reads all of them without Quartus, and writes only where it can rewrite a file safely: parameter values, connections, and instance names in exported Platform Designer Tcl and .qsys XML.

It also opens Q-Sys Designer .qsys designs (the QSC audio platform). Those files share the .qsys extension but are a .NET BinaryFormatter container with a gzip-compressed object graph, so they are detected by signature and read by a separate parser.

Qscope beside Platform Designer on the same system:

Open tcl with Qscope:

Show base addresses:

and much more!

What it does

• Opens .qsys directly. Exported .tcl and *_hw.tcl remain text by default and open through Reopen Editor With… or Open Qscope Graph.
• Reads Q-Sys Designer (QSC) .qsys designs by file signature and maps their components, ports, and wires onto the same graph, without the Q-Sys Designer installation.
• Draws a left-to-right layered graph, keeps hierarchical subsystems collapsed as single IP blocks, and expands a selected one in place, enters it in the same canvas, or opens it in a new editor without expanding deeper levels by itself.
• Shows component parameters and external interfaces on click — including elaborated physical port names and widths — and parameter documentation on hover in Tcl and in .qsys XML opened as text.
• Runs validation, elaboration, and composition callbacks locally so parameter-dependent instances and connections update immediately, and lists the leaf-component files a *_hw.tcl registers or sources as an expandable tree without Quartus.
• Reports parser problems and structural findings in one Problems list — dangling endpoints, disabled instances that are still wired, clock/reset endpoints without a driver, Avalon-ST width mismatches, two slaves mapped to the same base address in one host's memory-mapped space, a connection declared twice, and IP version drift — opens the exact source line for each, and offers a lightbulb fix for the findings it can repair by deleting a connection.
• Refreshes the graph by itself when the file changes on disk — a rewrite by git, Q-Sys Designer, or Platform Designer — keeping the current pan, zoom, and filters, and summarizes the active design's IP and problem counts in the status bar.
• Compares two systems structurally, or three versions at once, against another file or a git revision of the open one, and exports the comparison as Markdown or as a self-contained HTML report that draws both designs as inline SVG.
• Searches every .qsys and .tcl design in the workspace — including binary Q-Sys designs — for a module type, instance, parameter name or value, signal, or exported interface, and reveals any IP, port, parameter, or connection in its exact parser range rather than a guessed line. A hit inside a binary Q-Sys design opens that design instead, because a binary container has no line to reveal.
• Edits where the file can be rewritten safely: a parameter value, an instance name everywhere the file that declares it names it — including from an expanded subsystem — and a connection's endpoints, or its removal without leaving the parameter commands behind (exported Platform Designer Tcl and .qsys XML).
• Completes and warns on the Q-SYS Lua API in .lua modules and control scripts, and on the plugin API in .qplug files, offering only the names QSC documents and a quick fix for a misspelled one.

Also: highlights clock, reset, Avalon-MM, and interrupt domains or traces one signal family and dims the rest; exports the view as a standalone SVG or a 2× PNG and the graph model as JSON, Mermaid, Graphviz DOT, or normalized design text; navigates by keyboard with screen-reader summaries, a minimap, saved views, and fit-to-page printing; and opens the system in Platform Designer or converts Tcl in a disposable sibling folder when Quartus is wanted.

Views and interfaces

Qscope has two modes:

Only interface filters present in the current system are shown. Pipeline is the Intel Platform Designer layout: Avalon-ST streaming anchors it, so it is offered only where those interfaces are known — a Q-Sys design connects over its own signal domains and would draw no wires in it at all, so a Q-Sys design is read in Classic. For exported system Tcl, Pipeline remains disabled until Read interfaces… resolves the real interface types for every visible hierarchy level. Safely elaborated *_hw.tcl compositions already provide their declared connection types and can use Pipeline view without Quartus.

The Tcl reader accepts Platform Designer declarations for avalon, axi, tristate_conduit, avalon_streaming, interrupt, conduit, clock, reset, and nios_custom_instruction. Before Quartus analysis, Avalon-MM is also recognized from exported connection properties such as baseAddress and arbitrationPriority; unrelated unknown connections remain grey.

Hardware Tcl components without Quartus

Open a *_hw.tcl file with Reopen Editor With… → Platform Designer IP. Qscope evaluates it with a local restricted tclsh interpreter, emulates the component API needed for parameters, module properties, filesets, interfaces, instances, and connections, then invokes VALIDATION_CALLBACK and either COMPOSITION_CALLBACK or ELABORATION_CALLBACK.

Every definition first appears as one component block. Leaf components stay as one block. A composition component has a + control that replaces the block with its internal instances and connections; − collapses it again. Click a one-line external interface such as din or dout directly on the canvas to expand it into physical signals such as din.valid, din.data, and din.ready; click any expanded signal to collapse the interface. Use IP definition to inspect parameters and the same signal metadata. Apply & re-elaborate runs the callbacks again and redraws parameter-dependent contents.

For both leaf and composition components, Files lists effective add_fileset_file results and direct registrations made through sourced file helpers as a compact terminal-style +/− folder tree, for example common/wip/common_hdl/packages and common/others/hdl/common_sc_fifo. Click a filename to open that registered source beside the graph. Calls made through sourced helpers such as add_wip_common_pkg_files and add_files_common_others_common_sc_fifo are evaluated normally; the helper name remains available as file provenance rather than becoming a visual group. A file used by multiple filesets appears once with all purposes, such as QUARTUS_SYNTH and SIM_VERILOG. This workflow does not require Quartus.

The interpreter supports normal Tcl control flow, procedures, substitutions, and workspace-local source files. It blocks external commands and unsafe filesystem operations, limits output, and stops slow evaluation. If a component depends on a vendor command that cannot be safely emulated, Qscope falls back to a static preview and reports the reason.

System Tcl and Quartus analysis

In a trusted workspace, Qscope automatically runs the system in a restricted safe tclsh interpreter. Platform Designer commands only record their resolved arguments, so source, namespaces, procedures, substitutions, if, switch, and loops appear immediately without starting Quartus. File access and external commands remain blocked; sourced Tcl is restricted to the current workspace and the resolver has a short timeout. If tclsh is unavailable or the script needs unsupported capabilities, Qscope falls back to the lexical reader and reports a warning.

Problems in a Tcl system are reported at their source line, with the closest known command suggested:

The Read interfaces… action still runs qsys-script on demand. Use it when exact elaborated interfaces, ports, streaming formats, or automatic adapters are required.

Use qsysView.tclVariables to select a configuration before evaluation or before opening the Tcl system in Platform Designer. For example:

{
  "qsysView.tclVariables": {
    "PLATFORM_CONFIG": "WHC"
  }
}

Infer clk/reset classifies only unknown static Tcl connections by interface names. It recognizes clock, clk, reset, reset_n, rst, rst_n, nrst, and rstn. Reset takes priority for names such as clk_reset. Disable the checkbox if a project uses those words for unrelated interfaces. Explicit Qsys/Tcl kinds and Quartus results are never overridden.

Quartus analysis is user-triggered and runs on a disposable copy. It supplies exact types and ports, Avalon-ST format information, and automatic-adapter detection. While this metadata is current, Read interfaces… and Infer clk/reset are hidden. Editing any loaded source invalidates its metadata and shows the controls again. The source file is never modified.

Automatic Avalon-ST adapters are marked with a red dot, and the details panel reports the adaptation Quartus will insert:

Q-Sys Designer designs

Q-Sys Designer (QSC audio) also saves designs as .qsys, but they are not Intel Platform Designer XML: the file begins with a .NET BinaryFormatter header followed by a gzip-compressed object graph. Qscope detects that signature and reads the design with a separate parser, so opening one never reports Invalid Qsys XML.

Q-Sys components become IP blocks, their ports become interfaces, and Q-Sys wires become connections on the same canvas. Components are identified by the code name a designer sees rather than by the GUID the file stores, so connections, diffs, and exports read the same way in Qscope as in the design; a code name repeated by a snapshot placement gets a numeric suffix. Port directions and signal domains (audio, control, speaker, and so on) come from the design itself, so the graph is fully populated without Quartus or the Q-Sys Designer installation. Wires that Q-Sys itself excludes from the wired design, and wires whose pins belong to a container that is not part of a placed component, are skipped and reported as a single diagnostic instead of being drawn as floating links.

Every placed component also carries the top-left and size the design recorded, so the Layout selector can draw it where Q-Sys Designer placed it — a uniform scale keeps the design's relative spacing — instead of letting the layered algorithm choose; a wire that records bend points is drawn through them, matching how Designer routed it. Selecting a component shows its channel counts (for example 12 channels in · 12 channels out) in the details panel, a compact 12 in · 12 out is drawn on a block tall enough to hold it, and the full summary is the block's tooltip. When the component is a plugin, the details panel also parses the Lua the design stores in it and lists the interface the plugin declares for itself: its PluginInfo, the properties GetProperties inserts, and the GetControls controls with their pin style and configured channel count. A count written as an expression such as props["Cache Size"].Value is resolved against the component's configured values (falling back to the plugin's declared default), so a cache of 10 shows 10 channels, not the raw expression. A control or property the plugin builds in a for i, name in pairs({ … }) loop is expanded into one entry per literal, since that is where a plugin usually declares its generated channels. A component's designer-facing label (_Label / _UserLabel) and its hidden/locked state are shown when they differ from the defaults.

Because the container is binary, git cannot show a useful diff for a Q-Sys .qsys. Export… → Design text (normalized) writes the parsed design as one line per component, placement, parameter, pin, and wire — sorted, so a change appears as one changed line — and a multi-line value such as a plugin script is written verbatim between <<TEXT and TEXT markers so its own lines show up in the diff. A moved component writes a changed set_position line and a rerouted wire writes a changed via list, so placement and routing are reviewable too. Commit that file next to the design to review changes and resolve merges.

Reading a Q-Sys design is local and read-only, and a Q-Sys .qsys is never modified. Edits — a parameter value, a connection, an instance name — apply to exported Platform Designer Tcl and Platform Designer .qsys XML only.

Q-SYS Lua and plugin scripts

A .lua file that Q-SYS runs — a Lua Module or a Control Script — and a .qplug plugin file get completion and diagnostics for the Q-SYS API. Both surfaces are transcribed from the Q-SYS Help pages, so the editor offers the documented functions, methods, properties, events, and module tables and accepts nothing else; a name that is misspelled is flagged with a warning whose quick fix is the exact documented spelling. Inside a .qplug file Controls is the plugin's own control table, so the Lua module of that name is not offered, and the plugin API is added on top of the Lua one.

Hierarchical systems

When an IP type matches a sibling .qsys or .tcl file, its block has a + control. Expanding replaces only that instance with its internal graph, reconnects parent links through exported interfaces, and surrounds the child with a dashed container without changing the flat IP topology chosen by the layout engine. Use − to collapse the container or ↘ to enter it as the full canvas.

A subsystem expanded in place, with the parent links reconnected through its exported interfaces:

If the parent was read with Read interfaces…, expanded children are analyzed too. Nested Tcl connections therefore keep their exact interface types in Pipeline view, while exported clock and reset bridges remain part of the parent domain.

Choose Enter subsystem in the IP details to navigate within the current viewer; ← Back restores the parent layout and zoom. Choose Open in new editor, or double-click the block, for a separate Qscope. Nested children remain collapsed and can be expanded independently.

Controls

• View switches between Classic and Pipeline.
• Layout chooses Layered (the default, placed from the connections) or Design positions, which places a Q-Sys design's components at the X/Y and size the design recorded. It appears only for a Q-Sys design and is remembered in saved views.
• All IP includes IP without visible functional connections; off by default. Clock/reset highlighting alone does not make an IP visible.
• Disabled IP includes disabled instances; off by default.
• Infer clk/reset controls name inference; on by default.
• Errors/Warnings appears when the reader or the structural analysis finds a problem; click an item to open its source line.
• + expands a detected subsystem; − collapses its container; ↘ enters it; ← Back returns to the parent.
• Read interfaces… requests exact Quartus metadata.
• IP definition opens parameters and external interfaces for a *_hw.tcl component.
• Open in Platform Designer opens or converts the system.
• Reload source rereads the active Qsys/Tcl hierarchy, including sourced configuration files, and invalidates stale Quartus analysis.
• Disable connections in IP or interconnect details hides those links only in the current viewer; Restore connections brings all hidden links back.
• Trace signal path in connection details highlights the connected chain in the same signal family — data, clock, or reset — and dims everything else; Trace from this IP in IP details does the same starting at a module, listing the families it followed; Clear trace removes it.
• Find IP highlights the blocks whose name or type matches as you type, moves keyboard focus to the first match and pans it into view, and shows 3 / 5 beside the box; Enter or ↓ steps to the next match, Shift+Enter or ↑ to the previous one, and Escape clears the find and returns focus to the graph. The arrow keys keep moving focus from the match, because the find box uses the same focus model as the canvas.
• Compare… picks another file or a git revision of the open system and shows the structural diff in the details panel; entries that exist in the open file reveal their source, and Export report… writes the diff to a Markdown file or Export HTML report… to a self-contained HTML file that draws both designs as inline SVG — added in green, removed in red, changed in amber — beside the change table.
• Compare 3-way… picks a common base and a second version, then groups the structural changes by side — only here, only in the other version, in both, or conflicting — with each row revealing its own source and conflicts revealing both versions; Export report… in that panel writes the comparison to a Markdown file.
• ✎ next to a parameter in the details panel asks for a new value and rewrites just that value in the source file. It appears only for exported .tcl scripts and .qsys XML, never for *_hw.tcl or Q-Sys designs.
• Find in workspace… (or Qscope: Search Designs in the command palette) indexes the workspace designs and opens the match you pick.
• The status-bar item reports the active design's IP count and problem count; clicking it, or Qscope: Show Active Design in the command palette, reveals that editor.
• ⌕ next to a parameter or a port in the details panel (or Qscope: Find References in the command palette) finds every set_instance_parameter_value, .qsys <parameter>, or <instance>.<port> endpoint across the workspace and reveals the one you pick. The Ports section lists each instance's ports with their interface, direction, and any exported interface names, each with its own search button.
• Find references… in IP details (or Qscope: Find References in the command palette) finds every declaration, parameter, connection, and export that names an instance across the workspace and reveals the reference you pick.
• Relayout recalculates the active layout from currently visible connections while preserving analysis; Fit fits it to the viewport.
• Export… writes the current view as SVG or PNG (image formats follow the active filters and view mode) or the whole model as JSON, Mermaid, Graphviz DOT, or a normalized design text — one line per component, placement, parameter, pin, and wire, sorted, with multi-line values written verbatim between <<TEXT and TEXT markers, so a binary Q-Sys design can be reviewed and merged in git.
• Drag to pan and use the wheel to zoom.
• Arrow keys move focus to the nearest IP in that direction; Enter opens its details and Escape closes them and clears an active trace.
• The minimap in the bottom-right shows every IP and the current viewport; click or drag it to jump to that part of the design.
• Save view stores the current mode, filters, and IP visibility under a name; the Saved views list restores one and Delete removes it. Saved views belong to the workspace.
• Screen readers hear the same summaries the status line shows — the visible IP and interface counts, trace results, problem counts, and restored views — through a polite live region. Printing fits the whole design to the page and restores your pan and zoom afterwards.

New viewers start in Classic mode. With Remember Last View State enabled, Qscope reuses the last mode, interface filters, IP visibility options, and name-inference choice across editors.

Installation

Requires Visual Studio Code 1.90 or newer. Install Qscope from the VS Code Extensions view, or run:

code --install-extension QuantForgeSoftware.qscope

A local package can be installed with (substitute the version printed by npm run package):

code --install-extension qscope-<version>.vsix --force

Then reload the window (Developer: Reload Window) if the extension does not appear. .qsys files open with Qscope straight away; for a Tcl system use Reopen Editor With… → Qscope or the Open Qscope Graph command.

tclsh 8.5 or newer is optional. With it, Qscope runs exported systems and *_hw.tcl compositions locally; without it those files fall back to the lexical reader and report why. Quartus is optional too — Read interfaces… and Open in Platform Designer need it, everything else does not.

Settings

Development

Node.js 20 or newer is required.

npm ci
npm run check
npm run format:check
npm test
npm run test:coverage
npm run package

npm run package runs every gate and creates qscope-<version>.vsix. Press F5 in VS Code to run an Extension Development Host. The tests need a tclsh (8.5 or newer) on PATH.

Scope

Qscope edits only parameter values, connections, and instance names, and only in exported Platform Designer Tcl scripts and Platform Designer .qsys XML; *_hw.tcl and Q-Sys designs stay read-only. Its safe component API covers common Platform Designer commands but does not replace vendor validation for unusual proprietary extensions. Unknown system Tcl connections remain grey in Classic mode until their type is explicit, inferred, or resolved by Quartus. Waveforms are protocol illustrations, not simulation output.

License

MIT

Qscope is maintained by John Baima at Quant Forge Software.