tartelette / documentation demossource ↗

sdcard: SD card

An SDHC card in SPI mode, backed by a disk image held in memory. It works with embedded-sdmmc, and other SPI-mode drivers that stick to the commands below should work too.

Keys

KeyTypeDefault
busspi0 | spi1the bus it sits on
csGPIOchip select, active low; left out, always selected
size_mb1..2048start with a blank card this size, in MiB; left out, the slot is empty
[buses]
spi1 = { sck = 10, mosi = 11, miso = 12 }

[parts.sd]
kind = "sdcard"
bus = "spi1"
cs = 8

Without an image, the slot is empty: the card never answers and the data line reads high, as with nothing in a real slot, so the firmware's card init times out. Loading an image (--sd, Load… or dropping one on the window) puts a card in, fresh from power-up. With size_mb, the board starts with a blank card instead: all zeros, no partition table, no file system. A firmware that formats its own card will be happy with that; most won't be. Make an image with tartelette mkdisk or any other tool:

tartelette mkdisk card.img --dir data      # 64 MiB, FAT32
tartelette fw.elf --board my-board.toml --sd sd=card.img

--sd NAME=FILE loads the image into the card called NAME. An image that's smaller than 512 KiB is padded. See running.md for saving it back, browsing it while it runs and --sd-live.

What's modelled

The card starts in native SD mode and ignores everything until it sees CMD0 with chip select low, which puts it in SPI mode. Then:

Command
CMD0go idle
CMD8interface condition (v2 card)
CMD9, CMD10CSD (v2) and CID
CMD12stop a multi-block read
CMD13status
CMD16block length
CMD17, CMD18single and multiple block read
CMD24, CMD25single and multiple block write
CMD55 + ACMD41initialisation (takes a few polls, as on a real card)
ACMD23pre-erase count
CMD58OCR, with CCS set: block addressing
CMD59CRC on / off

The CRC7 of CMD0 and CMD8 is always checked, and every command's once CRC is switched on, along with the CRC16 on data blocks in both directions. Anything else gets "illegal command".

Timing is counted in bytes, not clocks: a response comes one byte after the command, a data block one byte after its response, and the card holds the data line low (busy) for a few bytes after each block written.

Panel

The card's size and whether the firmware has written to it, with Load…, Save… and Browse… buttons; for an empty slot, "no card" and just Load…. Browse shows the files on a snapshot of the card (FAT12/16/32, whole disk or partitioned), with text and hex preview.

Not modelled

Standard-capacity (SDSC) cards with byte addressing and CSD v1, erase commands, write protect, card detect, and native SD (4-bit) mode.