About Virgule and its simulator emulsiV

• Motivation and scope
• Processor architecture
  • Relation with the RISC-V specification
  • Registers
  • Memory organization
  • Interrupts
  • Instruction set
  • Instruction encoding
• Memory and peripheral devices
  • Memory layout
  • Text input/output
  • General-purpose input/output
  • Bitmap output
• Creating programs for emulsiV with the GNU toolchain
  • Installation
  • Using the assembler
  • Using the C compiler
  • Using the linker
  • Converting an executable to the hex format
• License

emulsiV is a visual simulator for a simple RISC processor called Virgule.

Virgule is a 32-bit RISC processor core that implements a minimal subset of the RISC-V instruction set. Here, “minimal” means that Virgule accepts only the instructions that a C compiler would generate from a pure stand-alone C program.

Motivation and scope

Virgule and emulsiV are used for teaching computer architecture and digital design to beginners at ESEO. Before choosing a processor architecture, we had the following requirements in mind:

• An open architecture that we could use and implement without asking for permission.
• A simple and regular instruction set, yet complete enough to serve as a target for a C compiler.
• An architecture in line with the current state of the market, preferrably with actual industrial implementations.
• A free and open-source toolchain.

Among the candidate architectures, the RISC-V filled all our requirements:

• It has an open specification.
• It is a state-of-the-art RISC architecture with a clean and simple base instruction set.
• The RISC-V foundation has an impressive member list; RISC-V cores and chips are available today.
• The RISC-V architecture is supported by the GNU toolchain.

These properties allow several teaching scenarios.

In a computer architecture course, students discover how a processor works, what kinds of languages and tools can be used to create low-level programs (assembly, C). A simulator is a great way to visualize how each instruction affects the data path.

In a digital circuit design course, students can implement a processor core in VHDL or Verilog, or instantiate one to make their own system-on-chip.

Processor architecture

Relation with the RISC-V specification

Virgule implements all the computational, transfer control, and memory access instructions from the integer subset RV32I of the RISC-V specification. It also provides an exception return instruction that can be used in interrupt handlers.

The following instructions are not available:

• Memory ordering instructions.
• Environment call and breakpoints.
• Control and Status Register (CSR) instructions.

The RISC-V architecture defines three privilege levels: user, supervisor, and machine. Virgule only supports the machine level.

Registers

Virgule contains the following 32-bit registers:

• 32 general-purpose registers named x0 to x31.
• The program counter pc. This register contains the address of the current instruction. Its reset value is zero and it is always a multiple of 4.
• The machine exception program counter mepc. This register receives the return address when a machine-level exception occurs.

Memory organization

Data formats for memory load and store instructions follow these conventions:

In memory, 16-bit and 32-bit data will follow the little-endian ordering.

The following two addresses have a specific role:

• On reset, execution starts at adress 0. At this address, we will typically find a branch instruction to the beginning of the program.
• At address 4, Virgule expects to find the interrupt handler.

Interrupts

Virgule implements a simple hardware interrupt scheme in the machine privilege mode. There is no interrupt control or status register in the processor core itself.

When it receives an interrupt request, Virgule performs the following operations:

1. Complete the current instruction.
2. Switch to an uninterruptible state.
3. Set mepc to the address of the next instruction.
4. Set pc to 4, which will transfer control to the interrupt handler.

Returning from an interrupt handler is done with the mret instruction. This instruction has the following effect:

1. Copy mepc to pc.
2. Switch to an interruptible state.

Instruction set

In the following table:

• rd is the destination general-purpose register.
• rs1 and rs2 are the source general-purpose registers.
• imm is a literal (immediate) integer value.

if rs1 = rs2:
    pc ← pc + imm
else:
    pc ← pc + 4

if rs1 ≠ rs2:
    pc ← pc + imm
else:
    pc ← pc + 4

if signed(rs1) < signed(rs2):
    pc ← pc + imm
else:
    pc ← pc + 4

if signed(rs1) ≥ signed(rs2):
    pc ← pc + imm
else:
    pc ← pc + 4

if unsigned(rs1) < unsigned(rs2):
    pc ← pc + imm
else:
    pc ← pc + 4

if unsigned(rs1) ≥ unsigned(rs2):
    pc ← pc + imm
else:
    pc ← pc + 4

if signed(rs1) < signed(imm):
    rd ← 1
else:
    rd ← 0

if unsigned(rs1) < unsigned(imm):
    rd ← 1
else:
    rd ← 0

if signed(rs1) < signed(rs2):
    rd ← 1
else:
    rd ← 0

if unsigned(rs1) < unsigned(rs2):
    rd ← 1
else:
    rd ← 0

In the above table, logical and shift operations have the following meanings:

Instruction encoding

An instruction word can be composed of the following fields:

• funct7, funct3 and opcode define the operation to perform;
• rd is the index of the destination general-purpose register (allowed values are in the range 0 to 15).
• rs1 and rs2 are the indices of the source general-purpose registers (allowed values are in the range 0 to 15);
• imm represents a literal (immediate) integer value;

The RISC-V instruction set defines six instruction formats:

Immediate values

Immediate values are sign-extended to 32 bits. When they are not explicitly encoded in the imm field, the least significant bits are 0.

In the specification, formats B and J are described as variants of formats S and U. In formats B and J, immediate values represent offsets in relative branch instructions. They are encoded so that they share most of their bits with other formats while preserving their most significant bit at location 31 of the instruction word.

The following table shows the mapping between the bits of the instruction word and the bits of the immediate values:

Base opcodes

In Virgule, we have retained the following base opcodes from the RISC-V specification. Each opcode corresponds to a specific instruction format:

Field values for each instruction

When decoding an instruction word, Virgule uses the following fields to identify the actual instruction. In this table, the opcode column refers to the names from the base opcode table above.

Memory and peripheral devices

Memory layout

The addressing space is organized as follows.

Text input/output

The text input device is represented by a text field in the user interface of the simulator. It has two 8-bit registers:

The control/status register works as follows:

• On reset, bits 6 and 7 are cleared.
• Bit 6 is set after the user enters a character in the text field. The only way to clear it is to write a zero using a store instruction.
• The device will send an interrupt request to the processor when bits 7 and 6 are both set.

The text output device is represented by a text area in the user interface of the simulator. It has only one write-only register:

General-purpose input/output

The GPIO (General-purpose input/output) peripheral allows to connect at most 32 simple user I/O devices:

• Push-buttons.
• Toggle switches.
• LEDs.

The inputs are arranged in an 8×4 grid at the bottom of the General-purpose I/O section of the simulator. Right-click on a cell to change its type. Left-click to change the state of a button or switch.

It has the following 32-bit registers:

On reset, all pins are configured as inputs and interrupts are disabled.

The rising-edge and falling-edge events registers must be cleared in software using store instructions when the events have been processed.

Bitmap output

The simulator provides a graphic display area with 32 rows of 32 pixels. Each pixel is mapped to a RAM byte and its color is encoded like this:

The bitmap RAM follows a raster-scan ordering. For each address, this table shows the (x, y) coordinates of the corresponding pixel:

Creating programs for emulsiV with the GNU toolchain

The simulator allows to create and edit programs by entering instructions in the assembly column of the memory view. Another option is to type your program in a text editor and generate an executable for emulsiV using the GNU toolchain.

The following instructions have been tested in Ubuntu 20.04

Installation

If you are using Ubuntu, you can install the pre-built RISC-V bare-metal toolchain using this command:

sudo apt install gcc-riscv64-unknown-elf

Despite what the name suggests, this installs a toolchain that supports both the 32-bit and 64-bit architectures.

Using the assembler

Here is a typical startup module (startup.s) that you can use for your programs. Another assembly or C source file should define the main subprogram, and optionally override the irq_handler subprogram.

    .section vectors, "x"

    .global __reset
__reset:
    j start

__irq:
    j irq_handler

    .text
    .align 4

    .weak irq_handler
irq_handler:
    mret

start:
    la gp, __global_pointer
    la sp, __stack_pointer
    la t0, __bss_start
    la t1, __bss_end
    bgeu t0, t1, memclr_done
memclr:
    sw zero, (t0)
    addi t0, t0, 4
    bltu t0, t1, memclr

memclr_done:
    call main
    j .

This command assembles the source file startup.s into an object file startup.o:

riscv64-unknown-elf-gcc -march=rv32i -mabi=ilp32 -c -o startup.o startup.s

Using the C compiler

#define TEXT_OUT (*(char*)0xC0000000)

void print(const char *str) {
    while (*str) {
        TEXT_OUT = *str++;
    }
}

void main(void) {
    print("Virgule says\n<< Hello! >>\n");
}

This command compiles the source file hello.c into an object file hello.o:

riscv64-unknown-elf-gcc -march=rv32i -mabi=ilp32 -ffreestanding -c -o hello.o hello.c

If you want to write an interrupt handler in C, you can override the irq_handler subprogram, adding the interrupt attribute like this:

__attribute__((interrupt("machine")))
void irq_handler(void) {
    // Insert your code here.
}

Using the linker

This command links startup.o and hello.o into a binary executable file hello.elf:

riscv64-unknown-elf-gcc -march=rv32i -mabi=ilp32 -nostdlib -T emulsiv.ld -o hello.elf startup.o hello.o

The memory map of the simulator is configured in the linker script emulsiv.ld below:

ENTRY(__reset)

MEM_SIZE    = 4K;
STACK_SIZE  = 512;
BITMAP_SIZE = 1K;

SECTIONS {
    . = 0x0;

    .text : {
        *(vectors)
        *(.text)
        __text_end = .;
    }

    .data   : { *(.data) }
    .rodata : { *(.rodata) }

    __global_pointer = ALIGN(4);

    .bss ALIGN(4) : {
        __bss_start = .;
        *(.bss COMMON)
        __bss_end = ALIGN(4);
    }

    . = MEM_SIZE - STACK_SIZE - BITMAP_SIZE;

    .stack ALIGN(4) : {
        __stack_start = .;
        . += STACK_SIZE;
        __stack_pointer = .;
    }

    .bitmap ALIGN(4) : {
        __bitmap_start = .;
        *(bitmap)
    }

    __bitmap_end = __bitmap_start + BITMAP_SIZE;
}

Converting an executable to the hex format

This command converts an ELF binary file hello.elf into a text file hello.hex in the Intel Hex format:

riscv64-unknown-elf-objcopy -O ihex hello.elf hello.hex

In the simulator, use the button "Open an hex file from your computer" and choose hello.hex or any other hex file that you want to load.

License

emulsiV is free software and is distributed under the terms of the Mozilla Public License 2.0.

This document was created by Guillaume Savaton, ESEO. It is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.