Shop OBEX P1 Docs P2 Docs Learn Events
P2 uSD Card Driver — FAT32 Filesystem (spin2/pasm2) — Parallax Forums

P2 uSD Card Driver — FAT32 Filesystem (spin2/pasm2)

Stephen MoracoStephen Moraco Posts: 412
edited 2026-02-26 01:18 in Propeller 2

New P2 uSD Card Driver — FAT32 Filesystem with Smart Pin SPI

Version 1.0.0

This is the first public release of a new FAT32-compliant microSD card filesystem driver for the P2. It started as a study of Chris Gadd's OB4269 driver from OBEX and evolved into a complete rewrite — smart pin SPI, streamer DMA, multi-file handles, multi-cog access, and a full set of card utilities you can run directly from the P2 with no PC tools needed.

What's in the box

  • Driver (micro_sd_fat32_fs.spin2) — FAT32 read/write with smart pin SPI + streamer DMA, dedicated worker cog, hardware lock serialization, up to 6 simultaneous file/directory handles, per-cog working directories
  • Card Formatter — Format any SDHC/SDXC card as FAT32 directly from the P2. Cross-OS compatible (Windows, macOS, Linux can read the result)
  • Filesystem Repair — 4-pass fsck with auto-repair: structural integrity, chain validation, lost cluster recovery, FAT sync. Plus a separate read-only audit (41 checks)
  • Benchmark & Characterizer — Measure raw sector and filesystem throughput, read card registers to identify manufacturer, capacity, speed class, and SD spec version
  • Demo Shell — Interactive terminal with dir, cd, type, format, fsck, audit, bench, and more
  • Example Programs — Four compilable examples: basic read/write, data logger with sync, directory walk, and multi-cog concurrent access
  • Tutorial — See SD Card Driver — Tutorial

20 cards tested across 9 manufacturers — see the Card Performance Guide for ranked comparisons, purchase recommendations, and card sizing guidance.

Testing: 345+ automated regression tests across 19 test suites, all validated on hardware.

Known limitations:

  • 8.3 filenames only (no LFN)
  • SPI mode only, 25 MHz maximum
  • Tested with cards up to 128 GB; driver goal is full 2 TB support (FAT32/SDXC maximum) in an upcoming release
  • Currently compiles with pnut/pnut-ts. Flexspin and Spin Tools IDE compile will be supported in next release.

Hardware: P2 Edge Module (has built-in microSD socket), or any P2 board with the microSD Add-on Board (#64009). The default pin configuration is base pin 56 (P2 Edge).

Visit the P2 microSD FAT32 Filesystem repository for full documentation, including a driver tutorial, theory of operations, and card catalog.

The release package can be downloaded from the Releases page.

If you find issues, please file them at the Issues page.

What's next? Ensuring this driver and utilities compile with all of our compilers. Expanding card size support toward the full 2 TB FAT32 limit, researching windowed FSCK validation for larger cards, and investigating the Silicon Power CMD18 compatibility issue. I also want to look into whether A2 command queuing features can/should be leveraged in SPI mode.

Enjoy!

Stephen

Comments

  • roglohrogloh Posts: 6,255

    Wow this is very extensive @"Stephen Moraco" . It looks very comprehensive from my initial browse on GitHub. I really like how you've collected and documented all the important design decisions here too, lots of stuff everyone can learn from. It will be great to try this out when I get a chance. I also like how it supports multi-COG operation, that opens up lots of interesting possibilities for P2 COG based apps/tools that could be run simultaneously and sharing the same filesystem. Very nice indeed!

  • ke4pjwke4pjw Posts: 1,283

    YES! Thank you @"Stephen Moraco" ! I love that it is handle based. This is the missing piece for me using tasks in spin to do a task switching webserver with multiple sockets. I will take it for a test drive this weekend using Spin Tools.

  • Francis BauerFrancis Bauer Posts: 406

    @"Stephen Moraco" , great work. I just started trying out the new driver.
    I started by running the SD_example_directory_walk program. The program seemed run correctly, but one thing I noticed is that the Volume Name that was displayed as "NO NAME", when the freshly formatted (using Windows 11 format) 8 GB SD card had a volume label of "P2DATA" defined.
    I'm not sure what is going on, is there an alternate location for where the volume label is stored?

    Cog0  INIT $0000_0000 $0000_0000 load
Cog0  INIT $0000_0F64 $0000_6ACC jump
Cog0  === SD Directory Walk Example ===
Cog1  INIT $0000_0F64 $0000_1D2C jump
Cog0  Volume: sd.volumeLabel() = "NO NAME    "
Cog0  Free:   sd.freeSpace() >> 11 = 7_423 MB
Cog0   
Cog0  --- Root Directory ---
Cog0    [DIR]  @name_copy = "EXDIR"
Cog0   
Cog0  --- Creating EXDIR with files ---
Cog0   
Cog0  --- EXDIR contents (via directory handle) ---
Cog0    [DIR]  @name_copy = "."
Cog0    [DIR]  @name_copy = ".."
Cog0    [FILE] @name_copy = "FILE_A.TXT"  sd.fileSize() = 18 bytes
Cog0    [FILE] @name_copy = "RENAMED.TXT"  sd.fileSize() = 18 bytes
Cog0    [FILE] @name_copy = "FILE_B.TXT"  sd.fileSize() = 18 bytes
Cog0    [FILE] @name_copy = "TEMP.TXT"  sd.fileSize() = 14 bytes
Cog0   
Cog0  --- File management ---
Cog0  Deleted TEMP.TXT
Cog0  Renamed FILE_B.TXT -> RENAMED.TXT
Cog0   
Cog0  --- EXDIR after changes ---
Cog0    [DIR]  @name_copy = "."
Cog0    [DIR]  @name_copy = ".."
Cog0    [FILE] @name_copy = "FILE_A.TXT"  sd.fileSize() = 18 bytes
Cog0    [FILE] @name_copy = "RENAMED.TXT"  sd.fileSize() = 18 bytes
Cog0    [FILE] @name_copy = "FILE_B.TXT"  sd.fileSize() = 18 bytes
Cog0   
Cog0  === Done ===
  • evanhevanh Posts: 17,080
    edited 2026-02-26 09:08

    That is substantial. And filesystems are far from simple logic so I presume the bulk of it is ported. What is the original source code?

    I'd very much like to plug in my 4-bit SD mode low level driver. What you've got would need some reworking to suit having a low level interface though. There's way too many low level functions as it stands.

    Although it doesn't have to be this small, the basic interface is just cardinit(), readblocks() and writeblocks().

  • maccamacca Posts: 999

    Great job!

    @"Stephen Moraco" said:

    • Currently compiles with pnut/pnut-ts. Flexspin and Spin Tools IDE compile will be supported in next release.

    Just a note for Spin Tools:

    You may replace the #PRAGMA EXPORTDEF SD_INCLUDE_ALL that throw and error with #DEFINE SD_INCLUDE_ALL, the result is the same because in Spin Tools the #defines are propagated to child objects.

    I'll add support for EXPORTDEF in the next release anyway, until then you can also use the conditional compile to be compatible with both:

    #IFDEF __SPINTOOLS__
#DEFINE SD_INCLUDE_ALL
#ELSE
#PRAGMA EXPORTDEF SD_INCLUDE_ALL
#ENDIF

    I hope you can implement support for long file names in the future, that will be really great.

  • RaymanRayman Posts: 16,076
    edited 2026-02-26 09:54

    This looks really nice. Looking forward to FlexProp and Spin Tools support.
    How much memory does it need?

Sign In or Register to comment.