HAL SPI Functions

Initialization / De-Initialization functions

group SPI_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and de-initialize the SPIx peripheral:

  • Call the function HAL_SPI_Init() to initialize the selected SPI handle and associate an instance.

  • Call the function HAL_SPI_DeInit() to restore the default initialization of the selected SPIx peripheral.

Functions

hal_status_t HAL_SPI_Init ( hal_spi_handle_t * hspi , hal_spi_t instance )

Initialize the SPI according to the associated handle.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • instance – SPI instance.

Return values :

  • HAL_INVALID_PARAM – When the handle is NULL.

  • HAL_ERROR – When the MUTEX cannot be created.

  • HAL_OK – HAL SPI driver correctly Initialized for the given SPI instance.

void HAL_SPI_DeInit ( hal_spi_handle_t * hspi )

De-Initialize the HAL SPI driver for the given handle.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

General Config functions

group SPI_Exported_Functions_Group2

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

  • Call the function HAL_SPI_SetConfig() to configure the selected device with the selected configuration:

    • Mode

    • Direction

    • Data Width

    • Clock Polarity and Phase

    • Baud Rate Prescaler

    • FirstBit

    • Chip select management

  • Call the function HAL_SPI_GetConfig() to retrieve the current global configuration set by the user.

Functions

hal_status_t HAL_SPI_SetConfig ( hal_spi_handle_t * hspi , const hal_spi_config_t * p_config )

Set the configuration to the SPI peripheral.

Parameters :
Return values :

  • HAL_INVALID_PARAM – Invalid parameters.

  • HAL_ERROR – When io locked.

  • HAL_OK – SPI instance has been correctly configured.

void HAL_SPI_GetConfig ( const hal_spi_handle_t * hspi , hal_spi_config_t * p_config )

Retrieve the configuration from the SPI peripheral.

Parameters :

Features functions

group SPI_Exported_Functions_Group3

This subsection provides a set of functions allowing to configure some additional features for the selected SPIx peripheral.

There are two types of features, features with configuration parameters and features without configuration parameters.

For each feature that has a configuration structure, there are those dedicated APIs:

There is a specific case for always-on features which cannot be disabled (NSS and Underrun detection), there are those dedicated APIs:

For each feature without parameters (TI Mode, Master Receiver Auto Suspend, Master Keep IO State, IO Swap and Ready Pin management), there are those dedicated APIs:

Functions

hal_status_t HAL_SPI_SetConfigCRC ( hal_spi_handle_t * hspi , const hal_spi_crc_config_t * p_config )

Configure the CRC feature.

Parameters :
Return values :

  • HAL_INVALID_PARAM – in case of invalid parameter allocation such as a null config pointer.

  • HAL_OK – in case of valid configuration.

void HAL_SPI_GetConfigCRC ( const hal_spi_handle_t * hspi , hal_spi_crc_config_t * p_config )

Retrieve the current CRC configuration.

Parameters :
hal_status_t HAL_SPI_EnableCRC ( const hal_spi_handle_t * hspi )

Enable the CRC feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – CRC feature enabled successfully.

hal_status_t HAL_SPI_DisableCRC ( const hal_spi_handle_t * hspi )

Disable the CRC feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – CRC feature disabled successfully.

hal_spi_crc_status_t HAL_SPI_IsEnabledCRC ( const hal_spi_handle_t * hspi )

Retrieve CRC status for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_crc_status_t – SPI CRC feature status.

hal_status_t HAL_SPI_SetConfigNSS ( hal_spi_handle_t * hspi , const hal_spi_nss_config_t * p_config )

Configure the NSS feature.

Parameters :
Return values :

  • HAL_INVALID_PARAM – in case of invalid parameter allocation.

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – in case of valid configuration.

void HAL_SPI_GetConfigNSS ( const hal_spi_handle_t * hspi , hal_spi_nss_config_t * p_config )

Retrieve the current NSS configuration.

Parameters :
hal_status_t HAL_SPI_SLAVE_SetConfigUnderrun ( const hal_spi_handle_t * hspi , const hal_spi_underrun_config_t * p_config )

Configure the Underrun detection mode feature.

Parameters :
Return values :

  • HAL_INVALID_PARAM – in case of invalid parameter allocation.

  • HAL_OK – in case of valid configuration.

void HAL_SPI_SLAVE_GetConfigUnderrun ( const hal_spi_handle_t * hspi , hal_spi_underrun_config_t * p_config )

Retrieve the current underrun detection configuration.

Parameters :
hal_status_t HAL_SPI_EnableTIMode ( hal_spi_handle_t * hspi )

Enable the TI mode feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – TI mode feature enabled successfully.

hal_status_t HAL_SPI_DisableTIMode ( hal_spi_handle_t * hspi )

Disable the TI mode feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – TI mode feature disabled successfully.

hal_spi_ti_mode_status_t HAL_SPI_IsEnabledTIMode ( const hal_spi_handle_t * hspi )

Retrieve the TI mode status for the dedicated SPI.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_ti_mode_status_t – SPI TI mode feature status.

hal_status_t HAL_SPI_MASTER_EnableReceiverAutoSuspend ( const hal_spi_handle_t * hspi )

Enable the master automatic suspension in Receive mode feature for the dedicated SPIx. The automatic suspension is not quite reliable when size of data drops below 8 bits. In this case, a safe suspension can be achieved by combination with delay inserted between data frames applied when MIDI parameter keeps a non zero value; sum of data size and the interleaved SPI cycles must always produce interval at length of 8 SPI clock periods at minimum.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – Master Receiver Automatic Suspension feature enabled successfully.

hal_status_t HAL_SPI_MASTER_DisableReceiverAutoSuspend ( const hal_spi_handle_t * hspi )

Disable the master automatic suspension in Receive mode feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – Master Receiver Automatic Suspension feature disabled successfully.

hal_spi_master_rx_auto_suspend_status_t HAL_SPI_MASTER_IsEnabledReceiverAutoSuspend ( const hal_spi_handle_t * hspi )

Retrieve the master automatic suspension in Receive mode feature status for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_master_rx_auto_suspend_status_t – SPI master receiver automatic suspension feature status.

hal_status_t HAL_SPI_MASTER_EnableKeepIOState ( hal_spi_handle_t * hspi )

Enable the alternate function GPIOs control feature for the dedicated SPIx.

Note

Enabling the “Master Keep IO State” prevents any glitches on the associated outputs configured at alternate function mode by keeping them forced at state corresponding the current SPI configuration.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Master Keep IO State feature enabled successfully.

hal_status_t HAL_SPI_MASTER_DisableKeepIOState ( hal_spi_handle_t * hspi )

Disable the alternate function GPIOs control feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Master Keep IO State feature disabled successfully.

hal_spi_master_keep_io_state_status_t HAL_SPI_MASTER_IsEnabledKeepIOState ( const hal_spi_handle_t * hspi )

Retrieve the alternate function GPIOs control feature status for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_master_keep_io_state_status_t – SPI mster keep IO state feature status.

hal_status_t HAL_SPI_EnableMosiMisoSwap ( hal_spi_handle_t * hspi )

Enable the MISO/MOSI alternate functions inversion feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – IO Swap feature enabled successfully.

hal_status_t HAL_SPI_DisableMosiMisoSwap ( hal_spi_handle_t * hspi )

Disable the MISO/MOSI alternate functions inversion feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – IO Swap feature disabled successfully.

hal_spi_mosi_miso_swap_status_t HAL_SPI_IsEnabledMosiMisoSwap ( const hal_spi_handle_t * hspi )

Retrieve the MISO/MOSI alternate functions inversion feature status for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_mosi_miso_swap_status_t – SPI IO swap feature status.

hal_status_t HAL_SPI_EnableReadyPin ( hal_spi_handle_t * hspi )

Enable the ready pin feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Ready Pin feature enabled successfully.

hal_status_t HAL_SPI_DisableReadyPin ( hal_spi_handle_t * hspi )

Disable the ready pin feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Ready Pin feature disabled successfully.

hal_spi_ready_pin_status_t HAL_SPI_IsEnabledReadyPin ( const hal_spi_handle_t * hspi )

Retrieve the ready pin feature status for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_ready_pin_status_t – SPI ready pin management feature status.

hal_status_t HAL_SPI_SetReadyPinPolarity ( hal_spi_handle_t * hspi , hal_spi_ready_pin_polarity_t polarity )

Set the ready pin polarity for the dedicated SPIx.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Ready Pin polarity set successfully.

hal_spi_ready_pin_polarity_t HAL_SPI_GetReadyPinPolarity ( const hal_spi_handle_t * hspi )

Retrieve the ready pin polarity of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_ready_pin_polarity_t – Current ready pin polarity.

hal_status_t HAL_SPI_LockIOConfig ( const hal_spi_handle_t * hspi )

Lock the IO configuration for the dedicated SPI.

Note

The reset of the IOLock bit is done by hardware.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – Operation completed successfully.

hal_spi_io_cfg_status_t HAL_SPI_IsLockedIOConfig ( const hal_spi_handle_t * hspi )

Retrieve the IO configuration lock status for the dedicated SPI.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_io_cfg_status_t. –

Autonomous Mode functions

group SPI_Exported_Functions_Group4

This subsection provides a set of functions allowing to use the autonomous mode feature for the SPIx instance. Prior to use the autonomous mode feature, one has to configure one’s instance in asynchronous mode with HAL_SPI_SetConfig() . A set of functions is provided to use the autonomous mode feature:

Functions

hal_status_t HAL_SPI_AM_SetConfigTrigger ( const hal_spi_handle_t * hspi , const hal_spi_am_trig_config_t * p_config )

Configure the Autonomous mode feature.

Parameters :
Return values :

  • HAL_INVALID_PARAM – in case of invalid parameter allocation.

  • HAL_OK – in case of valid configuration.

void HAL_SPI_AM_GetConfigTrigger ( const hal_spi_handle_t * hspi , hal_spi_am_trig_config_t * p_config )

Retrieve the current autonomous mode configuration.

Parameters :
hal_status_t HAL_SPI_AM_EnableTrigger ( const hal_spi_handle_t * hspi )

Enable the autonomous mode feature for the dedicated SPIx.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – Autonomous mode feature enabled successfully.

hal_status_t HAL_SPI_AM_DisableTrigger ( const hal_spi_handle_t * hspi )

Disable the autonomous mode feature for the dedicated SPI.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

HAL_OK – Autonomous mode feature disabled successfully.

hal_spi_am_trig_status_t HAL_SPI_AM_IsEnabledTrigger ( const hal_spi_handle_t * hspi )

Retrieve the autonomous mode status for the dedicated SPI.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_am_trig_status_t – SPI autonomous mode feature status.

Items functions

group SPI_Exported_Functions_Group5

This subsection provides a set of functions allowing to change and retrieve a single configuration item in the IDLE state.

Functions

hal_status_t HAL_SPI_SetMode ( hal_spi_handle_t * hspi , const hal_spi_mode_t mode )

Set the mode of the SPI peripheral.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_mode_t HAL_SPI_GetMode ( const hal_spi_handle_t * hspi )

Retrieve the mode of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_mode_t – Current SPI mode configuration.

hal_status_t HAL_SPI_SetDirection ( hal_spi_handle_t * hspi , const hal_spi_direction_t direction )

Set the direction of the SPI peripheral.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_direction_t HAL_SPI_GetDirection ( const hal_spi_handle_t * hspi )

Retrieve the direction of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_direction_t – Current SPI direction configuration.

hal_status_t HAL_SPI_SetDataWidth ( const hal_spi_handle_t * hspi , const hal_spi_data_width_t data_width )

Set the data width for the SPI peripheral.

Parameters :
Return values :

HAL_OK – Operation completed successfully.

hal_spi_data_width_t HAL_SPI_GetDataWidth ( const hal_spi_handle_t * hspi )

Retrieve the data width of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_data_width_t – Current SPI data width configuration.

hal_status_t HAL_SPI_SetClockPolarity ( hal_spi_handle_t * hspi , const hal_spi_clock_polarity_t clock_polarity )

Set the clock polarity of the SPI peripheral.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_clock_polarity_t HAL_SPI_GetClockPolarity ( const hal_spi_handle_t * hspi )

Retrieve the clock polarity of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_clock_polarity_t – Current SPI clock polarity configuration.

hal_status_t HAL_SPI_SetClockPhase ( hal_spi_handle_t * hspi , const hal_spi_clock_phase_t clock_phase )

Set the active clock edge for the bit capture.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_clock_phase_t HAL_SPI_GetClockPhase ( const hal_spi_handle_t * hspi )

Retrieve the active clock edge for the bit capture of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_clock_phase_t – Current SPI clock phase configuration.

hal_status_t HAL_SPI_SetBaudRatePrescaler ( const hal_spi_handle_t * hspi , const hal_spi_baud_rate_prescaler_t baud_rate_prescaler )

Set the Baud Rate prescaler value which is used to configure the transmit and receive SCK clock.

Parameters :
Return values :

HAL_OK – Operation completed successfully.

hal_spi_baud_rate_prescaler_t HAL_SPI_GetBaudRatePrescaler ( const hal_spi_handle_t * hspi )

Retrieve the baud rate prescaler of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_baud_rate_prescaler_t – Current SPI clock baud rate prescaler configuration.

hal_status_t HAL_SPI_SetFirstBit ( hal_spi_handle_t * hspi , const hal_spi_first_bit_t first_bit )

Set whether data transfers start from MSB or LSB bit.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_first_bit_t HAL_SPI_GetFirstBit ( const hal_spi_handle_t * hspi )

Retrieve the first bit (MSB or LSB bit) of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_first_bit_t – Current SPI first bit configuration.

hal_status_t HAL_SPI_SetNSSPinManagement ( hal_spi_handle_t * hspi , hal_spi_nss_pin_management_t nss_pin_management )

Set the management configuration of the NSS Pin.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_nss_pin_management_t HAL_SPI_GetNSSPinManagement ( const hal_spi_handle_t * hspi )

Retrieve the NSS Pin management of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_nss_pin_management_t – Current SPI NSS Pin management configuration.

hal_status_t HAL_SPI_SetFifoThreshold ( const hal_spi_handle_t * hspi , const hal_spi_fifo_threshold_t fifo_threshold )

Set the FIFO threshold level.

Parameters :
Return values :

HAL_OK – Operation completed successfully.

hal_spi_fifo_threshold_t HAL_SPI_GetFifoThreshold ( const hal_spi_handle_t * hspi )

Retrieve the FIFO threshold level of the SPI peripheral.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_fifo_threshold_t – Current FIFO threshold configuration.

hal_status_t HAL_SPI_MASTER_SetInterDataIdlenessDelay ( hal_spi_handle_t * hspi , const hal_spi_master_inter_data_idleness_delay_t nb_cycles )

Set an extra delay, expressed in number of SPI clock cycle periods, inserted additionally between active edge of SS and first data transaction start in master mode.

Parameters :
Return values :

  • HAL_ERROR – when the IO configuration register (SPI_CFG2) is locked.

  • HAL_OK – Operation completed successfully.

hal_spi_master_inter_data_idleness_delay_t HAL_SPI_MASTER_GetInterDataIdlenessDelay ( const hal_spi_handle_t * hspi )

Retrieve the extra delay, expressed in number of SPI clock cycle periods, inserted additionally between active edge of SS and first data transaction start in master mode.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_master_inter_data_idleness_delay_t – Current inter data idleness delay.

void HAL_SPI_SetUserData ( hal_spi_handle_t * hspi , const void * p_user_data )

Store User Data pointer into the handle.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_user_data – Pointer to the user data.

const void * HAL_SPI_GetUserData ( const hal_spi_handle_t * hspi )

Retrieve User Data pointer from the handle.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

Pointer – to the user data.

hal_status_t HAL_SPI_SetTxDMA ( hal_spi_handle_t * hspi , hal_dma_handle_t * hdma )

Link the Transmit DMA handle to the SPI handle.

Parameters :
Return values :

HAL_INVALID_PARAM – Invalid parameter.

hal_status_t HAL_SPI_SetRxDMA ( hal_spi_handle_t * hspi , hal_dma_handle_t * hdma )

Link the Receive DMA handle to the SPI handle.

Parameters :
Return values :

HAL_INVALID_PARAM – Invalid parameter.

IO operation functions

group SPI_Exported_Functions_Group6

This subsection provides a set of functions allowing to manage the SPI data transfers.

The SPI supports master and slave mode :

  • There are two modes of transfer:

    • Blocking mode: The communication is performed in polling mode. The HAL status of all data processing is returned by the same function after finishing transfer.

    • No-Blocking mode: The communication is performed using Interrupts or DMA, these APIs return the HAL status. The end of the data processing will be indicated through the dedicated SPI IRQ when using Interrupt mode or the DMA IRQ when using DMA mode. The HAL_SPI_TxCpltCallback() , HAL_SPI_RxCpltCallback() and HAL_SPI_TxRxCpltCallback() user callbacks will be executed respectively at the end of the Transmit or Receive process. The HAL_SPI_ErrorCallback() user callback will be executed when a communication error is detected.

  • APIs provided for these 2 transfer modes (Blocking mode or Non blocking mode using either Interrupt or DMA) exist for simplex, half-duplex and full-duplex modes.

Functions

hal_status_t HAL_SPI_Transmit ( hal_spi_handle_t * hspi , const void * p_data , uint32_t count_packet , uint32_t timeout_ms )

Transmit an amount of data in blocking mode.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be sent.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

  • HAL_TIMEOUT – Operation exceeds user timeout.

hal_status_t HAL_SPI_Receive ( hal_spi_handle_t * hspi , void * p_data , uint32_t count_packet , uint32_t timeout_ms )

Receive an amount of data in blocking mode.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be received.

  • timeout_ms – Timeout duration in milliseconds.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

  • HAL_TIMEOUT – Operation exceeds user timeout.

hal_status_t HAL_SPI_TransmitReceive ( hal_spi_handle_t * hspi , const void * p_tx_data , void * p_rx_data , uint32_t count_packet , uint32_t timeout_ms )

Transmit and Receive an amount of data in blocking mode.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_tx_data – Pointer to transmission data buffer.

  • p_rx_data – Pointer to reception data buffer.

  • count_packet – Amount of data to be exchanged in full-duplex. The process manages the same number of data for rx and tx transfer.

  • timeout_ms – Timeout duration.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_TIMEOUT – Operation exceeds user timeout.

hal_status_t HAL_SPI_Transmit_IT ( hal_spi_handle_t * hspi , const void * p_data , uint32_t count_packet )

Transmit an amount of data in non-blocking mode with Interrupt.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be sent.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_SPI_Receive_IT ( hal_spi_handle_t * hspi , void * p_data , uint32_t count_packet )

Receive an amount of data in non-blocking mode with Interrupt.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be sent.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_SPI_TransmitReceive_IT ( hal_spi_handle_t * hspi , const void * p_tx_data , void * p_rx_data , uint32_t count_packet )

Transmit and Receive an amount of data in non-blocking mode with Interrupt.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_tx_data – Pointer to transmission data buffer.

  • p_rx_data – Pointer to reception data buffer.

  • count_packet – Amount of data to be exchanged in full-duplex. The process manages the same number of data for rx and tx transfer.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_SPI_Transmit_DMA ( hal_spi_handle_t * hspi , const void * p_data , uint32_t count_packet )

Transmit an amount of data in non-blocking mode with DMA.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be sent.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SPI_Receive_DMA ( hal_spi_handle_t * hspi , void * p_data , uint32_t count_packet )

Receive an amount of data in non-blocking mode with DMA.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_data – Pointer to data buffer.

  • count_packet – Amount of data to be sent.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SPI_TransmitReceive_DMA ( hal_spi_handle_t * hspi , const void * p_tx_data , void * p_rx_data , uint32_t count_packet )

Transmit and Receive an amount of data in non-blocking mode with DMA.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_tx_data – Pointer to transmission data buffer.

  • p_rx_data – Pointer to reception data buffer.

  • count_packet – Amount of data to be exchanged in full-duplex. The process manages the same number of data for rx and tx transfer.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_BUSY – Concurrent process ongoing.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SPI_Abort ( hal_spi_handle_t * hspi )

Abort ongoing transfer (blocking mode).

Note

This procedure could be used for aborting any ongoing transfer (Tx and Rx), started in Interrupt or DMA mode.

Note

This procedure performs following operations :

  • Disable SPI Interrupts (depending of transfer direction).

  • Disable the DMA transfer in the peripheral register (if enabled).

  • Abort DMA transfer by calling HAL_DMA_Abort (in case of transfer in DMA mode).

  • Set handle State to READY.

Note

This procedure is executed in blocking mode : when exiting function, Abort is considered as completed.

Note

After the abort, other process (Tx, Rx or TxRx) can be started.

Parameters :

hspi – SPI handle.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SPI_Abort_IT ( hal_spi_handle_t * hspi )

Abort ongoing transfer (Interrupt mode).

Note

This procedure could be used for aborting any ongoing transfer (Tx and Rx), started in Interrupt or DMA mode.

Note

This procedure performs following operations :

  • Disable SPI Interrupts (depending of transfer direction).

  • Disable the DMA transfer in the peripheral register (if enabled).

  • Abort DMA transfer by calling HAL_DMA_Abort_IT (in case of transfer in DMA mode).

  • Set handle State to READY.

  • At abort completion, call user abort complete callback.

Note

This procedure is executed in Interrupt mode, meaning that abort procedure could be considered as completed only when user abort complete callback is executed (not when exiting function).

Parameters :

hspi – SPI handle.

Return values :

  • HAL_OK – Operation completed successfully.

  • HAL_ERROR – Operation completed with error.

IRQ Handler/Callbacks/Register Callbacks functions

group SPI_Exported_Functions_Group7

This subsection provides a set of functions allowing to register the SPI process and error callbacks:

There are two ways to use callbacks: Override weak callbacks functions:

Or register callbacks user:

HAL_SPI_IRQHandler() is designed to process the different interruptions :

  • Error interruptions during transfer (OVR, UDR, MODF, TIFRE)

  • Transfer interruptions (DXP, RXP, TXP, EOT)

Depending on the process function one’s use, different callback might be triggered:

Process API

\

Callbacks

HAL_SPI_Transmit_IT

HAL_SPI_Receive_IT

HAL_SPI_TransmitReceive_IT

HAL_SPI_TxCpltCallback

x

HAL_SPI_RxCpltCallback

x

HAL_SPI_TxRxCpltCallback

x

HAL_SPI_SuspendCallback

x

x

x

HAL_SPI_ErrorCallback

x

x

x

Process API

\

Callbacks

HAL_SPI_Transmit_DMA

HAL_SPI_Receive_DMA

HAL_SPI_TransmitReceive_DMA

HAL_SPI_TxHalfCpltCallback*

x

HAL_SPI_TxCpltCallback

x

HAL_SPI_RxHalfCpltCallback*

x

HAL_SPI_RxCpltCallback

x

HAL_SPI_TxRxHalfCpltCallback*

x

HAL_SPI_TxRxCpltCallback

x

HAL_SPI_ErrorCallback**

x

x

x

Process API

\

Callbacks

HAL_SPI_Abort_IT

HAL_SPI_AbortCpltCallback

x

HAL_SPI_ErrorCallback

x

Note

* these callbacks might be called following DMA IRQ management, not SPIx IRQ management.

Note

** these callbacks might be called following DMA IRQ management, or SPIx IRQ management.

Functions

void HAL_SPI_IRQHandler ( hal_spi_handle_t * hspi )

Handle SPI interrupt request.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_TxCpltCallback ( hal_spi_handle_t * hspi )

Tx Transfer completed callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_RxCpltCallback ( hal_spi_handle_t * hspi )

Rx Transfer completed callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_TxRxCpltCallback ( hal_spi_handle_t * hspi )

Tx and Rx Transfer completed callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_TxHalfCpltCallback ( hal_spi_handle_t * hspi )

Tx Half Transfer completed callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_RxHalfCpltCallback ( hal_spi_handle_t * hspi )

Rx Half Transfer completed callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_TxRxHalfCpltCallback ( hal_spi_handle_t * hspi )

Tx and Rx Half Transfer callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_ErrorCallback ( hal_spi_handle_t * hspi )

SPI error callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_AbortCpltCallback ( hal_spi_handle_t * hspi )

SPI Abort Complete callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

void HAL_SPI_SuspendCallback ( hal_spi_handle_t * hspi )

SPI Suspend callback.

Warning

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

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

hal_status_t HAL_SPI_RegisterTxCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Tx Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Tx Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterRxCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Rx Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Rx Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterTxRxCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Tx/Rx Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Tx/Rx Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterTxHalfCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Tx half Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Tx half Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterRxHalfCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Rx half Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Rx half Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterTxRxHalfCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI TxRx half Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Rx half Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterErrorCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Error Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Error Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterAbortCpltCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Abort Cplt Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Abort Cplt Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

hal_status_t HAL_SPI_RegisterSuspendCallback ( hal_spi_handle_t * hspi , hal_spi_cb_t p_callback )

Register the SPI Suspend Callback.

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • p_callback – Pointer to the Error Callback function.

Return values :

  • HAL_INVALID_PARAM – invalid Callback pointer.

  • HAL_OK – Register completed successfully.

Peripheral current frequency, state and errors functions

group SPI_Exported_Functions_Group8

This subsection provides 3 functions allowing to read peripheral current frequency, state and last occurred errors.

Functions

uint32_t HAL_SPI_GetClockFreq ( const hal_spi_handle_t * hspi )

Return the peripheral clock frequency for SPI.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • uint32_t – Frequency in Hz.

  • 0 – source clock of the hspi not configured or not ready.

hal_spi_state_t HAL_SPI_GetState ( const hal_spi_handle_t * hspi )

Retrieve the SPI handle state.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

hal_spi_state_t – SPI state.

uint32_t HAL_SPI_GetLastErrorsCodes ( const hal_spi_handle_t * hspi )

Retrieve the SPI errors codes.

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

uint32_t – Returned value can be a combination of the following values:

  • HAL_SPI_ERROR_NONE

  • HAL_SPI_ERROR_MODF

  • HAL_SPI_ERROR_CRC

  • HAL_SPI_ERROR_OVR

  • HAL_SPI_ERROR_FRE

  • HAL_SPI_ERROR_DMA

  • HAL_SPI_ERROR_ABORT

  • HAL_SPI_ERROR_UDR

Acquire/release Bus functions

group SPI_Exported_Functions_Group9

This subsection provides a set of functions allowing to Acquire/Release the bus based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

Functions

hal_status_t HAL_SPI_AcquireBus ( hal_spi_handle_t * hspi , uint32_t timeout_ms )

Acquire the SPI bus thanks to the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_SPI_AcquireBus function must be called from thread mode only (not from handler mode i.e from ISR).

Parameters :

  • hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

  • timeout_ms – Time to wait before the bus is occupied by the handle.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_ERROR – Operation completed with error.

hal_status_t HAL_SPI_ReleaseBus ( hal_spi_handle_t * hspi )

Release the SPI bus thanks to the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_SPI_ReleaseBus function can be called from thread mode or from handler mode i.e from ISR

Parameters :

hspi – Pointer to a hal_spi_handle_t structure which contains the SPI instance.

Return values :

  • HAL_OK – Operation started successfully.

  • HAL_ERROR – Operation completed with error.