HAL MMC How to Use ¶

group MMC_How_To_Use

How to use this driver ¶

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

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

This driver provides 10 different set of APIs that allows to :

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

   • To initialize the MMC Card, use the HAL_MMC_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_MMC_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_MMC_Init() .

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

2. Set and Get MMC configuration:

   • Configure the MMC card, use the HAL_MMC_SetConfig() to apply the MMC card configuration process, the clock frequency must be less than 400Khz. then, this phase allows the card identification and Get all card information (CSD, EXT CSD, CID, Card Status Register) to ensure that the card has been correctly identified and then, Apply the user parameters. In this stage, the MMC 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 MMC card Erase, read and write operation.

   • To get the MMC card configuration, use the HAL_MMC_GetConfig() to retrieve the current MMC configuration.

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

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

   • According to the MMC 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_MMC_DATA_MAX_TIMEOUT (0xFFFFFFFFU) : Max data timeout

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

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

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

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

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

3. Input and Output operations:

   • Blocking mode: Polling

     • Read from MMC card in polling mode by using function HAL_MMC_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_MMC_GetCardState() function of MMC card state.

     • Write to MMC card in polling mode by using function HAL_MMC_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_MMC_GetCardState() function of the MMC card state.

   • Non-Blocking mode: IT

     • Read from the MMC card in Interrupt mode by using function HAL_MMC_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 MMC card in Interrupt mode by using function HAL_MMC_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 MMC card in DMA mode by using function HAL_MMC_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 MMC xfer interrupt event.

     • Write to MMC card in DMA mode by using function HAL_MMC_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 fueature by enabling the USE_HAL_MMC_LINKEDLIST compilation flag through stm32tnxx_hal_conf.h module. At this stage, Build a linked-list Q using the module Q.

     • Read from the MMC card in linked-list mode by using the function HAL_MMC_ReadBlocks_LinkedList() . This functions 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 MMC card in linked-list mode by using the function HAL_MMC_WriteBlocks_LinkedList() . This functions 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 MMC card by using the HAL_MMC_Abort() to stop the transfer in polling mode

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

4. IRQHandler and Callbacks Functions:

   • All MMC card interrupts requests are handled by the HAL_MMC_IRQHandler function.

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

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

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

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

   • To use the callback registration feature, Set the USE_HAL_MMC_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_MMC_RegisterXferCpltCallback() : To register an xfer callback function.

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

     • HAL_MMC_RegisterAbortCpltCallback() : To register an abort callback function. When The compilation define USE_HAL_MMC_REGISTER_CALLBACKS is set to 0 or not defined, the callback registering feature is not available and weak (surcharged) callbacks are used.

5. MMC Card related information functions:

   • To get the global state, use the HAL_MMC_GetState() .

   • To get the internal state of the MMC card, use the HAL_MMC_GetCardState() .

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

   • To get the MMC Card Identification Data, Set the USE_HAL_MMC_GET_CID to 1U the compilation flag through stm32tnxx_hal_conf.h module and use the function HAL_MMC_GetCardCID() .

   • To retrieve the MMC/EMMC card specification version, use the HAL_MMC_GetCardSpecVersion() .

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

   • To store the user data into the MMC handle, Set the USE_HAL_MMC_USER_DATA to 1U the compilation flag through stm32tnxx_hal_conf.h module and use the function HAL_MMC_SetUserData() .

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

6. MMC Card Peripheral Erase management

   • To perform specific commands sequence for the different type of erase, use the function HAL_MMC_EraseSequence() .

   • To perform sanitize operation on the device, use the function HAL_MMC_Sanitize() .

   • To configure the Secure Removal Type in the Extended CSD register, use the function HAL_MMC_SetSecureRemovalType() .

   • To get the supported type of the Secure Removal, use the function HAL_MMC_GetSecureRemovalType() .

7. MMC Card Peripheral low power management

   • To switch the device from Standby State to Sleep State, use the function HAL_MMC_EnterCardSleepMode() .

   • To switch the device from Sleep State to Standby State, use the function HAL_MMC_ExitCardSleepMode() .

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

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

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

   • To set the MMC linked list node data buffer state, use the HAL_MMC_SetNodeDataBufferState() .

   • To get the MMC linked list node data buffer state, use the HAL_MMC_GetNodeDataBufferState() .

   • To get the MMC linked list node information, use the HAL_MMC_GetNodeInfo() .

   • To set the MMC linked list node address, use the HAL_MMC_SetNodeAddress() .

   • To get the MMC linked list node address, use the HAL_MMC_GetNodeAddress() .

9. MMC Delay Block functions: This subsection provides a set of functions allowing to generate an output clock that is dephased from the input clock.

   • Use HAL_MMC_SetConfigDlybDelay() to set the MMC delay block configuration.

   • Use HAL_MMC_GetDlybOutputClockPhase() to get the MMC delay block output clock phase.

   • Use HAL_MMC_CalculateDlybMaxClockPhase() to calculate the MMC delay block maximum output clock phase.

   • Use HAL_MMC_EnableDlyb() to enable the MMC delay block.

   • Use HAL_MMC_DisableDlyb() to disable the MMC delay block.

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

10. MMC Card Interrupt and flags Inline functions:

    • HAL_MMC_EnableIT() : Enable the MMC device interrupt to generate an interrupt request.

    • HAL_MMC_DisableIT() : Disable the MMC device interrupt to clear an interrupt request.

    • HAL_MMC_IsActiveFlag() : Check whether the specified MMC flag is set or not.

    • HAL_MMC_ClearFlag() : Clear the MMC’s pending flags.

11. MMC Card Replay Protected Memory Block Management (RPMB): This subsection provides a set of functions for managing the Replay Protected Memory Block (RPMB).

    • Before RPMB key programming, read/write data from/to the RPMB area, you need to switch to the RPMB partition area using the API HAL_MMC_SelectPartitionArea() .

    • If the authentication key is not yet programmed, you need to program the RPMB authentication key by calling the API HAL_MMC_ProgramRPMBAuthenticationKey() .

    • Retrieve the current write counter value using the API HAL_MMC_GetRPMBWriteCounter() . This counter is used to prevent replay attacks by ensuring that each write operation has a unique counter value.

    • Generate the MAC for the data to be written. The MAC ensures the integrity and authenticity of the data.

    • Write the authenticated data to the RPMB using the API HAL_MMC_WriteRPMBBlocks() .

    • Read the authenticated data back from the RPMB using the API HAL_MMC_ReadRPMBBlocks() and verify its integrity.

    • Get the RPMB error codes using the API HAL_MMC_GetRPMBErrorCodes() .

    • Get the RPMB partition size area using API HAL_MMC_GetRPMBSize() .