Mind Chasers Inc.
Mind Chasers Inc.

Getting Started with the RISC-V Open Source GNU Toolchain

We build the RISC-V software tools from their Git repositories and create & verify assembly instructions against the open source ISA specification for an RV32IM core.

Creating the United States
  • Update: We are working hard here on a follow-on to our Darsena system for Private Island and plan to announce a new platform in the second quarter of this year (2021). We're very excited about it!
  • We will be posting more information soon.

Overview

We continue to work with the RISC-V open source ISA as we pursue development of our own implementation for embedding in an FPGA. We need a software toolchain to create assembly instructions & sequences for the purpose of execution in both a simulator and target FPGA. Therefore, we have posted this page to document some of the getting started steps required to work with the software tools and produce executable assembly. Our goal is to develop a 32-bit microcontroller for fixed-point operations inside an FPGA integrated with our Private Island ® open source project for FPGAs.

A good resource for reviewing the available RISC-V software related tools is the RISC-V Software Ecosystem Overview page. In the steps shown below, we'll be working with the RISC-V toolchain repos found on the Github page RISC-V GNU Compiler Toolchain.

Build the Toolchain

The following steps are performed on an Ubuntu 18.04 machine and closely follow the documentation available on the aforementioned Github page. Also, refer to this page for a list of required packages for Ubuntu (e.g., libtool).

We first recursively clone the suite of open source GNU tools for RISC-V:

$ cd /build
$ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
Cloning into 'riscv-gnu-toolchain'...
...
Submodule 'qemu' (https://git.qemu.org/git/qemu.git) registered for path 'qemu'
Submodule 'riscv-binutils' (https://github.com/riscv/riscv-binutils-gdb.git) registered for path 'riscv-binutils'
Submodule 'riscv-dejagnu' (https://github.com/riscv/riscv-dejagnu.git) registered for path 'riscv-dejagnu'
Submodule 'riscv-gcc' (https://github.com/riscv/riscv-gcc.git) registered for path 'riscv-gcc'
Submodule 'riscv-gdb' (https://github.com/riscv/riscv-binutils-gdb.git) registered for path 'riscv-gdb'
Submodule 'riscv-glibc' (https://github.com/riscv/riscv-glibc.git) registered for path 'riscv-glibc'
Submodule 'riscv-newlib' (git://sourceware.org/git/newlib-cygwin.git) registered for path 'riscv-newlib'
...
Submodule path 'riscv-binutils': checked out 'f35674005e609660f5f45005a9e095541ca4c5fe'
Submodule path 'riscv-dejagnu': checked out '4ea498a8e1fafeb568530d84db1880066478c86b'
Submodule path 'riscv-gcc': checked out '03cb20e5433cd8e65af6a1a6baaf3fe4c72785f6'
Submodule path 'riscv-gdb': checked out '5da071ef0965b8054310d8dde9975037b0467311'
Submodule path 'riscv-glibc': checked out '9826b03b747b841f5fc6de2054bf1ef3f5c4bdf3'
Submodule path 'riscv-newlib': checked out '415fdd4279b85eeec9d54775ce13c5c412451e08'

Let's make sure we understand that we just cloned a repository of repositories:

$ cd /build/riscv-gnu-toolchain/

$ git log 
commit b715e4f01b43efef487166f75d5d85d3c33fa7ef (HEAD -> master, origin/master, origin/HEAD)
Author: Kito Cheng 
Date:   Thu Apr 22 23:32:35 2021 +0800

    Bump riscv-binutils
        
$ cd riscv-binutils

$ git log
commit f35674005e609660f5f45005a9e095541ca4c5fe (HEAD, origin/riscv-binutils-2.36.1, origin/HEAD, riscv-binutils-2.36.1)
Author: Nick Clifton 
Date:   Sat Feb 6 09:12:37 2021 +0000

    This is 2.36.1 release

Next we configure our build in a separate sub directory to produce a toolchain for a 32-bit RISC-V core (RV32IM):

  • RV32I: Base Integer Instruction Set
  • M: Instructions that multiply and divide values held in two integer registers
$ cd /build/riscv-gnu-toolchain/

$ mkdir build; cd build

$ ../configure --help | grep abi
  --with-abi=lp64d        Sets the base RISC-V ABI, defaults to lp64d
  
 

$ ../configure --prefix=/opt/riscv32 --with-arch=rv32im --with-abi=ilp32
checking for gcc... gcc
...
config.status: creating Makefile
config.status: creating scripts/wrapper/awk/awk
config.status: creating scripts/wrapper/sed/sed

Note that ilp32 specifies that int, long, and pointers are all 32-bits

After configure is complete, we can make our code. Note that make also performs an install into the path specified by --prefix: /opt/riscv32.

$ make

$ ls
build-binutils-newlib    build-gcc-newlib-stage2  build-newlib       config.log     install-newlib-nano  scripts
build-gcc-newlib-stage1  build-gdb-newlib         build-newlib-nano  config.status  Makefile             stamps

Note that the overall build took approximately 30 minutes on a Dell 7740 Precision laptop with an 8-core I9 (2.3 GHz), 64 GB of RAM, and /build mounted on a 2.5" 1TB 7200RPM SATA Hard Drive.

Let's take a look at what we built & installed:

$ cd /opt/riscv32

$ tree -L 3 -d
.
├── bin
├── include
│   └── gdb
├── lib
│   ├── bfd-plugins
│   └── gcc
│       └── riscv32-unknown-elf
├── libexec
│   └── gcc
│       └── riscv32-unknown-elf
├── riscv32-unknown-elf
│   ├── bin
│   ├── include
│   │   ├── bits
│   │   ├── c++
│   │   ├── machine
│   │   ├── newlib-nano
│   │   ├── rpc
│   │   ├── ssp
│   │   └── sys
│   └── lib
│       └── ldscripts
└── share
    ├── gcc-10.2.0
    │   └── python
    ├── gdb
    │   ├── python
    │   ├── syscalls
    │   └── system-gdbinit
    ├── info
    ├── locale
    │   ├── bg
    │   ├── ca
    │   ├── da
    │   ├── de
...
    │   ├── tr
    │   ├── uk
    │   ├── vi
    │   ├── zh_CN
    │   └── zh_TW
    └── man
        ├── man1
        ├── man5
        └── man7

Next we set up an env-riscv script that we can source when we need to work with our toolchain. Later we'll add environment variables like CFLAGS to it.

file: /opt/riscv32/env-riscv32:

export PATH=/opt/riscv32/bin:$PATH

Let's make sure we can execute our tools:

$ mkdir -p ~/Projects/riscv

$ source /opt/riscv32/env-riscv32

$ riscv32-unknown-elf-gcc --version
riscv32-unknown-elf-gcc (GCC) 10.2.0
...

$ riscv32-unknown-elf-objcopy --version
GNU objcopy (GNU Binutils) 2.36.1

Great, we see that we're ready to go with our compiler and binutils. However, before we move on, let's do some inspection of our compiler to see how it's been configured:

$ riscv32-unknown-elf-gcc -dumpmachine
riscv32-unknown-elf

$ riscv32-unknown-elf-gcc -print-sysroot
/opt/riscv32/riscv32-unknown-elf

$ riscv32-unknown-elf-gcc -print-libgcc-file-name
/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/libgcc.a

$ riscv32-unknown-elf-gcc -print-search-dirs
install: /opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/
programs: =/opt/riscv32/libexec/gcc/riscv32-unknown-elf/10.2.0/:/opt/riscv32/libexec/gcc/riscv32-unknown-elf/10.2.0/:/opt/riscv32/libexec/gcc/riscv32-unknown-elf/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/../../../../riscv32-unknown-elf/bin/riscv32-unknown-elf/10.2.0/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/../../../../riscv32-unknown-elf/bin/
libraries: =/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/../../../../riscv32-unknown-elf/lib/riscv32-unknown-elf/10.2.0/:/opt/riscv32/lib/gcc/riscv32-unknown-elf/10.2.0/../../../../riscv32-unknown-elf/lib/:/opt/riscv32/riscv32-unknown-elf/lib/riscv32-unknown-elf/10.2.0/:/opt/riscv32/riscv32-unknown-elf/lib/:/opt/riscv32/riscv32-unknown-elf/usr/lib/riscv32-unknown-elf/10.2.0/:/opt/riscv32/riscv32-unknown-elf/usr/lib/

Let's confirm we're working with the newlib-nano library:

$ ls /opt/riscv32/riscv32-unknown-elf/lib
crt0.o     libc.a       libg.a      libgloss_nano.a  libm.a       libnosys.a     libsim.a     libstdc++.a-gdb.py  libsupc++.a   nano.specs   semihost.specs
ldscripts  libc_nano.a  libgloss.a  libg_nano.a      libm_nano.a  libsemihost.a  libstdc++.a  libstdc++.la        libsupc++.la  nosys.specs  sim.specs

Build a simple function and analyze it against the specification

Shown below is a very simple C program that has a multiply function mult() for the purpose of obtaining the RV32IM instructions used to multiply two integers. This is certainly something we want to do in our FPGA with our RISC-V.

int mult() {
        int a=1000,b=3;
        return a*b;
}

int main() {
        mult();
}

We build the simple C application "tst.c" with our new RISC-V GCC compiler:

$ export PATH=/opt/riscv32/bin/:$PATH

$ riscv32-unknown-elf-gcc -g tst.c -o tst

$ file tst
tst: ELF 32-bit LSB executable, UCB RISC-V, version 1 (SYSV), statically linked, with debug_info, not stripped

Since our ELF executable isn't stripped, it has section headers and objdump can be used to analyze the code:

$ riscv32-unknown-elf-objdump -d tst

...
00010150 <mult>:
   10144:   fe010113            addi    sp,sp,-32
   10148:   00812e23            sw  s0,28(sp)
   1014c:   02010413            addi    s0,sp,32
   10150:   3e800793            li  a5,1000
   10154:   fef42623            sw  a5,-20(s0)
   10158:   00300793            li  a5,3
   1015c:   fef42423            sw  a5,-24(s0)
   10160:   fec42703            lw  a4,-20(s0)
   10164:   fe842783            lw  a5,-24(s0)
   10168:   02f707b3            mul a5,a4,a5
   1016c:   00078513            mv  a0,a5
   10170:   01c12403            lw  s0,28(sp)
   10174:   02010113            addi    sp,sp,32
   10178:   00008067            ret
...

We can see in the dump of mult() above that our two operands are retrieved into registers using load immediate (li) but then pushed onto the stack before retrieving them again using load word (lw) into registers a4 and a5. The actual multiply operation is perfomed by the mul instruction.

We can find the definition of these instructions in the Unprivileged ISA specification. Specifically, the mul instruction is defined in Chapter 7. This is the "M" extension for our RV32IMA core.

We can see that the "mul a5,a4,a5" instruction is encoded as 0x02f707b3. Keep in mind that RISC-V is a little-endian system, especially when working with debuggers and viewing memory.

Referring to Chapter 25 (RISC-V Assembly Programmer’s Handbook) of the Unprivileged ISA Specification, we find that registers a2 through a7 are considered function argument registers and are mapped to x12 through x17. Therefore, a4-a5 are registers x14-x15 respectively.

Next, let's refer to Chapter 24 (RV32/64G Instruction Set Listings) and compare our instruction's encoded value against what is shown for MUL:

31-25 24-20 19-15 14-12 11-7 6-0
MUL 0000001 rs2 rs1 000 rd 0110011
15 14 15

So, now we have confirmed that the master branch of the GNU RISC-V tools do indeed create assembly that matches the RV32IM specification (at least for MUL). Perhaps it's now a little easier to envision some of the stages of a RISC-V pipeline (e.g., instruction/data fetch and instruction decode).

Some natural next steps for an FPGA-based microcontroller includes creating a bare metal software build environment, linker script, along with the proper startup code and exception table.

We'll continue to update this page as we progress with testing, developing, and integrating our RISC-V core.

Common RISC-V Terms and Acronyms

Terms

  • Chisel: Constructing Hardware in a Scala Embedded Language
  • Exception: "Unusual condition occurring at run time associated with an instruction in the current RISC-V hart"
  • Hart: Hardware Thread
  • Interrupt: "external asynchronous event that may cause a RISC-V hart to experience an unexpected transfer of control"
  • SemVer: Semantic Versioning
  • Tile: (Rocket) Core + Private Caches
  • Trap: "Transfer of control to a trap handler caused by either an exception or an interrupt."
  • XLEN: "Width of an integer register in bits"

Acronyms

  • AEE: Application Execution Environment
  • AUIPC: Add Upper Immediate to PC
  • DSL: Domain-Specific Language
  • EEI: Execution Environment Interface
  • FESVR: Front End Server
  • FIRRTL: Flexible Intermediate Representation for RTL
  • HTIF: Host-Target Interface
  • JAL: Jump and Link
  • IR: Intermediate Representation
  • MTVEC: Machine Trap-Vector Base-Address Register
  • RISC: Reduced Instruction Set Computation/Computer
  • SEE: Supervisor Execution Environment

Additional RISC-V and Embedded Programming References

Didn't find an answer to your question? Post your issue below or in our new FORUM, and we'll try our best to help you find a solution.

And please note that we update our site daily with new content related to our open source approach to network security and system design. If you would like to be notified about these changes, then please follow us on Twitter and join our mailing list.

Related articles on this site:

share
subscribe to mailing list:

Date: April 21, 2021

Author: Christopher Morales

Comment:

Its been hard for me to "make", i had to install make, texinfo, bison and flex so that i didn't get an error. But still it's been about 22min, and it hasnt finished. My question is, how long does it normally takes to "make" so that i know that im making things right.

Date: April 23, 2021

Author: Mind Chasers

Comment:

Thank you for the question Christopher. Others have posted the same question. It takes about 30 minutes for us to build the complete toolchain as configured. Note that we now include this information in our article along with the machine we used. We rebuild the toolchain infrequently, so we haven't spent any effort to improve build time.

Add a new comment here or reply to one above:

your email address will be kept private
authenticate with a 3rd party for enhanced features, such as image upload
previous month
next month
Su
Mo
Tu
Wd
Th
Fr
Sa
loading