3. 开发主机环境搭建

Kria 平台的开发体验与主机环境强相关。KV260、KR260 这类 SOM 上运行的是 Ubuntu 22.04 LTS 根文件系统，而开发主机承担的是“交叉编译 + 镜像打包 + 调试下载”三类任务。如果主机版本、工具链版本、依赖包和许可证状态不匹配，最典型的现象是 PetaLinux 在 petalinux-config 阶段报 Python 模块缺失，或 Vitis 在生成 BOOT.BIN 时找不到 bootgen。因此本节按“选系统 → 装工具 → 配依赖与许可 → 容器化隔离 → 准备调试通道”的顺序，把主机环境一次性搭稳。

一、Ubuntu 版本选择：以 22.04 LTS 为基准

AMD 官方对 2023.x 及之后的 Vitis、PetaLinux 工具链，明确支持 Ubuntu 20.04 LTS 与 22.04 LTS。选择 22.04 LTS 的理由有三点：其一，Kria 官方 Ubuntu 镜像本身基于 22.04，主机与目标机的 glibc、Python 版本更接近，减少交叉编译时的库差异；其二，22.04 默认 Python 3.10，与 PetaLinux 2023.2 要求的 Python 3.8+ 兼容；其三，22.04 的长期支持到 2027 年，适合课程与项目周期。

需要避免的是 23.10、24.04 这类较新版本。PetaLinux 安装脚本会检查发行版代号，遇到未列入白名单的系统会直接退出，即使强行跳过检查，也可能因 GCC 13 默认标准变化导致内核模块编译失败。若主机已装 24.04，建议用容器或虚拟机固定到 22.04，而不是在裸机上硬改。

磁盘与内存方面，Vitis 完整安装约 60 GB，PetaLinux 安装加一次完整构建约 100 GB，建议预留 250 GB SSD 空间、32 GB 内存；若只有 16 GB 内存，PetaLinux 构建需把并行任务数降到 -j4 以下，否则容易 OOM。

二、Vitis 与 PetaLinux 工具链安装

两者是独立安装包，但共享部分依赖。Vitis 2023.2 统一安装器（Xilinx Unified Installer）中，必须勾选 Vitis Embedded Development 与 Zynq UltraScale+ MPSoC 器件支持，否则后续无法为 Kria 生成平台。安装时建议把安装目录设为 /tools/Xilinx，避免路径含空格或中文。

# 安装器下载后赋予执行权限并启动
chmod +x Xilinx_Unified_2023.2_1013_2256_Lin64.bin
./Xilinx_Unified_2023.2_1013_2256_Lin64.bin

# 安装完成后加载环境（写入 ~/.bashrc 可持久化）
source /tools/Xilinx/Vitis/2023.2/settings64.sh
source /tools/Xilinx/PetaLinux/2023.2/settings.sh
echo $PETALINUX   # 应输出 /tools/Xilinx/PetaLinux/2023.2

PetaLinux 安装包为 petalinux-v2023.2-10121855-installer.run，安装时用 --dir 指定目录。安装结束后执行 petalinux-util --webtalk off 关闭遥测，可减少构建时的网络等待。验证安装是否成功，最直接的方式是新建一个最小工程并跑到配置界面：

petalinux-create -t project --template zynqMP -n kria_test
cd kria_test
petalinux-config --get-hw-description=../  # 指向含 .xsa 的目录

若 petalinux-config 能正常弹出菜单，说明工具链、Python 依赖和许可证均已就绪。

三、依赖包与许可证配置

PetaLinux 对主机依赖非常敏感，官方推荐一次性安装以下包（22.04 下）：

sudo apt-get install -y gcc g++ make python3 python3-pip \
  python3-venv python3-dev zlib1g-dev libncurses5-dev libncursesw5-dev \
  libssl-dev libselinux1 gnupg wget git diffstat chrpath socat \
  cpio texinfo gawk build-essential flex bison libsdl1.2-dev \
  xterm autoconf libtool tar unzip texinfo gcc-multilib \
  libsdl1.2-dev libglib2.0-dev libtool-bin

其中 chrpath、socat、cpio、libncurses5-dev 是最常被遗漏、又最容易导致构建中断的四个包。建议安装后用 petalinux-util --check 做一次依赖自检。

许可证方面，Vitis 与 PetaLinux 均使用免费许可证，但需在 Xilinx 官网生成 Xilinx.lic 并设置环境变量：

export XILINXD_LICENSE_FILE=/opt/licenses/Xilinx.lic
export LM_LICENSE_FILE=$XILINXD_LICENSE_FILE

若使用浮动许可证服务器，则写成 2100@license-server 形式。许可证未生效时，Vivado 会在综合阶段报 Feature not available，而 PetaLinux 本身不校验许可证，容易造成“PetaLinux 能跑、Vitis 报错”的错觉。

四、Docker/Podman 容器化构建环境

把工具链装进容器，可以彻底解决“换主机就要重装”的问题。AMD 在 Docker Hub 提供 xilinx/vitis-tools 与 xilinx/petalinux 镜像，但更推荐基于 Ubuntu 22.04 自建，便于固定依赖版本。Podman 与 Docker 命令基本兼容，且 Podman 无需 root 守护进程，在课程实验机上更安全。

# 以 Podman 为例，构建并进入容器
podman build -t kria-dev:22.04 -f Dockerfile.kria .
podman run -it --rm \
  -v $HOME/kria_ws:/workspace \
  -v /dev:/dev \
  --device=/dev/ttyUSB0 --device=/dev/ttyUSB1 \
  --group-add keep-groups \
  kria-dev:22.04 /bin/bash

关键点有三：一是把工作区挂载进容器，保证构建产物落在主机上；二是用 --device 把串口和 JTAG 的 USB 设备透传进容器，否则容器内无法下载与调试；三是镜像内提前 source 好 Vitis 与 PetaLinux 环境，进入容器即可直接构建。若使用 Docker，把 podman 换成 docker 即可，但需注意 Docker 默认以 root 运行，挂载文件的属主会变成 root，建议加 --user $(id -u):$(id -g)。

五、串口与 JTAG 调试工具准备

Kria 板卡通过板载 FTDI 芯片同时提供串口与 JTAG，插上 USB 后主机通常出现两个设备：/dev/ttyUSB0 为串口控制台，/dev/ttyUSB1 为 JTAG 通道。串口参数固定为 115200-8-N-1，无流控。推荐用 picocom 或 minicom：

sudo apt-get install -y picocom
sudo usermod -aG dialout $USER   # 重新登录后生效，避免每次 sudo
picocom -b 115200 /dev/ttyUSB0

JTAG 侧需要安装 libftdi 与 openocd，并确认 Xilinx 的 xsdb 能识别到目标：

sudo apt-get install -y libftdi1-dev openocd
source /tools/Xilinx/Vitis/2023.2/settings64.sh
xsdb
xsdb% connect
xsdb% targets      # 应列出 PS TAP 与 PL TAP

若 targets 为空，先检查 lsusb 是否出现 Future Technology Devices International 设备，再确认当前用户是否在 dialout 组、容器是否透传了 USB 设备。串口能打印 U-Boot 日志、JTAG 能列出 TAP，是主机环境“可用”的两个硬性判据。

完成本节后，主机应达到的状态是：petalinux-config 能弹出菜单、xsdb connect 能列出 TAP、picocom 能收到 U-Boot 打印、容器内可重复执行同一套构建命令。这四项通过，后续的镜像构建与下载调试才有稳定基础。