Skip to content

LiteX Zephyr tutorial

Jump to bottom
Robert Winkler edited this page Apr 2, 2020 · 4 revisions

LiteX - Zephyr tutorial

This tutorial shows how to generate basic CPU using LiteX SoC Builder and flush it to the board. The whole process is demonstrated using VexRiscv CPUVexRiscv CPU and Digilent Arty Board.

This tutorial assumes that you are using Debian distribution.

Table of Contents

  1. Prerequisites
    1. Vivado
    2. riscv toolchain
    3. migen library
    4. xc3sprog
    5. TFTP server
    6. picocom
  2. Prepare Basic Bitstream
    1. Compile the Bitstream
    2. Program the Chip
  3. Prepare Zephyr OS Application
    1. Follow the Zephyr Tutorial
  4. Shortcuts
    1. Litex Buldenv
    2. Other

Prerequisites

In order to compile LiteX you will need:

  • Vivado
  • riscv toolchain
  • migen library

Vivado

In order to download the Xilinx Vivado Design Suite, you will have to:

  1. Create a personal account on the Xilinx website

  2. Download the newest version of the tool dedicated to Linux. It is called Xilinx Unified Installer 2019.2:Linux Self Extracting Web Installer.

    The 2019.2 Version can be downloaded using this link

  3. Run the installer script and install Vivado in the default directory (requires root privileges)

chmod u+rx Xilinx_Unified_2019.2_1106_2127_Lin64.bin
sudo ./Xilinx_Unified_2019.2_1106_2127_Lin64.bin
  1. Follow the instructions from the installer.
  • In Select Product to Install section chose Vivado.
  • In Select Edition to Install section chose Vivado HL WebPACK.
  1. Check if Vivado is installed properly. Command bellow should display some informations about the binary:
stat /tools/Xilinx/Vivado/2019.2/bin/vivado
  1. Add vivado to your system path, by adding the following lines to your ~/.bashrc file:
export PATH="$PATH:/tools/Xilinx/Vivado/2019.2/bin/vivado"
  1. Source the ~/.bashrc:
source ~/.bashrc

riscv toolchain

  1. Install prerequisites:
sudo apt install autoconf automake autotools-dev curl libmpc-dev \
                 libmpfr-dev libgmp-dev gawk build-essential bison flex \
                 texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev
  1. Download the toolchain:
git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
  1. Compile and install the toolchain
cd riscv-gnu-toolchain
./configure --prefix=/opt/riscv
make -j$(nproc)
sudo make install

migen library

Install the migen library using:

pip3 install migen

Install required LiteX cores libraries:

pip3 install git+https://github.com/enjoy-digital/litedram.git 
pip3 install git+https://github.com/enjoy-digital/liteeth.git

xc3sprog

  1. Install prerequisites:
sudo apt install -y libusb-dev libftdi-dev

Install libftd2xx (version 1.4.8) from the website:

  1. Download the xc3sprog program from this repository:
git clone --recursive https://github.com/antmicro/xc3sprog
  1. Build and install the program
cd xc3sprog
mkdir build
cd build
cmake ..
make -j$(nproc)
sudo make install

TFTP server

To install the TFTP server follow the instructions on this website

picocom

  1. Install picocom using:
sudo apt install picocom
  1. Add $USER to dialout group
sudo usermod -a -G dialout $USER
  1. Reboot your computer

Prepare basic bitstream

Compile the bitstream

  1. Clone the LiteX repository:
git clone --recursive https://github.com/enjoy-digital/litex
  1. Run the script which will configure the VexRiscv CPU with ethernet for the Arty Board:
cd litex/litex/boards/targets
./arty.py --with-ethernet

Then you will see the log from the Vivado Design Suite. The output files will be saved to soc_ethernetsoc_arty directory.

It has the following structure:

cd soc_ethernetsoc_arty
tree -L -d2

.
├── gateware
│   ├── <...>
│   ├── top.bit (file with the final bitstream)
│   ├── top.v (file with the final verilog)
│   ├── <...>
└── software
    ├── bios
    ├── include
    ├── libbase
    ├── libcompiler_rt
    └── libnet

Program the Chip

  1. Plug the board to your computer using USB cable

  2. Find the /tty/USBx device associated with UART on your board:

ls /dev/ | grep USB

ttyUSB0
ttyUSB1
  1. Open the /tty/USBx device associated with UART. (For one of them associated with JTAG it will be impossible)
picocom -b 115200 /dev/ttyUSBx --imap lfcrlf

Replace x with the correct number

  1. Program the FPGA chip with the final bitstream
cd gateware
xc3sprog -c nexys4 top.bit

You should observe the BIOS messages in the terminal:

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|
   Build your hardware, easily!
 (c) Copyright 2012-2020 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs
 BIOS built on Mar 11 2020 12:56:58
 BIOS CRC passed (d2c6e2e8)
 Migen git sha1: 3f9809b
 LiteX git sha1: ba2f31d4
--=============== SoC ==================--
CPU:       VexRiscv @ 100MHz
ROM:       32KB
SRAM:      4KB
L2:        8KB
MAIN-RAM:  262144KB
--========== Initialization ============--
Ethernet init...
Initializing SDRAM...
SDRAM now under software control
Read leveling:
m0, b0: |11111111111100000000000000000000| delays: 06+-06
m0, b1: |00000000000000111111111111110000| delays: 21+-07
m0, b2: |00000000000000000000000000000011| delays: 31+-01
m0, b3: |00000000000000000000000000000000| delays: -
m0, b4: |00000000000000000000000000000000| delays: -
m0, b5: |00000000000000000000000000000000| delays: -
m0, b6: |00000000000000000000000000000000| delays: -
m0, b7: |00000000000000000000000000000000| delays: -
best: m0, b1 delays: 21+-07
m1, b0: |11111111111100000000000000000000| delays: 06+-06
m1, b1: |00000000000000111111111111100000| delays: 20+-06
m1, b2: |00000000000000000000000000000011| delays: 31+-01
m1, b3: |00000000000000000000000000000000| delays: -
m1, b4: |00000000000000000000000000000000| delays: -
m1, b5: |00000000000000000000000000000000| delays: -
m1, b6: |00000000000000000000000000000000| delays: -
m1, b7: |00000000000000000000000000000000| delays: -
best: m1, b1 delays: 20+-06
SDRAM now under hardware control
Memtest OK
Memspeed Writes: 229Mbps Reads: 245Mbps
...

Zephyr OS Application

Zephyr tutorial

Follow the Zephyr Getting-Started tutorial to prepare all the tools needed by the Zephyr OS.

Compiling Examples

Zephyr OS contains some basic examples. In order to compile the hello_world example for Vexriscv CPU on the Arty Board, you will need to use the following commands:

source zephyr-env.sh
cd samples/hello_world
mkdir build
cd build
cmake -DBOARD=litex_vexriscv ..
make -j$(nproc)

Note that you have to set the ZEPHYR_TOOLCHAIN_VARIANT and ZEPHYR_SDK_INSTALL_DIR variables, according to the Zephyr Getting-Started tutorial

Booting the application

Serial

For booting the application from serial you can use flterm:

flterm --port /dev/ttyUSB0 --kernel <path_to_zephyr.bin> --kernel-adr 0x40000000

Ethernet (recommended)

If you configured TFTP server properly you can just rename the obtained zephyr.bin to boot.bin. And copy it to your TFPT server directory i.e. /tftpboot (if you used the tutorial from previous steps). You should also change your computer IP to 192.168.1.100 because the LiteX bootloader expects that.

sudo ifconfig <ethernetid> 192.168.1.100
mv zephyr.bin boot.bin
cp boot.bin /tftpboot/boot.bin

Litex Buldenv

LiteX Buildenv is a project which creates an advanced building environment for the LiteX ecosystem.

More informations how to run Zephyr using LiteX Buildenv can be found in the project's Wiki

Other

This repository contains a minimalistic setup for LiteX-Zephyr development.

Clone this wiki locally