深入探究加布尔德斯奇的蓝牙堆栈：专为安卓系统重新开发的解决方案

// 在当前模块的处理器线程上触发一次一次性超时事件。
alarm_ = std::make_unique(GetHandler());

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

在这里，报警机制是针对模块的处理器对象来构建的，这样它的回调函数就会在正确的线程上执行。Schedule方法接受一个闭包和持续时间作为参数，会为该持续时间设置一个计时器文件描述符；当计时器触发时，反应器就会在处理器的线程上执行OnConnectionTimeout函数。
common::Unretained(this)这个代码告诉绑定器只需保留对对象的原始指针即可，而不会延长该对象的使用寿命。在这里这样做是安全的，因为报警机制和对象都在同一个线程上运行，而且它们的销毁顺序也是已知且可控的。

最后这一点非常重要。Unretained实际上是一种向编译器做出的承诺；如果你违反了这个约定，程序很可能会崩溃，而且这种崩溃往往会导致系统出现严重的问题。

模块系统

Gabeldorsche中的每一个功能层都是一个模块。每个模块都有自己的生命周期、依赖关系集合，以及专用的处理线程。而模块注册表负责按照依赖关系顺序启动这些模块，并以相反的顺序停止它们。这种设计将原本复杂的初始化顺序问题转化成了计算机能够自动处理的流程，相比那些写着“请不要重新排列这些调用的顺序”的注释来说，这种方式要合理得多。

一个模块会继承自Module类，声明一个静态的ModuleFactory对象，并实现一组方法。其中最重要的方法是ListDependencies、Start和Stop。

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

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

  void Start() override {
    hci_layer_ = GetDependency();
    controller_ = GetDependency();
    // 此时模块已经准备好执行其功能了。
  }

  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(); });

这个类完整地展示了模块应该具备的功能与接口。

ListDependencies方法在模块构造时会被调用，用于指定该模块需要依赖哪些其他模块，具体方法是将这些依赖模块的类型添加到ModuleList中。注册表会读取所有模块中的这些声明信息，然后计算出一个合适的启动顺序，以确保HciLayer和Controller在ExampleModule::Start被调用之前就已经启动完毕。

在Start方法中，GetDependency()会通过相应的工厂函数找到已经运行的依赖模块实例，并将其作为原始指针返回给当前模块。由于注册表会确保这些依赖模块的生命周期长于当前模块本身，因此该模块可以安全地缓存这些指针。Stop方法则在系统关闭前被调用，用于释放对这些对象的引用并取消尚未完成的任务。

ToString方法为模块提供一个名称，方便在日志记录或dumpsys报告中使用。而静态的Factory对象则是一个简单的构造器，它负责创建新的模块实例，并且注册表会利用这个工厂对象来实例化模块以及确定其在依赖关系图中的位置。由于根本不存在需要严格遵守的全局初始化顺序，因此也就不存在出错的可能性。

注册表本身在系统启动时会负责将所有这些组件连接在一起，同时还会为每个模块分配相应的处理线程。

ModuleList modules;
modules.add();

// 注册系统会按照拓扑结构对模块进行排序，然后启动所有模块。
ModuleRegistry registry;
registry.Start(&modules, thread);

// ……其他代码继续执行……

registry.StopAll();

在这里，应用程序声明了它所需要的顶层模块，并将这些模块以及这些模块将运行的线程一起提交给注册系统。

堆栈的初始化过程分为三个步骤：首先创建一个适合当前配置运行的线程；然后构建一个包含所有顶层模块的ModuleList对象，这个列表会自动包含这些模块所有的依赖关系；最后在这个线程上启动注册系统，并等待所有模块都完成启动后再返回结果，这样当调用结束时，整个系统就已经可以正常运行了。

关闭过程与启动过程正好相反：首先停止注册表的操作，这样就会按逆向依赖关系顺序依次停止所有模块的运行，之后再结束整个程序的执行。

将这一系列操作集中到一个对象中，意味着只有一个地方能够准确了解数据栈的增减过程。这与以往的情况截然不同——在过去，程序的成功启动取决于许多文件能否按照正确的顺序被加载进来，而且这种结果具有很大的不确定性。

队列抽象机制

那些生成或接收数据包的模块并不会直接相互调用。它们是通过一个队列来连接的。这个队列是一种基于反应式设计原理构建的、有界的数据传输通道，它只允许一个生产者向一个消费者发送数据。例如，ACL数据就是通过这种方式在L2CAP层和HCI层之间进行传递的，而双方既不会被阻塞，也不会需要共享锁机制。

队列提供了两个半接口，分别对应两端。生产者端通过注册一个回调函数来实现数据的插入操作；当队列有空闲空间时，队列会调用这个回调函数。消费者端也注册了一个回调函数，当队列中有数据可用时，队列会调用这个回调函数。这样一来，就不存在任何一方因等待而阻塞的情况，也不会因为队列为空或已满而导致系统停滞。

// 生产者端：注册回调函数以便在队列有空闲空间时接收数据包。
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_packet_.front());
  pending_packet_.pop();
  return packet;
}

这种数据插入机制与大多数人的预期是相反的。你并不是直接将数据推入队列中，而是通过调用RegisterEnqueue并传入一个回调函数来实现数据的添加。只有当队列有空闲空间时，队列才会调用这个回调函数来请求下一条数据。

你的回调函数会返回一个数据包构建对象，或者在没有数据可发送时返回nullptr。这种设计是刻意为之的——这样就可以实现自动的压力反馈机制。如果下游消费者处理数据的速度较慢，导致队列中的数据堆积过多，那么回调函数就会停止被调用，此时数据会暂时存储在你的缓冲区中，你可以随时查看和处理这些数据，而不会让它们滞留在内核的隐藏缓冲区中，从而引发无法解释的延迟问题。

数据提取的过程与插入过程完全相同。

// 消费者端：注册回调函数以便在收到数据包时得到通知。
queue_end_->RegisterDequeue(
    handler_,
    common::Bind(&MyModule::OnPacketReceived, common::Unretained(this)));

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

在消费者端，RegisterDequeue会将一个绑定到处理函数的回调函数传递给队列。当有数据包可用时，队列会将这个回调函数发送到处理函数的线程中，在那里你可以通过调用TryDequeue来获取数据包。不过，TryDequeue仍然有可能返回nullptr，因为可能已经有其他进程取走了该数据包，所以你需要进行检查。同样的线程绑定规则也在这里得到了应用：回调函数是在处理函数的线程中执行的，因此数据的处理过程是串行的，并且不需要使用锁机制。

在底层，这两个部分是通过基于事件文件描述符构建的一个小型信号机制来协调工作的。正是这一机制使得一个线程中的生产者能够安全地向另一个线程中的消费者发送信号。当你需要添加大量数据时，EnqueueBuffer会自动处理整个流程——让你只需添加数据，然后让缓冲区负责后续的注册工作，而这正是大多数实际应用中都会采用的方式。

HCI层

主机控制器接口是主机操作系统栈与控制器芯片之间的通信协议。在Gabeldorsche系统中，HciLayer模块负责管理命令通道，并严格执行一条至关重要的规则：控制器会通过“信用额度”来告知你它一次能够接收多少条指令。如果你发送的指令数量超出了它的信用额度，系统就会出现各种难以排查的问题。

你不能直接编写HCI相关的字节数据。你需要构建一个结构规范的命令数据包，将其交给HCI层处理，同时为可能的响应结果提供一个回调函数。HCI层会负责流量控制、将响应与相应的指令进行匹配，并将未经请求的事件转发给相应的订阅者。

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("重置失败");
  }
}

这段代码会发送HCI重置命令并处理其完成后的反馈。hci::ResetBuilder::Create()用于生成结构规范且经过验证的命令数据包，因此你绝对不可能发送格式错误的重置请求。

EnqueueCommand会将命令放入层内部的命令队列中。只有当有足够的“信用额度”时，才会将命令发送给控制器；否则，这些命令会被暂时保留，直到控制器在响应中归还相应的信用额度。第二个参数是一个通过BindOnceOn绑定到你的处理函数的回调函数，因此完成后的处理操作会在你的线程中执行。

指令分为两种类型：一种会触发“Command Complete”事件，另一种会触发“Command Status”事件。HCI层提供了重载版本的EnqueueCommand函数，以便将不同类型的指令分别转发给相应的回调函数。

当响应数据到达时，你会首先收到一个通用格式的响应对象，然后将其转换为具体的ResetCompleteView类型，并在读取数据之前先检查IsValid()方法是否返回true。这种有效性检查并非形式主义，而是解析器用来确认接收到的字节数据是否符合预期的结构。

HCI层还会将其输出数据分成多个独立的流，而不是通过一个统一的回调函数来处理所有数据。命令响应会直接发送给你在发送命令时指定的回调函数；而对于像远程设备连接这样的未经请求的事件，则会被转发给注册了相应处理函数的模块。对于LE元事件及其子事件，也会分别被转发给对应的订阅者。此外，HCI层还提供了诸如安全接口和LE广告接口之类的子接口，这样各个模块就可以只关注自己真正需要的数据部分，而无需处理全部的信息流。

这种分离将请求-响应逻辑与随机事件处理逻辑分离开来；在旧的架构中，往往同一个函数会试图同时完成三项任务。

与HciLayer并列存在的是Controller模块，它的职责是在系统启动时向芯片发送查询指令，并将得到的结果缓存起来。它会发出read-local-version、read-local-supported-commands、read-buffer-size以及LE feature等命令，然后通过简单的获取器函数将这些结果暴露出来。

这一点非常重要，因为系统的其他部分始终需要了解诸如ACL缓冲区的大小、控制器能够容纳多少数据包之类的信息。一次性进行查询并将结果缓存起来，远比反复向芯片发送请求要好得多。当上层模块想要知道某个功能是否被支持时，它会询问Controller，而不会直接去询问硬件。

数据包定义语言

这里有一种设计机制，它在实际应用中发挥了巨大的作用。在旧的架构中，解析数据包意味着需要根据手动计算出的偏移量来读取字节，然后进行位移和掩码操作，并且还要确保所有开发者都正确处理了数据的字节序和边界检查问题。然而他们并不总是能够做到这一点，而格式错误的双蓝牙数据包往往会成为远程攻击的漏洞——这类漏洞通常会有一个容易记住的名称和相应的图标。

Gabeldorsche通过引入“数据包定义语言”来取代原有的处理方式。你只需要在.pdl文件中描述一次数据包的格式，然后一个名为bluetooth_packetgen的工具就会根据这些描述生成C++代码中的解析器和构建类。

一个PDL文件首先会声明数据的字节序，接着定义枚举类型、结构体以及数据包的结构。下表总结了你在PDL文件中最常遇到的各种字段构造方式：

上表涵盖了PDL文件中常用的各种字段构造方式。标量字段和枚举字段用于表示具有固定位宽的数值；数组结构则用于描述重复出现的数据，无论是可变长度还是固定长度的数据。_size_和_count_这两个字段才是真正巧妙的地方：它们使得这种格式描述方式能够仅通过一次设定就能明确长度前缀的具体数值，同时生成器会自动处理相关的算术运算，从而确保在序列化时能够计算出正确的长度，在解析时也能进行验证。_payload_标记用于实现数据包的继承机制，使得子数据包的内容能够被包含在父数据包中。_fixed_和_reserved_这两个标记用于编码常量以及必须为0的值，这样人们就无需记住这些细节了。

这里所有的内容都只是声明性的描述，而生成器会将这些描述转换成不会忽略任何边界检查的代码。
具体的实现方式就是使用结构体来定义数据格式，其中会明确指定各字段的宽度及约束条件；子数据包会对其父数据包中的某些字段进行限制。

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],
}

这段代码定义了一个操作码枚举类型、一个通用的Command父数据包结构，以及两个具体的数据包类型。Command数据包包含操作码、其负载数据的长度信息，以及实际的数据内容——这种结构是所有命令所共有的。Reset数据包继承自Command，并且将其操作码固定为RESET，因此生成的代码总是会使用正确的操作码；而ReadLocalNameComplete数据包则继承自CommandComplete，并增加了一个status字段以及一个长度为248个8位字节的数据字段——这种设计正好符合蓝牙规范对本地名称字段的要求。
括号中的约束条件使得生成的代码能够根据数据包中携带的操作码，自动将原始字节序列转换为正确类型的数据结构，而完全不需要编写任何手动切换语句。
根据这样的定义，生成器会为每种数据包类型生成两种对应的类：一种是用于将结构化数据序列化为字节流的构建器，另一种则是用于将字节流解析为结构化数据并进行边界检查的访问器。

// 构建过程：结构化数据被转换为经过验证的字节序列。
auto builder = hci::ResetBuilder::Create();
std::vector<uint8_t>> bytes;
BitInserter it(bytes);
builder->Serialize(it);   // 写入操作码、计算出的数据长度以及实际的数据内容

// 解析过程：字节序列被转换为结构化且类型正确的数据对象。
auto command_view = hci::CommandView::Create(
    PacketView<>kLittleEndian>>(std::make_shared<std::vector<uint8_t>>&>(bytes)));
auto name_view = hci::ReadLocalNameCompleteView::Create(command_view);

if (name_view.IsValid()) {
  std::array<uint8_t, 248>> name = name_view.GetLocalName();
}

从构建的角度来看，构建器清楚地知道数据的结构：它会按照顺序遍历各个字段，写入固定的操作码、计算并写入数据长度，最后输出实际的数据内容——因此用户完全不需要手动处理任何偏移量问题。

解析过程采用懒惰处理机制，并且是分层进行的。PacketView类在不复制数据的情况下封装了共享的字节缓冲区，通用的CommandView负责解析常见的命令头信息，而特定的ReadLocalNameCompleteView则会进一步细化解析过程。

关键方法是IsValid()，生成代码会通过这个方法来验证缓冲区的长度是否足够容纳所有字段的信息，同时也会检查各种约束条件是否都得到满足，只有在通过这些检查后，才会调用GetLocalName()方法来获取解析后的数据。

// 在PSM上注册一个动态的L2CAP服务。
dynamic_channel_manager_->RegisterService(
    kMyPsm,
    security_policy,
    GetHandler()->BindOnceOn(this, &MyModule::OnServiceRegistered),
    GetHandler()->BindOn(this, &MyModule::OnConnectionOpen);

void MyModule::OnConnectionOpen(
    std::unique_ptr channel) {
  channel->RegisterOnCloseCallback(/* ... */);
  channel->GetQueueUpEnd()->RegisterDequeue(/* ... */);
}

service HciLayerFacade {
  rpc SendCommand(Command) returns (google.protobuf.Empty) {}
  rpc StreamEvents(google.protobuf.Empty) returns (stream Event) {}
}