The latest development version of this page may be more current than this released 3.7.0 version.

Secure Digital High Capacity (SDHC)

The SDHC api offers a generic interface for interacting with an SD host controller device. It is used by the SD subsystem, and is not intended to be directly used by the application

Basic Operation

SD Host Controller

An SD host controller is a device capable of sending SD commands to an attached SD card. These commands can be sent using the native SD protocol, or over SPI. Some SD host controllers are also capable of communicating with MMC devices. The SDHC api is designed to provide a generic way to send commands to and interact with attached SD devices.

Requests

The core of the SDHC api is the sdhc_request() api. Requests contain a sdhc_command command structure, and an optional sdhc_data data structure. The caller may check the return code, or the response field of the SD command structure to determine if the SDHC request succeeded. The data structure allows the caller to specify a number of blocks to transfer, and a buffer location to read or write them from. Whether the provided buffer is used for sending or reading data depends on the command opcode provided.

Host Controller I/O

The sdhc_set_io() api allows the user to change I/O settings of the SD host controller, such as clock frequency, I/O voltage, and card power. Not all controllers will support applying all I/O settings. For example, SPI mode controllers typically cannot toggle power to the SD card.

Related configuration options:

API Reference

group sdhc_interface

SDHC interface.

Since

3.1

Version

0.1.0

SD command timeouts

SDHC_TIMEOUT_FOREVER

Defines

SDHC_NATIVE_RESPONSE_MASK
SDHC_SPI_RESPONSE_TYPE_MASK

Typedefs

typedef void (*sdhc_interrupt_cb_t)(const struct device *dev, int reason, const void *user_data)

SDHC card interrupt callback prototype.

Function prototype for SDHC card interrupt callback.

Param dev:

SDHC device that produced interrupt

Param reason:

one of sdhc_interrupt_source values.

Param user_data:

User data, set via sdhc_enable_interrupt

Enums

enum sdhc_bus_mode

SD bus mode.

Most controllers will use push/pull, including spi, but SDHC controllers that implement SD host specification can support open drain mode

Values:

enumerator SDHC_BUSMODE_OPENDRAIN = 1
enumerator SDHC_BUSMODE_PUSHPULL = 2
enum sdhc_power

SD host controller power.

Many host controllers can control power to attached SD cards. This enum allows applications to request the host controller power off the SD card.

Values:

enumerator SDHC_POWER_OFF = 1
enumerator SDHC_POWER_ON = 2
enum sdhc_bus_width

SD host controller bus width.

Only relevant in SD mode, SPI does not support bus width. UHS cards will use 4 bit data bus, all cards start in 1 bit mode

Values:

enumerator SDHC_BUS_WIDTH1BIT = 1U
enumerator SDHC_BUS_WIDTH4BIT = 4U
enumerator SDHC_BUS_WIDTH8BIT = 8U
enum sdhc_timing_mode

SD host controller timing mode.

Used by SD host controller to determine the timing of the cards attached to the bus. Cards start with legacy timing, but UHS-II cards can go up to SDR104.

Values:

enumerator SDHC_TIMING_LEGACY = 1U

Legacy 3.3V Mode.

enumerator SDHC_TIMING_HS = 2U

Legacy High speed mode (3.3V)

enumerator SDHC_TIMING_SDR12 = 3U

Identification mode & SDR12.

enumerator SDHC_TIMING_SDR25 = 4U

High speed mode & SDR25.

enumerator SDHC_TIMING_SDR50 = 5U

SDR49 mode.

enumerator SDHC_TIMING_SDR104 = 6U

SDR104 mode.

enumerator SDHC_TIMING_DDR50 = 7U

DDR50 mode.

enumerator SDHC_TIMING_DDR52 = 8U

DDR52 mode.

enumerator SDHC_TIMING_HS200 = 9U

HS200 mode.

enumerator SDHC_TIMING_HS400 = 10U

HS400 mode.

enum sd_voltage

SD voltage.

UHS cards can run with 1.8V signalling for improved power consumption. Legacy cards may support 3.0V signalling, and all cards start at 3.3V. Only relevant for SD controllers, not SPI ones.

Values:

enumerator SD_VOL_3_3_V = 1U

card operation voltage around 3.3v

enumerator SD_VOL_3_0_V = 2U

card operation voltage around 3.0v

enumerator SD_VOL_1_8_V = 3U

card operation voltage around 1.8v

enumerator SD_VOL_1_2_V = 4U

card operation voltage around 1.2v

enum sdhc_interrupt_source

SD host controller interrupt sources.

Interrupt sources for SD host controller.

Values:

enumerator SDHC_INT_SDIO = BIT(0)

Card interrupt, used by SDIO cards.

enumerator SDHC_INT_INSERTED = BIT(1)

Card was inserted into slot.

enumerator SDHC_INT_REMOVED = BIT(2)

Card was removed from slot.

Functions

int sdhc_hw_reset(const struct device *dev)

reset SDHC controller state

Used when the SDHC has encountered an error. Resetting the SDHC controller should clear all errors on the SDHC, but does not necessarily reset I/O settings to boot (this can be done with sdhc_set_io)

Parameters:

  • dev – SD host controller device

Return values:

  • 0 – reset succeeded

  • -ETIMEDOUT – controller reset timed out

  • -EIO – reset failed

int sdhc_request(const struct device *dev, struct sdhc_command *cmd, struct sdhc_data *data)

Send command to SDHC.

Sends a command to the SD host controller, which will send this command to attached SD cards.

Parameters:

  • dev – SDHC device

  • cmd – SDHC command

  • data – SDHC data. Leave NULL to send SD command without data.

Return values:

  • 0 – command was sent successfully

  • -ETIMEDOUT – command timed out while sending

  • -ENOTSUP – host controller does not support command

  • -EIO – I/O error

int sdhc_set_io(const struct device *dev, struct sdhc_io *io)

set I/O properties of SDHC

I/O properties should be reconfigured when the card has been sent a command to change its own SD settings. This function can also be used to toggle power to the SD card.

Parameters:

  • dev – SDHC device

  • io – I/O properties

Returns:

0 I/O was configured correctly

Returns:

-ENOTSUP controller does not support these I/O settings

Returns:

-EIO controller could not configure I/O settings

int sdhc_card_present(const struct device *dev)

check for SDHC card presence

Checks if card is present on the SD bus. Note that if a controller requires cards be powered up to detect presence, it should do so in this function.

Parameters:

  • dev – SDHC device

Return values:

  • 1 – card is present

  • 0 – card is not present

  • -EIO – I/O error

int sdhc_execute_tuning(const struct device *dev)

run SDHC tuning

SD cards require signal tuning for UHS modes SDR104 and SDR50. This function allows an application to request the SD host controller to tune the card.

Parameters:

  • dev – SDHC device

Return values:

  • 0 – tuning succeeded, card is ready for commands

  • -ETIMEDOUT – tuning failed after timeout

  • -ENOTSUP – controller does not support tuning

  • -EIO – I/O error while tuning

int sdhc_card_busy(const struct device *dev)

check if SD card is busy

This check should generally be implemented as checking the line level of the DAT[0:3] lines of the SD bus. No SD commands need to be sent, the controller simply needs to report the status of the SD bus.

Parameters:

  • dev – SDHC device

Return values:

  • 0 – card is not busy

  • 1 – card is busy

  • -EIO – I/O error

int sdhc_get_host_props(const struct device *dev, struct sdhc_host_props *props)

Get SD host controller properties.

Gets host properties from the host controller. Host controller should initialize all values in the sdhc_host_props structure provided.

Parameters:

  • dev – SDHC device

  • props – property structure to be filled by sdhc driver

Return values:

  • 0 – function succeeded.

  • -ENOTSUP – host controller does not support this call

int sdhc_enable_interrupt(const struct device *dev, sdhc_interrupt_cb_t callback, int sources, void *user_data)

Enable SDHC interrupt sources.

Enables SDHC interrupt sources. Each subsequent call of this function should replace the previous callback set, and leave only the interrupts specified in the “sources” argument enabled.

Parameters:

  • dev – SDHC device

  • callback – Callback called when interrupt occurs

  • sources – bitmask of sdhc_interrupt_source values indicating which interrupts should produce a callback

  • user_data – parameter that will be passed to callback function

Return values:

  • 0 – interrupts were enabled, and callback was installed

  • -ENOTSUP – controller does not support this function

  • -EIO – I/O error

int sdhc_disable_interrupt(const struct device *dev, int sources)

Disable SDHC interrupt sources.

Disables SDHC interrupt sources. If multiple sources are enabled, only the ones specified in “sources” will be masked.

Parameters:

  • dev – SDHC device

  • sources – bitmask of sdhc_interrupt_source values indicating which interrupts should be disabled.

Return values:

  • 0 – interrupts were disabled

  • -ENOTSUP – controller does not support this function

  • -EIO – I/O error

struct sdhc_command
#include <sdhc.h>

SD host controller command structure.

This command structure is used to send command requests to an SD host controller, which will be sent to SD devices.

Public Members

uint32_t opcode

SD Host specification CMD index.

uint32_t arg

SD host specification argument.

uint32_t response[4]

SD card response field.

uint32_t response_type

Expected SD response type.

unsigned int retries

Max number of retries.

int timeout_ms

Command timeout in milliseconds.

struct sdhc_data
#include <sdhc.h>

SD host controller data structure.

This command structure is used to send data transfer requests to an SD host controller, which will be sent to SD devices.

Public Members

unsigned int block_addr

Block to start read from.

unsigned int block_size

Block size.

unsigned int blocks

Number of blocks.

unsigned int bytes_xfered

populated with number of bytes sent by SDHC

void *data

Data to transfer or receive.

int timeout_ms

data timeout in milliseconds

struct sdhc_host_caps
#include <sdhc.h>

SD host controller capabilities.

SD host controller capability flags. These flags should be set by the SDHC driver, using the sdhc_get_host_props api.

Public Members

unsigned int timeout_clk_freq

Timeout clock frequency.

unsigned int timeout_clk_unit

Timeout clock unit.

unsigned int sd_base_clk

SD base clock frequency.

unsigned int max_blk_len

Max block length.

unsigned int bus_8_bit_support

8-bit Support for embedded device

unsigned int bus_4_bit_support

4 bit bus support

unsigned int adma_2_support

ADMA2 support.

unsigned int high_spd_support

High speed support.

unsigned int sdma_support

SDMA support.

unsigned int suspend_res_support

Suspend/Resume support.

unsigned int vol_330_support

Voltage support 3.3V.

unsigned int vol_300_support

Voltage support 3.0V.

unsigned int vol_180_support

Voltage support 1.8V.

unsigned int address_64_bit_support_v4

64-bit system address support for V4

unsigned int address_64_bit_support_v3

64-bit system address support for V3

unsigned int sdio_async_interrupt_support

Asynchronous interrupt support.

unsigned int slot_type

Slot type.

unsigned int sdr50_support

SDR50 support.

unsigned int sdr104_support

SDR104 support.

unsigned int ddr50_support

DDR50 support.

unsigned int uhs_2_support

UHS-II support.

unsigned int drv_type_a_support

Driver type A support.

unsigned int drv_type_c_support

Driver type C support.

unsigned int drv_type_d_support

Driver type D support.

unsigned int retune_timer_count

Timer count for re-tuning.

unsigned int sdr50_needs_tuning

Use tuning for SDR50.

unsigned int retuning_mode

Re-tuning mode.

unsigned int clk_multiplier

Clock multiplier.

unsigned int adma3_support

ADMA3 support.

unsigned int vdd2_180_support

1.8V VDD2 support

unsigned int hs200_support

HS200 support.

unsigned int hs400_support

HS400 support.

struct sdhc_io
#include <sdhc.h>

SD host controller I/O control structure.

Controls I/O settings for the SDHC. Note that only a subset of these settings apply to host controllers in SPI mode. Populate this struct, then call sdhc_set_io to apply I/O settings

Public Members

enum sdhc_clock_speed clock

Clock rate.

enum sdhc_bus_mode bus_mode

command output mode

enum sdhc_power power_mode

SD power supply mode.

enum sdhc_bus_width bus_width

SD bus width.

enum sdhc_timing_mode timing

SD bus timing.

enum sd_driver_type driver_type

SD driver type.

enum sd_voltage signal_voltage

IO signalling voltage (usually 1.8 or 3.3V)

struct sdhc_host_props
#include <sdhc.h>

SD host controller properties.

Populated by the host controller using sdhc_get_host_props api.

Public Members

unsigned int f_max

Max bus frequency.

unsigned int f_min

Min bus frequency.

unsigned int power_delay

Delay to allow SD to power up or down (in ms)

struct sdhc_host_caps host_caps

Host capability bitfield.

uint32_t max_current_330

Max current (in mA) at 3.3V.

uint32_t max_current_300

Max current (in mA) at 3.0V.

uint32_t max_current_180

Max current (in mA) at 1.8V.

bool is_spi

Is the host using SPI mode.

struct sdhc_driver_api
#include <sdhc.h>