riSim Studio
riSim Studio is a VHDL simulation and verification environment built into VS Code. It discovers your VUnit testbenches, runs them on the bundled simulator, and streams live waveforms into an interactive viewer. No separate simulator, Python, or VUnit installation is required.
1. Quick start
An empty workspace is enough to get started. We'll add a testbench, point risim-config.toml at it, and run our first simulation.
Skip to 1.2. Configure your sources if you already have a project.
1.1. Write a VUnit testbench
Unless you already have a VUnit testbench, create one and add a testcase. Name the entity with a tb_ prefix or _tb suffix, include the VUnit context, add a runner_cfg : string generic, and terminate with test_runner_cleanup. More detail is in the VUnit user guide.
Create a tb folder in your workspace and copy the following example into tb/tb_example.vhd:
library vunit_lib;
context vunit_lib.vunit_context;
library ieee;
use ieee.std_logic_1164.all;
entity tb_example is
generic (runner_cfg : string);
signal clk : std_logic := '0';
end entity;
architecture tb of tb_example is
begin
-- stimulus process toggles the clock signal `clk` every 10 ns
stimulus : process
begin
wait for 10 ns;
clk <= not clk;
end process;
main : process
begin
test_runner_setup(runner, runner_cfg);
while test_suite loop
if run("test_pass") then
wait for 5 ns;
assert clk = '0' report "This will pass";
elsif run("test_fail") then
wait for 10 ns;
assert clk = '0' report "It fails";
end if;
end loop;
test_runner_cleanup(runner);
end process;
end architecture;
Add a risim-config.toml file at the root of your workspace folder, mapping source files to VHDL libraries:
[libraries.my_design]
files = ["tb/tb_*.vhd"]
This compiles all VHDL files in the tb folder into the my_design library. Source files are searched automatically for VUnit-compatible testbenches.
1.3. Discover your testcases
Open the riSim view in the activity bar. Once discovery completes, testbenches appear in the Testbenches sidebar. Configuration problems show up in the VS Code Problems panel.
1.4. Run and debug
Click the run icon next to a testcase to execute it, or choose Load and wait to start the simulation paused so you can open a waveform tab. Add signals from the Design Hierarchy to display their waveforms.
2. Features
2.1. Run your testbenches
The Testbenches sidebar lists all testcases in your project.
- Automatic discovery of VUnit testcases from
risim-config.toml — no run.py to maintain
- Run one testcase or all of them from the sidebar
- Parallel execution: simulations are scheduled across your CPU cores
- Incremental recompiles: edit sources and re-run; only what changed is recompiled
- Multi-root workspaces: each workspace folder can have its own
risim-config.toml
- Live signal updates stream into the waveform tab while the simulation runs
- Full run control: run, pause, and stop from the sidebar or the waveform view
- Build your view from the Design Hierarchy: add a single signal, a module's direct signals, or an entire subtree with one click
- Display options: signal colors, separators, binary/decimal/hexadecimal radix, string/signed/unsigned array representation, analog and digital drawing modes
- Navigation: one-click auto zoom to fit, time units from femtoseconds to seconds
2.3. Catch configuration errors early
The risim-config.toml file is validated on save. Errors appear in the Problems panel with file, line, and message. Changing the config file re-discovers testcases automatically; the next simulation run recompiles as needed.
2.4. Copilot integration
With GitHub Copilot Chat you can debug your testbenches and simulations with AI-powered assistance. Tell Copilot to debug a testbench or ask @risim how it can help you.
- Ask
@risim /workflow for a guided tour from configuration to waveforms, or @risim /explainConfig when testbenches will not run
- In agent mode, use
#risimTestcases, #risimSimulations, #risimDiagnostics, and #risimRunTestcase to list tests, check config errors, and launch simulation runs
- Ask Copilot to debug a testcase or write new testcases with the bundled MCP server
3. Requirements and limitations
- Platforms: VS Code 1.116 or newer, on Linux x64 or Windows x64
- Language: VHDL-2008, compiled with the bundled GHDL-based simulator
- Testbench: VUnit builtins
com and osvvm are added automatically
- No full
run.py support: riSim builds your project from risim-config.toml; VUnit's Python hooks (pre_config, post_check) are not available
4. Documentation
For more information about Copilot AI features, see AI and Copilot integration.
5. Support
Questions, bugs, and feature requests: open an issue on GitHub or visit risim-studio.com. Extension logs are in the Output panel under riSim. Please include them when reporting a problem.
6. License and Third-Party Notices
riSim Studio is proprietary software; see LICENSE.txt.
The extension bundles and incorporates third-party components (including the GHDL simulator under the GNU GPL v2, a CPython runtime, VUnit under the MPL 2.0, and numerous permissively licensed Rust and JavaScript libraries).
Their licenses, attributions, and the corresponding-source offer for GHDL are collected in THIRD_PARTY_NOTICES.md.
Full license texts are in third-party-licenses/.
