SPI SD-Card driver

Driver for reading and writing sd-cards via spi interface.

enum sd_version_t
SD_V2
SD version 2.
SD_V1
SD version 1.
MMC_V3
MMC version 3.
SD_UNKNOWN
SD-version unknown.
enum sd_rw_response_t
SD_RW_OK = 0
no error
SD_RW_NO_TOKEN
no token was received (on block read)
SD_RW_TIMEOUT
cmd timed out (not-busy-state wasn’t entered)
SD_RW_RX_TX_ERROR
error while performing SPI read/write
SD_RW_WRITE_ERROR
data-packet response indicates error
SD_RW_CRC_MISMATCH
CRC-mismatch of received data.
SD_RW_NOT_SUPPORTED
operation not supported on used card
int sdcard_spi_init(sdcard_spi_t * card, const sdcard_spi_params_t * params)

Initializes the sd-card with the given parameters in sdcard_spi_t structure.

The init procedure also takes care of initializing the spi peripheral to master mode and performing all neccecary steps to set the sd-card to spi-mode. Reading the CID and CSD registers is also done within this routine and their values are copied to the given sdcard_spi_t struct.

Parameters

card:the device descriptor
params:parameters for this device (pins and spi device are initialized by this driver)

Return values

  • 0 if the card could be initialized successfully
  • false if an error occured while initializing the card
int sdcard_spi_read_blocks(sdcard_spi_t * card, int blockaddr, char * data, int blocksize, int nblocks, sdcard_spi.h::sd_rw_response_t * state)

Reads data blocks (usually multiples of 512 Bytes) from card to buffer.

Parameters

card:Initialized sd-card struct
blockaddr:Start adress to read from. Independet of the actual adressing scheme of the used card the adress needs to be given as block address (e.g. 0, 1, 2… NOT: 0, 512… ). The driver takes care of mapping to byte adressing if needed.
data:Buffer to store the read data in. The user is responsible for providing a suitable buffer size.
blocksize:Size of data blocks. For now only 512 byte blocks are supported because only older (SDSC) cards support variable blocksizes anyway. With SDHC/SDXC-cards this is always fixed to 512 bytes. SDSC cards are automatically forced to use 512 byte as blocksize by the init procedure.
nblocks:Number of blocks to read
state:Contains information about the error state if something went wrong (if return value is lower than nblocks).

Return values

  • number of successfully read blocks (0 if no block was read).
int sdcard_spi_write_blocks(sdcard_spi_t * card, int blockaddr, const char * data, int blocksize, int nblocks, sdcard_spi.h::sd_rw_response_t * state)

Writes data blocks (usually multiples of 512 Bytes) from buffer to card.

Parameters

card:Initialized sd-card struct
blockaddr:Start adress to read from. Independet of the actual adressing scheme of the used card the adress needs to be given as block address (e.g. 0, 1, 2… NOT: 0, 512… ). The driver takes care of mapping to byte adressing if needed.
data:Buffer that contains the data to be sent.
blocksize:Size of data blocks. For now only 512 byte blocks are supported because only older (SDSC) cards support variable blocksizes anyway. With SDHC/SDXC-cards this is always fixed to 512 bytes. SDSC cards are automatically forced to use 512 byte as blocksize by the init procedure.
nblocks:Number of blocks to write
state:Contains information about the error state if something went wrong (if return value is lower than nblocks).

Return values

  • number of successfully written blocks (0 if no block was written).
uint64_t sdcard_spi_get_capacity(sdcard_spi_t * card)

Gets the capacity of the card.

Parameters

card:Initialized sd-card struct

Return values

  • capacity of the card in bytes
SD_HC_BLOCK_SIZE

size of a single block on SDHC cards 

1
(512)
SDCARD_SPI_INIT_ERROR

returned on failed init 

1
(-1)
SDCARD_SPI_OK

returned on successful init 

1
(0)
SD_SIZE_OF_OID

OID (OEM/application ID field in CID reg) 

1
2
SD_SIZE_OF_PNM

PNM (product name field in CID reg) 

1
5
struct cid_t

CID register see section 5.2 in SD-Spec v5.00.

uint8_t MID

Manufacturer ID.

char OID()

OEM/Application ID.

char PNM()

Product name.

uint8_t PRV

Product revision.

uint32_t PSN

Product serial number.

uint16_t MDT

Manufacturing date.

uint8_t CID_CRC

CRC7 checksum.

struct csd_v1_t

CSD register with csd structure version 1.0 see section 5.3.2 in SD-Spec v5.00.

uint8_t CSD_STRUCTURE

see section 5.3.2 in SD-Spec v5.00

uint8_t TAAC

see section 5.3.2 in SD-Spec v5.00

uint8_t NSAC

see section 5.3.2 in SD-Spec v5.00

uint8_t TRAN_SPEED

see section 5.3.2 in SD-Spec v5.00

uint16_t CCC

see section 5.3.2 in SD-Spec v5.00

uint8_t READ_BL_LEN

see section 5.3.2 in SD-Spec v5.00

uint8_t READ_BL_PARTIAL

see section 5.3.2 in SD-Spec v5.00

uint8_t WRITE_BLK_MISALIGN

see section 5.3.2 in SD-Spec v5.00

uint8_t READ_BLK_MISALIGN

see section 5.3.2 in SD-Spec v5.00

uint8_t DSR_IMP

see section 5.3.2 in SD-Spec v5.00

uint16_t C_SIZE

see section 5.3.2 in SD-Spec v5.00

uint8_t VDD_R_CURR_MIN

see section 5.3.2 in SD-Spec v5.00

uint8_t VDD_R_CURR_MAX

see section 5.3.2 in SD-Spec v5.00

uint8_t VDD_W_CURR_MIN

see section 5.3.2 in SD-Spec v5.00

uint8_t VDD_W_CURR_MAX

see section 5.3.2 in SD-Spec v5.00

uint8_t C_SIZE_MULT

see section 5.3.2 in SD-Spec v5.00

uint8_t ERASE_BLK_EN

see section 5.3.2 in SD-Spec v5.00

uint8_t SECTOR_SIZE

see section 5.3.2 in SD-Spec v5.00

uint8_t WP_GRP_SIZE

see section 5.3.2 in SD-Spec v5.00

uint8_t WP_GRP_ENABLE

see section 5.3.2 in SD-Spec v5.00

uint8_t R2W_FACTOR

see section 5.3.2 in SD-Spec v5.00

uint8_t WRITE_BL_LEN

see section 5.3.2 in SD-Spec v5.00

uint8_t WRITE_BL_PARTIAL

see section 5.3.2 in SD-Spec v5.00

uint8_t FILE_FORMAT_GRP

see section 5.3.2 in SD-Spec v5.00

uint8_t COPY

see section 5.3.2 in SD-Spec v5.00

uint8_t PERM_WRITE_PROTECT

see section 5.3.2 in SD-Spec v5.00

uint8_t TMP_WRITE_PROTECT

see section 5.3.2 in SD-Spec v5.00

uint8_t FILE_FORMAT

see section 5.3.2 in SD-Spec v5.00

uint8_t CSD_CRC

see section 5.3.2 in SD-Spec v5.00

struct csd_v2_t

CSD register with csd structure version 2.0 see section 5.3.3 in SD-Spec v5.00.

uint8_t CSD_STRUCTURE

see section 5.3.3 in SD-Spec v5.00

uint8_t TAAC

see section 5.3.3 in SD-Spec v5.00

uint8_t NSAC

see section 5.3.3 in SD-Spec v5.00

uint8_t TRAN_SPEED

see section 5.3.3 in SD-Spec v5.00

uint16_t CCC

see section 5.3.3 in SD-Spec v5.00

uint8_t READ_BL_LEN

see section 5.3.3 in SD-Spec v5.00

uint8_t READ_BL_PARTIAL

see section 5.3.3 in SD-Spec v5.00

uint8_t WRITE_BLK_MISALIGN

see section 5.3.3 in SD-Spec v5.00

uint8_t READ_BLK_MISALIGN

see section 5.3.3 in SD-Spec v5.00

uint8_t DSR_IMP

see section 5.3.3 in SD-Spec v5.00

uint32_t C_SIZE

see section 5.3.3 in SD-Spec v5.00

uint8_t ERASE_BLK_EN

see section 5.3.3 in SD-Spec v5.00

uint8_t SECTOR_SIZE

see section 5.3.3 in SD-Spec v5.00

uint8_t WP_GRP_SIZE

see section 5.3.3 in SD-Spec v5.00

uint8_t WP_GRP_ENABLE

see section 5.3.3 in SD-Spec v5.00

uint8_t R2W_FACTOR

see section 5.3.3 in SD-Spec v5.00

uint8_t WRITE_BL_LEN

see section 5.3.3 in SD-Spec v5.00

uint8_t WRITE_BL_PARTIAL

see section 5.3.3 in SD-Spec v5.00

uint8_t FILE_FORMAT_GRP

see section 5.3.3 in SD-Spec v5.00

uint8_t COPY

see section 5.3.3 in SD-Spec v5.00

uint8_t PERM_WRITE_PROTECT

see section 5.3.3 in SD-Spec v5.00

uint8_t TMP_WRITE_PROTECT

see section 5.3.3 in SD-Spec v5.00

uint8_t FILE_FORMAT

see section 5.3.3 in SD-Spec v5.00

uint8_t CSD_CRC

see section 5.3.3 in SD-Spec v5.00

union csd_t

CSD register (see section 5.3 in SD-Spec v5.00)

struct sd_status_t

SD status register (see section 4.10.2 in SD-Spec v5.00)

uint32_t SIZE_OF_PROTECTED_AREA

see section 4.10.2 in SD-Spec v5.00

uint32_t SUS_ADDR

see section 4.10.2.12 in SD-Spec v5.00

uint32_t VSC_AU_SIZE

see section 4.10.2.11 in SD-Spec v5.00

uint16_t SD_CARD_TYPE

see section 4.10.2 in SD-Spec v5.00

uint16_t ERASE_SIZE

see section 4.10.2.5 in SD-Spec v5.00

uint8_t SPEED_CLASS

see section 4.10.2.2 in SD-Spec v5.00

uint8_t PERFORMANCE_MOVE

see section 4.10.2.3 in SD-Spec v5.00

uint8_t VIDEO_SPEED_CLASS

see section 4.10.2.10 in SD-Spec v5.00

uint8_t ERASE_TIMEOUT

see section 4.10.2.6 in SD-Spec v5.00

uint8_t ERASE_OFFSET

see section 4.10.2.7 in SD-Spec v5.00

uint8_t UHS_SPEED_GRADE

see section 4.10.2.8 in SD-Spec v5.00

uint8_t UHS_AU_SIZE

see section 4.10.2.9 in SD-Spec v5.00

uint8_t AU_SIZE

see section 4.10.2.4 in SD-Spec v5.00

uint8_t DAT_BUS_WIDTH

see section 4.10.2 in SD-Spec v5.00

uint8_t SECURED_MODE

see section 4.10.2 in SD-Spec v5.00

struct sdcard_spi_params_t

sdcard_spi device params

spi.h::spi_t spi_dev

SPI bus used.

gpio.h::gpio_t cs

pin connected to the DAT3 sd pad

gpio.h::gpio_t clk

pin connected to the CLK sd pad

gpio.h::gpio_t mosi

pin connected to the CMD sd pad

gpio.h::gpio_t miso

pin connected to the DAT0 sd pad

gpio.h::gpio_t power

pin that controls sd power circuit

bool power_act_high

true if card power is enabled by ‘power’-pin HIGH

struct sdcard_spi_t

Device descriptor for sdcard_spi.

sdcard_spi_params_t params

parameters for pin and spi config

atmega_common/include/periph_cpu_common.h::spi_clk_t spi_clk

active SPI clock speed

bool use_block_addr

true if block adressing (vs.

byte adressing) is used

bool init_done

set to true once the init procedure completed successfully

sdcard_spi.h::sd_version_t card_type

version of SD-card

int csd_structure

version of the CSD register structure

cid_t cid

CID register.

csd_t csd

CSD register.