4. 开发环境搭建
旭日X5 是一颗面向边缘视觉推理的 SoC，其 CPU 为 ARM64 架构，而开发主机通常是 x86_64 的 Ubuntu。这意味着在主机上直接编译出的可执行文件无法在板端运行，必须使用交叉编译工具链生成 ARM64 目标程序。本节围绕“主机侧工具链 → 交叉编译配置 → 板端运行环境”这条主线，把开发环境一次搭稳，避免后续反复返工。
一、整体环境架构与依赖关系
下图展示了从开发主机到旭日X5 板端的完整环境拓扑。主机侧包含交叉编译工具链、模型转换工具与部署包；板端侧包含系统镜像、BPU 驱动、运行时库与推理程序。两侧通过 scp、NFS 或串口进行文件传输与调试。
二、主机侧工具链安装
推荐使用 Ubuntu 20.04 或 22.04，先安装基础编译依赖，再安装 ARM64 交叉编译器。以下命令可直接执行：
sudo apt update
sudo apt install -y build-essential cmake git wget \
gcc-aarch64-linux-gnu g++-aarch64-linux-gnu \
pkg-config libopencv-dev python3-pip
# 验证交叉编译器
aarch64-linux-gnu-gcc --version
aarch64-linux-gnu-g++ --version若使用官方提供的工具链压缩包，解压后需将 bin 目录加入 PATH，并确认 aarch64-linux-gnu-gcc 能正常输出版本号。工具链版本建议与板端 glibc 版本匹配，否则可能出现 GLIBC_2.xx not found 错误。
三、交叉编译配置
交叉编译的核心是让 CMake 或 Makefile 明确使用目标平台的编译器与系统根目录。推荐编写 toolchain.cmake：
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
set(CMAKE_FIND_ROOT_PATH /usr/aarch64-linux-gnu)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)编译时通过 -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake 引入。若项目依赖 OpenCV 或 BPU 运行时库，需要把板端对应的 include 与 lib 目录拷贝到主机，并在 CMake 中通过 target_include_directories 与 target_link_directories 指定，避免误链接主机 x86 库。
-march=armv8-a 与 -O2，并关闭主机侧不需要的测试程序，减少交叉编译时的依赖冲突。
四、板端运行环境准备
板端环境准备分为四步：烧录系统镜像、安装 BPU 驱动、部署运行时库、验证推理程序。烧录镜像后首次启动，建议先通过串口确认内核启动日志，再配置网络与 SSH。
- 烧录镜像：使用官方烧录工具将 Ubuntu 镜像写入 TF 卡或 eMMC，启动后确认
uname -a显示 aarch64。 - 安装 BPU 驱动：将驱动包拷贝到板端，执行
insmod或dkms安装，确认/dev/bpu*设备节点存在。 - 部署运行时库：把
libdnn.so、libhbrt.so等放入/usr/lib，执行ldconfig刷新缓存。 - 验证推理：运行官方示例程序，观察是否输出检测框与耗时日志。
# 板端检查 BPU 设备节点
ls /dev/bpu*
# 查看驱动模块
lsmod | grep bpu
# 刷新动态库缓存
sudo ldconfig
# 运行示例
./yolov5_demo --model model.bin --image test.jpg五、关键参数与常见误区对照
| 环节 | 关键参数/对象 | 正确做法 | 常见误区 |
|---|---|---|---|
| 工具链 | aarch64-linux-gnu-gcc | 版本与板端 glibc 对齐 | 用主机 gcc 直接编译 |
| 交叉编译 | CMAKE_TOOLCHAIN_FILE | 显式指定目标平台与根目录 | 遗漏 toolchain，链接到 x86 库 |
| 模型转换 | hb_mapper / 校准集 | 校准集覆盖真实场景分布 | 用少量随机图校准，精度骤降 |
| 板端驱动 | /dev/bpu* | 确认设备节点与驱动版本 | 只拷贝库，未装驱动 |
| 运行时库 | libdnn.so / libhbrt.so | 放入 /usr/lib 并 ldconfig | 库版本与模型不匹配 |
六、案例与复盘
某次部署中，主机交叉编译通过，但板端运行时报 error while loading shared libraries: libdnn.so: cannot open shared object file。排查发现库文件被放到了 /home/root/lib，而 LD_LIBRARY_PATH 未包含该路径。解决方式是将库放入 /usr/lib 并执行 ldconfig，或临时设置 export LD_LIBRARY_PATH=/home/root/lib:$LD_LIBRARY_PATH。
另一个高频问题是模型转换时校准集与推理输入尺寸不一致，导致板端输出异常。复盘结论是：主机侧工具链、模型转换参数、板端驱动与运行时库必须作为一套版本组合统一管理，建议在项目根目录维护 env_version.md，记录工具链版本、驱动版本、模型转换命令与板端库版本，便于复现与排障。
完成以上步骤后，主机具备交叉编译能力，板端具备 BPU 推理运行条件，后续即可进入模型转换与部署环节。建议先用官方示例跑通“编译—传输—运行”闭环，再替换为自己的视觉推理程序。