SDIO

This section introduces the SDIO driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, SDIO function groups, enums, structures and functions. More...

Overview

This section introduces the SDIO driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, SDIO function groups, enums, structures and functions.

Terms and acronyms

Terms	Details
MSDC	MS/SD memory card controller, that supports the MultiMediaCard System Specification Version 4.41,SD Memory Card Specification Version 2.0 and SDIO Card Specification Version 2.0.
SDIO	Secure Digital Input and Output. For an introduction to the SDIO, please refer to SDIO in Wikipedia .

Supported features

• Supports DMA and MCU modes.
  
  • DMA mode: In this mode, the DMA hardware carries data from the RAM to the MSDC FIFO and transmits to the SDIO slave or reads data from the MSDC FIFO to the RAM directly.
  • MCU mode: In this mode, the MCU writes data from the RAM to the MSDC FIFO and transmits to the SDIO slave or reads data from the MSDC FIFO to the RAM directly.
  There is one API for the DMA mode, hal_sdio_execute_command53_dma() to read data from the SDIO card or write data to the card. Similarly, there is one API for the MCU mode, hal_sdio_execute_command53() to read data from the SDIO card or write data to the card. COMMAND53 offers the simplest means to read and write multiple SDIO slave registers. For COMMAND53, SDIO cards may transfer data in either a multi-byte (1 to 512 bytes) or an optional block format, while the SDIO cards are fixed in the block transfer mode. For more details about the COMMAND53, please refer to SDIO Simplified Specification V2.0 Chapter 5.3.
  
  
• Supports 1-bit or 4-bit bus width.
  1-bit bus width or 4-bit bus width is available to select for data transmission. For 1-bit bus width, only data line 0 (SDIO_DAT0) is enabled to transfer data. The data lines 1-3 (SDIO_DAT[3:1]) cannot be used. All four data lines (SDIO_DAT[3:0]) are available in the 4-bit bus width mode. The corresponding API is hal_sdio_set_bus_width().
  
  

Software architecture of the SDIO

Call hal_sdio_init() to initialize the MSDC and the SDIO slave. Then the SDIO slave gets into a transfer state. Call hal_sdio_execute_command53(), hal_sdio_execute_command53_dma() or hal_sdio_execute_command52() to write data to the SDIO slave or read data from the SDIO slave. Other supported APIs can also be called, such as hal_sdio_set_clock(). Use COMMAND52 to access a single SDIO slave register and COMMAND53 to read and write multiple SDIO slave registers. For more details about COMMAND52 and COMMAND53, please refer to SDIO Simplified Specification V2.0 Chapter 5.1 and Chapter 5.3 .

How to use this driver

• Read from or write to the SDIO slave with COMMAND53 in the MCU mode.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Call hal_sdio_execute_command53() to read data from or write data to the SDIO card.
  • Read sample code:

    hal_sdio_status_t ret;
    hal_sdio_command53_config_t config;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }
    
    config.direction = HAL_SDIO_DIRECTION_READ;
    config.function = HAL_SDIO_FUNCTION_0;
    config.is_block = true;
    config.count = 2;
    config.address = address;
    config.buffer = buffer;
    ret = hal_sdio_execute_command53(HAL_SDIO_PORT_0, &config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

  • Write sample code:

    hal_sdio_status_t ret;
    hal_sdio_command53_config_t config;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }
    
    config.direction = HAL_SDIO_DIRECTION_WRITE;
    config.function = HAL_SDIO_FUNCTION_0;
    config.is_block = true;
    config.count = 2;
    config.address = address;
    config.buffer = buffer;
    ret = hal_sdio_execute_command53(HAL_SDIO_PORT_0, &config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

• Read from or write to the SDIO slave in the DMA blocking mode.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Call hal_sdio_execute_command53_dma_blocking() to read data from or write data to the SDIO card.
  • Read sample code:

    hal_sdio_status_t ret;
    hal_sdio_command53_config_t config;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
       // Error handler.
    }
    
    config.direction = HAL_SDIO_DIRECTION_READ;
    config.function = HAL_SDIO_FUNCTION_0;
    config.is_block = true;
    config.count = 2;
    config.address = address;
    config.buffer = buffer;
    ret = hal_sdio_execute_command53_dma_blocking(HAL_SDIO_PORT_0, &config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

  • Write sample code:

    hal_sdio_status_t ret;
    hal_sdio_command53_config_t config;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
    }
    
    config.direction = HAL_SDIO_DIRECTION_WRITE;
    config.function = HAL_SDIO_FUNCTION_0;
    config.is_block = true;
    config.count = 2;
    config.address = address;
    config.buffer = buffer;
    ret = hal_sdio_execute_command53_blocking(HAL_SDIO_PORT_0, &config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

• Read from or write to the SDIO slave in the DMA interrupt mode.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Call hal_sdio_register_callback() to register the transfer result callback.
  • Step 3. Call hal_sdio_execute_command53_dma() to read data from or write data to the SDIO card.
  • Read sample code:

     hal_sdio_status_t ret;
     hal_sdio_command53_config_t config;
     hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    
     void sdio_dma_transfer_callback(hal_sdio_callback_event_t sdio_event, void *user_data)
     {
         if (HAL_SDIO_EVENT_SUCCESS == sdio_event) {
             // DMA transfer OK.
         } else if (HAL_SDIO_EVENT_TRANSFER_ERROR == sdio_event) {
             // DMA transfer error.
         } else if (HAL_SDIO_EVENT_CRC_ERROR == sdio_event) {
             // DMA transfer with CRC error.
         } else if (HAL_SDIO_EVENT_DATA_TIMEOUT == sdio_event) {
             // DMA transfer with timeout.
         }
    }
    
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    
     if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
     }
    
    if (HAL_SDIO_STATUS_OK != hal_sd_register_callback(HAL_SDIO_PORT_0, sdio_dma_transfer_callback,NULL)) {
         // Error handler.
    }
    
     config.direction = HAL_SDIO_DIRECTION_READ;
     config.function = HAL_SDIO_FUNCTION_0;
     config.is_block = true;
     config.count = 2;
     config.address = address;
     config.buffer = buffer;
     ret = hal_sdio_execute_command53_dma(HAL_SDIO_PORT_0, &config);
     if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
     }

  • Write sample code:

     hal_sdio_status_t ret;
     hal_sdio_command53_config_t config;
     hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    
     void sdio_dma_transfer_callback(hal_sdio_callback_event_t sdio_event, void *user_data)
     {
          if (HAL_SDIO_EVENT_SUCCESS == sdio_event) {
              // DMA transfer OK.
          } else if (HAL_SDIO_EVENT_TRANSFER_ERROR == sdio_event) {
              // DMA transfer error.
          } else if (HAL_SDIO_EVENT_CRC_ERROR == sdio_event) {
              // DMA transfer with CRC error.
          } else if (HAL_SDIO_EVENT_DATA_TIMEOUT == sdio_event) {
              // DMA transfer with timeout.
          }
    }
    
     ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
     if (HAL_SDIO_STATUS_OK != ret) {
          // Error handler.
     }
    
     if (HAL_SDIO_STATUS_OK != hal_sd_register_callback(HAL_SDIO_PORT_0, sdio_dma_transfer_callback,NULL)) {
          // Error handler.
     }
    
     config.direction = HAL_SDIO_DIRECTION_WRITE;
     config.function = HAL_SDIO_FUNCTION_0;
     config.is_block = true;
     config.count = 2;
     config.address = address;
     config.buffer = buffer;
     ret = hal_sdio_execute_command53(HAL_SDIO_PORT_0, &config);
     if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
     }

• Set the SDIO output clock.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Set the SDIO output clock.

    hal_sdio_status_t ret;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
    }
    
    ret = hal_sdio_set_clock(&sdio_config,400);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

• Get the SDIO output clock.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Get the SDIO output clock.

    hal_sdio_status_t ret;
    uint32_t clock = 0;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }
    
    ret = hal_sdio_get_clock(HAL_SDIO_PORT_0,clock);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

• Set the SDIO bus width.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Set the SDIO bus width.

    hal_sdio_status_t ret;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }
    
    ret = hal_sdio_set_bus_width(HAL_SDIO_PORT_0,HAL_SDIO_BUS_WIDTH_4);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }

• Set the SDIO block size.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Set the SDIO block size.

    hal_sdio_status_t ret;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
    if (HAL_SDIO_STATUS_OK != ret) {
        // Error handler.
    }
    
     ret = hal_sdio_set_block_size(HAL_SDIO_PORT_0,HAL_SDIO_FUNCTION_1,256);
     if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
     }

• Get the SDIO block size.
  
  • Step 1. Call hal_sdio_init() to initialize the MSDC and the SDIO slave to transfer states.
  • Step 2. Get the SDIO block size.

    uint32_t block_size;
    hal_sdio_status_t ret;
    hal_sdio_config_t sdio_config = {HAL_SDIO_BUS_WIDTH_4, 25000};
    ret = hal_sdio_init(HAL_SDIO_PORT_0,&sdio_config);
     if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
    }
    
     ret = hal_sdio_get_block size(HAL_SDIO_PORT_0,HAL_SDIO_FUNCTION_1,&block_size);
     if (HAL_SDIO_STATUS_OK != ret) {
         // Error handler.
     }

Functions
hal_sdio_status_t	hal_sdio_register_callback (hal_sdio_port_t sdio_port, hal_sdio_callback_t sdio_callback, void *user_data)
	This function registers a callback function to inform the user the transfer is complete. More...
hal_sdio_status_t	hal_sdio_init (hal_sdio_port_t sdio_port, hal_sdio_config_t *sdio_config)
	This function initializes the MSDC hardware and SDIO slave. More...
hal_sdio_status_t	hal_sdio_deinit (hal_sdio_port_t sdio_port)
	This function deinitializes the MSDC and the SDIO slave settings. More...
hal_sdio_status_t	hal_sdio_set_clock (hal_sdio_port_t sdio_port, uint32_t clock)
	This function sets the output clock of the MSDC. More...
hal_sdio_status_t	hal_sdio_get_clock (hal_sdio_port_t sdio_port, uint32_t *clock)
	This function gets the output clock of the MSDC. More...
hal_sdio_status_t	hal_sdio_set_bus_width (hal_sdio_port_t sdio_port, hal_sdio_bus_width_t bus_width)
	This function sets the bus widths for the MSDC and SDIO slave. More...
hal_sdio_status_t	hal_sdio_set_block_size (hal_sdio_port_t sdio_port, hal_sdio_function_id_t function, uint32_t block_size)
	This function sets the transaction block size of the MSDC. More...
hal_sdio_status_t	hal_sdio_get_block_size (hal_sdio_port_t sdio_port, hal_sdio_function_id_t function, uint32_t *block_size)
	This function gets the transaction block size of the MSDC. More...
hal_sdio_status_t	hal_sdio_execute_command52 (hal_sdio_port_t sdio_port, hal_sdio_command52_config_t *command52_config)
	This function reads from or writes to the SDIO slave with COMMAND52. More...
hal_sdio_status_t	hal_sdio_execute_command53 (hal_sdio_port_t sdio_port, hal_sdio_command53_config_t *command53_config)
	This function reads from or writes to the SDIO slave with COMMAND53 MCU mode. More...
hal_sdio_status_t	hal_sdio_execute_command53_dma_blocking (hal_sdio_port_t sdio_port, hal_sdio_command53_config_t *command53_config)
	This function reads from or writes to the SDIO slave with COMMAND53 DMA interrupt mode. More...
hal_sdio_status_t	hal_sdio_execute_command53_dma (hal_sdio_port_t sdio_port, hal_sdio_command53_config_t *command53_config)
	This function reads from or writes to the SDIO slave with COMMAND53 DMA interrupt mode. More...

Modules
	Enum
	Struct
	Typedef

Function Documentation

hal_sdio_status_t hal_sdio_deinit

(

hal_sdio_port_t

sdio_port

)

This function deinitializes the MSDC and the SDIO slave settings.

Parameters

[in]

sdio_port

is the MSDC deinitialization port.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully.

See also

hal_sdio_init()

hal_sdio_status_t hal_sdio_execute_command52	(	hal_sdio_port_t	sdio_port,
		hal_sdio_command52_config_t *	command52_config
	)

This function reads from or writes to the SDIO slave with COMMAND52.

Parameters

[in]	sdio_port	is the MSDC port to read or write.
[in]	command52_config	is the configuration parameter pointer of the COMMAND52.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_execute_command53	(	hal_sdio_port_t	sdio_port,
		hal_sdio_command53_config_t *	command53_config
	)

This function reads from or writes to the SDIO slave with COMMAND53 MCU mode.

Parameters

[in]	sdio_port	is the MSDC port to read.
[in]	command53_config	is the configuration parameter pointer of the COMMAND53.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_execute_command53_dma	(	hal_sdio_port_t	sdio_port,
		hal_sdio_command53_config_t *	command53_config
	)

This function reads from or writes to the SDIO slave with COMMAND53 DMA interrupt mode.

This API would not block the application task.

Parameters

[in]	sdio_port	is the MSDC port to read.
[in]	command53_config	is the configuration parameter pointer of the COMMAND53.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_execute_command53_dma_blocking	(	hal_sdio_port_t	sdio_port,
		hal_sdio_command53_config_t *	command53_config
	)

This function reads from or writes to the SDIO slave with COMMAND53 DMA interrupt mode.

This API would not block the application task.

Parameters

[in]	sdio_port	is the MSDC port to read.
[in]	command53_config	is the configuration parameter pointer of the COMMAND53.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_get_block_size	(	hal_sdio_port_t	sdio_port,
		hal_sdio_function_id_t	function,
		uint32_t *	block_size
	)

This function gets the transaction block size of the MSDC.

Parameters

[in]	sdio_port	is the MSDC port to get block size.
[in]	function	is the SDIO function to get block size.
[out]	block_size	is the SDIO transaction block size.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given.

hal_sdio_status_t hal_sdio_get_clock	(	hal_sdio_port_t	sdio_port,
		uint32_t *	clock
	)

This function gets the output clock of the MSDC.

Parameters

[in]	sdio_port	is the MSDC port to get clock.
[out]	clock	is the current output clock of the MSDC.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given.

hal_sdio_status_t hal_sdio_init	(	hal_sdio_port_t	sdio_port,
		hal_sdio_config_t *	sdio_config
	)

This function initializes the MSDC hardware and SDIO slave.

It can also be used to set the MSDC pin output clock and bus width.

Parameters

[in]	sdio_port	is the initialization configuration port. For more details about this parameter, please refer to hal_sdio_port_t.
[in]	sdio_config	is the initialization configuration parameter. For more details about this parameter, please refer to hal_sdio_config_t.

Returns

Indicates whether this function call is successful or not. If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an initialization error occurred. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

See also

hal_sdio_deinit()

hal_sdio_status_t hal_sdio_register_callback	(	hal_sdio_port_t	sdio_port,
		hal_sdio_callback_t	sdio_callback,
		void *	user_data
	)

This function registers a callback function to inform the user the transfer is complete.

Parameters

[in]	sdio_port	is the MSDC port to transfer data.
[in]	hal_sdio_callback_t	is the function pointer of the callback. The callback function is called once the SDIO data transfer is complete.
[in]	user_data	is the callback parameter.

Returns

HAL_SDIO_STATUS_OK, if the operation completed successfully.

hal_sdio_status_t hal_sdio_set_block_size	(	hal_sdio_port_t	sdio_port,
		hal_sdio_function_id_t	function,
		uint32_t	block_size
	)

This function sets the transaction block size of the MSDC.

Parameters

[in]	sdio_port	is the MSDC port to set.
[in]	function	is the SDIO function to set block size.
[in]	block_size	is the SDIO transaction block size.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_set_bus_width	(	hal_sdio_port_t	sdio_port,
		hal_sdio_bus_width_t	bus_width
	)

This function sets the bus widths for the MSDC and SDIO slave.

Parameters

[in]	sdio_port	is the MSDC port to set.
[in]	bus_width	is the SDIO bus width.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.

hal_sdio_status_t hal_sdio_set_clock	(	hal_sdio_port_t	sdio_port,
		uint32_t	clock
	)

This function sets the output clock of the MSDC.

Parameters

[in]	sdio_port	is the MSDC port to set clock.
[in]	clock	is the expected output clock of the MSDC.

Returns

If the return value is HAL_SDIO_STATUS_OK, the operation completed successfully. If the return value is HAL_SDIO_STATUS_ERROR, an error occurred, such as a wrong parameter is given. If the return value is HAL_SDIO_STATUS_BUSY, the MSDC is busy.