📚 课程目录第4章开发环境搭建与交叉编译

4. 开发环境搭建与交叉编译

Ryzen Embedded 平台（如 V2000/V3000 系列）在工业 GPU 图形工程中，开发环境的核心矛盾是：宿主机（x86_64 Ubuntu）与目标板（AMD APU + Radeon GPU）架构一致但运行环境不同。因此交叉编译并非传统 ARM 场景下的“跨指令集编译”，而是“同架构、跨根文件系统与内核版本”的构建。理解这一点，才能正确选择 Yocto、Buildroot 或 Ubuntu 工业镜像三条路线。

三条构建路线的定位与选择

Yocto 提供完整的 BSP 层与配方（recipe）体系，适合需要长期维护、定制内核与固件打包的产品；Buildroot 更轻量，适合功能固定、镜像体积敏感的嵌入式设备；Ubuntu 工业镜像（Ubuntu Core / Ubuntu Server with livepatch）则适合需要 apt 生态、快速迭代的工业网关或边缘计算节点。三者对 AMD GPU 驱动的集成方式差异明显：Yocto 通过 mesa、linux-firmware、amdvlk 等配方控制；Buildroot 通过 BR2_PACKAGE_MESA3D 与内核配置项；Ubuntu 则依赖官方内核模块与 linux-firmware 包。

交叉编译工具链的建立

在 Yocto 中，工具链由 bitbake meta-toolchain 或 bitbake -c populate_sdk core-image-sato 生成，输出一个自解压的 .sh 安装包。安装后通过 source /opt/poky/4.0/environment-setup-x86_64-poky-linux 激活，此时 CC、CXX、PKG_CONFIG_PATH 等变量自动指向目标 sysroot。Buildroot 则在 make sdk 后于 output/host/bin 下生成 x86_64-buildroot-linux-gnu-gcc 等工具。Ubuntu 工业镜像路线通常不生成独立工具链，而是直接在目标板上编译，或使用 debootstrap 构建 chroot 环境。

一个容易忽略的细节是：AMD GPU 用户态驱动（Mesa RADV/AMDVLK）依赖 libdrm、libdrm_amdgpu 和 libelf。交叉编译时，这些库必须来自目标 sysroot，而非宿主机。若 pkg-config 误用了宿主机的 libdrm.pc，链接阶段会报 undefined reference to drmIoctl 或版本不匹配。验证方法是执行 $CC -print-sysroot 确认路径，并用 pkg-config --cflags --libs libdrm_amdgpu 检查输出是否指向 sysroot。

内核参数与固件加载

AMD APU 的 GPU 驱动 amdgpu 以内核模块形式存在，其加载依赖两个条件：内核配置中启用 CONFIG_DRM_AMDGPU=y（或 =m）以及固件文件位于 /lib/firmware/amdgpu/。对于 V2000 系列（Renoir），所需固件包括 renoir_*.bin；V3000 系列（Cezanne）则对应 cezanne_*.bin。这些文件来自 linux-firmware 仓库，Yocto 中通过 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "linux-firmware-amdgpu" 加入镜像。

内核命令行参数直接影响 GPU 初始化行为。常用参数如下表所示：

参数	作用	推荐值	验证方式
`amdgpu.modeset`	启用内核模式设置（KMS）	1	`dmesg \| grep modeset`
`amdgpu.dc`	启用显示核心（Display Core）	1	`dmesg \| grep "Display Core"`
`amdgpu.sg_display`	分散-聚集显示，工业多屏场景可关闭	0	`dmesg \| grep sg_display`
`amdgpu.ppfeaturemask`	电源管理特性掩码	0xffffffff	`cat /sys/module/amdgpu/parameters/ppfeaturemask`

固件加载验证的关键日志片段如下：

[    2.345678] amdgpu 0000:04:00.0: firmware: direct-loading firmware amdgpu/renoir_asd.bin
[    2.456789] amdgpu 0000:04:00.0: firmware: direct-loading firmware amdgpu/renoir_ta.bin
[    2.567890] amdgpu 0000:04:00.0: firmware: direct-loading firmware amdgpu/renoir_dmcub.bin
[    2.678901] amdgpu 0000:04:00.0: firmware: direct-loading firmware amdgpu/renoir_pfp.bin
[    2.789012] [drm] Initialized amdgpu 3.49.0 20150101 for 0000:04:00.0 on minor 0

若出现 firmware: failed to load amdgpu/renoir_asd.bin，说明固件未打包进根文件系统。此时应检查 /lib/firmware/amdgpu/ 目录是否存在对应文件，并确认内核配置中 CONFIG_EXTRA_FIRMWARE 是否误将固件编译进内核而非从文件系统加载。

实操提示：在 Yocto 中调试固件加载时，可临时在 local.conf 中加入 IMAGE_INSTALL:append = " linux-firmware-amdgpu"，然后执行 bitbake core-image-minimal -c cleanall 后重新构建，避免配方缓存导致固件未更新。

Ubuntu 工业镜像的 GPU 配置要点

若选择 Ubuntu 路线，推荐使用 Ubuntu Server 22.04 LTS 并安装 linux-image-generic-hwe-22.04 以获取较新的 amdgpu 驱动。GPU 相关包包括 mesa-utils、vulkan-tools、clinfo、libdrm-amdgpu1。工业场景常需关闭图形界面以节省资源，此时应设置 systemctl set-default multi-user.target，但保留 /dev/dri 设备节点供 OpenCL/Vulkan 计算使用。

验证图形栈是否完整，可依次执行：glxinfo | grep "OpenGL renderer" 应输出 AMD RENOIR 或 AMD CEZANNE；vulkaninfo | grep deviceName 应输出 AMD RADV RENOIR；clinfo | grep "Device Name" 应输出 gfx90c 或 gfx90c:xnack-。若 glxinfo 报 Error: unable to open display，说明未设置 DISPLAY 或 X11 未启动，此时可改用 eglinfo 进行无头验证。

常见陷阱：Yocto 的 mesa 配方默认可能未启用 radeonsi 或 radv 驱动。需在 PACKAGECONFIG:append:pn-mesa = " gallium-llvm r600 radeonsi" 中显式开启，否则 glxinfo 会回退到 llvmpipe 软件渲染，性能相差数十倍。

构建与验证的闭环

完整的开发环境搭建应形成“配置—构建—部署—验证”的闭环。以 Yocto 为例：在 bblayers.conf 中加入 meta-amd 层，在 local.conf 中设置 MACHINE = "ryzen-embedded-v2000"，执行 bitbake core-image-weston 生成镜像，通过 dd 写入 eMMC 或 SD 卡，启动后依次检查 dmesg | grep amdgpu、lsmod | grep amdgpu、ls /dev/dri/、glxinfo | grep renderer。四步全部通过，才说明 GPU 驱动、固件、用户态图形栈均已正确集成。

对于 Buildroot，对应流程为：make menuconfig 中启用 Target packages → Hardware handling → mesa3d 与 System tools → amdgpu firmware，内核配置中勾选 Device Drivers → Graphics support → AMD GPU，执行 make 后于 output/images/ 获取 sdcard.img。验证方式与 Yocto 一致，但 Buildroot 默认不包含 glxinfo，需额外启用 mesa-utils 包。

交叉编译工具链的最终检验标准是：用目标工具链编译一个调用 libdrm_amdgpu 的小程序，在目标板上运行并成功打开 /dev/dri/renderD128。若编译通过但运行时报 Permission denied，需将运行用户加入 render 组；若报 No such device，则回到内核与固件加载环节排查。这一闭环将宿主机构建、目标板运行、GPU 硬件初始化三者串联，是 Ryzen Embedded 图形工程开发环境搭建的完整验收路径。