4. UHCI 传输描述符 (TD)

UHCI 主机控制器通过一个称为“传输描述符”(Transfer Descriptor, TD) 的数据结构来管理 USB 总线上的每一个数据包传输。TD 是 UHCI 调度与 DMA 协同工作的核心单元，它精确描述了“谁、从哪里、传多少、传完后怎么办”。本章将深入剖析 TD 的结构体定义、链接机制、控制状态位以及实际传输长度的计算规则。

4.1 TD 结构体定义

UHCI 的 TD 是一个 32 字节（4 个 64 位 QWORD）的固定长度数据结构，必须按 16 字节对齐存放在系统内存中。其结构定义如下：

// UHCI 传输描述符 (TD) 结构体定义
// 共 32 字节，按 16 字节对齐
typedef struct _UHCI_TD {
    // QWORD 0: 链接指针 (Link Pointer)
    uint32_t    LinkPointer;        // [31:4] TD 或 QH 物理地址, [3:2] 保留, [1] VF, [0] T
    uint32_t    Reserved1;          // 保留，必须为 0

    // QWORD 1: 控制状态 (Control & Status)
    uint32_t    ControlStatus;      // [31:28] 保留, [27] IOC, [26] IOS, [25] LS, [24:23] SPD,
                                    // [22:21] 保留, [20:16] ErrorCount, [15] CRC/Timeout,
                                    // [14] BitStuff, [13] BufferError, [12] Active,
                                    // [11] Stalled, [10] DataBufferError, [9] Babble,
                                    // [8] NAK, [7:4] 保留, [3:0] ActualLength
    uint32_t    Reserved2;          // 保留，必须为 0

    // QWORD 2: 令牌 (Token)
    uint32_t    Token;              // [31:30] PID (00=OUT, 01=IN, 10=SETUP),
                                    // [29:21] DeviceAddress, [20:18] Endpoint,
                                    // [17:16] DataToggle, [15:8] MaxPacketSize,
                                    // [7:0] 保留
    uint32_t    Reserved3;          // 保留，必须为 0

    // QWORD 3: 缓冲区指针 (Buffer Pointer)
    uint32_t    BufferPointer;      // 数据缓冲区物理地址 (4KB 对齐)
    uint32_t    Reserved4;          // 保留，必须为 0
} UHCI_TD;

4.2 链接指针 (Link Pointer)

链接指针是 UHCI 实现“链表调度”的关键字段。它位于 TD 的第一个 DWORD，格式如下：

链接指针支持三种链表拓扑：

• TD → TD 水平链接： VF=0, T=0，指向下一个同层 TD，形成水平队列。
• TD → QH 垂直链接： VF=1, T=0，指向一个队列头 (QH)，用于中断端点或批量端点调度。
• 链表终止： T=1，表示链表结束，UHCI 停止遍历该分支。

4.3 控制状态位 (Control & Status)

控制状态字段是 TD 的“大脑”，它控制传输行为并记录传输结果。该字段位于 TD 的第二个 DWORD，位定义如下：

4.4 实际传输长度 (ActualLength)

实际传输长度字段位于控制状态字的 [3:0] 位，是一个 4 位无符号整数，表示该 TD 实际传输的字节数。其取值范围为 0~15，但实际含义取决于传输方向：

实际传输长度与 MaxPacketSize 的关系决定了“短包”检测逻辑：

• 正常完成： ActualLength == MaxPacketSize，表示传输了完整的数据包。
• 短包： ActualLength < MaxPacketSize，表示传输结束或设备发送了短包。
• 零长度包： ActualLength == 0，用于 IN 传输中的 NAK 或显式零长度包。
• 错误情况： 如果 Babble 位置 1，ActualLength 可能无效，应丢弃该 TD 的数据。

4.5 令牌字段 (Token) 与缓冲区指针

令牌字段定义了 USB 传输的“身份信息”，包括 PID、设备地址、端点号、数据切换位和最大包大小。缓冲区指针则指向数据在系统内存中的物理地址。

4.6 TD 链表操作示例

以下代码展示了如何在嵌入式系统中初始化一个 TD 链表，并设置 DMA 传输：

// TD 链表初始化示例
#define TD_COUNT 4
UHCI_TD td_pool[TD_COUNT] __attribute__((aligned(16)));
uint8_t data_buffer[TD_COUNT][64] __attribute__((aligned(4096)));

void td_chain_init(void) {
    for (int i = 0; i < TD_COUNT; i++) {
        // 清空 TD
        memset(&td_pool[i], 0, sizeof(UHCI_TD));

        // 设置链接指针：水平链接，最后一个 TD 终止
        if (i < TD_COUNT - 1) {
            td_pool[i].LinkPointer = (uint32_t)(uintptr_t)&td_pool[i+1] | 0; // VF=0, T=0
        } else {
            td_pool[i].LinkPointer = 1; // T=1, 终止
        }

        // 设置控制状态：激活，全速 IN，IOC 使能
        td_pool[i].ControlStatus = (1 << 12)  // Active
                                 | (1 << 27)  // IOC
                                 | (1 << 23); // SPD=01 (全速 IN)

        // 设置令牌：IN 传输，设备地址 2，端点 1，DATA0，最大包 64
        td_pool[i].Token = (1 << 30)          // PID=01 (IN)
                          | (2 << 21)          // DeviceAddress=2
                          | (1 << 18)          // Endpoint=1
                          | (0 << 16)          // DataToggle=DATA0
                          | (64 << 8);         // MaxPacketSize=64

        // 设置缓冲区指针
        td_pool[i].BufferPointer = (uint32_t)(uintptr_t)data_buffer[i];
    }
}

// DMA 完成回调：检查 ActualLength 并处理数据
void td_dma_complete(UHCI_TD *td) {
    uint32_t status = td->ControlStatus;
    if (status & (1 << 12)) {
        // Active 仍为 1，TD 未完成，等待
        return;
    }
    uint8_t actual_len = status & 0x0F;
    if (status & (1 << 9)) {
        // Babble 错误，丢弃数据
        debug_printf("Babble error on TD %p\n", td);
        return;
    }
    // 处理实际传输的数据
    debug_printf("TD completed: actual_len=%d bytes\n", actual_len);
    process_usb_data(td->BufferPointer, actual_len);
}