This page contains information about how to configure, build, and run Zephyr on the MicroBlaze V™ processor (RISC-V). Instructions for setting up the Zephyr environment, building applications, and running tests are given.

Introduction

2024.2 is the first release where Zephyr support is targeted for the MicroBlaze V processor.

The AMD Zephyr repo is available at: GitHub - Xilinx/zephyr-amd

Supported Peripherals

Please consult the Peripheral Support page for more information.

Other Limitations

FAST interrupts are not supported for this release. However, Vivado™ default example designs come with fast interrupts enabled.

Please refer to the appendix for information on disabling FAST interrupts in a hardware design.

The current Zephyr flow is under development and being upstreamed. This may cause the flow the change in subsequent releases.

Zephyr RTOS

The Zephyr RTOS consists of the Zephyr kernel, an architecture specific porting layer, device drivers, various subsystems, the Zephyr test framework and so on.

Any new hardware is ported to Zephyr based on the hierarchical abstractions (boards, SoC etc.) Please refer Porting — Zephyr Project Documentation. The MicroBlaze V soft core has been ported to Zephyr using the mbv32 SoC and mbv32 board. Default configurations for the mbv32 board and SoC are set up for a KCU105 example design from Vivado. The only change done on the example hardware design is disabling FAST interrupts as they are not supported in Zephyr.

A Zephyr distribution comes with west, a command line based build environment which AMD will use heavily.

Note: Below you can find the XSA and bitstream for the KCU105 example hardware design with FAST interrupts disabled.

Using AMD Zephyr with MicroBlaze V

This section describes how to set up a Zephyr environment and how to build test applications for a hardware design.

Users must have a MB-V soft processor based hardware design. Users can choose to create their own MB-V soft processor based hardware design or leverage Vivado examples. AMD Vivado offers MB-V preset design examples for various evaluation boards. Each embedded hardware design offers a MicroBlaze V subsystem that can be targeted for the real-time and microcontroller configurations. As of now, Zephyr is supported only for the real-time configuration.

How to Set up the Zephyr Environment

Follow the steps mentioned in the Zephyr 3.7.0 Getting Started Guide up to and including installing the Zephyr SDK
Next complete these steps to replace the upstream Zephyr repo with the AMD clone. As we upstream our work the importance of this step will diminish and may be removed.

cd <local path>/zephyrproject/
mv zephyr zephyr.upstream
git clone https://github.com/Xilinx/zephyr-amd.git  -b xlnx_rel_v2024.2 zephyr
mv zephyr-amd zephyr
west update
west lopper-install

The Zephyr environment is ready to build applications and/or kernel tests

How to Build Kernel Tests for the Default KCU105 Example Hardware Design

The devicetree (board/amd/mbv32/mbv32.dts) and Kconfig for mbv32 are by default configured for the KCU105 real time example Hardware design from Vivado. Use the following command to build the sample application test:

cd zephyr
west build -p -b mbv32 tests/misc/test_build/

Note: The executable generated after the build command contains the application as well as the kernel.

The expected output for the sample application is given below:

*** Booting Zephyr OS build 43e80ea32443 ***
threadA: Hello World from riscv!
threadB: Hello World from riscv!
threadA: Hello World from riscv!
threadB: Hello World from riscv!

How to Build Kernel Tests for a Targeted Customized Hardware Design

Because each FPGA based hardware design can have different hardware configurations, users need to update the devicetree (boards/amd/mbv32/mbv32.dts) based on the targeted hardware design. The base address and interrupt IDs might be different from what we have configured in mbv32.dts. Users need to either update mbv32.dts and kconfigs (soc/xlnx/mbv32/Kconfig, soc/xlnx/kconfig.defconfig) manually based on the hardware design or they can use west lopper-command to set it up using lopper. Subsequent sections provide steps for setting up mbv32 board and DTS for targeted hardwaredesigns using west lopper-command.

Create Hardware Design and Generate XSA

Users must create a hardware design based on the soft MB-V core or leverage example designs provided by Vivado. Build the the hardware design and export the XSA.

Generate SDT Using XSA

Refer to the to the AMD Technical Information Portal for the steps to generate a System Device Tree (SDT) using a hardware design XSA. The SDT is mandatory to generate a Zephyr devicetree and Kconfig for targeted hardware designs using the west lopper-command.

Note: Use the 2024.2 version of xsct (you may need to use a different path to Vivado to point to your local installation). Please replace design_1_wrapper.xsa with the name of the file exported above.

. /tools/Xilinx/Vivado/2024.2/settings64.sh
xsct -eval "sdtgen set_dt_param -dir design_1_wrapper -xsa design_1_wrapper.xsa ; sdtgen generate_sdt"

Invoke lopper-command to set up the Zephyr Repository for Targeted Hardware Design

To make life easier, lopper has been integrated with the west build system. Using west lopper-command, users can configure the targeted Zephyr repository for a specific hardware design.

The input to the lopper-command is the system devicetree, the processor instance name, and the targeted Zephyr repository path. The steps to invoke lopper-command are shown below. Please change the path to the system-top.dts file to match the directory used for xsct above and the processor name to match the name of the processor in your design you are targetting for Zephyr.

LOPPER_DTC_FLAGS="-b 0 -@" west lopper-command -p microblaze_riscv_0 -s design_1_wrapper/system-top.dts -w <local path>/zephyrproject/zephyr

Once lopper-command is invoked, the Zephyr environment is ready to build kernel tests/apps for the targeted hardware design. Build a sample test using the commands below:

cd zephyr
west build -p -b mbv32 tests/misc/test_build/

# The executable would be generated in following location
<zephyr repository path>/build/zephyr/zephyr.elf

The expected output for sample application is shown below:

*** Booting Zephyr OS build 43e80ea32443 ***
threadA: Hello World from riscv!
threadB: Hello World from riscv!
threadA: Hello World from riscv!
threadB: Hello World from riscv!

Zephyr Test Runner (Twister):

Zephyr provides some built-in tools for testing. Twister is one of the CLI based tool used to execute/build the tests. It scans for sets of test applications in the Zephyr repository applicable for the targeted platform and builds/executes those tests. It also generates a test report for reference. More details can be found at Test Runner (Twister) — Zephyr Project Documentation.

Running Twister on MicroBlaze V

Use the following commands to run twister for an MB-V based hardware design:

cd <zephyr env path>/zephyrproject/zephyr

# To Run a specific test:
west flash --runner xsdb --elf-file mbv32/zephyr/zephyr.elf --bitstream <path>/system.bit
 
# To Run all the tests:
./scripts/twister -p mbv32 --west-runner xsdb --device-testing --device-serial /dev/ttyUSB0 --west-flash="--bitstream=<path>/system.bit"

Note: if you want to run Twister on a customized hardware design you must first configure the Zephyr repository for that design.

Results for Default MB-V 32 Board/SoC Configuration

We observed a small number of failures, and as per our initial analysis these failures are non-critical. Users can also expect some non-critical failures for customized hardware designs.

Appendix

How to Disable FAST Interrupts in Vivado Projects

Example projects offered by Vivado have FAST interrupts enabled by default. The AXI INTC IP looks like the following:

Disable FAST interrupts by un-marking the "Enable Fast interrupt logic" button and re-build the project.

Xilinx Wiki

Zephyr on MicroBlaze V

Table of Contents