SDHC (SD Host Controller)

General Description

High level interface to the Secure Digital Host Controller (SDHC).

The SDHC driver allows data to be read from and written to an SD Card using the SDHC block. The data is transferred in blocks with a block size of 512 bytes.

Features

• Supports the 4-bit interface
• Supports Ultra High Speed (UHS-I) mode
• Supports Default Speed (DS), High Speed (HS), SDR12, SDR25 and SDR50 speed modes

Quick Start

Initialize SDHC by using cyhal_sdhc_init by selecting the pins according to the target device used. Specify the SDHC configuration using the configuration structure (const cyhal_sdhc_config_t * config).
See Snippet 1: SDHC Initialization and configuration

Code Snippets

Snippet 1: SDHC Initialization and configuration

The following snippet is used to initialize the SDHC block. SDHC object - cyhal_sdhc_t, SDHC card configuration structure (const cyhal_sdhc_config_t * config). The pins connected to the SDHC block needs to be provided to the cyhal_sdhc_init function.

 
    #define ENABLE_LED_CONTROL      false
    #define LOW_VOLTAGE_SIGNALLING  false
    #define IS_EMMC                 false
    #define BUS_WIDTH               4
 
    cy_rslt_t rslt;
 
    cyhal_sdhc_t sdhc_obj;
 
    const cyhal_sdhc_config_t sdhc_config = { ENABLE_LED_CONTROL,
                                              LOW_VOLTAGE_SIGNALLING,
                                              IS_EMMC, BUS_WIDTH };
 
    rslt = cyhal_sdhc_init(&sdhc_obj, &sdhc_config, CMD, CLK,
                           DAT0, DAT1, DAT2, DAT3, DAT4, DAT5, DAT6, DAT7,
                           CARD_DETECT, IO_VOLT_SEL, CARD_IF_PWREN,
                           CARD_MECH_WRITEPROT, LED_CTL, EMMC_RESET, NULL);
 

Snippet 2: Reading a block of data from an SD Card

The following snippet reads a block of data from the SD Card.

    #define DEFAULT_BLOCKSIZE 512
 
    // Data buffer to store the data read from the SD Card
    uint8_t read_buff[DEFAULT_BLOCKSIZE] = { 0 };
 
    // Starting block address from which the data needs to be read
    uint32_t block_address = 0;
 
    // Number of blocks that needs to be read
    size_t block_count = 1;
 
    rslt = cyhal_sdhc_read(&sdhc_obj, block_address, read_buff, &block_count);
 

Snippet 3: Writing a block of data to an SD Card

The following snippet writes a block of data to the SD Card.

    #define DEFAULT_BLOCKSIZE 512
 
    // Number of bytes of data to be written into the SD Card
    #define  DATA_BYTE_COUNT (2 * DEFAULT_BLOCKSIZE)
 
    // Data buffer that stores the data to be written into the SD Card
    uint8_t write_buff[DATA_BYTE_COUNT];
 
    // Starting block address into which the data is to be written
    uint32_t block_address = 0;
 
    // Number of blocks that needs to be written
    size_t block_count = 2;
 
    // Generate sample data
    for (int i = 0; i < DATA_BYTE_COUNT; i++)
    {
        write_buff[i] = i;
    }
 
    rslt = cyhal_sdhc_write(&sdhc_obj, block_address, write_buff, &block_count);
 

API Reference
	SDHC HAL Results
	SDHC specific return codes.

Data Structures
struct	cyhal_sdhc_config_t
	Defines configuration options for the SDHC block. More...
struct	cyhal_sdhc_data_config_t
	Defines data configuration. More...
struct	cyhal_sdhc_cmd_config_t
	Defines command configuration for cyhal_sdhc_send_cmd function. More...

Typedefs
typedef void(*	cyhal_sdhc_event_callback_t) (void *callback_arg, cyhal_sdhc_event_t event)
	Handler for SDHC interrupts.

Enumerations
enum	cyhal_sdhc_card_type_t {   CYHAL_SDHC_SD ,   CYHAL_SDHC_SDIO ,   CYHAL_SDHC_EMMC ,   CYHAL_SDHC_COMBO ,   CYHAL_SDHC_UNUSABLE ,   CYHAL_SDHC_NOT_EMMC }
	Card types. More...
enum	cyhal_sdhc_event_t {   CYHAL_SDHC_CMD_COMPLETE = 0x00001 ,   CYHAL_SDHC_XFER_COMPLETE = 0x00002 ,   CYHAL_SDHC_BGAP_EVENT = 0x00004 ,   CYHAL_SDHC_DMA_INTERRUPT = 0x00008 ,   CYHAL_SDHC_BUF_WR_READY = 0x00010 ,   CYHAL_SDHC_BUF_RD_READY = 0x00020 ,   CYHAL_SDHC_CARD_INSERTION = 0x00040 ,   CYHAL_SDHC_CARD_REMOVAL = 0x00080 ,   CYHAL_SDHC_INT_A = 0x00200 ,   CYHAL_SDHC_INT_B = 0x00400 ,   CYHAL_SDHC_INT_C = 0x00800 ,   CYHAL_SDHC_RE_TUNE_EVENT = 0x01000 ,   CYHAL_SDHC_FX_EVENT = 0x02000 ,   CYHAL_SDHC_CQE_EVENT = 0x04000 ,   CYHAL_SDHC_ERR_INTERRUPT = 0x08000 ,   CYHAL_SDHC_ALL_INTERRUPTS = 0x0FEFF }
	SDHC interrupt triggers. More...
enum	cyhal_sdhc_io_voltage_t {   CYHAL_SDHC_IO_VOLTAGE_3_3V = 0U ,   CYHAL_SDHC_IO_VOLTAGE_1_8V = 1U }
	I/O voltage levels. More...
enum	cyhal_sdhc_io_volt_action_type_t {   CYHAL_SDHC_IO_VOLT_ACTION_NEGOTIATE = 0U ,   CYHAL_SDHC_IO_VOLT_ACTION_SWITCH_SEQ_ONLY = 1U ,   CYHAL_SDHC_IO_VOLT_ACTION_NONE = 2U }
	SDHC I/O voltage select principle. More...
enum	cyhal_sdhc_cmd_response_type_t {   CYHAL_SDHC_RESPONSE_NONE = 0U ,   CYHAL_SDHC_RESPONSE_LEN_136 = 1U ,   CYHAL_SDHC_RESPONSE_LEN_48 = 2U ,   CYHAL_SDHC_RESPONSE_LEN_48B = 3U }
	SDHC response types. More...
enum	cyhal_sdhc_auto_cmd_t {   CYHAL_SDHC_AUTO_CMD_NONE = 0U ,   CYHAL_SDHC_AUTO_CMD_12 = 1U ,   CYHAL_SDHC_AUTO_CMD_23 = 2U ,   CYHAL_SDHC_AUTO_CMD_AUTO = 3U }
	SDHC auto command enable selection. More...
enum	cyhal_sdhc_cmd_type_t {   CYHAL_SDHC_CMD_NORMAL = 0U ,   CYHAL_SDHC_CMD_SUSPEND = 1U ,   CYHAL_SDHC_CMD_RESUME = 2U ,   CYHAL_SDHC_CMD_ABORT = 3U }
	SDHC command types. More...
enum	cyhal_sdhc_error_type_t {   CYHAL_SDHC_NO_ERR = 0x0000U ,   CYHAL_SDHC_CMD_TOUT_ERR = 0x0001U ,   CYHAL_SDHC_CMD_CRC_ERR = 0x0002U ,   CYHAL_SDHC_CMD_END_BIT_ERR = 0x0004U ,   CYHAL_SDHC_CMD_IDX_ERR = 0x0008U ,   CYHAL_SDHC_DATA_TOUT_ERR = 0x0010U ,   CYHAL_SDHC_DATA_CRC_ERR = 0x0020U ,   CYHAL_SDHC_DATA_END_BIT_ERR = 0x0040U ,   CYHAL_SDHC_CUR_LMT_ERR = 0x0080U ,   CYHAL_SDHC_AUTO_CMD_ERR = 0x0100U ,   CYHAL_SDHC_ADMA_ERR = 0x0200U ,   CYHAL_SDHC_TUNNING_ERR = 0x0400U ,   CYHAL_SDHC_RESP_ERR = 0x0800U ,   CYHAL_SDHC_BOOT_ACK_ERR = 0x1000U }
	SDHC command error states. More...

Functions
cy_rslt_t	cyhal_sdhc_init_hw (cyhal_sdhc_t *obj, const cyhal_sdhc_config_t *config, cyhal_gpio_t cmd, cyhal_gpio_t clk, cyhal_gpio_t data0, cyhal_gpio_t data1, cyhal_gpio_t data2, cyhal_gpio_t data3, cyhal_gpio_t data4, cyhal_gpio_t data5, cyhal_gpio_t data6, cyhal_gpio_t data7, cyhal_gpio_t card_detect, cyhal_gpio_t io_volt_sel, cyhal_gpio_t card_pwr_en, cyhal_gpio_t card_mech_write_prot, cyhal_gpio_t led_ctrl, cyhal_gpio_t emmc_reset, cyhal_clock_t *block_clk)
	Initialize SDHC driver and corresponding hardware. More...
cy_rslt_t	cyhal_sdhc_init_card (cyhal_sdhc_t *obj)
	Initialize the connected card. More...
cy_rslt_t	cyhal_sdhc_init (cyhal_sdhc_t *obj, const cyhal_sdhc_config_t *config, cyhal_gpio_t cmd, cyhal_gpio_t clk, cyhal_gpio_t data0, cyhal_gpio_t data1, cyhal_gpio_t data2, cyhal_gpio_t data3, cyhal_gpio_t data4, cyhal_gpio_t data5, cyhal_gpio_t data6, cyhal_gpio_t data7, cyhal_gpio_t card_detect, cyhal_gpio_t io_volt_sel, cyhal_gpio_t card_pwr_en, cyhal_gpio_t card_mech_write_prot, cyhal_gpio_t led_ctrl, cyhal_gpio_t emmc_reset, cyhal_clock_t *block_clk)
	Initialize the SDHC block and connected card. More...
void	cyhal_sdhc_free (cyhal_sdhc_t *obj)
	Release the SDHC peripheral, not currently invoked. More...
cy_rslt_t	cyhal_sdhc_read (cyhal_sdhc_t *obj, uint32_t address, uint8_t *data, size_t *length)
	Attempts to read data synchronously over the SDHC peripheral. More...
cy_rslt_t	cyhal_sdhc_write (cyhal_sdhc_t *obj, uint32_t address, const uint8_t *data, size_t *length)
	Attempts to write data synchronously over SDHC peripheral. More...
cy_rslt_t	cyhal_sdhc_erase (cyhal_sdhc_t *obj, uint32_t start_addr, size_t length, uint32_t timeout_ms)
	Erases a block of data over the SDHC peripheral. More...
cy_rslt_t	cyhal_sdhc_read_async (cyhal_sdhc_t *obj, uint32_t address, uint8_t *data, size_t *length)
	Start SDHC asynchronous read. More...
cy_rslt_t	cyhal_sdhc_write_async (cyhal_sdhc_t *obj, uint32_t address, const uint8_t *data, size_t *length)
	Start asynchronous SDHC write. More...
bool	cyhal_sdhc_is_busy (const cyhal_sdhc_t *obj)
	Checks if the specified SDHC peripheral is in use. More...
cy_rslt_t	cyhal_sdhc_abort_async (cyhal_sdhc_t *obj)
	Abort an SDHC transfer. More...
void	cyhal_sdhc_register_callback (cyhal_sdhc_t *obj, cyhal_sdhc_event_callback_t callback, void *callback_arg)
	Register an SDHC callback handler. More...
void	cyhal_sdhc_enable_event (cyhal_sdhc_t *obj, cyhal_sdhc_event_t event, uint8_t intr_priority, bool enable)
	Configure SDHC event enablement. More...
bool	cyhal_sdhc_is_card_inserted (const cyhal_sdhc_t *obj)
	Checks if SD card is inserted. More...
bool	cyhal_sdhc_is_card_mech_write_protected (const cyhal_sdhc_t *obj)
	Checks if the inserted SD card is mechanically write protected. More...
cy_rslt_t	cyhal_sdhc_get_block_count (cyhal_sdhc_t *obj, uint32_t *block_count)
	Get block count of inserted SD card / eMMC. More...
cy_rslt_t	cyhal_sdhc_set_frequency (cyhal_sdhc_t *obj, uint32_t hz, bool negotiate)
	Sets the SD bus frequency (frequency on which SD card / eMMC is accessed) More...
uint32_t	cyhal_sdhc_get_frequency (cyhal_sdhc_t *obj)
	Get the actual frequency that SD bus is configured for. More...
cy_rslt_t	cyhal_sdhc_set_data_read_timeout (cyhal_sdhc_t *obj, uint32_t timeout, bool auto_reconfigure)
	Sets the maximum time to wait for data from the card. More...
cy_rslt_t	cyhal_sdhc_config_data_transfer (cyhal_sdhc_t *obj, cyhal_sdhc_data_config_t *data_config)
	Initializes the SD block and DMA for a data transfer. More...
cy_rslt_t	cyhal_sdhc_send_cmd (cyhal_sdhc_t *obj, cyhal_sdhc_cmd_config_t *cmd_config)
	Sends a command to the card and wait until it is sent. More...
cy_rslt_t	cyhal_sdhc_get_response (cyhal_sdhc_t *obj, uint32_t *response, bool large_response)
	Returns a response of last issued by cyhal_sdhc_send_cmd function command. More...
cy_rslt_t	cyhal_sdhc_wait_transfer_complete (cyhal_sdhc_t *obj)
	Wait for asynchronous data transfer to complete. More...
cy_rslt_t	cyhal_sdhc_set_io_voltage (cyhal_sdhc_t *obj, cyhal_sdhc_io_voltage_t io_voltage, cyhal_sdhc_io_volt_action_type_t io_switch_type)
	Sets the voltage level of the I/O lines. More...
cyhal_sdhc_io_voltage_t	cyhal_sdhc_get_io_voltage (cyhal_sdhc_t *obj)
	Returns the current voltage level of the I/O lines. More...
cy_rslt_t	cyhal_sdhc_set_bus_width (cyhal_sdhc_t *obj, uint8_t bus_width, bool configure_card)
	Configures data bus width on host side and (optionally) informs the card about new width configuration. More...
uint8_t	cyhal_sdhc_get_bus_width (cyhal_sdhc_t *obj)
	Returns currently configured data bus width. More...
cyhal_sdhc_error_type_t	cyhal_sdhc_get_last_command_errors (cyhal_sdhc_t *obj)
	Returns last issued SD operation error states. More...
void	cyhal_sdhc_clear_errors (cyhal_sdhc_t *obj)
	Clears SDHC hardware error states. More...
void	cyhal_sdhc_software_reset (cyhal_sdhc_t *obj)
	Resets CMD and Data lines and corresponding circuits of SD Host. More...
cy_rslt_t	cyhal_sdhc_enable_card_power (cyhal_sdhc_t *obj, bool enable)
	Powers up / down the card based on provided parameter. More...
cy_rslt_t	cyhal_sdhc_init_cfg (cyhal_sdhc_t *obj, const cyhal_sdhc_configurator_t *cfg)
	Initialize the SDHC peripheral using a configurator generated configuration struct. More...

---

Data Structure Documentation

cyhal_sdhc_config_t

struct cyhal_sdhc_config_t

Data Fields
bool	enableLedControl	Drive one IO to indicate when the card is being accessed.
bool	lowVoltageSignaling	Whether 1.8V signaling is supported.
bool	isEmmc	true if eMMC card, otherwise false
uint8_t	busWidth	The desired bus width, 1-bit, 4-bit, 8-bit.

cyhal_sdhc_data_config_t

struct cyhal_sdhc_data_config_t

Data Fields
uint32_t *	data_ptr	The pointer to data for send/receive. Data will be transfered using DMA, which will be configured automaticaly by SDHC HAL driver.
uint32_t	block_size	The size of the data block.
uint32_t	number_of_blocks	The number of blocks with size block_size to send.
cyhal_sdhc_auto_cmd_t	auto_command	Selects which auto commands are used if any.
bool	is_read	true = Read from the card, false = Write to the card.

cyhal_sdhc_cmd_config_t

struct cyhal_sdhc_cmd_config_t

Data Fields
uint32_t	command_index	The index of the command.
uint32_t	command_argument	The argument for the command.
bool	enable_crc_check	Enables the CRC check on the response.
cyhal_sdhc_cmd_response_type_t	response_type	The response type.
bool	enable_idx_check	Checks the index of the response.
cyhal_sdhc_cmd_type_t	command_type	The command type.
cyhal_sdhc_data_config_t *	data_config	Data transfer configuration, defined in cyhal_sdhc_data_config_t. Should be NULL if data transfer is not expected for provided command.

Enumeration Type Documentation

cyhal_sdhc_card_type_t

enum cyhal_sdhc_card_type_t

Card types.

Enumerator
CYHAL_SDHC_SD	Secure Digital card.
CYHAL_SDHC_SDIO	SD Input Output card.
CYHAL_SDHC_EMMC	Embedded Multimedia card.
CYHAL_SDHC_COMBO	Combo Card (SD + SDIO)
CYHAL_SDHC_UNUSABLE	Unusable card or unsupported type.
CYHAL_SDHC_NOT_EMMC	Not an eMMC card.

cyhal_sdhc_event_t

enum cyhal_sdhc_event_t

SDHC interrupt triggers.

Enumerator
CYHAL_SDHC_CMD_COMPLETE	Command Complete.
CYHAL_SDHC_XFER_COMPLETE	Host read/write transfer is complete.
CYHAL_SDHC_BGAP_EVENT	This bit is set when both read/write transaction is stopped at the block gap.
CYHAL_SDHC_DMA_INTERRUPT	Host controller detects an SDMA Buffer Boundary during transfer.
CYHAL_SDHC_BUF_WR_READY	This bit is set if the Buffer Write Enable changes from 0 to 1.
CYHAL_SDHC_BUF_RD_READY	This bit is set if the Buffer Read Enable changes from 0 to 1.
CYHAL_SDHC_CARD_INSERTION	This bit is set if the Card Inserted in the Present State register changes from 0 to 1.
CYHAL_SDHC_CARD_REMOVAL	This bit is set if the Card Inserted in the Present State register changes from 1 to 0.
CYHAL_SDHC_RE_TUNE_EVENT	This bit is set if the Re-Tuning Request changes from 0 to 1.
CYHAL_SDHC_FX_EVENT	This status is set when R[14] of response register is set to 1.
CYHAL_SDHC_CQE_EVENT	This status is set if Command Queuing/Crypto event has occurred.
CYHAL_SDHC_ERR_INTERRUPT	If any of the bits in the Error Interrupt Status register are set.
CYHAL_SDHC_ALL_INTERRUPTS	Is used to enable/disable all interrupts.

cyhal_sdhc_io_voltage_t

enum cyhal_sdhc_io_voltage_t

I/O voltage levels.

Enumerator
CYHAL_SDHC_IO_VOLTAGE_3_3V	I/O voltage is 3.3V.
CYHAL_SDHC_IO_VOLTAGE_1_8V	I/O voltage is 1.8V.

cyhal_sdhc_io_volt_action_type_t

enum cyhal_sdhc_io_volt_action_type_t

SDHC I/O voltage select principle.

Enumerator
CYHAL_SDHC_IO_VOLT_ACTION_NEGOTIATE	(Recommended) HAL driver performs all steps, needed for switching I/O bus voltage to certain level: sends needed commands to prepare card, changes level of io_volt_sel pin and performs switching sequence according to SD specification.
CYHAL_SDHC_IO_VOLT_ACTION_SWITCH_SEQ_ONLY	HAL driver performs switching sequence (if voltage is being switched to 1.8V) and changes io_volt_sel pin level accordingly. No commands are being send to the card in this mode.
CYHAL_SDHC_IO_VOLT_ACTION_NONE	I/O voltage is changed by changing io_volt_sel pin's level. No commands are being send to the card in this mode.

cyhal_sdhc_cmd_response_type_t

enum cyhal_sdhc_cmd_response_type_t

SDHC response types.

Enumerator
CYHAL_SDHC_RESPONSE_NONE	No Response.
CYHAL_SDHC_RESPONSE_LEN_136	Response Length 136.
CYHAL_SDHC_RESPONSE_LEN_48	Response Length 48.
CYHAL_SDHC_RESPONSE_LEN_48B	Response Length 48. Check Busy after response.

cyhal_sdhc_auto_cmd_t

enum cyhal_sdhc_auto_cmd_t

SDHC auto command enable selection.

Enumerator
CYHAL_SDHC_AUTO_CMD_NONE	Auto command disable.
CYHAL_SDHC_AUTO_CMD_12	Auto command 12 enable.
CYHAL_SDHC_AUTO_CMD_23	Auto command 23 enable.
CYHAL_SDHC_AUTO_CMD_AUTO	Auto command Auto enable.

cyhal_sdhc_cmd_type_t

enum cyhal_sdhc_cmd_type_t

SDHC command types.

Enumerator
CYHAL_SDHC_CMD_NORMAL	Other commands.
CYHAL_SDHC_CMD_SUSPEND	CMD52 for writing "Bus Suspend" in CCCR.
CYHAL_SDHC_CMD_RESUME	CMD52 for writing "Function Select" in CCCR.
CYHAL_SDHC_CMD_ABORT	CMD12, CMD52 for writing "I/O Abort" in CCCR.

cyhal_sdhc_error_type_t

enum cyhal_sdhc_error_type_t

SDHC command error states.

Enumerator
CYHAL_SDHC_NO_ERR	Last operation did not cause any error status.
CYHAL_SDHC_CMD_TOUT_ERR	Command timeout error. In SD/eMMC Mode, this event is set only if no response is returned within 64 SD clock cycles from the end bit of the command. If the Host Controller detects a CMD line conflict, along with Command CRC Error bit, this event is set to 1, without waiting for 64 SD/eMMC card clock cycles.
CYHAL_SDHC_CMD_CRC_ERR	Command CRC error. A Command CRC Error is generated in SD/eMMC mode when: A response is returned and the Command Timeout Error is set to 0 (indicating no timeout), this bit is set to 1 when detecting a CRC error in the command response. The Host Controller detects a CMD line conflict by monitoring the CMD line when a command is issued. If the Host Controller drives the CMD line to level 1, but detects level 0 on the CMD line at the next SD clock edge, then the Host Controller aborts the command (stop driving CMD line) and sets this bit to 1. The Command Timeout Error is also set to 1 to distinguish a CMD line conflict.
CYHAL_SDHC_CMD_END_BIT_ERR	Command End Bit error. This bit is set after detecting that the end bit of a command response is 0 in SD/eMMC mode.
CYHAL_SDHC_CMD_IDX_ERR	Command Index error. This bit is set if a Command Index error occurs in the command response in SD/eMMC mode.
CYHAL_SDHC_DATA_TOUT_ERR	Data Timeout error. This bit is set in SD/eMMC mode when detecting one of the following timeout conditions: Busy timeout for R1b, R5b type Busy timeout after Write CRC status Write CRC Status timeout Read Data timeout.
CYHAL_SDHC_DATA_CRC_ERR	Data CRC error. This error occurs in SD/eMMC mode after detecting a CRC error while transferring read data that uses the DAT line, detecting the Write CRC status having a value other than 010 or when writing a CRC status timeout.
CYHAL_SDHC_DATA_END_BIT_ERR	Data End Bit error. This error occurs in SD/eMMC mode either when detecting 0 at the end bit position of read data that uses the DAT line or at the end bit position of the CRC status.
CYHAL_SDHC_CUR_LMT_ERR	Current Limit error.
CYHAL_SDHC_AUTO_CMD_ERR	Auto CMD error. This error status is used by Auto CMD12 and Auto CMD23 in SD/eMMC mode. This bit is set after detecting that any of the bits D00 to D05 in the Auto CMD Error Status register has changed from 0 to 1. D07 is effective in case for Auto CMD12. The Auto CMD Error Status register is valid while this bit is set to 1 and may be cleared by clearing this bit.
CYHAL_SDHC_ADMA_ERR	ADMA error. This bit is set when the Host Controller detects an error during an ADMA-based data transfer. The possible reasons for an error: An error response is received from the System bus; ADMA3, ADMA2 Descriptors are invalid; CQE Task or Transfer descriptors are invalid. When an error occurs, the state of the ADMA is saved in the ADMA Error Status register.
CYHAL_SDHC_TUNNING_ERR	Tuning error.
CYHAL_SDHC_RESP_ERR	Response error. Host Controller Version 4.00 supports the response error check function to avoid overhead of the response error check by Host Driver during DMA execution. If the Response Error Check Enable is set to 1 in the Transfer Mode register, the Host Controller checks R1 or R5 response. If an error is detected in a response, this bit is set to 1. This is applicable in SD/eMMC mode.
CYHAL_SDHC_BOOT_ACK_ERR	Boot Acknowledgement error. This bit is set when there is a timeout for boot acknowledgement or after detecting the boot ACK status having a value other than 010. This is applicable only when boot acknowledgement is expected in eMMC mode.

Function Documentation

cyhal_sdhc_init_hw()

cy_rslt_t cyhal_sdhc_init_hw	(	cyhal_sdhc_t *	obj,
		const cyhal_sdhc_config_t *	config,
		cyhal_gpio_t	cmd,
		cyhal_gpio_t	clk,
		cyhal_gpio_t	data0,
		cyhal_gpio_t	data1,
		cyhal_gpio_t	data2,
		cyhal_gpio_t	data3,
		cyhal_gpio_t	data4,
		cyhal_gpio_t	data5,
		cyhal_gpio_t	data6,
		cyhal_gpio_t	data7,
		cyhal_gpio_t	card_detect,
		cyhal_gpio_t	io_volt_sel,
		cyhal_gpio_t	card_pwr_en,
		cyhal_gpio_t	card_mech_write_prot,
		cyhal_gpio_t	led_ctrl,
		cyhal_gpio_t	emmc_reset,
		cyhal_clock_t *	block_clk
	)

Initialize SDHC driver and corresponding hardware.

Parameters

[out]	obj	Pointer to an SDHC object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	config	The card configuration object
[out]	clk	The pin connected to the clk signal
[in]	cmd	The pin connected to the command signal
[in]	data0	The pin connected to the data0 signal
[in]	data1	The pin connected to the data1 signal. This pin can be NC if bus width is 1-bit.
[in]	data2	The pin connected to the data2 signal. This pin can be NC if bus width is 1-bit.
[in]	data3	The pin connected to the data3 signal. This pin can be NC if bus width is 1-bit.
[in]	data4	The pin connected to the data4 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data5	The pin connected to the data5 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data6	The pin connected to the data6 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data7	The pin connected to the data7 signal. This pin can be NC if bus width is less than 8-bit.
[in]	card_detect	The pin connected to the card_detect signal Card is considered as inserted if card_detect pin in low state. This pin can be NC.
[out]	io_volt_sel	The pin connected to the io_volt_sel signal. This pin changes the logic level on the sd_io_volt_sel line. It assumes that this line is used to control a regulator connected to the VDDIO of the MCU. This regulator allows for switching between the 3.3V and 1.8V signaling. High level on the pin stands for 1.8V signaling, while low - for 3.3V. This pin can be NC.
[out]	card_pwr_en	The pin connected to the card_pwr_en signal This pin can be used to enable a voltage regulator used to power the card. High level on the pin - card is powered. Low - card is not powered. This pin can be NC.
[in]	card_mech_write_prot	The pin connected to the card_mech_write_prot signal This pin is used for card mechanical write protect checking. If pin in high state - card is mechanically write protected, if in low state - card is not mechanically write protected. cyhal_sdhc_is_card_mech_write_protected function can be used to check card write protection state. This pin can be NC.
[in]	led_ctrl	The pin connected to the led_ctrl signal. This pin can be NC.
[in]	emmc_reset	The pin connected to the emmc_reset signal. This pin can be NC.
[in]	block_clk	The clock to use can be shared, if not provided a new clock will be allocated

Returns

The status of the init request

cyhal_sdhc_init_card()

cy_rslt_t cyhal_sdhc_init_card

(

cyhal_sdhc_t *

obj

)

Initialize the connected card.

Note

This function should be called after cyhal_sdhc_init_hw

Parameters

[in,out]

obj

The SDHC object

Returns

The status of the card init request

cyhal_sdhc_init()

cy_rslt_t cyhal_sdhc_init	(	cyhal_sdhc_t *	obj,
		const cyhal_sdhc_config_t *	config,
		cyhal_gpio_t	cmd,
		cyhal_gpio_t	clk,
		cyhal_gpio_t	data0,
		cyhal_gpio_t	data1,
		cyhal_gpio_t	data2,
		cyhal_gpio_t	data3,
		cyhal_gpio_t	data4,
		cyhal_gpio_t	data5,
		cyhal_gpio_t	data6,
		cyhal_gpio_t	data7,
		cyhal_gpio_t	card_detect,
		cyhal_gpio_t	io_volt_sel,
		cyhal_gpio_t	card_pwr_en,
		cyhal_gpio_t	card_mech_write_prot,
		cyhal_gpio_t	led_ctrl,
		cyhal_gpio_t	emmc_reset,
		cyhal_clock_t *	block_clk
	)

Initialize the SDHC block and connected card.

This function is a combination of cyhal_sdhc_init_hw and cyhal_sdhc_init_card calls.

Note

refer to cyhal_sdhc_init_hw function description for detailed parameter guidance.

Parameters

[out]	obj	Pointer to an SDHC object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	config	The card configuration object
[out]	clk	The pin connected to the clk signal
[in]	cmd	The pin connected to the command signal
[in]	data0	The pin connected to the data0 signal
[in]	data1	The pin connected to the data1 signal. This pin can be NC if bus width is 1-bit.
[in]	data2	The pin connected to the data2 signal. This pin can be NC if bus width is 1-bit.
[in]	data3	The pin connected to the data3 signal. This pin can be NC if bus width is 1-bit.
[in]	data4	The pin connected to the data4 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data5	The pin connected to the data5 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data6	The pin connected to the data6 signal. This pin can be NC if bus width is less than 8-bit.
[in]	data7	The pin connected to the data7 signal. This pin can be NC if bus width is less than 8-bit.
[in]	card_detect	The pin connected to the card_detect signal
[out]	io_volt_sel	The pin connected to the io_volt_sel signal
[out]	card_pwr_en	The pin connected to the card_pwr_en signal
[in]	card_mech_write_prot	The pin connected to the card_mech_write_prot signal
[in]	led_ctrl	The pin connected to the led_ctrl signal
[in]	emmc_reset	The pin connected to the emmc_reset signal
[in]	block_clk	The clock to use can be shared, if not provided a new clock will be allocated

Returns

The status of the init request

cyhal_sdhc_free()

void cyhal_sdhc_free

(

cyhal_sdhc_t *

obj

)

Release the SDHC peripheral, not currently invoked.

It requires further resource management.

Parameters

[in,out]

obj

The SDHC object

cyhal_sdhc_read()

cy_rslt_t cyhal_sdhc_read	(	cyhal_sdhc_t *	obj,
		uint32_t	address,
		uint8_t *	data,
		size_t *	length
	)

Attempts to read data synchronously over the SDHC peripheral.

This will read as many blocks as possible, up to length blocks, into the buffer pointed to by data, then return. The value pointed to by length will be updated to reflect the number of words that were actually read.

See Snippet 2: Reading a block of data from an SD Card

Parameters

[in]	obj	The SDHC object
[in]	address	The address to read data from
[out]	data	Pointer to the byte-array where data read from the device should be stored
[in,out]	length	Number of 512 byte blocks to read, updated with the number actually read

Returns

The status of the read request

cyhal_sdhc_write()

cy_rslt_t cyhal_sdhc_write	(	cyhal_sdhc_t *	obj,
		uint32_t	address,
		const uint8_t *	data,
		size_t *	length
	)

Attempts to write data synchronously over SDHC peripheral.

This will write as many blocks as possible, up to length blocks, then return. The value pointed to by length will be updated to reflect the number of words that were actually read.

See Snippet 3: Writing a block of data to an SD Card

Parameters

[in]	obj	The SDHC object
[in]	address	The address to write data to
[in]	data	Pointer to the byte-array of data to write to the device
[in,out]	length	Number of 512 byte blocks to write, updated with the number actually written

Returns

The status of the write request

cyhal_sdhc_erase()

cy_rslt_t cyhal_sdhc_erase	(	cyhal_sdhc_t *	obj,
		uint32_t	start_addr,
		size_t	length,
		uint32_t	timeout_ms
	)

Erases a block of data over the SDHC peripheral.

Parameters

[in]	obj	The SDHC object
[in]	start_addr	Is the address of the first byte to erase
[in]	length	Number of 512 byte blocks (starting at start_addr) to erase
[in]	timeout_ms	Timeout value in ms for waiting/polling operations. If zero is provided for this parameter the default value will be used. See implementation specific documentation for timeout details.

Returns

The status of the erase request

cyhal_sdhc_read_async()

cy_rslt_t cyhal_sdhc_read_async	(	cyhal_sdhc_t *	obj,
		uint32_t	address,
		uint8_t *	data,
		size_t *	length
	)

Start SDHC asynchronous read.

This will transfer length 512 byte blocks into the buffer pointed to by data in the background. When the requested quantity of data has been read, the CYHAL_SDHC_XFER_COMPLETE event will be raised. See cyhal_sdhc_register_callback and cyhal_sdhc_enable_event.

Parameters

[in]	obj	The SDHC object that holds the transfer information
[in]	address	The address to read data from
[out]	data	The receive buffer
[in,out]	length	Number of 512 byte blocks to read, updated with the number actually read

Returns

The status of the read_async request

cyhal_sdhc_write_async()

cy_rslt_t cyhal_sdhc_write_async	(	cyhal_sdhc_t *	obj,
		uint32_t	address,
		const uint8_t *	data,
		size_t *	length
	)

Start asynchronous SDHC write.

This will transfer length 512 byte blocks from the buffer pointed to by data in the background. When the requested quantity of data has been written, the CYHAL_SDHC_XFER_COMPLETE event will be raised. See cyhal_sdhc_register_callback and cyhal_sdhc_enable_event.

Parameters

[in]	obj	The SDHC object that holds the transfer information
[in]	address	The address to write data to
[in]	data	The transmit buffer
[in,out]	length	The number of 512 byte blocks to write, updated with the number actually written

Returns

The status of the write_async request

cyhal_sdhc_is_busy()

bool cyhal_sdhc_is_busy

(

const cyhal_sdhc_t *

obj

)

Checks if the specified SDHC peripheral is in use.

Parameters

[in]

obj

The SDHC peripheral to check

Returns

Indication of whether the SDHC is still transmitting

cyhal_sdhc_abort_async()

cy_rslt_t cyhal_sdhc_abort_async

(

cyhal_sdhc_t *

obj

)

Abort an SDHC transfer.

Parameters

[in]

obj

The SDHC peripheral to stop

Returns

The status of the abort_async request

cyhal_sdhc_register_callback()

void cyhal_sdhc_register_callback	(	cyhal_sdhc_t *	obj,
		cyhal_sdhc_event_callback_t	callback,
		void *	callback_arg
	)

Register an SDHC callback handler.

This function will be called when one of the events enabled by cyhal_sdhc_enable_event occurs.

Parameters

[in]	obj	The SDHC object
[in]	callback	The callback handler which will be invoked when the event fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_sdhc_enable_event()

void cyhal_sdhc_enable_event	(	cyhal_sdhc_t *	obj,
		cyhal_sdhc_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure SDHC event enablement.

When an enabled event occurs, the function specified by cyhal_sdhc_register_callback will be called.

Parameters

[in]	obj	The SDHC object
[in]	event	The SDHC event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off

cyhal_sdhc_is_card_inserted()

bool cyhal_sdhc_is_card_inserted

(

const cyhal_sdhc_t *

obj

)

Checks if SD card is inserted.

Parameters

[in]

obj

The SDHC peripheral to check

Returns

Indication of whether the card is inserted.

cyhal_sdhc_is_card_mech_write_protected()

bool cyhal_sdhc_is_card_mech_write_protected

(

const cyhal_sdhc_t *

obj

)

Checks if the inserted SD card is mechanically write protected.

Parameters

[in]

obj

The SDHC peripheral to check

Returns

Indication of whether the inserted SD card is mechanically write protected

cyhal_sdhc_get_block_count()

cy_rslt_t cyhal_sdhc_get_block_count	(	cyhal_sdhc_t *	obj,
		uint32_t *	block_count
	)

Get block count of inserted SD card / eMMC.

Note

SDHC driver should be initialized with cyhal_sdhc_init prior to using this function.

Parameters

[in]	obj	The SDHC object
[in]	block_count	Pointer to variable where block count will be stored

Returns

The status of the operation

cyhal_sdhc_set_frequency()

cy_rslt_t cyhal_sdhc_set_frequency	(	cyhal_sdhc_t *	obj,
		uint32_t	hz,
		bool	negotiate
	)

Sets the SD bus frequency (frequency on which SD card / eMMC is accessed)

Note

Actual frequency may differ from the desired frequency due to available dividers and the frequency of source clock. Function will set the closest possible (but not greater than) frequency to what was requested. Use cyhal_sdhc_get_frequency function to get actual frequency value that was achieved and set.

If data timeout was configured by cyhal_sdhc_set_data_read_timeout, it can be automaticaly recalculated according to new SD bus frequency. For details, please refer to cyhal_sdhc_set_data_read_timeout function description.

Parameters

[in]	obj	The SDHC object
[in]	hz	Desired SD bus frequency in Hz
[in]	negotiate	Whether new frequency value needs to be negotiated with card or not. true is recommended and it means that new frequency will be negotiated.

Returns

The status of the operation

cyhal_sdhc_get_frequency()

uint32_t cyhal_sdhc_get_frequency

(

cyhal_sdhc_t *

obj

)

Get the actual frequency that SD bus is configured for.

Parameters

[in]

obj

The SDHC object

Returns

Frequency in Hz

cyhal_sdhc_set_data_read_timeout()

cy_rslt_t cyhal_sdhc_set_data_read_timeout	(	cyhal_sdhc_t *	obj,
		uint32_t	timeout,
		bool	auto_reconfigure
	)

Sets the maximum time to wait for data from the card.

The time is specified in number of card clock cycles. With SD bus frequency changed by cyhal_sdhc_set_frequency, timeout can automaticaly be recalculated according to new clock frequency. This can be activated by 'auto_reconfigure' parameter.

Parameters

[in]	obj	The SDHC object
[in]	timeout	Time to wait for data from the card.
[in]	auto_reconfigure	Timeout value will be automaticaly reconfigured upon clock change

Returns

The status of the operation

cyhal_sdhc_config_data_transfer()

cy_rslt_t cyhal_sdhc_config_data_transfer	(	cyhal_sdhc_t *	obj,
		cyhal_sdhc_data_config_t *	data_config
	)

Initializes the SD block and DMA for a data transfer.

It does not start a transfer. cyhal_sdhc_send_cmd needs to be called after this function in order to start data transfer.

Parameters

[in]	obj	The SDHC object
[in]	data_config	Data transfer configuration

Returns

The status of the operation

cyhal_sdhc_send_cmd()

cy_rslt_t cyhal_sdhc_send_cmd	(	cyhal_sdhc_t *	obj,
		cyhal_sdhc_cmd_config_t *	cmd_config
	)

Sends a command to the card and wait until it is sent.

If the command assumes data transfer via data lines, cyhal_sdhc_config_data_transfer function needs to be called prior to this one. The response of issued command can be retrieved by using cyhal_sdhc_get_response function.

Note

Function does not wait until data (configured with cyhal_sdhc_config_data_transfer) transfer complete. In order to do so, user can:

• register CYHAL_SDHC_XFER_COMPLETE and wait for it
• wait until cyhal_sdhc_is_busy return false
• use cyhal_sdhc_wait_transfer_complete function

Parameters

[in]	obj	The SDHC object
[in]	cmd_config	Command configuration

Returns

The status of the operation

cyhal_sdhc_get_response()

cy_rslt_t cyhal_sdhc_get_response	(	cyhal_sdhc_t *	obj,
		uint32_t *	response,
		bool	large_response
	)

Returns a response of last issued by cyhal_sdhc_send_cmd function command.

Parameters

[in]	obj	The SDHC object
[in]	response	Pointer to array where response will be stored
[in]	large_response	If true, the expected response is 136 bits, false - 48 bits, which corresponds to 120 and 32 bits of useful for application data respectively. So for large_response 4 uint32_t element array can be used while for not large_response 1 uint32_t value will be enough.

Returns

The status of the operation

cyhal_sdhc_wait_transfer_complete()

cy_rslt_t cyhal_sdhc_wait_transfer_complete

(

cyhal_sdhc_t *

obj

)

Wait for asynchronous data transfer to complete.

Such data transfer can be triggered by cyhal_sdhc_write_async, cyhal_sdhc_read_async or by cyhal_sdhc_config_data_transfer + cyhal_sdhc_send_cmd functions.

Parameters

[in]

obj

The SDHC object

Returns

The status of the operation

cyhal_sdhc_set_io_voltage()

cy_rslt_t cyhal_sdhc_set_io_voltage	(	cyhal_sdhc_t *	obj,
		cyhal_sdhc_io_voltage_t	io_voltage,
		cyhal_sdhc_io_volt_action_type_t	io_switch_type
	)

Sets the voltage level of the I/O lines.

Note

This function requires io_volt_sel and (for some cases) card_pwr_en pins to be assigned. Please refer to cyhal_sdhc_init_hw for pin details.

Switching from 1.8V to 3.3V can be done only via power cycle sequence (power down card, wait, power up card), which is supported by HAL driver and performed only if CYHAL_SDHC_IO_VOLT_ACTION_NEGOTIATE selected. card_pwr_en pin has to be assigned. Please refer to cyhal_sdhc_init_hw for pin details.

Parameters

[in]	obj	The SDHC object
[in]	io_voltage	I/O voltage to be set on lines
[in]	io_switch_type	Defines how I/O voltage will be switched

Returns

The status of the operation

cyhal_sdhc_get_io_voltage()

cyhal_sdhc_io_voltage_t cyhal_sdhc_get_io_voltage

(

cyhal_sdhc_t *

obj

)

Returns the current voltage level of the I/O lines.

Parameters

[in]

obj

The SDHC object

Returns

Current I/O voltage setting value

cyhal_sdhc_set_bus_width()

cy_rslt_t cyhal_sdhc_set_bus_width	(	cyhal_sdhc_t *	obj,
		uint8_t	bus_width,
		bool	configure_card
	)

Configures data bus width on host side and (optionally) informs the card about new width configuration.

Parameters

[in]	obj	The SDHC object
[in]	bus_width	The desired bus width, 1-bit, 4-bit, 8-bit
[in]	configure_card	Whether card needs to be configured with new bus width. true is recommended.

Returns

The status of the operation

cyhal_sdhc_get_bus_width()

uint8_t cyhal_sdhc_get_bus_width

(

cyhal_sdhc_t *

obj

)

Returns currently configured data bus width.

Parameters

[in]

obj

The SDHC object

Returns

Currently configured bus width, 1-bit, 4-bit, 8-bit

cyhal_sdhc_get_last_command_errors()

cyhal_sdhc_error_type_t cyhal_sdhc_get_last_command_errors

(

cyhal_sdhc_t *

obj

)

Returns last issued SD operation error states.

This function can be used for error checking after any of cmd / data transfer-related operations. For list of possible errors, that are being tracked, please refer to cyhal_sdhc_error_type_t.

Parameters

[in]

obj

The SDHC object

Returns

Errors occurred during last command

cyhal_sdhc_clear_errors()

void cyhal_sdhc_clear_errors

(

cyhal_sdhc_t *

obj

)

Clears SDHC hardware error states.

Error statuses are indicated by cyhal_sdhc_get_last_command_errors function.

Parameters

[in]

obj

The SDHC object

cyhal_sdhc_software_reset()

void cyhal_sdhc_software_reset

(

cyhal_sdhc_t *

obj

)

Resets CMD and Data lines and corresponding circuits of SD Host.

Parameters

[in]

obj

The SDHC object

cyhal_sdhc_enable_card_power()

cy_rslt_t cyhal_sdhc_enable_card_power	(	cyhal_sdhc_t *	obj,
		bool	enable
	)

Powers up / down the card based on provided parameter.

This function uses card_pwr_en pin to change card power state. Please refer to cyhal_sdhc_init_hw for pin description.

Parameters

[in]	obj	The SDHC peripheral to configure
[in]	enable	Card is powered if true, not powered if false.

Returns

The status of the operation

cyhal_sdhc_init_cfg()

cy_rslt_t cyhal_sdhc_init_cfg	(	cyhal_sdhc_t *	obj,
		const cyhal_sdhc_configurator_t *	cfg
	)

Initialize the SDHC peripheral using a configurator generated configuration struct.

Parameters

[in]	obj	The SDHC peripheral to configure
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the operation