Skip to content


Repository files navigation


RISC-V Architecture Layer for OpenEmbedded/Yocto

license Build Status


This is the general hardware-specific BSP overlay for the RISC-V based devices.

More information can be found at: (Official Site)

The core BSP part of meta-riscv should work with different OpenEmbedded/Yocto distributions and layer stacks, such as:

  • Distro-less (only with OE-Core).
  • Yoe Distro.
  • Yocto/Poky.


This layer depends on:

Quick Start

Note: You only need this if you do not have an existing Yocto Project build environment.

Make sure to install the repo command by Google first.

Create workspace

mkdir riscv-yocto && cd riscv-yocto
repo init -u  -b master -m tools/manifests/riscv-yocto.xml
repo sync
repo start work --all

Update existing workspace

In order to bring all the layers up to date with upstream

cd riscv-yocto
repo sync
repo rebase

Setup Build Environment

. ./meta-riscv/

Kas Support

Kas build is supported, you can run the following commands:

git clone -b kirkstone
cd meta-riscv
  • For basic qemuriscv64 build run:
kas build kas/base-riscv.yml

base-riscv.yml will build core-image-minimal, you can then boot it with:

runqemu core-image-minimal nographic

NOTE nographic is needed for this image, because it has no graphical support for graphical Qemu run.

  • For nezha build:
kas build kas/nezha.yml
  • For beaglev build:
kas build kas/beaglev.yml
  • For more machines check kas folder.

Custom Project

If you have your own layer that depends on this layer, you can create a kas yml file in your layer with the following content (nezha build as an example):

  version: 8
    - repo: meta-riscv
      file: kas/nezha.yml

    path: layers
    refspec: kirkstone

target: custom-image # Or nezha default image: riscv-nezha-image

For more details on nezha, beaglev and other boards steps check doc folder.

Available Machines

The different machines you can build for are:

  • freedom-u540: The SiFive HiFive Unleashed board
  • beaglev-starlight-jh7100: BeagleV - Based on Starlight JH7100 SOC
  • mangopi-mq-pro: MangoPi MQ Pro - Based on Allwinner D1 SOC

Note that this layer also provides improvements and features for the upstream qemuriscv32 and qemuriscv64 machines.

Additional beagleV notes on bringup are here

Build Images

A console-only image for the 64-bit QEMU machine

MACHINE=qemuriscv64 bitbake core-image-full-cmdline
MACHINE=beaglev-starlight-jh7100 bitbake core-image-full-cmdline

To build an image to run on the HiFive Unleashed using Wayland run the following

MACHINE=freedom-u540 bitbake core-image-weston

To build an image to run on the BeagleV using Wayland run the following

MACHINE=beaglev-starlight-jh7100 bitbake core-image-weston

To build an image to run on the MangoPi MQ Pro (console only has been tested so far) run the following:

MACHINE=mangopi-mq-pro bitbake core-image-base

To build a full GUI equipped image running Plasma Mobile see the in-tree documentation here.

Running in QEMU

Run the 64-bit machine in QEMU using the following command:

MACHINE=qemuriscv64 runqemu nographic

Run the 32-bit machine in QEMU using the following command:

MACHINE=qemuriscv32 runqemu nographic

Running on hardware

Setting up a TFTP server

If you would like to boot the images from a TFTP server (optional) you should set your TFTP server address in your local.conf with the following line. Change to the IP address of your TFTP server and copy the uImage to the server.


Running with the Microsemi Expansion board

To use the Microsemi expansion board with your HiFive Unleased add the following line to your local.conf. This tells the Unleashed to use a device tree with the PCIe device described:

RISCV_SBI_FDT:freedom-u540 = "hifive-unleashed-a00-microsemi.dtb"

Sparse Image Creation

The output of the build can also be written to an SD card using bmaptool, the steps to do this are below:

$ MACHINE=freedom-u540 wic create freedom-u540-opensbi -e core-image-minimal
$ bmaptool create ./ > image.bmap
$ sudo bmaptool copy --bmap image.bmap ./ /dev/sdX

dding wic.gz

The output of a freedom-u540, beaglev-starlight-jh7100 or mangopi-mq-pro build will be a <image>.wic.gz file. You can write this file to an sd card using:

$ zcat <image>-<machine>.wic.gz | sudo dd of=/dev/sdX bs=4M iflag=fullblock oflag=direct conv=fsync status=progress

Using bmaptoop to write the image

Instead of dding wic.gz image bmaptool (available in most Linux distributions and/or pip) can be used for more reliable and faster flashing. You can write this file to an sd card using:

$ sudo bmaptool copy <image>-<machine>.wic.gz /dev/sdX


  • Khem Raj <raj dot khem at>