RISC-V

This page describes the status of the FreeBSD/RISC-V port, an adaptation of the FreeBSD Operating System to run on the RISC-V Instruction-Set Architecture (ISA).

As a result of this work, FreeBSD is able to boot to multi-user mode on the QEMU emulator, Spike simulator and real hardware (see below). Following a number of commits to the FreeBSD subversion repository in January 2016 (see riscv/history), FreeBSD is the first operating system to have bootable in-tree support for RISC-V. This work was supported by the DARPA CTSRD Project at the University of Cambridge Computer Laboratory and is led by RuslanBukin.

The FreeBSD Foundation posted a blog article describing the RISC-V porting effort and merge of architectural support to the FreeBSD base system in January 2016.

Though RISC-V can support up to a 48-bit virtual addressing scheme, the FreeBSD/RISC-V port currently supports the 39-bit virtual addressing scheme (r298580).

Current Status

FreeBSD's support for the RISC-V architecture is currently classified as Tier-2, beginning with FreeBSD 13.0. It was present with Tier-3 support in FreeBSD 11 and 12.

Supported Platforms

Available Platforms

Target

Type

Support

Tested Features

Availability

Spike

emulator

fully supported

SMP

QEMU

emulator

fully supported

SMP, virtio-block, virtio-net

HiFive Unleashed (SiFive FU540)

hardware

fully supported

SMP, mmcsd, ethernet

discontinued; "basically impossible to obtain" -- KristofProvost

Announced Platforms

These are boards that we believe will be supported at some point.

Target

Type

Support

Tested Features

Availability

Beagle-V

hardware

unknown

see here for earlyl availability info

HiFive Unmatched (SiFive FU740)

hardware

N/A

pre-orders announced; Pre-order on Mouser; Pre-order on Crowd Supply

PolarFire SoC Icicle Kit

hardware

status unknown

Purchase on Crowd Supply

Platforms With Unknown Support

Target

Type

Support

Tested Features

Availability

Rocketchip

hardware

status unknown

lowRISC

hardware

status unknown

Unsupported Platforms

The Kendryte K210 based systems will not be supported on FreeBSD due to MMU and RAM limitations.

There is no existing or planned support for 32-bit RISC-V systems at the time of writing (April 2021). This choice could be revisited if this proves to be a popular hardware configuration, but so far it has not.

Contact

People

A non-comprehensive list of committers who currently work on RISC-V:

IRC channel

See IRC/Channels.

Mailing List

freebsd-riscv

Toolchain

After r356499, the default toolchain is the in-tree clang/lld.

ExternalGCC is also supported.

Sources

All FreeBSD RISC-V sources have been upstreamed and development happens in HEAD. For the development history, see riscv/history.

HEAD build status: https://ci.freebsd.org/job/FreeBSD-main-riscv64-build/

13-STABLE build status: https://ci.freebsd.org/job/FreeBSD-stable-13-riscv64-build/

Quick Start

This section describes how to boot the official release snapshots in QEMU.

To build your own image for development or customization, see #Build Instructions, below.

Install required packages

sudo pkg install opensbi u-boot-qemu-riscv64 qemu

Note: emulators/qemu-devel also works.

Download FreeBSD/RISC-V virtual machine image

fetch https://download.freebsd.org/ftp/snapshots/VM-IMAGES/14.0-CURRENT/riscv64/Latest/FreeBSD-14.0-CURRENT-riscv-riscv64.raw.xz
xz --decompress FreeBSD-14.0-CURRENT-riscv-riscv64.raw.xz

Optionally, extend the image using truncate(1). The root filesystem will grow to fill the free space upon first boot.

truncate -s 10G FreeBSD-14.0-CURRENT-riscv-riscv64.raw

Boot image in QEMU

Spawn a VM with 2 CPUs and 2GB of memory:

qemu-system-riscv64 -machine virt -m 2048M -smp 2 -nographic \
    -bios /usr/local/share/opensbi/lp64/generic/firmware/fw_jump.elf \
    -kernel /usr/local/share/u-boot/u-boot-qemu-riscv64/u-boot.bin \
    -drive file=FreeBSD-14.0-CURRENT-riscv-riscv64.raw,format=raw,id=hd0 -device virtio-blk-device,drive=hd0 \
    -netdev user,id=net0,ipv6=off,hostfwd=tcp::8022-:22 -device virtio-net-device,netdev=net0

Log in as root without password. You can connect ssh into the VM using port 8022 on the host.

For more information on running in QEMU, see riscv/QEMU.

Build Instructions

This section describes how to build a riscv64 bootable image from source.

External Toolchain Setup (Optional)

In order to compile FreeBSD for the riscv64 target, a cross-toolchain is needed. By default the in-tree LLVM will be bootstrapped during the build for this purpose so it is recommended to skip this section, and the system toolchain can also be used on any FreeBSD system with base LLVM version 9 or greater. Otherwise, follow the instructions below to set up an external GCC toolchain.

Install External GCC Toolchain

Install the riscv64-gcc9 (devel/freebsd-gcc9@riscv64) and riscv64-binutils (devel/binutils@riscv64) packages:

sudo pkg install riscv64-gcc9 riscv64-binutils

This provides /usr/local/share/toolchains/riscv64-gcc9.mk to be used as CROSS_TOOLCHAIN=riscv64-gcc9 when building FreeBSD.

Build GCC toolchain manually

If you prefer, a GCC toolchain can also be compiled from source. This fork is not actively updated or tested, but it should still work fine.

Set up toolchain installation directory

setenv PREFIX $HOME/riscv

Install required packages

sudo pkg install bison gmp mpfr mpc gawk gsed pkgconf texinfo

Build

git clone https://github.com/freebsd-riscv/riscv-gnu-toolchain
cd riscv-gnu-toolchain
git submodule update --init --recursive
./configure --prefix=$PREFIX
gmake -j16 freebsd

Cross-compile FreeBSD

Build FreeBSD world

No different than other architectures:

make TARGET_ARCH=riscv64 buildworld

Using GCC package

make CROSS_TOOLCHAIN=riscv64-gcc9 TARGET_ARCH=riscv64 buildworld

Using a toolchain built by hand

setenv CROSS_BINUTILS_PREFIX $PREFIX/riscv64-unknown-freebsd12.0/bin/
setenv CROSS_COMPILER_PREFIX $PREFIX/bin/riscv64-unknown-freebsd12.0-
setenv XCC ${CROSS_COMPILER_PREFIX}gcc
setenv XCXX ${CROSS_COMPILER_PREFIX}c++
setenv XCPP ${CROSS_COMPILER_PREFIX}cpp
setenv STRIPBIN ${CROSS_COMPILER_PREFIX}strip

setenv X_COMPILER_TYPE gcc

make TARGET_ARCH=riscv64 buildworld

Build FreeBSD kernel

make TARGET_ARCH=riscv64 buildkernel

For QEMU add KERNCONF=QEMU in make parameters. As above, set the appropriate arguments if using GCC.

Or get from: artifact.ci.freebsd.org/snapshot/head/latest/riscv/riscv64/kernel.txz (Extract kernel with: tar Jxvf kernel.txz --strip-components 3 boot/kernel/kernel )

Bootloader

OpenSBI

OpenSBI is a RISC-V bootloader and SBI firmware. It is a recommended alternative to BBL that has a larger feature set and is more actively maintained.

To get started with OpenSBI, please install sysutils/opensbi. This will install the OpenSBI firmware files for various platforms. See the section below on running QEMU for an example of booting with OpenSBI. Note that a version of OpenSBI is shipped with QEMU, as of QEMU version 4.2. It can be selected with the "-bios default" option, but it may lag behind the OpenSBI version available in ports.

OpenSBI can also be built from source. It requires the RISC-V bare-metal toolchain to be installed. Install the riscv64-none-elf-gcc and riscv64-none-elf-binutils (a FLAVOR of devel/binutils) packages.

git clone https://github.com/riscv/opensbi.git
cd opensbi
gmake CROSS_COMPILE=riscv64-none-elf- PLATFORM=generic

The firmware files will be available by default in build/platform/generic/firmware/. Add FW_PAYLOAD_PATH=/path/to/riscv/kernel to the gmake parameters to embed a custom payload into the fw_payload binaries. Add FDT_PAYLOAD_PATH=/path/to/fdt.dtb to the gmake parameters to embed a static device tree blob.

Consult OpenSBI's documentation for information on its supported platforms.

BBL (Berkley Boot Loader)

BBL is the RISC-V bootloader originally used by FreeBSD. It is slowly becoming legacy software in favor of OpenSBI, but it is still maintained and may be useful for bringup on platforms not yet supported by OpenSBI.

To build BBL:

git clone https://github.com/riscv/riscv-pk.git
cd riscv-pk
mkdir build && cd build
setenv PATH ${PATH}:${PREFIX}/bin
setenv CPP cpp
setenv CFLAGS "-nostdlib"
setenv WITH_ARCH rv64gc
../configure --enable-logo --prefix=$PREFIX --host=riscv64-none-elf --without-payload
gmake bbl
unsetenv CFLAGS
unsetenv CPP

This will generate the bbl firmware binary in the current directory.

Installation

Install FreeBSD world and kernel

setenv DESTDIR /home/${USER}/riscv-world
make TARGET_ARCH=riscv64 -DNO_ROOT DESTDIR=$DESTDIR installworld
make TARGET_ARCH=riscv64 -DNO_ROOT DESTDIR=$DESTDIR distribution
make TARGET_ARCH=riscv64 -DNO_ROOT DESTDIR=$DESTDIR installkernel

Build a complete rootfs image to run in QEMU

cd $DESTDIR
sed -E 's/time=[0-9\.]+$//' METALOG > METALOG.new
mv METALOG.new METALOG
echo 'hostname="qemu"' > etc/rc.conf
echo "/dev/vtbd0        /       ufs     ro      1       1" > etc/fstab
echo "./etc/fstab type=file uname=root gname=wheel mode=0644" >> METALOG
echo "./etc/rc.conf type=file uname=root gname=wheel mode=0644" >> METALOG
makefs -D -f 1000000 -o version=2 -s 10g riscv.img METALOG

Or get from artifact.ci.freebsd.org/snapshot/head/latest/riscv/riscv64/riscv.img.zst

Alternatively, build a small rootfs for Spike to be used as mdroot (memory disk)

cd freebsd-riscv
fetch https://raw.githubusercontent.com/bukinr/riscv-tools/master/image/basic.files
tools/tools/makeroot/makeroot.sh -s 32m -f basic.files riscv.img $DESTDIR

Ensure you have correct path to riscv.img in your kernel config for Spike:

options         MD_ROOT
options         MD_ROOT_SIZE=32768      # 32MB ram disk
makeoptions     MFS_IMAGE=/path/to/riscv.img
options         ROOTDEVNAME=\"ufs:/dev/md0\"

Boot FreeBSD

QEMU Emulator

Support for RISC-V has landed upstream in qemu. The easiest way to get started is to install emulators/qemu-devel.

Run QEMU

Load tap kernel module if not loaded:

sudo kldload if_tuntap

Configure the network with tap(4):

ifconfig tap0 create up
ifconfig bridge0 create up
ifconfig bridge0 addm em0 addm tap0 # em0 might depends of your ethernet devices

Run QEMU, specifying FreeBSD with -kernel and SBI firmware with -bios

sudo qemu-system-riscv64 -machine virt -m 2048M -smp 2 -nographic -kernel /path/to/kernel -bios /path/to/sbi/firmware -drive file=/path/to/riscv.img,format=raw,id=hd0 -device virtio-blk-device,drive=hd0 -netdev tap,ifname=tap0,script=no,id=net0 -device virtio-net-device,netdev=net0

If you get mountroot prompt, then indicate to the kernel the location of rootfs:

mountroot> ufs:/dev/vtbd0

This parameter can also be passed into the qemu-system-riscv64 string, specifying the device and partition such as "vtbd0" or "vtbd0p3":

-append "vfs.root.mountfrom=ufs:/dev/vtbd0"

Spike Simulator

Build Spike

# Use clang on FreeBSD
setenv CXX c++
setenv PREFIX $HOME/riscv

git clone https://github.com/freebsd-riscv/riscv-isa-sim
cd riscv-isa-sim
mkdir build && cd build
setenv CPPFLAGS -DRISCV_ENABLE_DIRTY=1
../configure --prefix=$PREFIX
gmake install

Or install emulators/riscv-isa-sim

Run Spike

./riscv-isa-sim/build/spike -m2048 -p2 /path/to/bbl

RocketChip

Create sdcard using 'Quick instructions' on https://github.com/ucb-bar/fpga-zynq, then copy bbl to sdcard (to the first msdos partition). Once you have booted linux from sdcard on Zedboard, then you can run FreeBSD/RISC-V:

./fesvr-zynq /mnt/boot/bbl

Ports on RISC-V

See riscv/ports.

TODO

A collection of in-progress and planned work as well as some future ideas. Contributions are welcome, so if you'd like to work on something please contact the owner or ask in IRC.

Bugzilla

Query RISC-V related bugs here.

New/Missing Features

Project

Owner

Status

Comments

Fix failing tests

Open

Check the latest run ci.freebsd.org/job/FreeBSD-head-riscv64-test/lastCompletedBuild/testReport/ from CI

PMC

Open

SBI PMU extension has been proposed, awaiting inclusion in the spec

PTrace

Open

Investigate the state of ptrace on RISC-V. Make improvements as necessary.

Kernel ifunc support

Open

Support landed in lld here, should be present in lld 11

Improve RISC-V timer driver

Open

Some small improvments to be made. See about adding support for VDSO timehands for userspace gettimeofday(3)

Performance Improvements

Task

Owner

Status

Comments

pmap fixes

Open

Address TODO comments in riscv/pmap.c

pmap Global bit

mhorne

In-progress

pmap ASIDs

Open

QEMU supports ASIDs. See: D21922

CLINT/CLIC driver

Investigation

Investigate adding a driver for the CLIC. This could reduce the cost of IPIs by avoiding SBI ecall.

Future/Larger Projects

Project

Owner

Status

Comments

linuxulator

Open

Add the MD support for FreeBSD's Linux subsystem

sv48 virtual memory scheme

Open

Support a 4th level page table for machines where sv39 does not provide enough kva

RISC-V Vector Extension Support

Open

Vector extension spec is not yet ratified, but support is beginning to land in GCC/Clang.

RISC-V hypervisor

Open

Necessary support present in OpenSBI. Some resources here.

UEFI

Open

Add support for EFI runtime services. Keep an eye on progress of edk2/OVMF.

Useful Links

Specifications

RISC-V ISA Specifications

RISC-V ELF ABI Specification

RISC-V Supervisor Binary Interface Specification

ELF handling for thread-local storage

Presentations

FreeBSD/RISC-V workshop slides video

FreeBSD Foundation blog post on the RISC-V port

FOSDEM 2019 Embedded FreeBSD on a five-core RISC-V processor using LLVM

See Also

riscv (last edited 2021-04-26 14:40:23 by MitchellHorne)