HAL SPI How to Use

group SPI_How_To_Use

The serial peripheral interface (SPI) can be used to communicate with external devices while using the specific synchronous protocol. The SPI protocol supports half-duplex, full-duplex and simplex synchronous, serial communication with external devices. The interface can be configured as master or slave and is capable of operating in multi slave or multi master configurations. The device configured as master provides communication clock (SCK) to the slave device. The Slave select (SS) and ready (RDY) signals can be applied optionally just to setup communication with concrete slave and to assure it handles the data flow properly. The Motorola data format is used by default, but some other specific modes are supported as well.

Main features

• Full-duplex synchronous transfers on three lines

• Half-duplex synchronous transfer on two lines (with bidirectional data line)

• Simplex synchronous transfers on two lines (with unidirectional data line)

• From 4-bit up to 32-bit data size selection or fixed to 8-bit multiples

• Multi master or multi slave mode capability

• Dual clock domain, the peripheral kernel clock is independent from the APB bus clock

• Baud rate prescaler up to kernel frequency/2 or bypass from RCC in Master mode

• Protection of configuration and setting

• Hardware or software management of SS for both master and slave

• Adjustable minimum delays between data and between SS and data flow

• Configurable SS signal polarity and timing, MISO x MOSI swap capability

• Programmable clock polarity and phase with optional sampling delay when reading master data

• Programmable data order with MSB-first or LSB-first shifting

• Programmable number of data within a transaction to control SS and CRC

• Dedicated transmission and reception flags with interrupt capability

• SPI Motorola and TI formats support

• Hardware CRC feature can verify integrity of the communication at the end of transaction by:

  • Adding CRC value in Tx mode

  • Automatic CRC error checking for Rx mode

• Error detection with interrupt capability in case of data overrun, CRC error, data underrun, the mode fault and frame error, depending upon the operating mode

• Two multiples of 8-bit embedded Rx and Tx FIFOs (FIFO size depends on instance)

• Configurable FIFO thresholds (data packing)

• Capability to handle data streams by system DMA controller

• Configurable behavior for slave underrun condition (support of cascaded circular buffers)

• Optional status pin RDY signalizing that the slave device is ready to handle the data flow

How to use

The SPI HAL driver can be used as follows:

• Declare a hal_spi_handle_t handle structure, for example: hal_spi_handle_t hspi;

• Initialize the SPI according to the associated handle with HAL_SPI_Init() Note: Enable the SPI interface clock if you have set USE_HAL_SPI_CLK_ENABLE_MODEL to HAL_CLK_ENABLE_PERIPH_ONLY or HAL_CLK_ENABLE_PERIPH_PWR_SYSTEM (in those cases HAL_SPI_Init() will enable the clock).

• Initialize the SPI low level resources:

  • Enable the SPIx interface clock

  • SPI pins configuration

    • Enable the clock for the SPI GPIOs

    • Configure these SPI pins as alternate function push-pull

  • NVIC configuration if you need to use interrupt process or DMA process

    • Configure the SPIx interrupt priority

    • Enable the NVIC SPI IRQ handle

  • DMA Configuration if you need to use DMA process

    • Declare a hal_dma_handle_t handle structure for the transmit or receive Stream/Channel

    • Enable the DMAx clock

    • Configure the DMA handle parameters

    • Configure the DMA Tx or Rx Stream/Channel

    • Associate the initialized hdma_tx handle to the hspi DMA Tx or Rx handle

    • For each DMA channel (Tx and Rx), configure the corresponding NVIC line priority and enable Tx or Rx Stream/Channel

• Set the generic configuration of the SPI with HAL_SPI_SetConfig() to choose:

  • The mode

  • The direction

  • The data width

  • The clock polarity

  • The clock phase

  • The baud rate prescaler

  • The first bit

  • The NSS pin management

• For an advanced configuration, use the following functions:

  • HAL_SPI_SetConfigCRC() to configure the CRC feature

  • HAL_SPI_SetConfigNSS() to configure the NSS feature

  • HAL_SPI_SLAVE_SetConfigUnderrun() to configure the Underrun Detection feature

  • HAL_SPI_EnableTIMode() to enable the TI mode feature

  • HAL_SPI_MASTER_EnableReceiverAutoSuspend() to enable the Master Receiver automatic suspension feature

  • HAL_SPI_MASTER_EnableKeepIOState() to enable the Master Keep IO State feature

  • HAL_SPI_EnableMosiMisoSwap() to enable the IO Swap feature

  • HAL_SPI_EnableReadyPin() to enable the Ready Pin management feature

  • HAL_SPI_LockIOConfig() to enable the Lock of IO configuration feature

  • HAL_SPI_EnableDelayReadDataSampling() to enable the Delay Read Data Sampling feature

Circular mode restriction:

• The DMA circular mode cannot be used when the SPI is configured in these modes:

  • Master Simplex Rx

  • Master Half duplex Rx

• The CRC feature is not managed when the DMA circular mode is enabled

Callback registration:

The compilation flag USE_HAL_SPI_REGISTER_CALLBACKS allows the user to configure dynamically the driver callbacks, via its own method:

Callback name	Default value	Callback registration function
ErrorCallback	HAL_SPI_ErrorCallback()	HAL_SPI_RegisterErrorCallback()
TxCpltCallback	HAL_SPI_TxCpltCallback()	HAL_SPI_RegisterTxCpltCallback()
RxCpltCallback	HAL_SPI_RxCpltCallback()	HAL_SPI_RegisterRxCpltCallback()
TxRxCpltCallback	HAL_SPI_TxRxCpltCallback()	HAL_SPI_RegisterTxRxCpltCallback()
TxHalfCpltCallback	HAL_SPI_TxHalfCpltCallback()	HAL_SPI_RegisterTxHalfCpltCallback()
RxHalfCpltCallback	HAL_SPI_RxHalfCpltCallback()	HAL_SPI_RegisterRxHalfCpltCallback()
TxRxHalfCpltCallback	HAL_SPI_TxRxHalfCpltCallback()	HAL_SPI_RegisterTxRxHalfCpltCallback()
AbortCpltCallback	HAL_SPI_AbortCpltCallback()	HAL_SPI_RegisterAbortCpltCallback()
SuspendCallback	HAL_SPI_SuspendCallback()	HAL_SPI_RegisterSuspendCallback()

If one needs to unregister a callback, register the default callback via the registration function.

By default, after the HAL_SPI_Init() and when the state is HAL_SPI_STATE_INIT, all callbacks are set to the corresponding default weak functions.

Callbacks can be registered in handle global_state HAL_SPI_STATE_INIT and HAL_SPI_STATE_IDLE.

When the compilation define USE_HAL_SPI_REGISTER_CALLBACKS is set to 0U or not defined, the callback registration feature is not available and weak callbacks are used, represented by the default value in the table above.

Note: HAL_SPI_RegisterTxHalfCpltCallback(), HAL_SPI_RegisterRxHalfCpltCallback() and HAL_SPI_RegisterTxRxHalfCpltCallback() apply only in DMA mode.

SuspendCallback restriction: SuspendCallback is called only when MasterReceiverAutoSuspend is enabled and End Of Transfer (EOF) interrupt is activated. SuspendCallback is used in relation with functions HAL_SPI_Transmit_IT, HAL_SPI_Receive_IT and HAL_SPI_TransmitReceive_IT.