Integration Challenges with LittleFS on STM32H5 QSPI External Flash

[Vaishak-hoomanely]

Hi LittleFS community,
We're integrating LittleFS into our STM32H5-based system using the QSPI (OctoSPI) peripheral to manage an external Winbond W25Q256JW flash chip.
Setup Summary:

• STM32H5 MCU with external 256Mbit Winbond W25Q256JW flash via Quad SPI in half/OctoSPI mode
• PSRAM used as intermediate buffer for thermal and camera data, offloaded to flash via LittleFS
• LittleFS version [specify if known]; customized with platform-specific flash drivers
• FreeRTOS-based firmware with full internal SRAM allocation for task stacks and mutexes (to avoid deadlocks)

Observed Symptoms:

• Large file writes (~300-500KB) succeed initially but sometimes cause assertion failures during file truncation
• Occasional hangs or timeouts when performing batch writes or recovery operations in LittleFS
• Data corruption suspected during truncation or after cache flush operations
• Watchdog suppressions during offload tasks lead to hard faults under mutex contention
• Challenges with mutex timeout hierarchy causing priority inversion and deadlocks during flash access

Request for Guidance:

1. Are there known best practices or configuration recommendations specific to STM32 or Winbond W25Q256JW flash to avoid truncation assertion failures?
2. What are typical LittleFS configuration parameters (block size, cache size, lookahead size, block cycles) that work well with similar external flash setups?
3. Any advice on mutex management or offload scheduling to prevent priority inversion deadlocks under concurrent flash use?
4. Recommendations for robust power-loss recovery strategies integrated with LittleFS on external flash?
5. We welcome any insights, example configurations, or patches to improve stability and performance in this environment.

[geky]

Hi @Vaishak-hoomanely,

I'm unaware of any known truncate-related bugs. Is it possible to replicate this behavior locally? Possibly in a littlefs test case (example, testing)?

• Occasional hangs or timeouts when performing batch writes or recovery operations in LittleFS

There are a number of high-latency pitfalls in littlefs. There is ongoing work to improve this, but at the moment there are cases where single function calls can take an extreme amount of time to complete. More info may be needed to know the exact case here, but issues marked with performance may be interesting to browse.

• Challenges with mutex timeout hierarchy causing priority inversion and deadlocks during flash access

Are you yielding in your block device operations (prog, read, erase, sync)? If not, I think yielding would at least solve deadlocks (taskYIELD?), though this may only work if the filesystem thread is low-priority. If high-priority threads need to interact with the filesystem, maybe this can be accomplished with a dedicated low-priority filesystem thread + message passing/queues?

Even if littlefs was perfectly performant, blocking threads while waiting for QSPI transactions is not ideal. (Note littlefs is IO-bound not CPU-bound, all latency spikes should involve a block device operation.)

2. What are typical LittleFS configuration parameters (block size, cache size, lookahead size, block cycles) that work well with similar external flash setups?

For W25Q256JW I would suggest starting with:

.read_size = 1,
.prog_size = 1,
.block_size = 4096, // erase size
.cache_size = 256, // very arbitrary, needs ~3x RAM
.lookahead_size = 256, // very arbitrary, needs ~1x RAM
.block cycles = 100, // somewhat arbitrary, trades wear distribution for performance

But I would encourage tweaking these to find the best per-application/device configuration.

4. Recommendations for robust power-loss recovery strategies integrated with LittleFS on external flash?

LittleFS is designed with the intention of making powerloss safety easy, and W25Q256JW is a relatively simple device, so for the most part it should just work.

For example: LittleFS uses per-file snapshots, so it's not possible to end up with intermediate file states until you call sync or close. Unfortunately this does make performance issues more noticeable.