针对环境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. 修改 Makefilebashcd rtl8821cu vim Makefile针对IMX6UL你需要这样做① 在平台选择区添加IMX6UL的配置如果没有现成的ARM平台可用makefileCONFIG_PLATFORM_I386_PC n # 关闭PC平台 CONFIG_PLATFORM_ARM_IMX6UL y # 新增你的平台 ...其他所有平台 n② 在平台设置区添加IMX6UL的编译参数makefileifeq ($(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_ENDIANARM都是小端ARCHCPU架构armCROSS_COMPILE交叉编译器前缀你的工具链路径如/opt/fsl-imx-x11/.../bin/arm-linux-gnueabihf-KSRC内核源码路径你的IMX6UL内核源码绝对路径MODULE_NAME生成的模块名8821cu四、集成驱动到Linux内核树表格步骤操作1复制驱动源码到drivers/net/wireless/rtl8821CU2修改drivers/net/wireless/Makefile添加obj-$(CONFIG_RTL8821CU) rtl8821CU/3修改drivers/net/wireless/Kconfig添加source drivers/net/wireless/rtl8821CU/Kconfig4方法A用make menuconfig配置内核选择y或m。方法B直接修改 defconfig 文件(步骤如下)5make编译内核.config文件中增加CONFIG_RTL8821CUm配置内核启用 RTL8821CU 驱动bash# 方法A用 menuconfig 图形界面推荐 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- menuconfig # 方法B直接修改 defconfig 文件如果用 menuconfig进入Device Drivers→Network device support→Wireless LAN找到Realtek 8821C USB WiFi或类似名称按M键设为模块M或按Y键编译进内核*按Esc退出保存配置如果直接改 defconfigbash# 找到你的 defconfig 文件 find arch/arm/configs -name *imx* # 编辑添加配置 echo CONFIG_RTL8821CUm arch/arm/configs/imx_v7_defconfig # 或者编译进内核 # echo CONFIG_RTL8821CUy arch/arm/configs/imx_v7_defconfig3. 编译驱动方式A在驱动源码目录独立编译推荐调试方便bashcd 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);具体步骤bashcd /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在内核树中编译bashcd kernel_source make modules五、目标板部署1. 复制驱动bash# 宿主机执行 scp 8821cu.ko rootimx6ul:/lib/modules/3.14.38-6UL_ga/kernel/drivers/net/wireless/ scp rtl8821cu_fw.bin rootimx6ul:/lib/firmware/rtlwifi/ scp rtl8821cu_config.bin rootimx6ul:/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 REGDOMAINCN /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_gage4944a5/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到这一步就表明连接成功了
针对环境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. 修改 Makefilebashcd rtl8821cu vim Makefile针对IMX6UL你需要这样做① 在平台选择区添加IMX6UL的配置如果没有现成的ARM平台可用makefileCONFIG_PLATFORM_I386_PC n # 关闭PC平台 CONFIG_PLATFORM_ARM_IMX6UL y # 新增你的平台 ...其他所有平台 n② 在平台设置区添加IMX6UL的编译参数makefileifeq ($(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_ENDIANARM都是小端ARCHCPU架构armCROSS_COMPILE交叉编译器前缀你的工具链路径如/opt/fsl-imx-x11/.../bin/arm-linux-gnueabihf-KSRC内核源码路径你的IMX6UL内核源码绝对路径MODULE_NAME生成的模块名8821cu四、集成驱动到Linux内核树表格步骤操作1复制驱动源码到drivers/net/wireless/rtl8821CU2修改drivers/net/wireless/Makefile添加obj-$(CONFIG_RTL8821CU) rtl8821CU/3修改drivers/net/wireless/Kconfig添加source drivers/net/wireless/rtl8821CU/Kconfig4方法A用make menuconfig配置内核选择y或m。方法B直接修改 defconfig 文件(步骤如下)5make编译内核.config文件中增加CONFIG_RTL8821CUm配置内核启用 RTL8821CU 驱动bash# 方法A用 menuconfig 图形界面推荐 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- menuconfig # 方法B直接修改 defconfig 文件如果用 menuconfig进入Device Drivers→Network device support→Wireless LAN找到Realtek 8821C USB WiFi或类似名称按M键设为模块M或按Y键编译进内核*按Esc退出保存配置如果直接改 defconfigbash# 找到你的 defconfig 文件 find arch/arm/configs -name *imx* # 编辑添加配置 echo CONFIG_RTL8821CUm arch/arm/configs/imx_v7_defconfig # 或者编译进内核 # echo CONFIG_RTL8821CUy arch/arm/configs/imx_v7_defconfig3. 编译驱动方式A在驱动源码目录独立编译推荐调试方便bashcd 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);具体步骤bashcd /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在内核树中编译bashcd kernel_source make modules五、目标板部署1. 复制驱动bash# 宿主机执行 scp 8821cu.ko rootimx6ul:/lib/modules/3.14.38-6UL_ga/kernel/drivers/net/wireless/ scp rtl8821cu_fw.bin rootimx6ul:/lib/firmware/rtlwifi/ scp rtl8821cu_config.bin rootimx6ul:/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 REGDOMAINCN /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_gage4944a5/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到这一步就表明连接成功了
)
