This guide details how to install the development environment for our RISC-V based microcontroller boards.

The installation takes a few steps, but only has to be done once. If you run into trouble along the way, you are welcome to ask Linus for help, via either Canvas or e-mail (remahl@kth.se)

Local development environment (MacOS, Windows, Linux)

Miljön vi använder liknar den ni använt i C-programmeringskursen, och bygger på GCC. Men eftersom mikrokontrollern vi programmerar här är av en annan typ än den du har i din dator måste vi använda en version av GCC som kan “korskompilera” till RISC-V.

The environment that we use is C-based and built on GCC and Make. You need this specific version of GCC since if you have a local copy it is unlikely to be able to cross compile for RISC-V.

In addition the toolchain includes peripheral drivers for the specific chip, so that we can use a slightly more ergonomic C-api to access things like GPIO, serial protocols et.c.

Steg 1. Download the software package

toolchain-gd32v-v200-osx.zip MacOS

toolchain-gd32v-v201-win.zip Windows

toolchain-gd32v-v200-linux.zip Linux

Extract in a folder that you can easily find using a terminal.

(Avoid extracting in a "cloud"-folder (iCloud/Onedrive et.c.) since those are known to cause trouble sometimes.)

Steg 2. Install Commandline Tools and dfu-util (MacOS only)

First check wheter you have CommandLine Tools installed. Open a terminal and write:

gcc -v

If the command is recognized you likely already have CLT installed.

If it was not available write the following command into the terminal and follow the instructions:

xcode-select -–install

(A more exhaustive guide is available from herehttps://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/

Links to an external site. )

When CLT is installed we will install Homebrew using the following command (skip if you already have homebrew installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You may need to write in your local password during the installation.

When the installation finishes there may be some more instructions for a few commands that need to be entered (starting with "echo").

Once Homebrew is installed we can install dfu-util by writing the following into the terminal:

brew install dfu-util

Once that has finished you are ready to proceed.

Steg 2.1: Install Mingw-Make and USB driver (windows only)

If you already have Mingw-make installed you can skip this step.

In the windows package there is a file named “mingw32-make-3.80.0-3.exe”.

Double click it and install according to the instructions. Make note of where you are installing to! (Usually “C:\mingw\”)

Open the start menu and select “Edit the system environment variables”/”Redigera Systemets Miljövariabler”.

Then press “Environment variables...”/”Miljövariabler...”

In the upper box there should be a line named "Path" click it and then press “Edit”.

In the next box press “Ny”/”New” och sen “Browse”. Browse to the installation you just made so you get to the folder "bin". Should be: [installation folder]\bin (usually “C:\mingw\bin”)

Press OK and check that there is now a new line containing the path to the "bin" folder.

Step2.2: Install driver part1 (You need a microcontroller present during install)

Windows also needs a USB-driver to program the microcontroller.

Start by downloading GigaDevices official DFU-driver:

GD32DFUDrivers.exe (7.1MB)

Links to an external site.

Open the program and press install.

Step 2.3: Install driver part 2

This step can only be done once you have a microcontroller card present.

Download the following program:

Zadig 2.5 (4.9MB)

Links to an external site.

Open the program.

Press [options] -> [List all devices] in the menu.

zadig1

Now connect your card while pressing "BOOT". You can let go of boot once the card is connected.

In the dropdown-menu there should be an empty row, or it could be named "GD32 Device In DFU Mode". Click it.

zadig2

If the row is empty press the "Edit"-checkbox (1) and copy in "GD32 Device In DFU Mode" (2).

Then check carefully that the values marked 3 match EXACTLY with the picture below. If the numbers aren't

USB ID: 28E9 0189 try starting over from where you opened Zadig. If you cant get the right numbers to show up here abort here and ask for help.

If (and only if) the USB ID is correct press "Replace Driver". (4)

replace driver

It can take a few minutes but after a while the install should say "Successful"

With that the driver is fully installed.

Note that the installation is coupled with the USB port that was used when doing the Zadig step, so you will need to repeat this step for each port that you want to be able to use for programming your card.

Steg 2.4: USB rules (Linux only)

The toolchain is tested on Ubuntu, but should work on most distribution. What can be slightly different between distros are USB permissions thoug. This method works on most systemd based distros (debian, arch et.c.). If you run something else some additional tinkering may be required and left as an excercise for the reader.

In the toolchain folder you can find "99-gd32v.rules" put it in /usr/lib/udev/rules.d/

The file contains a "rule" which lets the programmer access the usb interface of the card.

Step 3: Creating a new project

Create a new project by copying the folder "template" located in:

[Path to toolchain]/toolchain-gd32v/projects

Rename the copied folder to the project name. Do not use spaces or special characters.

To always be able to make a new project make sure to never change anything inside "template" always make a copy before making changes.

Your source files go directly into the copied folder.

Then open up VSCode and press File→Open folder and find your project: toolchain-gd32v/projects/[your project]

3.2 Configure the environment (MacOS only)

Before opening your first project MacOS needs to be configured to not block the programs used in the toolchain. This is most easily done by left clicking the project in the menu to the left and pressing "Open in integrated terminal"

Then write:

make install

You only need to do this once on your first project.

Step 5: Compile/Download programs

There are two ways to compile and load programs. The easiest is to in the menu press [Terminal]→ [New Task…] and then press:

lio make [ditt projekt]

...to just compile and...

lio make dfu [ditt projekt]

... to load the program into your card.

For the card to be able to be programmed it needs to be set in programming mode which is done by pressing both “BOOT” and “RESET” at the same time and then releasing “RESET” och then releasing “BOOT”. If you did it right the card is now waiting for a program to be sent by running lio make dfu.

It is also possible to run the commands in a terminal.

Open a terminal in VSCode by pressing [Terminal]→[new terminal]

(Make sure that the terminal is navigated inside the project folder that you want to compile)

(MacOS, Linux):

make

(Windows):

mingw32-make

To just compile.

And to both compile and load the program into the card:

(MacOS, Linux):

make dfu

(Windows):

mingw32-make dfu

Make sure to press boot-reset-boot on the card before you run make dfu

Steg 6: Syntax highlighting (Frivilligt)

If you need syntax highlighting on RISC-V assembly you can additionally install the extension "RISC-V Support".

To do that click on "Extensions" and search for "RISC-V Support" and then install.