SDIO (Secure Digital Input Output)

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 mtb_hal_sdio_host_command_t. Bulk data transfer is supported via mtb_hal_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

Initialize SDIO by using the Device Configurator and selecting pins according to the target device used. Specify the SDIO configuration using the configuration structure (const mtb_hal_sdio_configurator_t * config).

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;
    mtb_hal_sdio_t sdio_object;
    cy_stc_sd_host_context_t sdio_context;
 
    #define BLOCK_SIZE     (512)
    #define SDIO_FREQ_HF   (100000000UL)
 
    mtb_hal_sdio_cfg_t my_sdio_cfg =
    {
        .block_size        = BLOCK_SIZE,
        .frequencyhal_hz   = SDIO_FREQ_HF,
        .is_sdio_dev       = false
    };
 
 
    // Use PDL to configure SDIO hardware
    Cy_SD_Host_Enable(SDIO_sdio_hal_config.base);
    Cy_SD_Host_Init(SDIO_sdio_hal_config.base, SDIO_sdio_hal_config.host_config, &sdio_context);
    rslt = Cy_SD_Host_SetHostBusWidth(SDIO_sdio_hal_config.base, CY_SD_HOST_BUS_WIDTH_4_BIT);
 
    // Configure interrupt handling
    cy_stc_sysint_t intr_cfg_1 = { .intrSrc = SDIO_IRQ, .intrPriority = 7u }; // SDIO_IRQ generated
                                                                              // through device
                                                                              // configurator
    Cy_SysInt_Init(&intr_cfg_1, my_sdio_interrupt_handler);
    NVIC_EnableIRQ(SDIO_IRQ);
 
    // Set up our SDIO HAL object
    rslt = mtb_hal_sdio_setup(&sdio_object, &SDIO_sdio_hal_config, NULL, &sdio_context);
 
    // Configure the SDIO HAL object
    rslt = mtb_hal_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 mtb_hal_sdio_event_t for different types of events.

 
// Event handler callback function
void sdio_host_event_handler(void* handler_arg, mtb_hal_sdio_event_t event)
{
    CY_UNUSED_PARAMETER(handler_arg);
    CY_UNUSED_PARAMETER(event);
 
    switch (event)
    {
        case MTB_HAL_SDIO_CARD_INSERTION:
        {
            // Triggered when card insertion is detected in present state
            // Insert application code to handle events
            break;
        }
 
        case MTB_HAL_SDIO_CMD_COMPLETE:
        {
            // Triggered when command transfer is complete
            // Insert application code to handle events
            break;
        }
 
        case MTB_HAL_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_mtb_hal_host_sdio_interrupt_init()
{
    // Register the event callback
    mtb_hal_sdio_register_callback(&sdio_obj, &sdio_host_event_handler, NULL);
 
    // Enable events that should trigger the callback
    mtb_hal_sdio_enable_event(&sdio_obj, MTB_HAL_SDIO_ALL_INTERRUPTS, 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 mtb_hal_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                     ((mtb_hal_sdio_host_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 = mtb_hal_sdio_host_send_cmd(&sdio_obj, MTB_HAL_SDIO_XFER_TYPE_WRITE,
                                      MTB_HAL_SDIO_CMD_GO_IDLE_STATE,
                                      MY_SDIO_CMD_NO_ARG, &response);
 
    // Voltage check (CMD8).
    rslt = mtb_hal_sdio_host_send_cmd(&sdio_obj, MTB_HAL_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 = mtb_hal_sdio_host_bulk_transfer(&sdio_obj, MTB_HAL_SDIO_XFER_TYPE_WRITE,
                                           MY_SDIO_CMD_NO_ARG,
                                           data,
                                           DATA_LENGTH,
                                           &response);
 

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;
    mtb_hal_sdio_t sdio_object;
 
    #define BLOCK_SIZE         (512)
    #define SDIO_FREQ          (50000000UL)
 
    mtb_hal_sdio_cfg_t my_sdio_cfg =
    {
        .block_size        = BLOCK_SIZE,
        .frequenmtb_hal_hz = SDIO_FREQ,
        .is_sdio_dev       = true
    };
 
    rslt = mtb_hal_sdio_init(&sdio_object,
                             SDIO_CMD_PIN,
                             SDIO_CLK_PIN,
                             SDIO_DATA0_PIN,
                             SDIO_DATA1_PIN,
                             SDIO_DATA2_PIN,
                             SDIO_DATA3_PIN);
 
    rslt = mtb_hal_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 mtb_hal_sdio_event_t for different types of events.

 
// Event handler callback function
void sdio_dev_event_handler(void* handler_arg, mtb_hal_sdio_event_t event)
{
    CY_UNUSED_PARAMETER(handler_arg);
    CY_UNUSED_PARAMETER(event);
 
    switch (event)
    {
        case MTB_HAL_SDIO_DEV_HOST_INFO:
        {
            // Triggered on a mailbox or an F2 enable event
            // Insert application code to handle events
            break;
        }
 
        case MTB_HAL_SDIO_DEV_READ_COMPLETE:
        {
            // Triggered on a read completion event
            // Insert application code to handle events
            break;
        }
 
        case MTB_HAL_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_mtb_hal_dev_sdio_interrupt_init()
{
    #define INTERRUPT_PRIORITY (3u)
 
    // Register the event callback
    mtb_hal_sdio_register_callback(&sdio_obj, &sdio_dev_event_handler, NULL);
 
    // Enable events that should trigger the callback
    mtb_hal_sdio_enable_event(&sdio_obj, MTB_HAL_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, mtb_hal_sdio_event_t event)
{
    if ((handler_arg != NULL) && (event == MTB_HAL_SDIO_DEV_READ_COMPLETE))
    {
        // Triggered when device async read is complete
        // Insert application code to handle events
    }
}
 
 
void snippet_mtb_hal_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
    mtb_hal_sdio_register_callback(&sdio_obj, &sdio_dev_async_interrupt_handler,
                                   (void*)&handler_args);
 
    // Enable events MTB_HAL_SDIO_DEV_READ_COMPLETE and MTB_HAL_SDIO_DEV_READ_ERROR events.
    // Event MTB_HAL_SDIO_DEV_READ_COMPLETE is triggered once
    // async read is complete. Handle event in the event handler.
    mtb_hal_sdio_enable_event(&sdio_obj,
                              (mtb_hal_sdio_event_t)(MTB_HAL_SDIO_DEV_READ_COMPLETE |
                                                     MTB_HAL_SDIO_DEV_READ_ERROR),
                              INTERRUPT_PRIORITY,
                              true);
 
    // Begin async read
    mtb_hal_sdio_dev_read_async(&sdio_obj, &data[0], DATA_LENGTH);
 
    // Wait for read to finish
    while (mtb_hal_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_mtb_hal_sdio_dev_write_mailbox()
{
    #define HOST_MAILBOX_BITS                (0x5u)
    #define HOST_MAILBOX_DATA                (0x3u)
 
    uint32_t data = HOST_MAILBOX_DATA;
 
    cy_rslt_t status = mtb_hal_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	mtb_hal_sdio_cfg_t
	SDIO initial configuration struct. More...

Typedefs
typedef void(*	mtb_hal_sdio_event_callback_t) (void *callback_arg, mtb_hal_sdio_event_t event)
	Callback for SDIO events.

Enumerations
enum	mtb_hal_sdio_event_t { MTB_HAL_SDIO_ALL_INTERRUPTS = 0x0E1FF }
	Types of events that could be asserted by SDIO. More...

Functions
cy_rslt_t	mtb_hal_sdio_setup (mtb_hal_sdio_t *obj, const mtb_hal_sdio_configurator_t *config, const mtb_hal_clock_t *clock, cy_stc_sd_host_context_t *sdio_context)
	Sets up a HAL instance to use the specified hardware resource.
cy_rslt_t	mtb_hal_sdio_configure (mtb_hal_sdio_t *obj, const mtb_hal_sdio_cfg_t *config)
	Configure the SDIO block.
void	mtb_hal_sdio_register_callback (mtb_hal_sdio_t *obj, mtb_hal_sdio_event_callback_t callback, void *callback_arg)
	Register an SDIO event callback handler.
void	mtb_hal_sdio_enable_event (mtb_hal_sdio_t *obj, mtb_hal_sdio_event_t event, bool enable)
	Configure the callback event.
cy_rslt_t	mtb_hal_sdio_process_interrupt (mtb_hal_sdio_t *obj)
	Process interrupts related related to an SDIO instance.

---

Data Structure Documentation

mtb_hal_sdio_cfg_t

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

Enumeration Type Documentation

mtb_hal_sdio_event_t

enum mtb_hal_sdio_event_t

Types of events that could be asserted by SDIO.

Enumerator
MTB_HAL_SDIO_ALL_INTERRUPTS	Used to enable/disable all interrupts events.

Function Documentation

mtb_hal_sdio_setup()

cy_rslt_t mtb_hal_sdio_setup	(	mtb_hal_sdio_t *	obj,
		const mtb_hal_sdio_configurator_t *	config,
		const mtb_hal_clock_t *	clock,
		cy_stc_sd_host_context_t *	sdio_context
	)

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

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

Note

It is required that after calling mtb_hal_sdio_setup a User must call Cy_SD_Host_SetHostBusWidth to set the bus width to 4 (CY_SD_HOST_BUS_WIDTH_4_BIT).

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]	sdio_context	The context for the sdio instance allocated by the user

Returns

the status of the HAL setup

mtb_hal_sdio_configure()

cy_rslt_t mtb_hal_sdio_configure	(	mtb_hal_sdio_t *	obj,
		const mtb_hal_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 mtb_hal_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.

mtb_hal_sdio_register_callback()

void mtb_hal_sdio_register_callback	(	mtb_hal_sdio_t *	obj,
		mtb_hal_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 mtb_hal_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.

mtb_hal_sdio_enable_event()

void mtb_hal_sdio_enable_event	(	mtb_hal_sdio_t *	obj,
		mtb_hal_sdio_event_t	event,
		bool	enable
	)

Configure the callback event.

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

Parameters

[in]	obj	The SDIO object
[in]	event	The SDIO event type
[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.

mtb_hal_sdio_process_interrupt()

cy_rslt_t mtb_hal_sdio_process_interrupt

(

mtb_hal_sdio_t *

obj

)

Process interrupts related related to an SDIO 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