简介UFS driver 源码包聚焦通用闪存存储UFS在 U-Boot 引导加载程序中的驱动适配面向嵌入式系统移植工程师与存储驱动开发学习者解决 U-Boot 启动阶段无法识别和操作 UFS 设备的问题。资源以精简源码形式展示 UFS 协议命令、硬件接口初始化、DMA 数据传输、中断及错误处理等核心实现适合用于理解驱动分层与 U-Boot 设备注册流程。包体为 rar 压缩格式共 7 个文件包含 3 个头文件、3 个 C 源文件和 1 个 Makefile整体仅 20KB便于快速阅读和集成。头文件用于声明寄存器与接口结构C 文件分别实现主机控制器操作、协议工具函数等逻辑Makefile 简化编译接入。源码将硬件相关接口与协议处理拆分为独立模块体现了清晰的层次划分可供二次开发时参考移植。目前已有 1537 人学习浏览适合有一定 U-Boot 或存储驱动基础、希望深入 UFS 驱动实现的开发者使用。1. UFS driver 出问题最直观的后果是明明换了 UFS 4.0跑分却和 eMMC 差不多同样一颗 UFS 4.0 芯片放到两台设备上一台开机只要 8 秒一台要 20 秒同样跑 4K 随机写一台稳定输出高带宽一台掉到跟 eMMC 一个量级。九成问题不在闪存颗粒而在 UFS driver——也就是内核里负责把主机控制器、设备、电源、时钟和命令队列串起来的那一层软件。UFS driver 要做的并不只是让系统识别出一个设备节点它要做初始化握手、电源管理、链路速率协商、错误恢复和固件更新。搞定它系统性能与稳定性就赢了一半。这篇文章面向嵌入式 BSP、内核驱动开发和存储测试工程师按「驱动栈 → 跑通 → 调优 → 排错 → 验证」的路径展开所有命令都可以直接上板复现。2. UFS 驱动栈从主机控制器到 block 层四层协作怎么分活UFS driver 不是一个孤立的文件而是一整条路径上的多层软件组合。常见做法是把这层软件拆成四段UFS 主机控制器驱动UFSHCI、平台驱动、SCSI 层、block 层。排错时如果分不清「日志是从哪一层打出来的」很容易在平台上瞎调参数调半天发现是协议层的命令超时。2.1 主机控制器与门铃机制命令是从哪一端被接走的UFS 主机控制器UFSHCI在 Linux 里由 ufshcd 核心驱动管理。它维护一组传输描述符每个描述符对应一条待处理的命令驱动把 SCSI 命令封装成 UFS 协议规定的 UPIU 包组织成一整批描述符再写入门铃寄存器通知控制器「这边有活干」。控制器完成后会更新完成列表并触发中断。/* 示意提交一条命令到 UTR 槽位然后由中断负责回收 */ writel(1 slot, base doorbell_reg); /* 门铃寄存器用来提交不是用来轮询的确认中断还是要靠 ISR */这段示意代码里的门铃寄存器名要以具体主机控制器手册为准不同版本 UFSHCI 的偏移不完全一致。要点是门铃机制本身写 1 表示提交硬件收下后内存里的描述符才生效。这也是 UFS 与 eMMC 的一个显著差异——eMMC 的命令提交路径短UFS 走的是描述符列表加门铃加中断的完整 DMA 路径链路一长出问题的点就多。中断丢失或者门铃没清掉最典型的表现就是命令超时。2.2 平台驱动的分工ufshcd 核心与厂商驱动的差异Linux 把 UFS 驱动分成两层。ufshcd 这层处理协议和设备管理的通用逻辑设备描述符读取、电源模式状态机、错误恢复、命令队列管理。而平台驱动负责差异化的部分PHY 参数、时钟树、pinctrl、电源轨控制、UFS 版本特性开关。平台驱动通常以「ufs-平台名」这类模块存在和 ufshcd 核心是一对多的关系。这样分层的原因很直接PHY 硬件各家完全不同但 UFS 协议是统一的。核心层稳住了换平台只需要关注平台驱动里那几十个回调。排查日志时也要按这个思路分看到 ufshcd 前缀的消息先想协议侧看到平台模块名前缀的消息先想硬件侧。# 查看当前系统加载的 UFS 相关模块 lsmod | grep -i ufs # 查看平台驱动总线上有哪些 UFS 控制器的驱动实例 ls /sys/bus/platform/drivers/ | grep -i ufs第一段命令确认驱动有没有加载成功第二段命令确认平台驱动是否匹配到了设备树节点。如果第二段返回空说明 compatible 没匹配上后面所有调试都不用继续了。2.3 SCSI 与 block 层为何 UFS 设备总是一个 SCSI 磁盘UFS 的命令集基于 SCSI不是 eMMC 那种简化的块命令集。所以 Linux 会把 UFS 控制器注册成一个 scsi host每个 LUN 注册成 /dev/sdX再走通用的 block 层。文件系统、分区工具、fio、iostat 全都压在这条标准路径上。# 确认设备的传输类型和厂商型号 lsblk -d -o NAME,TRAN,MODEL,SIZE # 观察块层吞吐和 IO 队列深度 iostat -x 1lsblk 里 TRAN 一列只要显示 ufs就说明 SCSI 层和 block 层已经正常衔接。iostat 里的 avgqu-sz 和 %util 是判断队列深度是否打满的第一手指标。很多性能问题到最后会发现瓶颈不在驱动而在 block 层调度或者文件系统所以这一层不能省。3. 把 UFS 驱动跑起来probe 到设备可见的最小流程一块 UFS 设备从「上电」到「系统里出现可用磁盘」中间有一长串步骤设备树匹配、probe、资源获取、电源和时钟准备、主机控制器复位、UTP 任务列表建立、设备握手、LUN 扫描、scsi host 注册。任何一个环节断了表现都可能是同一个——设备节点不出现。3.1 设备树最小配置reg、中断、电源与时钟节点设备树是 UFS 驱动跑起来的第一关。最少需要 reg 提供控制器寄存器基地址interrupts 提供完成中断clocks 和 clock-names 提供参考时钟和核心时钟再配合电源轨 supply 节点。缺一个probe 就会在某个资源获取阶段提前返回。/* UFS 控制器设备树节点兼容字符串以实际平台为准 */ ufs12300000 { compatible example,ufs-controller; reg 0x12300000 0x1000; interrupts 0 102 4; /* 三个时钟参考时钟、核心时钟、总线时钟 */ clocks ref_clk, core_clk, bus_clk; clock-names ref_clk, core_clk, bus_clk; vcc-supply reg_vcc; vccq-supply reg_vccq; vccq2-supply reg_vccq2; /* 三组时钟的 min/max 频率0 表示交给驱动按需处理 */ freq-table-hz 0 0, 0 0, 0 0; };这里的关键是时钟顺序必须跟 clock-names 一一对应电源轨也不能漏。freq-table-hz 是三组min max如果填 0 0表示驱动不强制调整该时钟频率交给时钟框架自己管理。新平台 bring-up 阶段我一般先全部填 0 0等通信稳定再逐个上频率这样好定位是哪个时钟引入的问题。3.2 probe 到注册数据设备的过程平台驱动的 probe 函数通常只做两件事准备资源和调用 ufshcd 核心的初始化接口。资源准备包括映射寄存器、获取中断号、可选的电源轨获取剩下的链路初始化、电源模式切换、LUN 注册都在核心初始化里完成。static int ufs_platform_probe(struct platform_device *pdev) { struct device *dev pdev-dev; void __iomem *base; int irq, ret; /* 第一步拿到控制器寄存器地址和中断号 */ base devm_platform_ioremap_resource(pdev, 0); if (IS_ERR(base)) return PTR_ERR(base); irq platform_get_irq(pdev, 0); if (irq 0) return irq; /* 第二步交给 ufshcd 核心完成剩余的初始化流程 */ ret ufshcd_pltfrm_init(pdev, platform_vops, platform_cfg); if (ret) { dev_err(dev, ufs init failed: %d\n, ret); return ret; } return 0; }ufshcd_pltfrm_init 内部会依次完成控制器能力读取、UTP 任务列表建立、UFS 设备描述符读取、LUN 扫描、scsi host 注册。这个接口返回 0 不代表设备已经完全可用只能代表控制器层面的初始化没报错。probe 日志里如果出现 ufshcd 字样但后面没有 scsi host 注册信息多半是 UFS 设备握手失败需要去查电源或者时钟。3.3 确认驱动工作正常的三个检查点设备树配好了probe 也过了接下来不是直接跑性能而是先用三个检查点确认整条链路是通的。# 检查点一设备树匹配和 probe 日志 dmesg -T | grep -iE ufshcd|ufs # 检查点二块设备是否按 UFS 传输类型出现 lsblk -d -o NAME,TRAN,MODEL,SIZE # 检查点三整盘可读性最基础验证 dd if/dev/sda of/dev/null bs1M count256 statusprogress三个检查点分别对应驱动有没有匹配、SCSI 层有没有注册成功、数据面能不能转起来。dd 只要不报 I/O error 就算通过但注意它只能证明「能读」不能证明「读得对」。数据完整性要靠后面的 fio 校验场景来确认。新手最容易在这一步看到 /dev/sda 出现就以为大功告成实际链路降速、电源不稳这类问题 dd 根本看不出来。4. 调好 UFS 驱动时钟、电源轨与 Gear 协商的边界UFS 驱动调优的核心不是把某个参数调到最大而是搞清楚每个参数的真实边界。电源轨电压、参考时钟频率、Gear 协商结果、队列深度这些参数相互牵制只调一项往往会在另一项上翻车。4.1 三路电源轨与参考时钟的选择UFS 设备通常需要三路供电含义完全不同。VCC 负责闪存内部核心供电VCCQ 是 M-PHY 和控制器 IO 的电源VCCQ2 是低电压逻辑部分。三路电源的上电顺序、稳定时间、电压值都会影响链路握手。参考时钟则要匹配 SoC 的 PHY 设计常见有 19.2MHz、26MHz、52MHz 几档。电源轨典型作用常见电压范围调试重点VCCNAND 闪存核心供电2.5V ~ 3.6V上电稳定时序VCCQM-PHY / 控制器 IO1.2V ~ 1.8V与 PHY 摆幅匹配VCCQ2低电压逻辑1.8V 左右掉电检测阈值调电压不是越大越好VCCQ 给高了反而可能损伤 PHY 信号质量。我的做法是先按规格书的典型值配置然后用示波器在设备端量 VCC 的上升沿确认从 regulator 使能到电压稳定之间的时间足够。这个时序如果不对UFS 驱动看起来一切正常但第一条命令就可能超时。# 查看 UFS 相关时钟在时钟树里的实际频率 grep -i ufs /sys/kernel/debug/clk/clk_summaryclk_summary 里能看到参考时钟当前跑在哪个频率。如果在这里看到的频率和设备树里预期不符优先查 clock driver 的父时钟配置而不是怀疑 UFS 驱动本身。4.2 Gear 协商为什么协商结果经常不是标称值UFS 链路不是开机就直接满速。驱动会先从低速模式建立基本通信再逐步往高速 Gear 升速。Gear 协商是链路握手的结果不是驱动配置项。信号质量、PHY 参数、PCB 走线、参考时钟抖动都会影响协商结果驱动只能按协商出来的速率工作。# 从启动日志里看链路速率协商结果 dmesg -T | grep -iE ufshcd | grep -iE gear|pwm|lane日志里能看到类似 gear、lane、PWM、HS 这样的字眼。如果协商结果长期停在低档位先别急着在驱动里强制指定高速 Gear而是回头查 PHY 调优参数。强制指定 Gear 在信号质量不支持的情况下会导致链路反复重协商吞吐比停在低档位更难看。这个坑我踩过一次为了让跑分好看强行把协商档位拉高结果随机读写直接掉了一个数量级。4.3 队列深度与 WB/HPB 特性UFS 支持命令队列队列深度直接决定小 IO 场景的并发能力。驱动默认会按控制器能力设置一般不用手动去加大。真正值得关注的是两个特性WriteBooster 和 HPB。WriteBooster 用 SLC 缓存吸收写入突刺对随机写提升明显HPB 则把设备内部的逻辑到物理映射缓存给主机缩短读命令的延迟。这两个特性都有前提设备本身支持内核配置打开驱动在初始化时读到的设备描述符里能力位正确。判断方式很简单——启动日志里或设备描述符信息里能看到对应特性名。看不到先查内核 config再看设备固件版本。很多时候设备规格书支持但量产固件把特性关了这时候找驱动厂家没用得推设备固件更新。5. UFS 驱动避坑电源时序、命令超时与 FFU 升级这一章是血泪经验的集合。每个问题都按「现象 → 原因 → 解决」展开直接对应我在不同平台和不同芯片方案上实际排查过的场景。5.1 电源时序导致设备失踪现象设备树和驱动代码看起来完全没问题probe 也返回成功但系统里始终只有一个空 scsi host一个 LUN 都扫不到。dmesg 里能看到 ufshcd 初始化日志却没有任何设备版本信息。原因UFS 设备的电源时序要求严格。VCC 稳定之前 VCCQ 不能先上参考时钟要等供电稳定后才能打开。某个平台上我第一次调的时候没注意时钟和电源的顺序导致每次冷启动 50% 概率设备消失。解决修改设备树 regulator 节点的 rise-time 和 settle-time或者干脆在 platform 驱动 probe 早期用 regulator API 显式控制上电顺序。调试阶段可以在初始化接口调用前加一段延时确认问题就是时序引入的。/* 调试片段先按序打开电源轨再给时钟留出稳定窗口 */ regulator_enable(vcc); regulator_enable(vccq); udelay(1000); /* 这个延时按规格书要求调整不能随便拍脑袋 */这个片段只是调试定位用量产正确的做法是在 regulator 里配好上电时序。顺带一提有的平台把 UFS 的复位脚接在 GPIO 上复位信号拉低时间不足也会有类似现象排查时记得一起看。5.2 SCSI 命令超时与中断丢失现象系统运行一段时间后dmesg 里出现 scsi 层的命令超时报警伴随文件系统只读或者 IO hang。重启后又正常跑一段时间再复现。原因中断没有真正到达 CPU。常见两种情况中断号在设备树里配错或者是共享中断里 UFS 中断源没有正确使能另一种是 runtime PM 把 UFS 相关时钟关了但命令还在队列里。解决第一步看中断计数是否增长第二步查时钟是否被 PM 关掉。# 看 UFS 中断发生次数确认中断是否真的在触发 grep -i ufs /proc/interrupts如果中断计数不动说明中断配置有问题计数在涨但命令还是超时优先查中断线程里的错误处理路径。还有一个容易被忽略的点UFS 的错误处理会先把队列全部清空再重新初始化这个过程中如果有新的 IO 进来会被直接丢到超时处理。遇到这种情况检查错误处理的 busy 标志位处理是否完整。5.3 链路降速到 PWM 模式现象顺序读写速度远低于预期dmesg 里链路协商结果停在低速率档位而且会看到链路错误计数增长。原因链路协商过程中出现 CRC 校验错误或者 PHY 自适应失败驱动自动降速重协商。常见诱因是 PCB 走线过长、参考时钟抖动过大、或者 PHY 的阻抗配置和实际硬件不匹配。解决先确认是不是每次都在同一个速率档位失败如果是缩小范围到 PHY 参数如果不是重点查参考时钟和供电稳定度。在 debugfs 里找 UFS 的错误历史记录看具体的错误类型。# 如果内核开启了 debugfs查看 UFS 错误记录 ls /sys/kernel/debug/ufshcd/ cat /sys/kernel/debug/ufshcd/*/error_history 2/dev/null如果 debugfs 没有对应目录可以看 tracefs 里有没有 ufshcd 相关事件。链路降速这事玄学成分很高正交实验是最可靠的定位手段一次只改一个 PHY 参数记录协商结果不要同时调摆幅和阻抗否则根本不知道是谁生效。5.4 FFU 升级中断在半路现象执行固件升级时进度到一半命令超时设备直接消失重新上电后不再枚举。这块盘在系统里彻底看不到了。原因升级过程中有并发 IO 打断写入流程或者固件包校验失败后驱动没有正确处理错误恢复。UFS 的 FFU 流程要求设备先进入专用模式写入过程中不能有普通 IO 干扰。解决升级前必须先停掉所有对这个设备的 IO并且确认系统没有后台的 fstrim、日志写入等任务。升级过程中不要碰设备节点等工具自己退出。# 升级前的基本准备流程 sync # 停掉文件系统上可能的后台任务 # 执行平台各自提供的 UFS 固件更新工具进入 FFU 模式写入 # 工具退出后需要重新枚举确认固件版本如果升级失败导致设备不枚举了多数平台能用强制下载模式恢复但恢复流程和工具因平台而异务必提前确认。量产之后再做 FFU风险比开发阶段大很多。我的习惯是能出厂前烧好就绝不依赖 FFUFFU 只作为售后补救手段。5.5 排查日志怎么分级查UFS 的问题日志分三层ufshcd 核心层、平台驱动层、SCSI 层。三层日志的关键字前缀不同查的时候分开抓效率要高得多。# 分层抓取 UFS 相关日志 dmesg -T | grep -i ufshcd # 核心协议层 dmesg -T | grep -i ufs-xxx # 平台驱动层xxx 换成具体模块名 dmesg -T | grep -iE sd[a-z].*timeout|scsi.*timeout # SCSI 层先看平台驱动层有没有资源获取错误再看核心层的设备握手日志最后才查 SCSI 超时。很多同事一上来就盯 scsi timeout绕过了真正的问题源头。超时只是结果不是原因。驱动层如果已经报设备忙或者链路错误SCSI 层超时是必然的修 SCSI 层没有意义。6. 验证 UFS 驱动的最后一步数据完整性检查与 trace 定位驱动跑通只是开始真正让人放心的是数据完整性验证和命令路径的可观测性。这一步能找出不少「看起来正常但实际有隐患」的问题。6.1 用 fio 带校验跑一轮完整读写普通 dd 只验证能不能读fio 的 verify 模式会在写入时记录校验值读取时重新计算对比任何一位翻转都能被发现。# 4G 空间、4K 块、70% 读 30% 写混合带 CRC32C 校验 fio --nameufs-verify --filename/dev/sda --direct1 \ --rwrandrw --rwmixread70 --bs4k --iodepth32 \ --verifycrc32c --verify_backlog1024 \ --size4G --numjobs1 --group_reportingverify 参数让 fio 在写 IO 的同时记录校验上下文读取阶段复核。出现校验失败时先换一块盘确认是不是盘本身的问题再考虑驱动。如果固定在某几个 LBA 出错很大概率是设备固件的问题如果是随机 LBA 出错优先怀疑数据路径上的 DMA 或者 PHY 信号完整性。6.2 用 block 层 trace 定位命令延迟链路能力确认没问题之后还要看命令在块层的实际延迟分布。用 trace 挂上块层事件看每个 IO 从下发到完成的时间间隔能快速区分是队列堆积还是设备响应慢。# 挂上块层请求事件然后触发一小段 IO echo 0 /sys/kernel/tracing/tracing_on echo block:block_rq_issue /sys/kernel/tracing/set_event echo 1 /sys/kernel/tracing/tracing_on dd if/dev/sda of/dev/null bs4k count1000 echo 0 /sys/kernel/tracing/tracing_on看 trace 输出里同一批 IO 的 issue 和 complete 时间差。如果延迟均匀且都在正常范围驱动数据路径基本没问题如果出现明显毛刺下去查中断上下文和电源管理。后来我养成一个习惯新板子回来先跑一轮 crc32c 校验再改任何驱动参数。这个习惯救过我至少两次也让我在排查问题时少走一半弯路。希望帮到你。本文还有配套的精品资源点击获取
