This Visual Studio Code extension embeds the popular Venus RISC-V simulator. It provides a standalone learning environment as no other tools are needed. It runs RISC-V assembly code with the standard debugging capabilities of VS Code.
To use it as educational tool, further views are added as described below.
You can easily install the extension via the marketplace by searching for "riscv":
Alternatively, you can install it via VS Code Quick Open (CTRL+P):
ext install hm.riscv-venus
You can debug any assembler file you are editing. We recommend using the RISC-V Support extension for syntax highlighting.
Just start debugging with "Run and Debug" to debug the current file:
You can step through the code and pseudo-operations are expanded automatically. The actually executed instructions are displayed in an assembly view (auto-opens if set in extension-settings). Breakpoints are of course also supported.
The basic Venus environmental calls are also supported. Further environment calls are also supported for educational toy examples are described in the following.
From, the Debugger you can open the "Venus Options". From there you can open settings, views, documentation and more. Also there are commands for all these actions which you can execute with CTRL+P and typing "Venus: ..."
There is also Support for the VSCode-Inherent launch.json. There are pre-made configs availale which you can access by typing "Venus...". Alternitavely a full launch.json currently looks like this.
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "venus",
"request": "launch",
"name": "Launch current file with all options",
"program": "${file}",
"stopOnEntry": true,
"stopAtBreakpoints": true,
"openViews": [
"Robot",
"LED Matrix",
"Seven Segment Board"
],
"ledMatrixSize": {
"x": 10,
"y": 10
}
}
]
}
You can view the memory contents by opening the memory view with CTRL+P and
"Venus: Open Memory".
You can select which segment to view and scroll through the memory words (as in the online Venus version).
You can change the registers by clicking on their value, update the value and press enter.
To change to format of the registers, click on "Venus Options" or press CTRL+P
and enter "Venus: Set Variable Format".
The LED matrix is by default a 10x10 RGB LED matrix which size can be changed with launch parameters. Each LED is set individually by the
environment call 0x100.
This sets the pixel at position (x,y) to an RGB color (r,g,b):
a1containsxin bits 31-16 andyin bits 15-0`a2containsrin bits 23-16,gin bits 15-8 andbin bits 7-0
For example to set a red pixel at position (2,4):
li a0, 0x100
li a1, 0x00020004
li a2, 0x00FF0000
ecall
This sets all pixels to an RGB color (r,g,b):
a1containsrin bits 23-16,gin bits 15-8 andbin bits 7-0
For example to set all pixels to red:
li a0, 0x101
li a1, 0x00FF0000
ecall
You can open the board view by pressing CTRL+P and then select/enter "Venus:
Open LED Matrix".
Alternatively, you can have it open automatically by adding
.vscode/launch.json in your project:
{
"version": "0.2.0",
"configurations": [
{
"type": "venus",
"request": "launch",
"name": "Debug current file",
"program": "${file}",
"stopOnEntry": true,
"openViews": [ "LED Matrix" ]
}
]
}
You find an example that draws the RISC-V logo here.
The toy robot example is a variation of the LED matrix, but with a different style and way of setting the LEDs: The LEDs are all green and are set by a single bitmask per row. It has 12 rows of each 16 LEDs.
Update a single row:
a1sets the row, where 0 is the bottom rowa2contains the LEDs on/off (1/0) status in bits 15-0 where bit 15 is the leftmost LED
You can open the board view by pressing CTRL+P and then select/enter "Venus:
Open LED Matrix".
Alternatively, you can have it open automatically by adding
.vscode/launch.json in your project:
{
"version": "0.2.0",
"configurations": [
{
"type": "venus",
"request": "launch",
"name": "Debug current file",
"program": "${file}",
"stopOnEntry": true,
"openViews": [ "Robot" ]
}
]
}
You find an example that draws the RISC-V logo here.
The seven segment is a more complex example. It has two push buttons as input devices and two LEDs and seven segment displays as output.
This ecall updates the seven segment display. The segments can be driven individually. The environment call expects the values and a mask of valid updates in two registers.
The segments are mapped to the bits in the two registers (value and mask) as follows:
Register a1 contains the values and register a2 contains the mask of the
updates.
The following code will show "42" in the segments:
li a0, 0x120
li a1, 0b0110011001011011
li a2, 0b1111111111111111
ecall
Update only two segments:
li a0, 0x120
li a1, 0b0000000000000100
li a2, 0b0000000000010100
ecall
What will the segments display now?
This environment call sets the LEDs as defined in the two lowest bits of a1.
Bit 0 sets LED 0 (green) and bit 1 sets LED 1 (red). The LEDs are on when the
bit is 1 and off when the bit is 0. The LEDs preserve their state until they are
changed by calling this ecall again.
The following code lets the LEDs blink alternating:
loop:
li a0, 0x121
li a1, 0b01
ecall
li a0, 0x121
li a1, 0b10
ecall
j loop
This reads whether the push buttons have been pressed. Once the push buttons are
pressed they will visually be highlighted as the environment will buffer this
press. The ecall whether the two buttons were pressed in the lowest two bits of
a0 and resets the buffers.
The following code reads whether buttons have been pressed and set the LEDs accordingly.
loop:
li a0, 0x122
ecall
mv a1, a0
li a0, 0x121
ecall
j loop
You can open the board view by pressing CTRL+P and then select/enter "Venus:
Open Seven Segment Board UI".
Alternatively, you can have it open automatically by adding
.vscode/launch.json in your project:
{
"version": "0.2.0",
"configurations": [
{
"type": "venus",
"request": "launch",
"name": "Debug current file",
"program": "${file}",
"stopOnEntry": true,
"openViews": [ "Seven Segment Board" ]
}
]
}
You can find an example here.
There is a Terminal which supports the standard Venus Ecalls for printing integers and strings and error output. In addition also Input is supported (currently only via polling until Interrupts are supported).
To activate Input the Ecall 0x130 must be called. After that you can ecall 0x131 to read the input. After sending your input with enter in the console, internally the input is buffered and can be read one by one with calling 0x131. There are 3 states when calling 0x131(read Input):
- a0 == 0x00000001: Still waiting for input.
- a0 == 0x00000000: All Input has been read. Buffer is empty.
- a0 == 0x00000002: Input has been detected and one character has been read. a1 == input in UTF-16 code.
For an example see terminal.s in examples in the repository.
Implement a counter with the seven segment board. Count up when button 1 is pressed and count down when button 0 is pressed. Display the current counter value in the seven segment display. Let the red LED blink when the counter overflows.