HAL SD How to Use ¶

group SD_How_To_Use

How to use this driver ¶

The HAL SD driver can be used as follows: ¶

SD memory card system Specifications are available through the SD card association website at www.sdcard.org This driver is compliant with SD memory card specification version 6.0 and full compliant with previous version.

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

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

This driver provides different set of APIs that allows to :

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

   • To initialize the SD Card, use the HAL_SD_Init() function to

     • to associate physical instance to logical object.

     • Enable the SDMMC peripheral Clock:

       • Either by calling the appropriate HAL RCC function HAL_RCC_SDMMCx_EnableClock

       • Either by Setting the USE_HAL_SD_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_SD_Init() .

   • To de-initiliaze the SD card, use the HAL_SD_DeInit() function that must turn off the SD Card and set the HAL SD handle state to RESET

2. Set and Get SD configuration:

   • Configure the SD card, use the HAL_SD_SetConfig() to apply the SD card configuration process, the clock frequency must be less than 400Khz. then, this phase allows the card identification and Get all card information (CSD, CID, Card Status Register) to ensure that the card has been correctly identified and then, Apply the user parameters. In this stage, the SD card moved from the IDENTIFICATION STATE to TRANSFER STATE and put the globale state at the IDLE state. In this case, we can perform any SD card Erase, read and write operation.

   • To get the SD card configuration, use the HAL_SD_GetConfig() to retrieve the current SD configuration.

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

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

   • According to the SD card specification (speed, size and class), the timeout values available through define can be used also by user to fill the configuration structure at the SetConfig call:

     • HAL_SD_DATA_MAX_TIMEOUT (0xFFFFFFFFU) : Max data timeout

     • HAL_SD_STOP_XFER_MAX_TIMEOUT (500U) : Max stop transfer timeout 500 ms

     • HAL_SD_ERASE_MAX_TIMEOUT (63000U) : Max erase Timeout 63 seconds It can modify the timeout process values:

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

     • For the stopxfer_timeout_ms : Use HAL_SD_SetStopXferTimeout() to update it with the user definition

     • for the erase_timeout_ms : Use HAL_SD_SetEraseTimeout() to update it with the user definition

3. Input and Output operations:

   • Blocking mode: Polling

     • Read from SD card in polling mode by using function HAL_SD_ReadBlocks() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly. The check is done through HAL_SD_GetCardState() function of SD card state.

     • Write to SD card in polling mode by using function HAL_SD_WriteBlocks() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly. The check is done through HAL_SD_GetCardState() function of the SD card state.

   • Non-Blocking mode: IT

     • Read from the SD card in Interrupt mode by using function HAL_SD_ReadBlocks_IT() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly by using the Xfer complete callbacks to check the end of the process.

     • Write to SD card in Interrupt mode by using function HAL_SD_WriteBlocks_IT() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly by using the Xfer complete callbacks to check the end of the process.

   • Non-Blocking mode: DMA in normal mode

     • Read from the SD card in DMA mode by using function HAL_SD_ReadBlocks_DMA() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly by checking the IT transfer process through the SD xfer interrupt event.

     • Write to SD card in DMA mode by using function HAL_SD_WriteBlocks_DMA() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). Choose either one block read operation or multiple block read operation by adjusting blocks_nbr. After this, ensure that the transfer is done correctly by using the Xfer complete callbacks to check the end of the process.

   • Non-Blocking mode: DMA in linked-list mode Use the Linked list feature by enabling the USE_HAL_SD_LINKEDLIST compilation flag through stm32tnxx_hal_conf.h module. At this stage, Build a linked-list Q using the module Q.

     • Read from the SD card in linked-list mode by using the function HAL_SD_ReadBlocks_LinkedList() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). After this, ensure that the transfer is done correctly by using the Xfer complete callbacks to check the end of the process.

     • Write to the SD card in linked-list mode by using the function HAL_SD_WriteBlocks_LinkedList() . This function supports only 512-bytes block length (the block size must be chosen as 512 bytes). After this, ensure that the transfer is done correctly by using the Xfer complete callbacks to check the end of the process.

   • Abort operation

     • Abort any transfer to/from the SD card by using the HAL_SD_Abort() to stop the transfer in polling mode

     • Abort any transfer to/from the SD card by using the HAL_SD_Abort_IT() to stop the transfer in IT mode

4. IRQHandler and Callbacks Functions:

   • All SD card interrupt requests are handled by the HAL_SD_IRQHandler function.

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

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

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

     • HAL_SD_AbortCallback() : A Callback when an abort is completed.

     • HAL_SD_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_SD_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_SD_RegisterXferCpltCallback() : To register an xfer callback function.

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

     • HAL_SD_RegisterAbortCpltCallback() : To register an abort callback function.

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

5. SD Card related information functions:

   • To get the globale global_state, use the HAL_SD_GetState() .

   • To get the internal state of the SD card, use the HAL_SD_GetCardState() .

   • To get SD card status use the function HAL_SD_GetCardStatus() to retrieve the status bits that are related to the SD memory card proprietary features.

   • To get SD card information, use the function HAL_SD_GetCardInfo() . It returns useful information about the SD card such as block number, block size type, logical block number, logical block size and the relative card address.

   • To switch the speed mode of the SD card, use the HAL_SD_SwitchSpeedMode() .

   • To retrieve the SD card specification version, use the HAL_SD_GetCardSpecVersion() .

   • To get the SD card identification register value, use the HAL_SD_GetCardCID() function.

   • To retrieve the last error code detecting by the SD card, Set the USE_HAL_SD_GET_LAST_ERRORS to 1U the compilation flag through stm32tnxx_hal_conf.h module to allow the user to get the last error code.

6. SD Card Interrupt and flags Inline functions:

   • HAL_SD_EnableIT() : Enable the SD device interrupt to generate an interrupt request.

   • HAL_SD_DisableIT() : Disable the SD device interrupt to clear an interrupt request.

   • HAL_SD_IsActiveFlag() : Check whether the specified SD flag is set or not.

   • HAL_SD_ClearFlag() : Clear the SD’s pending flags.

7. SD card linked-list queue functions: This subsection provides a set of functions allowing to manage the SD linked-list node and queue:

   • To build an SDMMC node, use the HAL_SD_FillNodeConfig() according to configured parameters within hal_sd_node_config_t structure.

   • To get the current SDMMC node configuration, use the HAL_SD_GetNodeConfig() .

   • To set the SD linked list node data buffer state, use the HAL_SD_SetNodeDataBufferState() .

   • To get the SD linked list node data buffer state, use the HAL_SD_GetNodeDataBufferState() .

   • To get the SD linked list node information, use the HAL_SD_GetNodeInfo() .

   • To set the SD linked list node address, use the HAL_SD_SetNodeAddress() .

   • To get the SD linked list node address, use the HAL_SD_GetNodeAddress() .

8. SD Delay Block functions: The delay block (DLYB) is used to generate an output clock that is dephased from the input clock.

   • Use HAL_SD_SetConfigDlybDelay() to set the SD delay block configuration.

   • Use HAL_SD_GetDlybOutputClockPhase() to get the SD delay block output clock phase.

   • Use HAL_SD_CalculateDlybMaxClockPhase() to calculate the SD delay block maximum output clock phase.

   • Use HAL_SD_EnableDlyb() to enable the SD delay block.

   • Use HAL_SD_DisableDlyb() to disable the SD delay block.

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