How to Run Zephyr on a LiteX SoC in the Tang Nano 20K

In this guide, you will learn how to install and run Zephyr OS on a LiteX SoC with a VexRiscv CPU on the Tang Nano 20K FPGA. This process will allow you to experiment with advanced embedded systems and leverage the capabilities of open hardware.

📦 Requirements

  • Tang Nano 20K
  • LiteX development environment (Python, dependencies, toolchains)
  • Zephyr OS and toolchain (west, cmake, ninja, etc.)
  • USB cable for programming and serial connection
  • Basic knowledge of FPGA and embedded systems

🛠️ Steps

1️⃣ Prepare Zephyr

Follow the official documentation to install Zephyr and its SDK:

python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
pip install west
west init ~/zephyrproject
cd ~/zephyrproject
west update
west zephyr-export
west packages pip --install
cd zephyr
west sdk install

2️⃣ Clone the VexRiscv support repository

git clone https://github.com/DitsoLabs/zephyr-vexriscv.git

The next steps need to be run from inside the Zephyr-VexRisc folder.

3️⃣ Install the board in Zephyr

From the cloned folder:

python3 install_board.py -z ~/zephyrproject

This will add the necessary support for Tang Nano 20K and VexRiscv.

4️⃣ Generate the SoC and bitstream

python3 bitstream_generator.py --build --load

This command will:

  1. Generate the LiteX SoC.
  2. Compile the bitstream.
  3. Load it onto the FPGA.

5️⃣ Build a Zephyr application

Example with hello_world:

cd ~/zephyrproject/zephyr
west build -p always -b tang_nano_20k samples/hello_world/

6️⃣ Load the firmware into the SoC

litex_term /dev/ttyUSB0 --kernel build/zephyr/zephyr.bin

Note: Adjust /dev/ttyUSB0 according to your system.

7️⃣ Run from the LiteX BIOS

In the LiteX BIOS:

serialboot

If the load is successful, you should see the Zephyr output in the console.