Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== RISC-V ====== ====== Introduction ====== %%FreeBSD%%/RISC-V is a architecture port for %%FreeBSD%% to run on the [[http://riscv.org|RISC-V Instruction-Set Architecture (ISA)]], able to boot to multi-user mode on the QEMU emulator, Spike simulator and [[#support|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 [[https://www.cl.cam.ac.uk/research/security/ctsrd/|DARPA CTSRD Project]] at the [[https://www.cl.cam.ac.uk|University of Cambridge Computer Laboratory]] led by RuslanBukin. The %%FreeBSD%% Foundation posted a [[http://freebsdfoundation.blogspot.co.uk/2016/02/initial-freebsd-risc-v-architecture.html|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 [[https://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/archs.html|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 ([[https://cgit.freebsd.org/src/commit/?id=02a371289a3766de9d06a7791357921aba4606a9|02a371289a37]]) and partially supports (userspace only) the 48-bit ([[https://cgit.freebsd.org/src/commit/?id=31218f3209acf0f8f0dc54e436342c8fa604d279|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 ==== ^ Target ^ Type ^ Support ^ Tested Features ^ Availability ^ Notes ^ | [[riscv/Spike|Spike]] | emulator | fully supported | SMP | | | | [[riscv/QEMU|QEMU]] | emulator | fully supported | SMP, virtio-block, virtio-net | | | | [[riscv/BeagleV|BeagleV]] | hardware | in review | SMP, mmcsd | [[https://beaglev.org/blog/2021-07-30-the-future-of-beaglev-community|abandoned]] (a few %%FreeBSD%% developers have the prototype boards) | Future products may use the same or a similar %%SoC%% | | %%HiFive%% Unleashed (%%SiFive%% FU540) | hardware | fully supported | SMP, mmcsd, ethernet | [[https://www.sifive.com/boards/hifive-unleashed|discontinued]]; "basically impossible to obtain" -- KristofProvost | | | [[riscv/HiFiveUnmatched|HiFive Unmatched]] ([[https://sifive.cdn.prismic.io/sifive/28560457-c5a4-4f88-866c-8098d02afea1_FU740-C000-Manual-v1p0.pdf|SiFive FU740)]] | hardware | fully* supported in 14-CURRENT | SMP, PCIe, NVMe, USB, ethernet | [[https://www.mouser.com/ProductDetail/SiFive/HF105-000?qs=zW32dvEIR3vHEV%2FPYYkdMA%3D%3D|Order on Mouser]]; [[https://www.crowdsupply.com/sifive/hifive-unmatched|Order on Crowd Supply]] | *: except for SD card (see board-specific page) | ==== Announced Platforms ==== These are boards that we believe will be supported at some point. ^ Target ^ Type ^ Support ^ Tested Features ^ Availability ^ Notes ^ | %%PolarFire%% %%SoC%% Icicle Kit | hardware | status unknown | | [[https://www.crowdsupply.com/microchip/polarfire-soc-icicle-kit|Purchase on Crowd Supply]] | | | [[https://wiki.sipeed.com/hardware/en/lichee/RV/RV.html|Sipeed Lichee RV & Nezha RISC-V Linux SBC]] | hardware | in progress | | [[https://wiki.sipeed.com/store.html|Sipeed Online Store]] [[https://www.aliexpress.com/item/1005002668194142.html?awc=10748_1623756655_ae0268b081b5f87faa809d226c8342c9&af=78888&dp=10748_1623756655_ae0268b081b5f87faa809d226c8342c9&cn=10748&Afref=Skimlinks|Purchase on AliExpress]] | [[https://reviews.freebsd.org/people/revisions/13728/|Reviews]] [[https://github.com/jcassette/freebsd-src/tree/d1/mmc|GitHub]] [[https://lists.freebsd.org/archives/freebsd-riscv/2022-February/000140.html|FreeBSD List archive]] | ===== Unsupported Platforms ===== 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%% [[https://lore.kernel.org/all/CA++6G0Do001Bo+kxhUNz5T937TYU-K5Y43MH+X=Q2TgFCaxcfQ@mail.gmail.com/|violating the RISC-V Sv39 specification]], which would likely require intrusive patches to work around. 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: * RuslanBukin (br@) * MitchellHorne (mhorne@) * JohnBaldwin (jhb@) * LiWenHsu (lwhsu@) * KristofProvost (kp@) * JessicaClarke (jrtc27@) ===== IRC channel ===== See [[IRC/Channels]]. ===== Mailing List ===== [[https://lists.freebsd.org/mailman/listinfo/freebsd-riscv|freebsd-riscv]] ====== Toolchain ====== After [[https://svnweb.freebsd.org/changeset/base/r356499|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 [[https://cgit.freebsd.org/src/log/|HEAD]]. For the development history, see [[riscv/history]]. HEAD build status: [[https://ci.freebsd.org/job/FreeBSD-main-riscv64-build/|[[https://ci.freebsd.org/job/FreeBSD-main-riscv64-build/lastCompletedBuild/badge/icon ]] 13-STABLE build status: [[https://ci.freebsd.org/job/FreeBSD-stable-13-riscv64-build/|[[https://ci.freebsd.org/job/FreeBSD-stable-13-riscv64-build/lastCompletedBuild/badge/icon ]] ====== 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 ==== <code> sudo pkg install opensbi u-boot-qemu-riscv64 qemu </code> //Note: emulators/qemu-devel also works.// ==== Download FreeBSD/RISC-V virtual machine image ==== <code> 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 </code> Optionally, extend the image using ''%%truncate(1)%%''. The root filesystem will grow to fill the free space upon first boot. <code> truncate -s 10G FreeBSD-14.0-CURRENT-riscv-riscv64.raw </code> ==== Boot image in QEMU ==== Spawn a VM with 2 CPUs and 2GB of memory: <code> 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 </code> 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. 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, and the system toolchain can also be used on any %%FreeBSD%% system with base LLVM version 9 or greater, but if you wish to use an external GCC toolchain instead then see the documentation towards the bottom of this page. ===== Cross-compile FreeBSD ===== ==== Build FreeBSD world ==== No different than other architectures: <code> make TARGET_ARCH=riscv64 buildworld </code> === Using GCC package === <code> make CROSS_TOOLCHAIN=riscv64-gcc9 TARGET_ARCH=riscv64 buildworld </code> === Using a toolchain built by hand === <code> 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 </code> ==== Build FreeBSD kernel ==== <code> make TARGET_ARCH=riscv64 buildkernel </code> For QEMU add ''%%KERNCONF=QEMU%%'' in ''%%make%%'' parameters. As above, set the appropriate arguments if using GCC. ===== 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 [[http://www.freshports.org/sysutils/opensbi|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 [[https://www.freshports.org/devel/riscv64-none-elf-gcc|riscv64-none-elf-gcc]] and [[https://www.freshports.org/devel/binutils/|riscv64-none-elf-binutils]] (a FLAVOR of devel/binutils) packages. <code> git clone https://github.com/riscv/opensbi.git cd opensbi gmake CROSS_COMPILE=riscv64-none-elf- PLATFORM=generic </code> 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 [[https://github.com/riscv/opensbi/tree/master/docs/platform|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 [[riscv#OpenSBI|OpenSBI]], but it is still maintained and may be useful for bringup on platforms not yet supported by %%OpenSBI%%. To build BBL: <code> 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 </code> This will generate the ''%%bbl%%'' firmware binary in the current directory. ===== Installation ===== ==== Install FreeBSD world and kernel ==== <code> 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 </code> ==== Build a complete rootfs image to run in QEMU ==== <code> 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 </code> 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 [[http://www.freshports.org/emulators/qemu-devel|emulators/qemu-devel]]. ==== Run QEMU ==== Load tap kernel module if not loaded: <code> sudo kldload if_tuntap </code> Configure the network with tap(4): <code> ifconfig tap0 create up ifconfig bridge0 create up ifconfig bridge0 addm em0 addm tap0 # em0 might depends of your ethernet devices </code> Run QEMU, specifying %%FreeBSD%% with -kernel and SBI firmware with -bios <code> 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 </code> If you get mountroot prompt, then indicate to the kernel the location of rootfs: <code> mountroot> ufs:/dev/vtbd0 </code> This parameter can also be passed into the ''%%qemu-system-riscv64%%'' string, specifying the device and partition such as "vtbd0" or "vtbd0p3": <code> -append "vfs.root.mountfrom=ufs:/dev/vtbd0" </code> ==== 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: <code> ./fesvr-zynq /mnt/boot/bbl </code> ====== 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 [[https://bugs.freebsd.org/bugzilla/buglist.cgi?bug_status=__open__&short_desc=risc%5C-%3Fv&short_desc_type=regexp|here]]. ===== New/Missing Features ===== ^ Project ^ Owner ^ Status ^ Comments ^ | Fix failing tests | | Open | Check the [[https://ci.freebsd.org/job/FreeBSD-main-riscv64-test/lastCompletedBuild/testReport/|latest run]] 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 [[https://reviews.llvm.org/rG9f854c048997ee5b90cf45083b6c13132f46fed9|here]], should be present in lld 11 | | Port concurrencykit to RISC-V | mhorne | In-progress | Currently we use the generic implementation. Upstream: https://github.com/concurrencykit/ck | | UEFI | | Open | Add support for EFI runtime services. | ===== 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: [[https://reviews.freebsd.org/D21922|D21922]] | ===== Security/Stability ===== ^ Task ^ Owner ^ Status ^ Comments ^ | Syzkaller | P1ummer | In-progress | [[https://mentorship.lfx.linuxfoundation.org/project/f4314dad-5cdd-4179-a6ea-53a2fc9f55a4|LFX Project]] | | Kernel Address Sanitizer (kasan(9%%))%% | | Open | | | Kernel Memory Sanitizer (kmsan(9%%))%% | | Open | | ===== Future/Larger Projects ===== ^ Project ^ Owner ^ Status ^ Comments ^ | linuxulator | | Open | Add the MD support for %%FreeBSD%%'s Linux subsystem | | RISC-V Vector Extension Support | | Open | [[https://github.com/riscv/riscv-v-spec|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 [[https://lkml.org/lkml/2019/5/30/714|here]]. | ====== Useful Links ====== ===== Specifications ===== [[https://riscv.org/specifications/|RISC-V ISA Specifications]] [[https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/master/riscv-abi.adoc|RISC-V ABI Specification]] [[https://github.com/riscv/riscv-sbi-doc/blob/master/riscv-sbi.adoc|RISC-V Supervisor Binary Interface Specification]] [[https://github.com/riscv/riscv-platform-specs/blob/main/riscv-platform-spec.adoc|RISC-V Platform Specification]] {{riscv/tls.pdf?linkonly|ELF handling for thread-local storage}} ===== Presentations ===== [[https://www.youtube.com/watch?v=QGW3l_Bz04I|FreeBSD Fridays: Introduction to RISC-V]] {{riscv/freebsd-riscv.pdf?linkonly|FreeBSD/RISC-V workshop slides}} [[https://www.youtube.com/watch?v=eW_KHFeCg3s|video]] [[http://freebsdfoundation.blogspot.co.uk/2016/02/initial-freebsd-risc-v-architecture.html|FreeBSD Foundation blog post on the RISC-V port]] [[https://fosdem.org/2019/schedule/event/testing_freebsd_risc_v5/|FOSDEM 2019 Embedded FreeBSD on a five-core RISC-V processor using LLVM]] ===== See Also ===== * [[riscv/BeagleV|BeagleV]] * [[riscv/HiFiveUnmatched|HiFiveUnmatched]] * [[riscv/QEMU|QEMU]] * [[riscv/Spike|Spike]] * [[riscv/TestSuite|TestSuite]] * [[riscv/U-Boot-ports|U-Boot-ports]] * [[riscv/history|history]] * [[riscv/ports|ports]] ====== 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. ====== Appendices ====== ===== External GCC Toolchain Setup ===== Follow these instructions if you wish to use an external GCC toolchain rather than the in-tree LLVM toolchain or your host's LLVM toolchain. ==== Install External GCC Toolchain ==== Install the riscv64-gcc9 ([[http://www.freshports.org/devel/freebsd-gcc9|devel/freebsd-gcc9@riscv64]]) and riscv64-binutils ([[http://www.freshports.org/devel/binutils|devel/binutils@riscv64]]) packages: <code> sudo pkg install riscv64-gcc9 riscv64-binutils </code> 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 === <code> setenv PREFIX $HOME/riscv </code> === Install required packages === <code> sudo pkg install bison gmp mpfr mpc gawk gsed pkgconf texinfo </code> === Build === <code> 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 </code> riscv.txt Last modified: 2023/03/14 20:27by JessicaClarke