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 Device Configurator and selecting the pins according to the target device used. Specify the SDHC configuration using the configuration structure (const mtb_hal_sdhc_configurator_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 - mtb_hal_sdhc_t, SDHC card configuration structure (const mtb_hal_sdhc_config_t * config). The pins connected to the SDHC block needs to be provided by the design.modus file after using Device Configurator.

 
    cy_rslt_t rslt = CY_RSLT_SUCCESS;
    mtb_hal_sdhc_t sdhc_object;
    cy_stc_sd_host_context_t sdhc_context;
 
    // Use PDL to configure SDHC hardware
    (void)Cy_SD_Host_Enable(SDHC_sdhc_hal_config.base);
 
 
    // Configure interrupt handling
    cy_stc_sysint_t intr_cfg_1 = { .intrSrc = SDHC_IRQ, .intrPriority = 7u }; // SDHC_IRQ generated
                                                                              // through device
                                                                              // configurator
    Cy_SysInt_Init(&intr_cfg_1, my_sdhc_interrupt_handler); // User implements interrupt handler
    NVIC_EnableIRQ(SDHC_IRQ);
 
 
    // Continue using PDL for SDHC hardware configuration
    if (rslt == CY_RSLT_SUCCESS)
    {
        rslt = (cy_rslt_t)Cy_SD_Host_Init(SDHC_sdhc_hal_config.base,
                                          SDHC_sdhc_hal_config.host_config, &sdhc_context);
    }
 
    if (rslt == CY_RSLT_SUCCESS)
    {
        rslt = (cy_rslt_t)Cy_SD_Host_InitCard(SDHC_sdhc_hal_config.base,
                                              SDHC_sdhc_hal_config.card_config, &sdhc_context);
    }
 
    // Set up our SDHC HAL object
    rslt = mtb_hal_sdhc_setup(&sdhc_object, &SDHC_sdhc_hal_config, NULL, &sdhc_context);
 
 

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

The following snippet reads a block of data from the SD Card. The setup steps from Snippet 1: SDHC Initialization and configuration must be followed before reading.

    #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;
 
    // Call to make the asynchronous read
    rslt = mtb_hal_sdhc_read_async(&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. The setup steps from Snippet 1: SDHC Initialization and configuration must be followed before writing.

    #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;
    }
 
    // Call to make the asynchronous write
    rslt = mtb_hal_sdhc_write_async(&sdhc_obj, block_address, write_buff, &block_count);
 

API Reference
	SDHC HAL Results
	SDHC specific return codes.

Data Structures
struct	mtb_hal_sdhc_config_t
	Defines configuration options for the SDHC block. More...
struct	mtb_hal_sdhc_data_config_t
	Defines data configuration. More...
struct	mtb_hal_sdhc_cmd_config_t
	Defines command configuration for mtb_hal_sdhc_send_cmd function. More...

Enumerations
enum	mtb_hal_sdhc_card_type_t {   MTB_HAL_SDHC_SD ,   MTB_HAL_SDHC_SDIO ,   MTB_HAL_SDHC_EMMC ,   MTB_HAL_SDHC_COMBO ,   MTB_HAL_SDHC_UNUSABLE ,   MTB_HAL_SDHC_NOT_EMMC }
	Card types. More...
enum	mtb_hal_sdhc_io_voltage_t {   MTB_HAL_SDHC_IO_VOLTAGE_3_3V = 0U ,   MTB_HAL_SDHC_IO_VOLTAGE_1_8V = 1U }
	I/O voltage levels. More...
enum	mtb_hal_sdhc_io_volt_action_type_t {   MTB_HAL_SDHC_IO_VOLT_ACTION_NEGOTIATE = 0U ,   MTB_HAL_SDHC_IO_VOLT_ACTION_SWITCH_SEQ_ONLY = 1U ,   MTB_HAL_SDHC_IO_VOLT_ACTION_NONE = 2U }
	SDHC I/O voltage select principle. More...
enum	mtb_hal_sdhc_cmd_response_type_t {   MTB_HAL_SDHC_RESPONSE_NONE = 0U ,   MTB_HAL_SDHC_RESPONSE_LEN_136 = 1U ,   MTB_HAL_SDHC_RESPONSE_LEN_48 = 2U ,   MTB_HAL_SDHC_RESPONSE_LEN_48B = 3U }
	SDHC response types. More...
enum	mtb_hal_sdhc_auto_cmd_t {   MTB_HAL_SDHC_AUTO_CMD_NONE = 0U ,   MTB_HAL_SDHC_AUTO_CMD_12 = 1U ,   MTB_HAL_SDHC_AUTO_CMD_23 = 2U ,   MTB_HAL_SDHC_AUTO_CMD_AUTO = 3U }
	SDHC auto command enable selection. More...
enum	mtb_hal_sdhc_cmd_type_t {   MTB_HAL_SDHC_CMD_NORMAL = 0U ,   MTB_HAL_SDHC_CMD_SUSPEND = 1U ,   MTB_HAL_SDHC_CMD_RESUME = 2U ,   MTB_HAL_SDHC_CMD_ABORT = 3U }
	SDHC command types. More...
enum	mtb_hal_sdhc_error_type_t {   MTB_HAL_SDHC_NO_ERR = 0x0000U ,   MTB_HAL_SDHC_CMD_TOUT_ERR = 0x0001U ,   MTB_HAL_SDHC_CMD_CRC_ERR = 0x0002U ,   MTB_HAL_SDHC_CMD_END_BIT_ERR = 0x0004U ,   MTB_HAL_SDHC_CMD_IDX_ERR = 0x0008U ,   MTB_HAL_SDHC_DATA_TOUT_ERR = 0x0010U ,   MTB_HAL_SDHC_DATA_CRC_ERR = 0x0020U ,   MTB_HAL_SDHC_DATA_END_BIT_ERR = 0x0040U ,   MTB_HAL_SDHC_CUR_LMT_ERR = 0x0080U ,   MTB_HAL_SDHC_AUTO_CMD_ERR = 0x0100U ,   MTB_HAL_SDHC_ADMA_ERR = 0x0200U ,   MTB_HAL_SDHC_TUNNING_ERR = 0x0400U ,   MTB_HAL_SDHC_RESP_ERR = 0x0800U ,   MTB_HAL_SDHC_BOOT_ACK_ERR = 0x1000U }
	SDHC command error states. More...

Functions
cy_rslt_t	mtb_hal_sdhc_setup (mtb_hal_sdhc_t *obj, const mtb_hal_sdhc_configurator_t *config, const mtb_hal_clock_t *clock, cy_stc_sd_host_context_t *sdhc_host_context)
	Sets up a HAL instance to use the specified hardware resource. More...
cy_rslt_t	mtb_hal_sdhc_erase (mtb_hal_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	mtb_hal_sdhc_read_async (mtb_hal_sdhc_t *obj, uint32_t address, uint8_t *data, size_t *length)
	Start SDHC asynchronous read. More...
cy_rslt_t	mtb_hal_sdhc_write_async (mtb_hal_sdhc_t *obj, uint32_t address, const uint8_t *data, size_t *length)
	Start asynchronous SDHC write. More...
bool	mtb_hal_sdhc_is_card_inserted (const mtb_hal_sdhc_t *obj)
	Checks if SD card is inserted. More...
bool	mtb_hal_sdhc_is_card_mech_write_protected (const mtb_hal_sdhc_t *obj)
	Checks if the inserted SD card is mechanically write protected. More...
cy_rslt_t	mtb_hal_sdhc_get_block_count (mtb_hal_sdhc_t *obj, uint32_t *block_count)
	Get block count of inserted SD card / eMMC. More...
cy_rslt_t	mtb_hal_sdhc_set_frequency (mtb_hal_sdhc_t *obj, uint32_t hz, bool negotiate)
	Sets the SD bus frequency (frequency on which SD card / eMMC is accessed) More...
uint32_t	mtb_hal_sdhc_get_frequency (mtb_hal_sdhc_t *obj)
	Get the actual frequency that SD bus is configured for. More...
cy_rslt_t	mtb_hal_sdhc_set_data_read_timeout (mtb_hal_sdhc_t *obj, uint32_t timeout, bool auto_reconfigure)
	Sets the maximum time to wait for data from the card. More...
cy_rslt_t	mtb_hal_sdhc_config_data_transfer (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_data_config_t *data_config)
	Initializes the SD block and DMA for a data transfer. More...
cy_rslt_t	mtb_hal_sdhc_send_cmd (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_cmd_config_t *cmd_config)
	Sends a command to the card and wait until it is sent. More...
cy_rslt_t	mtb_hal_sdhc_get_response (mtb_hal_sdhc_t *obj, uint32_t *response, bool large_response)
	Returns a response of last issued by mtb_hal_sdhc_send_cmd function command. More...
cy_rslt_t	mtb_hal_sdhc_wait_transfer_complete (mtb_hal_sdhc_t *obj)
	Wait for asynchronous data transfer to complete. More...
cy_rslt_t	mtb_hal_sdhc_set_io_voltage (mtb_hal_sdhc_t *obj, mtb_hal_sdhc_io_voltage_t io_voltage, mtb_hal_sdhc_io_volt_action_type_t io_switch_type)
	Sets the voltage level of the I/O lines. More...
mtb_hal_sdhc_io_voltage_t	mtb_hal_sdhc_get_io_voltage (mtb_hal_sdhc_t *obj)
	Returns the current voltage level of the I/O lines. More...
cy_rslt_t	mtb_hal_sdhc_set_bus_width (mtb_hal_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	mtb_hal_sdhc_get_bus_width (mtb_hal_sdhc_t *obj)
	Returns currently configured data bus width. More...
mtb_hal_sdhc_error_type_t	mtb_hal_sdhc_get_last_command_errors (mtb_hal_sdhc_t *obj)
	Returns last issued SD operation error states. More...
void	mtb_hal_sdhc_clear_errors (mtb_hal_sdhc_t *obj)
	Clears SDHC hardware error states. More...
void	mtb_hal_sdhc_software_reset (mtb_hal_sdhc_t *obj)
	Resets CMD and Data lines and corresponding circuits of SD Host. More...
cy_rslt_t	mtb_hal_sdhc_enable_card_power (mtb_hal_sdhc_t *obj, bool enable)
	Powers up / down the card based on provided parameter. More...
cy_rslt_t	mtb_hal_sdhc_process_interrupt (mtb_hal_sdhc_t *obj)
	Process interrupts related to an SDHC instance. More...

---

Data Structure Documentation

mtb_hal_sdhc_config_t

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

mtb_hal_sdhc_data_config_t

struct mtb_hal_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. Selects which auto commands are used if any.
mtb_hal_sdhc_auto_cmd_t	auto_command
bool	is_read	true = Read from the card,false = Write to the card.

mtb_hal_sdhc_cmd_config_t

struct mtb_hal_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.
mtb_hal_sdhc_cmd_response_type_t	response_type	The response type.
bool	enable_idx_check	Checks the index of the response.
mtb_hal_sdhc_cmd_type_t	command_type	The command type.
mtb_hal_sdhc_data_config_t *	data_config	Data transfer configuration, defined in mtb_hal_sdhc_data_config_t. Should be NULL if data transfer is not expected for provided command.

Enumeration Type Documentation

mtb_hal_sdhc_card_type_t

enum mtb_hal_sdhc_card_type_t

Card types.

Enumerator
MTB_HAL_SDHC_SD	Secure Digital card.
MTB_HAL_SDHC_SDIO	SD Input Output card.
MTB_HAL_SDHC_EMMC	Embedded Multimedia card.
MTB_HAL_SDHC_COMBO	Combo Card (SD + SDIO)
MTB_HAL_SDHC_UNUSABLE	Unusable card or unsupported type.
MTB_HAL_SDHC_NOT_EMMC	Not an eMMC card.

mtb_hal_sdhc_io_voltage_t

enum mtb_hal_sdhc_io_voltage_t

I/O voltage levels.

Enumerator
MTB_HAL_SDHC_IO_VOLTAGE_3_3V	I/O voltage is 3.3V.
MTB_HAL_SDHC_IO_VOLTAGE_1_8V	I/O voltage is 1.8V.

mtb_hal_sdhc_io_volt_action_type_t

enum mtb_hal_sdhc_io_volt_action_type_t

SDHC I/O voltage select principle.

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

mtb_hal_sdhc_cmd_response_type_t

enum mtb_hal_sdhc_cmd_response_type_t

SDHC response types.

Enumerator
MTB_HAL_SDHC_RESPONSE_NONE	No Response.
MTB_HAL_SDHC_RESPONSE_LEN_136	Response Length 136.
MTB_HAL_SDHC_RESPONSE_LEN_48	Response Length 48.
MTB_HAL_SDHC_RESPONSE_LEN_48B	Response Length 48. Check Busy after response.

mtb_hal_sdhc_auto_cmd_t

enum mtb_hal_sdhc_auto_cmd_t

SDHC auto command enable selection.

Enumerator
MTB_HAL_SDHC_AUTO_CMD_NONE	Auto command disable.
MTB_HAL_SDHC_AUTO_CMD_12	Auto command 12 enable.
MTB_HAL_SDHC_AUTO_CMD_23	Auto command 23 enable.
MTB_HAL_SDHC_AUTO_CMD_AUTO	Auto command Auto enable.

mtb_hal_sdhc_cmd_type_t

enum mtb_hal_sdhc_cmd_type_t

SDHC command types.

Enumerator
MTB_HAL_SDHC_CMD_NORMAL	Other commands.
MTB_HAL_SDHC_CMD_SUSPEND	CMD52 for writing "Bus Suspend" in CCCR.
MTB_HAL_SDHC_CMD_RESUME	CMD52 for writing "Function Select" in CCCR.
MTB_HAL_SDHC_CMD_ABORT	CMD12, CMD52 for writing "I/O Abort" in CCCR.

mtb_hal_sdhc_error_type_t

enum mtb_hal_sdhc_error_type_t

SDHC command error states.

Enumerator
MTB_HAL_SDHC_NO_ERR	Last operation did not cause any error status.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_SDHC_CUR_LMT_ERR	Current Limit error.
MTB_HAL_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.
MTB_HAL_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.
MTB_HAL_SDHC_TUNNING_ERR	Tuning error.
MTB_HAL_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.
MTB_HAL_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

mtb_hal_sdhc_setup()

cy_rslt_t mtb_hal_sdhc_setup	(	mtb_hal_sdhc_t *	obj,
		const mtb_hal_sdhc_configurator_t *	config,
		const mtb_hal_clock_t *	clock,
		cy_stc_sd_host_context_t *	sdhc_host_context
	)

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

[out]	obj	The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
[in]	config	The configurator-generated HAL config structure for this peripheral instance
[in]	clock	The HAL clock object that is connected to this peripheral instance
[in]	sdhc_host_context	The context for the sdhc instance allocated by the user

Returns

the status of the HAL setup

mtb_hal_sdhc_erase()

cy_rslt_t mtb_hal_sdhc_erase	(	mtb_hal_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

mtb_hal_sdhc_read_async()

cy_rslt_t mtb_hal_sdhc_read_async	(	mtb_hal_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 mtb_hal_sdhc_wait_transfer_complete function returns true.

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

mtb_hal_sdhc_write_async()

cy_rslt_t mtb_hal_sdhc_write_async	(	mtb_hal_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 mtb_hal_sdhc_wait_transfer_complete function returns true.

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

mtb_hal_sdhc_is_card_inserted()

bool mtb_hal_sdhc_is_card_inserted

(

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

mtb_hal_sdhc_is_card_mech_write_protected()

bool mtb_hal_sdhc_is_card_mech_write_protected

(

const mtb_hal_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

mtb_hal_sdhc_get_block_count()

cy_rslt_t mtb_hal_sdhc_get_block_count	(	mtb_hal_sdhc_t *	obj,
		uint32_t *	block_count
	)

Get block count of inserted SD card / eMMC.

Note

SDHC driver should be initialized 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

mtb_hal_sdhc_set_frequency()

cy_rslt_t mtb_hal_sdhc_set_frequency	(	mtb_hal_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 mtb_hal_sdhc_get_frequency function to get actual frequency value that was achieved and set.

If data timeout was configured by mtb_hal_sdhc_set_data_read_timeout, it can be automaticaly recalculated according to new SD bus frequency. For details, please refer to mtb_hal_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

mtb_hal_sdhc_get_frequency()

uint32_t mtb_hal_sdhc_get_frequency

(

mtb_hal_sdhc_t *

obj

)

Get the actual frequency that SD bus is configured for.

Parameters

[in]

obj

The SDHC object

Returns

Frequency in Hz

mtb_hal_sdhc_set_data_read_timeout()

cy_rslt_t mtb_hal_sdhc_set_data_read_timeout	(	mtb_hal_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 mtb_hal_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

mtb_hal_sdhc_config_data_transfer()

cy_rslt_t mtb_hal_sdhc_config_data_transfer	(	mtb_hal_sdhc_t *	obj,
		mtb_hal_sdhc_data_config_t *	data_config
	)

Initializes the SD block and DMA for a data transfer.

It does not start a transfer. mtb_hal_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

mtb_hal_sdhc_send_cmd()

cy_rslt_t mtb_hal_sdhc_send_cmd	(	mtb_hal_sdhc_t *	obj,
		mtb_hal_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, mtb_hal_sdhc_config_data_transfer function needs to be called prior to this one. The response of issued command can be retrieved by using mtb_hal_sdhc_get_response function.

Note

Function does not wait until data (configured with mtb_hal_sdhc_config_data_transfer) transfer complete. In order to do so, user can use the mtb_hal_sdhc_wait_transfer_complete function

Parameters

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

Returns

The status of the operation

mtb_hal_sdhc_get_response()

cy_rslt_t mtb_hal_sdhc_get_response	(	mtb_hal_sdhc_t *	obj,
		uint32_t *	response,
		bool	large_response
	)

Returns a response of last issued by mtb_hal_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 correspond to 120 and 32 bits of useful for application data respectively. So for large_response a 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

mtb_hal_sdhc_wait_transfer_complete()

cy_rslt_t mtb_hal_sdhc_wait_transfer_complete

(

mtb_hal_sdhc_t *

obj

)

Wait for asynchronous data transfer to complete.

Such data transfer can be triggered by mtb_hal_sdhc_write_async, mtb_hal_sdhc_read_async or by mtb_hal_sdhc_config_data_transfer + mtb_hal_sdhc_send_cmd functions.

Parameters

[in]

obj

The SDHC object

Returns

The status of the operation

mtb_hal_sdhc_set_io_voltage()

cy_rslt_t mtb_hal_sdhc_set_io_voltage	(	mtb_hal_sdhc_t *	obj,
		mtb_hal_sdhc_io_voltage_t	io_voltage,
		mtb_hal_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 the device datasheet and PDL documentation for 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 MTB_HAL_SDHC_IO_VOLT_ACTION_NEGOTIATE selected. card_pwr_en pin has to be assigned. Please refer to the PDL documentation for 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

mtb_hal_sdhc_get_io_voltage()

mtb_hal_sdhc_io_voltage_t mtb_hal_sdhc_get_io_voltage

(

mtb_hal_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

mtb_hal_sdhc_set_bus_width()

cy_rslt_t mtb_hal_sdhc_set_bus_width	(	mtb_hal_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

mtb_hal_sdhc_get_bus_width()

uint8_t mtb_hal_sdhc_get_bus_width

(

mtb_hal_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

mtb_hal_sdhc_get_last_command_errors()

mtb_hal_sdhc_error_type_t mtb_hal_sdhc_get_last_command_errors

(

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

Parameters

[in]

obj

The SDHC object

Returns

Errors occurred during last command

mtb_hal_sdhc_clear_errors()

void mtb_hal_sdhc_clear_errors

(

mtb_hal_sdhc_t *

obj

)

Clears SDHC hardware error states.

Error statuses are indicated by mtb_hal_sdhc_get_last_command_errors function.

Parameters

[in]

obj

The SDHC object

mtb_hal_sdhc_software_reset()

void mtb_hal_sdhc_software_reset

(

mtb_hal_sdhc_t *

obj

)

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

Parameters

[in]

obj

The SDHC object

mtb_hal_sdhc_enable_card_power()

cy_rslt_t mtb_hal_sdhc_enable_card_power	(	mtb_hal_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 the device datasheet 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

mtb_hal_sdhc_process_interrupt()

cy_rslt_t mtb_hal_sdhc_process_interrupt

(

mtb_hal_sdhc_t *

obj

)

Process interrupts related to an SDHC instance.

Parameters

obj	HAL object for which the interrupt should be processed

Returns

CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error