SDHC (SD Host Controller)

group group_hal_sdhc

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);

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);

Typedefs

typedef void (*cyhal_sdhc_event_callback_t)(void *callback_arg, cyhal_sdhc_event_t event)

Handler for SDHC interrupts.

Enums

enum cyhal_sdhc_card_type_t

cyhal_sdhc_card_type_t: Card types.

Values:

enumerator CYHAL_SDHC_SD

Secure Digital card.

enumerator CYHAL_SDHC_SDIO

SD Input Output card.

enumerator CYHAL_SDHC_EMMC

Embedded Multimedia card.

enumerator CYHAL_SDHC_COMBO

Combo Card (SD + SDIO)

enumerator CYHAL_SDHC_UNUSABLE

Unusable card or unsupported type.

enumerator CYHAL_SDHC_NOT_EMMC

Not an eMMC card.

enum cyhal_sdhc_event_t

cyhal_sdhc_event_t: SDHC interrupt triggers.

Values:

enumerator CYHAL_SDHC_CMD_COMPLETE

Command Complete.

enumerator CYHAL_SDHC_XFER_COMPLETE

Host read/write transfer is complete.

enumerator CYHAL_SDHC_BGAP_EVENT

This bit is set when both read/write transaction is stopped at the block gap.

enumerator CYHAL_SDHC_DMA_INTERRUPT

Host controller detects an SDMA Buffer Boundary during transfer.

enumerator CYHAL_SDHC_BUF_WR_READY

This bit is set if the Buffer Write Enable changes from 0 to 1.

enumerator CYHAL_SDHC_BUF_RD_READY

This bit is set if the Buffer Read Enable changes from 0 to 1.

enumerator CYHAL_SDHC_CARD_INSERTION

This bit is set if the Card Inserted in the Present State register changes from 0 to 1.

enumerator CYHAL_SDHC_CARD_REMOVAL

This bit is set if the Card Inserted in the Present State register changes from 1 to 0.

enumerator CYHAL_SDHC_INT_A
enumerator CYHAL_SDHC_INT_B
enumerator CYHAL_SDHC_INT_C
enumerator CYHAL_SDHC_RE_TUNE_EVENT

This bit is set if the Re-Tuning Request changes from 0 to 1.

enumerator CYHAL_SDHC_FX_EVENT

This status is set when R[14] of response register is set to 1.

enumerator CYHAL_SDHC_CQE_EVENT

This status is set if Command Queuing/Crypto event has occurred.

enumerator CYHAL_SDHC_ERR_INTERRUPT

If any of the bits in the Error Interrupt Status register are set.

enumerator CYHAL_SDHC_ALL_INTERRUPTS

Is used to enable/disable all interrupts.

enum cyhal_sdhc_io_voltage_t

cyhal_sdhc_io_voltage_t: I/O voltage levels.

Values:

enumerator CYHAL_SDHC_IO_VOLTAGE_3_3V

I/O voltage is 3.3V.

enumerator CYHAL_SDHC_IO_VOLTAGE_1_8V

I/O voltage is 1.8V.

enum cyhal_sdhc_io_volt_action_type_t

cyhal_sdhc_io_volt_action_type_t: SDHC I/O voltage select principle.

Values:

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.

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

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

enum cyhal_sdhc_cmd_response_type_t

cyhal_sdhc_cmd_response_type_t: SDHC response types.

Values:

enumerator CYHAL_SDHC_RESPONSE_NONE

No Response.

enumerator CYHAL_SDHC_RESPONSE_LEN_136

Response Length 136.

enumerator CYHAL_SDHC_RESPONSE_LEN_48

Response Length 48.

enumerator CYHAL_SDHC_RESPONSE_LEN_48B

Response Length 48. Check Busy after response.

enum cyhal_sdhc_auto_cmd_t

cyhal_sdhc_auto_cmd_t: SDHC auto command enable selection.

Values:

enumerator CYHAL_SDHC_AUTO_CMD_NONE

Auto command disable.

enumerator CYHAL_SDHC_AUTO_CMD_12

Auto command 12 enable.

enumerator CYHAL_SDHC_AUTO_CMD_23

Auto command 23 enable.

enumerator CYHAL_SDHC_AUTO_CMD_AUTO

Auto command Auto enable.

enum cyhal_sdhc_cmd_type_t

cyhal_sdhc_cmd_type_t: SDHC command types.

Values:

enumerator CYHAL_SDHC_CMD_NORMAL

Other commands.

enumerator CYHAL_SDHC_CMD_SUSPEND

CMD52 for writing “Bus Suspend” in CCCR.

enumerator CYHAL_SDHC_CMD_RESUME

CMD52 for writing “Function Select” in CCCR.

enumerator CYHAL_SDHC_CMD_ABORT

CMD12, CMD52 for writing “I/O Abort” in CCCR.

enum cyhal_sdhc_error_type_t

cyhal_sdhc_error_type_t: SDHC command error states.

Values:

enumerator CYHAL_SDHC_NO_ERR

Last operation did not cause any error status.

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

enumerator CYHAL_SDHC_CMD_CRC_ERR

Command CRC error.

A Command CRC Error is generated in SD/eMMC mode when:

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

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

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

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

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

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

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

enumerator CYHAL_SDHC_CUR_LMT_ERR

Current Limit error.

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

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

enumerator CYHAL_SDHC_TUNNING_ERR

Tuning error.

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

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

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)

Initialize SDHC driver and corresponding hardware.

Return

The status of the init request

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.

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

Return

The status of the card init request

Parameters
  • [inout] obj: The SDHC object

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)

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.

Return

The status of the init request

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

void cyhal_sdhc_free(cyhal_sdhc_t *obj)

Release the SDHC peripheral, not currently invoked.

It requires further resource management.

Parameters
  • [inout] obj: The SDHC object

cy_rslt_t cyhal_sdhc_read(const 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

Return

The status of the read request

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

  • [inout] length: Number of 512 byte blocks to read, updated with the number actually read

cy_rslt_t cyhal_sdhc_write(const 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

Return

The status of the write request

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

  • [inout] length: Number of 512 byte blocks to write, updated with the number actually written

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

Erases a block of data over the SDHC peripheral.

Return

The status of the erase request

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

cy_rslt_t cyhal_sdhc_read_async(const 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.

Return

The status of the read_async request

Parameters
  • [in] obj: The SDHC object that holds the transfer information

  • [in] address: The address to read data from

  • [out] data: The receive buffer

  • [inout] length: Number of 512 byte blocks to read, updated with the number actually read

cy_rslt_t cyhal_sdhc_write_async(const 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.

Return

The status of the write_async request

Parameters
  • [in] obj: The SDHC object that holds the transfer information

  • [in] address: The address to write data to

  • [in] data: The transmit buffer

  • [inout] length: The number of 512 byte blocks to write, updated with the number actually written

bool cyhal_sdhc_is_busy(const cyhal_sdhc_t *obj)

Checks if the specified SDHC peripheral is in use.

Return

Indication of whether the SDHC is still transmitting

Parameters
  • [in] obj: The SDHC peripheral to check

cy_rslt_t cyhal_sdhc_abort_async(const cyhal_sdhc_t *obj)

Abort an SDHC transfer.

Return

The status of the abort_async request

Parameters
  • [in] obj: The SDHC peripheral to stop

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

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

bool cyhal_sdhc_is_card_inserted(const cyhal_sdhc_t *obj)

Checks if SD card is inserted.

Return

Indication of whether the card is inserted.

Parameters
  • [in] obj: The SDHC peripheral to check

bool cyhal_sdhc_is_card_mech_write_protected(const cyhal_sdhc_t *obj)

Checks if the inserted SD card is mechanically write protected.

Return

Indication of whether the inserted SD card is mechanically write protected

Parameters
  • [in] obj: The SDHC peripheral to check

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.

Return

The status of the operation

Parameters
  • [in] obj: The SDHC object

  • [in] block_count: Pointer to variable where block count will be stored

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.

note

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.

Return

The status of the operation

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.

uint32_t cyhal_sdhc_get_frequency(cyhal_sdhc_t *obj)

Get the actual frequency that SD bus is configured for.

Return

Frequency in Hz

Parameters
  • [in] obj: The SDHC object

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.

Return

The status of the operation

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

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.

Return

The status of the operation

Parameters
  • [in] obj: The SDHC object

  • [in] data_config: Data transfer configuration

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:

Return

The status of the operation

Parameters
  • [in] obj: The SDHC object

  • [in] cmd_config: Command configuration

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.

Return

The status of the operation

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.

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.

Return

The status of the operation

Parameters
  • [in] obj: The SDHC object

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.

note

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.

Return

The status of the operation

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

cyhal_sdhc_io_voltage_t cyhal_sdhc_get_io_voltage(cyhal_sdhc_t *obj)

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

Return

Current I/O voltage setting value

Parameters
  • [in] obj: The SDHC object

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.

Return

The status of the operation

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.

uint8_t cyhal_sdhc_get_bus_width(cyhal_sdhc_t *obj)

Returns currently configured data bus width.

Return

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

Parameters
  • [in] obj: The SDHC object

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.

Return

Errors occurred during last command

Parameters
  • [in] obj: The SDHC object

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

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

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.

Return

The status of the operation

Parameters
  • [in] obj: The SDHC peripheral to configure

  • [in] enable: Card is powered if true, not powered if false.

struct cyhal_sdhc_config_t
#include <cyhal_sdhc.h>

Defines configuration options for the SDHC block.

Public Members

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.

struct cyhal_sdhc_data_config_t
#include <cyhal_sdhc.h>

Defines data configuration.

Public Members

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.

struct cyhal_sdhc_cmd_config_t
#include <cyhal_sdhc.h>

Defines command configuration for cyhal_sdhc_send_cmd function.

Public Members

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.