2、环境搭建：RK3588开发板准备、交叉编译工具链、NPU驱动与RKNN Toolkit安装

RK3588作为瑞芯微旗舰级SoC，集成了四核Cortex-A76与四核Cortex-A55的big.LITTLE架构CPU、Mali-G610 GPU以及算力达6 TOPS的NPU（神经网络处理单元）。在开始模型部署之前，搭建一套完整、稳定且版本匹配的软件开发环境，是整个项目成功的基础。本章将围绕开发板硬件准备、交叉编译工具链配置、NPU驱动安装以及RKNN Toolkit部署四个核心环节展开，帮助您从零构建一套可用的RK3588模型部署工作台。

2.1 开发板硬件准备与系统烧录

核心原理：RK3588开发板是模型部署的物理载体，其硬件配置直接决定了后续调试的便利性与性能验证的准确性。常见的RK3588开发板包括瑞芯微官方EVB、Toybrick RK3588、Orange Pi 5 Plus等。不同板卡的差异主要体现在内存容量（4GB/8GB/16GB/32GB LPDDR4x）、存储接口（eMMC/NVMe/SD）、调试接口（Type-C/HDMI/40Pin GPIO）以及散热设计上。对于模型部署工作，建议优先选择至少8GB内存的版本，因为NPU推理时往往需要同时加载模型权重、输入/输出张量以及中间计算结果，内存不足会导致OOM（Out of Memory）或频繁swap，严重影响推理延迟。

操作流程：开发板准备分为以下四个步骤：

1. 硬件检查：确认板卡供电（建议12V/3A以上DC电源）、串口调试线（USB转TTL，3.3V电平）、网络连接（千兆以太网或Wi-Fi模块）。
2. 系统镜像烧录：从瑞芯微官方或板卡厂商获取Ubuntu 20.04/22.04固件（需包含NPU驱动）。使用 RKDevTool（Windows）或 upgrade_tool（Linux）将镜像烧录至eMMC。烧录时需将板卡进入MaskROM模式（按住BOOT键再上电）。
3. 系统验证：通过串口或HDMI进入系统，执行 cat /proc/version 确认内核版本，执行 ls /dev/rknpu* 检查NPU设备节点是否存在。
4. 网络配置：设置静态IP或使用DHCP，确保宿主机与开发板之间可以SSH连接，便于后续文件传输与远程调试。

2.2 交叉编译工具链配置

核心原理：交叉编译是指在x86_64架构的宿主机上编译生成ARM64架构可执行文件的过程。RK3588的NPU部署通常需要编写C/C++程序调用 librknnrt.so 运行时库，而该库的依赖（如glibc、libstdc++）必须与目标板系统匹配。使用 aarch64-linux-gnu-gcc 工具链可以确保编译出的二进制文件能在RK3588的Linux系统上正确运行。工具链版本建议使用GCC 9.3或更高版本，以支持C++14/17特性。

判断方法：在宿主机上执行以下命令验证工具链是否可用：

# 安装交叉编译工具链（Ubuntu 20.04）
sudo apt-get update
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

# 验证版本
aarch64-linux-gnu-gcc --version

# 编写测试程序 hello.c
# printf("Hello RK3588!\n");
# 编译
aarch64-linux-gnu-gcc hello.c -o hello_arm

# 通过scp传输到开发板并执行
scp hello_arm root@<板卡IP>:/root/
ssh root@<板卡IP> "./hello_arm"

案例拆解：在实际项目中，我们通常使用CMake管理交叉编译工程。以下是一个典型的 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)

使用 cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake .. 即可生成Makefile并编译。需要注意，CMAKE_FIND_ROOT_PATH 必须指向目标板的sysroot，否则链接器可能找不到 librknnrt.so 的头文件和库文件。

2.3 NPU驱动安装与验证

核心原理：RK3588的NPU硬件由内核驱动 rknpu.ko 管理，该驱动负责NPU的电源管理、内存分配、任务调度以及与用户态 librknnrt.so 的交互。驱动版本必须与固件内核版本严格匹配。瑞芯微官方发布的 rknpu2 驱动包中包含了预编译的 .ko 文件以及对应的 librknnrt.so 运行时库。如果驱动未正确加载，NPU设备节点 /dev/rknpu 将不存在，任何NPU调用都会失败。

操作流程：NPU驱动安装步骤如下：

1. 获取驱动包：从瑞芯微官方GitHub仓库（https://github.com/airockchip/rknn-toolkit2）或板卡厂商BSP中下载 rknpu2 驱动压缩包。
2. 上传并解压：将驱动包通过scp传输至开发板，解压后进入 rknpu2/runtime/Linux/librknn_api 目录。
3. 安装驱动：执行 sudo cp rknpu.ko /lib/modules/$(uname -r)/，然后运行 sudo depmod -a 和 sudo modprobe rknpu。若系统启动时自动加载，可将 rknpu 添加到 /etc/modules 文件。
4. 验证驱动：执行 dmesg | grep rknpu 查看内核日志，应看到 rknpu: RKNPU driver version: 0.9.2 之类的信息。同时检查 ls -l /dev/rknpu 确认设备节点权限。

常见误区：很多初学者在烧录固件后直接运行NPU程序，却忽略了驱动是否已加载。如果开发板固件是厂商预编译的，通常已包含驱动；但如果自行编译内核，则必须手动配置 CONFIG_ROCKCHIP_RKNPU=y。此外，驱动版本与 librknnrt.so 版本不匹配时，程序运行会报 RKNN_ERR_MODEL_INVALID 或 RKNN_ERR_DRIVER_VERSION 错误。建议使用 rknn-toolkit2 自带的 librknnrt.so 替换板卡上的旧版本，确保一致性。

2.4 RKNN Toolkit安装与版本匹配

核心原理：RKNN Toolkit是运行在宿主机上的Python工具包，用于将TensorFlow、PyTorch、ONNX等格式的模型转换为RK3588 NPU可执行的 .rknn 文件。它同时提供模拟器功能，可以在x86宿主机上模拟NPU推理结果，便于算法工程师在无硬件环境下进行模型精度验证。RKNN Toolkit分为 rknn-toolkit（旧版）和 rknn-toolkit2（新版，适配RK3588）。必须使用 rknn-toolkit2，且版本需与板卡上的 rknpu2 驱动版本对应。

安装流程：推荐使用Python虚拟环境安装，避免污染系统环境：

# 创建虚拟环境（Python 3.8/3.9/3.10均可）
python3 -m venv rknn_env
source rknn_env/bin/activate

# 安装RKNN-Toolkit2（以v1.6.0为例）
pip install rknn-toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl

# 验证安装
python -c "from rknn.api import RKNN; print('RKNN-Toolkit2 OK')"

版本匹配表：以下为经过验证的版本组合，建议严格遵循：

案例拆解：假设我们需要在宿主机上将ONNX模型转换为RK3588可用的RKNN模型。以下是一个最小化转换脚本：

from rknn.api import RKNN

rknn = RKNN()
# 配置NPU目标平台
rknn.config(target_platform='rk3588', optimization_level=3)
# 加载ONNX模型
ret = rknn.load_onnx(model='yolov5s.onnx')
if ret != 0:
    print('模型加载失败')
    exit(1)
# 构建RKNN模型（可指定量化数据集）
ret = rknn.build(do_quantization=False)
if ret != 0:
    print('模型构建失败')
    exit(1)
# 导出RKNN文件
ret = rknn.export_rknn('yolov5s.rknn')
if ret != 0:
    print('导出失败')
    exit(1)
rknn.release()

转换完成后，将 .rknn 文件和 librknnrt.so 一起拷贝到开发板，即可编写C/C++或Python推理程序。注意，宿主机上的 rknn-toolkit2 仅用于模型转换和仿真，实际推理必须依赖板卡上的NPU硬件。