Skip to content

docs(sdcardio): replace init-order note with the real shared-SPI CS invariant#10962

Merged
dhalbert merged 3 commits intoadafruit:mainfrom
mikeysklar:docs-sdcardio-cs-invariant
Apr 21, 2026
Merged

docs(sdcardio): replace init-order note with the real shared-SPI CS invariant#10962
dhalbert merged 3 commits intoadafruit:mainfrom
mikeysklar:docs-sdcardio-cs-invariant

Conversation

@mikeysklar
Copy link
Copy Markdown

Supersedes #10947 and #10961. Per @dhalbert's note on #10961, folding the revert and the rewrite into one PR so we don't run two merge builds.

What this does

Why

The previous note said the SD card must be initialized before any other peripheral on a shared SPI bus. That rule worked in practice because every co-resident CS line on the supported boards had a hardware pull-up silently keeping the bus clean at boot — not because SD card init has to come first. As @bablokb pointed out on #10947, the real invariant is that every CS pin on the shared bus must be in a known HIGH (deselected) state before any SPI transaction, whether guaranteed by a hardware pull-up or driven HIGH in software. Init order is secondary.

The Feather RP2040 RFM is the board that exposes the gap: RFM_CS has no pull-up, so it floats and corrupts the bus during SD init unless the user drives it HIGH first. #10947 tried to document this as an "exception to the SD-first rule" — but the SD-first rule itself was only ever a proxy for the real CS-state invariant, so documenting the invariant directly is the correct fix.

Context

The previous ".. important::" note said SD card init must come first on
a shared SPI bus. That rule happened to work when every co-resident CS
line had a hardware pull-up, but it is not the real invariant: what
actually matters is that every CS on the shared bus is in a known HIGH
(deselected) state before any SPI transaction. On boards where a CS
floats (e.g. the Feather RP2040 RFM, whose RFM_CS has no pull-up), it
must be driven HIGH in software; init order is secondary.
Copy link
Copy Markdown
Collaborator

@dhalbert dhalbert left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this slight clarification is fine with you, you or I can just apply the suggestion, and then I'll approve and merge.

Thanks for the clarification and rewrite.

Comment thread shared-bindings/sdcardio/SDCard.c Outdated
Co-authored-by: Dan Halbert <halbert@adafruit.com>
@mikeysklar
Copy link
Copy Markdown
Author

Looks good. Thx dan.

@dhalbert dhalbert merged commit 9cf5880 into adafruit:main Apr 21, 2026
76 of 577 checks passed
@bablokb
Copy link
Copy Markdown

bablokb commented Apr 21, 2026

the SPI bus can be corrupted

Maybe this is nitpicking, but is this really true? I don't think the SPI bus cares about the data. I think the core problem is that a floating CS might fool a peripheral into thinking that data on the bus is for itself, thus corrupting the device state because most probably it receives wrong commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants