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. 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.

SD command timeouts

SDHC_TIMEOUT_FOREVER

Defines

SDHC_NATIVE_RESPONSE_MASK
SDHC_SPI_RESPONSE_TYPE_MASK

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

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

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.

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>