WiFi/蓝牙驱动

本文档介绍 RK3588 通过 SDIO / PCIe 连接外接 WiFi / 蓝牙模块（Broadcom、Realtek、Qualcomm 等）的驱动配置和用户态使用。

适用范围： RK3588 Linux 6.1 Debian 12 / Ubuntu 22.04 系统，C-3588LQ V1.0 + SHIMETAPI-M5-R2A V1.0 底板。 状态： 出厂镜像本机未配 WiFi / 蓝牙硬件模块，文档按「已焊接模块」为预期状态编写；如启用后出错，请优先检查硬件连接。

1. 概念基础

1.1 RK3588 没有内置 WiFi / BT

RK3588 芯片里没有 WiFi / 蓝牙控制器，必须外接模块，接口多为 SDIO（SD 卡接口的变体，WiFi 模块常用）或 PCIe。常见模块：

模块	接口	协议	驱动
AP6275S	SDIO	WiFi 5 + BT 5.0	bcmdhd / brcmfmac
RTL8852BE	PCIe	WiFi 6 + BT 5.2	rtw89
QCA6390 / AX210	PCIe	WiFi 6E + BT 5.2	ath11k / iwlwifi

1.2 模块典型参数

项	说明
WiFi 标准	802.11 a/b/g/n/ac/ax
频段	2.4 GHz + 5 GHz（部分 6 GHz）
安全	WPA3-SAE / WPA2-PSK
蓝牙	BT 5.0+ / BLE
最高速率	WiFi 6 ~2.4 Gbps，6E ~5.4 Gbps

2. 准备工作

2.1 硬件清单

组件	型号/规格	数量	备注
主控板	C-3588LQ 核心板 + SHIMETAPI-M5-R2A 底板	1
WiFi/BT 模块	AP6275S / RTL8852BE / QCA6390	1	SDIO 或 PCIe
天线	2.4G + 5G	1~2	增益 2-5 dBi

2.2 引脚（以 SDIO 模块为例）

主控板	模块引脚	功能
SDIO0_CLK	CLK	SDIO 时钟
SDIO0_CMD	CMD	命令
SDIO0_D0~D3	D0~D3	数据线
GPIO	WL_REG_ON	模块使能
GPIO	WL_HOST_WAKE	唤醒主机
GPIO (UART)	BT_UART / BT_RST	蓝牙 UART 控制
3.3V	VCC	电源
GND	GND	共地

PCIe 接口模块需接 PCIe 控制器引脚（参考 ch16 PCIe 驱动）。

3. 软件准备

3.1 内核配置

WiFi 驱动分两层：cfg80211 / MAC80211 是内核的无线框架，所有 WiFi 驱动的公共底座；在此之上按模块厂商打开对应驱动（选其一即可）：

CONFIG_CFG80211=y
CONFIG_MAC80211=y
CONFIG_WLAN=y
# 常见驱动模块（按模块厂商选其一）
CONFIG_BRCMUTIL=m
CONFIG_BRCMFMAC=m                      /* Broadcom（AP6275S 等） */
CONFIG_CFG80211=m
CONFIG_BT=m
CONFIG_BT_HCIUART=m
CONFIG_BT_BCMCFG=m                    /* Broadcom BT */
CONFIG_RTW89=m                        /* Realtek PCIe */
CONFIG_ATH11K=m                       /* Qualcomm */

3.2 蓝牙 HCI 绑定

蓝牙芯片一般走一根 UART 连到 SoC，两边按 HCI（Host Controller Interface，主机与蓝牙芯片之间的通信协议）对话。内核把 UART 上的蓝牙芯片接进来，需要用户空间的 hciattach 工具帮忙：

# 查看蓝牙 UART 设备
ls /dev/ttyS* /dev/ttyUSB* | grep -i bt

# RK 提供的 helper（bcmdhd 模块专用）
hciattach -s 115200 /dev/ttyS8 bcm43xx 3000000

真机 UART 编号以底板原理图为准。

3.3 设备树

SDIO 模块还要在设备树里声明上电时序（pwrseq，即 power sequence，控制模块按什么顺序上电、复位）：

&sdio0 {
    status = "okay";
    /* WiFi 模块专用 GPIO */
    wifi_pwrseq: wifi-pwrseq {
        compatible = "mmc-pwrseq-simple";
        clocks = <&wifi_32k>;
        clock-names = "ext_clock";
        pinctrl-names = "default";
        pinctrl-0 = <&wifi_en>;
        reset-gpios = <&gpio3 RK_PA0 GPIO_ACTIVE_LOW>;
    };
    mmc3: mmc@fe310000 {
        /* 注：依实际 RK 设备树绑定 */
    };
    mmc3_pwrseq {
        pinctrl-0 = <&wifi_en>;
    };
};

4. 本机 WiFi / BT 模块状态

出厂镜像下逐项确认，本机未焊模块，输出也如实记录，正好说明每种缺失长什么样。

4.1 检查模块文件

ls /lib/modules/$(uname -r)/*bcmdhd* 2>&1

实机输出：

/lib/modules/bcmdhd.ko
/lib/modules/bcmdhd_pcie.ko

本机有 Broadcom bcmdhd 系列驱动（SDIO + PCIe 两种），但硬件模块没装的话，这些驱动暂时派不上用场。

4.2 检查当前是否有硬件模块

ip link show
ls /sys/class/net/

本机没有任何 wlanX 接口，即模块未焊接或未识别；装上硬件模块后会自动创建。

4.3 检查蓝牙

hciconfig -a 2>&1 | head

没有 BT 节点输出，同样说明蓝牙硬件未配。

5. 用户态使用（假设 WiFi 模块已装载）

5.1 NetworkManager 连接

NetworkManager 是 Debian 默认的网络管理服务，nmcli 是它的命令行工具：

nmcli radio wifi on
nmcli dev wifi list
nmcli dev wifi connect "MyHomeWiFi" password "your_password"

详见快速上手 ch02 网络配置与 SSH。

5.2 扫描 WiFi

iw dev
# 输出：phy#X  Interface wlanX ...

iw dev wlan0 scan | grep SSID

5.3 手动连接（不带 NM）

不用 NetworkManager 时，可以用 wpa_supplicant（WiFi 加密认证的标准工具）手动连接：

wpa_passphrase "MyHomeWiFi" "your_password" > /etc/wpa_supplicant.conf
wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf
dhclient wlan0

5.4 蓝牙启动

systemctl start bluetooth
bluetoothctl

进入 bluetoothctl 后按下面的顺序操作，从开启、扫描到配对连接：

[bluetooth] power on
[bluetooth] scan on
[NEW] XX:XX:XX:XX:XX:XX MyDevice
[bluetooth] pair XX:XX:XX:XX:XX:XX
[bluetooth] connect XX:XX:XX:XX:XX:XX

6. 设备树微调（PC 端）

按所用模块的数据手册修改：

&sdio0 {
    status = "okay";

    /* 选配：把 WiFi 模块挂在 sdio0 上 */
    mmc@fe310000 {
        status = "okay";
        #address-cells = <1>;
        #size-cells = <0>;

        brcmf: wifi@1 {
            reg = <1>;            /* SDIO function 1 */
            compatible = "brcm,bcm4329-fmac";
            /* （具体 compatible 应按模块厂商实际值填） */
        };
    };
};

电脑端 重新编译烧录：

./build.sh kernel
./mkfirmware.sh

烧录重启后回到 4.2，能看到 wlanX 接口就说明模块被识别了。

7. 代码解读

7.1 驱动注册（以 bcmdhd 为例）

bcmdhd 驱动的注册形式：

// drivers/net/wireless/broadcom/bcmdhd/dhd_linux.c（简化）

static struct platform_driver bcmdhd_driver = {
    .probe  = bcmdhd_probe,
    .remove = bcmdhd_remove,
    .driver = {
        .name = "bcmdhd",
    },
};

7.2 WiFi 连接调用链

应用发起连接后，请求一路传到 WiFi 芯片固件：

应用（NM / iw / 自定义 socket）
  → cfg80211 connect
    → brcmfmac_connect()
      → bcmdhd_bus_txdata()              /* Broadcom dongle host driver */
        → SDIO / PCIe DMA → WiFi chip 固件
          → 802.11 帧收发

8. 故障排除

8.1 无 wlanX 接口

dmesg | grep -iE 'wifi|wlan|bcmdhd|sdio'

可能原因：

模块未焊接
SDIO0/PCIe 控制器未 enable
pinctrl 未配置 WL_REG_ON / WL_HOST_WAKE
模块芯片固件路径不对（多数需要 brcmfmac firmware blobs）

8.2 能识别但扫不到网络

检查天线连接
检查国家域：iw reg set CN
确认固件已加载：dmesg | grep firmware

8.3 蓝牙 / UART 问题

dmesg | grep -iE 'bluetooth|hci_uart'

常见：

HCI UART 速度不匹配（典型 3000000 baud）
hciattach 未运行
BT 模块 RTS/CTS 流控未配置