Lab 01: Getting Started with LiteX

Objectives

  1. Build a minimal System on Chip (SoC) with LiteX

  2. Discover how LiteX work

Prerequisites

Firstly we will configure the environnement for the lab.

LiteX installation and setup has been done in a Python virtual environment, so activate it:

source venv/pyenv-litex/bin/activate

To generate the software you need a software toolchain. For LiteX to use the toolchain you have to configure it:

export PATH="INSTALL-PATH/riscv64-unknown-elf-gcc-8.3.0-2019.08.0-x86_64-linux-ubuntu14/bin:$PATH"

To generate the gateware you need a FPGA toolchain. For LiteX to use the toolchain you have to configure it:

export LITEX_ENV_VIVADO="INSTALL-PATH/Xilinx/Vivado/2019.1"

The FPGA board used in this lab is a Digilent Basys3 board:

Basys3 board

The FPGA is a Artix-7 FPGA.

All the materials for the lab are available in the following folder:

cd hands-on/lab01

Build your first SoC for Verilator

A makefile is available to help you execute the right commands. To look at behind the scene what happened look at inside the Makefile.

To generate the verilated model of the SoC try:

make soc_sim_gateware

To generate the software, here the demo example provided by LiteX, try:

make soc_sim_demo

Finally to test your SoC with the associated software you can try:

make soc_sim_demo_run

And you should have something like this:

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|
   Build your hardware, easily!

 (c) Copyright 2012-2022 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs

 BIOS built on Dec  5 2022 23:35:03
 BIOS CRC passed (7c5b41e8)

 LiteX git sha1: a4cc859d

--=============== SoC ==================--
CPU:            VexRiscv @ 1MHz
BUS:            WISHBONE 32-bit @ 4GiB
CSR:            32-bit data
ROM:            128KiB
SRAM:           8KiB
MAIN-RAM:       64KiB

--========== Initialization ============--

--============== Boot ==================--
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
Executing booted program at 0x40000000

--============= Liftoff! ===============--

LiteX minimal demo app built Dec  5 2022 23:34:50

Available commands:
help               - Show this command
reboot             - Reboot CPU
donut              - Spinning Donut demo
helloc             - Hello C
litex-demo-app> helloc
Hello C demo...
C: Hello, world!
litex-demo-app>

Build your first SoC for FPGA

If you do not have Vivado installed in your system we already a bitstream for you. It is available in the demo-digilent-basys folder inside the virtual machine. If you have Vivado installed in your system you can try:

make soc_basys3_gateware

You can generate the doc of the SoC

make soc_basys3_doc

And then open it

open build/digilent_basys3/doc/_build/html/index.html

You can load the generated bitstream to the board

make soc_basys3_load_bitstream

Connect a serial terminal to the board

litex_term /dev/ttyUSB1

Then press the BTNC button to reset the board. You should have something like this

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|
   Build your hardware, easily!

 (c) Copyright 2012-2022 Enjoy-Digital
 (c) Copyright 2007-2015 M-Labs

 BIOS built on Dec  5 2022 22:46:08
 BIOS CRC passed (729066ee)

 LiteX git sha1: a4cc859d

--=============== SoC ==================--
CPU:            VexRiscv @ 75MHz
BUS:            WISHBONE 32-bit @ 4GiB
CSR:            32-bit data
ROM:            128KiB
SRAM:           8KiB
MAIN-RAM:       128KiB

--========== Initialization ============--
Memtest at 0x40000000 (128.0KiB)...
  Write: 0x40000000-0x40020000 128.0KiB
   Read: 0x40000000-0x40020000 128.0KiB
Memtest OK
Memspeed at 0x40000000 (Sequential, 128.0KiB)...
  Write speed: 123.9MiB/s
   Read speed: 63.9MiB/s

--============== Boot ==================--
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
No boot medium found

--============= Console ================--

litex>

Load an application from the LiteX BIOS

Generate the demo example for the gateware

make soc_basys3_demo

Load the application over the serial bus

make soc_basys3_load_demo

Then press the BTNC button to reset the board and observe.

Take aways

  • A SoC functional in few minutes!

  • A lots of supported boards!

  • Several FPGA toolchains supported!

  • Open source community https://github.com/enjoy-digital/litex

  • High level description of your Gateware.