1. 引言

本文面向具备 Linux 命令行与 C 语言基础的新手开发者，旨在帮助你在 ARM 单板机（SBC）上快速开启 Linux 内核驱动开发之旅。

我们将从零开始，手把手带你搭建一套完整、高效且可复现的开发环境，涵盖硬件准备、系统烧录、编写驱动、交叉编译、部署和调试等全流程。

本文以 香橙派 5 Pro 开发板和 Armbian 系统为例，但核心思路也适用于其他 ARM SBC 及基于 Debian 的发行版。

1.1 香橙派 5 Pro 简介

Orange Pi 5 Pro 采用了瑞芯微 RK3588S 新一代八核 64 位处理器，具体为四核 A76 + 四核 A55，采用了 8nm 工艺设计，主频高达 2.4GHz，集成 ARM Mali-G610，内置 3D GPU，兼容 OpenGL ES1.1/2.0/3.2、OpenCL 2.2 和 Vulkan 1.2；内嵌的 NPU 支持 INT4/INT8/INT16 混合运算，算力高达 6TOPS，可以满足绝大多数终端设备的边缘计算需求；拥有 4GB/8GB/16GB LPDDR5，具有高达 8K 显示处理能力，支持 eMMC 模块或 SPI Flash（二选一），具有 Wi-Fi5、BT5.0，支持 BLE。

Orange Pi 5 Pro 提供了相当丰富的接口，包括 HDMI 输出、GPIO 接口、USB2.0、USB3.1、3.5mm 耳机插座、千兆网口，支持 PoE+（需要 PoE+ HAT），配备一个 M.2 M-Key 插槽，支持安装 NVMe 固态硬盘或 SATA 固态硬盘。

Orange Pi 5 Pro 精致小巧，尺寸仅为 89mm x 56mm x 1.6mm，功能强大，可广泛适用于高端平板、边缘计算、人工智能、云计算、AR/VR、智能安防、智能家居等领域，覆盖 AIoT 各个行业。Orange Pi 5 Pro 支持 Orange Pi 官方研发的操作系统 Orange Pi OS，同时，支持 Ubuntu、Android12、Debian 等操作系统。

Orange Pi 5 Pro 规格参数

主控芯片	Rockchip RK3588S（8nm LP 制程）
CPU	• 8 核 64 位处理器 • 4 核 Cortex-A76 和 4 核 Cortex-A55 的典型大小核架构，大核主频 2.4GHz，小核主频 1.8GHz
GPU	• 集成 ARM Mali-G610 • 内置 3D GPU • 兼容 OpenGL ES1.1/2.0/3.2、OpenCL 2.2 和 Vulkan 1.2
NPU	内置高达 6 Tops 算力的 AI 加速器 NPU，支持 INT4/INT8/INT16 混合运算
PMU	RK806-1
RAM	LPDDR5 496PIN：4GB、8GB、16GB 可选
存储	• eMMC 插座：支持 eMMC 模块（选购） • SPI Flash（默认空贴） 注：以上 eMMC 插座和板载 SPI Flash 二选一 • MicroSD（TF）插槽 • M.2 M-KEY 插槽：NVMe SSD 或 SATA SSD
USB	USB3.1 Gen1×1；USB2.0×1； USB HUB：USB2.0×2（Type A）+USB2.0×2 排针扩展接口
视频输出	• HDMI2.1，最高支持 8K @60Hz • HDMI2.0，最高支持 4K @60Hz • MIPI 4 Lane，最高可配置为 4K @60Hz
摄像头	• 2×MIPI CSI 4 Lane
音频	CODEC:ES8388 • 3.5mm 耳机孔音频输入/输出 • 输入：板载 MIC • HDMI 2.1 eARC
以太网	10/100/1000Mbps 以太网，支持 PoE+（需要 PoE+ HAT）
Wi-Fi、BT 模块	板载 Wi-Fi5+BT 5.0/BLE 模块：AP6256
PCIe M.2 M-KEY 插槽	M.2 M-Key 插槽支持接入 NVMe SSD 硬盘或 SATA 固态硬盘
扩展口：40PIN 双排插针	双排插针：2.54mm 40Pin 支持 DC 5V 和 3.3V 电源输出 可配置 UART、PWM、 I2C、 SPI、CAN、GPIO 等功能接口
按键	1×MaskROM，1×RESET，1×POWER
供电	• 支持 Type-C 供电，5V @ 5A
LED	RGB LED 三色指示灯
FAN	5V 2PIN 1.25mm 插座
RTC	3V 2PIN 1.25mm 插座
调试	调试串口 UART 包含在 40PIN 扩展口内
PCB	12 层，长：89mm，宽：56mm，厚：1.6mm
重量	62g
支持的操作系统	Orangepi OS（Droid）、Orangepi OS（Arch）、Orangepi OS（OH）、Ubuntu、Debian、Android12

1.2 Armbian 简介

Armbian 是为单板计算机（Single Board Computer，SBC）提供的高度优化的基础操作系统。它兼具极致轻量化的硬件适配特性，以及基于 Debian 构建、广为人知且支持完善的用户空间体验，还配备了功能丰富的构建框架，适用于工业场景或家庭使用。

Armbian 本身并非一款独立的 Linux 发行版。相反，Armbian 以 Debian GNU/Linux 和 Ubuntu Linux 作为镜像基础，供用户下载和部署。Armbian 为每款单板计算机构建专属的优化内核，随后提供一套功能全面且可自定义的框架，用于构建、调整和配置这些系统镜像 —— 这套框架正是该项目的核心所在。

2. 准备工作

工欲善其事，必先利其器。准备好以下物品，让开发过程顺畅无阻：

2.1 核心硬件

• 香橙派 5 Pro 开发板 ×1
• 高速 MicroSD 卡 ×1（推荐 32GB 及以上, Class 10/UHS-I）
• 稳定的 USB-C 电源 ×1（5V/5A 官方电源或同等规格）
• MicroSD 读卡器 ×1

2.2 调试与连接

• USB 转 TTL 串口模块 ×1（网络无法连接或者首次启动无显示器时选择，常见型号 CP2102/CH340/FT232）
• 以太网线 ×1（用于 SSH 远程登录和文件传输）

2.3 开发主机

• Windows 开发主机：推荐 Windows 11
• Linux 开发主机：推荐 Ubuntu 22.04 LTS（传统虚拟机/WSL2/物理机均可）

2.4 核心软件

• 交叉编译器: aarch64-linux-gnu-gcc（仅交叉编译模式需要，后续在 Linux 开发主机上安装）。
• Armbian 镜像：orangepi-5pro，Desktop 和 Minimal（无图形界面）镜像均可，请手动下载到 Windows 开发主机。
• 烧录工具：BalenaEtcher，请手动下载安装到 Windows 开发主机（需以管理员身份运行）。

小贴士：为什么强烈推荐交叉编译？
虽然可以直接在香橙派上安装编译器进行开发（板上编译），但 ARM 板的性能、内存和散热均有限。在 x86_64 主机上进行交叉编译速度更快、环境更稳定，是专业嵌入式开发的首选方案。

3. 系统部署

3.1 烧写 Armbian 镜像

在 Windows 开发主机上，使用图形化工具 BalenaEtcher 将下载到本地的 Armbian 镜像写入 MicroSD 卡。

1. 打开 BalenaEtcher，点击左侧「Flash from file」，选择下载好的 Armbian 镜像（.img 格式）。
2. 点击中间「Select target」，选择插入的 MicroSD 卡（务必确认选择的是 SD 卡，避免误选硬盘分区导致数据丢失）。
3. 点击右侧「Flash!」，等待烧写完成（约 5-10 分钟，取决于 SD 卡速度）。
4. 烧写完成后，BalenaEtcher 会自动校验镜像（不要手动拔卡），校验通过后再弹出 SD 卡。

常见失败原因

• SD 卡/读卡器损坏：换用其他 SD 卡或者读卡器。
• 端口接触不良：换用 USB 2.0 端口（USB 3.0 可能存在兼容性问题）。
• 镜像损坏：Armbian 下载页面提供镜像 MD5 值，PowerShell 下执行 certutil -hashfile 镜像文件名 核对哈希值。

3.2 首次启动

1. 连接硬件: 将烧写好的 SD 卡插入香橙派，连接好显示器、网线、电源、鼠标和键盘。
2. 启动系统: 按下电源键开机，首次开机需等待引导（约 1-2 分钟），Armbian 系统启动后可以在显示器上看到命令行或者图形界面输出。
3. 初次配置：Armbian 首次启动会引导你进行一系列系统设置：1. 选择语言（推荐 English，避免中文乱码）；2. 设置时区（如 Asia/Shanghai）；3. 创建普通用户并设置密码（记住密码，后续 SSH 登录用）。
4. 获取 IP 地址: 系统启动后，在终端输入 ip addr 命令，找到 inet 后的 IP 地址（排除 inet 127.0.0.1），以便后续通过 SSH 登录。

4. 板上编译 vs. 交叉编译

这是一个关键的选择，直接影响你的开发效率。

方案	优点	缺点	适用场景
在板上编译	配置简单，无需额外工具链	编译速度慢，占用板上宝贵资源，可能因内存不足导致失败	临时快速验证一个极小的模块，或者在没有开发主机时应急。
交叉编译（主机）	速度极快，充分利用主机性能，便于版本控制	需要正确配置交叉编译器和内核源码/头文件	强烈推荐，专业驱动开发的标准流程。

结论：对于驱动开发，请尽量选择交叉编译。

5. 搭建主机交叉编译环境

这是核心部分，请严格按照步骤操作。

5.1 在 Linux 主机上安装交叉编译器

# === 在 Linux 开发主机上执行 ===
sudo apt update
# 安装交叉编译器、工具链和其他工具
sudo apt install -y build-essential gcc-aarch64-linux-gnu libelf-dev bison flex libssl-dev libncurses-dev bc git

5.2 获取目标板内核头文件

内核模块必须基于与目标板运行内核 完全相同版本 的源码进行编译。最稳妥的方式是在开发板上安装对应的头文件包，然后拷贝到主机。

开发板烧录的 armbian 镜像版本不同，内核版本也会不一样，请根据你的实际情况修改版本号。下面以 6.1.115 内核版本为例说明。

第 1 步：在香橙派开发板上操作

# === 在香橙派开发板上执行 ===
sudo apt update
# 1. 安装开发板内核头文件
# 如果下面的命令找不到包，请尝试 apt search "linux-headers-" 查找匹配的头文件包进行安装。
sudo apt install linux-headers-vendor-rk35xx
# 2. 将安装好的头文件打包，方便传输
# uname -r 获取内核版本号，如：6.1.115-vendor-rk35xx
cd /usr/src/
tar -czf ~/orangepi-5-pro-kernel-headers.tar.gz linux-headers-$(uname -r)

第 2 步：在 Linux 开发主机上操作

# === 在 Linux 开发主机上执行 ===
# 1. 将压缩包从开发板拷贝到主机
scp <user_name>@<orangepi_ip>:~/orangepi-5-pro-kernel-headers.tar.gz ~/
# 2. 在主机上解压，解压后的目录就是编译时需要的内核头文件目录
# 解压后的目录名是 linux-headers-6.1.115-vendor-rk35xx
cd ~/
tar -xzf orangepi-5-pro-kernel-headers.tar.gz

注：以上操作假设 Armbian 仓库提供匹配的头文件包。若无法通过 apt 获取，需从 Armbian 或官方内核源码仓库获取对应版本源码并编译以生成内核头文件，可参考下面自编译内核章节内容。

5.3 交叉编译与部署

现在，我们可以在 Linux 主机上编译内核模块了。

5.3.1 内核模块示例代码

在 Linux 主机 home 目录下创建一个新文件夹，例如 ~/hello_orangepi，并创建以下两个文件。

hello_orangepi.c

#include <linux/init.h>
#include <linux/module.h>
#include <linux/kernel.h>

static int __init hello_init(void)
{
    pr_info("Hello World from Orange Pi 5 Pro kernel module!\n");
    return 0;
}

static void __exit hello_exit(void)
{
    pr_info("Goodbye from Orange Pi 5 Pro kernel module!\n");
}

module_init(hello_init);
module_exit(hello_exit);

MODULE_LICENSE("GPL");

Makefile

# 编译后生成的目标模块名为 hello_orangepi.ko
obj-m := hello_orangepi.o
# KDIR 指向远程拷贝自开发板的香橙派5Pro内核头文件目录
# !!! 注意：请将这里的版本号替换为你自己的内核版本号 !!!
KDIR := $(HOME)/linux-headers-6.1.115-vendor-rk35xx
PWD := $(shell pwd)

all:
	$(MAKE) -C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

5.3.2 设置环境变量

# === 在 Linux 开发主机上执行 ===
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-

提示：这里设置的环境变量仅在当前终端会话中有效，关闭终端后需重新执行。

5.3.3 内核头文件适配

从开发板拷贝过来的内核头文件包含了一些构建工具（如 fixdep, modpost），这些工具是 aarch64 架构的可执行文件，在 x86 主机上不能直接使用，我们需要在 x86 主机上重新编译生成。

# === 在 Linux 开发主机上执行 ===
# 临时禁用 qemu-aarch64，防止系统自动运行 ARM64 程序（仅限 WSL2）
sudo sh -c 'echo -1 > /proc/sys/fs/binfmt_misc/qemu-aarch64'
# 删除 aarch64 构建工具并重新编译生成 x86 版本（请替换为你的实际路径）
cd ~/linux-headers-6.1.115-vendor-rk35xx/
rm -f scripts/basic/fixdep && gcc scripts/basic/fixdep.c -o scripts/basic/fixdep
rm -f scripts/mod/modpost && gcc scripts/mod/modpost.c scripts/mod/file2alias.c scripts/mod/sumversion.c -o scripts/mod/modpost
# 操作完成后恢复启用 qemu-aarch64（仅限WSL2）
sudo sh -c 'echo 0 > /proc/sys/fs/binfmt_misc/qemu-aarch64'

5.3.4 执行编译

# === 在 Linux 开发主机上执行 ===
# 进入模块源码目录
cd ~/hello_orangepi
# 已设置环境变量则直接编译
make
# 或者，在编译时临时指定环境变量
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

编译成功后会在当前目录下生成 hello_orangepi.ko 文件。

5.3.5 加载模块并查看日志

第 1 步：将编译好的模块从主机拷贝到开发板

# === 在 Linux 开发主机上执行 ===
scp hello_orangepi.ko <user_name>@<orangepi_ip>:~/

第 2 步：登录开发板并加载模块

# === 在香橙派开发板上执行 ===
cd ~/
# 加载模块
sudo insmod hello_orangepi.ko
# 查看内核日志，你应该能看到 "Hello World from Orange Pi 5 Pro kernel module!"
sudo dmesg | tail
# 卸载模块
sudo rmmod hello_orangepi
# 查看内核日志，你应该能看到 "Goodbye from Orange Pi 5 Pro kernel module!"
sudo dmesg | tail

6. 最佳实践

6.1 推荐开发流程

1. 主机: 编写/修改驱动代码。
2. 主机: 运行 make 交叉编译生成 .ko 文件。
3. 网络: 使用 scp 或 rsync 将 .ko 文件同步到板子上。
4. 板子: rmmod 旧模块（如果已加载），insmod 新模块。
5. 板子/主机: 通过 dmesg、sysfs 或实际硬件行为来测试和调试。
6. 重复: 如果经常重复上述操作，可以编写 shell 脚本实现自动化。

6.2 可视化工作流

7. 自编译内核（可选）

在某些场景下，我们可能需要修改内核配置、打补丁或增加新功能，这就需要自己编译整个内核。

7.1 获取 Linux 内核源码

• 香橙派内核：linux-orangepi
• Armbian 内核：linux-armbian
• Rockchip 官方：linux-rockchip

Rockchip 官方对具体开发板的支持比较欠缺，请使用香橙派或者 Armbian 内核源码，本文以 Armbian 内核源码为例进行说明。

请选择和开发板内核版本一致的仓库分支，以前述 6.1.115 内核为例，它属于 rk-6.1 分支。

# === 在 Linux 开发主机上执行 ===
cd ~/
git clone https://github.com/armbian/linux-rockchip.git -b rk-6.1-rkr3

7.2 构建内核并生成镜像

7.2.1 配置内核

Armbian 为其设备提供了预置的内核配置文件，我们可以下载并使用它作为基础。

# === 在 Linux 开发主机上执行 ===
# 进入内核源码目录
cd ~/linux-rockchip
# 下载 armbian 提供的默认配置文件
wget https://raw.githubusercontent.com/armbian/build/main/config/kernel/linux-rk35xx-vendor.config -O .config
# 基于现有 .config 文件生成完整的配置，并接受所有默认选项
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- olddefconfig
# (可选) 如果需要自定义配置，可运行 make menuconfig
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- menuconfig

7.2.2 编译内核

# === 在 Linux 开发主机上执行 ===
# 可根据需要添加 -j$(nproc) 参数加速编译
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

编译成功后，主要输出文件及其路径：

• 内核镜像 Image：arch/arm64/boot/
• 设备树文件 rk3588s-orangepi-5-pro.dtb：arch/arm64/boot/dts/rockchip/

7.3 替换内核镜像或设备树

如果需要修改内核或设备树源码，则在 Linux 开发主机上修改，然后交叉编译，生成内核镜像文件 Image 或者设备树文件 rk3588s-orangepi-5-pro.dtb。

第 1 步：将编译好的文件从主机拷贝到开发板

# === 在 Linux 开发主机上执行 ===
cd ~/linux-rockchip
# 拷贝内核镜像
scp arch/arm64/boot/Image <user_name>@<orangepi_ip>:~/
# 拷贝设备树
scp arch/arm64/boot/dts/rockchip/rk3588s-orangepi-5-pro.dtb <user_name>@<orangepi_ip>:~/

第 2 步：在开发板上备份并替换文件

注意：这是高风险操作，请提前备份重要数据！

# === 在香橙派开发板上执行 ===
# 以 6.1.115 版本内核为例，其他版本请自行修改版本号
cd ~/
# 需要替换内核镜像时执行
sudo cp Image /boot/vmlinuz-6.1.115-vendor-rk35xx
# 需要替换设备树时执行
sudo cp rk3588s-orangepi-5-pro.dtb /boot/dtb/rockchip/
# 重启生效
sudo reboot

8. 总结

通过以上步骤，你已完成从硬件准备 → 系统部署 → 内核/模块编写 → 交叉编译 → 部署调试的完整闭环，为后续开发 I2C、SPI、GPIO、Camera 等驱动打下了坚实的基础。祝你探索顺利！