Minor optimizations, safety fixes for corrupted filesystems, and doc updates

[Chamath-Adithya]

Description

This PR provides a collection of performance micro-optimizations, safety improvements for corrupted filesystems, and minor documentation updates.

All changes are strictly no_std and no_alloc compatible.

What's Changed

1. Division/Modulo Removal in FAT Traversals

   • Replaced remainder division operations (% Block::LEN_U32 and / Block::LEN_U32) with fast bitwise masking (& (Block::LEN_U32 - 1) i.e., & 511) and bit shifts (>> 9).
   • On bare-metal microcontrollers without hardware division support, this avoids expensive compiler software division library calls in hot traversal paths (next_cluster, find_next_free_cluster, update_fat).

2. Unsafe Block Reductions

   • Replaced unsafe { open_files.push_unchecked(...) } in VolumeManager with safe checked pushes. Since we already perform boundary/capacity checks immediately before pushing, the unsafe block was redundant.
   • Replaced unsafe from_utf8_unchecked in LfnBuffer::as_str with core::str::from_utf8. Since the internal buffer only accumulates valid UTF-8, this is a zero-cost safety improvement.

3. Robustness Against Corrupted Media/CSDs

   • Guarded bytes_per_cluster calculations with checked_mul to protect against corrupted volume geometries.
   • Guarded cluster index conversions with saturating_sub(2) to prevent subtraction underflows in debug builds when encountering corrupted/invalid cluster indexes < 2.
   • Prevented division-by-zero panics in parse_volume for root directories by validating blocks_per_cluster != 0.
   • Hardened CSD parsing against out-of-bound shifts and arithmetic overflows when encountering unsupported or corrupted SD card data.

4. Testing

   • Added unit tests checking the LfnBuffer boundary and empty buffer handling.
   • Added unit tests checking cluster-to-block saturating conversions on border inputs (0, 1, and 2).

5. Documentation

   • Added short architectural explanations to alloc_cluster explaining FAT traversal/zeroing mechanics.
   • Documented the internal locking, static generic memory bounds, and division-free properties of VolumeManager.

All 45 tests build and pass cleanly.

[thejpster]

I looked at a couple at random and I’m not convinced these are useful. Please don’t drop 17 commits on us without discussing the fixes first, eg in the form of an issue.

If you used an LLM to generate these then I refer you to the CONTRIBUTING file.