Recently, I stumbled upon an excellent open-source project that allows for the quick customization of an SoC on one’s FPGA development board. so, what is LiteX?

LiteX is a Migen/MiSoC based Core/SoC builder that provides the infrastructure to easily create Cores/SoCs (with or without CPU).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
                        +---------------+
                        |FPGA toolchains|
                        +----^-----+----+
                             |     |
                          +--+-----v--+
         +-------+        |           |
         | Migen +-------->           |
         +-------+        |           |        Your design
                          |   LiteX   +---> ready to be used!
                          |           |
+----------------------+  |           |
|LiteX Cores Ecosystem +-->           |
+----------------------+  +-^-------^-+
 (Eth, SATA, DRAM, USB,     |       |
  PCIe, Video, etc...)      +       +
                           board   target
                           file    file

This article documents my feasibility study:

  • Install LiteX and required FPGA toolchain
  • Build an example SoC and load it on an FPGA dev board

Okay, let’s go!

安装 LiteX

从GitHub上拉取安装脚本（注意：需要提前安装pip3 sudo apt-get install python3-pip），安装过程会下载非常多的 LiteX 模块到单独的目录，所以建议单独新建一个文件夹执行 LiteX 安装脚本，命令如下：

1
2
3
4
5
mkdir litex && cd litex
mkdir python-litex && cd python-litex
wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
chmod +x litex_setup.py
./litex_setup.py --init --install --user --config=full

安装的过程中需要给网络施加一点魔法，至于怎么施加这里就不赘述了「すみません」，自行 Google。当安装结束后，我们可以看到最后的提示需要我们确保 ~/.local/bin is 在我们的 PATH 中。

1
2
3
[  76.646] Make sure that ~/.local/bin is in your PATH
[  76.646] export PATH=$PATH:~/.local/bin # temporary (limited to the current terminal)
[  76.646] or add the previous line into your ~/.bashrc to permanently update PATH

我们可以输入 echo $PATH 查看 ~/.local/bin 是否在我们的环境变量中，如若不在，需要添加环境变量，如下：

1
2
3
4
sudo gedit ~/.zshrc			# vim or gedit 都可，笔者更喜欢 gedit

# 在 .zshrc 末尾添加
export PATH=$PATH:/home/theo/.local/bin

接下来安装 RISC-V 工具链

1
2
pip3 install meson ninja
sudo ./litex_setup.py --gcc=riscv

到此，LiteX 就已经安装完成了。

生成 SOC

在 LiteX 中， SOC 的 Verilog HDL 代码和 ROM 的生成都在 litex-boards 目录下。在上一步安装 LiteX 环境时会自动下载，该目录结构如下：

1
2
3
4
5
.
├── __init__.py
├── platforms  # 板卡相关的IO、时钟、约束，以及生成板卡bit流时的一些tcl脚本
├── prog				
└── targets    # 创建SOC所需的代码，可在该目录下，配置SOC的组件（以太网，DRAM，GPIO等）

LiteX 目前支持的 FPGA 有 Xilinx (AMD), Altera (Intel), Lattice, Anlogic 各种平台，如果自己的开发板不被 Litex 默认支持，也可以自己添加platform (FPGA 型号、板载资源) 和 target (期望生成的 SoC)。这里我使用的是正点原子的达芬奇开发板（XC7A35TFGG484I），貌似没有被官方支持，but 在官方支持的板子中有 xc7a35t 芯片的 board，身为”资深”的 ctrl cv 工程师表示我们直接拿来改改就可以用了（bushi）。我们在项目根目录下新建一个 soc 文件夹存放我们的 platform 和 target 定义。

LiteX 自定义开发板

对于已经被官方支持的开发板，它们的定义会存储在 litex_boards/platforms 和 litex_boards/targets 目录下的相应的 Python 文件中。对于新的开发板我们可以在 litex_boards/platforms 目录下新增 platforms 文件，用来定义你的开发板。文件名应该采用 <vendor>_<board>.py 的格式，其中 <vendor> 是开发板制造商的名称，<board> 是开发板型号的名称，在这个新的 Python 文件中，需要定义一个继承自 litex_boards.platforms.Platform 的类，这个类包含开发板的一些基本信息，例如时钟频率、I/O 管脚、Flash 存储器等，也可以在这个类中定义一些额外的方法，用于初始化和配置硬件。在 litex_boards/targets 目录下新增 targets 文件，以包含针对开发板的应用程序。后将我们新增的文件添加到 Makefile 中。

这里笔者使用的是正点原子的达芬奇开发板，该系列采用的是 Xilinx Artix7 系列 XC7A35T-FGG484-2作为主控芯片，其余参数请自行查阅官方Wiki。

编译位流

在任意目录下执行以下语句：

1
python3 <PATH>/targets/<vendor>_<board>.py --build

会在当前目录下生成一个 build 目录

1
2
3
4
5
.
└── build
    └── openedv_davinci
        ├── gateware		
        └── software

下载位流

上一步我们已经成功构建出了我们的 hardware Soc，接下来就是将位流下载至开发板。进入 build/<board>/gateware 目录，在该目录下找到 <board>.bit 将其下载至开发板。这里我是在虚拟机进行开发的，而硬件板卡连接的是本地电脑，所以我们要在本地电脑打开 vivado_path/bin/hw_server.bat 软件，如下图所示：

服务器端打开 open hardware manager -> open target -> open new target

下载成功后可以看到流水灯闪烁同时串口有数据输出。

Okay，测试通过，接下来就是在 Litex SoC 上运行Linux。Enjoy Digital 团队创建了一个名为 Linux-on-Litex 的项目，该项目使用 Litex 生成能够运行 Linux 的 SoC，只要你的板子有 32MB RAM 和一个串口以及足够的逻辑资源就可以运行这个项目。非常感谢 Enjoy Digital！

Linux on LiteX-VexRiscv

TODO