UFS_软件设计规范http://39.108.239.75:5001/share/yGwX6KZLZUaOa09lUFS 软件设计规范编制日期 2026-09-24 版本号 Rev 1.5UFS-SW-SPEC-001 · V1.0面向嵌入式与移动终端UFSUniversal Flash StorageJEDEC JESD220 系列主机侧驱动的设计约束与推荐实现 覆盖协议栈与 UPIU 事务模型、初始化状态机、Descriptor / Flag / Attribute 配置体系、LU 逻辑单元管理、读写擦命令序列、RPMB 与写保护、掉电保护、低功耗与错误恢复逐条给出可落地的判据与流程。18章节6附录4 KB逻辑块大小32任务队列深度文档编号UFS-SW-SPEC-001版本 / 状态V1.0 · 正式发布适用器件JEDEC UFS 2.0 / 2.1 / 3.0 / 3.1 / 4.0JESD220B~F器件容量 32 GB ~ 1 TB基准器件UFS 3.1 器件HS-G32 laneVCCQ1.2 V / VCCQ21.8 V4 KB 逻辑块LU 队列深度 32文中标注「本器件」的数值取自该档器件典型手册值参考标准JEDEC JESD220F / EUFS 4.0 / 3.1· MIPI UniPro v2.0 · MIPI M-PHY v5.0 · SCSI SPC-4 / SBC-3 / SAM-4配套文档UFS_电路设计指南.html电源时序 / REF_CLK / 差分 Layout / SI 与故障排查0 · 文档说明0.1 目的与范围本规范约束 UFS 主机侧驱动的命令序列、配置口径、判据与超时预算目标是让不同平台、不同人员的实现保持一致避免能跑但不稳的实现进入量产。与 eMMC 最大的差别在于UFS 是基于 UPIU 的事务模型 SCSI 命令集且引入了任务队列与三态配置对象Descriptor / Flag / Attribute。范围内主机驱动UFS Host Controller Driver的初始化、读写擦、配置管理、Boot、RPMB、掉电保护、低功耗、错误恢复与 API 语义。范围外① M-PHY / UniPro 链路层以下的实现由主控 IP 提供② 文件系统与 FTL 策略器件内部实现主机不可见③ UFS 卡JESD223的热插拔协议④ 具体 SoC 寄存器编程细节。0.2 文档使用说明「必须 / 禁止」表示硬性约束违反会导致可靠性问题或量产事故。「建议 / 推荐」表示经验值可按平台能力调整但需记录理由。所有0x前缀为十六进制b前缀表示 1 字节字段Byted前缀表示 4 字节Dwordw前缀表示 2 字节Word沿用 UFS 规范的匈牙利命名。IDNIdentifier Number等具体编号以所选器件手册为准本文给出的是常见档位的典型值。硬件相关电源、时钟、复位、Layout问题请先查《UFS 电路设计指南》。0.3 书写约定记号含义示例bXxx1 字节字段 / AttributebBootLunEndXxx4 字节字段dNumAllocUnitswXxx2 字节字段wManufacturerIDfXxxFlag布尔fDeviceInitLU n第 n 个逻辑单元LU 0、LU 1W-LUNWell-Known LU特殊功能单元RPMB0x441 · 器件定位与协议栈架构UFS 把「SCSI 命令集」搬进了嵌入式存储主机发的是标准 SCSI CDB传输靠 UPIU 事务包底层是 UniPro M-PHY 串行链路。理解这套分层才能看懂后面的所有命令序列。1.1 定位与关键参数维度典型值说明命令集SCSI SPC / SBC 子集主机下发标准 CDB传输单元UPIUUFS Protocol Information Unit命令、数据、响应、任务管理、查询逻辑块大小4 KB主流由bLogicalBlockSize决定部分器件支持 512 B逻辑单元LU 0~7最多 8 个可配置 LU 若干 W-LUN队列深度≤ 32每 LU由bLUQueueDepth与主机能力取小单次 UPIU 负载≤ bMaxDataIn/OutSize × 512 B典型 8~324~16 KB双工全双工读写可并发安全区RPMB独立认证访问通道1.2 协议栈四层模型层规范职责驱动可见性应用层UFS Command SetSCSI 子集读写擦、模式页、诊断、安全协议完全可见驱动构造 CDB传输层 UTPUFS Transport ProtocolUPIU 封装、Task Tag 管理、流控完全可见驱动组装 UPIU数据链路层MIPI UniPro连接建立、可靠传输、功耗管理部分可见通过主机控制器寄存器物理层MIPI M-PHYHS / PWM 模式、差分传输不可见硬件完成一句话分工驱动负责构造 CDB 并包成 UPIU主机控制器负责把 UPIU 交给 UniPro / M-PHY链路问题表现为 UPIU 超时或链路重训而不是 CDB 报错。1.3 UPIU 事务模型UPIU 是主机与器件之间交换的最小协议单元。常见事务类型与其事务码Transaction CodeUPIU 类型事务码方向用途NOP OUT / NOP IN0x00 / 0x20双向链路探测、保活COMMAND / RESPONSE0x01 / 0x21双向承载 SCSI CDB 与其响应DATA OUT / DATA IN0x02 / 0x22双向承载实际数据负载READY TO TRANSFERRTT0x31器 → 主流控告知可发送多少数据TASK MANAGEMENT REQ / RSP0x04 / 0x24双向中止任务、LU 复位等QUERY REQUEST / RESPONSE0x16 / 0x36双向读写 Descriptor / Flag / AttributeREJECT0x3F器 → 主拒绝非法 UPIU典型写事务COMMAND → RTT → DATA OUT → RESPONSE主机侧器件侧COMMAND UPIU (0x01)WRITE(10) CDB LBA 长度RTT UPIU (0x31)允许发送 N 个数据块DATA OUT UPIU (0x02)按 RTT 额度分批发送直到写完RESPONSE UPIU (0x21)SCSI Status Sense 数据关键约束DATA OUT 必须等 RTT不可一次全发每批不超过 bMaxDataOutSize响应中的 Status 非 GOOD 时必须取 Sense 判因Task Tag同一时刻最多 32 个在途任务由主机分配并回收图 1 · 典型写事务的 UPIU 交互序列COMMAND → RTT → DATA OUT → RESPONSE关于 RTT写方向由器件通过RTT控制节奏主机必须遵守额度不能一次把全部数据推下去读方向则由主机发 COMMAND 后等待DATA IN。这是 UFS 与发完就等的 eMMC 流程最大的不同。1.4 寻址LU 与 LBALULogical Unit是 UFS 的分区单位最多 8 个LU 0~7每个 LU 有独立的容量、逻辑块大小、写保护与队列深度。LBA在每个 LU 内独立编址从 0 开始命令中的 LUN 字段决定访问哪个 LU。W-LUNWell-Known LU不是存储区而是功能入口REPORT LUNS、UFS Device、Boot、RPMB。访问粒度是逻辑块典型 4 KB不是 NAND 页——主机看不到物理页与坏块这部分完全由器件 FTL 负责。1.5 与 eMMC 的关键差异对比项eMMCUFS配置方式EXT_CSD 512 BCMD6 单一入口Descriptor / Flag / Attribute 三类QUERY UPIU 读写命令模型CMD 响应半双工SCSI CDB UPIU全双工 队列并发单命令串行最多 32 个在途任务分区Boot / RPMB / GPP 分区LU 0~7 Boot LU RPMB W-LUN初始化CMD0/1/2… 提速链路启动 → NOP 探测 → fDeviceInit → 配置掉电通知Power Off NotificationCMD6START STOP UNITPower Down SYNCHRONIZE CACHE2 · 术语与缩写2.1 协议栈术语术语全称 / 含义UPIUUFS Protocol Information Unit主机与器件交换的协议包UTPUFS Transport Protocol传输层负责 UPIU 的封装与任务管理UniProMIPI 统一协议UFS 的数据链路层M-PHYMIPI 物理层UFS 的差分串行接口HS-GearHigh Speed GearM-PHY 高速档位G1~G5PWM-GearPulse Width Modulation Gear低速档位用于建链与休眠Lane一对收发差分线UFS 支持 1~2 laneTask Tag在途任务的编号最多 32 个主机分配CDBCommand Descriptor BlockSCSI 命令描述块RTTReady To Transfer器件发给主机的流控许可2.2 存储与 LU 术语术语全称 / 含义LULogical Unit逻辑单元UFS 的分区单位0~7W-LUNWell-Known LU功能型逻辑单元Boot / RPMB / Report LUNs / UFS DeviceLBALogical Block Address逻辑块地址LU 内从 0 编址Allocation Unit分配单元器件内部容量管理粒度Thin Provisioning精简配置LU 容量按需分配而非一次性占用UNMAPSCSI 命令释放逻辑块等价于 TrimPurgeUFS 的安全擦除操作使数据不可恢复RPMBReplay Protected Memory Block重放保护存储区2.3 特性与机制术语术语全称 / 含义WriteBoosterUFS 3.1 起的 pseudo-SLC 写缓存提升突发写性能HPBHost Performance Booster把 L2P 映射表缓存到主机内存以加速随机读FFUField Firmware Update现场固件升级Descriptor只读或可写的结构化配置块Device / Unit / Geometry 等Flag布尔型开关fDeviceInit / fPurgeEnable 等Attribute数值型参数bMaxDataInSize / bBootLunEn 等Query读写上述三类对象的 UPIU 事务SSUSTART STOP UNITSCSI 命令用于功耗状态切换Device Init器件内部初始化阶段由 fDeviceInit 触发需轮询等待完成3 · 驱动架构与初始化UFS 初始化比 eMMC 多两个环节链路启动UniPro/M-PHY和器件内部初始化fDeviceInit。跳过或判错这两步是 Bring-up 阶段最常见的坑。3.1 分层职责层次职责典型实现Block / 文件系统提交 bio / 请求管理脏页与回写内核通用层无 UFS 特有逻辑UFS 驱动核心UPIU 组装、Task Tag 管理、错误恢复、电源管理UFS Host Controller Driver主机控制器HCIDoorBell 寄存器、DMA 传输列表、中断SoC IP寄存器编程UniPro / M-PHY链路建立、HS 训练、功耗状态硬件 PHY 固件驱动核心要管好三件事①Task Tag 池分配、回收、超时回收②错误恢复区分链路级重训与命令级重试/复位③电源状态与 Runtime PM 联动唤醒后正确地恢复链路。3.2 上电初始化流程UFS 上电初始化流程硬件链路 → 软件配置 → 就绪① 电源与时钟就绪VCC / VCCQ / VCCQ2 稳定REF_CLK 输出释放 RST_n② UniPro 链路启动PWM 建链 → 协商 → 切换 HS-Gear硬件完成③ NOP OUT / NOP IN 探测确认 UTP 层可用失败则判为链路未通④ 读 Device / Geometry Descriptor获取厂商、型号、容量、队列能力⑤ 置位 fDeviceInit 并轮询器件内部初始化未完成时禁止下发数据命令⑥ 下发配置并枚举 LUbMaxDataIn/OutSize、电源模式REPORT LUNS 枚举步骤 ⑤ 是最易出错的环节fDeviceInit 置位后需轮询该 Flag 直至器件清除期间下发读写会返回错误或产生不可预期行为步骤 ③ 失败时的判定NOP 无响应 链路未通优先查硬件电源、REF_CLK、RST_n、焊接而不是反复重试软件流程步骤 ⑥ 的配置顺序先配 bMaxDataInSize / bMaxDataOutSize影响吞吐再配电源模式与 LU 属性最后枚举 LU超时预算建议初值按平台调整链路启动秒级硬件完成驱动等待中断NOP 探测100 ms ~ 1 sfDeviceInit 轮询建议上限 5 s超时应报错而非死等普通读写命令按数据量估算小命令建议 1~5 sFORMAT UNIT / Purge分钟级必须给足超时初始化完成后驱动应记录器件型号 / 固件版本 / HS-Gear / lane 数 / 逻辑块大小 / 各 LU 容量供后续诊断使用图 2 · UFS 上电初始化流程硬件链路 → NOP 探测 → 读 Descriptor → fDeviceInit → 配置与枚举两条硬规则①必须在 NOP 探测成功后才继续NOP 无响应时不许反复重试——那是硬件问题②必须轮询fDeviceInit直到器件清除该标志未完成前禁止下发任何读写命令。3.3 器件识别与能力协商读取项来源用途wManufacturerIDDevice Descriptor厂商识别用于 quirk 匹配产品型号 / 固件版本Device Descriptor / String Descriptor版本追踪与升级判断dNumAllocUnits 单元大小Geometry / Unit Descriptor计算 LU 容量bLogicalBlockSizeUnit Descriptor逻辑块大小常见 12 → 4 KBbLUQueueDepthUnit Descriptor队列深度上限bMaxDataInSize / OutSizeAttribute单次 UPIU 数据负载上限bBootLunEn / Boot 能力Attribute / Device Descriptor是否支持启动能力协商原则主机能力 ∩ 器件能力取交集。若主控 M-PHY 只支持 HS-G3 而器件是 UFS 4.0链路会在 HS-G3 上工作软件不应按器件标称的最高性能来做调度假设。3.4 配置下发与生效配置分三类下发Attribute 写值数值、Flag 置位/清除/翻转布尔、Descriptor 写结构块仅部分可写。bMaxDataInSize/bMaxDataOutSize必须在第一次数据传输前配置取值受主控 DMA 与器件能力共同限制。部分配置如 LU 容量、写保护需要 LU 处于未使用状态或需要下电复位才生效务必查手册。配置完成后建议回读校验写入后再 Query 读一次确认值已生效且未被器件拒绝。3.5 初始化自检清单三路电源电压与时序符合硬件规范见配套硬件文档。REF_CLK 已稳定RST_n 已释放且低电平时间充足。链路启动完成HS-Gear 与 lane 数符合预期。NOP OUT/IN 成功返回。Device Descriptor 读取成功厂商与型号符合 BOM。fDeviceInit 已置位并轮询到清除。bMaxDataInSize / bMaxDataOutSize 已配置并回读校验。REPORT LUNS 枚举成功LU 数量与容量符合预期。初始化日志已记录型号 / 固件 / Gear / lane / 块大小。4 · Descriptor / Flag / AttributeUFS 的配置体系是「三类对象 一个 Query 通道」。与 eMMC 的 EXT_CSD 相比更结构化但也更容易写错时机。4.1 三类配置对象类型形态访问方式典型成员Descriptor结构化数据块若干字节READ / WRITE DESCRIPTORDevice、Geometry、Unit、Power、HealthFlag布尔True / FalseREAD / SET / CLEAR / TOGGLE FLAGfDeviceInit、fPurgeEnable、fBackgroundOpsEnAttribute数值1 / 2 / 4 字节READ / WRITE ATTRIBUTEbBootLunEn、bMaxDataInSize、bCurrentPowerMode4.2 Query Request / Response三类对象都通过QUERY REQUESTUPIU0x16访问器件回QUERY RESPONSE0x36。请求包里用Function操作码与IDN对象编号定位目标。Query Request / Response三类对象的统一访问通道QUERY REQUEST UPIU0x16Transaction Code 0x16Function操作码IDN对象编号IndexLU 序号等SelectorValue / Data写操作携带0x01~0x08见附录 BQUERY RESPONSE UPIU0x36Transaction Code 0x36Response 字段成功 / 失败原因Value / Data读操作返回判据先看 Response 字段非成功时不得使用返回数据常见失败原因对象不可写、时机不允许、参数越界建议写后立即回读校验图 3 · Query Request / ResponseFunction IDN Index 定位对象先看 Response 再信数据Function操作码作用READ DESCRIPTOR0x01读取 DescriptorWRITE DESCRIPTOR0x02写入可写 DescriptorREAD ATTRIBUTE0x03读取 AttributeWRITE ATTRIBUTE0x04写入 AttributeREAD FLAG0x05读取 FlagSET FLAG0x06置位 FlagCLEAR FLAG0x07清除 FlagTOGGLE FLAG0x08翻转 Flag4.3 Descriptor 清单DescriptorIDN主要内容可写性Device Descriptor0x00厂商、型号、LU 数量、Boot 能力、队列深度只读Configuration Descriptor0x01当前配置状态部分字段可写部分可写Unit Descriptor0x02每 LU 的容量、块大小、写保护、队列深度部分可写Interconnect Descriptor0x04UniPro / M-PHY 参数只读为主String Descriptor0x05型号名、固件版本等字符串只读Geometry Descriptor0x07总容量、分配单元大小、最大块数只读Power Parameters Descriptor0x08各功耗状态的电流与超时参数只读Device Health Descriptor0x09寿命估计、EOL 信息、异常计数只读RPMB Unit Descriptor版本相关RPMB 区域大小与特性只读注IDN 取值在不同 UFS 版本间存在差异实现前请以器件手册核对RPMB Unit Descriptor 的编号随版本变化本文不给出固定值。4.4 Flag 与 Attribute 清单FlagIDN作用备注fDeviceInit0x01触发器件内部初始化置位后需轮询至清除fPermanentWPEn0x02永久写保护使能不可逆慎用fPowerOnWPEn0x03上电写保护使能下电后失效fBackgroundOpsEn0x04后台操作使能建议保持开启fPurgeEnable0x06Purge 操作使能执行 Purge 前先置位fWriteBoosterEn0x0EWriteBooster 使能3.1配合缓存容量配置fHPBEn0x10HPB 使能3.1需主机侧配套实现AttributeIDN作用备注bBootLunEn0x00启动 LU 使能01h Boot LU A02h BbCurrentPowerMode0x02当前功耗模式只读为主用于状态确认bActiveICCLevel0x03Active 状态电流档位0~15越大性能越高bOutOfOrderDataEn0x04乱序数据传输使能按需开启bBackgroundOpStatus0x05后台操作状态用于判断是否需让行bPurgeStatus0x06Purge 操作状态轮询判断完成bMaxDataInSize0x0A读方向单次 UPIU 负载单位 512 BbMaxDataOutSize0x0B写方向单次 UPIU 负载单位 512 BbRefClkFreq0x0D参考时钟频率与硬件设计一致bDeviceLifeTimeEstA/B/C见手册寿命估计Device Health见 §12注上表 IDN 为常见档位典型值UFS 4.0 新增字段较多实现前请以器件手册核对。4.5 写入准则与生效时机先读后写修改前先读回当前值避免覆盖其他位。写后回读写入后立即 Query 读一次确认生效。判 ResponseQuery Response 非成功时不得认为配置已生效。注意时机LU 容量、写保护类配置通常要求 LU 无在途 IO甚至要求下电复位。不可逆操作二次确认永久写保护、Purge、FFU 等不可逆操作必须在上层增加显式确认与日志。并发保护Query 通道在同一时刻应串行化避免多线程同时下发 Query 造成竞态。4.6 常见陷阱陷阱表现规避未等 fDeviceInit 完成就下发 IO命令返回错误或行为异常轮询 Flag 至清除设超时上限把 Descriptor 当普通内存改写只读字段写失败、配置无效区分可写性只改允许字段写 Flag 用错 Function本想置位却做了翻转明确使用 SET / CLEAR不用 TOGGLE忽略 Query Response配置静默失败问题延后爆发统一封装非成功即报错多线程并发 Query偶发配置错乱Query 通道加互斥锁按 eMMC 经验找 EXT_CSD概念错位、配置无处下手改用三类对象 Query 通道后续章节请下载「芯参谋」查看……篇幅原因, 还有20章· 详见芯参谋→方案设计当前分享仅开放前5章正文。详细资料请在芯参谋客户端中打开完整文档。打开路径解决方案应用市场分析 - 原理方案设计 - UFS_软件设计规范 下载芯参谋客户端