SDMMC写eMMC报TXUNDERR：冷启动偶发欠载的排查与修复

第一次在SDMMC1上报TXUNDERR的时候我其实并不慌。FIFO欠载这类错误多数情况下调一调watermark就能压下去。真正让我警觉的是它的组合条件冷启动必现、热重启不现、只写不读、而且不是100%复现是那种“隔几次冷启动冒出来一次”的间歇性中断。这类问题最磨人的地方在于它能顺利通过所有常规单元测试却在产线长时间老化或者用户正常使用一段时间后突然冒出来一条dmesg日志往往还没看明白上下文现场就过去了。这篇文章我打算把它当成一个完整的排查案例来写梳理SDMMC1控制器在写eMMC时报TXUNDERR发送欠载的硬件机制、常见根因、定位手段和能落地的修复方案。适合正在调eMMC/SD驱动、做BSP bring-up或者手头刚好有类似“冷启动偶发报错”问题的嵌入式工程师参考。如果你只是被分配到一个bug单、连复现都没复现出来那这篇文章也能帮你少走不少弯路至少知道第一次现场该抓什么数据而不是等下一次复现。1. 先搞清楚TXUNDERR到底在报什么1.1 从数据通路讲起写eMMC时数据是怎么走的SDMMC控制器向eMMC写数据链路大体是这样的CPU或DMA把数据从DDR搬到控制器内部FIFO控制器再按照卡的时钟CLK节拍把FIFO里的数据一位一位推到DATA线上eMMC在时钟沿采样。这里的TXUNDERR全称是Transmit Underrun对应发送方向FIFO欠载控制器从FIFO取数的时候发现FIFO已经空了但发送动作还没结束。类比一下就是水龙头已经开到最大但水桶还没接满水闸门就先打开了水管里流着流着就断了气。对SD/eMMC这种同步串行总线来说发送一旦开始就不能停因为CLK一直在走数据必须每个节拍都有效。如果中间出现一个空拍接收方采样到的就是无效数据轻则命令超时重则触发CRC错误或控制器直接上报欠载中断。读操作就不太一样。读的时候数据是从eMMC流进控制器的FIFO再由DMA搬走虽然也有FIFO溢出overrun的可能但接收侧的时序容错比发送侧宽松一些。况且很多控制器读路径有独立的接收FIFO和水位判断和发送路径不是同一套逻辑。所以同一个控制器写方向对时序敏感得多。1.2 冷启动条件为什么这么关键“只有冷启动复现”是这个问题最有价值的信息。冷启动和热启动的硬件初始化路径差异很大冷启动时电源从零开始爬升复位释放的顺序由硬件逻辑决定SoC内部很多外设时钟默认走慢速时钟源PLL要等锁定时间DMA和中断控制器也要等总线仲裁稳定。这些条件的组合给了各种“竞争窗口”出现的机会。热启动比如软件reboot时电源不掉SoC内部很多时钟域其实还处于上次运行的状态控制器FIFO、DMA描述符、时钟分频器的残留值可能让问题被掩盖。换句话说冷启动复现往往意味着某个初始化时序存在微秒级别的窗口而这个窗口正好在上电第一次写操作时被踩中。间歇性本身就证明它不是单纯的静态配置错误。静态配置错了会100%必现不会“偶尔冒一次”。所以一上来就怀疑某个寄存器写错了方向大概率不对。真正该找的是两个异步逻辑之间的竞态比如DMA还没有把数据填进FIFO控制器已经认为数据够了开始发送。1.3 只写不读的深层原因回到这个case最奇怪的约束只写不读。读操作走的是接收方向控制器把卡发来的数据放进接收FIFO满了之后DMA再搬走。即使DMA晚来一拍接收FIFO还有缓冲余量而且读超时后控制器可以做重试。写操作则相反数据在DMA和FIFO之间的供给是“推”的模式一旦DMA没有按预期时间到达发送侧立刻断供。另外从FIFO水位配置来看发送水位的含义是“FIFO中数据量达到多少时开始向卡发送”。如果这个阈值设得太高比如FIFO总深度1024字节、水位设在960字节那么DMA必须一次性灌满这么多数据控制器才允许发送。而DMA的一次burst可能只有128字节或512字节传输路径上又有总线仲裁延迟FIFO的填充是阶梯式上涨的跟发送时钟的持续消耗之间很容易出现一个短暂的“空窗”。换到读方向接收水位通常设置得比FIFO深度小让DMA有足够时间搬走数据而且读操作即使发生overrun很多控制器也能通过CRC/重传机制补偿一大部分。所以同一个SDMMC控制器“写报欠载、读不报”是非常典型的现象它不一定是异常反而可能是默认配置下的一种必然只是平时没暴露。2. 常见根因从FIFO水位到时钟切换逐个排查2.1 FIFO水位和DMA burst配置是第一嫌疑我相信70%的TXUNDERR都出在这一块。不同SoC的SDMMC控制器在FIFO水位配置上有差异但思路是共通的发送水位必须小于等于“FIFO深度减去一次DMA传输的最大burst长度”否则就会出现DMA还没来得及完成一次完整搬运控制器就开始发送。举个例子。假设FIFO深度是1024字节DMA burst长度配置为512字节发送水位如果设成960字节那么问题就来了DMA从DDR往FIFO搬数据是分段进行的每搬运512字节需要一次总线事务总线上还有别的master在抢带宽。水位到了960字节并不意味着第960到1024之间已经被填满而控制器一旦判定“达到发送条件”就会开始消耗FIFO。如果DMA下一笔512字节还没到FIFO耗尽TXUNDERR就来了。一个相对安全的经验是把发送水位设在“FIFO深度 / 2”左右或者按控制器手册推荐的“FIFO深度 – 2 * burst长度”来设。具体值要结合DMA的max burst长度和设备树里的fifo-depth属性算不能拍脑袋。另外不同厂商的驱动里水位配置可能藏在平台回调函数里而不是直接用宏定义搜索的时候要留意。还有一点容易忽略有些控制器允许配置DMA的burst长度这个值不是越大越好。burst越大单次搬运效率越高但一次总线事务在总线上占用的时间也越长如果多个master同时竞争反而会在关键窗口卡住。我的建议是优先把水位调低再尝试让burst长度与L1 cache line大小通常是64字节对齐减少描述符处理带来的额外延迟。2.2 DMA描述符与内存一致性一个隐蔽的小坑如果水位和burst都正常仍然偶发欠载下一个要查的就是DMA描述符和内存buffer的一致性管理。SDMMC控制器通常用描述符链表来组织DMA传输每个描述符里有物理地址、长度、以及一个所有权标志位用来指示描述符是属于CPU还是控制器。常见踩坑点是驱动在完成上一次传输后用dma_map_single/dma_unmap_single做cache clean/invalidate时地址没有按cache line对齐导致DMA拿到了一部分还是旧数据的cache行。在写方向这个问题表现为DMA往FIFO灌的数据比预期少或者某个burst读到了空数据进而引发欠载。为什么冷启动更容易踩中因为热启动时这些cache行大概率还残留着上次写过的数据看起来“碰巧是对的”冷启动后cache处于全部失效状态问题才暴露出来。排查手段不难但需要细致在发送之前把所有涉及DMA的buffer地址和长度打印出来检查它们是否按L1 cache line对齐并确认dma_map操作在最后一次写buffer之后、启动传输之前完成。有些平台还需要在“启动传输”和“置所有权位”之间加一个内存屏障避免CPU写描述符的顺序被编译器或流水线重排。这类问题用JTAG调试器看是最直观的但纯软件打印也能定位只是费点时间。2.3 时钟切换窗口发命令前一刻钟变了SD/eMMC识别的经典流程是先以400kHz的慢速时钟读取卡信息然后通过mmc_set_ios切换到高速模式。问题往往出在“切换”本身。有些驱动在修改时钟分频器或者切换时钟源时没有先等卡忙完、也没有保证FIFO处于空状态如果切换窗口正好和一次写传输重叠时钟抖动或暂时性的停拍就会让发送侧瞬间欠载。这类问题在冷启动后特别明显因为第一次写操作往往紧跟在时钟切换之后。热启动时控制器可能还保持着高速时钟的配置省掉了切换步骤反而不报错。如果你在日志里看到TXUNDERR之前紧跟一条“mmc_set_ios: clock changed to 52000000 Hz”之类的记录那基本可以锁定方向。对此我的一般处理思路是把时钟切换放在DMA传输开始之前完成并且在切换后加一个极短的稳定等待有些平台的时钟管理寄存器写入后要读回确认必要时在控制器驱动的set_ios回调里把FIFO reset一并做了。注意不要在传输进行中动态改时钟这个很多驱动其实没有显式防止要靠review和实测才能发现。2.4 板级因素电源跌落和信号质量软件配置都查完之后如果问题还在就要怀疑板级了。eMMC写入时电流变化很大尤其多bank并行写入或cache命中时瞬间电流能拉到几百毫安级别。如果VCCQ通常是1.8V或3.3V的退耦电容不足或者电源走线太细写入瞬间电源会跌落控制器内部逻辑的时序余量被压缩偶发欠载就来了。这个方向在冷启动时也说得通刚上电时电源轨还没完全稳定电容充电不充分第一次大电流写入最容易把电压拉出纹波。热启动时电源轨已经处于稳定状态同样的写操作自然不会触发。怎么验证两个办法。一是用示波器钩在eMMC的VCCQ管脚上冷启动后连续做写操作观察有没有瞬间跌落超过5%的毛刺。二是做交叉验证把CLK频率降下来比如从200MHz降到50MHz如果欠载概率显著下降说明和电源/信号质量的相关性很高。降频后每次比特翻转的时间变长对电压跌落和信号振铃的敏感度降低欠载自然减少。3. 实操排查从复现到定位的完整流程3.1 先复现再收敛问题边界拿到这类间歇性bug第一件事不是改代码而是把复现条件固定下来。我会先做一个最小化实验矩阵每项跑20次冷启动记录是否报TXUNDERR。我常用的实验矩阵如下实验项条件A条件B预期判断启动方式冷启动热重启确认是否只在冷启动复现操作类型eMMC顺序写eMMC顺序读确认是否只写不读写入块大小4KB512B确认是否与DMA burst大小相关CLK频率最高频降频到1/4确认是否与时钟/电源相关DMA模式DMA开启PIO模式确认是否DMA路径相关文件系统裸分区写ext4大文件写确认是否与IO调度相关每次复现后记录dmesg里TXUNDERR出现前后50行日志、中断统计、以及当前时钟频率。这一步的意义是排除变量很多时候你做完这个表就已经能定位到大概方向了根本不用动示波器。需要注意每轮测试之间要让设备完全断电不能只按reboot否则“冷启动”这个条件就不成立了。3.2 在中断现场把寄存器一次抓全TXUNDERR通常是中断触发驱动在ISR里都会清中断标志但如果ISR处理得很快现场信息一清就没了。我的做法是在ISR里先关闭中断再依次读取状态寄存器、FIFO水位寄存器、DMA状态寄存器、以及控制器当前的时钟配置全部打进一个环形缓冲区。如果平台没有现成的寄存器dump函数用devmem直接读也行。前提是你知道控制器基地址比如某个SoC的SDMMC1基地址是0xFE310000那就可以先看中断状态寄存器偏移量在复现后立刻用devmem把这几个地址的值抓出来对比正常写操作时的值。重点看TXD水位是否归零、DMA是否还停留在某个描述符上、以及发送状态机是否卡在某个中间态。这里有个小技巧很多控制器的欠载中断不是一次性的它会把FIFO状态寄存器锁存到异常时刻的值直到软件清标志。所以ISR里读取顺序很重要一定要先读FIFO水位、再读DMA描述符指针、最后才清中断。如果反过来现场信息就永久丢了。这个习惯要提前写进驱动的debug版本里不要等出问题才补。3.3 用逻辑分析仪抓波形一次看清数据流软件寄存器看的是“结果”波形看的是“过程”。如果手头有逻辑分析仪或者示波器抓eMMC的CLK、CMD、DATA0这三个信号就够了。正常写传输时DATA0上应该是连续的、随CLK变化的数据翻转中间不会出现长时间的高阻或固定电平。欠载的特征是CLK还在跑CMD也已经切到data phase但DATA线上突然出现一段没有驱动的空白通常是悬空或电平不变然后控制器上报错误。用逻辑分析仪抓的时候把触发条件设为“DATA0上升沿后500ns内没有下一次跳变”就能很精准地捕捉到欠载瞬间。抓完波形后把欠载时刻的CLK频率、DMA描述符地址、以及对应时间的软件日志对齐基本就能判定问题出在DMA侧还是控制器侧。如果欠载时DMA描述符已经完成说明FIFO供应没问题是控制器配置问题如果DMA还在搬第一个描述符那就说明DMA启动太晚或者总线仲裁卡了。这一步能直接告诉你该去改驱动还是改板子。3.4 用配置改动快速二分定位在寄存器、波形都不太好抓的情况下纯软件手段也能大幅缩小范围。我的习惯是每次只改一个变量做20次冷启动测试按结果判断。第一个变量是发送水位调低一档如果消失基本锁定FIFO配置。第二个变量是把DMA burst长度减半如果也消失说明是总线竞争或cache line对齐问题。第三个变量是把时钟降频到1/4如果消失说明问题在电源或信号质量。第四个变量是把驱动改成PIO模式如果PIO模式下不报那DMA路径嫌疑最大。这个方法不花哨但非常有效。不要一次改多个变量否则出问题后你根本不知道是哪个改动起了作用。每次只改一项然后完整跑一轮冷启动测试记录结果。这样两到三轮下来根因方向基本就锁定了。4. 修复方案从软件补丁到硬件整改4.1 方案一调整FIFO水位和DMA参数如果定位到FIFO水位配置不当修改通常是几行代码的事。以dw_mmc系控制器为例FIFO深度可以从设备树或驱动里的fifo-depth属性获取水位计算逻辑一般放在读写的控制函数里/* 伪代码实际需按平台适配 */ #define TX_WATERMARK_LOW (fifo_depth / 2) #define TX_WATERMARK_HIGH (fifo_depth - 2 * max_burst) dw_mci_write_fifo_watermark(host, TX_WATERMARK_LOW);修改后不要只验证正常工作还要验证“不生效”时是否确实会报错这样才能确认你改对了地方。具体做法是临时把水位设回原来的危险值确认复现再改回安全值确认消失。这一步叫“正反验证”能避免把无关变量当成根因。4.2 方案二修时钟切换和初始化顺序如果是时钟切换窗口的问题需要调整驱动的set_ios流程。核心思路是保证时钟切换之前控制器处于非busy状态时钟切换完成后再允许发起新的传输。一个比较通用的做法是在mmc_set_ios里增加一个等待函数切换后轮询控制器的时钟稳定标志/* 伪代码 */ mmc-ios.clock target_clk; host-ops-set_ios(mmc, mmc-ios); /* 等待时钟稳定或轮询状态寄存器 */ while (!(readl(host-base STATUS) CLK_STABLE)) cpu_relax();这里有个细节不要等太久否则会影响eMMC的初始化时序导致卡识别超时。一般几个微秒内就应该稳定。如果平台没有时钟稳定标志位可以退而求其次读到寄存器值后再加一个很小的delay然后用set_ios返回值确认。这个方案对驱动的侵入性不大但需要充分验证确保不会拖慢初始化流程。4.3 方案三错误重试和降级策略兜底方案即使你修复了根因我建议仍然保留错误重试逻辑。原因很简单嵌入式产品的现场环境远比实验室复杂偶尔一次欠载不应直接导致IO错误甚至文件系统损坏。驱动层面可以在检测到TXUNDERR时先做FIFO reset清中断重新挂描述符再重发同一条命令。流程大致是ISR里识别到TXUNDERR立即屏蔽新的中断。读取并保存现场寄存器打印错误日志。复位控制器FIFO和发送状态机。重新初始化DMA描述符将数据地址回退到本次传输的起始位置。清中断标志再次触发发送命令。连续重试超过3次仍失败才向上层报告IO错误。重点提醒重试只能作为兜底不能作为根因掩盖手段。如果重试太频繁说明根因还在应该继续深挖。另外重试时要注意数据一致性eMMC是块设备重发前要确保目标块没有被部分写入否则可能造成文件系统元数据损坏。最稳妥的做法是重试前先做一次read-back校验确认块内数据是否一致。4.4 验证闭环冷启动压测怎么设计修复完后验证比修复更重要。我的验收标准是连续冷启动100次每次启动后跑一轮eMMC写读校验全程不允许出现一次TXUNDERR在-10℃和60℃环境下各跑20次因为间歇性问题和温度相关度很高。一个简单的压力循环脚本大概长这样for i in $(seq 1 100); do echo cold boot round $i # 写4GB数据到eMMC裸分区 dd if/dev/urandom of/dev/mmcblk0p1 bs1M count4096 convfsync # 读回来做校验 dd if/dev/mmcblk0p1 of/dev/null bs1M count4096 dmesg | grep -i txunderr echo FAIL || echo PASS reboot sleep 60 done注意脚本里的reboot方式要看平台有些设备需要硬件断电才能算冷启动。如果平台不支持脚本自动断电那就只能靠人肉或者半自动测试架。测试时每次冷启动后不要立刻开始写先给电源轨和时钟一个稳定时间比如3秒后再发起IO这样更贴近用户实际使用场景。5. 现场排查速查表与独家避坑心得5.1 一张表判断问题该往哪查以下是我在实际调试过程中整理出来的快速对照表表格顺序就是排查优先级现象特征最可能原因验证手段修复方向冷启动后首次写必现时钟切换窗口/初始化时序抓dmesg看set_ios顺序调整set_ios、加稳定等待高速时钟下频繁、低频下消失电源跌落或信号质量示波器量VCCQ、降频对比板级电源/走线整改大块写易触发、小块写不触发FIFO水位设置偏高调低水位做正反验证修改FIFO watermark配置随机偶发、位置固定DMA描述符/cache一致性问题检查地址对齐和内存屏障修正dma_map和barrier顺序PIO模式不报、DMA模式报DMA总线竞争或burst配置切换DMA burst长度调整burst和传输策略这张表不是万能钥匙但能帮你把排查从“大海捞针”变成“按图索骥”。5.2 容易被忽略的三个细节第一个细节是查芯片手册的errata。很多SoC的SDMMC控制器都存在已知勘误TXUNDERR可能就是其中一条手册里会给出官方推荐的workaround比如某个特定寄存器序列、或者必须在某个中断里做额外处理。如果你在手册勘误表里找到相同描述直接按厂商的推荐实现能省掉大量排查时间。第二个细节是确认uboot或者bootloader阶段有没有留下“脏状态”。有些产品的bootloader为了加快启动可能已经初始化过SDMMC控制器并做过读操作但没有把控制器恢复到复位默认状态。内核驱动probe时如果假设控制器是干净上电状态就可能踩到残留配置的坑。排查方法是把内核的SDMMC驱动改成“先做全控制器复位再init”看问题是否消失。第三个细节是不要一上来就怀疑DMA cache一致性。这个方向听起来高端但实际占比很小而且很容易让调试陷入泥潭。先用最简单的FIFO水位和时钟切换排查工具也更可靠。如果实在查不出再检查DMA一致性也不迟。5.3 我现在遇到TXUNDERR的排查习惯踩过几次这类坑之后我形成了一套自己的固定流程。先花10分钟把复现条件收敛到“最小复现场景”然后直接看dmesg里欠载发生前的最后一条日志再往前翻5条如果看到时钟切换记录就先怀疑切换窗口如果没有就查FIFO水位和DMA burst配置。很多时候问题不是单点原因而是多个因素叠加比如FIFO水位本来就设得偏高加上某次总线仲裁延迟特别长才导致偶发。这种叠加型问题最难查因为单独改任何一个变量都不能完全消除。我的经验是不要追求“一次改到位”先做降频实验把最危险的因素排除掉再逐步恢复高频观察是哪个变量让概率重新上来。最后再分享一个小技巧给驱动的错误路径加一个计数器和时间戳在debugfs下暴露出来这样即使客户现场复现了也能拿到“一共发生了多少次、分别在什么时间点”的数据比单纯一条dmesg有用得多。有了这些数据你甚至不用去现场远程就能判断出问题的大致方向。这套方法不限于TXUNDERR任何间歇性外设错误都可以用同样的思路去收敛和定位。