SystemVerilog Pro

SystemVerilog, Verilog, and UVM support for reading, navigating, and editing hardware code in VS Code and compatible editors.

Created and maintained by Taher Anaya · LinkedIn · anaya.taher@gmail.com

Autocomplete, hover, definitions, parameter help, usage searches, highlighting, and formatting share a background workspace index. No separate language server is required. Your source code stays in your local or remote workspace; the extension does not upload source, telemetry, or usage data.

Start here

1. Install SystemVerilog Pro and open your project folder.
2. Open a supported HDL file and let background indexing finish. The status indicator disappears when work is complete.
3. Hover a symbol, use Go to Definition, or type obj. to explore its members.
4. Right-click a variable, callable, or concrete class and choose Find Usages. Select lines and choose Format Selected Lines to limit formatting changes.

Ordinary navigation works without a setup script or compiler profile. For macros whose meaning changes between builds, optionally select a compiler context.

Features at a glance

SystemVerilog Pro provides static source assistance. Compilation, simulation, linting, and project tests remain in your existing tools. Complex preprocessing and dynamic language behavior can limit navigation; uncertain results remain unresolved or are clearly labeled.

Commands and shortcuts

Commands below appear under SystemVerilog Pro in the Command Palette.

Standard Find All References and Peek References use the extension's declaration matching. Editor keybindings and mouse gestures can be customized separately. The extension does not replace your context menu or add a custom mouse gesture.

Go to Definition targets the declaration's identifier when its source position can be verified, including the intended variable when several declarations share a line. The editor controls how the destination is revealed and highlighted. Cursor's standard jump briefly highlights the target and places the caret there; persistent text selection and exact vertical centering are not controlled by the definition provider.

Press Escape to dismiss suggestions or parameter help; use Alt+Space / Option+Space to reopen them. These popups use the editor's native font sizing and zoom. The extension does not override editor.suggestFontSize.

Navigation and autocomplete

Find the declaration that belongs to the reference

Navigation recognizes common modules, classes, interfaces, packages, programs, functions, tasks, ports, parameters, variables, typedefs, structs, unions, enums, covergroups, properties, sequences, clocking blocks, modports, virtual interfaces, and macros. Common UVM classes, phases, macros, and p_sequencer declarations are also supported.

• Lexical scope, method arguments, block locals, imports, and the nearest inherited declaration determine which symbols are visible.
• Package-qualified types such as demo_pkg::packet_t keep their own member namespace. Ambiguous imports do not silently select an unrelated declaration.
• Wildcard and selective imports retain source order and enclosing scope through nested includes. Explicit imports take precedence over wildcard imports at the same scope.
• Typedef aliases, simple macro-selected parent types, and supported positional, named, or default class type parameters participate in member resolution.
• An explicitly typed argument or variable can resolve to a unique package-owned declaration even when its standalone source has no known package/import context. Multiple possible declarations remain unresolved; explicit imports and forward declarations keep precedence.

Follow members and inheritance

• Type obj. for known members, including inherited members; type pkg:: or class_type:: for supported scoped members.
• Follow nested struct fields, package-qualified fields, virtual interfaces, and supported method-return chains such as factory.get_item().child.
• Index an array element before requesting element members: items[0].. The array itself does not incorrectly expose its element's members.
• Click super to open the immediate parent class. super.method and super.new search upward for the nearest matching parent declaration.
• Struct completion shows fields, rather than the typedef name or unrelated global symbols. Unresolved receivers or members stay unresolved.

Autocomplete uses flexible name matching: for example, pack_stat can match packet_status. Completion icons distinguish symbol kinds. Type $ for system tasks, or a backtick for directives, macros, and UVM snippets. Known UVM calls such as `uvm_info show their argument names and declarations.

Hover previews use a small cache and a bounded declaration-preview wait to remain responsive on slow filesystems. Syntax and semantic colors can be customized with the editor's normal settings; semantic port and parameter rules use editor.semanticTokenColorCustomizations.

Find reads, writes, callers, and class references

Run Find Usages on a variable, parameter, function, task, or concrete class. SV Pro Usages opens in the sidebar with clickable results grouped by access and file:

Variable groups appear as Declarations → Updates → Writes → Reads, followed by unresolved matches if present. In count = count + 1, the left occurrence is a write and the right occurrence is a separate read. Other symbol kinds show their applicable groups, such as callers or class references.

Searches respect lexical scope, declared receiver types, and imports. A same-named symbol in another scope is not counted as a confirmed use. Locals in anonymous or named blocks, forks, and supported loop bodies retain their own lifetimes and shadowing rules. A macro-dependent loop whose lifetime cannot be established leaves affected references unresolved.

Indexing prepares identifier locations, bounded lexical access roles, and call-argument structure. Queries reuse these facts, match declarations and callable signatures, and read only matching source candidates to verify freshness and show result lines. Oversized or unusually complex files use a cancellable analysis worker when queried. No compiler or simulation is started.

When the same header is included in several package contexts, starting from a variable, parameter, or concrete class declaration collects confirmed uses of that exact declaration across its known contexts. Starting from a receiver-qualified use keeps the search in that resolved context. Same-named declarations in other files remain separate, and ambiguous use sites remain unresolved. Callable prototype and implementation matching retains its existing declaration rules.

Nested member searches also handle tied inherited receiver declarations in the same source scope when their known types lead to one final declaration. Distinct final declarations or an unknown alternative type or ancestor remain unresolved; the extension does not infer which preprocessor branch was compiled.

Opening a result, switching preview tabs, closing an unchanged file, or receiving an identical-text refresh preserves the result list. Actual source changes mark it Out of date; run the command again to refresh it. Output › SystemVerilog Pro records a short reason when displayed results become stale. The view reports unresolved identifier matches and unreadable candidate files.

Argument access follows the called declaration. Passing a variable to an input argument is a read; an output argument is a write; inout and writable ref are updates; const ref is a read. The same rules apply to supported positional and named module/interface/program connections. Expressions used to select an output element, such as the index in task_call(array[index]), are reads. A custom method's name alone does not establish its direction: get(output value) writes value, while get(input key) reads key.

Supported native array methods use their language-defined argument contracts after the receiver is confirmed as an array. For example, queue.push_back(value) reads value; a scalar project object's same-named method uses that object's declaration. Interface modport prototypes are joined to implementations only when their complete contracts agree. Incomplete formal lists remain unresolved until a complete signature is indexed.

Results describe static source references. Generated macro expansions, unresolved types, argument directions, and dynamic dispatch can prevent precise binding. A possible identifier match is not automatically a confirmed usage.

Class searches

Start from a concrete class declaration or an unambiguous type reference. Explicit class-name uses can include fields, formals, return types, inheritance, generic arguments, casts, and static/factory qualifiers when declaration matching confirms the type. A forward declaration alone does not safely identify the complete class usage set.

Including files shows direct literal includes of the declaration file that the index can resolve. It does not traverse transitive include chains. Include locations are excluded from the usage count and from standard Find All References / Peek References results.

Class searches use the identifier locations already collected by indexing. They do not infer class allocations from a handle-only new() expression, trace object ownership, or infer a derived allocation from a cast. Uncertain macro arguments remain under Unresolved references, with a separate unresolved-match count, rather than being labeled as confirmed type uses. Standard reference actions return confirmed class references and omit header relationships and uncertain class matches.

Compiler context and macro precision

The same macro name can mean different things in different builds. Source order and explicit include relationships help without configuration; directory proximity alone does not identify the active build.

Hover Build context incomplete in the status bar to see the prepared input diagnostics. A saved context can outlive its generated build directory: if its compiler filelist was removed, restore those generated inputs through the normal build or capture the current compiler filelist again. Running an unrelated build does not repair a saved missing path. Diagnostic details clear when background preparation starts.

Unsupported or width-dependent expressions remain expressions. Merely running a build does not make every workspace file part of it. A source must be reached through the compiler's ordered sources and includes.

Macro states are prepared in the background with workspace indexing. Full indexing settles after symbol and configured build-context work has finished. Hover and Go to Definition then consult the prepared source-position state; they do not rescan compiler inputs or repeat preprocessing for each query.

Select a context

Optional configuration sources are checked in this order:

1. The workspace's systemverilogPro.compilation editor setting.
2. A .sv-pro.json file in the workspace root.
3. A private shell-captured context for that exact workspace.

For example, .sv-pro.json can contain:

{
  "version": 1,
  "filelist": "compiler.f",
  "workingDirectory": "build",
  "filelistMode": "f"
}

Use the actual compiler filelist and invocation directory. In this example, compiler.f is relative to build, which is relative to the workspace. Compiler filelists commonly contain -f/-F, +incdir+/-I, and +define+/-D. Project-specific templates must be expanded by the normal build before they accurately describe compiler inputs. Unsupported simulator options, missing inputs, and incomplete library context produce a warning rather than a guessed active value.

Discover a build inside a results directory

Run SystemVerilog Pro: Copy Results Directory Discovery Command, then paste the command into your normally configured Linux or csh/tcsh terminal, where RESULTSDIR identifies your build results. You can replace "$RESULTSDIR" in the copied command with an explicit results path.

The helper searches nested folders for supported logged compiler invocations and their actual source filelists. It does not require a particular project directory prefix, target name, or compile_tb.log filename. A combined log may contain headers or multiple compiler invocations. Recorded working directories and leading cd ... && compiler ... commands are interpreted as data; no logged commands are executed.

Choose the intended compiler context from the numbered list. Multi-stage or simulator builds can produce several choices, so select the invocation whose filelist includes the source you are working on. An inferred directory is marked as requiring confirmation; an unknown directory needs an explicit --cwd rather than a guess.

Refresh or change the saved build selection

If your shell setup already provides the optional svctx wrapper, run this in your normally configured editor terminal:

svctx --choose

Choose the intended compiler invocation from the numbered list. Use this after switching builds, changing compiler arguments, or removing the previously selected build. Normal login refreshes the saved selection; it does not silently switch to another build. A successful capture updates the extension in the background without a window reload.

If no choices appear, use svctx --discover to inspect the discovery diagnostics. Time limits, unreadable logs and missing compiler inputs are reported separately. A results folder containing only simulation output cannot establish a compiler context.

svctx is an optional command from your shell setup, not a command installed into every user's shell by the extension. Without that wrapper, use SystemVerilog Pro: Copy Results Directory Discovery Command above; running its copied command interactively provides the numbered build selection.

After selecting a build, the same command with --auto can run after normal shell setup or after compiler inputs are generated. An unchanged remembered context is checked directly without rescanning the results directory. Changes to compiler arguments, defines, working directory, or invocation identity require a new choice. Ordinary source editing does not require another login.

Discovery reads log headers across the collected results folders before scanning large log bodies. Compiler, build and command filename tokens receive priority, but no particular filename is required. Ordinary simulation output is filtered before full compiler-argument parsing. Traversal, time and read allowances remain bounded. Incomplete search coverage is reported, and cannot produce a new automatic choice. You can explicitly select a fully validated listed invocation despite incomplete coverage elsewhere, or use the explicit filelist workflow below. Unsupported shell expressions and unexpanded path arguments remain unresolved. A directory containing run outputs alone does not establish the compiler invocation, arguments, or working directory.

The selection, ordered compiler arguments, and referenced environment values remain in private user configuration. Failed selection, missing inputs, and changing build files preserve the previous saved context. This optional discovery runs in the capture helper; hover, navigation, and symbol indexing do not scan the results tree.

Capture success confirms readable filelists and their referenced variables. The extension then prepares the selected compiler context, including option interpretation and source preprocessing. A successful capture can therefore still be followed by Build context incomplete if an input changed or a compiler option is unsupported. Hover the warning for the specific diagnostic; repeating the same capture will not add support for an unknown option.

Without a configured or selected compiler context, the extension does not retain a build-context warning. Build context incomplete means a configured context could not be validated, including missing filelists, captured variables, or unresolved compiler inputs. It does not require a completed build to have existed previously.

Recognized Questa options preserve their argument boundaries, including C/C++ flags that must not become HDL macros. Supported macro and language modes retain conservative behavior for encrypted source, library-dependent definitions, token pasting and macro-string construction. A macro remains a possible definition when the source context does not prove it; a known unconditional definition can be confirmed independently of unrelated unknown state.

Capture an explicit Linux or csh/tcsh build environment

Use this when a configured terminal has build variables that the editor's extension host did not inherit:

1. Run SystemVerilog Pro: Copy Build Context Capture Command.
2. In your already configured build terminal, replace the compiler-filelist and build-directory placeholders and run the copied command. The workspace is filled in automatically.

python3 "$HOME/.config/systemverilog-pro/capture-build-context.py" \
  --workspace "/path/to/workspace" \
  --filelist "/path/to/build/compiler.f" \
  --cwd "/path/to/build"

For --compiler-log, the log's first nonempty line must be the actual compiler invocation, optionally prefixed with cmd :. The helper checks that it uses the selected filelist, then saves ordered arguments in a private companion filelist. This captures defines, undefines, include paths, and compilation-unit flags without entering each separately. A combined log with another header needs a separate log whose first nonempty line is the selected invocation. Log contents are read as data, never executed.

The helper captures only environment variables referenced by the selected nested filelists. It does not source setup scripts, run a build, or upload data. It writes an owner-readable context under ${XDG_CONFIG_HOME:-~/.config}/systemverilog-pro/contexts/, keyed by the canonical workspace path. The copied command uses your configured helper location. Python 3 is needed only for this optional helper; ordinary extension features do not require Python.

Refresh automatically, without reloading the editor

Place the capture command after your normal setup in the interactive part of .cshrc, or in an existing build wrapper after it generates the compiler filelist. Keep the workspace, selected compiler-filelist path, and invocation directory correct for that build. Once configured, ordinary editing requires no repeated input.

• Rerun capture when switching builds or changing environment variables or extra compiler flags.
• Changes to an existing filelist, includes, macros, or profile prepare updated context automatically.
• Ordinary body edits and saves with unchanged preprocessing directives update source positions without replaying the build.
• The extension detects captured-context updates even after initial indexing; background progress appears without a window reload.
• Changing a terminal's environment alone cannot update an already running extension host.

Filtered filesystem watches and background metadata checks also cover dependencies outside the workspace. Queries use prepared state and document versions without filesystem validation. Unreadable inputs and unresolved includes keep the incomplete-context warning. Prepared state uses directive records and shared checkpoints rather than retained source text, and is released when superseded or when its workspace is removed.

Formatting

Automatic formatting is off by default. Choose the scope of each change:

For shared files, selected-line formatting limits changes to the chosen area. Selecting the entire file removes trailing empty lines and the terminal newline; a partial selection reaching the file's end also trims selected trailing blanks.

Formatting rules

Strings, comments, multiline macro bodies, escaped identifiers, numeric literals, UDP tables, and encrypted code receive special preservation handling. Review formatting changes in unusual or preprocessor-heavy syntax.

Formatting limits and cancellation

• .sv, .svh, .v, and .vh files are editable. Generated .gsv and .gsvh files remain indexed but are never formatted.
• Files larger than 1 MiB use a lighter indentation/spacing pass; deeper vertical joins do not run.
• Files larger than 8 MiB remain unchanged. Selected formatting reads surrounding context, so these size limits apply to it too.
• Document, selected-line, and folder formatting run in isolated workers. Outdated document requests can be cancelled, and a size-aware deadline prevents exceptionally difficult formatting from blocking a save.
• Document/selected-line timeout details appear in Output › SystemVerilog Pro. Folder results report timed-out or changed files; unsupported encodings are left unchanged.

Supported files and environments

Matching is case-insensitive, including .SV and .SVH. Other file types—such as Python, shell scripts, Tcl, Makefiles, and logs—are excluded from the symbol index even if manually associated with an HDL language. The same file check covers discovery, editor events, filesystem changes, and background workers.

VS Code 1.85 or newer is required. The extension supports local folders, Remote SSH, WSL, Dev Containers, Codespaces, and virtual workspaces. It runs where the workspace extension is installed. When workers cannot access a workspace directly, the extension uses the editor's filesystem API.

Indexing, progress, and troubleshooting

The background index updates after edits, saves, external changes, file creation, deletion, and renames. Opening or closing an unchanged source does not count as a content update. Full scans reconcile changes received while they are running; large bursts can be combined into one rebuild after changes settle instead of restarting on every event.

Know when work is finished

The branded SV Pro | Taher Anaya status indicator shows full indexing, incremental indexing, or build-context preparation only while work is running. Hover it for details. It disappears immediately when all work settles; no persistent Ready/Done message is added. An incomplete build context or failed indexing keeps a warning visible.

Output › SystemVerilog Pro records progress, failures, and memory measurements. File-update names are off by default; enable SystemVerilog Pro › Status Bar: Show File Updates (systemverilogPro.statusBar.showFileUpdates) to show those details.

Large-workspace behavior

• Controlled worker batches, compact numeric indexes, shared identifiers, and reusable storage reduce retained memory. Retired incremental references are released; owned worker buffers can be adopted without redundant copies.
• Workspace discovery requests all supported HDL files and intentionally ignores files.exclude, keeping hidden generated/vendor/verification sources available. It does not silently stop at the editor's usual 20,000-result search limit.
• There are no workspace-wide, per-file, or large-file declaration budgets. Closed files receive complete symbol extraction, port processing, and scope assignment too.
• Very broad completion/workspace-symbol queries return a bounded response window to protect the shared host. Narrow the query to retrieve any stored symbol; this does not discard symbols from the index.
• Large sources are read in pages, including sources larger than the runtime's single-string limit. Large retry/update parses also run in the background. Files without recognized declarations complete with an empty symbol index.
• Failed full-index files are retried three times with increasing delays using the workspace filesystem. Remaining failures keep a warning and an exact output-log error. Files confirmed deleted or renamed since discovery are removed from that failure report.
• With no full scan active, a burst of at least 100 unique HDL changes waits five seconds after the last event before one clean rebuild. Structural changes that cannot be reconciled incrementally can also request one rebuild.

Privacy and scope

Source parsing and indexing stay in your local machine or the remote workspace environment. The extension does not send source code, telemetry, or usage data over the network. Optional compiler contexts and captured variables remain in the workspace or private user configuration.

Published packages contain the extension runtime, language definitions, documentation, license, and icon. They do not contain project sources, workspace indexes, private project paths, captured build variables, or diagnostic logs. Examples use generic names.

Static source analysis has limits: unresolved macro expansions, unsupported expressions, incomplete includes, and complex generated or dynamic code can reduce accuracy. A known build context improves macro precision without making unrelated files part of that build.

Help and feedback

For a bug report or feature request, contact Taher Anaya at anaya.taher@gmail.com. You can also find the maintainer on LinkedIn.

License: MIT