针对环境（Linux + RTL8821CU）的完整移植方案
一、驱动源码获取
推荐：使用lwfinger/rtl8821cu（对老内核兼容性较好）
bash
# 在宿主机（Ubuntu/CentOS）上执行 git clone https://github.com/lwfinger/rtl8821cu.git cd rtl8821cu #如果github无法拉下来，或者网速太慢，可以找一个国内镜像源备选：Realtek 官方老版本驱动
向你的 WiFi 模块供应商索取：
明确说明：
Linux kernel 版本, ARM 芯片平台, USB还是SDIO接口索取
RTL8821CU_Linux_v5.x.x或更早版本的驱动包
二、交叉编译环境准备
1. 确认你的交叉编译工具链
bash
# 在你的宿主机上检查 which arm-linux-gnueabihf-gcc # 或 which arm-poky-linux-gnueabi-gcc # 如果是 Yocto 环境 # 1. 找交叉编译器 which arm-linux-gnueabihf-gcc || which arm-none-linux-gnueabi-gcc || find /opt /usr -name "*gcc" -path "*arm*" 2>/dev/null | head -52. 确认内核源码路径
你需要有与目标板完全一致的内核源码：
bash
# 典型路径，根据你的 SDK 调整 KSRC=/path/to/imx6ul-bsp/linux-imx # 例如 Yocto 环境： KSRC=/opt/fsl-imx-fb/3.14.38-6UL_ga/sysroots/cortexa7hf-vfp-neon-poky-linux-gnueabi/usr/src/kernel # 2. 找内核源码 find /home /opt /root -maxdepth 4 -type d -name "linux-*imx*" 2>/dev/null | head -53. 确认目标内核版本
uname -r # 如果在目标板上执行三、驱动移植与编译
1. 修改 Makefile
bash
cd rtl8821cu vim Makefile针对IMX6UL，你需要这样做：
① 在平台选择区，添加IMX6UL的配置（如果没有现成的ARM平台可用）：
makefile
CONFIG_PLATFORM_I386_PC = n # 关闭PC平台 CONFIG_PLATFORM_ARM_IMX6UL = y # 新增你的平台 ...其他所有平台 = n② 在平台设置区，添加IMX6UL的编译参数：
makefile
ifeq ($(CONFIG_PLATFORM_ARM_IMX6UL), y) EXTRA_CFLAGS += -DCONFIG_LITTLE_ENDIAN ARCH := arm CROSS_COMPILE := /你的交叉编译器路径/bin/arm-linux-gnueabihf- KSRC := /你的内核源码路径/linux-imx6ul MODULE_NAME := 8821cu endif参数说明：
表格
| 参数 | 含义 | 你的值 |
|---|---|---|
EXTRA_CFLAGS | 额外编译标志 | -DCONFIG_LITTLE_ENDIAN（ARM都是小端） |
ARCH | CPU架构 | arm |
CROSS_COMPILE | 交叉编译器前缀 | 你的工具链路径，如/opt/fsl-imx-x11/.../bin/arm-linux-gnueabihf- |
KSRC | 内核源码路径 | 你的IMX6UL内核源码绝对路径 |
MODULE_NAME | 生成的模块名 | 8821cu |
四、集成驱动到Linux内核树
表格
| 步骤 | 操作 |
|---|---|
| 1 | 复制驱动源码到drivers/net/wireless/rtl8821CU |
| 2 | 修改drivers/net/wireless/Makefile，添加obj-$(CONFIG_RTL8821CU) += rtl8821CU/ |
| 3 | 修改drivers/net/wireless/Kconfig，添加source "drivers/net/wireless/rtl8821CU/Kconfig" |
| 4 | 方法A：用make menuconfig配置内核，选择y或m。方法B：直接修改 defconfig 文件(步骤如下) |
| 5 | make编译内核 |
.config文件中增加"CONFIG_RTL8821CU=m"
配置内核，启用 RTL8821CU 驱动
bash
# 方法A：用 menuconfig 图形界面（推荐） make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig # 方法B：直接修改 defconfig 文件如果用 menuconfig：
进入
Device Drivers→Network device support→Wireless LAN找到
Realtek 8821C USB WiFi（或类似名称）按
M键设为模块（<M>），或按Y键编译进内核（<*>）按
Esc退出，保存配置
如果直接改 defconfig：
bash
# 找到你的 defconfig 文件 find arch/arm/configs -name "*imx*" # 编辑，添加配置 echo "CONFIG_RTL8821CU=m" >> arch/arm/configs/imx_v7_defconfig # 或者编译进内核 # echo "CONFIG_RTL8821CU=y" >> arch/arm/configs/imx_v7_defconfig3. 编译驱动
方式A：在驱动源码目录独立编译（推荐，调试方便）
bash
cd rtl8821CU/ make编译可能遇到的问题：
ERROR: modpost: module 8821cu uses symbol kernel_write from namespace VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver, but does not import it. ERROR: modpost: module 8821cu uses symbol kernel_read from namespace VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver, but does not import it. ERROR: modpost: module 8821cu uses symbol filp_open from namespace VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver, but does not import it. make[2]: *** [scripts/Makefile.modpost:168: /home/forlinx/work/OK3562-linux-source/kernel-5.10/drivers/net/wireless/rtl8821cu/Module.symvers] Error 1 make[2]: *** Deleting file '/home/forlinx/work/OK3562-linux-source/kernel-5.10/drivers/net/wireless/rtl8821cu/Module.symvers' make[1]: *** [Makefile:1856: modules] Error 2 make[1]: Leaving directory '/home/forlinx/work/OK3562-linux-source/kernel-5.10' make: *** [Makefile:2646: modules] Error 2这是 Linux 5.10 内核的symbol namespace机制导致的编译错误。内核 5.4+ 引入了 namespace 限制，驱动需要显式导入符号才能使用kernel_write、kernel_read、filp_open等 VFS 函数。
解决方法：在 8821cu 驱动的源码中，找到包含module_init或MODULE_LICENSE的文件（通常是core/rtw_cmd.c或os_dep/linux/os_intfs.c），添加以下导入声明：
c
// 在文件顶部（#include 之后）添加： #include <linux/module.h> MODULE_IMPORT_NS(VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver);具体步骤：
bash
cd /path/to/rtl8821cu # 找到使用这些函数的文件 grep -rn "kernel_write\|kernel_read\|filp_open" os_dep/ core/ --include="*.c" # 在这些文件的顶部（#include 之后）添加 MODULE_IMPORT_NS通常这些函数在os_dep/linux/os_intfs.c或core/rtw_mp.c中使用，找到对应文件后添加：
c
// 在 os_dep/linux/os_intfs.c 顶部添加： MODULE_IMPORT_NS(VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver);编译成功后生成：8821cu.ko
方式B：在内核树中编译
bash
cd <kernel_source> make modules五、目标板部署
1. 复制驱动
bash
# 宿主机执行 scp 8821cu.ko root@imx6ul:/lib/modules/3.14.38-6UL_ga/kernel/drivers/net/wireless/ scp rtl8821cu_fw.bin root@imx6ul:/lib/firmware/rtlwifi/ scp rtl8821cu_config.bin root@imx6ul:/lib/firmware/rtlwifi/2. 目标板加载
bash
# 在 IMX6UL 上执行 depmod -a modprobe 8821cu # 查看日志 dmesg | tail -20 # 确认接口 ifconfig -a # 或 ip link六、5G 频段配置
1. 设置国家码
bash
# 临时设置 iw reg set CN # 永久设置（写入配置文件） echo 'REGDOMAIN=CN' > /etc/default/crda2. 验证 5G 支持
bash
# 查看支持的频率 iwlist wlan0 frequency # 扫描 5G AP iw dev wlan0 scan | grep "SSID\|freq: 5"七、可能遇到的硬件问题
表格
| 现象 | 排查 |
|---|---|
插入模块后lsusb无变化 | 检查 USB 焊接、供电（需 3.3V 或 5V）、模块是否损坏 |
lsusb显示0bda:c811但加载驱动失败 | 固件缺失，检查/lib/firmware/ |
能识别但ifconfig无 wlan0 | 检查cfg80211和mac80211是否编译进内核 |
| 只能连 2.4G，看不到 5G | 国家码未设置，或 regdb 数据库缺失 |
| 5G 信号弱 | 检查模块天线接口是否接好，5G 衰减大需要好的天线 |
八、快速验证流程
bash
# 1. 硬件识别 lsusb | grep -i "0bda:c811\|Realtek" # 2. 驱动加载 lsmod | grep 8821cu dmesg | grep 8821cu #或者 insmod /lib/modules/3.14.38-6UL_ga+ge4944a5/kernel/drivers/net/wireless/realtek/rtl8821CU/8821cu.ko # 3. 网络接口 # 查看驱动是否加载 lsmod | grep 8821cu # 查看无线接口是否出现 ip link show wlan0 #启用无线接口 ifconfig wlan0 up # 4. 5G 频段支持 iw phy phy0 info | grep -A 10 "Band 2" # 5G 是 Band 2 # 5. 扫描测试 iw dev wlan0 scan | grep SSID | head -10 # 6.创建 wpa_supplicant 配置文件 cat > /etc/wpa_supplicant.conf << 'EOF' network={ ssid="你的WiFi名称" psk="你的WiFi密码" } EOF # 7.连接 WiFi # 后台运行 wpa_supplicant wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf 获取 IP 地址 udhcpc -i wlan0 # 8.确认连接成功 # 查看 IP 地址 ifconfig wlan0 # 查看连接信息 iwconfig wlan0 # 测试网络 ping -c 4 8.8.8.8到这一步就表明连接成功了！