/
Zephyr Getting Started Guide

Zephyr Getting Started Guide

This page contains information about how to configure, build, and run Zephyr on supported processors. Instructions are provided for creating a Vivado project, setting up the Zephyr environment, building applications, and running tests.

Table of Contents

Introduction

Zephyr support is provided for processors and peripherals, with each release adding or extending support.

The AMD Zephyr repo is available at:  https://github.com/Xilinx/zephyr-amd.git

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

Supported Processors

Consult the Zephyr Processor Support page for more information.

Supported Peripherals

Consult the Zephyr - Peripheral Support page for more information.

Zephyr RTOS

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

Any new hardware is ported to Zephyr based on the hierarchical abstractions (boards, SoC, etc.). Refer to https://docs.zephyrproject.org/latest/hardware/porting/index.html.

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

Using AMD Zephyr 

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

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 it might be removed.

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

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

Creating a Vivado Project

To ensure your hardware design is compatible with the current release of the zephyr-amd repo, it must consist of a supported processor and accompanying supported peripherals. Users can choose to create their own hardware design or leverage Vivado examples. AMD Vivado offers preset design examples for various evaluation boards. Each embedded hardware design offers a subsystem that can be targeted for the real-time and microcontroller configurations. As of now, Zephyr is supported only for the real-time configuration.

Once your design has been finalized and you have exported the XSA file, you can begin integrating with Zephyr.

Generate a SDT Using XSA

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

Setting Up the Zephyr Repository for a Targeted Hardware Design

Because each FPGA based hardware design can have different hardware configurations, users need to update the devicetree (boards/amd/<board_name>/<board_name>.dts) based on the targeted hardware design. The base address and interrupt IDs might be different from what is configured in the default devicetree. Users need to either update .dts and kconfigs (soc/xlnx/<board_name>/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 the DTS for a targeted hardware design using west lopper-command.

image-20241219-172710.png

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. Change the path to the system-top.dts file to match the directory used for xsct above and processor_instance_name to match the name of the processor in your design you are targeting for Zephyr.

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

For example:

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

Once the lopper-command has been invoked, the Zephyr environment is ready to build kernel tests/apps for the targeted hardware design. Build a sample test by replacing board with your target in the commands below:

cd zephyr west build -p -b board tests/misc/test_build/ # The executable would be generated in following location <zephyr repository path>/build/zephyr/zephyr.elf

For example:

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

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

 

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 https://docs.zephyrproject.org/latest/develop/test/twister.html.

Running Twister on AMD Devices

Use the following commands to run twister for an AMD based hardware design:

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

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

Expected Results

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.