# Deshab xHCI USB 驱动设计文档

## 1. 概述

xHCI (eXtensible Host Controller Interface) 是 USB 3.0+ 的标准主机控制器接口规范，统一支持 USB 1.1/2.0/3.x 设备，取代 UHCI/OHCI/EHCI。本驱动实现 xHCI 控制器驱动 + USB 大容量存储设备支持，使 Deshab 内核可通过 USB 存储设备（U 盘）读写数据。

### 1.1 驱动定位

```text
驱动名称:  xhci
驱动类:    DKM_CLASS_STORAGE (6)
加载阶段:  stage1 (boot)
依赖:      pci, irq
提供:      block
输出文件:  SYSTEM/driver/block/xhci.drv
```

### 1.2 实现范围

- xHCI 控制器发现、复位、启动
- Command Ring / Event Ring / ERST 管理
- USB 设备端口检测、重置、枚举
- 设备描述符 / 配置描述符读取
- Bulk-Only Transport (BOT) 大容量存储协议
- SCSI Transparent Command Set: INQUIRY / READ CAPACITY / READ(10) / WRITE(10)
- 块设备注册 (kernel_api.block)

### 1.3 不在范围内

- USB 3.x LPM (Link Power Management)
- USB 2.0 TT (Transaction Translator)
- Isochronous / Interrupt 传输
- 多设备并发（首版只枚举第一个 MSC 设备）
- USB Hub（假设设备直连控制器端口）
- xHCI Stream IDs
- MSI/MSI-X 中断（首版使用同步轮询）

---

## 2. xHCI 架构概述

### 2.1 寄存器布局

```text
MMIO Base
├── Capability Registers (0x00 - CAPLEN)
│   ├── HCSPARAMS1: MaxSlots, MaxIntrs, MaxPorts
│   ├── HCSPARAMS2: Scratchpad, MaxERST, IST, SPB
│   ├── HCCPARAMS1: ContextSize, ExtCapPtr
│   ├── DBOFF: Doorbell Register Offset
│   └── RTSOFF: Runtime Register Space Offset
│
├── Operational Registers (CAPLEN - 0x3FF)
│   ├── USBCMD: RS, RST, INTE
│   ├── USBSTS: HCH, EINT, CNR
│   ├── CRCR: Command Ring Control
│   ├── DCBAAP: Device Context Base Array Ptr
│   └── CONFIG: MaxSlotsEn
│
├── Port Registers (0x400 - 0x7FF)
│   └── PORTSC[n]: CCS, PED, PR, PLS, Speed
│
├── Runtime Registers (RTSOFF - )
│   ├── MFINDEX: Microframe Counter
│   └── IR[0]: IMAN, IMOD, ERSTSZ, ERSTBA, ERDP
│
└── Doorbell Registers (DBOFF - )
    └── DB[n]: Doorbell for Slot n
```

### 2.2 数据结构关系

```text
DCBAA (Device Context Base Address Array)
├── [0]: Scratchpad Buffer Array Phys
├── [1]: Device Context 1 Phys
├── [2]: Device Context 2 Phys
└── ...

Device Context
├── Slot Context (32/64 bytes)
└── Endpoint Context[0-31] (32/64 bytes each)
    └── Transfer Ring Dequeue Pointer

Command Ring (Circular)
├── TRB[0]: Enable Slot Command
├── TRB[1]: Address Device Command
├── ...
└── TRB[N-1]: Link TRB → TRB[0]

Event Ring (Circular)
├── TRB[0]: Command Completion Event
├── TRB[1]: Transfer Event
├── TRB[2]: Port Status Change Event
├── ...
└── TRB[N-1]: Link TRB → TRB[0]

Transfer Ring (per Endpoint, Circular)
├── TRB[0]: Setup Stage / Normal
├── TRB[1]: Data Stage / Normal
├── TRB[2]: Status Stage / Normal
├── ...
└── TRB[N-1]: Link TRB → TRB[0]
```

---

## 3. TRB 格式

### 3.1 通用 TRB (16 字节)

```text
Offset  Size  Field
0x00    8     Parameter (数据指针 / 命令参数)
0x08    4     Status (传输长度 / 完成码)
0x0C    4     Control (TRB Type[15:10], Cycle Bit[0], Flags)
```

### 3.2 Cycle Bit 机制

- **Producer Cycle State (PCS)**: 写入方维护的 cycle 值
- **Consumer Cycle State (CCS)**: 读取方维护的 cycle 值
- TRB 有效条件: `TRB.CycleBit == Ring.CCS`
- 环绕时翻转 Cycle State，实现无锁生产者-消费者同步

### 3.3 关键 TRB 类型

| Type | 名称 | 用途 |
|------|------|------|
| 0x01 | Normal | Bulk/Interrupt 数据传输 |
| 0x02 | Setup Stage | Control 传输 Setup 阶段 |
| 0x03 | Data Stage | Control 传输 Data 阶段 |
| 0x04 | Status Stage | Control 传输 Status 阶段 |
| 0x06 | Link | 环链接，指向下一段 |
| 0x09 | Enable Slot | 分配设备 Slot |
| 0x0A | Disable Slot | 释放设备 Slot |
| 0x0B | Address Device | 设置 USB 设备地址 |
| 0x0C | Configure Endpoint | 配置设备端点 |
| 0x17 | No-Op | 空操作 |

### 3.4 事件 TRB 类型

| Type | 名称 | 用途 |
|------|------|------|
| 0x01 | Transfer Event | 传输完成通知 |
| 0x02 | Command Completion | 命令完成通知 |
| 0x04 | Port Status Change | 端口状态变化 |

---

## 4. USB 设备枚举流程

```text
1. 检测端口连接 (PORTSC.CCS = 1)
2. 端口重置 (PORTSC.PR = 1 → 等待 PED = 1)
3. 读取端口速度 (PORTSC.Speed)
4. Enable Slot → 获得 Slot ID
5. 分配 Input Context + Transfer Ring (EP0)
6. Address Device (BSR=0) → 设备获得 USB 地址
7. Control Transfer (EP0): GET_DESCRIPTOR(Device)
8. 重新 Address Device (使用真实 MaxPacketSize)
9. Control Transfer (EP0): GET_DESCRIPTOR(Configuration)
10. Configure Endpoint (Bulk IN/OUT)
11. 设备就绪，可进行 Bulk 传输
```

---

## 5. BOT (Bulk-Only Transport) 协议

### 5.1 CBW (Command Block Wrapper, 31 字节)

```text
Offset  Size  Field
0x00    4     Signature: 0x43425355 ("USBC")
0x04    4     Tag: 递增标签（用于匹配 CSW）
0x08    4     Data Transfer Length: 期望数据字节数
0x0C    1     Flags: 0x80=Device-to-Host (IN), 0x00=Host-to-Device (OUT)
0x0D    1     LUN: 逻辑单元号
0x0E    1     CB Length: 命令块长度 (1-16)
0x0F    16    CB: SCSI 命令块
```

### 5.2 CSW (Command Status Wrapper, 13 字节)

```text
Offset  Size  Field
0x00    4     Signature: 0x53425355 ("USBS")
0x04    4     Tag: 匹配 CBW Tag
0x08    4     Data Residue: 未传输字节数
0x0C    1     Status: 0=OK, 1=Failed, 2=Phase Error
```

### 5.3 传输流程

```text
OUT (Bulk EP): CBW →
IN/OUT (Bulk EP): Data (如有) →
IN (Bulk EP): CSW
```

---

## 6. SCSI 命令集

### 6.1 INQUIRY (0x12)

```text
CB: [0x12, 0x00, 0x00, 0x00, allocation_length, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
Response: 36 字节标准 INQUIRY 数据
  - Byte 0: Peripheral Device Type (0x00 = Direct Access Block)
  - Bytes 8-15: Vendor Identification
  - Bytes 16-31: Product Identification
  - Bytes 32-35: Product Revision Level
```

### 6.2 READ CAPACITY(10) (0x25)

```text
CB: [0x25, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
Response: 8 字节
  - Bytes 0-3: Maximum LBA (big-endian)
  - Bytes 4-7: Block Size (big-endian, typically 512)
```

### 6.3 READ(10) (0x28)

```text
CB: [0x28, 0x00, LBA[3], LBA[2], LBA[1], LBA[0], 0x00, TransferLength[1], TransferLength[0], 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
Direction: Device-to-Host (IN)
Data: TransferLength × BlockSize 字节
```

### 6.4 WRITE(10) (0x2A)

```text
CB: [0x2A, 0x00, LBA[3], LBA[2], LBA[1], LBA[0], 0x00, TransferLength[1], TransferLength[0], 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
Direction: Host-to-Device (OUT)
Data: TransferLength × BlockSize 字节
```

---

## 7. Context 格式

### 7.1 Slot Context (32 或 64 字节)

```text
DW0: Route String[23:0], Speed[29:27], MTT[31:30]
DW1: Max Packet Size[15:0], Device Address[31:24]
DW2: TT Hub Slot ID[7:0], TT Port Number[15:8], TTT[19:18], Rsv[23:20], Context Entries[31:27]
DW3: Exit Latency[19:0], Slot State[31:27]
```

### 7.2 Endpoint Context (32 或 64 字节)

```text
DW1: EP Type[3:0], Max Packet Size[31:16]
DW2: Max ESIT Payload Lo
DW4: Average TRB Length[15:0], Max Burst[31:24]
DW6: Dequeue Pointer Low (Transfer Ring)
DW7: Dequeue Pointer High
```

### 7.3 Input Context

```text
Offset 0:   Input Control Context (32/64 bytes) - 位图指示哪些 Context 有效
Offset 32/64: Slot Context
Offset 64/128: Endpoint 0 Context
Offset 96/192: Endpoint 1 Context (Bulk OUT)
Offset 128/256: Endpoint 2 Context (Bulk IN)
```

---

## 8. USB 描述符格式

### 8.1 设备描述符 (18 字节)

```text
Offset  Size  Field
0       1     bLength: 18
1       1     bDescriptorType: 1
2       2     bcdUSB: USB 版本 (0x0200 = USB 2.0)
4       1     bDeviceClass: 设备类 (0x08 = Mass Storage)
5       1     bDeviceSubClass
6       1     bDeviceProtocol
7       1     bMaxPacketSize0: EP0 最大包大小 (8/16/32/64)
8       2     idVendor
10      2     idProduct
12      2     bcdDevice
14      1     iManufacturer
15      1     iProduct
16      1     iSerialNumber
17      1     bNumConfigurations
```

### 8.2 配置描述符 (9 字节) + 接口描述符 (9 字节) + 端点描述符 (7 字节×N)

```text
配置描述符:
  bLength=9, bDescriptorType=2, wTotalLength, bNumInterfaces,
  bConfigurationValue, bmAttributes, bMaxPower

接口描述符:
  bLength=9, bDescriptorType=4, bInterfaceNumber, bAlternateSetting,
  bNumEndpoints, bInterfaceClass(0x08=MSC), bInterfaceSubClass(0x06=SCSI),
  bInterfaceProtocol(0x50=BOT)

端点描述符:
  bLength=7, bDescriptorType=5, bEndpointAddress(0x81=Bulk IN, 0x02=Bulk OUT),
  bmAttributes(0x02=Bulk), wMaxPacketSize, bInterval
```

---

## 9. Control Transfer Setup Packet (8 字节)

```text
Offset  Size  Field
0       1     bmRequestType: 数据方向 + 类型 + 接收者
1       1     bRequest: 请求码
2       2     wValue: 参数
4       2     wIndex: 索引
6       2     wLength: 数据长度

GET_DESCRIPTOR(Device):
  bmRequestType = 0x80 (Device-to-Host, Standard, Device)
  bRequest = 0x06 (GET_DESCRIPTOR)
  wValue = 0x0100 (Device Descriptor, Index 0)
  wIndex = 0x0000
  wLength = 0x0012 (18 bytes)

GET_DESCRIPTOR(Configuration):
  bmRequestType = 0x80
  bRequest = 0x06
  wValue = 0x0200 (Configuration Descriptor, Index 0)
  wIndex = 0x0000
  wLength = 0x00FF (255 bytes, 足够包含完整配置)
```

---

## 10. USB Legacy Support (BIOS Handoff)

### 10.1 Extended Capability

```text
HCCPARAMS1[31:16] → ExtCapPtr (以 32-bit 字为单位的偏移)

ExtCap 结构:
  DW0: ID[7:0], Next[15:8] (下一能力偏移，0=结束)
  
  ID=1: USB Legacy Support Capability
    DW0: ID=1, Next
    DW1: USBLEGSUP (BIOS/OS Ownership Semaphore)
      bit[0-15]: BIOS Semaphore (BIOS 写 1 占用)
      bit[16-31]: OS Semaphore (OS 写 1 请求所有权)
    DW2: USBLEGCTLSTS (Legacy Control)
```

### 10.2 Handoff 流程

```text
1. 读取 USBLEGSUP
2. 若 BIOS Semaphore (bit[0]) = 1:
   a. 写 USBLEGSUP: OS Semaphore (bit[16]) = 1
   b. 等待 BIOS Semaphore 清除 (超时 1s)
   c. 写 USBLEGCTLSTS: 清除所有 SMI 触发位
```

---

## 11. 错误处理与安全不变式

### 11.1 安全不变式

1. **不阻塞启动**：任何 xHCI 初始化步骤失败，只记日志，驱动返回 0（成功），不注册块设备
2. **超时保护**：所有硬件等待使用 TSC deadline，无无限循环
3. **Cache 一致性**：写入 DMA 缓冲区后执行 `wbinvd`
4. **DMA 缓冲区**：所有 DMA 内存通过 `kernel_api.dma->alloc_pages` 分配（低 4G，4K 对齐）
5. **端口重置安全**：重置超时后跳过该端口，不阻塞其他端口枚举

### 11.2 Completion Code 映射

| Completion Code | 含义 | 处理 |
|----------------|------|------|
| 0 | Success | 正常完成 |
| 1 | USB Transaction Error | 重试或报错 |
| 2 | Babble Detected | 报错 |
| 3 | USB Ring Stall | 端点 Stall，需 Clear Feature |
| 4 | Stop | 停止 |
| 5 | Short Packet | 部分完成，检查 residue |
| 13 | Event Data | 含事件数据 |
| 22 | Stream Protocol Error | 报错 |

---

## 12. 性能考虑

1. **TRB Ring 大小**：Command Ring 256 TRB，Event Ring 256 TRB，Transfer Ring 256 TRB
2. **Bulk 传输最大包**：USB 2.0 High-Speed = 512 字节，USB 3.0 Super-Speed = 1024 字节
3. **SCSI 传输粒度**：每次 READ(10)/WRITE(10) 最多 16 扇区 (8KB)，与 AHCI 一致
4. **轮询 vs 中断**：首版使用 Event Ring 同步轮询 + TSC deadline，后续升级 MSI-X 中断
5. **多 TRB 链式传输**：大数据传输拆分为多个 Normal TRB，最后一次设置 IOC

---

## 13. QEMU 测试配置

```text
# xHCI 控制器 + USB 大容量存储
-device qemu-xhci,id=xhci0
-device usb-storage,bus=xhci0.0,drive=usb0
-drive id=usb0,if=none,file=usb_test.img,format=raw

# USB 测试镜像创建 (FAT32, 64MB)
# Windows:
# fsutil file createnew usb_test.img 67108864
# 格式化为 FAT32 (需管理员权限)
```

---

## 14. 与现有驱动的对比

| 特性 | AHCI | NVMe | xHCI |
|------|------|------|------|
| PCI Class | 01/06/01 | 01/08/02 | 0C/03/30 |
| 命令模型 | Port CI 命令 | SQ/CQ Doorbell | TRB Ring + Doorbell |
| 中断 | IRQ (PIC) | 轮询 | 轮询 (首版) |
| 数据传输 | PRDT DMA | PRP DMA | USB Bulk Transfer |
| 协议层 | ATA FIS | NVMe 命令 | USB + BOT + SCSI |
| 复杂度 | ~700 行 | ~800 行 | ~1500 行 |
| 块设备名 | ahci0 | nvme0 | usb0 |

---

## 参考资料

1. Intel xHCI Specification Rev 1.2 (2019): https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf
2. USB Mass Storage Class Bulk-Only Transport Rev 1.0
3. SCSI Primary Commands (SPC-4) / SCSI Block Commands (SBC-3)
4. USB 2.0 Specification
5. USB 3.1 Specification