UFSHCI（UFS Host Controller Interface）是 UFS 主机控制器的软件可见接口规范，定义操作系统驱动如何通过寄存器、队列、doorbell、中断和 DMA 控制 UFS host controller。
核心问题
不同 SoC 厂商可以实现不同的 UFS 控制器硬件，但操作系统需要一个相对统一的驱动模型。UFSHCI 的作用类似“主机控制器和驱动之间的合同”：硬件按规范暴露寄存器和队列，驱动按规范提交请求、收完成、处理错误。
核心对象
| 对象 | 作用 |
|---|---|
| host controller registers | 控制器状态、能力、启动、复位和中断寄存器。 |
| transfer request list | 主机提交普通读写/查询命令的请求队列。 |
| task management request list | 主机提交 abort、reset 等任务管理命令的队列。 |
| doorbell | 驱动通知硬件“新请求已准备好”的寄存器位。 |
| completion interrupt | 控制器通知驱动请求完成或出错。 |
| DMA descriptor | 指向内存中命令、数据 buffer 和响应结构。 |
核心机制
一次简化提交流程：
driver fills request descriptor
driver maps DMA buffers
driver rings doorbell
controller sends UPIU
device completes request
controller writes completion
driver handles interrupt这里 rings doorbell 不是物理门铃，而是驱动写控制器寄存器，告诉硬件某个队列槽位可以执行。控制器随后通过 DMA 读取请求结构，经过 UPIU、UniPro、MIPI M-PHY 访问设备。
工程用途
- Linux、Android 或 RTOS 中实现 UFS host driver。
- 排查 UFS probe、队列卡死、中断丢失、DMA 错误、任务 abort 和 host reset。
- 根据控制器能力配置队列深度、电源管理、自动 hibernate 和错误恢复策略。
边界与常见坑
- UFSHCI 不是 UFS device 内部固件；它描述主机控制器接口。
- UFSHCI 不是 M-PHY/UniPro 规范；PHY 和链路层仍有独立配置和状态。
- probe 成功不代表链路稳定。后续高 gear、低功耗恢复、热状态和错误恢复都可能出问题。
- DMA buffer、cache coherency 和 IOMMU 配置错误会表现为随机 I/O 超时或数据错误。
- vendor 控制器可能有私有寄存器和 errata，通用驱动仍需平台 glue 代码配合。