General Description

High level interface to the Secure Digital Input Output (SDIO).

The SDIO protocol is an extension of the SD interface for general I/O functions. Refer to the SD Specifications Part 1 SDIO Specifications Version 4.10 for more information on the SDIO protocol and specifications.

The host functionality of this driver allows commands to be sent over the SDIO bus; the supported commands can be found in cyhal_sdio_host_command_t. Bulk data transfer is supported via cyhal_sdio_bulk_transfer().

The device functionality of this driver allows configuring the SDIO device for receiving commands from the host. Data can be sent and received from/to application buffers.

Features

Supports 4-bit interface
Supports Ultra High Speed (UHS-I) mode
Supports Default Speed (DS), High Speed (HS), SDR12, SDR25 and SDR50 speed modes
Supports SDIO card interrupts in both 1-bit SD and 4-bit SD modes
Supports Standard capacity (SDSC), High capacity (SDHC) and Extended capacity (SDXC) memory

Quick Start

cyhal_sdio_init initializes the SDIO peripheral and passes a pointer to the SDIO block through the obj object of type cyhal_sdio_t.

Code Snippets

Host Code Snippets

Snippet1: Simple SDIO Host Initialization example

The following snippet shows how to initialize the SDIO host interface with a pre-defined configuration

 
    cy_rslt_t    rslt;
    cyhal_sdio_t sdio_object;
 
    #define BLOCK_SIZE     (512)
    #define SDIO_FREQ_HF   (100000000UL)
 
    cyhal_sdio_cfg_t my_sdio_cfg =
    {
        .block_size      = BLOCK_SIZE,
        .frequencyhal_hz = SDIO_FREQ_HF,
        .is_sdio_dev     = false
    };
 
    rslt = cyhal_sdio_init(&sdio_object,
                           SDIO_CMD_PIN,
                           SDIO_CLK_PIN,
                           SDIO_DATA0_PIN,
                           SDIO_DATA1_PIN,
                           SDIO_DATA2_PIN,
                           SDIO_DATA3_PIN);
 
    rslt = cyhal_sdio_configure(&sdio_object, &my_sdio_cfg);
 

Snippet2: Configure Host Interrupt

The following snippet shows how to configure an interrupt to handle host specific events. Refer cyhal_sdio_event_t for different types of events.

 
// Event handler callback function
void sdio_host_event_handler(void* handler_arg, cyhal_sdio_event_t event)
{
    CY_UNUSED_PARAMETER(handler_arg);
    CY_UNUSED_PARAMETER(event);
 
    switch (event)
    {
        case CYHAL_SDIO_CARD_INSERTION:
        {
            // Triggered when card insertion is detected in present state
            // Insert application code to handle events
            break;
        }
 
        case CYHAL_SDIO_CMD_COMPLETE:
        {
            // Triggered when command transfer is complete
            // Insert application code to handle events
            break;
        }
 
        case CYHAL_SDIO_XFER_COMPLETE:
        {
            // Triggered when host read/write transfer is complete
            // Insert application code to handle events
            break;
        }
 
        default:
        {
            // Anything for other commands
            break;
        }
    }
}
 
 
void snippet_cyhal_host_sdio_interrupt_init()
{
    #define INTERRUPT_PRIORITY (3u)
 
    // Register the event callback
    cyhal_sdio_register_callback(&sdio_obj, &sdio_host_event_handler, NULL);
 
    // Enable events that should trigger the callback
    cyhal_sdio_enable_event(&sdio_obj, CYHAL_SDIO_ALL_INTERRUPTS, INTERRUPT_PRIORITY, true);
}
 
 

Snippet3: Sending Host Commands

The following snippet shows how to send a particular command. Some steps of the card initialization have been provided for reference. Refer to cyhal_sdio_host_command_t for different commands.

 
    cy_rslt_t    rslt;
    uint32_t     response;
    bool         f8Flag = false; // The CMD8 valid flag.
 
    #define MY_SDIO_CMD_NO_ARG               (0u)
    #define MY_SDIO_CMD8                     ((cyhal_sdio_command_t)8u)
    #define MY_SDIO_CMD8_VHS_27_36           (0x100UL) // CMD8 voltage supplied 2.7-3.6 V.
    #define MY_SDIO_CMD8_PATTERN_MASK        (0xFFUL)
    #define MY_SDIO_CMD8_CHECK_PATTERN       (0xAAUL)
 
    // Start the card initialization process
 
    // Reset Card (CMD0).
    rslt = cyhal_sdio_send_cmd(&sdio_obj, CYHAL_SDIO_XFER_TYPE_WRITE, CYHAL_SDIO_CMD_GO_IDLE_STATE,
                               MY_SDIO_CMD_NO_ARG, &response);
 
    // Voltage check (CMD8).
    rslt = cyhal_sdio_send_cmd(&sdio_obj, CYHAL_SDIO_XFER_TYPE_WRITE, MY_SDIO_CMD8, MY_SDIO_CMD8_VHS_27_36 |
                               MY_SDIO_CMD8_CHECK_PATTERN,
                               &response);
 
    // Check the pattern.
    if (MY_SDIO_CMD8_CHECK_PATTERN == (response & MY_SDIO_CMD8_PATTERN_MASK))
    {
        // The pattern is valid.
        f8Flag = true;
    }
    else
    {
        // SDIO Card is unusable
    }
 
    if (f8Flag)
    {
        // Add further initialization commands based on SDIO card
    }
 

Snippet4: Host Bulk Data Transfer

The following snippet shows how to start a bulk data transfer.

    #define DATA_LENGTH                      (5u)
    #define MY_SDIO_CMD_NO_ARG               (0u)
 
    cy_rslt_t rslt;
    uint32_t  data[DATA_LENGTH] = { '1', '2', '3', '4', '5' };
    uint32_t  response;
 
    // Begin bulk data transfer
    rslt = cyhal_sdio_bulk_transfer(&sdio_obj, CYHAL_SDIO_XFER_TYPE_WRITE, MY_SDIO_CMD_NO_ARG, data,
                                    DATA_LENGTH,
                                    &response);
 

Snippet5: Host Async Data Transfer

The following snippet shows how to start an async data transfer.

void sdio_host_async_interrupt_handler(void* handler_arg, cyhal_sdio_event_t event)
{
    if ((handler_arg != NULL) && (event == CYHAL_SDIO_XFER_COMPLETE))
    {
        // Triggered when host read/write async transfer is complete
        // Insert application code to handle events
    }
}
 
 
void snippet_cyhal_host_sdio_async_transfer()
{
    #define DATA_LENGTH                      (5u)
    #define MY_SDIO_CMD_NO_ARG               (0u)
    #define INTERRUPT_PRIORITY               (3u)
 
    uint32_t data[DATA_LENGTH] = { '1', '2', '3', '4', '5' };
    uint32_t handler_args      = 0;
 
    // Register the event callback
    cyhal_sdio_register_callback(&sdio_obj, &sdio_host_async_interrupt_handler,
                                 (void*)&handler_args);
 
    // Enable events CYHAL_SDIO_CMD_COMPLETE and CYHAL_SDIO_XFER_COMPLETE events.
    // Event CYHAL_SDIO_XFER_COMPLETE is triggered once
    // async transfer is complete. Handle event in the event handler.
    cyhal_sdio_enable_event(&sdio_obj,
                            (cyhal_sdio_event_t)(CYHAL_SDIO_CMD_COMPLETE |
                                                 CYHAL_SDIO_XFER_COMPLETE),
                            INTERRUPT_PRIORITY,
                            true);
 
    // Begin async data transfer
    cyhal_sdio_transfer_async(&sdio_obj, CYHAL_SDIO_XFER_TYPE_WRITE, MY_SDIO_CMD_NO_ARG, data,
                              DATA_LENGTH);
 
    // Wait for transfer to finish
    while (cyhal_sdio_is_busy(&sdio_obj))
    {
        // Halt here until condition is false
    }
}
 
 

Device Code Snippets

Snippet1: Simple SDIO Device Initialization example

The following snippet shows how to initialize the SDIO device interface with a pre-defined configuration

 
    cy_rslt_t    rslt;
    cyhal_sdio_t sdio_object;
 
    #define BLOCK_SIZE         (512)
    #define SDIO_FREQ          (50000000UL)
 
    cyhal_sdio_cfg_t my_sdio_cfg =
    {
        .block_size      = BLOCK_SIZE,
        .frequencyhal_hz = SDIO_FREQ,
        .is_sdio_dev     = true
    };
 
    rslt = cyhal_sdio_init(&sdio_object,
                           SDIO_CMD_PIN,
                           SDIO_CLK_PIN,
                           SDIO_DATA0_PIN,
                           SDIO_DATA1_PIN,
                           SDIO_DATA2_PIN,
                           SDIO_DATA3_PIN);
 
    rslt = cyhal_sdio_configure(&sdio_object, &my_sdio_cfg);
 

Snippet2: Configure Device Interrupt

The following snippet shows how to configure an interrupt to handle device specific events. Refer cyhal_sdio_event_t for different types of events.

 
// Event handler callback function
void sdio_dev_event_handler(void* handler_arg, cyhal_sdio_event_t event)
{
    CY_UNUSED_PARAMETER(handler_arg);
    CY_UNUSED_PARAMETER(event);
 
    switch (event)
    {
        case CYHAL_SDIO_DEV_HOST_INFO:
        {
            // Triggered on a mailbox or an F2 enable event
            // Insert application code to handle events
            break;
        }
 
        case CYHAL_SDIO_DEV_READ_COMPLETE:
        {
            // Triggered on a read completion event
            // Insert application code to handle events
            break;
        }
 
        case CYHAL_SDIO_DEV_READ_ERROR:
        {
            // Triggered on a read error event
            // Insert application code to handle events
            break;
        }
 
        default:
        {
            // Anything for other commands
            break;
        }
    }
}
 
 
void snippet_cyhal_dev_sdio_interrupt_init()
{
    #define INTERRUPT_PRIORITY (3u)
 
    // Register the event callback
    cyhal_sdio_register_callback(&sdio_obj, &sdio_dev_event_handler, NULL);
 
    // Enable events that should trigger the callback
    cyhal_sdio_enable_event(&sdio_obj, CYHAL_SDIO_ALL_INTERRUPTS, INTERRUPT_PRIORITY, true);
}
 
 

Snippet3: Device Async Read

The following snippet shows how to start an async read.

void sdio_dev_async_interrupt_handler(void* handler_arg, cyhal_sdio_event_t event)
{
    if ((handler_arg != NULL) && (event == CYHAL_SDIO_DEV_READ_COMPLETE))
    {
        // Triggered when device async read is complete
        // Insert application code to handle events
    }
}
 
 
void snippet_cyhal_sdio_dev_async_read()
{
    #define DATA_LENGTH                      (5u)
    #define INTERRUPT_PRIORITY               (3u)
 
    uint8_t data[DATA_LENGTH] = { '1', '2', '3', '4', '5' };
    uint32_t handler_args      = 0;
 
    // Register the event callback
    cyhal_sdio_register_callback(&sdio_obj, &sdio_dev_async_interrupt_handler,
                                 (void*)&handler_args);
 
    // Enable events CYHAL_SDIO_DEV_READ_COMPLETE and CYHAL_SDIO_DEV_READ_ERROR events.
    // Event CYHAL_SDIO_DEV_READ_COMPLETE is triggered once
    // async read is complete. Handle event in the event handler.
    cyhal_sdio_enable_event(&sdio_obj,
                            (cyhal_sdio_event_t)(CYHAL_SDIO_DEV_READ_COMPLETE |
                                                 CYHAL_SDIO_DEV_READ_ERROR),
                            INTERRUPT_PRIORITY,
                            true);
 
    // Begin async read
    cyhal_sdio_dev_read_async(&sdio_obj, &data[0], DATA_LENGTH);
 
    // Wait for read to finish
    while (cyhal_sdio_is_busy(&sdio_obj))
    {
        // Halt here until condition is false
    }
}
 
 

Snippet4: Device Mailbox Write

The following snippet shows how to write to the mailbox.

void snippet_cyhal_sdio_dev_write_mailbox()
{
    #define HOST_MAILBOX_BITS                (0x5u)
    #define HOST_MAILBOX_DATA                (0x3u)
 
    uint32_t data = HOST_MAILBOX_DATA;
 
    cy_rslt_t status = cyhal_sdio_dev_mailbox_write(&sdio_obj, HOST_MAILBOX_BITS, &data);
 
    if (status != CY_RSLT_SUCCESS)
    {
        // Handle error
    }
}
 
 

API Reference
	SDIO HAL Results
	SDIO specific return codes.

Data Structures
struct	cyhal_sdio_cfg_t
	SDIO initial configuration. More...

Macros
#define	cyhal_sdio_send_cmd cyhal_sdio_host_send_cmd
	Deprecated. More...

#define	cyhal_sdio_bulk_transfer cyhal_sdio_host_bulk_transfer
	Deprecated. More...

#define	cyhal_sdio_transfer_async cyhal_sdio_host_transfer_async
	Deprecated. More...

#define	cyhal_sdio_set_io_voltage cyhal_sdio_host_set_io_voltage
	Deprecated. More...

Typedefs
typedef void(*	cyhal_sdio_event_callback_t) (void *callback_arg, cyhal_sdio_event_t event)
	Callback for SDIO events.

Enumerations
enum	cyhal_sdio_event_t { CYHAL_SDIO_CMD_COMPLETE = 0x00001 , CYHAL_SDIO_XFER_COMPLETE = 0x00002 , CYHAL_SDIO_BGAP_EVENT = 0x00004 , CYHAL_SDIO_DMA_INTERRUPT = 0x00008 , CYHAL_SDIO_BUF_WR_READY = 0x00010 , CYHAL_SDIO_BUF_RD_READY = 0x00020 , CYHAL_SDIO_CARD_INSERTION = 0x00040 , CYHAL_SDIO_CARD_REMOVAL = 0x00080 , CYHAL_SDIO_CARD_INTERRUPT = 0x00100 , CYHAL_SDIO_INT_A = 0x00200 , CYHAL_SDIO_INT_B = 0x00400 , CYHAL_SDIO_INT_C = 0x00800 , CYHAL_SDIO_RE_TUNE_EVENT = 0x01000 , CYHAL_SDIO_FX_EVENT = 0x02000 , CYHAL_SDIO_CQE_EVENT = 0x04000 , CYHAL_SDIO_ERR_INTERRUPT = 0x08000 , CYHAL_SDIO_GOING_DOWN = 0x10000 , CYHAL_SDIO_COMING_UP = 0x20000 , CYHAL_SDIO_ALL_INTERRUPTS = 0x0E1FF }
	Types of events that could be asserted by SDIO. More...

enum	cyhal_sdio_host_command_t { CYHAL_SDIO_CMD_GO_IDLE_STATE = 0 , CYHAL_SDIO_CMD_SEND_RELATIVE_ADDR = 3 , CYHAL_SDIO_CMD_IO_SEND_OP_COND = 5 , CYHAL_SDIO_CMD_SELECT_CARD = 7 , CYHAL_SDIO_CMD_VOLTAGE_SWITCH = 11 , CYHAL_SDIO_CMD_GO_INACTIVE_STATE = 15 , CYHAL_SDIO_CMD_IO_RW_DIRECT = 52 , CYHAL_SDIO_CMD_IO_RW_EXTENDED = 53 }
	Commands that can be issued. More...

enum	cyhal_sdio_host_transfer_type_t { CYHAL_SDIO_XFER_TYPE_READ , CYHAL_SDIO_XFER_TYPE_WRITE }
	Types of transfer that can be performed. More...

enum	cyhal_sdio_host_io_voltage_t { CYHAL_SDIO_IO_VOLTAGE_3_3V = 0U , CYHAL_SDIO_IO_VOLTAGE_1_8V = 1U }
	I/O voltage levels. More...

enum	cyhal_sdio_host_io_volt_action_type_t { CYHAL_SDIO_IO_VOLT_ACTION_SWITCH_SEQ_ONLY = 1U , CYHAL_SDIO_IO_VOLT_ACTION_NONE = 2U }
	SDIO I/O voltage select principle. More...

Functions
cy_rslt_t	cyhal_sdio_init (cyhal_sdio_t *obj, cyhal_gpio_t cmd, cyhal_gpio_t clk, cyhal_gpio_t data0, cyhal_gpio_t data1, cyhal_gpio_t data2, cyhal_gpio_t data3)
	Initialize the SDIO peripheral. More...

void	cyhal_sdio_free (cyhal_sdio_t *obj)
	Release the SDIO block. More...

cy_rslt_t	cyhal_sdio_configure (cyhal_sdio_t obj, const cyhal_sdio_cfg_t config)
	Configure the SDIO block. More...

bool	cyhal_sdio_is_busy (const cyhal_sdio_t *obj)
	Check if the specified SDIO is in use. More...

cy_rslt_t	cyhal_sdio_abort_async (cyhal_sdio_t *obj)
	Abort an SDIO transfer. More...

void	cyhal_sdio_register_callback (cyhal_sdio_t obj, cyhal_sdio_event_callback_t callback, void callback_arg)
	Register an SDIO event callback handler. More...

void	cyhal_sdio_enable_event (cyhal_sdio_t *obj, cyhal_sdio_event_t event, uint8_t intr_priority, bool enable)
	Configure the callback event. More...

cy_rslt_t	cyhal_sdio_init_cfg (cyhal_sdio_t obj, const cyhal_sdio_configurator_t cfg)
	Initialize the SDIO peripheral using a configurator generated configuration struct. More...

cy_rslt_t	cyhal_sdio_host_send_cmd (cyhal_sdio_t obj, cyhal_sdio_host_transfer_type_t direction, cyhal_sdio_host_command_t command, uint32_t argument, uint32_t response)
	Send command to the SDIO device. More...

cy_rslt_t	cyhal_sdio_host_bulk_transfer (cyhal_sdio_t obj, cyhal_sdio_host_transfer_type_t direction, uint32_t argument, const uint32_t data, uint16_t length, uint32_t *response)
	Perform a bulk data transfer. More...

cy_rslt_t	cyhal_sdio_host_transfer_async (cyhal_sdio_t obj, cyhal_sdio_host_transfer_type_t direction, uint32_t argument, const uint32_t data, uint16_t length)
	Perform a bulk asynchronous data transfer. More...

cy_rslt_t	cyhal_sdio_host_set_io_voltage (cyhal_sdio_t *obj, cyhal_gpio_t io_volt_sel, cyhal_sdio_host_io_voltage_t io_voltage, cyhal_sdio_host_io_volt_action_type_t io_switch_type)
	Set the voltage level of the I/O line. More...

Data Structure Documentation

◆ cyhal_sdio_cfg_t

struct cyhal_sdio_cfg_t

Data Fields
uint32_t	frequencyhal_hz	Clock frequency in hertz (target SDIO frequency for device mode)
uint16_t	block_size	Block size (max block size for device mode)
bool	is_sdio_dev	0 if SDIO host, 1 if SDIO device

Macro Definition Documentation

◆ cyhal_sdio_send_cmd

#define cyhal_sdio_send_cmd cyhal_sdio_host_send_cmd

Deprecated.

Send command to the SDIO device

See cyhal_sdio_host_command_t for list of available commands. This will block until the command is completed.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	command	The command to send to the SDIO device
[in]	argument	The argument to the command
[out]	response	The response from the SDIO device

Returns: The status of the command transfer.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet3: Sending Host Commands for more information.

◆ cyhal_sdio_bulk_transfer

#define cyhal_sdio_bulk_transfer cyhal_sdio_host_bulk_transfer

Deprecated.

Perform a bulk data transfer

Sends CYHAL_SDIO_CMD_IO_RW_EXTENDED command (CMD=53) which allows writing and reading of a large number of I/O registers with a single command. This will block until the transfer is completed.

If D-cache is enabled and data Cache line is 32 bytes, the user needs to make sure that the data pointer passed to the cyhal_sdio_bulk_transfer function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	argument	The argument to the command
[in]	data	The data to send to the SDIO device. A bulk transfer is done in block size (default: 64 bytes) chunks for better performance. Therefore, the size of the data buffer passed into this function must be at least `length` bytes and a multiple of the block size. For example, when requesting to read 100 bytes of data with a block size 64 bytes, the data buffer needs to be at least 128 bytes. The first 100 bytes of data in the buffer will be the requested data.
[in]	length	The number of bytes to send
[out]	response	The response from the SDIO device

Returns: The status of the bulk transfer operation.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet4: Host Bulk Data Transfer for more information.

◆ cyhal_sdio_transfer_async

#define cyhal_sdio_transfer_async cyhal_sdio_host_transfer_async

Deprecated.

Perform a bulk asynchronous data transfer

Transfer by issuing CYHAL_SDIO_CMD_IO_RW_EXTENDED command(CMD=53) to the SDIO block. After exiting this function, CYHAL_SDIO_CMD_COMPLETE and CYHAL_SDIO_XFER_COMPLETE events are not asserted.

The CYHAL_SDIO_CMD_COMPLETE and CYHAL_SDIO_XFER_COMPLETE events are enabled after the asynchronous transfer completes and in the condition they were enabled in before the transfer operation started. Handle these events in the interrupt callback.

When the transfer is complete, the CYHAL_SDIO_XFER_COMPLETE event will be raised. See cyhal_sdio_register_callback and cyhal_sdio_enable_event.

If D-cache is enabled and data Cache line is 32 bytes, the user needs to make sure that the data pointer passed to the cyhal_sdio_transfer_async function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	argument	The argument to the command
[in]	data	The data to send to the SDIO device
[in]	length	The number of bytes to send

Returns: The status of the async tranfer operation.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet5: Host Async Data Transfer for more information.

◆ cyhal_sdio_set_io_voltage

#define cyhal_sdio_set_io_voltage cyhal_sdio_host_set_io_voltage

Deprecated.

Set the voltage level of the I/O line

This function changes the logic level on the io_volt_sel pin. 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.

Parameters

[in]	obj	The SDIO host object
[in]	io_volt_sel	The pin connected to the io_volt_sel signal (This pin can be NC).
[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

Enumeration Type Documentation

◆ cyhal_sdio_event_t

enum cyhal_sdio_event_t

Types of events that could be asserted by SDIO.

Enumerator
CYHAL_SDIO_CMD_COMPLETE	Command Complete.
CYHAL_SDIO_XFER_COMPLETE	Host read/write transfer is complete.
CYHAL_SDIO_BGAP_EVENT	Set when both read/write transaction is stopped.
CYHAL_SDIO_DMA_INTERRUPT	Host controller detects an SDMA Buffer Boundary during transfer.
CYHAL_SDIO_BUF_WR_READY	Set if the Buffer Write Enable changes from 0 to 1.
CYHAL_SDIO_BUF_RD_READY	Set if the Buffer Read Enable changes from 0 to 1.
CYHAL_SDIO_CARD_INSERTION	Set if the Card Inserted in the Present State.
CYHAL_SDIO_CARD_REMOVAL	Set if the Card Inserted in the Present State.
CYHAL_SDIO_CARD_INTERRUPT	Synchronized value of the DAT[1] interrupt input for SD mode.
CYHAL_SDIO_INT_A	Reserved: set to 0.
CYHAL_SDIO_INT_B	Reserved: set to 0.
CYHAL_SDIO_INT_C	Reserved: set to 0.
CYHAL_SDIO_RE_TUNE_EVENT	Reserved: set to 0.
CYHAL_SDIO_FX_EVENT	Set when R[14] of response register is set to 1.
CYHAL_SDIO_CQE_EVENT	Set if Command Queuing/Crypto event has occurred.
CYHAL_SDIO_ERR_INTERRUPT	Set if any of the bits in the Error Interrupt Status register are set.
CYHAL_SDIO_GOING_DOWN	The interface is going away (eg: powering down for some period of time)
CYHAL_SDIO_COMING_UP	The interface is back up (eg: came back from a low power state)
CYHAL_SDIO_ALL_INTERRUPTS	Used to enable/disable all interrupts events.

◆ cyhal_sdio_host_command_t

enum cyhal_sdio_host_command_t

Commands that can be issued.

Enumerator
CYHAL_SDIO_CMD_GO_IDLE_STATE	Go to idle state.
CYHAL_SDIO_CMD_SEND_RELATIVE_ADDR	Send a relative address.
CYHAL_SDIO_CMD_IO_SEND_OP_COND	Send an OP IO.
CYHAL_SDIO_CMD_SELECT_CARD	Send a card select.
CYHAL_SDIO_CMD_VOLTAGE_SWITCH	Voltage switch.
CYHAL_SDIO_CMD_GO_INACTIVE_STATE	Go to inactive state.
CYHAL_SDIO_CMD_IO_RW_DIRECT	Perform a direct read/write.
CYHAL_SDIO_CMD_IO_RW_EXTENDED	Perform an extended read/write.

◆ cyhal_sdio_host_transfer_type_t

enum cyhal_sdio_host_transfer_type_t

Types of transfer that can be performed.

Enumerator
CYHAL_SDIO_XFER_TYPE_READ	Read from the card.
CYHAL_SDIO_XFER_TYPE_WRITE	Write to the card.

◆ cyhal_sdio_host_io_voltage_t

enum cyhal_sdio_host_io_voltage_t

I/O voltage levels.

Enumerator
CYHAL_SDIO_IO_VOLTAGE_3_3V	I/O voltage is 3.3V.
CYHAL_SDIO_IO_VOLTAGE_1_8V	I/O voltage is 1.8V.

◆ cyhal_sdio_host_io_volt_action_type_t

enum cyhal_sdio_host_io_volt_action_type_t

SDIO I/O voltage select principle.

Enumerator
CYHAL_SDIO_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_SDIO_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.

Function Documentation

◆ cyhal_sdio_init()

cy_rslt_t cyhal_sdio_init	(	cyhal_sdio_t *	obj,
		cyhal_gpio_t	cmd,
		cyhal_gpio_t	clk,
		cyhal_gpio_t	data0,
		cyhal_gpio_t	data1,
		cyhal_gpio_t	data2,
		cyhal_gpio_t	data3
	)

Initialize the SDIO peripheral.

Parameters

[out]	obj	Pointer to an SDIO object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	cmd	The pin for the command signal
[in]	clk	The pin for the clk signal
[in]	data0	The pin for the data0 signal
[in]	data1	The pin for the data1 signal
[in]	data2	The pin for the data2 signal
[in]	data3	The pin for the data3 signal

Returns: The status of the init request

Returns CY_RSLT_SUCCESS on successful operation. Refer to Snippet1: Simple SDIO Host Initialization example and Snippet1: Simple SDIO Device Initialization example for more information.

◆ cyhal_sdio_free()

void cyhal_sdio_free ( cyhal_sdio_t * obj )

Release the SDIO block.

Return the peripheral, pins and clock owned by the SDIO object to its reset state

Parameters

[in,out] obj The SDIO object to deinitialize

◆ cyhal_sdio_configure()

cy_rslt_t cyhal_sdio_configure	(	cyhal_sdio_t *	obj,
		const cyhal_sdio_cfg_t *	config
	)

Configure the SDIO block.

SDIO is either a host or a device type. This function allows specifying the features for either type. Refer to cyhal_sdio_cfg_t for more information.

Parameters

[in,out]	obj	The SDIO object
[in]	config	The SDIO configuration to apply

Returns: The status of the configure request.

Returns CY_RSLT_SUCCESS on successful operation.

◆ cyhal_sdio_is_busy()

bool cyhal_sdio_is_busy ( const cyhal_sdio_t * obj )

Check if the specified SDIO is in use.

Parameters

[in] obj The SDIO peripheral to check

Returns: true if SDIO is in use. false, otherwise.

◆ cyhal_sdio_abort_async()

cy_rslt_t cyhal_sdio_abort_async ( cyhal_sdio_t * obj )

Abort an SDIO transfer.

Parameters

[in] obj The SDIO peripheral to stop

Returns: The status of the abort_async request.

Returns CY_RSLT_SUCCESS on successful operation.

◆ cyhal_sdio_register_callback()

void cyhal_sdio_register_callback	(	cyhal_sdio_t *	obj,
		cyhal_sdio_event_callback_t	callback,
		void *	callback_arg
	)

Register an SDIO event callback handler.

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

Parameters

[in]	obj	The SDIO object
[in]	callback	The callback function which will be invoked when the event triggers
[in]	callback_arg	Generic argument that will be provided to the callback when executed

Refer to Snippet2: Configure Host Interrupt and Snippet2: Configure Device Interrupt for usage information.

◆ cyhal_sdio_enable_event()

void cyhal_sdio_enable_event	(	cyhal_sdio_t *	obj,
		cyhal_sdio_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure the callback event.

Callbacks will be triggered for the specified SDIO events. Refer to cyhal_sdio_event_t for the list of supported events.

Parameters

[in]	obj	The SDIO object
[in]	event	The SDIO event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	Set to true to enable events, or false to disable them

Refer to Snippet2: Configure Host Interrupt and Snippet2: Configure Device Interrupt for usage information.

◆ cyhal_sdio_init_cfg()

cy_rslt_t cyhal_sdio_init_cfg	(	cyhal_sdio_t *	obj,
		const cyhal_sdio_configurator_t *	cfg
	)

Initialize the SDIO peripheral using a configurator generated configuration struct.

Parameters

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

Returns: The status of the operation

◆ cyhal_sdio_host_send_cmd()

cy_rslt_t cyhal_sdio_host_send_cmd	(	cyhal_sdio_t *	obj,
		cyhal_sdio_host_transfer_type_t	direction,
		cyhal_sdio_host_command_t	command,
		uint32_t	argument,
		uint32_t *	response
	)

Send command to the SDIO device.

See cyhal_sdio_host_command_t for list of available commands. This will block until the command is completed.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	command	The command to send to the SDIO device
[in]	argument	The argument to the command
[out]	response	The response from the SDIO device

Returns: The status of the command transfer.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet3: Sending Host Commands for more information.

◆ cyhal_sdio_host_bulk_transfer()

cy_rslt_t cyhal_sdio_host_bulk_transfer	(	cyhal_sdio_t *	obj,
		cyhal_sdio_host_transfer_type_t	direction,
		uint32_t	argument,
		const uint32_t *	data,
		uint16_t	length,
		uint32_t *	response
	)

Perform a bulk data transfer.

Sends CYHAL_SDIO_CMD_IO_RW_EXTENDED command (CMD=53) which allows writing and reading of a large number of I/O registers with a single command. This will block until the transfer is completed.

If D-cache is enabled and data Cache line is 32 bytes, the user needs to make sure that the data pointer passed to the cyhal_sdio_host_bulk_transfer function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	argument	The argument to the command
[in]	data	The data to send to the SDIO device. A bulk transfer is done in block size (default: 64 bytes) chunks for better performance. Therefore, the size of the data buffer passed into this function must be at least `length` bytes and a multiple of the block size. For example, when requesting to read 100 bytes of data with a block size 64 bytes, the data buffer needs to be at least 128 bytes. The first 100 bytes of data in the buffer will be the requested data.
[in]	length	The number of bytes to send
[out]	response	The response from the SDIO device

Returns: The status of the bulk transfer operation.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet4: Host Bulk Data Transfer for more information.

◆ cyhal_sdio_host_transfer_async()

cy_rslt_t cyhal_sdio_host_transfer_async	(	cyhal_sdio_t *	obj,
		cyhal_sdio_host_transfer_type_t	direction,
		uint32_t	argument,
		const uint32_t *	data,
		uint16_t	length
	)

Perform a bulk asynchronous data transfer.

Transfer by issuing CYHAL_SDIO_CMD_IO_RW_EXTENDED command(CMD=53) to the SDIO block. After exiting this function, CYHAL_SDIO_CMD_COMPLETE and CYHAL_SDIO_XFER_COMPLETE events are not asserted.

The CYHAL_SDIO_CMD_COMPLETE and CYHAL_SDIO_XFER_COMPLETE events are enabled after the asynchronous transfer completes and in the condition they were enabled in before the transfer operation started. Handle these events in the interrupt callback.

When the transfer is complete, the CYHAL_SDIO_XFER_COMPLETE event will be raised. See cyhal_sdio_register_callback and cyhal_sdio_enable_event.

If D-cache is enabled and data Cache line is 32 bytes, the user needs to make sure that the data pointer passed to the cyhal_sdio_host_transfer_async function points to a 32 byte aligned array of words that contains the buffer data. The size of buffer data must be a multiple of 32 bytes to ensure cache coherency. CY_ALIGN(__SCB_DCACHE_LINE_SIZE) macro can be used for 32 byte alignment.

Refer to DCACHE_Management for more information.

Parameters

[in,out]	obj	The SDIO host object
[in]	direction	The direction of transfer (read/write)
[in]	argument	The argument to the command
[in]	data	The data to send to the SDIO device
[in]	length	The number of bytes to send

Returns: The status of the async tranfer operation.

Returns CY_RSLT_SUCCESS on successful operation. Refer Snippet5: Host Async Data Transfer for more information.

◆ cyhal_sdio_host_set_io_voltage()

cy_rslt_t cyhal_sdio_host_set_io_voltage	(	cyhal_sdio_t *	obj,
		cyhal_gpio_t	io_volt_sel,
		cyhal_sdio_host_io_voltage_t	io_voltage,
		cyhal_sdio_host_io_volt_action_type_t	io_switch_type
	)

Set the voltage level of the I/O line.

This function changes the logic level on the io_volt_sel pin. 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.

Parameters

[in]	obj	The SDIO host object
[in]	io_volt_sel	The pin connected to the io_volt_sel signal (This pin can be NC).
[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

General Description

Features

Quick Start

Code Snippets

Host Code Snippets

Snippet1: Simple SDIO Host Initialization example

Snippet2: Configure Host Interrupt

Snippet3: Sending Host Commands

Snippet4: Host Bulk Data Transfer

Snippet5: Host Async Data Transfer

Device Code Snippets

Snippet1: Simple SDIO Device Initialization example

Snippet2: Configure Device Interrupt

Snippet3: Device Async Read

Snippet4: Device Mailbox Write

API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ cyhal_sdio_cfg_t

Macro Definition Documentation

◆ cyhal_sdio_send_cmd

◆ cyhal_sdio_bulk_transfer

◆ cyhal_sdio_transfer_async

◆ cyhal_sdio_set_io_voltage

Enumeration Type Documentation

◆ cyhal_sdio_event_t

◆ cyhal_sdio_host_command_t

◆ cyhal_sdio_host_transfer_type_t

◆ cyhal_sdio_host_io_voltage_t

◆ cyhal_sdio_host_io_volt_action_type_t

Function Documentation

◆ cyhal_sdio_init()

◆ cyhal_sdio_free()

◆ cyhal_sdio_configure()

◆ cyhal_sdio_is_busy()

◆ cyhal_sdio_abort_async()

◆ cyhal_sdio_register_callback()

◆ cyhal_sdio_enable_event()

◆ cyhal_sdio_init_cfg()

◆ cyhal_sdio_host_send_cmd()

◆ cyhal_sdio_host_bulk_transfer()

◆ cyhal_sdio_host_transfer_async()

◆ cyhal_sdio_host_set_io_voltage()