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