📚 课程目录第2章主机控制器接口（HCI）并发命令队列

第2章主机控制器接口（HCI）并发命令队列：命令缓冲、事件处理、流量控制

2.1 为什么要关注 HCI 命令队列？

在 BLE 并发连接场景中，Host（主机）通过 HCI 命令与 Controller（控制器）交互。每个 HCI 命令都会消耗 Controller 内部有限的命令缓冲槽位。当多个连接同时需要发送命令（如连接参数更新、加密启动、特征读取）时，必须严格管理命令队列，否则会导致命令丢失、死锁或控制器复位。本章将深入剖析 HCI 并发命令队列的缓冲机制、事件处理流程和流量控制协议，并提供切实可行的实现方案。

2.2 HCI 命令交互基础

元素	说明
HCI 命令包	Host 发送的固定格式包，包含 OpCode、参数长度和参数数据。
命令缓冲槽位	Controller 内部用于暂存待处理命令的硬件/软件队列，数量由芯片决定（通常 1~8 个）。
HCI_Command_Status 事件	Controller 收到命令后立即返回，携带状态码，不代表命令已完成。
HCI_Command_Complete 事件	命令执行完成后返回，同时包含 `Num_HCI_Command_Packets` 字段（可用缓冲槽数）。
流量控制令牌	Host 根据 `Num_HCI_Command_Packets` 决定是否允许发送下一个命令。

2.3 并发连接下的队列依赖问题

对于单个连接，简单的“发送→等待完成→再发送”过程即可。但在多连接并发时，多个连接会同时竞争 HCI 命令资源。常见依赖场景包括：

连接创建依赖：LE Create Connection 命令必须独占控制器，直到事件返回连接建立成功或失败。
连接参数更新依赖：LE Connection Update 命令必须等待前一个更新完成（或超时）才能再次发起。
加密启动依赖：LE Start Encryption 命令需要在配对/绑定完成后才能执行，且加密过程中不可发送其他与连接相关的命令。
特征操作依赖：读取/写入特征值可能需要前序 MTU 交换或服务发现完成。

2.4 流量控制机制：基于令牌的发送许可

Controller 通过 HCI_Command_Complete 事件中的 Num_HCI_Command_Packets 向 Host 通告当前可用的命令缓冲槽数。Host 必须维护一个内部计数器，每发送一个命令减 1，每收到一个携带正数的 Complete 事件加 1。计数器不可小于 0。典型实现：

static volatile uint8_t cmd_buf_count = 0;    // 初始值由 Controller 报告
static bt_hci_cmd_tx_q_t tx_queue;           // 发送队列

// 发送一个 HCI 命令
int hci_cmd_send(bt_hci_cmd_t *cmd) {
    if (cmd_buf_count == 0) {
        // 没有可用槽位，入队等待
        return enqueue_cmd(&tx_queue, cmd);
    }
    cmd_buf_count--;
    return hci_send_raw(cmd);
}

// HCI_Command_Complete 事件处理回调
void on_hci_cmd_complete(uint8_t num_packets) {
    cmd_buf_count += num_packets;
    // 尝试从队列中取出等待的命令
    while (!is_queue_empty(&tx_queue) && cmd_buf_count > 0) {
        bt_hci_cmd_t *pending = dequeue_cmd(&tx_queue);
        cmd_buf_count--;
        hci_send_raw(pending);
    }
}

2.5 命令依赖管理：事件驱动的调度器

仅仅有流量控制是不够的。我们必须为每个连接维护一个命令依赖状态机。以下是一个简化的调度策略：

连接维度队列：每个连接拥有独立的命令队列，命令按插入顺序入队。
全局仲裁器：所有连接队列的队首命令，根据优先级和依赖条件选出可发送的命令。
依赖检查规则：
- 如果某个连接正在执行独占命令（如连接更新、加密），则该连接的其他命令必须等待。
- 如果某个连接处于“命令等待”状态（等待 Command_Complete 或 Command_Status），则该连接不可再发送新命令。
事件触发：收到 HCI 事件后更新对应连接的状态，并尝试发送下一个命令。

2.6 内联流程图：HCI 并发命令队列工作流

2.7 常见错误与调试方法

错误表现	根本原因	调试手段
`HCI_Command_Status` 返回 `Memory Capacity Exceeded`	Host 发送命令过快，超出 Controller 缓冲能力	抓取 HCI 日志，检查 `Num_HCI_Command_Packets` 递减轨迹
连接建立后立即断开，原因码 0x3E（连接超时）	连接更新命令未被及时发送，导致 Controller 等待	在事件回调中打印命令队列深度
死锁：所有连接卡住，无任何事件	依赖循环：A 连接等待 B 连接完成，B 又等待 A	验证依赖状态机，确保每个连接独立调度

2.8 性能与稳定性优化

批量命令合并：对于非关键命令（如读取 RSSI），可在队列中合并为一次 HCI 命令？（不支持合并，但可在 Host 侧延迟发送）。
优先级队列：为每个连接分配优先级，高优先级连接的命令可以插队，但需注意不超过控制器令牌数。
命令超时重试：为每个命令设置超时计时器，若超时未收到 Complete 事件，则重发或重置连接。
预分配命令缓冲：在连接建立阶段一次性预留足够的命令槽位（需控制器支持扩展命令缓冲）。

2.9 实现检查清单

开发验证步骤：
模拟多连接场景，每个连接连续发送 10 个不依赖的 HCI 命令（如 Read Local Supported Features）。
验证 Num_HCI_Command_Packets 从未变为负值，且最终所有命令都收到 Complete 事件。
插入依赖命令（如连接更新），确认仲裁器阻止了同一连接的其他命令。
使用 HCI 抓包工具（如 Elliot、Frontline）对比 Host 发送时间戳与令牌数变化。

2.10 小结

HCI 命令队列是 BLE 并发连接稳定性的基石。开发者必须正确实现基于令牌的流量控制，并为每个连接维护独立的依赖状态机。本节的实现框架可直接嵌入 Zephyr、NimBLE 或 FreeRTOS+BLE 等常见协议栈中。第3章将展开“连接更新与参数协商并发管理”中的具体依赖场景。

📚 课程目录

第2章 主机控制器接口（HCI）并发命令队列：命令缓冲、事件处理、流量控制