Low-level SDIO/SD/MMC peripheral driver. More...

Detailed Description

Low-level SDIO/SD/MMC peripheral driver.

The low-level SDIO/SD/MMC peripheral driver interface as used by high-level SDIO/SD/MMC device API functions. It has to be implemented for a specific CPU.

Note
High-level functions such as sdmmc_read_blocks are provided by the SDIO/SD/MMC API and should be used instead. Directly calling these functions is not recommended.

Definition at line 956 of file sdmmc.h.

#include <sdmmc.h>

Data Fields

void(* init )(sdmmc_dev_t *dev)
 Basic initialization of the given SDIO/SD/MMC device. More...
 
int(* send_cmd )(sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, sdmmc_resp_t resp_type, uint32_t *resp)
 Send command to SDIO/SD/MMC Card and optionally wait for response. More...
 
int(* card_init )(sdmmc_dev_t *dev)
 Card Initialization and Identification. More...
 
int(* set_bus_width )(sdmmc_dev_t *dev, sdmmc_bus_width_t width)
 Set data bus width. More...
 
int(* set_clock_rate )(sdmmc_dev_t *dev, sdmmc_clock_rate_t rate)
 Set SD CLK signal rate. More...
 
int(* enable_clock )(sdmmc_dev_t *dev, bool enable)
 Enable or disable the SD CLK signal. More...
 
int(* xfer_prepare )(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer)
 Prepare a data transfer. More...
 
int(* xfer_execute )(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer, const void *data_wr, void *data_rd, uint16_t *done)
 Execute the data transfer. More...
 
int(* xfer_finish )(sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer)
 Finish the data transfer. More...
 

Field Documentation

◆ card_init

int(* sdmmc_driver_t::card_init) (sdmmc_dev_t *dev)

Card Initialization and Identification.

Warning
Usually the standard procedure implemented by the high-level SDIO/SD/MMC device API function sdmmc_card_init is used for card initialization and identification (recommended). The low-level SDIO/SD/MMC peripheral driver should implement its own sdmmc_driver_t::card_init function only in very special cases, e.g. when special hardware handling is required. Therefore, this driver function should be set to NULL, that is the card initialization and identification function is not implemented by low-level SDIO/SD/MMC peripheral driver
See also
sdmmc_card_init
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card is not supported or can't operate under supplied voltage
-EFAULTon card status error
-ETIMEDOUTon card initialization and identification timeout
-EBADMSGon CRC7 error
-EIOon not further specified error incl. hardware errors

Definition at line 1060 of file sdmmc.h.

◆ enable_clock

int(* sdmmc_driver_t::enable_clock) (sdmmc_dev_t *dev, bool enable)

Enable or disable the SD CLK signal.

The function is used by the SDIO/SD/MMC device API functions to enable or disable the SD CLK signal if the SDIO/SD/MMC peripheral driver does not support the Auto CLK feature (periph_sdmmc_auto_clk). It can be left NULL if the SDIO/SD/MMC peripheral driver does not support enabling or disabling the SD CLK signal.

Parameters
[in]devSDIO/SD/MMC device to be used
[in]enableenable SD CLK signal on true or disable the SD CLK signal on false
Return values
0on success
-EIOif the SD CLK signal could not be enabled or disabled

Definition at line 1156 of file sdmmc.h.

◆ init

void(* sdmmc_driver_t::init) (sdmmc_dev_t *dev)

Basic initialization of the given SDIO/SD/MMC device.

Low-level SDIO/SD/MMC peripheral driver function for basic initialization of the peripheral including pin configuration of used pins. It is called by sdmmc_init during the board initialization to prepare the SDIO/SD/MMC peripheral for further usage. Specific initialization parameters required for this initialization are defined in the board's periph_conf.h.

Errors like configuration parameter problems are not signaled by return values, but by using the assert().

See also
sdmmc_init
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to initialize

Definition at line 975 of file sdmmc.h.

◆ send_cmd

int(* sdmmc_driver_t::send_cmd) (sdmmc_dev_t *dev, sdmmc_cmd_t cmd_idx, uint32_t arg, sdmmc_resp_t resp_type, uint32_t *resp)

Send command to SDIO/SD/MMC Card and optionally wait for response.

Low-level SDIO/SD/MMC peripheral driver function to send command cmd_idx with argument arg to the SDIO/SD/MMC card. resp_type specifies the type of the response expected.

Warning
This function must not be used for application specific commands. The high-level SDIO/SD/MMC device API function sdmmc_send_acmd is used instead.

To ensure that the sdmmc_send_acmd function is used for application specific commands, the function must fail if the command cmd_idx is an application specific command (ACMDx). Use

assert((cmd_idx & SDMMC_ACMD_PREFIX) == 0);
#define assert(cond)
abort the program if assertion is false
Definition: assert.h:137
#define SDMMC_ACMD_PREFIX
Application specific command index prefix (Bit is 7 used)
Definition: sdmmc.h:186

in the implementation of this function for that purpose.

The response has to be stored word-wise in host byte order in the buffer provided by resp as follows:

  • resp_type = SDMMC_NO_R (No Response): resp can be NULL
  • resp_tpye = SDMMC_R2 (Long Response): resp = { R[127:96], R[95:64], R[63:32], R[31:0] }
  • resp_type = anything else (Short Response): resp = { R[39:8] }

The buffer provided by resp can be NULL if the response is not needed. However, the low-level SDIO/SD/MMC peripheral driver must receive the expected response, but does not store it in resp in that case.

Note
R3 does not use CRC7 in CRC field but a fixed value of 0b111111. The driver must check the CRC field for this response.
See also
sdmmc_send_cmd and sdmmc_send_acmd
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]cmd_idxCommand index
[in]argCommand argument
[in]resp_typeType of response expected
[out]respBuffer of 32-bit words to store the response if needed, otherwise NULL
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support the command or is in wrong state
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EBADMSGon CRC7 error in response
-EIOon not further specified error incl. hardware errors

Definition at line 1031 of file sdmmc.h.

◆ set_bus_width

int(* sdmmc_driver_t::set_bus_width) (sdmmc_dev_t *dev, sdmmc_bus_width_t width)

Set data bus width.

Set the data bus width used by the SDIO/SD/MMC peripheral. The function is called by the high-level SDIO/SD/MMC device function sdmmc_card_init at the end of the card initialization and identification procedure to change the data bus width used by the SDIO/SD/MMC peripheral. The data bus width of the card has been already changed at that time by sending the ACMD6 (SET_BUS_WIDTH) command.

Supported data bus width depend on

  • the card type,
  • the mode in which the card operates and
  • the SDIO/SD/MMC peripheral.

In identification mode, always 1-bit data bus width is used. When switching from the identification mode to the data transfer mode, the data bus width is changed. In data transfer mode, the data bus width depends on the type of the used card:

  • MMCs V3.x support 4-bit data bus width
  • MMCs V4.x support 8-bit data bus width
  • SD Memory Cards support 4-bit data bus width
  • SDIO Cards support 4-bit data bus width
  • Embedded SDIO devices support 8-bit data bus width

The data bus width width is the minimum of the data bus width supported by the identified card and the data bus width sdmmc_dev_t::bus_width configured for the SDIO/SD/MMC peripheral. The low-level SDIO/SD/MMC peripheral driver is responsible for correctly setting sdmmc_dev_t::bus_width in the sdmmc_driver_t::init function.

Note
The set_bus_width function must not change sdmmc_dev_t::bus_width because it is the configured data bus width which may be larger than the supported data bus width of the identified card.
Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]widthData bus width to be set
Return values
0on success
-ENOTSUPif SDIO/SD/MMC peripheral does not support the width
-EIOon not further specified error incl. hardware errors

Definition at line 1111 of file sdmmc.h.

◆ set_clock_rate

int(* sdmmc_driver_t::set_clock_rate) (sdmmc_dev_t *dev, sdmmc_clock_rate_t rate)

Set SD CLK signal rate.

Set the SD CLK rate used by the SDIO/SD/MMC peripheral. The clock frequency in identification mode f_OD is fixed and is 400 kHz. The actual clock frequency in data transfer mode f_PP depends on the SDIO/SD/MMC device and the card used.

The function is called by the high-level SDIO/SD/MMC device API function sdmmc_card_init at the end of the card identification procedure with rate set to any of the clock rates defined in sdmmc_clock_rate_t. The low-level SDIO/SD/MMC peripheral is responsible to set the clock rate to the highest value it supports for the identified card type.

Precondition
dev must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]rateClock rate to be set
Return values
0on success
-ENOTSUPif SDIO/SD/MMC peripheral does not support the clock rate
-EIOon not further specified error incl. hardware errors

Definition at line 1137 of file sdmmc.h.

◆ xfer_execute

int(* sdmmc_driver_t::xfer_execute) (sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer, const void *data_wr, void *data_rd, uint16_t *done)

Execute the data transfer.

Low-level SDIO/SD/MMC peripheral driver function to transfer the data (read or write) by the SDIO/SD/MMC peripheral.

It is called by the high-level SDIO/SD/MMC device API function sdmmc_xfer after it sent the block-oriented, stream or byte/multi-byte command to start the transfer from or to the card.

The function returns the number of transferred blocks in done. Most SDIO/SD/MMC peripherals use a block or byte counter when transferring data, which can be used for this purpose.

Note
If the SDIO/SD/MMC peripheral does not allow to determine the number of transferred blocks, the function must return 0 in done in case of an error or sdmmc_xfer_desc_t::block_num on success.
See also
sdmmc_xfer
Precondition
dev and xfer must not be NULL.
data_rd must not be NULL for read transfers and
data_wr must not be NULL for write transfers.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]xferTransfer descriptor of type sdmmc_xfer_desc_t
[in]data_wrBuffer with data to write in write transfers, NULL otherwise
[out]data_rdBuffer for data to read in read transfers, NULL otherwise
[out]doneNumber of blocks transferred, can be NULL
Return values
0on success
-ENODEVif card is not present or not usable
-ENOTSUPif card does not support a used command or is in wrong state
-EBUSYif card is busy
-EFAULTon card status error
-ETIMEDOUTon timeout condition
-EINVALon invalid transfer parameters
-EBADMSGon CRC7 error in data
-ENOMEMon RX FIFO overflow or TX FIFO underrun error
-EIOon not further specified error incl. hardware errors

Definition at line 1226 of file sdmmc.h.

◆ xfer_finish

int(* sdmmc_driver_t::xfer_finish) (sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer)

Finish the data transfer.

Low-level SDIO/SD/MMC peripheral driver function to terminate a data transfer (read or write) in the SDIO/SD/MMC peripheral.

It is called by the high-level SDIO/SD/MMC device API function sdmmc_xfer after the data transfer has been executed and the stop command (CMD12) has been sent if necessary.

See also
sdmmc_xfer
Precondition
dev and xfer must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]xferTransfer descriptor of type sdmmc_xfer_desc_t
Return values
0on success
-EIOon not further specified error incl. hardware errors

Definition at line 1249 of file sdmmc.h.

◆ xfer_prepare

int(* sdmmc_driver_t::xfer_prepare) (sdmmc_dev_t *dev, sdmmc_xfer_desc_t *xfer)

Prepare a data transfer.

Low-level SDIO/SD/MMC peripheral driver function to prepare a data transfer (read or write) in the SDIO/SD/MMC peripheral.

It is called by the high-level SDIO/SD/MMC device API function sdmmc_xfer before it sends a block-oriented, stream or byte/multi-byte command to the card to start the transfer from or to the card.

A typical activity of this function is the configuration of the DMA transfer.

See also
sdmmc_xfer
Precondition
dev and xfer must not be NULL.
Parameters
[in]devSDIO/SD/MMC device to be used
[in]xferTransfer descriptor of type sdmmc_xfer_desc_t
Return values
0on success
-EINVALon invalid transfer parameters
-EIOon not further specified error incl. hardware errors

Definition at line 1183 of file sdmmc.h.


The documentation for this struct was generated from the following file: