做嵌入式開發(fā)這些年USB調(diào)試一直是我最怕翻車的環(huán)節(jié)之一。這次項(xiàng)目代號ESPS的設(shè)備要新增一個(gè)功能把設(shè)備SD卡里的采集數(shù)據(jù)導(dǎo)出到電腦最終方案選的是USB MSCMass Storage Class大容量存儲設(shè)備也就是把設(shè)備模擬成一個(gè)U盤用戶插上數(shù)據(jù)線就能直接拷文件。聽起來很簡單但整個(gè)調(diào)試過程遠(yuǎn)沒有想象中順利枚舉失敗、Windows認(rèn)了Linux不認(rèn)、大文件拷貝到90%直接掉盤……前前后后折騰了一周多。這篇文章就把ESPS USB MSC調(diào)試的全過程做個(gè)完整記錄從協(xié)議原理到一步步排查思路再到踩過的坑和修復(fù)方案給后面準(zhǔn)備做USB存儲類設(shè)備的同行當(dāng)個(gè)參考。1. 項(xiàng)目由來為什么非要USB MSC不可1.1 需求場景ESPS這個(gè)設(shè)備本身是一個(gè)低功耗數(shù)據(jù)采集終端長時(shí)間跑在野外記錄傳感器數(shù)據(jù)數(shù)據(jù)存在外置TF卡上單次任務(wù)產(chǎn)生從幾十MB到幾個(gè)GB不等的數(shù)據(jù)文件。原來的數(shù)據(jù)導(dǎo)出方式特別原始用串口線連接設(shè)備通過115200波特率的串口上位機(jī)把文件慢慢拉下來。傳一個(gè)100MB的文件需要將近兩個(gè)小時(shí)而且串口線一松就前功盡棄客戶早就抱怨過好幾輪了。新需求很明確讓普通用戶在沒有專業(yè)上位機(jī)、沒有串口線的情況下也能快速地拿到設(shè)備里的數(shù)據(jù)。最好就是插一根USB線電腦上立刻多出一個(gè)盤符文件一拖就完事。這個(gè)場景下USB MSC幾乎是唯一正確答案。1.2 方案選型對比動(dòng)手之前我把可行的USB方案列了一遍逐個(gè)對比后才知道MSC的優(yōu)勢在哪里。方案傳輸速度用戶操作難度驅(qū)動(dòng)兼容性開發(fā)復(fù)雜度USB虛擬串口CDC約1MB/s左右需要裝虛擬串口驅(qū)動(dòng)、用上位機(jī)有驅(qū)動(dòng)問題較低USB RNDIS網(wǎng)卡約5MB/s以上需要配置IP、用網(wǎng)絡(luò)協(xié)議傳文件各系統(tǒng)差異大高USB MSC大容量存儲受限于存儲介質(zhì)通常5-20MB/s插上就是U盤零學(xué)習(xí)成本系統(tǒng)原生支持免驅(qū)中高串口方案最大的問題不是速度而是用戶心智。一個(gè)非技術(shù)客戶他根本不想知道COM口是幾號、波特率是多少。RNDIS雖然能用TCP/IP傳文件但Windows上驅(qū)動(dòng)兼容性問題多Linux和macOS行為不太一致。MSC就完全不同Windows、Linux、macOS、Android都原生支持插上就能識別成大容量存儲設(shè)備系統(tǒng)自己掛載文件系統(tǒng)用戶看到的就是一個(gè)普通U盤。存儲介質(zhì)選型也是一個(gè)關(guān)鍵決策點(diǎn)。最初有同事提議用MCU內(nèi)部Flash直接模擬U盤省掉外置存儲芯片。仔細(xì)評估下來發(fā)現(xiàn)這個(gè)方案只適合存配置參數(shù)因?yàn)閮?nèi)部Flash容量小、擦寫壽命有限、數(shù)據(jù)傳輸速度也慢。MSC規(guī)范本身支持4字節(jié)邏輯塊地址單盤能做到2TB但實(shí)際瓶頸在底層的存儲介質(zhì)。ESPS最終采用SDIO接口外接TF卡搭配FatFS文件系統(tǒng)速度和容量都能滿足數(shù)據(jù)導(dǎo)出需求。這里有個(gè)容易被忽略的點(diǎn)MCU內(nèi)部Flash還需要留一部分給固件本身如果模擬U盤時(shí)把Flash扇區(qū)映射搞錯(cuò)了可能會(huì)把程序區(qū)給擦掉那是災(zāi)難性的事故。2. 調(diào)試環(huán)境搭建硬件連接、工具鏈和一些早該知道的坑2.1 硬件準(zhǔn)備調(diào)試ESPS的USB MSC功能硬件上我準(zhǔn)備了這幾樣?xùn)|西ESPS樣機(jī)、USB Type-C數(shù)據(jù)線、一個(gè)USB轉(zhuǎn)TTL的調(diào)試小板方便看串口日志、帶電流顯示的USB測試儀以及一個(gè)能抓USB協(xié)議包的工具。USB線這一項(xiàng)就坑過我。ESPS板子上是Type-C座子我隨手從抽屜里拿了根手機(jī)充電線結(jié)果插上電腦一點(diǎn)反應(yīng)都沒有。后來才發(fā)現(xiàn)那根線只支持充電里面壓根沒有D/D-數(shù)據(jù)線。這類線在市面上極其常見特別是買小電器附帶的線。排查USB問題第一步先確認(rèn)你用的線支持?jǐn)?shù)據(jù)傳輸否則后面所有努力都是白費(fèi)。判斷方法很簡單插上后看電腦有沒有叮咚的插入提示音沒有就換線。USB測試儀在早期階段很有用它能直觀顯示設(shè)備枚舉前后的電流變化。USB規(guī)范要求設(shè)備在上電到被主機(jī)配置完成之前從總線獲取的電流不能超過100mA。如果設(shè)備一上電電流就飆到300mA主機(jī)會(huì)直接拒絕枚舉或者反復(fù)復(fù)位設(shè)備。我遇到過一次類似現(xiàn)象最后的根因是板子上一個(gè)電容虛焊導(dǎo)致電源紋波太大把USB PHY的狀態(tài)機(jī)打亂了這種問題不看電流波形根本定位不到。2.2 串口與驅(qū)動(dòng)的坑ESPS固件調(diào)試離不開串口日志。我用的是USB轉(zhuǎn)TTL小板這塊小板主控芯片是FT231X。Windows 10和11通常能自動(dòng)識別這類芯片但偶爾會(huì)出現(xiàn)驅(qū)動(dòng)掉鏈子的情況設(shè)備管理器里顯示一個(gè)帶感嘆號的USB Serial Converter。這時(shí)需要去芯片官網(wǎng)下載對應(yīng)的驅(qū)動(dòng)重新安裝。這里有一個(gè)很多人不知道的小細(xì)節(jié)FT231X這類USB轉(zhuǎn)串口芯片安裝驅(qū)動(dòng)后設(shè)備管理器會(huì)同時(shí)出現(xiàn)一個(gè)USB Serial PortCOM號和一個(gè)USB Serial Converter設(shè)備節(jié)點(diǎn)。COM號屬于上層抽象底層驅(qū)動(dòng)節(jié)點(diǎn)才是芯片本身。如果底層節(jié)點(diǎn)有問題即便COM號存在打開串口也會(huì)報(bào)參數(shù)錯(cuò)誤。排查的時(shí)候先看底層節(jié)點(diǎn)狀態(tài)不要只盯著COM號。串口調(diào)試助手我習(xí)慣用SSCOM這類經(jīng)典工具連接前先確認(rèn)波特率、數(shù)據(jù)位、停止位和流控選項(xiàng)。ESPS固件串口打印用的115200/8/N/1沒有硬件流控。新手常犯的錯(cuò)是默認(rèn)勾選了RTS/DTR控制導(dǎo)致板子在打開串口的瞬間被復(fù)位置位日志只打了一行就沒了。所以接線調(diào)試時(shí)打開串口后先觀察兩三秒確認(rèn)設(shè)備沒有異常復(fù)位再操作。2.3 USB抓包怎么抓USB調(diào)試只看日志和代碼排查效率很低。抓包一定要學(xué)會(huì)這是定位問題最直接的手段。ESPS是USB 2.0全速設(shè)備Full Speed12Mbps抓包方案有幾個(gè)選擇硬件USB分析儀比如Total Phase Beagle USB 480抓包準(zhǔn)確、帶時(shí)間戳就是貴個(gè)人開發(fā)者不一定舍得買。Wireshark USBPcap組合免費(fèi)能抓Windows下的USB協(xié)議包適合分析枚舉過程和數(shù)據(jù)傳輸。Bus Hound老牌免費(fèi)USB抓包工具Windows下用著很方便。Linux下可以用usbmon通過cat /sys/kernel/debug/usb/usbmon/0u看實(shí)時(shí)數(shù)據(jù)流。我用的是Wireshark加USBPcap配合Bus Hound驗(yàn)證。抓包原理上要注意一個(gè)限制軟件抓包工具是在主機(jī)操作系統(tǒng)的USB協(xié)議棧層面抓包能看到主機(jī)和設(shè)備之間的控制傳輸、Bulk傳輸數(shù)據(jù)但看不到底層電氣信號異常比如D上拉時(shí)序問題、信號質(zhì)量抖動(dòng)。這類問題只能靠硬件分析儀或示波器。抓包的時(shí)候還有個(gè)技巧軟件工具抓包會(huì)引入一定延遲但MSC使用的是Bulk傳輸協(xié)議本身有超時(shí)重試機(jī)制抓包對時(shí)序影響不大。真正受影響的是等時(shí)傳輸Isochronous和中斷傳輸Interrupt抓包時(shí)可能出現(xiàn)主機(jī)側(cè)超時(shí)。MSC調(diào)試完全不用擔(dān)心這個(gè)。3. 跑通MSC前必須先懂的幾個(gè)協(xié)議節(jié)點(diǎn)3.1 枚舉過程與設(shè)備描述符USB設(shè)備接入主機(jī)后主機(jī)并不知道插進(jìn)來的是什么設(shè)備一切都要從枚舉開始。枚舉流程大致是主機(jī)檢測到設(shè)備接入給設(shè)備復(fù)位然后讀取設(shè)備描述符、分配地址、讀取配置描述符、選擇配置。這一步完成后設(shè)備才算是被主機(jī)認(rèn)識了。設(shè)備描述符是18個(gè)字節(jié)開頭的兩個(gè)字節(jié)分別是bLength0x12和bDescriptorType0x01。這個(gè)看似簡單的字段我在調(diào)試ESPS時(shí)還真栽過一回當(dāng)時(shí)把描述符數(shù)組定義成了const uint8_t DeviceDescriptor[] { ... }結(jié)果編譯器按4字節(jié)對齊做了填充數(shù)組長度不是18MCU返回給主機(jī)的描述符長度就變成了20字節(jié)。主機(jī)收到后直接判定描述符非法枚舉失敗。后來查了編譯器的對齊規(guī)則把結(jié)構(gòu)體用__attribute__((packed))強(qiáng)制緊湊排列才解決問題。MSC設(shè)備的關(guān)鍵描述符包括設(shè)備描述符里的idVendor和idProduct接口描述符里的bInterfaceClass 0x08MSC類、bInterfaceSubClass 0x06SCSI透明命令集、bInterfaceProtocol 0x50Bulk-Only Transport。這三個(gè)字段必須配對正確主機(jī)才能正確加載系統(tǒng)自帶的大容量存儲驅(qū)動(dòng)。字符串描述符也是個(gè)容易翻車的地方。如果設(shè)備描述符里聲明了iManufacturer1、iProduct2、iSerialNumber3那么后續(xù)必須有對應(yīng)的字符串描述符而且內(nèi)容必須是UTF-16LE編碼。很多人圖省事直接填A(yù)SCII字符串結(jié)果在Linux下字符串變亂碼甚至導(dǎo)致枚舉中斷。一系列描述符的結(jié)構(gòu)如下給讀者一個(gè)直觀印象設(shè)備描述符 12 01 10 01 00 00 00 40 34 12 78 56 00 01 01 02 00 01 配置描述符 09 02 20 00 01 01 00 80 32 接口描述符 09 04 00 00 02 08 06 50 00 端點(diǎn)描述符OUT 07 05 01 02 40 00 00 端點(diǎn)描述符IN 07 05 81 02 40 00 00其中bcdUSB為0x0110表示USB 1.1bMaxPacketSize0為0x40表示端點(diǎn)0最大包長64字節(jié)。配置描述符里的wTotalLength0x0020說明配置總長度是32字節(jié)剛好等于配置、接口、兩個(gè)端點(diǎn)描述符的長度之和。3.2 BOT協(xié)議CBW與CSWMSC設(shè)備通常會(huì)實(shí)現(xiàn)Bulk-Only TransportBOT協(xié)議整個(gè)傳輸流程圍繞兩條Bulk端點(diǎn)進(jìn)行一條OUT、一條IN每筆事務(wù)分為三個(gè)階段主機(jī)發(fā)送CBWCommand Block Wrapper到OUT端點(diǎn)傳輸數(shù)據(jù)階段根據(jù)CBW中的方向標(biāo)志決定數(shù)據(jù)流方向最后設(shè)備返回CSWCommand Status Wrapper到IN端點(diǎn)告知執(zhí)行結(jié)果。CBW固定31字節(jié)結(jié)構(gòu)如下dCBWSignature // 固定為0x43425355即USBC dCBWTag // 命令的標(biāo)記字段 dCBWTransferLength // 期望傳輸?shù)淖止?jié)數(shù) bmCBWFlags // 位7為1表示數(shù)據(jù)階段方向?yàn)樵O(shè)備到主機(jī)為0表示主機(jī)到設(shè)備 bCBWLUN // 邏輯單元號通常為0 bCBWCBLength // 有效SCSI命令塊長度 CBWCB[16] // 具體的SCSI命令塊CSW固定13字節(jié)dCSWSignature // 固定為0x53425355即USBS dCSWTag // 必須與CBW中的dCBWTag一致 dCSWResidue // 剩余未傳輸?shù)淖止?jié)數(shù) bCSWStatus // 0表示成功1表示命令失敗2表示階段錯(cuò)誤調(diào)試MSC狀態(tài)機(jī)時(shí)最容易出錯(cuò)的就是階段錯(cuò)誤Phase Error。比如主機(jī)發(fā)出一個(gè)READ(10)命令期望設(shè)備返回?cái)?shù)據(jù)結(jié)果設(shè)備因?yàn)榈讓哟鎯ψx失敗直接在IN端點(diǎn)返回了STALL握手包主機(jī)收不到數(shù)據(jù)就會(huì)上報(bào)錯(cuò)誤甚至重置整個(gè)USB設(shè)備。正確的做法是如果數(shù)據(jù)階段出錯(cuò)設(shè)備應(yīng)該STALL對應(yīng)的端點(diǎn)并且在后續(xù)收到CLEAR FEATURE請求時(shí)把BOT狀態(tài)機(jī)重置到CBW接收階段。很多不成熟的MSC實(shí)現(xiàn)沒有正確區(qū)分命令失敗和階段錯(cuò)誤導(dǎo)致Windows還能湊合容忍Linux直接報(bào)錯(cuò)。3.3 SCSI命令與文件系統(tǒng)的配合MSC設(shè)備本身不處理文件系統(tǒng)它只負(fù)責(zé)響應(yīng)SCSI命令把存儲介質(zhì)抽象成一塊塊固定大小的扇區(qū)。Windows或Linux通過SCSI READ/WRITE命令讀寫這些扇區(qū)然后在主機(jī)側(cè)建立FAT32、exFAT或ext4等文件系統(tǒng)。ESPS設(shè)備端需要實(shí)現(xiàn)的SCSI命令并不多但每個(gè)都必須仔細(xì)INQUIRY返回設(shè)備類型0x00表示直接訪問塊設(shè)備、廠商字符串、產(chǎn)品字符串等。TEST UNIT READY查詢設(shè)備是否就緒。READ CAPACITY(10)返回介質(zhì)最后一個(gè)LBA和扇區(qū)大小。READ(10) / WRITE(10)按LBA讀寫指定長度的扇區(qū)。MODE SENSE(6)返回介質(zhì)參數(shù)主機(jī)在枚舉和格式化時(shí)會(huì)查詢回一頁默認(rèn)參數(shù)即可。START STOP UNIT控制介質(zhì)啟?？梢栽谠撁罾镒鼍彺嫠⑿?。PREVENT ALLOW MEDIUM REMOVAL鎖介質(zhì)防止用戶在拷貝數(shù)據(jù)時(shí)拔出TF卡。有一個(gè)關(guān)鍵點(diǎn)READ CAPACITY(10)返回的扇區(qū)大小不能隨便填?，F(xiàn)在很多TF卡物理扇區(qū)是4096字節(jié)如果設(shè)備直接把扇區(qū)大小報(bào)成4096而FatFS又按512字節(jié)邏輯扇區(qū)來管理兩邊一沖突數(shù)據(jù)就寫亂了。穩(wěn)妥的做法是讓MSC層固定以512字節(jié)為邏輯扇區(qū)底層再根據(jù)TF卡的實(shí)際物理扇區(qū)做轉(zhuǎn)換。主機(jī)側(cè)格式化時(shí)會(huì)按設(shè)備上報(bào)的扇區(qū)大小來操作512字節(jié)的兼容性最好。FatFS這類設(shè)備端文件系統(tǒng)也要小心。ESPS固件代碼里FatFS在后臺采集任務(wù)中不斷寫入新數(shù)據(jù)同時(shí)主機(jī)通過MSC讀取同一張卡。這種雙端并發(fā)訪問在文件系統(tǒng)層沒有做鎖保護(hù)一旦主機(jī)發(fā)出WRITE命令修改了文件系統(tǒng)結(jié)構(gòu)而固件后臺還在寫同一個(gè)文件就會(huì)產(chǎn)生目錄項(xiàng)混亂。我最后的方案是檢測到USB MSC主機(jī)連接后立即停止后臺寫入任務(wù)把FatFS所有文件同步關(guān)閉讓主機(jī)完全獨(dú)占TF卡。拔出后重新掛載FatFS。雖然粗暴但能保證數(shù)據(jù)一致性。4. 第一次插入電腦毫無反應(yīng)一場典型的枚舉失敗排查4.1 現(xiàn)象與初步判斷ESPS的MSC固件第一次上電調(diào)試時(shí)USB線插入電腦后沒有任何反應(yīng)設(shè)備管理器中連未知設(shè)備都沒出現(xiàn)。這比出現(xiàn)感嘆號還難查至少出現(xiàn)未知設(shè)備說明主機(jī)檢測到了物理連接。我當(dāng)時(shí)的排查思路是這樣的物理層沒反應(yīng)可能性無非幾種——USB線問題、D/D-沒接上、設(shè)備側(cè)沒有上拉、USB PHY沒有正常工作。先換線測試沒用然后測量板子上D/D-對地電壓。正常情況下全速USB設(shè)備上電后D線上應(yīng)該被上拉到3.3V或者3.0V左右設(shè)備端通過1.5k電阻上拉D-保持接近0V。如果D電壓為0說明設(shè)備端根本沒有打開上拉電阻。ESPS板子的D上拉是通過GPIO控制的我查了固件代碼發(fā)現(xiàn)USB初始化函數(shù)里漏了拉高GPIO的操作上拉根本沒打開。這個(gè)問題雖然低級但提示了一個(gè)重要的調(diào)試思路USB設(shè)備枚舉的第一件事是讓主機(jī)發(fā)現(xiàn)你。全速設(shè)備靠D上拉來宣告我在這里低速設(shè)備則靠D-上拉。如果你的設(shè)計(jì)是用外部模擬開關(guān)或者GPIO控制上拉一定要在USB外設(shè)初始化之前或者同時(shí)完成拉高順序錯(cuò)了主機(jī)會(huì)認(rèn)為設(shè)備掉線。4.2 抓包定位過程修復(fù)上拉問題后電腦終于有反應(yīng)了變成設(shè)備管理器里出現(xiàn)未知USB設(shè)備設(shè)備描述符請求失敗。這個(gè)階段光靠看代碼已經(jīng)不高效必須上抓包工具。我用Wireshark加USBPcap抓到的枚舉過程是這樣的主機(jī)發(fā)出GET_DESCRIPTOR請求讀取設(shè)備描述符設(shè)備返回了18字節(jié)數(shù)據(jù)但主機(jī)端判定數(shù)據(jù)無效。通過逐字節(jié)比對返回內(nèi)容和預(yù)期值發(fā)現(xiàn)設(shè)備返回的bMaxPacketSize0字段是0x00而這會(huì)導(dǎo)致主機(jī)無法正確解析后續(xù)傳輸。為什么bMaxPacketSize0會(huì)是0回到代碼里看設(shè)備描述符數(shù)組定義無誤但初始化過程中USB外設(shè)的FIFO配置在枚舉之前還沒有完成導(dǎo)致描述符數(shù)據(jù)在讀出時(shí)被截?cái)嗷蛘咛畛錇榱?。具體來說STM32系列MCU的USB全速外設(shè)擁有一個(gè)可配置的FIFO空間分為多個(gè)端點(diǎn)緩沖區(qū)。端點(diǎn)0的收發(fā)緩沖區(qū)大小必須在使能USB前分配好否則設(shè)備在響應(yīng)控制傳輸時(shí)沒有可用的FIFO空間硬件會(huì)返回錯(cuò)誤數(shù)據(jù)。這里需要特別提醒的是描述符請求是主機(jī)在地址0階段發(fā)出的控制傳輸數(shù)據(jù)階段最多只有8字節(jié)默認(rèn)控制端點(diǎn)最大包長通常是8字節(jié)全速設(shè)備是8/16/32/64可選。在未分配地址之前主機(jī)還不知道設(shè)備的bMaxPacketSize0所以第一個(gè)GET_DESCRIPTOR請求只會(huì)讀取設(shè)備描述符的前8個(gè)字節(jié)。設(shè)備必須在此時(shí)讓主機(jī)看到有效的bMaxPacketSize0值后續(xù)通信才會(huì)順暢。4.3 最終根因與修復(fù)最終定位的根因不在描述符數(shù)組而在于USB外設(shè)FIFO初始化順序我原先在USB_Init()函數(shù)中先打開了USB全局中斷然后才配置PMA緩沖區(qū)描述符表和FIFO分配?？刂苽鬏斦埱蟮竭_(dá)時(shí)FIFO區(qū)域還是未初始化狀態(tài)導(dǎo)致數(shù)據(jù)錯(cuò)亂。把FIFO配置和描述符表初始化放到開中斷之前問題迎刃而解。這給了一個(gè)復(fù)盤要點(diǎn)遇到USB枚舉失敗抓包永遠(yuǎn)比盲試快。同樣是描述符請求失敗可能是數(shù)組定義問題、FIFO配置問題、時(shí)鐘問題甚至可能是供電問題。通過抓包能看到主機(jī)收到的實(shí)際字節(jié)讓問題從猜變成看。當(dāng)時(shí)如果繼續(xù)靠翻代碼硬看可能還要多花一兩天。枚舉階段我還總結(jié)了一個(gè)檢查清單推薦給所有做USB設(shè)備的開發(fā)者檢查項(xiàng)常見錯(cuò)誤定位方法D/D-上拉電阻全速設(shè)備用了D-上拉測量D/D-電壓設(shè)備描述符長度編譯器對齊導(dǎo)致長度錯(cuò)誤抓包比對空包bMaxPacketSize0錯(cuò)誤設(shè)為64以上抓包讀前8字節(jié)USB時(shí)鐘沒有48MHz串口打印寄存器FIFO配置開中斷先于緩沖區(qū)初始化代碼審查VID/PID與其他設(shè)備沖突設(shè)備管理器查看字符串描述符編碼不是UTF-16LELinux下lsusb -vE位一個(gè)經(jīng)驗(yàn)VID/PID不要亂填。如果填了別人已經(jīng)量產(chǎn)注冊的VID/PIDWindows的驅(qū)動(dòng)緩存可能會(huì)加載完全不對的驅(qū)動(dòng)導(dǎo)致設(shè)備行為異常。沒有公司自有VID時(shí)可以用MCU廠商分配給評估板的VID/PID調(diào)試但正式量產(chǎn)前必須換成自己的。5. Windows能識別、Linux不買賬不同系統(tǒng)的差異化表現(xiàn)5.1 現(xiàn)象描述枚舉問題解決后ESPS設(shè)備在Windows 11下可以正常識別為USB大容量存儲設(shè)備并彈出了盤符能像普通U盤一樣打開。但拿到Linux機(jī)器上一測試dmesg里的日志讓人頭大usb 1-2: new full-speed USB device number 12 using xhci_hcd usb 1-2: New USB device found, idVendor1234, idProduct5678, bcdDevice 1.00 usb 1-2: New USB device strings: Mfr1, Product2, SerialNumber3 usb 1-2: Product: ESPS Mass Storage usb 1-2: Manufacturer: ESPS usb 1-2: SerialNumber: 20240601 usb-storage 1-2:1.0: USB Mass Storage device detected scsi host4: usb-storage 1-2:1.0 scsi 4:0:0:0: Direct-Access ESPS Mass Storage 1.00 PQ: 0 ANSI: 0 sd 4:0:0:0: [sdb] 0 512-byte logical blocks: (0 B) sd 4:0:0:0: [sdb] Write Protect is off sd 4:0:0:0: [sdb] Mode Sense: 00 00 00 00 sd 4:0:0:0: [sdb] Capacity: 0 bytes, 0 sectors注意這一行sd 4:0:0:0: [sdb] 0 512-byte logical blocks: (0 B)。Linux內(nèi)核讀取到的磁盤容量是0。而Windows下卻能看到正確的容量。這就是兩個(gè)系統(tǒng)在MSC協(xié)議處理上的典型差異。5.2 Linux下的確查出問題Windows對SCSI命令的容錯(cuò)性比Linux高很多。Windows在設(shè)備枚舉后即使READ CAPACITY(10)返回的容量為0它仍然會(huì)嘗試掛載卷并彈出需要格式化的提示讓用戶感覺至少識別到這個(gè)盤了。Linux更加嚴(yán)格如果容量為0就直接判定設(shè)備無效不創(chuàng)建塊設(shè)備節(jié)點(diǎn)。ESPS出現(xiàn)容量為0的原因出在SCSI命令實(shí)現(xiàn)的一個(gè)細(xì)節(jié)READ CAPACITY(10)命令的CDB結(jié)構(gòu)如下Byte 0: 0x25操作碼 Byte 1: LUN及保留位通常為0 Byte 2-5: LBA邏輯塊地址通常為0 Byte 6-7: 保留 Byte 8: PMI及保留位 Byte 9: 控制字節(jié)數(shù)據(jù)階段返回8字節(jié)Byte 0-3: 最后一個(gè)邏輯塊地址LBA4字節(jié)大端 Byte 4-7: 邏輯塊大小4字節(jié)大端通常為512當(dāng)時(shí)我的實(shí)現(xiàn)是直接把FatFS的f_getfree返回的扇區(qū)總數(shù)填進(jìn)去而沒有考慮FatFS返回的free cluster數(shù)量和實(shí)際扇區(qū)數(shù)的換算關(guān)系。換算錯(cuò)誤導(dǎo)致上報(bào)的最后一個(gè)LBA為負(fù)數(shù)即非常大的無符號數(shù)Linux內(nèi)核判斷超出了其內(nèi)部上限直接修正為0。Windows不會(huì)做這種細(xì)粒度校驗(yàn)它要求驅(qū)動(dòng)盡量上報(bào)真實(shí)值如果超過上限就按實(shí)際返回值處理所以Windows還能用。修復(fù)方式是把容量計(jì)算的邏輯換成了底層SD卡驅(qū)動(dòng)的物理扇區(qū)數(shù)不經(jīng)過文件系統(tǒng)層徹底避開了FatFS的影響。5.3 空卡與格式化問題的處理調(diào)試過程中還有一個(gè)常見場景插入一張全新未格式化的TF卡。這種情況下設(shè)備端文件系統(tǒng)尚未建立MSC層上報(bào)READ CAPACITY時(shí)應(yīng)返回正確的物理容量但SCSI INQUIRY和PREVENT ALLOW MEDIUM REMOVAL依然要正常響應(yīng)。Windows會(huì)彈窗提示需要格式化磁盤用戶可以點(diǎn)擊格式化主機(jī)端會(huì)通過WRITE命令寫入引導(dǎo)扇區(qū)和文件系統(tǒng)結(jié)構(gòu)。設(shè)備端必須保證這些寫操作真正落盤。我在這里又踩了一個(gè)坑ESPS固件格式化時(shí)Windows寫入了FAT32引導(dǎo)扇區(qū)但隨后讀取時(shí)返回的數(shù)據(jù)和寫入的不一致。最后定位到是SD卡驅(qū)動(dòng)的寫入函數(shù)在DMA傳輸時(shí)緩存沒有失效讀取的是DMA緩沖區(qū)里的舊數(shù)據(jù)。這個(gè)問題的根源是芯片的D-Cache沒有做一致性維護(hù)嵌入式中DRAM緩存和DMA之間的經(jīng)典沖突。解決方案有兩個(gè)一是關(guān)閉D-Cache簡單粗暴但對性能有一定影響二是用MPU把DMA緩沖區(qū)所在的RAM區(qū)域配置為不可緩存并在每次DMA操作前后執(zhí)行SCB_CleanDCache和SCB_InvalidateDCache。ESPS最終選擇了第二種。Linux下掛載問題的另一個(gè)根因是DPRDOS Partition Record分區(qū)表。有些MSC設(shè)備實(shí)現(xiàn)直接把整個(gè)介質(zhì)作為一個(gè)超級軟盤Superfloppy不寫分區(qū)表Windows認(rèn)Linux也認(rèn)。但如果設(shè)備擅自寫了一個(gè)分區(qū)表里面的分區(qū)偏移和大小與實(shí)際不符Windows會(huì)嘗試按分區(qū)表掛載Linux則直接拒絕并提示unable to read partition table。調(diào)試時(shí)我建議先用電腦把TF卡格式化成FAT32然后用十六進(jìn)制編輯器把前512字節(jié)導(dǎo)出保存為模板設(shè)備端在新卡初始化時(shí)直接寫入這個(gè)模板比手搓DBR可靠得多。6. 大文件拷貝必現(xiàn)崩潰緩沖區(qū)、DMA、看門狗連環(huán)坑6.1 崩潰現(xiàn)象記錄當(dāng)設(shè)備能在Windows和Linux下都正常識別后我進(jìn)行了拷貝測試。小文件沒問題幾十MB的文件也能正?？匠鰜淼坏┛截惓^300MB左右的單個(gè)大文件拷貝進(jìn)度到80%-90%時(shí)設(shè)備就會(huì)掉線Windows提示該設(shè)備的前一個(gè)USB設(shè)備已停止正常工作或者Linux下出現(xiàn)usb 1-2: reset full-speed USB device number 12 using xhci_hcd sd 4:0:0:0: [sdb] tag#0 FAILED Result: hostbyteDID_ERROR driverbyteDRIVER_OK blk_update_request: I/O error, dev sdb, sector 409600這種進(jìn)度過半就崩的現(xiàn)象非常有規(guī)律幾乎可以斷定是某個(gè)資源在長時(shí)間、大數(shù)據(jù)量傳輸下被耗盡。我猜測有三個(gè)方向USB接收緩沖溢出、SD卡寫入速度跟不上導(dǎo)致超時(shí)、看門狗復(fù)位。6.2 排查鏈路第一步是加日志。ESPS固件在USB中斷、SD卡寫回調(diào)、看門狗喂狗函數(shù)里都加了計(jì)數(shù)日志通過串口每隔1秒打印一次?？截惔笪募耐瑫r(shí)觀察串口輸出結(jié)果發(fā)現(xiàn)一個(gè)異常每次崩潰前串口都會(huì)輸出一行SD_WRITE_TIMEOUT錯(cuò)誤。這基本鎖定了問題方向USB從主機(jī)接收數(shù)據(jù)的速率大于SD卡實(shí)際寫入速率。PC在通過MSC寫文件時(shí)一次會(huì)發(fā)很多個(gè)WRITE(10)命令命令之間沒有握手等待USB協(xié)議站在Bulk傳輸層面允許設(shè)備用NAK來暫時(shí)阻止主機(jī)繼續(xù)發(fā)送。設(shè)備端如果來不及處理應(yīng)該在USB外設(shè)端點(diǎn)上產(chǎn)生NAK響應(yīng)給固件爭取時(shí)間。但ESPS實(shí)現(xiàn)的USB中斷處理邏輯里每收到一個(gè)OUT包就立刻把緩沖區(qū)交給SD卡DMA然后馬上重新使能端點(diǎn)接收。如果SD卡還在忙新數(shù)據(jù)又進(jìn)來了緩沖區(qū)就被覆蓋導(dǎo)致數(shù)據(jù)錯(cuò)亂。第二步查DMA和緩存一致性。ESPS主控是帶D-Cache的Cortex-M7內(nèi)核最初我為SD卡DMA分配了靜態(tài)緩沖區(qū)但忘了在DMA寫入SRAM之后、CPU讀取數(shù)據(jù)之前做Cache Invalidate操作。這就導(dǎo)致CPU讀到的是Cache里的舊數(shù)據(jù)數(shù)據(jù)損壞后FatFS文件系統(tǒng)直接報(bào)錯(cuò)主機(jī)會(huì)看到READ返回的數(shù)據(jù)和寫入時(shí)不匹配進(jìn)而報(bào)I/O錯(cuò)誤。第三步查看門狗。ESPS固件開啟了一個(gè)獨(dú)立看門狗正常喂狗調(diào)用在main主循環(huán)里。但在大文件拷貝時(shí)USB中斷頻率極高主循環(huán)如果被USB中斷長期搶占喂狗函數(shù)的執(zhí)行會(huì)被無限推遲最終看門狗超時(shí)復(fù)位整個(gè)系統(tǒng)。從崩潰現(xiàn)象來看設(shè)備掉線后電腦提示USB設(shè)備已停止工作這實(shí)際上就是MCU復(fù)位后USB會(huì)話斷開了。6.3 修復(fù)措施針對三個(gè)根因我逐一做了修改。緩沖策略改成雙緩沖乒乓結(jié)構(gòu)定義兩個(gè)緩沖區(qū)USB DMA先寫入緩沖區(qū)A寫滿后提示CPU處理同時(shí)USB端點(diǎn)立刻指向緩沖區(qū)B繼續(xù)接收主機(jī)數(shù)據(jù)。CPU在SD卡空閑時(shí)把緩沖區(qū)A的數(shù)據(jù)寫卡寫完后等待下次切換。這樣USB接收不被SD卡寫卡阻塞也不會(huì)因?yàn)榫彌_區(qū)覆蓋導(dǎo)致數(shù)據(jù)丟失。SD卡驅(qū)動(dòng)加了一層忙等待流控。每次接收完USB數(shù)據(jù)后先檢查SD卡狀態(tài)寄存器如果還在忙就在USB端點(diǎn)上返回NAK。USB協(xié)議本身允許Bulk端點(diǎn)無限NAK主機(jī)會(huì)等待設(shè)備準(zhǔn)備好不會(huì)因此超時(shí)。這一步很關(guān)鍵流的節(jié)奏掌握在設(shè)備手里而不是主機(jī)手里?？撮T狗問題通過調(diào)整喂狗策略解決。主循環(huán)仍然喂狗但在SD卡寫卡循環(huán)里也會(huì)定期喂狗同時(shí)把USB中斷處理邏輯縮短——中斷里只做緩沖區(qū)切換和事件計(jì)數(shù)真正的文件系統(tǒng)操作放到主循環(huán)里處理避免中斷長時(shí)間占用CPU也避免主循環(huán)餓死。DMA緩沖區(qū)通過MPU配置為不可緩存區(qū)域并保持Cache操作的正確性。修改后我再跑一次1GB大文件拷貝測試不再復(fù)現(xiàn)之前的崩潰。修復(fù)前后對比數(shù)據(jù)項(xiàng)修復(fù)前修復(fù)后拷貝300MB單文件約90%時(shí)設(shè)備掉線正常完成拷貝1GB單文件無法完成約2分15秒約7.5MB/s連續(xù)拷貝10個(gè)文件第3-4個(gè)文件時(shí)崩潰全部正常磁盤校驗(yàn)chkdsk有錯(cuò)誤無錯(cuò)誤這里說句實(shí)話7.5MB/s的速率在全速USB12Mbps理論上限附近因?yàn)閁SB全速帶寬本身只有1.5MB/s左右理論值MSC BOT協(xié)議還有帶寬損耗。當(dāng)時(shí)看到這個(gè)數(shù)據(jù)我第一反應(yīng)是哪里沒配置對后來仔細(xì)檢查才發(fā)現(xiàn)ESPS的主控USB控制器只支持全速不支持高速480Mbps。在USB 2.0全速模式下MSC實(shí)際傳輸速度上限約1MB/s讀操作能到1.2MB/s左右。上面數(shù)據(jù)的7.5MB/s是后來換用主板側(cè)的USB 2.0高速控制器重新測試的結(jié)果。這也提醒大家USB全速和高速差異巨大設(shè)計(jì)產(chǎn)品時(shí)如果對傳輸速度有要求選型時(shí)必須注意MCU的USB控制器是否支持高速。7. 全平臺驗(yàn)證與調(diào)試經(jīng)驗(yàn)沉淀7.1 驗(yàn)證矩陣與速度測試修完所有問題后我做了一輪全平臺驗(yàn)證不能只在Windows下跑通就交付。驗(yàn)證矩陣包括平臺枚舉讀取寫入格式化熱插拔Windows 10 x64通過通過通過通過通過Windows 11 x64通過通過通過通過通過Ubuntu 22.04通過通過通過不適用用mkfs.vfat通過macOS 13通過通過通過通過通過Android手機(jī)OTG通過通過只讀不適用部分通過Android OTG測試有點(diǎn)出乎意料ESPS枚舉成功但寫入權(quán)限受限。原因是ESPS上報(bào)的MSC邏輯單元沒有實(shí)現(xiàn)寫保護(hù)位但Android的存儲訪問框架有自己的策略非系統(tǒng)應(yīng)用無法直接寫入外部USB存儲。這個(gè)屬于平臺限制不影響主要場景用戶從ESPS往外拷數(shù)據(jù)。速度測試用ATTO Disk Benchmark和CrystalDiskMark各跑了一輪。在USB 2.0高速模式下讀速度約36MB/s寫速度約20MB/s達(dá)到了ESPS外殼上標(biāo)注的高速U盤水平。注意這個(gè)速度受限于TF卡自身的讀寫速度如果卡是Class 4的速度會(huì)明顯下降。建議量產(chǎn)時(shí)在說明文檔里注明推薦使用Class 10以上TF卡。7.2 幾條靠踩坑換來的經(jīng)驗(yàn)整個(gè)ESPS USB MSC調(diào)試下來有幾個(gè)經(jīng)驗(yàn)我覺得特別值得分享。第一個(gè)經(jīng)驗(yàn)USB問題調(diào)試抓包工具是最值得先投入學(xué)習(xí)的。很多人習(xí)慣拿串口日志加代碼review死磕遇到枚舉失敗這類問題會(huì)非常低效?；ò胄r(shí)學(xué)會(huì)用Wireshark抓USB包很多問題一眼就能看出來。我這次調(diào)試第一階段的枚舉失敗如果早用抓包可能半天就定位完了。第二個(gè)經(jīng)驗(yàn)廠商提供的USB MSC參考例程是起點(diǎn)但它只覆蓋了裸的MSC讀寫底層存儲介質(zhì)。真正復(fù)雜的部分是MSC層和文件系統(tǒng)層、底層驅(qū)動(dòng)、應(yīng)用任務(wù)的協(xié)作。尤其當(dāng)你有兩個(gè)系統(tǒng)同時(shí)在訪問同一張卡時(shí)必須設(shè)計(jì)好訪問權(quán)限的切換機(jī)制。ESPS的方案簡單粗暴但有效USB主機(jī)連接時(shí)獨(dú)占斷開后釋放給應(yīng)用層。第三個(gè)經(jīng)驗(yàn)代碼里每個(gè)關(guān)鍵路徑都要留日志而且日志要帶上時(shí)間戳和關(guān)鍵值。這次排大文件崩潰問題如果沒有串口日志里SD_WRITE_TIMEOUT那一行我可能會(huì)在USB配置上浪費(fèi)很多時(shí)間。日志系統(tǒng)的價(jià)值平時(shí)不明顯出問題時(shí)它就是最有力的線索。第四個(gè)經(jīng)驗(yàn)先確認(rèn)你的USB是Full Speed還是High Speed再談速度優(yōu)化。很多人在全速USB上做MSC折騰到最后發(fā)現(xiàn)速度上不去其實(shí)協(xié)議棧和代碼都沒問題只是硬件本身不支持高速。產(chǎn)品需求里若有導(dǎo)出大量數(shù)據(jù)的場景MCU選型建議直接選中帶USB HS控制器的芯片。再補(bǔ)充一個(gè)小技巧調(diào)試階段給ESPS板子保留一個(gè)UART串口調(diào)試引腳不要所有引腳都鋪完。USB問題調(diào)試過程中既要防止主循環(huán)餓死又要檢查中斷風(fēng)暴串口日志是唯一能同時(shí)觀察兩側(cè)狀態(tài)的手段。沒有串口你只能靠PC端的表現(xiàn)盲猜。后來我把這個(gè)調(diào)試引腳定義成了標(biāo)準(zhǔn)4Pin排針放在板子一角成了所有后續(xù)項(xiàng)目通用的調(diào)試口。最后說一下目前的狀態(tài)ESPS的USB MSC功能已經(jīng)穩(wěn)定跑了兩個(gè)月累計(jì)拷貝數(shù)據(jù)量超過200GB沒有再出現(xiàn)掉盤、文件損壞或枚舉失敗的問題。這次調(diào)試給我最大的體會(huì)是USB MSC這個(gè)簡單U盤背后是協(xié)議狀態(tài)機(jī)、底層存儲驅(qū)動(dòng)、系統(tǒng)兼容性和實(shí)時(shí)操作系統(tǒng)調(diào)度四者的深度融合任何一個(gè)環(huán)節(jié)欠賬最后都會(huì)在用戶插上電腦這個(gè)動(dòng)作上報(bào)復(fù)回來。