HAL SD Functions

Initialization and de-initialization functions

group SD_Exported_Functions_Group1

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

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

  • Call the function HAL_SD_DeInit() to de-initialize the SD card device.

Functions

hal_status_t HAL_SD_Init ( hal_sd_handle_t * hsd , hal_sd_t instance )

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

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – SD handle has been correctly Initialized.

void HAL_SD_DeInit ( hal_sd_handle_t * hsd )

De-Initialize the SD card.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Set and Get configurations functions

group SD_Exported_Functions_Group2

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

There are 2 categories of HAL configuration APIs

Functions

hal_status_t HAL_SD_SetConfig ( hal_sd_handle_t * hsd , const hal_sd_config_t * p_config )

Configure the SD according to the user parameters.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

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

  • HAL_OK – SD instance has been correctly configured.

void HAL_SD_GetConfig ( const hal_sd_handle_t * hsd , hal_sd_config_t * p_config )

Get the SD configuration.

Parameters :
hal_status_t HAL_SD_NotifyCardInsertion ( hal_sd_handle_t * hsd , const hal_sd_config_t * p_config )

Notify SD card after insertion.

Parameters :
Return values :

  • HAL_ERROR – An error has occurred.

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

hal_status_t HAL_SD_NotifyCardRemoval ( hal_sd_handle_t * hsd )

Notify SD card after removal.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

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

hal_status_t HAL_SD_SetDataTimeout ( hal_sd_handle_t * hsd , uint32_t data_timeout_cycle )

Set SD data timeout.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • data_timeout_cycle – SD data timeout cycle.

Return values :

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

uint32_t HAL_SD_GetDataTimeout ( const hal_sd_handle_t * hsd )

Get SD data timeout.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

uint32_t – data_timeout_cycle value in millisecond.

hal_status_t HAL_SD_SetStopXferTimeout ( hal_sd_handle_t * hsd , uint32_t stopxfer_timeout_ms )

Set SD stop transfer timeout.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • stopxfer_timeout_ms – SD stop xfer timeout.

Return values :

HAL_OK – When SD card sets correctly the stop xfer timeout in millisecond.

uint32_t HAL_SD_GetStopXferTimeout ( const hal_sd_handle_t * hsd )

Get SD stop transfer timeout.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

uint32_t – stop_xfer_timeout_ms value in millisecond.

hal_status_t HAL_SD_SetEraseTimeout ( hal_sd_handle_t * hsd , uint32_t erase_timeout_ms )

Set SD erase timeout.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • erase_timeout_ms – SD erase timeout.

Return values :

HAL_OK – When SD card sets correctly the erase timeout value in millisecond.

uint32_t HAL_SD_GetEraseTimeout ( const hal_sd_handle_t * hsd )

Get SD erase timeout.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

uint32_t – erase_timeout_ms value in millisecond.

Input and Output operation functions

group SD_Exported_Functions_Group3

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

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

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

Functions

hal_status_t HAL_SD_Erase ( hal_sd_handle_t * hsd , uint32_t start_block_addr , uint32_t end_block_addr )

Erases the specified memory area of the given SD card.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Parameters :

  • hsd – Pointer to hal_sd_handle_t structure.

  • start_block_addr – Start Block address.

  • end_block_addr – End of Block address.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_ReadBlocks ( hal_sd_handle_t * hsd , uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr , uint32_t timeout_ms )

Reads block(s) from a specified address in a card. The Data transfer is managed by polling mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address from where the data is to be read.

  • blocks_nbr – Number of SD blocks to read.

  • timeout_ms – Specify timeout value.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_WriteBlocks ( hal_sd_handle_t * hsd , const uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr , uint32_t timeout_ms )

Allows to write block(s) to a specified address in a card. The Data transfer is managed by polling mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address where the data is written.

  • blocks_nbr – Number of SD blocks to write.

  • timeout_ms – Specify timeout value.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_ReadBlocks_IT ( hal_sd_handle_t * hsd , uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr )

Reads block(s) from a specified address in a card. The Data transfer is managed in interrupt mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the IT transfer process through the SD Rx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address from where the data is to be read.

  • blocks_nbr – Number of blocks to read.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_WriteBlocks_IT ( hal_sd_handle_t * hsd , uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr )

Writes block(s) to a specified address in a card. The Data transfer is managed in interrupt mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the IT transfer process through the SD Tx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address where data is written.

  • blocks_nbr – Number of blocks to write.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_ReadBlocks_DMA ( hal_sd_handle_t * hsd , uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr )

Reads block(s) from a specified address in a card. The Data transfer is managed by DMA mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the DMA transfer process through the SD Rx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address from where the data is to be read.

  • blocks_nbr – Number of SD blocks to read.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_WriteBlocks_DMA ( hal_sd_handle_t * hsd , uint8_t * p_data , uint32_t block_addr , uint32_t blocks_nbr )

Writes block(s) to a specified address in a card. The Data transfer is managed by DMA mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the DMA transfer process through the SD Tx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

  • block_addr – Block Address where data is written.

  • blocks_nbr – Number of SD blocks to write.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_ReadBlocks_LinkedList ( hal_sd_handle_t * hsd , uint32_t block_addr , uint32_t blocks_nbr , const hal_q_t * p_q )

Reads block(s) from a specified address in a card. The Data transfer is managed by DMA mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the DMA transfer process through the SD Rx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • block_addr – Block Address from where data is to be read.

  • blocks_nbr – Number of SD blocks to read.

  • p_q – Pointer to a hal_q_t structure that contains the configuration information for the Q.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_WriteBlocks_LinkedList ( hal_sd_handle_t * hsd , uint32_t block_addr , uint32_t blocks_nbr , const hal_q_t * p_q )

Writes block(s) to a specified address in a card. The Data transfer is managed by DMA mode.

Warning

This API must be followed by a check on the card state through HAL_SD_GetCardState() .

Warning

It could also check the DMA transfer process through the SD Tx interrupt event.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • block_addr – Block Address where the data is written.

  • blocks_nbr – Number of SD blocks to write.

  • p_q – Pointer to a hal_q_t structure that contains the configuration information for the Q.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_ERROR – An error has occurred.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_OK – Operation completed.

hal_status_t HAL_SD_Abort ( hal_sd_handle_t * hsd )

Abort the current transfer.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SD_Abort_IT ( hal_sd_handle_t * hsd )

Abort the current transfer in IT mode.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

IRQHandler and Callbacks Functions

group SD_Exported_Functions_Group4

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

Functions

void HAL_SD_IRQHandler ( hal_sd_handle_t * hsd )

This function handles SD card interrupt request.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

void HAL_SD_XferCpltCallback ( hal_sd_handle_t * hsd , hal_sd_event_cb_t cb_event )

Xfer Transfer completed callbacks.

Parameters :
void HAL_SD_ErrorCallback ( hal_sd_handle_t * hsd )

error callbacks.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

void HAL_SD_AbortCallback ( hal_sd_handle_t * hsd )

Abort callbacks.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

void HAL_SD_DriveTransceiver_1_8V_Callback ( hal_sd_handle_t * hsd , hal_sd_transceiver_state_t state )

Enable/Disable the SD Transceiver 1.8V Mode Callback.

Parameters :
hal_status_t HAL_SD_RegisterXferCpltCallback ( hal_sd_handle_t * hsd , hal_sd_xfer_cb_t callback )

Register the SD Xfer Callback to be used instead of the weak HAL_SD_XferCpltCallback predefined callback.

Parameters :

  • hsd – Pointer to a hal_sd_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_SD_RegisterErrorCpltCallback ( hal_sd_handle_t * hsd , hal_sd_cb_t callback )

Register the SD Error Callback to be used instead of the weak HAL_SD_ErrorCallback predefined callback.

Parameters :

  • hsd – Pointer to a hal_sd_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_SD_RegisterAbortCpltCallback ( hal_sd_handle_t * hsd , hal_sd_cb_t callback )

Register the SD Abort Callback to be used instead of the weak HAL_SD_AbortCallback predefined callback.

Parameters :

  • hsd – Pointer to a hal_sd_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_SD_RegisterTransceiverCallback ( hal_sd_handle_t * hsd , hal_sd_transceiver_cb_t callback )

Register a User SD Transceiver Callback to be used instead of the weak HAL_SD_DriveTransceiver_1_8V_Callback predefined callback.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

  • callback – Pointer to the Callback function.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Register completed successfully.

linked-list queue functions

group SD_Exported_Functions_Group7

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

Functions

hal_status_t HAL_SD_FillNodeConfig ( hal_sd_node_t * p_node , void * p_buffer , uint32_t size_byte )

Build the SD linked-list node.

Parameters :

  • p_node – Pointer to new node to build.

  • p_buffer – Pointer to buffer node.

  • size_byte – size of the node in byte.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Operation completed.

void HAL_SD_GetNodeConfig ( const hal_sd_node_t * p_node , uint32_t * p_buffer , uint32_t * p_size_byte )

Get the SD node configuration.

Parameters :

  • p_node – Pointer to hal_sd_node_t node structure.

  • p_buffer – Pointer to buffer node.

  • p_size_byte – Pointer to the size of the node in byte.

hal_status_t HAL_SD_SetNodeDataBufferState ( const hal_sd_node_t * p_node , hal_sd_node_state_t state )

Set SD linked list node data buffer state.

Parameters :

  • p_node – Pointer to node.

  • state – Node state.

Return values :

  • HAL_INVALID_PARAM – Invalid parameter.

  • HAL_OK – Operation completed.

hal_sd_node_state_t HAL_SD_GetNodeDataBufferState ( const hal_sd_node_t * p_node )

Get SD linked list node data buffer state.

Parameters :

p_node – Pointer to node.

Return values :

  • HAL_SD_DATA_BUFFER_NOT_READY – SD Data buffer node is not ready.

  • HAL_SD_DATA_BUFFER_READY – SD Data buffer node is ready.

void HAL_SD_GetNodeInfo ( uint32_t * next_offset_addr , hal_q_addressing_mode_t * p_addressing_mode )

Get SD Card Node information.

Parameters :

  • next_offset_addr – next node address offset.

  • p_addressing_mode – node addressing mode.

void HAL_SD_SetNodeAddress ( uint32_t head_node_addr , uint32_t prev_node_addr , uint32_t next_node_addr , uint32_t node_addr_offset )

Set SD Card node address.

Parameters :

  • head_node_addr – Head node address.

  • prev_node_addr – Previous node address.

  • next_node_addr – Next node address.

  • node_addr_offset – Node address offset.

uint32_t HAL_SD_GetNodeAddress ( uint32_t head_node_addr , uint32_t current_node_addr , uint32_t node_addr_offset )

Get SD Card node address.

Parameters :

  • head_node_addr – Head node address.

  • current_node_addr – Current node address.

  • node_addr_offset – Node address offset.

Return values :

SDMMC – node address.

SD Delay Block functions

group SD_Exported_Functions_Group8

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

Functions

hal_status_t HAL_SD_SetConfigDlybDelay ( const hal_sd_handle_t * hsd , uint32_t clock_phase_value )

Set the SD delay block configuration.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure.

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

Return values :

  • HAL_ERROR – An error has occurred.

  • HAL_OK – The delay is correctly set.

uint32_t HAL_SD_GetDlybOutputClockPhase ( const hal_sd_handle_t * hsd )

Get the SD delay block output clock phase.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

uint32_t – output clock phase value.

hal_status_t HAL_SD_CalculateDlybMaxClockPhase ( hal_sd_handle_t * hsd , uint32_t * p_max_clock_phase )

Calculate the SD delay block maximum output clock phase.

Parameters :

  • hsd – Pointer to a hal_sd_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_BUSY – Concurrent process ongoing.

  • HAL_OK – The max clock phase is correctly calculated.

hal_status_t HAL_SD_EnableDlyb ( hal_sd_handle_t * hsd )

Enable the SD delay block.

Parameters :

hsd – Pointer to a hal_mm_handle_t structure.

Return values :

HAL_OK – The delay block is enabled.

hal_status_t HAL_SD_DisableDlyb ( hal_sd_handle_t * hsd )

Disable the SD delay block.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

HAL_OK – The delay block is disabled.

hal_sd_dlyb_state_t HAL_SD_IsEnabledDlyb ( hal_sd_handle_t * hsd )

Check if the delay block peripheral is enabled or not.

Parameters :

hsd – Pointer to a hal_sd_handle_t structure.

Return values :

  • HAL_SD_DLYB_DISABLED – Delay block is disabled.

  • HAL_SD_DLYB_ENABLED – Delay block is enabled.

Interrupt And Flag Configuration

group SD_Exported_Functions_Group6

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

Functions

void HAL_SD_EnableIT ( hal_sd_handle_t * hsd , uint32_t interrupt )

Enable the SD device interrupt.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure that contains the configuration information for the SD.

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

void HAL_SD_DisableIT ( hal_sd_handle_t * hsd , uint32_t interrupt )

Disable the SD device interrupt.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure that contains the configuration information for the SD.

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

uint32_t HAL_SD_IsActiveFlag ( const hal_sd_handle_t * hsd , uint32_t flag )

Check whether the specified SD flag is set or not.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure that contains the configuration information for the SD.

  • flag – Specifies the flag source to check. This parameter can be a combination of Flags Sources group.

Return values :

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

void HAL_SD_ClearFlag ( hal_sd_handle_t * hsd , uint32_t flag )

Clear the SD pending flags.

Parameters :

  • hsd – Pointer to a hal_sd_handle_t structure that contains the configuration information for the SD.

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