# include/sdmmc/sdmmc.h File Reference

SD/MMC driver interface. More...

`#include <types.h>`
`#include <bitops.h>`
`#include <slist.h>`
`#include <buffer.h>`
`#include <chip/portmux.h>`
`#include <dmac/dma_controller.h>`

Include dependency graph for sdmmc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | sdmmc_cid
| SD/MMC Card Identification register fields. More...
struct | sdmmc_csd
| SD/MMC Card-Specific Data register fields. More...
struct | sdmmc_command
| SD/MMC command structure. More...
struct | sdmmc_request
| Asynchronous SD/MMC request. More...
struct | sdmmc_card
| SD/MMC Card structure. More...
struct | sdmmc_slot
| SD/MMC Slot structure. More...
struct | sdmmc_host
| SD/MMC Host structure. More...
## Defines
#define | SDMMC_RSP_PRESENT (1 << 0)
#define | SDMMC_RSP_136 (1 << 1)
#define | SDMMC_RSP_CRC (1 << 2)
#define | SDMMC_RSP_BUSY (1 << 3)
## Enumerations
enum | sdmmc_req_flag { SDMMC_REQ_WRITE, SDMMC_REQ_STOP, SDMMC_REQ_INITSEQ }
| SD/MMC request flags. More...
enum | sdmmc_slot_flags { SDMMC_SLOT_CARD_DETECT, SDMMC_SLOT_CARD_PRESENT, SDMMC_SLOT_HCS, SDMMC_SLOT_HIGH_SPEED, SDMMC_SLOT_PROBING }
| Slot flags. More...
## Functions
static struct sdmmc_slot * | sdmmc_card_get_slot (struct sdmmc_card *card)
| Get the SD/MMC slot into which card is inserted.
void | sdmmc_req_prep_transfer (struct sdmmc_slot *slot, struct sdmmc_request *req, uint32_t lba, uint32_t nr_blocks, bool write)
| Prepare SD/MMC request for data transfer.
static void | sdmmc_req_init (struct sdmmc_request *req)
| Initialize SD/MMC request.
static void | sdmmc_req_prep_cmd (struct sdmmc_request *req, uint32_t opcode, uint32_t arg, unsigned long flags)
| Prepare command part of SD/MMC request.
static void | sdmmc_req_prep_data (struct sdmmc_request *req, struct buffer *buf)
| Prepare data part of SD/MMC request.
static void | sdmmc_req_prep_callback (struct sdmmc_request *req, void(*callback)(struct sdmmc_request *req), void *data)
| Prepare callback part of SD/MMC request.
static void | sdmmc_slot_update (struct sdmmc_slot *slot)
| Update bus parameters of a slot.
void | sdmmc_decode_sd_cid (struct sdmmc_card *card, const be32_t *raw_cid)
| Decode SD card CID (Card Identification).
int | sdmmc_decode_mmc_cid (struct sdmmc_card *card, const be32_t *raw_cid)
| Decode MMC card CID (Card Identification).
int | sdmmc_decode_sd_csd (struct sdmmc_card *card, const be32_t *raw_csd)
| Decode SD card CSD (Card-Specific Data).
int | sdmmc_decode_mmc_csd (struct sdmmc_card *card, const be32_t *raw_csd)
| Decode MMC card CSD (Card-Specific Data).
static void | sdmmc_card_set_type (struct sdmmc_card *card, enum sdmmc_card_type type)
| Set card type.
void | sdmmc_card_update_timeouts (struct sdmmc_card *card, uint32_t mmc_hz)
| Update data timeout calculations.
static uint32_t | sdmmc_card_get_rca (struct sdmmc_card *card)
| Get decoded RCA (Relative Card Address).
static uint32_t | sdmmc_card_block2addr (struct sdmmc_card *card, uint32_t lba)
| Convert block number to address used in communication.
void | sdmmc_slot_submit_req (struct sdmmc_slot *slot, struct sdmmc_request *req)
| Submit SD/MMC request to slot.
static int | sdmmc_req_submit_buf_list (struct sdmmc_host *host, struct sdmmc_request *req, struct slist *buf_list)
| Submit a list of buffers for use with a request.
static bool | sdmmc_slot_is_card_present (struct sdmmc_slot *slot)
| Check if SD/MMC card is present in slot.
static bool | sdmmc_slot_is_card_write_protected (struct sdmmc_slot *slot)
| Check if SD/MMC card in slot is write protected.
void | sdmmc_slot_power_up (struct sdmmc_slot *slot)
| Enable power to a slot.
void | sdmmc_slot_power_down (struct sdmmc_slot *slot)
| Disable power to a slot.
uint32_t | sdmmc_slot_set_voltage (struct sdmmc_slot *slot, uint32_t ocr)
| Set possible supported voltage on slot.
void | sdmmc_slot_set_f_max (struct sdmmc_slot *slot, int32_t f_max)
| Set the maximum MCK rate for a slot.
void | sdmmc_slot_set_bus_width (struct sdmmc_slot *slot, unsigned int bits)
| Set the bus width of a slot.
void | sdmmc_slot_notify_card_detect (struct sdmmc_slot *slot, int value)
| Notify slot about change in hw card detect.
void | sdmmc_slot_init (struct sdmmc_slot *slot, struct sdmmc_host *host, int slot_id)
| Init slot structure.
void | sdmmc_probe_notify_card_detect (void *data)
| Notify probe about card detect change.
void * | sdmmc_probe_init (struct sdmmc_slot *slot, void(*event)(struct sdmmc_slot *slot, void *context), void *context)
| Init slot. Start probing for card.
struct sdmmc_cd * | sdmmc_cd_init (struct sdmmc_slot *slot, gpio_pin_t pin)
| Initialize card detection handler.
void | sdmmc_cd_enable (struct sdmmc_cd *cd)
| Enable card detection handler.
static void | sdmmc_host_enable (struct sdmmc_host *host)
| Enable host.

## Detailed Description

SD/MMC driver interface.

This is the interface to a SD/MMC driver.

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All devices
- AppNote:

Author:
  Atmel Corporation: http://www.atmel.com
  Support and FAQ: http://support.atmel.no/

Definition in file sdmmc.h.

## Define Documentation

#define SDMMC_RSP_136 (1 << 1)

136-bit response

Definition at line 94 of file sdmmc.h.

#define SDMMC_RSP_BUSY (1 << 3)

card may send busy

Definition at line 96 of file sdmmc.h.

#define SDMMC_RSP_CRC (1 << 2)

expect valid crc

Definition at line 95 of file sdmmc.h.

#define SDMMC_RSP_PRESENT (1 << 0)

expect a response

Definition at line 93 of file sdmmc.h.

## Enumeration Type Documentation

enum sdmmc_req_flag

SD/MMC request flags.

Enumerator:

  SDMMC_REQ_WRITE | Set means write, and unset means read
  SDMMC_REQ_STOP | Send STOP CMD after data
  SDMMC_REQ_INITSEQ | Request is special init sequence

Definition at line 119 of file sdmmc.h.

enum sdmmc_slot_flags

Slot flags.

Enumerator:

  SDMMC_SLOT_CARD_DETECT | Indicates hw card detect
  SDMMC_SLOT_CARD_PRESENT | Indicates card probed ok
  SDMMC_SLOT_HCS | Host Capacity Support. Means host support SDHC
  SDMMC_SLOT_HIGH_SPEED | High Speed enable
  SDMMC_SLOT_PROBING | Slot is in probing state

Definition at line 199 of file sdmmc.h.

## Function Documentation

static uint32_t sdmmc_card_block2addr | ( | struct sdmmc_card * | card,
|  | uint32_t | lba |
| ) |  |  | `[inline, static]`

Convert block number to address used in communication.

Parameters:

  | card | Card in question
  | lba | Block address

Returns:
  Address to be used in data read/write

Definition at line 458 of file sdmmc.h.

References sdmmc_card::block_size, and sdmmc_card::type.

Referenced by sdmmc_req_prep_transfer().

static uint32_t sdmmc_card_get_rca | ( | struct sdmmc_card * | card | ) | `[inline, static]`

Get decoded RCA (Relative Card Address).

Parameters:

  | card | Card in question

Returns:
  Decoded RCA

Definition at line 445 of file sdmmc.h.

References sdmmc_card::rca.

static struct sdmmc_slot* sdmmc_card_get_slot | ( | struct sdmmc_card * | card | ) | `[static, read]`

Get the SD/MMC slot into which card is inserted.

Definition at line 282 of file sdmmc.h.

References container_of.

Referenced by sdmmc_card_set_type(), sdmmc_decode_mmc_csd(), and sdmmc_decode_sd_csd().

static void sdmmc_card_set_type | ( | struct sdmmc_card * | card,
|  | enum sdmmc_card_type | type |
| ) |  |  | `[inline, static]`

Set card type.

Parameters:

  | card | Card to set the type on
  | type | Card type

Definition at line 422 of file sdmmc.h.

References sdmmc_card_get_slot(), sdmmc_slot_update(), and sdmmc_card::type.

Here is the call graph for this function:

void sdmmc_card_update_timeouts | ( | struct sdmmc_card * | card,
|  | uint32_t | mmc_hz |
| ) |  |  |

Update data timeout calculations.

Parameters:

  | card | Card to calculate timeout for
  | mmc_hz | The current frequence running on the slot

Definition at line 396 of file card.c.

void sdmmc_cd_enable | ( | struct sdmmc_cd * | cd | ) |

Enable card detection handler.

Parameters:

  | cd | Private data for card detction handler

Definition at line 118 of file card_detect.c.

References delayed_work_run_us(), and SDMMC_CD_DELAY_US.

Here is the call graph for this function:

struct sdmmc_cd* sdmmc_cd_init | ( | struct sdmmc_slot * | slot,
|  | gpio_pin_t | pin |
| ) |  |  | `[read]`

Initialize card detection handler.

Parameters:

  | slot | sdmmc_slot
  | pin | gpio pin to use as card detect input

Definition at line 97 of file card_detect.c.

References dbg_error, delayed_work_init(), gpio_init_irq_handler(), gpio_register_irq_handler(), and workqueue_init_item().

Referenced by sdmmc_mcihost_init().

Here is the call graph for this function:

int sdmmc_decode_mmc_cid | ( | struct sdmmc_card * | card,
|  | const be32_t * | raw_cid |
| ) |  |  |

Decode MMC card CID (Card Identification).

Parameters:

  | card | Card structure to fill data into
  | resp | Response from command requesting CID

Return values:

  | 0 | Success
  | <0 | decode failure

Definition at line 127 of file card.c.

References sdmmc_cid::application_id, sdmmc_cid::checksum, sdmmc_card::cid, sdmmc_card::csd, dbg_printf, extract_bitfield(), sdmmc_cid::manu_month, sdmmc_cid::manu_year, sdmmc_cid::manufacturer_id, sdmmc_csd::mmc_version, sdmmc_cid::name, sdmmc_cid::revision, and sdmmc_cid::serial.

Here is the call graph for this function:

int sdmmc_decode_mmc_csd | ( | struct sdmmc_card * | card,
|  | const be32_t * | raw_csd |
| ) |  |  |

Decode MMC card CSD (Card-Specific Data).

Parameters:

  | card | Card structure to fill data into
  | raw_csd | Response from command requesting CSD

Return values:

  | 0 | Success
  | <0 | decode failure

Definition at line 296 of file card.c.

References sdmmc_csd::can_read_misaligned, sdmmc_csd::can_read_partial, sdmmc_csd::can_write_misaligned, sdmmc_csd::can_write_partial, sdmmc_csd::capacity, sdmmc_csd::command_classes, sdmmc_card::csd, dbg_printf, extract_bitfield(), sdmmc_csd::max_transfer_rate, sdmmc_csd::mmc_version, sdmmc_csd::read_access_time_clks, sdmmc_csd::read_access_time_ns, sdmmc_csd::read_block_length, sdmmc_card_get_slot(), sdmmc_slot_update(), sdmmc_csd::write_block_length, and sdmmc_csd::write_speed_factor.

Here is the call graph for this function:

void sdmmc_decode_sd_cid | ( | struct sdmmc_card * | card,
|  | const be32_t * | raw_cid |
| ) |  |  |

Decode SD card CID (Card Identification).

Parameters:

  | card | Card structure to fill data into
  | resp | Response from command requesting CID

Definition at line 101 of file card.c.

References sdmmc_cid::application_id, sdmmc_cid::checksum, sdmmc_card::cid, extract_bitfield(), sdmmc_cid::manu_month, sdmmc_cid::manu_year, sdmmc_cid::manufacturer_id, sdmmc_cid::name, sdmmc_cid::revision, and sdmmc_cid::serial.

Here is the call graph for this function:

int sdmmc_decode_sd_csd | ( | struct sdmmc_card * | card,
|  | const be32_t * | raw_csd |
| ) |  |  |

Decode SD card CSD (Card-Specific Data).

Parameters:

  | card | Card structure to fill data into
  | raw_csd | Response from command requesting CSD

Return values:

  | 0 | Success
  | <0 | decode failure

Definition at line 207 of file card.c.

References sdmmc_csd::can_read_misaligned, sdmmc_csd::can_read_partial, sdmmc_csd::can_write_misaligned, sdmmc_csd::can_write_partial, sdmmc_csd::capacity, sdmmc_csd::command_classes, sdmmc_card::csd, dbg_printf, extract_bitfield(), sdmmc_csd::max_transfer_rate, sdmmc_csd::read_access_time_clks, sdmmc_csd::read_access_time_ns, sdmmc_csd::read_block_length, sdmmc_card_get_slot(), sdmmc_slot_update(), sdmmc_csd::write_block_length, and sdmmc_csd::write_speed_factor.

Here is the call graph for this function:

static void sdmmc_host_enable | ( | struct sdmmc_host * | host | ) | `[inline, static]`

Enable host.

Parameters:

  | host | Host structure

Definition at line 640 of file sdmmc.h.

References assert, and sdmmc_host::enable.

void* sdmmc_probe_init | ( | struct sdmmc_slot * | slot,
|  | void(*)(struct sdmmc_slot *slot, void *context) | event,
|  | void * | context |
| ) |  |  |

Init slot. Start probing for card.

Parameters:

  | slot | sdmmc_slot
  | event | Callback for card detection
  | context | Private data for event callback

Returns:
  pointer to private probe data on success and 0 on failure

Definition at line 538 of file probe.c.

References sdmmc_slot::context, delayed_work_init(), memset(), sdmmc_slot::notify_card_detect, sdmmc_probe_notify_card_detect(), and workqueue_init_item().

Referenced by sdmmc_blkdev_init_new().

Here is the call graph for this function:

void sdmmc_probe_notify_card_detect | ( | void * | data | ) |

Notify probe about card detect change.

Parameters:

  | data | Pointer to private data for probe

Definition at line 528 of file probe.c.

References workqueue_add_item().

Referenced by sdmmc_probe_init().

Here is the call graph for this function:

static void sdmmc_req_init | ( | struct sdmmc_request * | req | ) | `[inline, static]`

Initialize SD/MMC request.

Parameters:

  | req | Request

Definition at line 305 of file sdmmc.h.

References sdmmc_request::block_size, sdmmc_request::blocks, sdmmc_request::buf_list, sdmmc_request::flags, and slist_init().

Here is the call graph for this function:

static void sdmmc_req_prep_callback | ( | struct sdmmc_request * | req,
|  | void(*)(struct sdmmc_request *req) | callback,
|  | void * | data |
| ) |  |  | `[inline, static]`

Prepare callback part of SD/MMC request.

Parameters:

  | req | Request
  | callback | Callback when request is done
  | data | Private data for callback

Definition at line 350 of file sdmmc.h.

References sdmmc_request::context, and sdmmc_request::req_done.

static void sdmmc_req_prep_cmd | ( | struct sdmmc_request * | req,
|  | uint32_t | opcode,
|  | uint32_t | arg,
|  | unsigned long | flags |
| ) |  |  | `[inline, static]`

Prepare command part of SD/MMC request.

Parameters:

  | req | Request
  | opcode | Command index
  | arg | Argument
  | flags | Flags

Definition at line 321 of file sdmmc.h.

References sdmmc_command::arg, sdmmc_request::cmd, sdmmc_command::flags, and sdmmc_command::opcode.

Referenced by sdmmc_req_prep_transfer().

static void sdmmc_req_prep_data | ( | struct sdmmc_request * | req,
|  | struct buffer * | buf |
| ) |  |  | `[inline, static]`

Prepare data part of SD/MMC request.

Parameters:

  | req | Request
  | buf | Data buffer

Definition at line 335 of file sdmmc.h.

References sdmmc_request::block_size, sdmmc_request::blocks, sdmmc_request::buf_list, buffer::len, buffer::node, and slist_insert_tail().

Here is the call graph for this function:

void sdmmc_req_prep_transfer | ( | struct sdmmc_slot * | slot,
|  | struct sdmmc_request * | req,
|  | uint32_t | lba,
|  | uint32_t | nr_blocks,
|  | bool | write |
| ) |  |  |

Prepare SD/MMC request for data transfer.

Parameters:

  | slot | Slot this request is intended for
  | req | Request
  | lba | Logical Block Address
  | nr_blocks | Number of block to transfer
  | write | Set to true for write request and to false for read request

Definition at line 51 of file request.c.

References sdmmc_card::block_size, sdmmc_request::block_size, sdmmc_request::blocks, sdmmc_slot::card, sdmmc_request::flags, sdmmc_card_block2addr(), sdmmc_req_prep_cmd(), SDMMC_REQ_STOP, SDMMC_REQ_WRITE, and set_bit().

Here is the call graph for this function:

static int sdmmc_req_submit_buf_list | ( | struct sdmmc_host * | host,
|  | struct sdmmc_request * | req,
|  | struct slist * | buf_list |
| ) |  |  | `[inline, static]`

Submit a list of buffers for use with a request.

If successful, the host driver takes ownership of the buffers until they are handed back through sdmmc_request::buf_list_done().

Parameters:

  | host | The MMC host handling the request
  | req | The MMC request to receive the buffers
  | buf_list | A list of buffers

Return values:

  | STATUS_OK | The buffers were submitted successfully
  | -STATUS_FLUSHED | The request was terminated before the buffers could be submitted.

Definition at line 490 of file sdmmc.h.

References assert, and sdmmc_host::submit_buf_list.

void sdmmc_slot_init | ( | struct sdmmc_slot * | slot,
|  | struct sdmmc_host * | host,
|  | int | slot_id |
| ) |  |  |

Init slot structure.

Parameters:

  | slot | sdmmc_slot to be initialized
  | host | pointer to sdmmc_host structure
  | slot_id | slot identificator

Definition at line 139 of file slot.c.

References sdmmc_slot::f_max, sdmmc_slot::flags, sdmmc_slot::host, sdmmc_slot::id, and sdmmc_slot::notify_card_detect.

Referenced by sdmmc_mcihost_init().

static bool sdmmc_slot_is_card_present | ( | struct sdmmc_slot * | slot | ) | `[inline, static]`

Check if SD/MMC card is present in slot.

Parameters:

  | slot | Slot to check

Return values:

  | true | Card is present
  | false | Card is not present

Definition at line 506 of file sdmmc.h.

References sdmmc_slot::flags, SDMMC_SLOT_CARD_PRESENT, and test_bit().

Here is the call graph for this function:

static bool sdmmc_slot_is_card_write_protected | ( | struct sdmmc_slot * | slot | ) | `[inline, static]`

Check if SD/MMC card in slot is write protected.

If the card is not present, the result is undefined.

Parameters:

  | slot | Slot to check

Return values:

  | true | Card is write-protected
  | false | Card is not write-protected

Definition at line 521 of file sdmmc.h.

References sdmmc_slot::host, and sdmmc_host::wp_is_active.

void sdmmc_slot_notify_card_detect | ( | struct sdmmc_slot * | slot,
|  | int | value |
| ) |  |  |

Notify slot about change in hw card detect.

Can be called to notify about change in card detection. Ususally called by card detect handler.

Parameters:

  | slot | sdmmc_slot
  | value | Zero for no detection and non-zero for detection

Definition at line 128 of file slot.c.

References clear_bit(), sdmmc_slot::context, sdmmc_slot::flags, sdmmc_slot::notify_card_detect, SDMMC_SLOT_CARD_DETECT, and set_bit().

Here is the call graph for this function:

void sdmmc_slot_power_down | ( | struct sdmmc_slot * | slot | ) |

Disable power to a slot.

When this function returns, any card inserted into slot will not be powered, if power switching is supported on the current board/host combination. This function also sets the clock rate to "don't care" so that any other slots sharing the same clock line may be able to run faster.

Definition at line 104 of file slot.c.

References sdmmc_slot::host, sdmmc_host::power_down, and sdmmc_slot_set_f_max().

Here is the call graph for this function:

void sdmmc_slot_power_up | ( | struct sdmmc_slot * | slot | ) |

Enable power to a slot.

When this function returns, any card inserted into slot will be powered. This function also resets the bus width to 1 bit and clears any high-speed state bits.

Definition at line 96 of file slot.c.

References sdmmc_slot::bus_width, clear_bit(), sdmmc_slot::flags, sdmmc_slot::host, sdmmc_host::power_up, SDMMC_SLOT_HIGH_SPEED, and sdmmc_slot_set_f_max().

Here is the call graph for this function:

void sdmmc_slot_set_bus_width | ( | struct sdmmc_slot * | slot,
|  | unsigned int | bits |
| ) |  |  |

Set the bus width of a slot.

Parameters:

  | slot | A MMC/SD card slot
  | bits | The new bus width in bits

Definition at line 122 of file slot.c.

References sdmmc_slot::bus_width, and sdmmc_slot_update().

Here is the call graph for this function:

void sdmmc_slot_set_f_max | ( | struct sdmmc_slot * | slot,
|  | int32_t | f_max |
| ) |  |  |

Set the maximum MCK rate for a slot.

The bus frequency of the MCK line will be set to f_max Hz, rounded down to the nearest supported value, or up to the lowest rate supported by the host.

Parameters:

  | slot | A MMC/SD card slot
  | f_max | The maximum MCK rate in Hz. A negative value means "don't care" (i.e. the slot is inactive). Zero means that the clock should stop completely.

Definition at line 111 of file slot.c.

References sdmmc_slot::f_max, sdmmc_host::f_min, sdmmc_slot::host, and sdmmc_slot_update().

Referenced by sdmmc_slot_power_down(), and sdmmc_slot_power_up().

Here is the call graph for this function:

uint32_t sdmmc_slot_set_voltage | ( | struct sdmmc_slot * | slot,
|  | uint32_t | ocr |
| ) |  |  |

Set possible supported voltage on slot.

Parameters:

  | slot | Slot
  | ocr | Card Operation Condition Register

Returns:
  Possible Operation Condition Register

Definition at line 59 of file slot.c.

References dbg_verbose, ffs(), sdmmc_slot::host, sdmmc_host::ocr_avail, SDMMC_OCR_LOW_VOLTAGE, and sdmmc_host::set_voltage.

Here is the call graph for this function:

void sdmmc_slot_submit_req | ( | struct sdmmc_slot * | slot,
|  | struct sdmmc_request * | req |
| ) |  |  |

Submit SD/MMC request to slot.

Parameters:

  | slot | Slot to submit request to
  | req | Request to submit

Definition at line 53 of file slot.c.

References sdmmc_slot::host, sdmmc_request::slot, and sdmmc_host::submit_req.

static void sdmmc_slot_update | ( | struct sdmmc_slot * | slot | ) | `[inline, static]`

Update bus parameters of a slot.

Calling this function will trigger a recalculation of the data read and write timeout values, and will also cause the host to be updated according to the bus width, high-speed settings and maximum bus rate.

Parameters:

  | slot | A MMC/SD card slot

Definition at line 367 of file sdmmc.h.

References sdmmc_slot::host, and sdmmc_host::set_bus_params.

Referenced by sdmmc_card_set_type(), sdmmc_decode_mmc_csd(), sdmmc_decode_sd_csd(), sdmmc_slot_set_bus_width(), and sdmmc_slot_set_f_max().