• riscv

RISC-V

Introduction

FreeBSD/RISC-V is a architecture port for FreeBSD to run on the RISC-V Instruction-Set Architecture (ISA), able to boot to multi-user mode on the QEMU emulator, Spike simulator and real hardware.

History

Following a number of commits to the FreeBSD subversion repository in January 2016 (see riscv/history), FreeBSD was 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 led by RuslanBukin.

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

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 12.

Earlier versions of the privileged ISA and ELF psABI was supported in FreeBSD 11, but both saw breaking changes in the interim so FreeBSD 12 is the first version with which the current port is backwards compatible.

Address Space

Though RISC-V can support up to a 57-bit virtual addressing scheme, the FreeBSD/RISC-V port currently supports the 39-bit virtual addressing scheme (02a371289a37) and partially supports (userspace only) the 48-bit (31218f3209ac) scheme.

There is sv39, which is required, and sv48 and sv57, which are optional. Each is just the previous one with an extra level, nothing else. Hardware supporting sv57 is required to support sv48, and hardware supporting sv48 is required to support sv39. The svXX designation is the number of bits of virtual address supported; however, the encoding for sv64 mode is reserved.

Given that the current page table formats are limited to a 56-bit physical address space it's unclear how useful anything above sv57 would be.

Supported Platforms

Available Platforms

Announced Platforms

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

Unsupported Platforms

FreeBSD supports 64-bit RISC-V CPUs only.

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

The ASUS Tinker V, and any other platform based on the same AX45MP core IP configured with the ILM and/or DLM enabled, is unlikely to be supported on FreeBSD due to its SoC violating the RISC-V Sv39 specification, which would likely require intrusive patches to work around.

Hypervisor (Bhyve) support

Work is in progress. See riscv/bhyve

Contact

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.

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/snapshots/VM-IMAGES/15.0-CURRENT/riscv64/Latest/FreeBSD-15.0-CURRENT-riscv-riscv64.raw.xz
xz --decompress FreeBSD-15.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-15.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-15.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 bootable riscv64 image from source.

Cross-compile FreeBSD

The riscv64 architecture is fully supported by the in-tree clang/LLVM toolchain.

Build FreeBSD world

No different than other architectures:

make TARGET_ARCH=riscv64 buildworld

Build FreeBSD kernel

make TARGET_ARCH=riscv64 buildkernel

For QEMU add KERNCONF=QEMU in make parameters.

Bootloader

OpenSBI

OpenSBI is a RISC-V bootloader and SBI firmware. This project is actively developed and the de-facto standard for booting FreeBSD.

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.

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     rw      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

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"

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

PMAP Improvements

Future/Larger Projects

Security/Stability

/BeagleV   /HiFiveUnmatched   /QEMU   /Spike   /StarFive   /THEAD   /TestSuite   /U-Boot-ports   /bhyve   /history   /ports

Useful Links

Specifications

RISC-V ISA Specifications

RISC-V ABI Specification

RISC-V Supervisor Binary Interface Specification

RISC-V Platform Specification

ELF handling for thread-local storage

Presentations

FreeBSD Fridays: Introduction to RISC-V

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

Overlap With Other Documentation

ARM board documentation

The following pages were specifically written for ARM boards. However, much of the information is not ARM-specific, and should be generalized for RISC-V -- but that has not happened yet.

• arm/Allwinner/booting -- the description of U-Boot may be generally applicable.

• arm/BootProcess -- some of this may be applicable.

• arm/Build_image_notes -- this should be generalized; it is not arm-specific.

• arm/Build_image_using_release_building_infrastructure -- kind of a sub-page of the above. May or may not be applicable.

• arm/SDImage -- probably not applicable.

• arm/Self-hosting -- possibly applicable.

• arm/U-Boot-ports -- not applicable in general, but a similar page could be created.

• arm/crossbuild -- all but the very first section should apply.

• arm/netboot -- most of this is applicable.