HAL SDIO How to Use ¶

group SDIO_How_To_Use

How to use this driver ¶

The HAL SDIO driver can be used as follows: ¶

SDIO card system specifications are available through the SD card association website at www.sdcard.org This driver is compliant with SDIO card specification version 4.0 and fully compliant with previous version.

This HAL SDIO driver is a layered driver on top of the SDMMC core driver (allowing to handle SD,MMC memories and SDIO cards). The HAL SDIO driver allows to interface with SDIO cards.

This driver implements a high level communication layer for read and write from/to this SDIO card.

This driver provides 8 different sets of APIs that allows to:

1. Initialize and de-initialize the logical SDIO object :

   • To initialize the SDIO Card, use the HAL_SDIO_Init() function

     • to associate physical instance to logical object.

     • Enable the SDMMC peripheral clock either by :

       • Calling the appropriate HAL RCC function HAL_RCC_SDMMCx_EnableClock

       • Setting the USE_HAL_SDIO_CLK_ENABLE_MODEL to HAL_CLK_ENABLE_PERIPH_ONLY through stm32tnxx_hal_conf.h module, in this case the SDMMC peripheral clock must be automatically enabled by the HAL_SDIO_Init() .

   • To de-initialize the SDIO card, use the HAL_SDIO_DeInit() function that must turn off the SDIO Card and set the HAL SDIO handle state to RESET.

2. Set and Get SDIO configuration:

   • Configures the SDIO card. The clock frequency must be less than 400 kHz. This phase allows the card identification to ensure that the card has been correctly identified. After identification, apply the user parameters. During this stage, the SDIO card moves from the IDENTIFICATION STATE to the TRANSFER STATE and sets the global state to the IDLE state.

   • To retrieve the current SDIO card configuration, use the HAL_SDIO_GetConfig() .

   • When the GPIO Pin detects a removal of the SDIO card from the bus, use the HAL_SDIO_NotifyCardRemoval() to apply the SDMMC default configuration and wait for an insertion of the SDIO card.

   • When the GPIO Pin detects an insertion of the SDIO card, use the HAL_SDIO_NotifyCardInsertion() to re-apply the user configuration.

   • To change the SDIO data bus width, use the HAL_SDIO_SetDataBusWidth() .

   • To get the SDIO data bus width, use the HAL_SDIO_GetDataBusWidth() .

   • To set a new transfer clock frequency, use the HAL_SDIO_SetTransferClockFreq() .

   • To get the current transfer clock frequency, use the HAL_SDIO_GetTransferClockFreq() .

   • To update the SDIO block size, use the HAL_SDIO_SetBlockSize() .

   • To configure the speed mode on the SDIO card, use HAL_SDIO_SetSpeedMode() .

   • To reset the SDIO card, use the HAL_SDIO_ResetCard() .

   • To retrieve the peripheral clock frequency for SDIO card, use the HAL_SDIO_GetClockFreq() .

   • According to the SDIO card specification, the timeout values available through define can be used also by user to fill the configuration structure at the SetConfig call:

     • HAL_SDIO_DATA_MAX_TIMEOUT (0xFFFFFFFFU) : Max data timeout

     • For the data_timeout_cycle : Use HAL_SDIO_SetDataTimeout() to update it with the user definition

3. Input and Output operations:

   • Direct Read/Write Operations:

     • To read data directly from an SDIO card, use the HAL_SDIO_ReadDirect() function.

     • To write data directly to an SDIO card, use the HAL_SDIO_WriteDirect() function.

   • Extended Read/Write Operations:

     • Blocking mode: Polling

       • To read data in an extended manner from an SDIO card, use the HAL_SDIO_ReadExtended() function.

       • To write data in an extended manner to an SDIO card, use the HAL_SDIO_WriteExtended() function.

     • Non-Blocking mode: DMA in normal mode

       • To read data in an extended manner with DMA, use the HAL_SDIO_ReadExtended_DMA() function.

       • To write data in an extended manner with DMA, use the HAL_SDIO_WriteExtended_DMA() function.

4. IRQHandler and Callbacks Functions:

   • All SDIO card interrupt requests are handled by the HAL_SDIO_IRQHandler function.

   • By default, after the HAL_SDIO_Init, all callbacks are reset to the corresponding legacy weak (overridden) functions:

     • HAL_SDIO_XferCpltCallback() : A Callback when an Xfer transfer is completed.

     • HAL_SDIO_ErrorCallback() : A Callback when an error has occurred.

     • HAL_SDIO_IOFunctionCallback() : A Callback when an IO function is completed.

     • HAL_SDIO_DriveTransceiver_1_8V_Callback() : A Callback when the switch to 1.8 v is completed.

   • To use the callback registration feature, Set the USE_HAL_SDIO_REGISTER_CALLBACKS to 1U the compilation flag through stm32tnxx_hal_conf.h module to allow the user to configure dynamically the driver register callbacks.

   • Use Functions to register a user callback, it allows to register following callbacks:

     • HAL_SDIO_RegisterXferCpltCallback() : To register an xfer callback function.

     • HAL_SDIO_RegisterErrorCpltCallback() : To register an error callback function.

     • HAL_SDIO_RegisterIOFunctionCallback() : To register an IO function callback function.

     • HAL_SDIO_RegisterTransceiverCallback() : To register a transceiver callback function. When The compilation define USE_HAL_SDIO_REGISTER_CALLBACKS is set to 0 or not defined, the callback registering feature is not available and weak (overridden) callbacks are used.

5. SDIO Card related information functions:

   • To get the global_state, use the HAL_SDIO_GetState() .

   • To get SDIO card common control register information, use the function HAL_SDIO_GetCardCommonControlRegister() .

   • To get SDIO card function basic register information, use the function HAL_SDIO_GetCardFunctionBasicRegister() .

   • To retrieve the last error code detected by the SDIO card, Set the USE_HAL_SDIO_GET_LAST_ERRORS to 1U the compilation flag through stm32tnxx_hal_conf.h module to allow the user to get the last error code by calling HAL_SDIO_GetLastErrorCodes() .

   • To store the user data into the SDIO handle, set the USE_HAL_SDIO_USER_DATA to 1U the compilation flag through stm32tnxx_hal_conf.h module and use the function HAL_SDIO_SetUserData() .

   • To get the user data, use the function HAL_SDIO_GetUserData() .

6. SDIO card IO interrupt:

   • To enable an interrupt for function X, use the function HAL_SDIO_EnableIOFunctionInterrupt() .

   • To disable an interrupt for function x, use the function HAL_SDIO_DisableIOFunctionInterrupt() .

   • To enable an IO function x, use the function HAL_SDIO_EnableIOFunction() .

   • To disable an IO function x, use the function HAL_SDIO_DisableIOFunction() .

   • To select an IO function x, use the function HAL_SDIO_SelectIOFunction() .

   • To abort an IO read/write operations for function x, use the function HAL_SDIO_AbortIOFunction() .

   • to enable the asynchronous interrupt, use the function HAL_SDIO_EnableIOAsynInterrupt() .

   • to disable the asynchronous interrupt, use the function HAL_SDIO_DisableIOAsynInterrupt() .

7. SDIO Delay Block functions: The delay block (DLYB) is used to generate an output clock that is phased from the input clock.

   • Use HAL_SDIO_SetConfigDlybDelay() to set the SDIO delay block configuration.

   • Use HAL_SDIO_GetDlybOutputClockPhase() to get the SDIO delay block output clock phase.

   • Use HAL_SDIO_CalculateDlybMaxClockPhase() to calculate the SDIO delay block maximum output clock phase.

   • Use HAL_SDIO_EnableDlyb() to enable the SDIO delay block.

   • Use HAL_SDIO_DisableDlyb() to disable the SDIO delay block.

   • Use HAL_SDIO_IsEnabledDlyb() to check if the delay block peripheral is enabled or not.

8. SDIO Card Interrupt and flags Inline functions:

   • HAL_SDIO_EnableIT() : Enable the SDIO card interrupt to generate an interrupt request.

   • HAL_SDIO_DisableIT() : Disable the SDIO card interrupt to clear an interrupt request.

   • HAL_SDIO_IsEnabledIT() : Check whether or not the specified SDIO interrupt is set.

   • HAL_SDIO_IsActiveFlag() : Check whether the specified SDIO flag is set or not.

   • HAL_SDIO_ClearFlag() : Clear the SDIO’s pending flags.