Linux蓝牙之核外协议栈BlueZ架构分析

工程名称: BlueZ — 官方 Linux Bluetooth 协议栈
代码仓库: git://git.kernel.org/pub/scm/bluetooth/bluez.git
协议: GPL-2.0-or-later (核心) / LGPL-2.1-or-later (lib)
代码规模: ~525,695 行 C 代码, 803 个 C 源文件
核心维护者: Marcel Holtmann, Johan Hedberg, Luiz Augusto von Dentz

本报告基于 BlueZ(v5.86) git commit 0fdf34b17

目录

1. 1. 项目概述
2. 2. 功能全景
3. 3. 架构总览
4. 4. 核心模块详解
5. 5. D-Bus 接口体系
6. 6. 核心流程分析
7. 7. 关键子系统
8. 8. 工具生态
9. 9. 配置与存储
10. 10. 体系结构图

1. 项目概述

BlueZ 是 Linux 内核官方 Bluetooth 子系统的用户态实现，提供完整的蓝牙协议栈支持，涵盖：

• • 经典蓝牙 (BR/EDR): 传统蓝牙 2.0/2.1/3.0
• • 低功耗蓝牙 (BLE): 蓝牙 4.0/4.1/4.2/5.0/5.1/5.2/5.3
• • 双模 (Dual Mode): 同时支持 BR/EDR 和 LE

BlueZ 通过 D-Bus 系统总线向用户态应用提供标准化的蓝牙服务接口，是 Linux 桌面和嵌入式系统中蓝牙功能的事实标准实现。

2. 功能全景

2.1 核心蓝牙功能

2.2 音频/媒体支持 (A2DP/AVRCP/HFP)

2.3 输入设备 (HID)

2.4 网络服务 (PAN)

2.5 LE Audio (下一代)

2.6 OBEX/拨号/信息

2.7 Mesh 网络

3. 架构总览

3.1 分层架构

┌─────────────────────────────────────────────────────────────────┐
│                    用户态应用 (Applications)                      │
│   bluetoothctl         bluetooth-player      btgatt-client ...  │
└──────────────────────────┬──────────────────────────────────────┘
                           │ D-Bus System Bus (org.bluez)
┌──────────────────────────▼──────────────────────────────────────┐
│                        bluetoothd (守护进程)                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐  │
│  │  Adapter  │ │  Device  │ │ Profile  │ │  GATT Manager     │  │
│  │  Manager  │ │  Manager │ │ Manager  │ │  Client/Server    │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬──────────┘  │
│       │            │            │                 │             │
│  ┌────▼────────────▼────────────▼─────────────────▼──────────┐ │
│  │               Plugin 系统 (profiles/*)                      │ │
│  │  A2DP│AVRCP│HFP│HID│GATT Profiles│PAN│BAP│CSIP│TMAP...     │ │
│  └───────────────────────────┬────────────────────────────────┘ │
│                              │                                   │
│  ┌───────────────────────────▼────────────────────────────────┐ │
│  │           共享库 (src/shared/ + ell/)                        │ │
│  │  GATT DB │ MGMT │ HCI │ IO │ Crypto │ Queue │ BAP ...     │ │
│  └───────────────────────────┬────────────────────────────────┘ │
└──────────────────────────────┼──────────────────────────────────┘
                               │  mgmt socket / HCI sockets
┌──────────────────────────────▼──────────────────────────────────┐
│                   Linux Kernel Bluetooth 子系统                   │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐   │
│  │ HCI    │  │ L2CAP  │  │ SCO    │  │ RFCOMM │  │ BNEP   │   │
│  │ Core   │  │        │  │        │  │        │  │        │   │
│  └────────┘  └────────┘  └────────┘  └────────┘  └────────┘   │
├──────────────────────────────┬──────────────────────────────────┤
│                   Bluetooth 控制器 (USB/UART/PCI)                │
└─────────────────────────────────────────────────────────────────┘

3.2 关键架构特性

1. 1. D-Bus 驱动架构: 所有核心功能通过 D-Bus 系统总线暴露，应用与 bluetoothd 解耦
2. 2. Plugin 插件体系: 蓝牙 Profile 作为插件动态加载 (profiles/*/)
3. 3. 双循环支持: 支持 GLib 主循环和 ELL 主循环两种事件模型
4. 4. 共享组件: 公共基础库 src/shared/ 支持 GLib 和 ELL 两套后端
5. 5. MGMT 协议: 通过 mgmt socket 与内核通信，取代直接操作 HCI

4. 核心模块详解

4.1 bluetoothd 守护进程 (src/)

BlueZ 核心守护进程，处理所有蓝牙操作。

入口: src/main.c:1481 — main()` 函数

启动流程:

main()
├── init_defaults()          — 初始化全局配置默认值
├── parse_config(config)     — 解析 /etc/bluetooth/main.conf
├── connect_dbus()           — 连接到 system D-Bus
├── adapter_init()           — 初始化适配器管理
│   ├── 创建 mgmt socket
│   └── 枚举已连接的蓝牙适配器
├── btd_device_init()        — 设备管理器初始化
├── btd_agent_init()         — Agent 交互层初始化
├── btd_profile_init()       — Profile 管理器初始化
├── start_sdp_server()       — SDP 服务 (BR/EDR)
├── plugin_init()            — 加载所有内置及外部插件
├── rfkill_init()            — RFKILL 监控
├── mainloop_run_with_signal() — 进入 GLib 主循环
└── shutdown sequence        — 按相反顺序清理

核心源文件:

4.2 适配器管理 (Adapter Manager)

src/adapter.c — 12,000+ 行，最大源文件之一。

核心职责：

• • 枚举所有蓝牙适配器 (hci0, hci1, ...)
• • 通过 mgmt socket 与内核蓝牙子系统通信
• • 管理配对、发现、扫描参数
• • 控制电源、可发现性、可连接性
• • 实验性功能注册 (Debug, BQR, RPA Resolution, LE Simultaneous Roles, ISO Socket, Codec Offload)

mgmt 命令接口:

// 与内核通信的核心机制 — mgmt socket
staticstruct mgmt *mgmt_primary = NULL;

// 重要操作:
MGMT_OP_READ_INDEX_LIST        — 枚举适配器
MGMT_OP_READ_INFO              — 读取适配器信息
MGMT_OP_SET_POWERED            — 电源控制
MGMT_OP_SET_DISCOVERABLE       — 可发现模式
MGMT_OP_SET_CONNECTABLE        — 可连接模式
MGMT_OP_START_DISCOVERY        — 开始发现
MGMT_OP_STOP_DISCOVERY         — 停止发现
MGMT_OP_PAIR_DEVICE            — 配对
MGMT_OP_CANCEL_PAIR_DEVICE     — 取消配对
MGMT_OP_UNPAIR_DEVICE          — 解除绑定

4.3 设备管理 (Device Manager)

src/device.c — 约 5,800 行。

数据模型:

btd_device
├── bdaddr / bdaddr_type          — 地址
├── adapter                       — 所属适配器
├── name                          — 设备名称
├── class                         — 设备类
├── appearance                    — LE 外观
├── paired / bonded               — 配对状态
├── gatt_client / gatt_server     — GATT 通道
├── services / profiles           — 已发现的服务
├── keys (LTK/IRK/CSRK)          — 安全密钥
├── connection state              — 连接状态
└── uuids                         — 支持的 UUID 列表

5. D-Bus 接口体系

BlueZ 通过 D-Bus 系统总线 org.bluez 暴露所有功能。

5.1 Core Interfaces (在 bluetoothd 中实现)

5.2 Profile-Specific Interfaces (插件暴露)

6. 核心流程分析

6.1 设备发现流程

用户态应用                    bluetoothd                        内核
    │                           │                                │
    │  StartDiscovery()         │                                │
    │ ───────────────────────►  │  MGMT_OP_START_DISCOVERY      │
    │                           │ ──────────────────────────────►│
    │                           │                                │
    │                           │  ◄─── MGMT_EV_DEVICE_FOUND ───┤
    │                           │     (每个发现到的设备)          │
    │                           │                                │
    │  PropertiesChanged        │                                │
    │ ◄───────────────────────  │                                │
    │  (Device1 Found / RSSI)   │                                │
    │                           │                                │
    │  StopDiscovery()          │                                │
    │ ───────────────────────►  │  MGMT_OP_STOP_DISCOVERY       │
    │                           │ ──────────────────────────────►│
    │  Discovering = false      │                                │
    │ ◄───────────────────────  │                                │

6.2 配对绑定流程 (LE Secure Connections)

应用                    bluetoothd               Agent               内核
 │                         │                      │                  │
 │ PairDevice(addr)        │                      │                  │
 │────────────────────►    │                      │                  │
 │                         │ MGMT_OP_PAIR_DEVICE  │                  │
 │                         │─────────────────────►│                  │
 │                         │                      │                  │
 │                         │  ◄─ MGMT_EV_NEW_IRK ─┤                  │
 │                         │  ◄─ MGMT_EV_NEW_LTK ─┤                  │
 │                         │  ◄─ MGMT_EV_NEW_CSRK─┤                  │
 │                         │                      │                  │
 │                         │ RequestConfirmation  │                  │
 │                         │◄────────────────────│                  │
 │                         │    (Agent交互)        │                  │
 │                         │────────────────────►│                  │
 │                         │                      │                  │
 │ ◄─ Pairing Complete ────┤                      │                  │

6.3 GATT 服务发现流程

bluetoothd Device                  远端 GATT Server
    │                                      │
    │ Exchange MTU Request                  │
    │ ───────────────────────────────────►  │
    │ ◄─── Exchange MTU Response ────────── │
    │                                      │
    │ Discover All Primary Services         │
    │ ───────────────────────────────────►  │
    │ ◄─── Read by Group Type Response ──── │
    │                                      │
    │ Discover All Characteristics          │
    │ ───────────────────────────────────►  │
    │ ◄─── Read by Type Response ────────── │
    │                                      │
    │ Discover All Descriptors              │
    │ ───────────────────────────────────►  │
    │ ◄─── Find Information Response ───────│
    │                                      │
    │ Enable Notifications/Indications      │
    │ ───────────────────────────────────►  │
    │ ◄─── Write Response ──────────────── │

6.4 A2DP 音频流建立流程

应用                    bluetoothd                   远端 A2DP Sink
 │                         │                              │
 │ Connect("A2DP_Sink")    │                              │
 │────────────────────►    │                              │
 │                         │ AVDTP Discover              │
 │                         │ ───────────────────────────► │
 │                         │ ◄── AVDTP Discover Resp ──── │
 │                         │                              │
 │                         │ AVDTP Get Capabilities       │
 │                         │ ───────────────────────────► │
 │                         │ ◄── AVDTP Get Caps Resp ──── │
 │                         │                              │
 │                         │ AVDTP Set Configuration      │
 │                         │ ───────────────────────────► │
 │                         │ ◄── AVDTP Set Config Resp ───│
 │                         │                              │
 │                         │ AVDTP Open                   │
 │                         │ ───────────────────────────► │
 │                         │ ◄── AVDTP Open Resp ──────── │
 │                         │                              │
 │                         │ AVDTP Start                  │
 │                         │ ───────────────────────────► │
 │                         │ ◄── AVDTP Start Resp ────────│
 │                         │                              │
 │ TransportCreated        │                              │
 │◄────────────────────    │                              │
 │                         │         ◄ 音频流 ►           │

7. 关键子系统

7.1 Plugin 系统

插件是 BlueZ 的核心扩展机制，每个蓝牙 Profile 独立封装为插件。

注册机制:

// 每个插件使用 BLUETOOTH_PLUGIN_DEFINE 宏
BLUETOOTH_PLUGIN_DEFINE(a2dp, ...)

内置插件 (plugins/):

外部插件 (profiles/*/): 所有蓝牙 Profile 实现

7.2 共享库 (src/shared/)

双后端架构 — 同时支持 GLib 和 ELL (Embedded Linux Library)：

7.3 OBEX 守护进程 (obexd/)

独立的 OBEX 守护进程，处理文件传输和信息同步：

obexd/src/
├── main.c       — OBEX 守护进程入口
├── obex.c       — OBEX 协议核心
├── server.c     — OBEX 服务器
├── transport.c  — 传输层抽象 (蓝牙/UNIX)
├── plugin.c     — OBEX 插件系统
├── manager.c    — 会话管理
├── service.c    — 服务注册
└── mimetype.c   — MIME 类型处理

obexd/plugins/
├── bluetooth.c  — 蓝牙传输后端
├── filesystem.c — 文件系统后端
├── ftp.c        — 文件传输
├── opp.c        — 对象推送
├── pbap.c       — 电话簿访问
├── mas.c        — 消息访问
├── irmc.c       — IRMC 同步
├── pcsuite.c    — PC Suite 同步
└── vcard.c      — vCard 解析

7.4 Mesh 实现 (mesh/)

独立的蓝牙 Mesh 网络实现，支持：

• • PB-ADV Provisioning
• • 配置模型服务器
• • 朋友节点 (Friend Node)
• • 低功耗节点 (LCFN)
• • 中继 (Relay)
• • RPL (重放保护列表)
• • 多个 AppKey/NetKey 管理
• • Model 扩展框架

8. 工具生态

8.1 用户态工具

8.2 测试工具

8.3 调试工具

9. 配置与存储

9.1 配置文件

9.2 main.conf 配置

9.3 持久化存储

Bluetooth 状态存储在 /var/lib/bluetooth/：

/var/lib/bluetooth/
├── XX:XX:XX:XX:XX:XX/         # 每适配器一个目录
│   ├── settings               # 适配器设置
│   ├── cache/                 # GATT 缓存
│   └── YY:YY:YY:YY:YY:YY/    # 每个配对设备一个目录
│       ├── info               # 设备信息 (名称, 地址, 类等)
│       ├── primary            # GATT 主服务
│       └── attributes         # GATT 缓存属性

9.4 GATT 缓存策略

通过 main.conf 的 [GATT].Cache 选项控制：

• • always: 始终使用缓存
• • yes: 使用缓存 (服务变更检测启用时)
• • no: 禁用缓存，始终完整发现

10. 体系结构图

10.1 内部组件依赖

                           bluetoothd
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   src/adapter.c        src/device.c          src/profile.c
        │                     │                     │
        ├── mgmt socket ──────┤                     │
        │                     │                     │
   profiles/audio/a2dp.c      │          plugins/policy.c
        │                     │                     │
   profiles/input/hog.c  src/gatt-database.c        │
        │                     │                     │
   profiles/network/    src/gatt-client.c           │
        │                     │                     │
        └──────────────┬──────┘                     │
                       │                            │
               src/shared/ (lib)                    │
           ┌───────────┼───────────┐                │
           │           │           │                │
        gatt-db    mgmt/hci     io/queue           ell/

10.2 数据流 (以 A2DP 音频为例)

[手机/蓝牙音箱]                    [Linux 桌面]
      │                               │
      │  HCI 链路 (ACL+SCO)            │
      │ ──────────────────────────►    │
      │                          kernel/bluetooth
      │                               │
      │                          MGMT_EV_CONNECTED
      │                          AVDTP start stream
      │ ──────────────────────────►    │
      │                          bluetoothd
      │                               │
      │                          profiles/audio/a2dp.c
      │                               │
      │                          ├── a2dp-sep.c (Sink Endpoint)
      │                          ├── avdtp.c (信令)
      │                          └── transport.c (传输)
      │                               │
      │                          D-Bus: MediaTransport1
      │                               │
      │                     [PulseAudio/PipeWire]
      │                          │ 解码 PCM → ALSA
      │                          ▼
      │                     [扬声器输出]

附录 A: 代码统计

附录 B: D-Bus 操作路径总览

/org/bluez                    ─ Manager, AgentManager1, ProfileManager1
  ├── hci0                    ─ Adapter1, GattManager1, LEAdvertisingManager1
  │   ├── dev_XX_XX_XX_XX_XX_XX  ─ Device1
  │   │   ├── serviceXXXX     ─ GattService1
  │   │   │   ├── charXXXX    ─ GattCharacteristic1
  │   │   │   │   └── descXXXX  ─ GattDescriptor1
  │   ├── set_XXXX            ─ DeviceSet1
  │   └── fd_XXXX             ─ Bearer1 (LE/BREDR)
  └── hci1                    ─ (同上)a