A Deep Dive into Gabeldorsche: The Bluetooth Stack Android Rebuilt on Purpose

+------------------------------------------+
        |     Android Framework (Java / AIDL)      |
        +------------------------------------------+
        |     BTIF / BTA (legacy profile logic)    |
        +------------------------------------------+
        |     Shim layer (GD <~> legacy bridge)    |
        +------------------------------------------+
        |  GATT | Security | L2CAP | Neighbor      | 
        +------------------------------------------+
        |  AclManager | Controller | HciLayer      |   
        +------------------------------------------+
        |     hci_hal (HAL: AIDL / HIDL interface) |
        +------------------------------------------+
        |     Bluetooth Controller (radio chip)    |
        +------------------------------------------+

线程

反应器

处理器

定时器

重复定时器

队列

入队缓冲区

// 获取模块的 handler 并在其线程上提交工作。
os::Handler* handler = GetHandler();

handler->Post(common::BindOnce(
    [](int connection_handle) {
      // 该 lambda 在 handler 的线程上运行，而不是调用者的线程。
      LOG_INFO("正在拆除连接 %d", connection_handle);
    },
    connection_handle));

// 在模块的 handler 线程上触发一次性超时。
alarm_ = std::make_unique<os::Alarm>(GetHandler());

alarm_->Schedule(
    common::BindOnce(&MyModule::OnConnectionTimeout, common::Unretained(this)),
    std::chrono::milliseconds(5000));

class ExampleModule : public bluetooth::Module {
 public:
  static const ModuleFactory Factory;

 protected:
  void ListDependencies(ModuleList* list) const override {
    list->add<hci::HciLayer>();
    list->add<hci::Controller>();
  }

  void Start() override {
    hci_layer_ = GetDependency<hci::HciLayer>();
    controller_ = GetDependency<hci::Controller>();
    // 模块现在可以通过 GetHandler() 执行工作
  }

  void Stop() override {
    // 释放引用；注册表在停止依赖项之前会调用此方法
    hci_layer_ = nullptr;
    controller_ = nullptr;
  }

  std::string ToString() const override { return "ExampleModule"; }

 private:
  hci::HciLayer* hci_layer_ = nullptr;
  hci::Controller* controller_ = nullptr;
};

const ModuleFactory ExampleModule::Factory =
    ModuleFactory([]() { return new ExampleModule(); });

ModuleList modules;
modules.add<ExampleModule>();

// 注册表对所有模块进行拓扑排序并启动
ModuleRegistry registry;
registry.Start(&modules, thread);

// ... 栈开始运行 ...

registry.StopAll();

TestModuleRegistry test_registry;
test_registry.InjectTestModule(&HciLayer::Factory, fake_hci_layer_);
test_registry.Start<ExampleModule>(&test_registry.GetTestModuleList());

// 驱动假的 HCI 层，验证 ExampleModule 的响应行为。

// 生产者端：注册以等待被要求发送下一个数据包
queue_end_->RegisterEnqueue(
    handler_,
    common::Bind(&MyModule::OnQueueReadyToSend, common::Unretained(this)));

std::unique_ptr<packet::BasePacketBuilder> MyModule::OnQueueReadyToSend() {
  if (pending_packets_.empty()) {
    queue_end_->UnregisterEnqueue();  // 没有数据可发送，停止被询问
    return nullptr;
  }
  auto packet = std::move(pending_packets_.front());
  pending_packets_.pop();
  return packet;
}

// 消费者端：注册以在数据包到达时被通知
queue_end_->RegisterDequeue(
    handler_,
    common::Bind(&MyModule::OnPacketReceived, common::Unretained(this)));

void MyModule::OnPacketReceived() {
  auto packet = queue_end_->TryDequeue();
  if (packet == nullptr) {
    return;
  }
  // 在handler_线程上处理接收到的数据包
}

hci_layer_->EnqueueCommand(
    hci::ResetBuilder::Create(),
    GetHandler()->BindOnceOn(this, &MyModule::OnResetComplete));

void MyModule::OnResetComplete(hci::CommandCompleteView view) {
  auto reset_view = hci::ResetCompleteView::Create(view);
  ASSERT(reset_view.IsValid());
  if (reset_view.GetStatus() != hci::ErrorCode::SUCCESS) {
    LOG_ERROR("Reset failed");
  }
}

little_endian_packets

enum OpCode : 16 {
  RESET = 0x0C03,
  READ_LOCAL_NAME = 0x0C14,
}

packet Command {
  op_code : OpCode,
  _size_(payload) : 8,
  _payload_,
}

packet Reset : Command (op_code = RESET) {
}

packet ReadLocalNameComplete : CommandComplete (command_op_code = READ_LOCAL_NAME) {
  status : ErrorCode,
  local_name : 8[248],
}

// 构建：结构化数据转换为验证后的字节
auto builder = hci::ResetBuilder::Create();
std::vector<uint8_t> bytes;
BitInserter it(bytes);
builder->Serialize(it);   // 写入 op_code、计算大小、payload

构建端展示了构建器对布局的精确掌握：Serialize 通过 BitInserter 按字段顺序遍历，写入固定操作码，计算并写入负载大小，最后输出负载数据，因此你永远不需要直接处理偏移量。

解析端则采用惰性且分层的方式。PacketView<kLittleEndian> 包装共享字节缓冲区而无需复制，通用的 CommandView 解析通用命令头，而具体的 ReadLocalNameCompleteView 进一步缩小解析范围。

关键方法是 IsValid()，生成的代码通过该方法实现验证，确保缓冲区长度足以容纳所有字段且所有约束条件都满足后再进行读取操作。只有通过该检查后，才能调用 GetLocalName() 将解析出的字段作为类型化数组提取出来。

由于解析器是根据每个数据包的相同规范生成的，因此整个类别的一类越界和越界错误再也无法手动编写。甚至还有 Python 绑定，由相同的 PDL 生成，因此测试套件使用与生产堆栈完全相同的字节级逻辑来解析和构建数据包。

## ACL 管理器和连接管理

在原始 HCI 层之上是 AclManager 模块，该模块负责异步面向连接的链路，设备连接后正是通过这种链路传输实际用户数据。它同时管理经典连接和低功耗连接，并将连接表示为带有自己回调接口的对象，而不是作为在全局表中四处漂浮的整数句柄等待被误用。内部实现上，它分为经典连接实现和 LE 实现，两者共享下一节将描述的轮询数据调度器。

当你请求建立连接时，会注册一个回调，当连接成功或失败时触发。成功时会收到一个拥有该链路队列的连接对象。

这展示了从使用者视角看的连接生命周期。RegisterCallbacks 订阅你的模块在处理线程上的连接事件，CreateConnection 触发 HCI 协议流程以连接到远程地址。

成功时，OnConnectSuccess 会接收到一个由 unique_ptr 所拥有的 ClassicAclConnection 对象，这意味着所有权是显式的，当对象被销毁时链接会确定性地被拆除。连接对象自带数据队列，通过 GetAclQueueEnd() 访问，并使用与之前完全相同的队列模式在其上注册出队回调。

最后，你将连接移动到以句柄为键的自己的映射中。链接的所有权归属不再存在歧义，这在之前的架构中曾是导致使用后释放漏洞的真实根源。

LE侧增加了一个需要特别说明的细节：隐私保护。LE设备通过使用可解析私有地址轮换其广告地址，防止追踪者通过MAC地址跟踪设备。

Gabeldorsche包含一个LeAddressManager组件，它负责管理本地地址轮换和控制器的解析列表，并协调地址变更时机，确保地址不会在依赖地址稳定性的操作进行时发生轮换。这是需要精确处理、对时序敏感的工作，将地址逻辑集中到单一组件而非分散到LE代码各处，正是整个架构设计旨在简化的问题。

## 轮询调度器与ACL数据路径

控制器拥有有限数量的ACL缓冲区，每个连接都需要竞争这些资源。如果允许一个繁忙连接占用所有缓冲区，其他连接将陷入饥饿状态——在手机上，这意味着文件传输会中断音频播放。

Gabeldorsche通过位于每个连接队列与控制器共享链路之间的RoundRobinScheduler解决了这个问题。

调度器跟踪控制器拥有的缓冲区信用数量，按轮询顺序从每个连接依次取出一个数据包，将其分片为控制器ACL数据包大小，然后向下发送并递减信用计数。

当控制器通过已完成数据包数量事件报告已传输数据包并释放缓冲区时，调度器会将这些信用额度重新加入并恢复发送。

由于采用轮询顺序访问连接而非先耗尽一个连接再处理下一个，带宽可以在各链路间公平共享，无需任何连接知道其他连接的存在。分片操作也在此处完成，因此上层模块可以继续以完整的L2CAP帧进行思考，而调度器则默默地将它们分割为控制器大小的数据块，并在回传时重新组装信用额度。这个组件的存在使得"我的耳机和文件同步可以共存"成为可能，而非"二选一"。

## L2CAP与数据流水线

L2CAP（逻辑链路控制与适配协议）将单一ACL链路复用为多个逻辑通道，并处理大型服务数据单元的分片与重组。

Gabeldorsche将经典蓝牙和LE版本作为独立模块实现（L2capClassicModule和L2capLeModule），底层共享通用机制。它区分固定通道（始终存在用于信令等任务）与动态通道（按需为特定服务打开）。

服务通过协议或服务多路复用器注册自身，当远程设备打开到该服务的通道时，服务会收到一个拥有队列的通道对象。

以下是翻译后的 Markdown 内容：

---

此处服务注册到 Protocol Service Multiplexer 值，这在 L2CAP 中相当于端口号。RegisterService 函数接收 PSM、描述通道所需配对和加密级别的安全策略、一个确认注册的一次性回调，以及一个每次远程对等端打开通道时触发的重复回调。当通道打开时，OnConnectionOpen 会接收到一个由 unique_ptr 管理的 DynamicChannel 对象，并为其设置关闭回调和队列的出队操作。

将安全策略作为注册参数而非后续临时检查的机制，意味着通道在物理层面无法以低于服务要求的安全级别打开。将安全视为类型的属性而非运行时的临时考虑，是该协议栈中反复出现的设计选择。

在友好的通道对象之下，是一个真正的数据管道，值得想象一下字节如何通过这个管道传输。

该图示展示了 L2CAP 数据流的两个方向。传出方向时，来自上层的服务数据单元（SDU）进入通道的 Segmenter，将其拆分为协议数据单元（PDUs），并应用通道的传输模式（如基本模式或增强重传模式，包含确认和重传机制）。

随后，每链路 Scheduler 根据通道优先级决定哪个通道优先发送，从而确保低延迟通道获得优先权。Fragmenter 将这些 PDUs 拆分为控制器的 ACL 缓冲区大小，然后传递给 AclManager 队列和上一节提到的轮询调度器。

传入方向时，流程反向进行：Reassembler 将 ACL 片段重新组装为 PDUs，每通道 Recombiner 将 PDUs 重新组装为原始 SDU，最终 SDU 传递到通道队列的上端，供上层读取。

每个阶段都是一个职责单一、可测试的小型组件，这也是为什么历史上 L2CAP 作为最易出错的协议层之一，如今变得易于处理。

## 安全与配对

SecurityModule 模块为两种传输方式集中管理配对、绑定和加密。经典配对过程通过链路进行，而 LE 安全管理协议（LE Security Manager Protocol）则通过一个专用于 SMP 的固定 L2CAP 通道运行。

该模块驱动各种关联模型（包括数字比较、密码输入、带外传输和仅连接）的状态机。它通过回调接口暴露用户交互，使框架能够显示配对对话框并反馈用户的选择。

设计目标是确保其他模块不实现自己的加密或配对逻辑。当 L2CAP 需要加密通道才能传输数据时，它不会自行访问密钥存储或启动加密流程，而是通过强制接口请求安全模块，等待处理结果后才向高层打开通道。

## GATT 和 ATT

在低功耗蓝牙协议栈的顶层是属性协议（ATT）和通用属性配置文件（GATT），后者是几乎所有低功耗产品实际使用的请求-响应数据库。

ATT 定义了线缆操作，包括对编号属性句柄的读取、写入、通知和指示，并通过其专用的 L2CAP 通道运行。GATT 将这些属性组织成服务和特征，这是心率监测器或耳机向手机呈现的抽象模型。

在 Gabeldorsche 中，GATT 在其下层模块上实现了清晰的分层。ATT 是固定通道 L2CAP 接口的客户端，因此它通过与其他固定通道相同的机制获得通道，并通过相同的队列模式传输数据包。其数据包在 PDL 中与其他模块一样被定义，因此 ATT 读取请求及其响应通过相同的验证机制生成构建器和视图，与 HCI 命令具有相同的保证。

GATT 在 ATT 之上构建其服务和特征数据库，并向其上层配置文件暴露注册和通知接口。

架构的优势在这里以微妙的方式体现：由于 GATT 只是通过队列和类型化数据包进行通信的另一组模块，因此可以通过 RootCanal 与虚拟对等设备进行测试，而无需下层任何模块是真实硬件。

## 邻居和存储模块

两个支持模块组完善了整体架构。邻居模块负责其他设备的发现和识别，存储模块负责持久化数据。

发现过程并非单一操作，而是多个步骤，Gabeldorsche 在邻居模块下将每个步骤建模为独立组件。Inquiry 负责经典设备发现及其扫描模式。Page 和 page-scan 负责设备可连接性和连接建立。名称解析用于获取远程设备的人类可读名称。

将这些功能作为具有狭窄接口的独立组件，而非一个大型发现模块，意味着每个组件都可以单独分析和测试。这也意味着名称解析的错误不会意外破坏 Inquiry 的状态，因为它们不共享可变状态。

存储模块负责跨重启记住信息，主要包括已配对设备及其密钥，以及适配器和设备属性。它提供设备及其属性的内存模型，并将该模型持久化到配置文件中，通过批量写入避免属性更改激增导致磁盘频繁写入。

由于持久化功能通过模块接口实现，协议栈其余部分通过方法调用读写设备属性，而非直接解析配置文件。磁盘上的格式可以更改，而无需每一层都知晓。每次重启后丢失已配对设备会是令人难忘的糟糕体验，因此这个模块默默地发挥着关键作用。

## Shim 和 Facade 层

你不能在一个提交中重写整个蓝牙堆栈并直接发布。Gabeldorsche 是逐步推出的，每次只更新一层，这意味着在很长一段时间内，新的 GD 模块必须与旧的 Fluoride 代码共存。

`shim/` 层是实现这一目标的外交桥梁。它暴露了 BTIF 和 BTA 所期望的旧 C 风格接口，并将这些调用转换为底层新的模块方法调用，在跨越边界时会跳转到 GD 堆栈线程。各个层通过标志位进行控制，使得某一层可以在一个构建中运行于 GD，而在另一个构建中运行于旧代码。这使得通过切换标志位而非考古式分析，就能将回归问题定位到特定层。

`facade/` 层则承担着完全不同的职责。每个 GD 模块都可以暴露一个称为 `facade` 的 gRPC 服务，允许外部进程直接驱动该模块。这是测试框架插入的接口。测试不再需要通过整个 Android 框架进行，而是可以启动单个模块，通过 gRPC 连接到其 facade，并直接向被测层发送命令，同时观察其事件流。

这是模块 facade 在 protobuf 中的示例。它定义了一个 gRPC 服务，包含一个用于向模块发送命令的单向方法，以及一个用于将模块发出的每个事件推回调用方的服务器流方法。由于使用了 gRPC，驱动测试的客户端可以用任何语言编写，该项目选择 Python 作为测试用例的编写语言，兼顾可读性和编写速度。

facade 将每个内部层转化为可以从进程外部直接操作的对象，而无需围绕它构建整个操作系统。这就是可测试设计与仅仅在设计文档中写上“可测试”字样的设计之间的本质区别。

## 构建系统集成

如果没有将数据包生成器作为一等公民对待的构建工具，所有这些都不会如此顺畅。Gabeldorsche 使用 Soong 构建，这是 AOSP 构建系统，其文件名为 `Android.bp`，PDL 生成器作为自定义规则集成其中，使得 `.pdl` 文件在构建图中会自动编译为 C++ 头文件。

实现机制是通过生成源代码规则。构建规则指定 `bluetooth_packetgen` 工具，指向 `.pdl` 输入文件，并声明 `.h` 输出文件。任何将这些生成的头文件列为源文件的 C++ 库都会按需构建它们，并在 `.pdl` 文件更改时自动重新构建。

实际效果是，开发者修改数据包定义后重新构建，新的类型化构建器和视图会立即在 C++ 目标中存在，并通过并行规则在测试使用的 Python 绑定中同步存在。没有需要提交的生成代码，因此不会出现与真实状态脱节的情况，也无需在提交更改前手动执行代码生成步骤。同一份真实来源同时用于生产环境的 C++ 代码和测试用的 Python 代码，构建系统保证它们永远不会出现偏差。

## 日志、指标和 dumpsys

一个无法观察的堆栈是无法调试的，而蓝牙调试通常发生在错误报告之后。

Gabeldorsche 相应地进行了投资。它通过标准 Android 日志宏进行记录，并为每个模块分配独立标签，因此日志行能明确显示其来源层级。同时它维护结构化指标，将数据输送至平台统计管道，实现对整个设备集群的聚合健康监控。

最实用的调试功能是 dumpsys 集成。模块可以实现 dump 方法，注册表可遍历运行中的模块并要求每个模块序列化当前状态，这些信息最终会出现在崩溃报告的蓝牙部分。

由于每个模块都了解如何描述自身，崩溃报告能够完整捕捉整个堆栈的快照，包括连接表、通道状态、控制器能力等，无需人工在故障发生时进行任何监控操作。

这正是"请在我看着的时候重现问题"与"把你们已经有的崩溃报告发给我"之间的区别。对于蓝牙这种高度依赖时序的组件，这种区别往往决定了整个调查过程的成败。

## 使用认证测试与 RootCanal 进行测试

所有这些模块化设计带来的最大回报是测试基础设施，其中有两个突出亮点。第一个是认证测试套件（Cert tests），通常用 Python 编写，通过 gRPC 接口驱动模块进行测试。第二个是 RootCanal，一个虚拟蓝牙控制器。

RootCanal 值得特别关注。它是一个实现蓝牙控制器功能的软件，能够处理 HCI 协议。但与真实硬件不同，它使用的是模拟的物理层。

可以将多个协议栈连接到同一个 RootCanal 实例，它能模拟这些设备在彼此无线电覆盖范围内的状态，将一个协议栈的广告信息和连接请求传递给另一个。这意味着在没有蓝牙硬件的 Linux 机器上，可以通过持续集成系统完整运行两个设备之间的配对和数据传输场景。真实无线电的不稳定性、无线电干扰、时序抖动、同事拿着微波炉经过导致的信号干扰等曾让传统测试变得不可靠的问题，通过这种设计被彻底消除。

认证测试将这些组件串联起来：它启动被测协议栈和一个参考协议栈，将两者都连接到 RootCanal，并对它们之间传输的数据包进行断言。

这个测试无需任何硬件即可端到端测试 HCI 层。self.dut 是被测设备，是一个真实运行的 GD 协议栈实例，通过其 gRPC 接口进行交互。SendCommand 方法会序列化由 Python 绑定生成的 ResetBuilder（该绑定与 C++ 代码使用相同的 PDL 生成），并将其推送到协议栈的 HCI 接口。测试随后获取协议栈的事件流，并断言其发出对应 Reset 操作码的命令完成事件，使用的是等待事件到达的匹配器而非一次性检查的竞态条件处理方式。

整个场景在 CI 环境中可以确定性地运行。当这个测试通过时，说明 HCI 命令通道正常工作。当测试失败时，每次失败的表现都完全一致，这是测试能拥有的最有价值的特性。

## Floss：Gabeldorsche 走出 Android 的边界

由于GD堆栈是基于自己的操作系统抽象层构建，而非嵌入Android内部，因此它最终实现了可移植性。Floss（全称Fluoride Linux OS Stack）是运行Gabeldorsche核心的项目，作为桌面Linux和ChromeOS的蓝牙堆栈。它复用了相同的模块、相同的包库和相同的测试基础设施，并通过D-Bus接口而非Android AIDL向Linux世界暴露这些组件。

这充分验证了架构设计的正确性。用于保持手机耳塞连接的连接管理、HCI流量控制、轮询调度和PDL生成的解析器，同样也能在笔记本电脑上运行，因为这些逻辑从未与Android本身耦合。

平台间差异的部分被推至边缘，包括与芯片通信的传输层和与操作系统交互的接口层，而中间的协议层则在各平台间共享。

能够干净移植到完全不同操作系统的架构，说明其确实具备真正清晰的接口分隔，而非仅停留在理想化的注释层面。

## 总结

Gabeldorsche是当一个团队决定通过修复架构而非仅处理症状来解决十年来蓝牙连接不稳定问题时的产物。

整个设计基于每一层都重复的几个核心理念。工作被组织成模块，具有显式声明的依赖关系，注册表按正确顺序启动这些模块并按相反顺序销毁。并发通过消息传递到拥有数据的线程实现，基于反应器和处理程序构建，因此堆栈几乎不使用锁，所使用的锁也极少且刻意为之。

数据通过提供免费反压机制的响应式队列在各层间流动，轮询调度器公平分配控制器缓冲区以实现音频和大容量传输共存，L2CAP是多个小型专用阶段组成的流水线而非单一的巨型模块。数据包通过从形式化规范生成的代码进行解析，消除了整个内存安全漏洞家族，并使C++和Python路径的字节级实现完全一致。连接和通道是具有明确生命周期的对象而非全局表中的整数句柄，安全性作为类型和注册的属性附加，而非可能被遗忘的运行时检查。

测试方案是让其余部分令人信服的关键。每一层都暴露gRPC接口，构建系统在每次更改时重新生成数据包代码，dumpsys将完整状态快照捕获到每个错误报告中，RootCanal提供虚拟控制器使完整多设备场景在持续集成中无需任何无线电即可确定性运行。每次以相同方式失败的测试比偶尔能工作的堆栈更有价值，这一原则驱动了整个重构。

如果你想进一步探索，代码位于AOSP的蓝牙主线模块中，相同的内核现在通过Floss在Linux桌面运行。阅读一个.pdl文件，然后阅读其生成的头文件，再跟踪一个ACL数据包从L2CAP层经过轮询调度器到HCI层的完整路径，整个项目的理念将在一个下午变得清晰。这是一个被设计为易于理解的堆栈，对于蓝牙而言，这仍然感觉像是一个小奇迹。

阅读更多文章。

如果这篇文章对你有帮助，请分享它。

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发者。立即开始

广告