OpenHarmony 蓝牙 (BT) RTL8822cs 适配

本文档基于 OpenHarmony 蓝牙模块的实现，结合本项目的底层驱动（如 libbt_vendor），从下至上分析了蓝牙协议栈的调用链，涵盖了初始化流程、数据交互机制以及关键接口。

1. 整体架构层级与代码模块分布

在 OpenHarmony (OHOS) 中，蓝牙从应用层到底层芯片的完整交互链路被拆分成了多个独立运行的进程与动态库。结合我们在 RTL8822CS 上的适配和排查经验，其真实的架构与模块对应关系如下：
物理层与内核
Vendor层 libbt_vendor.z.so
HDI层
框架层
系统启动
系统启动时赋予服务读写权限
IPC
HDI Binder 跨进程调用
dlopen 动态调用
H5协议读写数据包
echo 0/1 控制电源
UART / CTS / RTS 引脚
控制 EN / WAKE 管脚
系统属性与权限控制 init.rk3568.cfg
蓝牙框架服务 bluetooth_service PID: 1634
蓝牙设置应用 Settings/UI
HDI 服务层 hci_interface_service
Vendor 初始化与配置 bt_vendor_rtk.c
串口协议与硬件流控 hardware_uart.c
电源与物理节点控制 upio.c
物理串口设备节点 /dev/ttyS1
物理电源/射频控制节点 /sys/class/rfkill/rfkill0/state
Realtek RTL8822CS 蓝牙芯片

各核心模块的作用：

内核设备树 (DTS): 依据硬件原理图配置芯片与 SOC 的物理连接，包括用于传输数据的 UART 通道（开启 CTS/RTS 硬件流控管脚复用），以及用于电源控制的 RFKILL GPIO（Host_Wake, Wake_Host 等）。
初始化脚本 (init.rk3568.cfg) : OHOS 在开机时由 init 进程解析，它负责注入蓝牙的默认设备名称 (const.bluetooth.name)，并最关键地开放底层串口和电源节点的所有权给 bluetooth 用户。
框架服务 (bluetooth_service): 核心的系统服务，内部维护着所有的蓝牙协议栈（GAP, GATT, A2DP等）。它启动时必须能成功获取 HDI 的代理并初始化，否则会不断重启（SA 1130 Removed）。
Vendor 动态库 (libbt_vendor.z.so) :
- bt_vendor_rtk.c : 暴露给 HDI 层的标准化入口，内部负责读取配置文件（如 rtkbt.conf），决定采用 H4 还是 H5 串口协议，并设置结构体的初始参数。
- hardware_uart.c : 处理芯片上电后的波特率同步（如 115200 提速到 1500000），应用硬件流控，以及下载 RTL8822CS 专属的 Patch 固件。
- upio.c : 处理物理电源，它的任务就是往 /sys/class/rfkill/rfkill0/state 写入 1（上电）或 0（断电）。一旦这里的判断逻辑异常（如误判为模拟器），整个芯片就变成了死物。

2. 内核设备树 (DTS) 与驱动配置 (基于原理图)

任何上层的协议都建立在坚实的物理连接之上。根据 RTL8822CS 硬件原理图，我们对 OHOS 内核的设备树 (kernel_dts) 进行了如下核心配置：

2.1 蓝牙 UART 接口与硬件流控

根据原理图，RTL8822CS 的蓝牙部分通过 UART1（或其它指定的 UART 节点）与 RK3568 通信。由于蓝牙在传输文件、A2DP 音频等场景下数据吞吐量极大，必须开启硬件流控 (CTS/RTS) ，否则会导致严重的缓冲区溢出与丢包。

在 DTS 中开启对应的 UART 节点并复用流控引脚：

dts 复制代码

&uart1 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&uart1m0_xfer &uart1m0_ctsn &uart1m0_rtsn>; // 必须包含 ctsn 和 rtsn
};

注意点 ：如果 DTS 中没有配置 uart1m0_ctsn 和 uart1m0_rtsn，即使在 libbt_vendor 中开启了硬件流控，底层物理引脚也不会生效，最终表现仍然是传输大文件断开连接。

2.2 蓝牙电源与休眠唤醒控制 (rfkill)

蓝牙芯片的使能 (BT_EN) 以及主从机双向唤醒引脚 (Host_Wake_BT, BT_Wake_Host) 必须在 DTS 的 wireless-bluetooth 节点下配置正确，从而在系统中注册为 /sys/class/rfkill/rfkill0 设备。

dts 复制代码

    wireless-bluetooth {
        compatible = "bluetooth-platdata";
        clocks = <&rk809 1>;
        clock-names = "ext_clock";
        uart_rts_gpios = <&gpio2 RK_PB5 GPIO_ACTIVE_LOW>;
        pinctrl-names = "default", "rts_gpio";
        pinctrl-0 = <&uart1m0_rtsn>;
        pinctrl-1 = <&uart1_gpios>;
        BT,reset_gpio    = <&gpio2 RK_PB7 GPIO_ACTIVE_HIGH>; // BT_EN 引脚
        BT,wake_host_irq = <&gpio2 RK_PC0 GPIO_ACTIVE_HIGH>; // BT 唤醒 Host 的中断
        status = "okay";
    };

作用：内核解析该节点后，生成 rfkill0/state 节点，libbt_vendor 中的 upio.c 正是通过向此节点写入 1 来拉高 BT,reset_gpio 给芯片上电。

3. 关键组件与接口分析

A. 厂商驱动层 (Vendor Lib)

代码位置 : device/board/kylin/yd_3568_EMR88/bt/src (如 bt_vendor_rtk.c, hardware_uart.c 等)
核心职责: 屏蔽不同厂家芯片的差异，执行特定的上电、复位、波特率同步、H5协议初始化以及固件(Patch)下载。
核心接口 : 必须导出 BLUETOOTH_VENDOR_LIB_INTERFACE 符号，其类型为 bt_vendor_interface_t：
- init: 传入 HDI 层提供的回调（如内存分配、数据发送回调）。
- op: 处理各种操作码（BT_OP_POWER_ON, BT_OP_HCI_CHANNEL_OPEN, BT_OP_INIT 等）。
- cleanup: 释放资源。

B. 蓝牙 HDI 服务层 (HCI 层)

代码位置 : drivers/peripheral/bluetooth/hci/hdi_service
核心职责 : 作为框架与驱动的桥梁。它负责通过 dlopen 加载 vendor 库，建立 HCI 通道，并启动独立线程从串口读取 HCI 数据包。
核心接口 :
- VendorInterface::Initialize: 负责 dlopen libbt_vendor.z.so，并依序调用 vendor 库的 init 和 op (POWER_ON, INIT)。
- 向框架层暴露 HDI 接口（如 Init, SendHciPacket, Close）。

C. 蓝牙框架服务层 (bluetooth_service)

代码位置 : foundation/communication/bluetooth_service
核心职责: 维护蓝牙的业务逻辑（GAP, GATT, A2DP 等），管理协议栈状态机。
核心交互 :
- 通过 HDF 框架发现并绑定 hci_interface_service。
- 调用 HDI 接口发送指令。
- 实现 IBluetoothHciCallback，接收底层上报的 HCI 事件和数据，推入上层协议栈解析。

3. 核心调用链梳理

3.1 初始化调用链 (自上而下)

框架层启动 : 系统拉起 bluetooth_service，尝试获取底层 HCI 服务代理（Proxy）。
HDI 代理调用 : 框架层调用 HDI 接口的 Init() 方法。
加载 Vendor 库 : HDI 层服务（Stub）执行初始化，调用 dlopen("libbt_vendor.z.so", RTLD_NOW) 加载厂商库，并解析 BLUETOOTH_VENDOR_LIB_INTERFACE 符号。
底层硬件初始化 :
- HDI 层调用 vendorInterface_->init(...) 注册回调。
- HDI 层调用 vendorInterface_->op(BT_OP_POWER_ON, ...) 通知厂商库给芯片上电。
- HDI 层调用 vendorInterface_->op(BT_OP_HCI_CHANNEL_OPEN, ...)。此时 vendor 库内部（如 userial_vendor_open）会打开对应的串口节点（如 /dev/ttyS1）。
- HDI 层调用 vendorInterface_->op(BT_OP_INIT, ...)。此时 vendor 库内部（如 hw_config_start）开始执行 H5 握手、识别芯片版本、下载固件 Patch 等极其关键的初始化步骤。
通道建立完成: 初始化成功后，HDI 层启动 Watcher 线程，开始监听串口的读写事件，蓝牙模块正式可用。

3.2 数据收发调用链 (双向)

下发命令/数据 (TX) :
1. 业务层触发蓝牙操作（如扫描、配对）。
2. 框架层组装 HCI Command 包，调用 HDI 代理的 SendHciPacket。
3. HDI 层接收到数据，直接写入已打开的串口 FD（UART/H4/H5 封装）。
接收事件/数据 (RX) :
1. 蓝牙芯片通过串口产生中断，数据到达 CPU。
2. HDI 层的 Watcher 线程从串口读取裸数据流。
3. 根据 H4/H5 协议，将数据流组装成完整的 HCI Event 或 ACL 数据包。
4. HDI 层调用预先注册的 OnEventReceive 回调，将数据通过 Binder 跨进程传递给 bluetooth_service。
5. 框架层协议栈解析数据并向上分发给具体的 Profile 处理。

4. 常见问题定位点

基于此调用链，如果蓝牙无法开启，常见排查点如下：

框架层报错 (如 HciInterfaceStubInit_ failed) : 通常是因为 HDI 层加载 libbt_vendor.z.so 失败，或者底层节点（/dev/ttyS1）权限被拒绝。
Vendor 层报错 : 串口波特率不匹配、固件文件缺失 (/vendor/etc/firmware/)、芯片休眠唤醒管脚电平异常。

5. OHOS BT蓝牙适配步骤与遇到的问题解决方法

在将 Realtek RTL8822CS 蓝牙芯片适配到 OpenHarmony 系统的过程中，经常会遇到设备名称异常、开关失效以及大文件传输断开等问题。以下是我们实际排查与修复过程中的核心步骤和避坑总结。

5.1 蓝牙设备名称显示为 "BluetoothDevice"

现象：系统启动后，或者其它设备搜索本机时，蓝牙名称显示为默认的 "BluetoothDevice"，而非产品定制名称（如 "鸿麒麟"）。
原因：OHOS 的蓝牙服务（bluetooth_service）在启动时会去读取系统的特定属性来设置默认名称。如果仅仅配置了 const.product.name 并不足够。
解决方案 ：

必须在系统的初始化脚本中（例如 init.rk3568.cfg）显式注入以下属性：

json 复制代码

"setprop const.bluetooth.name namex",
"setprop ro.bluetooth.default_name namex"

5.2 蓝牙界面开关失效（点击无反应，需手动 echo）

现象：在设置 UI 界面点击蓝牙开关，开关立刻回弹，系统日志报 bluetooth_service 重启或 bluetooth host is nullptr，导致 SA(1130) 不断崩溃。但如果在串口终端通过 echo 1 > /sys/class/rfkill/rfkill0/state 手动上电，蓝牙又能勉强工作。
排查与原因：

节点权限与属主错误 ：bluetooth_service 服务运行在 bluetooth 用户组下，而 /sys/class/rfkill/rfkill0/state 及串口节点 /dev/ttyS1 的所有者被错误地配置为了 blue_host。这导致服务在下发电源指令时遇到了 Permission denied。
Vendor 库中的"模拟器假动作"漏洞 ：在 Realtek 提供的 libbt_vendor 库源码（如 upio.c）中，存在一个 is_emulator_context() 判定函数，该函数被硬编码返回了 1。这导致 vendor 库自认为是运行在模拟器环境下，从而完全跳过 了对 rfkill 物理节点的写操作。
解决方案：

修改 init.rk3568.cfg，修正节点的权限和属主：

json 复制代码

"chmod 777 /sys/class/rfkill/rfkill0/state",
"chown bluetooth bluetooth /sys/class/rfkill/rfkill0/state",
"chmod 777 /dev/ttyS1",
"chown bluetooth bluetooth /dev/ttyS1"

修改 Vendor 库代码 (device/board/.../bt/src/upio.c)，修复 is_emulator_context 让其返回 0。同时增强 upio_set_bluetooth_power 函数的鲁棒性，在打开节点失败时重置 rfkill_id。

5.3 蓝牙大文件传输失败、容易断开连接

现象：蓝牙可以正常扫描和配对，但在传输文件（如通过 OPP/OBEX 协议）或者建立需要高吞吐量的连接时，极易发生传输失败、进度卡死或底层连接直接断开，且连接状态不显示为"已连接"。
原因：

此类问题通常是硬件流控 (Hardware Flow Control, CTS/RTS) 未正常开启导致的。RTL8822CS 使用 UART 接口进行 HCI 数据传输。当传输大文件时，主机端 (Host) 吐数据的速度极快，如果此时硬件流控关闭，蓝牙芯片来不及处理且无法通知主机暂停发送，就会发生串口缓冲区溢出和严重的丢包，从而导致协议栈状态机错乱和连接断开。
解决方案：

串口配置结构体修改 ：在 bt_vendor_rtk.c 中，将串口初始化结构体的流控选项开启：

c 复制代码

static const tUSERIAL_CFG userial_H5_cfg = {(USERIAL_DATABITS_8 | USERIAL_PARITY_EVEN | USERIAL_STOPBITS_1),
                                            USERIAL_BAUD_115200, USERIAL_HW_FLOW_CTRL_ON}; // 原为 OFF

固件下载状态机修改 ：在 hardware_uart.c 的状态机 HW_CFG_SET_UART_HW_FLOW_CONTROL 分支中，确保真正调用底层的流控开启接口：
c 复制代码
```
if (hw_cfg_cb.hw_flow_cntrl & 0x01) {
    userial_vendor_set_hw_fctrl(1); // 原本写死为 0
}
```

5.4 其他注意事项

无效的串口节点配置 ：在修改 init 脚本时，务必对照 dmesg 日志（如 ls -l /dev/tty*），移除不存在的串口节点配置（例如本板子中不存在 /dev/ttyAMA2，强行 chmod 会引发 Init 服务报错甚至阻塞启动流程）。
清理无效的服务 ：确保底层 libbt_vendor 初始化成功，否则 bluetooth_service 初始化底层硬件失败，会引起上层 SA 1130 频繁启停。这可通过 hilog 抓取 bt_vendor、upio 和 bluetooth_service 关键字来印证。