HAL SDIO Functions

Initialization and de-initialization functions

group SDIO_Exported_Functions_Group1

This section provides functions allowing to initialize and de-initialize the SDIO card :

  • Call the function HAL_SDIO_Init() to initialize the selected HAL SDIO handle and associate an SDIO peripheral instance.

  • Call the function HAL_SDIO_DeInit() to de-initialize the SDIO card.

Functions

hal_status_t HAL_SDIO_Init ( hal_sdio_handle_t * hsdio , hal_sdio_t instance )

Initialize the selected HAL SDIO handle and associate an SDIO peripheral instance.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – SDIO handle has been correctly Initialized.

void HAL_SDIO_DeInit ( hal_sdio_handle_t * hsdio )

De-Initializes the SDIO card.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Set and Get configurations functions

group SDIO_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the SDIO peripheral:

Functions

hal_status_t HAL_SDIO_SetConfig ( hal_sdio_handle_t * hsdio , const hal_sdio_config_t * p_config , hal_sdio_identify_card_t sdio_identify_card )

Configure the SDIO according to the user parameters.

Note

If the param sdio_identify_card is passed as NULL parameter, the SDIO module will be identified using the identification card function defined in the SDIO source file.

Note

If sdio_identify_card is passed as not null, the user utilizes a custom function to perform the identification phase for the SDIO module. This function must be properly registered and implemented by the user to handle the specific identification sequence of the SDIO card.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • p_config – Pointer to a hal_sdio_config_t structure that contains the SDIO configuration.

  • sdio_identify_card – Pointer to the identification callback function.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – SDIO instance is already configured and cannot be modified.

  • HAL_OK – SDIO instance has been correctly configured.

void HAL_SDIO_GetConfig ( hal_sdio_handle_t * hsdio , hal_sdio_config_t * p_config )

Get the SDIO configuration.

Parameters :
hal_status_t HAL_SDIO_NotifyCardInsertion ( hal_sdio_handle_t * hsdio , const hal_sdio_config_t * p_config )

Notify SDIO card after insertion.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – SDIO instance has been correctly configured after detection.

hal_status_t HAL_SDIO_NotifyCardRemoval ( hal_sdio_handle_t * hsdio )

Notify SDIO card after removal.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

HAL_OK – SDIO card has been correctly re-configured with its default configuration.

hal_status_t HAL_SDIO_SetDataBusWidth ( hal_sdio_handle_t * hsdio , hal_sdio_bus_wide_t bus_wide )

Set SDIO wide bus.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • bus_wide – Specifies the SDIO card wide bus mode

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_sdio_bus_wide_t HAL_SDIO_GetDataBusWidth ( hal_sdio_handle_t * hsdio )

Get SDIO wide bus.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure

Return values :

hal_sdio_bus_wide_t – sdio wide bus.

hal_status_t HAL_SDIO_SetTransferClockFreq ( hal_sdio_handle_t * hsdio , const uint32_t transfer_clock_freq_hz )

Set the SDIO transfer clock frequency.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • transfer_clock_freq_hz – SDIO Clock frequency in Hz.

Return values :

HAL_OK – Operation completed.

uint32_t HAL_SDIO_GetTransferClockFreq ( hal_sdio_handle_t * hsdio )

Get the SDIO transfer clock frequency.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure

Return values :

uint32_t – transfer clock frequency value in Hz.

hal_status_t HAL_SDIO_SetBlockSize ( hal_sdio_handle_t * hsdio , hal_sdio_function_t function_nbr , hal_sdio_block_size_t block_size )

Set the SDIO block size.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • function_nbr – Specifies the SDIO function number

  • block_size – Specifies the SDIO Block size to set

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_SetSpeedMode ( hal_sdio_handle_t * hsdio , const hal_sdio_speed_mode_t speed_mode )

Configure the data rate.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • speed_mode – Specifies the SDIO speed mode to set

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_ResetCard ( hal_sdio_handle_t * hsdio )

Reset SDIO Card.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_SetDataTimeout ( hal_sdio_handle_t * hsdio , uint32_t data_timeout_cycle )

Set SDIO data timeout.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • data_timeout_cycle – SDIO data timeout cycle.

Return values :

HAL_OK – SDIO card has been correctly set the data timeout cycle value.

uint32_t HAL_SDIO_GetDataTimeout ( const hal_sdio_handle_t * hsdio )

Get SDIO data timeout.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

uint32_t – data_timeout_cycle value in millisecond.

uint32_t HAL_SDIO_GetClockFreq ( hal_sdio_handle_t * hsdio )

Return the peripheral clock frequency for SDIO.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure

Return values :

  • uint32_t – Frequency in Hz

  • 0 – source clock of the SDIO not configured or not ready

Process functions

group SDIO_Exported_Functions_Group3

This subsection provides a set of functions allowing to manage the data transfer from/to SDIO card.

There are 2 categories of HAL functions APIs to manage the data transfer:

There are 2 categories of HAL functions APIs to manage data register from/to SDIO card:

Functions

hal_status_t HAL_SDIO_ReadDirect ( hal_sdio_handle_t * hsdio , const hal_sdio_direct_cmd_t * p_argument , uint8_t * p_data )

Read data from a specified address using the direct mode through cmd52.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • p_argument – Pointer to cmd52 argument structure

  • p_data – Pointer to the buffer that will contain the received data

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_WriteDirect ( hal_sdio_handle_t * hsdio , const hal_sdio_direct_cmd_t * p_argument , uint8_t data )

Write data to a specified address using the direct mode through cmd52.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • p_argument – Pointer to cmd52 argument structure

  • data – Data to write.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_ReadExtended ( hal_sdio_handle_t * hsdio , const hal_sdio_extended_cmd_t * p_argument , uint8_t * p_data , uint32_t size_byte , uint32_t timeout_ms )

Read data from a specified address using extended mode through cmd53.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • p_argument – Pointer to cmd53 argument structure

  • p_data – Pointer to the buffer that will contain the data to read

  • size_byte – Size to read

  • timeout_ms – Specify timeout value in millisecond

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_WriteExtended ( hal_sdio_handle_t * hsdio , const hal_sdio_extended_cmd_t * p_argument , const uint8_t * p_data , uint32_t size_byte , uint32_t timeout_ms )

Write data from a specified address using extended mode through cmd53.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • p_argument – Pointer to cmd53 argument structure

  • p_data – Pointer to the buffer that will contain the data to transmit

  • size_byte – Block size to write

  • timeout_ms – Specify timeout value in millisecond

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_ReadExtended_DMA ( hal_sdio_handle_t * hsdio , const hal_sdio_extended_cmd_t * p_argument , uint8_t * p_data , uint32_t size_byte )

Read data from a specified address using extended mode through cmd53 in DMA mode.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • p_argument – Pointer to cmd53 argument structure

  • p_data – pointer to the buffer that will contain the data to transmit

  • size_byte – Block size to write

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_WriteExtended_DMA ( hal_sdio_handle_t * hsdio , const hal_sdio_extended_cmd_t * p_argument , const uint8_t * p_data , uint32_t size_byte )

Write data from a specified address using extended mode through cmd53 in DMA mode.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure

  • p_argument – Pointer to cmd53 argument structure

  • p_data – Pointer to the buffer that will contain the data to transmit

  • size_byte – Block size to write

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

IRQHandler and Callbacks Functions

group SDIO_Exported_Functions_Group4

This subsection provides a set of callback functions allowing to manage the data transfer from/to SDIO card.

Functions

void HAL_SDIO_IRQHandler ( hal_sdio_handle_t * hsdio )

This function handles SDIO card interrupt request.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

void HAL_SDIO_XferCpltCallback ( hal_sdio_handle_t * hsdio , hal_sdio_event_cb_t cb_event )

Transfer completed callbacks.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :
void HAL_SDIO_ErrorCallback ( hal_sdio_handle_t * hsdio )

SDIO error callbacks.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

void HAL_SDIO_IOFunctionCallback ( hal_sdio_handle_t * hsdio , uint32_t func )

SDIO IO Function complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :
void HAL_SDIO_DriveTransceiver_1_8V_Callback ( hal_sdio_handle_t * hsdio , hal_sdio_transceiver_state_t state )

Enable/Disable the SDIO Transceiver 1.8V Mode callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :
hal_status_t HAL_SDIO_RegisterXferCpltCallback ( hal_sdio_handle_t * hsdio , hal_sdio_xfer_cb_t callback )

Register the SDIO Xfer callback to be used instead of the weak HAL_SDIO_XferCpltCallback predefined callback.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • callback – pointer to the Callback function.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SDIO_RegisterErrorCpltCallback ( hal_sdio_handle_t * hsdio , hal_sdio_cb_t callback )

Register the SDIO Error callback to be used instead of the weak HAL_SDIO_ErrorCallback predefined callback.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • callback – Pointer to the callback function.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SDIO_RegisterTransceiverCallback ( hal_sdio_handle_t * hsdio , hal_sdio_transceiver_cb_t callback )

Register a User SDIO Transceiver callback to be used instead of the weak (overridden) predefined callback.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • callback – Pointer to the callback function

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SDIO_RegisterIOFunctionCallback ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function , hal_sdio_io_function_cb_t callback )

Register an IO function callback.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – IO function number.

  • callback – IO IRQ handler.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

Peripheral IO interrupt

group SDIO_Exported_Functions_Group6

This subsection provides a set of functions allowing to enable/disable IO functions interrupt features on the SDIO card.

Functions

hal_status_t HAL_SDIO_EnableIOFunctionInterrupt ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Enable SDIO IO interrupt.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specifies the SDIO IO function.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_DisableIOFunctionInterrupt ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Disable SDIO IO interrupt.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specifies the SDIO IO function.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_EnableIOFunction ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Enable SDIO Function.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specifies the IO function to enable.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_DisableIOFunction ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Disable SDIO IO function.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specifies the IO function to disable.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_SelectIOFunction ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Select SDIO IO function.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specifies the IO function to select.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_AbortIOFunction ( hal_sdio_handle_t * hsdio , hal_sdio_function_t io_function )

Abort an IO transfer function.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • io_function – Specify the IO function to abort

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_EnableIOAsynInterrupt ( hal_sdio_handle_t * hsdio )

Enable asynchronous IO interrupt.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

hal_status_t HAL_SDIO_DisableIOAsynInterrupt ( hal_sdio_handle_t * hsdio )

Disable asynchronous IO interrupt.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – Operation completed.

SDIO Delay Block functions

group SDIO_Exported_Functions_Group7

This subsection provides a set of functions allowing to configure the delay block:

Functions

hal_status_t HAL_SDIO_SetConfigDlybDelay ( hal_sdio_handle_t * hsdio , uint32_t clock_phase_value )

Set the SDIO delay block configuration.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • clock_phase_value – The selected output clock phase value will be stored.

Return values :

  • HAL_ERROR – An error has been occurred.

  • HAL_OK – The delay is correctly set.

uint32_t HAL_SDIO_GetDlybOutputClockPhase ( const hal_sdio_handle_t * hsdio )

Get the SDIO delay block output clock phase.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • p_clock_phase – Pointer to the variable where the selected output clock phase value will be stored.

Return values :

uint32_t – output clock phase value.

hal_status_t HAL_SDIO_CalculateDlybMaxClockPhase ( hal_sdio_handle_t * hsdio , uint32_t * p_max_clock_phase )

Calculate the SDIO delay block maximum output clock phase.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure.

  • p_max_clock_phase – Pointer to the variable where the maximum clock phase value to be stored.

Return values :

  • HAL_INVALID_PARAM – Invalid p_max_clock_phase parameter.

  • HAL_ERROR – The max clock phase is not correctly calculated.

  • HAL_OK – The max clock phase is correctly calculated.

hal_status_t HAL_SDIO_EnableDlyb ( hal_sdio_handle_t * hsdio )

Enable the SDIO delay block.

Parameters :

hsdio – Pointer to a hal_mm_handle_t structure.

Return values :

HAL_OK – The delay block is enabled.

hal_status_t HAL_SDIO_DisableDlyb ( hal_sdio_handle_t * hsdio )

Disable the SDIO delay block.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

HAL_OK – The delay block is disabled.

hal_sdio_dlyb_state_t HAL_SDIO_IsEnabledDlyb ( hal_sdio_handle_t * hsdio )

Check if the delay block peripheral is enabled or not.

Parameters :

hsdio – Pointer to a hal_sdio_handle_t structure.

Return values :

  • HAL_SDIO_DLYB_DISABLED – Delay block is disabled.

  • HAL_SDIO_DLYB_ENABLED – Delay block is enabled.

Interrupt And Flag Configuration

group SDIO_Exported_Functions_Group8

This section provides functions allowing to initialize and de-initialize the SDIO card device :

Functions

void HAL_SDIO_EnableIT ( hal_sdio_handle_t * hsdio , uint32_t interrupt )

Enable the SDIO device interrupt.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure that contains the configuration information for the SDIO.

  • interrupt – Specifies the SDMMC interrupt sources to be enabled. This parameter can be a combination of Interrupt Sources group.

void HAL_SDIO_DisableIT ( hal_sdio_handle_t * hsdio , uint32_t interrupt )

Disable the SDIO device interrupt.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure that contains the configuration information for the SDIO.

  • interrupt – Specifies the SDMMC interrupt sources to be disable. This parameter can be a combination of Interrupt Sources group.

uint32_t HAL_SDIO_IsEnabledIT ( const hal_sdio_handle_t * hsdio , uint32_t interrupt )

Check whether or not the specified SDIO interrupt is set.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure that contains the configuration information for the SDIO.

  • interrupt – Specifies the SDMMC interrupt sources to be enabled.

Return values :

The – state of SDIO interrupt (0 or 1)

uint32_t HAL_SDIO_IsActiveFlag ( const hal_sdio_handle_t * hsdio , uint32_t flag )

Check whether the specified SDIO flag is set or not.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure that contains the configuration information for the SDIO.

  • flag – Specifies the flag source to check.

Return values :

The – new state of SDMMC_FLAG (SET or RESET).

void HAL_SDIO_ClearFlag ( hal_sdio_handle_t * hsdio , uint32_t flag )

Clear the SDIO pending flags.

Parameters :

  • hsdio – Pointer to a hal_sdio_handle_t structure that contains the configuration information for the SDIO.

  • flag – Specifies the SDMMC flag sources to clear. This parameter can be a combination of Flags Sources group.