Baremetal RISC-V Renode - Part 1: Blinky

What is baremetal?

In the non-embedded world, when you compile and link a C program into an executable you are doing so with the intention of running it within a specific operating system. When you compile baremetal or -freestanding you are telling the compiler that you intend to run this without relying on an operating system. This could be used, for example, to write an operating system. Alternatively it can be used to access the hardware of a system directly on an embedded system. Doing so sacrifices higher level luxuries such as memory management, standard IO, thread/process control, etc. Because of this, sometimes it makes sense to run on a type of minimal OS optimized for embedded, e.g. a real time operating system or RTOS.

When you use a commercial development platform, you will likely be provided with a cross compiling toolchain and possibly an RTOS. For an example see freedom-e-sdk. Alternatively, there are also attempts to make small, but hardware agonistic RTOS see zephyr.

What is RISC-V?

RISC-V is an open alternative to ARM or x86.

Wikipedia

RISC-V (pronounced "risk-five") is an open standard instruction set architecture (ISA) based on established reduced instruction set computer (RISC) principles. Unlike most other ISA designs, the RISC-V ISA is provided under open source licenses that do not require fees to use.

What is Renode?

Renode is a simulator designed for embedded firmware. What sets it apart is the goal of not only emulating CPUs and SOCs, but also entire boards with peripherals such as ethernet and even multi-node networks of devices.

Alternatives such as QEMU aren't as optimized for the embedded space.

An emulator that you might use for playing video game ROMs is specialized for a single platform. For example, in an emulator cpu, graphics chips, audio, memory-map, etc are fixed and optimized. Renode on the other hand configures each platform with a config file.

Building

To ease the burden on my own memory, I have added a Makefile to capture the various build options for the toolchains. If you have all of the build requirements already installed, building both can be as simple as:

$ cd baremetal-riscv-renode
$ make toolchains

Running make toolchains should usually be enough to let you know what you are missing. I have included some hints below, check the comments as well as different distros may have different packages.

Build requirement hints

Below are my hints for which packages to install, this can be different depending on the distribution. I've also included links to the official guides for getting unstuck.

gawk texinfo bison flex libncurses5-dev libncursesw5-dev

automake autoconf libtool g++ coreutils policykit-1 libgtk2.0-dev screen uml-utilities gtk-sharp2 python3

Just get it running

First open up the project folder:

$ cd 1_blinky

Then following command will handle all steps 1-3, we'll break this down later:

$ make launch

If everything went correctly, you should see something like this:

You should have also noticed the monitor window open up. This is used to control the running renode machine; the ? command will list the rest. The tab completion is also very helpful.

Quit using q or quit:

(vexriscv-machine) quit

Alternatively you can kill renode using CTRL + C in the terminal that you launched it from.

Hardware configuration

The hardware to will be simulated is defined using a renode specific platform description format [3]

vexriscv.repl:

mem: Memory.MappedMemory @ sysbus 0x0
    size: 0x00040000

cpu: CPU.VexRiscv @ sysbus

gpio_out: GPIOPort.LiteX_GPIO @ sysbus 0x60000800
    type: Type.Out
    0 -> led0@0
    1 -> led1@0

led0 : Miscellaneous.LED @ gpio_out 0
led1 : Miscellaneous.LED @ gpio_out 1

I like this because we can make a very minimal hardware configuration, free from any vendor specific complexity. Besides the cpu and memory, we have a general purpose input output (GPIO) register mapped to memory location 0x60000800. The -> makes a connection from the GPIO pins to the LEDs. I don't exactly know why we need both 0 -> led0@0 and @ gpio_out 0 as it seems redundant; if anyone knows, please let me know. You'll also commonly see -> used for connecting interrupts.

To toggle the LED we will need to write a driver that knows how to control the GPIO by writing to it's register.

Blinky source code

This initial program is written exclusively in RISC-V assembly [4] this is simple enough that every instruction that gets executed can be traced to this source file.

The code to drive this GPIO device is dead simple, you just need to write data to the memory location that maps to the GPIO pins.

Note that the platform specifies the mapping of 0x60000800 to the GPIO register.

baremetal.s:

.equ LED, 0x60000800
.equ DELAY_COUNT, 9000000
.equ LED_STATE_INITIAL, 0b00
.equ LED_STATE_TOGGLE_MASK, 0b01

.section .text
.global _start
_start:
        li a5, LED
        li a4, LED_STATE_INITIAL
        li a6, LED_STATE_TOGGLE_MASK
        sw a4, 0x0(a5)
loop:
        li a0, DELAY_COUNT      # reset counter
delay_loop:
        addi a0, a0, -1         # count down
        bnez a0, delay_loop
toggle_led:
        lw a4, 0x0(a5)          # read in old led state
        xor a4, a4, a6          # toggle led state word
        sw a4, 0x0(a5)          # write new state
        jump loop, t0

Attaching the GNU Debugger

After launching, you may attach GDB using make debug. This connects to the GDB server already running within Renode. It uses a GDB script to store default configuration, such as breaking execution and starting the text user interface or TUI, which shows source code alongside the disassembly.

$ make launch
$ make debug

If you are familiar with GDB you know the power of setting breakpoint, inspecting stacks, and much much more.

GDB Text User Interface (TUI)

Useful GDB scenarios

There are a couple simple commands that I find to be useful when exploring baremetal programming.

(gdb) si
(gdb) █

(gdb) c
Continuing.

(gdb) c
Continuing.

Program received signal SIGTRAP, Trace/breakpoint trap.
delay_loop () at baremetal.s:13
(gdb) █

(gdb) b toggle_led
Breakpoint 1 at 0x10074: file baremetal.s, line 16.
(gdb) c
Continuing.

Breakpoint 1, toggle_led () at baremetal.s:16
(gdb) █

(gdb) info registers
    ra             0x0      0x0
    fp             0x0      0x0
    s1             0x0      0
    a0             0x24648f 2385039
    ...
    t4             0x0      0
    t5             0x0      0
    t6             0x0      0
    pc             0x1006c  0x1006c <delay_loop>

(gdb) p $pc
$5 = (void (*)()) 0x10074 <toggle_led>
(gdb) p $a4
$6 = 2

(gdb) set $pc=delay_loop
(gdb) c
Continuing.