📚 课程目录第2章 xHCI寄存器空间

2. xHCI 寄存器空间：CAPLENGTH、HCSPARAMS1、HCSPARAMS2、HCCPARAMS1、HCCPARAMS2 详解

xHCI 控制器的初始化始于对寄存器空间的正确解析。主机软件（驱动程序）必须首先读取 CAPLENGTH 寄存器，以确定操作寄存器基地址的偏移量，随后通过 HCSPARAMS1/2 和 HCCPARAMS1/2 获取控制器的结构容量与功能支持。这些寄存器共同构成了 xHCI 的“能力寄存器”区域，是后续所有 DMA 描述符管理的基础。

  关键概念： 能力寄存器（Capability Registers）位于 xHCI MMIO 基地址的起始部分，其布局固定且只读。驱动程序通过解析这些寄存器，动态适配不同厂商、不同版本的 xHCI 控制器。

2.1 寄存器空间布局概览

xHCI 的 MMIO 空间分为两部分：能力寄存器（Capability Registers）和 操作寄存器（Operational Registers）。能力寄存器从基地址偏移 0x00 开始，而操作寄存器的起始地址由 CAPLENGTH 寄存器指定。

编程要点： 驱动程序在访问任何操作寄存器（如 USBCMD、PORTSC）之前，必须先读取 CAPLENGTH 的值，否则将导致错误的寄存器偏移，引发不可预测的行为。

2.2 CAPLENGTH 寄存器

CAPLENGTH 位于能力寄存器偏移 0x00，是一个 8 位只读寄存器。它定义了从 xHCI MMIO 基地址到操作寄存器起始地址的字节偏移量。根据 xHCI 规范，该值通常为 0x20（32 字节），但驱动程序必须动态读取，不能硬编码。

字段	位宽	偏移	描述
CAPLENGTH	8 位	0x00	操作寄存器基地址相对于 MMIO 基地址的偏移量（字节）。

// 读取 CAPLENGTH 示例（C 语言风格）
uint8_t caplength = *(volatile uint8_t*)(mmio_base + 0x00);
uint32_t op_regs_base = mmio_base + caplength;
// 现在可以通过 op_regs_base 访问 USBCMD、USBSTS 等操作寄存器

2.3 HCSPARAMS1 寄存器

HCSPARAMS1（Host Controller Structural Parameters 1）位于能力寄存器偏移 0x04，是一个 32 位只读寄存器。它描述了控制器的基本结构容量，包括支持的端口数量、中断线数量等。

位域	位范围	描述
Max Ports	[31:24]	控制器支持的 USB 端口总数（包括所有类型）。
Max Intrs	[23:8]	支持的中断线数量（用于 MSI/MSI-X 或传统中断）。
Max Slots	[7:0]	支持的设备槽位（Device Slots）数量，即最大可连接的 USB 设备数。

常见陷阱： Max Slots 字段决定了驱动程序需要分配的 Device Context Base Address Array（DCBAAP）条目数。如果驱动程序分配的条目数少于 Max Slots，控制器在访问超出范围的槽位时可能产生 DMA 错误。

2.4 HCSPARAMS2 寄存器

HCSPARAMS2 位于能力寄存器偏移 0x08，是一个 32 位只读寄存器。它提供了关于控制器内部结构的更多细节，特别是与中断和事件管理相关的参数。

位域	位范围	描述
Max ERST Entries	[31:27]	事件环段表（Event Ring Segment Table）支持的最大条目数（以 2 为底的对数）。
Max Scratchpad Buffers	[26:16]	控制器需要的暂存缓冲区（Scratchpad Buffer）数量，用于内部 DMA 操作。
Max ISOC Buffers	[15:8]	支持的最大等时（Isochronous）缓冲区数量。
Max Interrupters	[7:0]	支持的中断器（Interrupter）数量，每个中断器对应一个事件环。

  DMA 管理关联： Max Scratchpad Buffers 直接决定了驱动程序需要分配的暂存缓冲区数量。这些缓冲区是 DMA 描述符管理的一部分，用于控制器在内部操作（如地址转换）时临时存储数据。驱动程序必须在初始化时分配并注册这些缓冲区。

2.5 HCCPARAMS1 寄存器

HCCPARAMS1（Host Controller Capability Parameters 1）位于能力寄存器偏移 0x10，是一个 32 位只读寄存器。它描述了控制器支持的高级特性，这些特性直接影响 DMA 描述符的格式和管理策略。

位域	位范围	描述
AC64	[0]	64 位寻址能力。如果为 1，控制器支持 64 位 DMA 地址。
BNC	[1]	带宽协商能力（Bandwidth Negotiation Capability）。
CSZ	[2]	上下文大小（Context Size）。如果为 1，设备上下文大小为 64 字节；否则为 32 字节。
PPC	[3]	端口电源控制（Port Power Control）能力。
PIND	[4]	端口指示器（Port Indicators）支持。
LHRC	[5]	轻量级主机复位（Light Host Reset）能力。
LTC	[6]	延迟容忍度消息（Latency Tolerance Messaging）能力。
NSS	[7]	非标准速度（Non-Standard Speed）支持。
PAE	[8]	每端口 AER（Advanced Error Reporting）能力。
SPR	[9]	安全暂停恢复（Security Pause Resume）能力。
SEC	[10]	安全设备（Security Device）支持。
CFC	[11]	控制流控制（Control Flow Control）能力。
Max Primary Stream Arrays	[31:27]	支持的最大主流数组（Primary Stream Array）大小。

编程要点： AC64 和 CSZ 是 DMA 描述符管理中最关键的字段。AC64 决定是否使用 64 位地址描述符；CSZ 决定设备上下文的大小，直接影响 DCBAAP 中每个条目的步长。

2.6 HCCPARAMS2 寄存器

HCCPARAMS2 位于能力寄存器偏移 0x14，是一个 32 位只读寄存器。它提供了 xHCI 1.1 及更高版本引入的扩展能力信息。

位域	位范围	描述
U3C	[0]	U3 控制器（U3 Controller）支持，用于 USB 3.0 电源管理。
U3D	[1]	U3 设备（U3 Device）支持。
LEC	[2]	链路错误计数（Link Error Count）能力。
CIC	[3]	条件中断（Conditional Interrupt）能力。
CTC	[4]	控制器时间戳（Controller Timestamp）能力。
LEC	[5]	大端点（Large Endpoint）能力。
COC	[6]	控制器优化（Controller Optimization）能力。
XEC	[7]	扩展能力（Extended Capability）指针存在标志。
Max Exit Latency	[31:16]	最大退出延迟（Max Exit Latency），用于电源管理优化。

兼容性注意： 并非所有 xHCI 控制器都实现了 HCCPARAMS2。对于 xHCI 1.0 控制器，该寄存器可能返回全零。驱动程序在读取前应通过 HCCPARAMS1 中的扩展能力指针（XEC）确认其有效性。

2.7 寄存器解析流程与 DMA 描述符管理的关系

在初始化过程中，驱动程序必须按照严格的顺序解析这些寄存器，并根据解析结果配置 DMA 描述符管理结构。下面的 SVG 流程图展示了这一关键路径。

2.8 寄存器值对 DMA 描述符管理的直接影响

下表总结了关键寄存器字段与 DMA 描述符管理结构之间的直接映射关系，帮助开发者在初始化时做出正确的内存分配决策。

寄存器字段	影响的结构	DMA 管理动作
HCSPARAMS1.Max Slots	DCBAAP (Device Context Base Address Array)	分配 `Max Slots + 1` 个 64 位条目（条目 0 保留给 Scratchpad）
HCSPARAMS2.Max Scratchpad Buffers	Scratchpad Buffer Array	分配 `Max Scratchpad Buffers` 个缓冲区，并将地址填入 DCBAAP[0]
HCCPARAMS1.AC64	TRB (Transfer Request Block) 地址字段	如果为 1，TRB 中的地址字段使用 64 位；否则使用 32 位（高 32 位清零）
HCCPARAMS1.CSZ	Device Context 结构	如果为 1，每个 Device Context 大小为 64 字节；否则为 32 字节
HCSPARAMS2.Max ERST Entries	ERST (Event Ring Segment Table)	分配 ERST 条目数，每个条目包含段基地址和段大小

  实战案例： 假设读取到 HCSPARAMS1.Max Slots = 64、HCSPARAMS2.Max Scratchpad Buffers = 8、HCCPARAMS1.AC64 = 1、HCCPARAMS1.CSZ = 1。驱动程序需要分配：

  - DCBAAP：65 个 64 位条目（共 520 字节），64 位对齐。

  - Scratchpad Buffer Array：8 个 4KB 缓冲区（共 32KB），每个缓冲区物理地址连续。

  - Device Context：每个槽位 64 字节，共 64 * 64 = 4096 字节，用于后续设备连接时的上下文初始化。

2.9 初始化代码示例：解析能力寄存器

以下代码展示了如何在 xHCI 驱动初始化阶段解析上述五个能力寄存器，并根据解析结果准备 DMA 描述符管理所需的内存结构。

// xHCI 能力寄存器解析与 DMA 结构预分配
struct xhci_hcd {
    void __iomem *cap_regs;   // 能力寄存器基地址
    void __iomem *op_regs;    // 操作寄存器基地址
    uint32_t hcsparams1;
    uint32_t hcsparams2;
    uint32_t hccparams1;
    uint32_t hccparams2;
    uint8_t  caplength;
    
    // DMA 描述符管理结构
    uint64_t *dcbaap;         // Device Context Base Address Array
    dma_addr_t dcbaap_dma;
    void **scratchpad_bufs;   // Scratchpad 缓冲区指针数组
    uint32_t max_slots;
    uint32_t max_scratchpad;
    bool     ac64;
    bool     csz;
};

int xhci_init_cap_regs(struct xhci_hcd *xhci) {
    // 1. 读取 CAPLENGTH
    xhci->caplength = readb(xhci->cap_regs + 0x00);
    xhci->op_regs = xhci->cap_regs + xhci->caplength;
    
    // 2. 读取 HCSPARAMS1
    xhci->hcsparams1 = readl(xhci->cap_regs + 0x04);
    xhci->max_slots = (xhci->hcsparams1 >> 0) & 0xFF;
    
    // 3. 读取 HCSPARAMS2
    xhci->hcsparams2 = readl(xhci->cap_regs + 0x08);
    xhci->max_scratchpad = (xhci->hcsparams2 >> 16) & 0x7FF;
    
    // 4. 读取 HCCPARAMS1
    xhci->hccparams1 = readl(xhci->cap_regs + 0x10);
    xhci->ac64 = (xhci->hccparams1 >> 0) & 0x01;
    xhci->csz  = (xhci->hccparams1 >> 2) & 0x01;
    
    // 5. 读取 HCCPARAMS2 (可选)
    xhci->hccparams2 = readl(xhci->cap_regs + 0x14);
    
    // 6. 根据解析结果分配 DMA 描述符管理结构
    return xhci_alloc_dma_structures(xhci);
}

static int xhci_alloc_dma_structures(struct xhci_hcd *xhci) {
    size_t dcbaap_size;
    int i;
    
    // 分配 DCBAAP: (max_slots + 1) 个 64 位条目
    dcbaap_size = (xhci->max_slots + 1) * sizeof(uint64_t);
    xhci->dcbaap = dma_alloc_coherent(dev, dcbaap_size, 
                                       &xhci->dcbaap_dma, GFP_KERNEL);
    if (!xhci->dcbaap)
        return -ENOMEM;
    memset(xhci->dcbaap, 0, dcbaap_size);
    
    // 分配 Scratchpad Buffers
    if (xhci->max_scratchpad > 0) {
        xhci->scratchpad_bufs = kzalloc(xhci->max_scratchpad * sizeof(void *), 
                                         GFP_KERNEL);
        if (!xhci->scratchpad_bufs)
            return -ENOMEM;
        
        for (i = 0; i < xhci->max_scratchpad; i++) {
            xhci->scratchpad_bufs[i] = dma_alloc_coherent(dev, 
                XHCI_SCRATCHPAD_SIZE, &scratchpad_dma, GFP_KERNEL);
            if (!xhci->scratchpad_bufs[i])
                return -ENOMEM;
            // 将 Scratchpad 地址填入 DCBAAP[0] 的对应条目
            xhci->dcbaap[i + 1] = scratchpad_dma;
        }
    }
    
    // 注意: 根据 CSZ 决定 Device Context 大小，在设备连接时分配
    pr_info("xHCI: %d slots, %d scratchpad, AC64=%d, CSZ=%d\n",
            xhci->max_slots, xhci->max_scratchpad, 
            xhci->ac64, xhci->csz);
    return 0;
}

代码要点：

DCBAAP[0] 保留用于存储 Scratchpad Buffer Array 的基地址，不用于任何设备上下文。
如果 AC64 = 0，所有 DMA 地址必须保证在 32 位地址空间内（即高 32 位为零）。
CSZ 影响后续 Device Context 的分配大小，但 DCBAAP 条目始终为 64 位。

2.10 常见错误与调试建议

错误：硬编码 CAPLENGTH 为 0x20 —— 某些非标准控制器可能使用不同的偏移值，导致操作寄存器访问错位。
错误：忽略 Max Scratchpad Buffers —— 如果控制器需要 Scratchpad 但驱动程序未分配，控制器在内部 DMA 操作时可能崩溃。
错误：DCBAAP 分配不足 —— 必须分配 Max Slots + 1 个条目，而不是 Max Slots。
错误：未检查 AC64 就使用 64 位地址 —— 在不支持 64 位寻址的控制器上使用高 32 位地址会导致 DMA 错误。

调试建议： 在初始化完成后，通过读取 USBSTS 寄存器中的 HCHalted 位确认控制器已进入停止状态。如果控制器无法停止，通常是因为 DMA 描述符结构（DCBAAP 或 Scratchpad）配置错误。使用逻辑分析仪或 PCIe 嗅探工具捕获寄存器读写序列，可以快速定位问题。