1. 为什么先装代码开发工具链再上板:litex_setup.py 是第一个动作
拿到一块开发板,不少人第一反应是打开编辑器写 Verilog,我的习惯正好相反:先把代码开发工具链装通。LiteX 这套用 Python 描述硬件的框架,统一入口就是一个叫 litex_setup.py 的脚本,它替你把 Migen、LiteX 核心仓库、RISC-V 交叉工具链、Verilator 相关依赖一件件拉下来。这一步没走通,后面写多少行 HDL 都是空转。这篇按真实操作顺序展开:取脚本、选 --config 档位、装 RISC-V GCC、补 Verilator 依赖、用 litex_sim 跑起第一个带 CPU 的仿真,最后把几个最容易卡住的坑摊开讲。适合想无板先验证 SoC 结构、或者手里有板但环境还没搭起来的开发者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链的第一层:litex_setup.py 的获取与 --config 档位
2.1 用 wget 取脚本,再补一个执行位
整个安装体系只依赖一个入口文件。材料里给出的获取方式是 wget 直接从仓库的 master 分支取这个脚本,取下来之后必须给它执行权限,否则 ./litex_setup.py 会被系统当成普通文本拒绝执行。
bash复制# 从 LiteX 仓库的 master 分支取安装脚本
wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
# 赋予执行权限,之后才能用 ./ 直接运行
chmod +x litex_setup.py
这两行的含义要拆开看。第一行取的是 master 分支的最新脚本,不是某个固定发行版:好处是脚本的仓库清单永远和上游布局对得上,坏处是脚本自身不锁版本,隔几个月再跑,它拉取的内容可能已经变了。第二行 chmod +x 加的是执行位,加完之后 ./litex_setup.py 和 python3 litex_setup.py 两种跑法效果一致,区别只在报错路径——用 ./ 跑,报错堆栈里出现的是脚本自身的调用链,更适合判断是环境问题还是脚本参数问题。
这里有个平台差异必须先处理。macOS 出厂不带 wget,直接执行第一行会得到 wget: command not found。材料给的做法是先补工具:
bash复制# macOS 需要先装 wget
brew install wget
如果只是临时用一次,用系统自带的 curl -O 取同一个地址也能拿到脚本,取舍在于你后面会不会反复重装:反复装的话,把 wget 补上更省事,因为脚本内部后续的仓库拉取动作和 wget 生态更贴。
2.2 --init 与 --install 的分工,以及 --user 的副作用
脚本拿到手,第一次安装通常是这条命令:
bash复制# 初始化仓库 + 安装 Python 包 + 限定用户目录 + 选定安装档位
./litex_setup.py --init --install --user --config=standard
四个参数各管一件事,顺序不能随手打乱。--init 负责把 LiteX 相关的仓库拉到本地约定目录;--install 负责把这些已经落到本地的仓库以 Python 包的形式装进当前解释器环境。先 init 后 install 是硬约束,因为 install 装的东西来自 init 拉下来的目录,只跑 --install 而不跑 --init,通常会报找不到包或者目录为空。
--user 把安装目标限定到当前用户目录,作用是不碰系统级 Python 环境,也不需要 sudo。这条参数在多人共用的机器上很关键,翻车的姿势也很典型:不加 --user 而直接跑,要么因为权限被系统 Python 目录拒绝,要么装进去了但和系统包管理器管的文件打架,后面想卸载都找不到干净的入口。
代价是 PATH 问题。--user 装完之后,litex_sim 这类可执行脚本落在用户目录下的 bin 目录里,而不是系统 PATH 里。第一次跑 litex_sim 得到 command not found,九成是这里。处理办法是把那个目录补进 PATH,Linux 下常见位置是 ~/.local/bin:
bash复制# 把用户级脚本目录补进 PATH,当前终端立即生效
export PATH="$HOME/.local/bin:$PATH"
要长期生效就写进 shell 的启动文件。macOS 上这个目录不在同一位置,判断依据不要靠猜——pip 在 --user 安装结束时通常会打印一行警告,明确告诉你哪个目录不在 PATH 上,照着那行路径配就行。
2.3 --config 三档怎么选:别把占位写法当命令抄
材料里这一段的原始写法是 --config=(minimal, standard, full),括号和逗号是论文式的“三选一”标记,不是命令行语法。照着原样粘贴,脚本会因为参数值非法直接退出。正确做法是只填一个值,比如 --config=standard。
三档的差别在拉取范围和代价上,选档的逻辑应该按“这台机器要干什么”来定,而不是一次装到顶:
| 档位 | 拉取范围 | 适合场景 | 代价 |
|---|---|---|---|
| minimal | 只拉核心仓库 | 只想跑一次 litex_sim 验证环境是否通 |
最省时间,但缺目标板支持 |
| standard | 核心仓库加常用目标与工具 | 日常开发,偶尔切目标板 | 中等,多数人的默认选择 |
| full | 全部可选仓库 | 需要频繁在多种目标之间切换 | 下载与磁盘占用最高 |
新手最容易犯的错是一上来就 --config=full,觉得“装全了总没错”。实际上仓库越多,--install 阶段失败的暴露面越大,一旦某个可选仓库拉取中断,你很难判断是网络问题还是环境问题。我的建议是先 minimal 把 litex_sim 跑通,确认 Python 侧、工具链侧都没有问题,再回来补 standard 或 full,这时候出问题就能定位到“新加的仓库”上。
2.4 装完之后先别急着写代码
安装命令跑完不等于环境可用。这一步要有明确的验收动作:确认脚本没有在中途打印失败信息、确认 litex_sim 能被 shell 找到、确认 Python 能导入 LiteX。三者缺一,后面写多少代码都会在编译阶段一次性爆出来,而且报错信息往往指向一个和真实原因无关的位置。这也是我把它放在第一章之后单独成章的原因——验收顺序错了,排错成本会翻好几倍。
3. RISC-V 工具链:--gcc=riscv 该不该装、装在哪一步
3.1 先判断要不要 CPU,再决定装不装
材料里有一句关键限定:RISC-V 工具链“仅当您想使用 CPU 测试/创建 SoC 时”才需要安装。这句话直接决定了安装范围。如果你只是想让 LiteX 生成一份纯逻辑设计、或者跑一个不带 CPU 的仿真,这一步可以整个跳过,省下的是一大段下载和本地编译时间。
但只要目标里出现 --cpu-type=vexriscv 这样的参数,就绕不开它:仿真的对象本身是一个 RISC-V 核加周边总线,核的启动代码要用交叉编译器编出来,没有工具链,仿真器连启动镜像都生成不了。所以判断顺序是:先确定最终要跑什么,再决定装哪一层,而不是把脚本里所有开关都跑一遍。
3.2 meson 和 ninja 是构建工具链的前置
装 RISC-V GCC 不是下载一个压缩包解压那么简单,脚本走的是本地构建路线,因此需要先备好构建系统。材料给出的顺序是先装 Python 侧的 meson 和 ninja,再让脚本去拉并编译工具链:
bash复制# 构建 RISC-V 交叉工具链所需的前置构建工具
pip3 install meson ninja
# 让 litex_setup.py 拉取并构建 RISC-V 工具链
./litex_setup.py --gcc=riscv
meson 负责描述构建过程,ninja 负责实际执行编译任务,两者是搭配关系,缺一个都会在构建阶段停下来。没装就直接跑第二条命令,典型现象是脚本跑到构建环节报找不到 meson,前面拉取的部分看起来都成功了,很容易误判成“工具链下载失败”,实际是构建器没就位。
还有一点容易被忽略:--gcc=riscv 和前面的 --init --install --user --config 不是同一套参数体系,它是单独的一次工具链安装动作。把它们塞进同一条命令里,出问题时你分不清是仓库安装失败还是工具链构建失败。分开跑,每步单独验收,是更稳的做法。
3.3 装完之后的验证顺序:从 Python 侧往仿真侧推
工具链装完,验证要一层一层往上走,跳步会得到误导性的结论。第一层验 Python 侧是否真的装进去了:
bash复制# 确认 LiteX 能被当前解释器导入,并打印实际加载路径
python3 -c "import litex; print(litex.__file__)"
这一行能打出路径,说明 --install 那一步是成功的,且当前 shell 用的解释器和安装时是同一个。打不出来或者路径指向别处,问题在 Python 环境而不是工具链。
第二层才验工具链。判断方式不是去记工具链的可执行文件叫什么名字——不同来源的前缀不一样,记错了反而怀疑人生——而是直接跑仿真,看它停在哪:
bash复制# 带 RISC-V CPU 的仿真,用来暴露工具链和 Verilator 是否就位
litex_sim --cpu-type=vexriscv
报错里出现找不到交叉编译器,说明 --gcc=riscv 没跑或者构建产物没进 PATH;报错里出现找不到 verilator,说明工具链这关过了,卡在下一章的仿真器依赖上。用报错类型做分流,比逐个文件去翻目录快得多,这也是我排这类环境问题时最常用的手法。
4. Verilator 无板仿真:litex_sim 跑起来前的依赖清单
4.1 Linux 下三个系统包各管一段
没有开发板也能验证 SoC 结构,靠的是 Verilator 把生成的 Verilog 翻译成 C++ 模型再编译执行。这条链路需要几个系统级依赖,材料给出的 Linux 安装方式是:
bash复制# Verilator 本体 + 它依赖的事件库和 JSON-C 库
sudo apt install libevent-dev libjson-c-dev verilator
三个包不是随便凑的。verilator 是仿真器本体,负责把 Verilog 转成可编译的 C++;libevent-dev 提供事件循环支持,仿真的时钟推进和外部事件都走这套机制;libjson-c-dev 是 Verilator 部分组件解析配置时用到的库。只装 verilator 而漏掉后两个,典型现象是编译阶段链接报错,提示找不到对应的库文件,而报错位置看起来和你的设计毫无关系,第一次遇到很容易怀疑是自己生成的 Verilog 有问题。
这里要提醒的是发行版差异。上面这条命令是 Debian/Ubuntu 系的包名,换到别的发行版,包名和包管理器都要跟着换,但“本体加两个依赖库”这个结构不变。判断装没装全,最直接的办法是装完之后立刻跑一次 litex_sim,让它在真正需要这些库的时候自己暴露出来,而不是等到写完设计再一起爆。
4.2 macOS 上多一个 tuntap
macOS 的依赖清单和 Linux 不完全一样,材料给出的做法是:
bash复制# macOS 下的 Verilator 依赖
brew install json-c verilator libevent
# 网络仿真需要的虚拟网络接口支持
brew cask install tuntap
注意多出来的这一条。tuntap 提供的是虚拟网络接口能力,仿真里一旦涉及网络通路,没有它就跑不起来。这一步在 Linux 上通常不需要单独处理,所以从 Linux 切到 macOS 的人最容易漏装,现象是仿真启动到一半卡住或者直接报网络初始化失败,看上去像是设计里的网络部分写错了。
还有一个 HomeBrew 侧的变化值得提前知道:较新的版本把 cask 并进了 install 子命令,brew cask install tuntap 在新机器上可能提示命令已废弃。等价的写法是:
bash复制# 新版 HomeBrew 的等价写法
brew install --cask tuntap
两条命令装的是同一个东西,区别只在 HomeBrew 的版本。先跑前者,报废弃提示就换后者,不必纠结。
4.3 litex_sim 的运行链路与参数含义
依赖齐了,跑起来就是一行:
bash复制# 指定 RISC-V 的 vexriscv 核,启动无板仿真
litex_sim --cpu-type=vexriscv
这一行背后是四段动作:LiteX 先用 Python 生成一份完整的 Verilog 顶层;然后调 Verilator 把它翻译成 C++ 模型;接着用宿主机的编译器把模型编成可执行文件;最后运行这个可执行文件,CPU 从复位向量开始执行启动代码。
参数上,--cpu-type 决定仿真里放不放 CPU、放哪一种。不指定这个参数,得到的是不带 CPU 的纯逻辑仿真,速度快、依赖少,适合验证总线连接和外设行为;指定 vexriscv 才会引入核和启动镜像,也才会反过来要求第 3 章的交叉工具链。所以第一次跑仿真的正确顺序是:先不带 CPU 跑通,确认 Verilator 这条链没问题,再加 --cpu-type 验证工具链,两段分开排,出问题一眼就能定位到哪一层。
5. 常见问题:五个让 litex_setup.py 半路停下的坑
5.1 现象:第一步就报 wget: command not found
原因很直接:macOS 默认不带 wget,脚本的取用命令依赖它。解决是先把工具补上再重跑第一行,brew install wget。如果不想为一次安装引入新工具,用 curl -O 取同一个地址也能拿到脚本,但只要后面还要反复重装、或者脚本内部还会调用同类命令,补 wget 更省心。这条坑的典型特征是报错出现在所有安装动作之前,很好认。
5.2 现象:Windows 下脚本跑到一半行为异常
在 Windows 上直接跑这个脚本,可能在中途调用 shell 相关逻辑时失败或表现异常。材料给的解法是把 SHELL 环境变量指到 cmd:
bash复制# cmd 窗口里设置,之后再跑安装脚本
set SHELL=cmd.exe
PowerShell 里写法不同,用 $env:SHELL = "cmd.exe"。原因在于脚本内部假设自己处在一个类 Unix 的 shell 环境里,Windows 默认的 shell 解析方式和它对不上,于是前半段拉取正常、后半段执行异常。这类“一半成功一半失败”的现象最容易被误判成网络问题,实际是环境变量没设。设置之后要新开一个终端窗口再跑,旧窗口里的变量不会自动生效。
5.3 现象:照抄 --config=(minimal, standard, full) 直接报参数错误
原因是那串括号和逗号是文档里的“三选一”占位写法,不是命令行语法。解决是把整个值换成一个具体档位,例如 --config=standard。判断自己有没有踩这个坑很简单:报错发生在参数解析阶段、脚本还没开始任何下载动作,基本就是这一类。顺带说一句,档位不是越大越好,第一次装建议从 minimal 起,跑通再补。
5.4 现象:装完了,litex_sim 却是 command not found
原因是加了 --user,可执行脚本落在用户目录的 bin 下,而这个目录不在 PATH 里。解决是把该目录补进 PATH 并让当前终端生效。判别方法:用 python3 -c "import litex" 能导入,但 litex_sim 找不到,那就一定是 PATH 问题而不是安装失败。不要急着重装,重装一遍结果一样。具体目录以 pip 安装结束时打印的那行警告为准,照着配。
5.5 现象:仿真启动失败,提示缺库或网络初始化不了
分两种。Linux 上报找不到库文件,通常是只装了 verilator 本体,漏了 libevent-dev 和 libjson-c-dev;macOS 上仿真涉及网络时起不来,通常是漏了 tuntap。解决就是把对应系统的依赖清单补全再重跑。这类问题的特征是报错位置离你的设计很远,看起来像是生成的 Verilog 有问题,实际是宿主环境缺件。判断依据是报错里出现的库名,对照依赖清单一查就能确认。
6. 把安装序列固化成脚本:一份自检表和一条可复现的路径
环境搭通一次不算本事,换台机器还能一次搭通才算。我现在的做法是把整个序列固化成一段脚本,按“取脚本 → 装核心 → 装工具链 → 装仿真依赖 → 自检”五段排列,中间任何一段失败就停,不带着半成品往下走。
bash复制#!/usr/bin/env bash
set -e # 任何一步失败立即停止,避免半成品环境
# 1. 取安装脚本并赋权
wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
chmod +x litex_setup.py
# 2. 装核心仓库与 Python 包,先走最小档
./litex_setup.py --init --install --user --config=minimal
# 3. 用户级脚本目录补进 PATH(路径以 pip 警告为准)
export PATH="$HOME/.local/bin:$PATH"
# 4. 装 RISC-V 工具链的前置与工具链本身
pip3 install meson ninja
./litex_setup.py --gcc=riscv
# 5. 装 Verilator 及依赖,按系统二选一
# Linux:
sudo apt install libevent-dev libjson-c-dev verilator
# macOS:
# brew install json-c verilator libevent && brew install --cask tuntap
set -e 是这段脚本里最值钱的一行。没有它,中间某一步失败后脚本会继续往下跑,最后你面对的是一个“什么都装了一点、什么都跑不起来”的环境,排错时间远超重装一遍。
装完的验收按固定顺序做,每项单独确认,不要合并:
| 检查项 | 命令 | 通过表现 |
|---|---|---|
| Python 包 | python3 -c "import litex; print(litex.__file__)" |
打印出实际加载路径 |
| 可执行入口 | which litex_sim |
输出一个用户目录下的路径 |
| 无 CPU 仿真 | litex_sim |
生成 Verilog 并编译执行,不报缺库 |
| 带 CPU 仿真 | litex_sim --cpu-type=vexriscv |
越过交叉编译阶段,进入启动流程 |
这张表的顺序不能换。which litex_sim 放在 Python 导入之后,是因为两个失败原因完全不同;无 CPU 仿真放在带 CPU 之前,是为了把 Verilator 的问题和工具链的问题分开。有一次我把后两项顺序写反了,报错指向交叉编译器,我花了大半天去查工具链,最后发现是 Verilator 的依赖库没装全,工具链根本没有被执行到。这种误判在没有固定验收顺序的时候几乎必然发生。
从那以后,我每换一台机器,都先把这段脚本和这张表走一遍,四项全绿才动设计代码。希望帮到你。
