User description

Summary

Fixes USB Mass Storage mode on H743 boards and improves SDIO SD card reliability.

Problem Statement

USB MSC mode is broken on H743 flight controllers in INAV 8.0.1+:

• Windows shows "Virtual COM Port in FS Mode" error instead of mass storage device
• SD card reports "device offline" errors when accessed via USB MSC
• Users report occasional blackbox recording gaps and slow/unreliable SD writes on H7

Root Causes Identified

1. USB Descriptor Mismatch

The USB library update (v2.5.3 → v2.11.3) in commit 16ebb27 introduced stricter descriptor requirements. H7 MSC mode was attemtpoing to use composite mode with both mass storage (MSC) and CDC (VCP) descriptors, but that failed because the HAL changed between 2018 and 2024. This caused Windows enumeration to fail.

2. SDIO DMA Alignment Requirements

H7 SDIO DMA requires 32-byte aligned buffers, but the USB MSC library's bot_data buffer is only 16-byte aligned (at offset 16 in the structure). This caused USB MSC read operations to fail with SD_ADDR_MISALIGNED errors.

3. Aggressive Error Handling

Any SDIO operation failure immediately triggered a full card reset, causing recording gaps. This was also problematic when USB interrupts interfered with SDIO DMA completion.

Changes

USB MSC Descriptor Fix (src/main/vcp_hal/usbd_desc.c, usbd_desc.h)

• Added standalone MSC descriptor structure (MSC_Desc) separate from VCP descriptors
• Provides proper device class (0x00) and product strings for MSC mode
• Modified H7 MSC initialization to use MSC_Desc instead of VCP_Desc

SDIO DMA Alignment Fix (src/main/msc/usbd_storage_sd_spi.c)

• Added 32-byte aligned intermediate buffer for H7+SDIO configurations
• Modified STORAGE_Read() and STORAGE_Write() to copy data through aligned buffer
• Platform-specific using #if defined(STM32H7) && defined(USE_SDCARD_SDIO)
• No impact on F4/F7 or SPI-based SD card implementations

Retry Logic (src/main/drivers/sdcard/sdcard_impl.h, sdcard_sdio.c)

• Added operationRetries counter to sdcard state structure
• Retry failed operations up to 3 times with 1ms delays before triggering card reset
• Applied to both read and write paths
• Counter reset on successful operations and card initialization

Testing

• ✅ USB MSC enumeration works on Linux
• USB MSC enumeration works on Windows
• ✅ SD card accessible via USB MSC mode (31.3GB detected)
• ✅ Normal VCP mode confirmed working
• ✅ Build successful for BROTHERHOBBYH743 target

Technical Details

• F7 SDIO driver skips alignment check (#ifndef STM32F7)
• H7 requires alignment due to D-Cache invalidation requirements
• USB MSC buffer misalignment measured at offset 16 (needs offset 0 or 32)
• Intermediate buffer adds minimal overhead (single memcpy per 512-byte block)
• Retry logic adds only ~128 bytes to firmware size

Benefits

• Restores USB MSC functionality on H7 boards
• Reduces blackbox recording gaps from spurious SD card resets
• Improves overall SD card reliability when USB is active
• Handles transient DMA/bus conflicts gracefully

Platform Impact

• H7 only: Alignment fix and retry logic most beneficial
• F4/F7: Retry logic provides minor reliability improvement
• SPI SD cards: Unaffected by alignment changes

Fixes

Closes #10800

Related Issues

• Issue MSC broken for H743 - 8.0.1 #10800: H7 USB MSC regression in 8.0.1

PR Type

Bug fix, Enhancement

Description

This description is generated by an AI tool. It may have inaccuracies

• Fix H743 USB MSC regression by using standalone MSC descriptors instead of VCP descriptors

  • Resolves Windows enumeration failure with USB library v2.11.3
  • Provides proper MSC device class and product strings

• Add 32-byte aligned intermediate buffer for H7 SDIO DMA operations

  • Fixes SD_ADDR_MISALIGNED errors during USB MSC read/write operations
  • Platform-specific implementation for H7+SDIO configurations only

• Implement retry logic for transient SDIO operation failures

  • Retries up to 3 times with 1ms delays before triggering card reset
  • Reduces blackbox recording gaps from spurious SD card resets

• Improve SD card initialization with timeout and existing state checks

  • Prevents infinite loops and handles already-initialized cards gracefully

Diagram Walkthrough

flowchart LR
  A["USB MSC Mode"] -->|"Use MSC_Desc"| B["Standalone MSC Descriptors"]
  B -->|"Proper Device Class"| C["Windows Enumeration Fixed"]
  D["H7 SDIO DMA"] -->|"32-byte Aligned Buffer"| E["Intermediate Buffer"]
  E -->|"Copy Data"| F["Aligned Read/Write"]
  G["SDIO Operation"] -->|"Fails"| H["Retry Logic"]
  H -->|"< 3 Retries"| I["Retry with Delay"]
  H -->|">= 3 Retries"| J["Card Reset"]
  I -->|"Success"| K["Reset Counter"]