docs(sdcardio): replace init-order note with the real shared-SPI CS invariant#10962
Merged
dhalbert merged 3 commits intoadafruit:mainfrom Apr 21, 2026
Merged
Conversation
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.
dhalbert
requested changes
Apr 21, 2026
Collaborator
dhalbert
left a comment
There was a problem hiding this comment.
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.
Co-authored-by: Dan Halbert <halbert@adafruit.com>
Author
|
Looks good. Thx dan. |
dhalbert
approved these changes
Apr 21, 2026
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
.. important::note onsdcardio.SDCard.__init__to describe the actual invariant on a shared SPI bus.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_CShas 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