HAL XSPI How to Use

group XSPI_How_To_Use

An explanation of XSPI overall usage:

• XSPI is the abbreviation of Expanded Serial Peripheral Interface. It is an interface that supports most external serial memories such as serial PSRAMs, serial NAND and serial NOR flash memories, HyperRAM and HyperFlash memories, with different functional modes.

This file provides firmware functions to manage the following functions of the XSPI peripheral:

• Initialization and deinitialization functions

• Configuration functions

• Command and I/O operation functions

• IRQHandler, link DMA, and callback functions

• Status functions

• Delay Block functions

• High-speed interface and calibration functions

• Interrupt functions

How to use the XSPI HAL module driver

Initialization and deinitialization functions:

• Declare a hal_xspi_handle_t handle structure, for example: hal_xspi_handle_t hxspi

• Use HAL_XSPI_Init() function to initialize the XSPI handle and associate the physical instance

• Use HAL_XSPI_DeInit() function to abort any ongoing operation then reset the state

Configuration functions

• Use HAL_XSPI_SetConfig() function to configure the Regular/Hyperbus parameters of the XSPI peripheral

• Use HAL_XSPI_GetConfig() function to retrieve the current configuration for the XSPI instance

• Once a global configuration is applied (using HAL_XSPI_SetConfig()), optionally use the following unitary functions to update the different parameters individually:

  • HAL_XSPI_SetFifoThreshold() Configure the FIFO threshold according to the user parameters.

  • HAL_XSPI_GetFifoThreshold() Retrieve the FIFO threshold configuration.

  • HAL_XSPI_SetPrescaler() Configure the prescaler according to the user parameters.

  • HAL_XSPI_GetPrescaler() Retrieve the prescaler configuration.

  • HAL_XSPI_SetMemorySize() Configure the XSPI memory size according to the user parameters.

  • HAL_XSPI_GetMemorySize() Retrieve the XSPI memory size configuration.

  • HAL_XSPI_SetMemoryType() Configure the XSPI memory type according to the user parameters.

  • HAL_XSPI_GetMemoryType() Retrieve the XSPI memory type configuration.

  • HAL_XSPI_SetMemorySelection() Configure the nCS used for memory selection.

  • HAL_XSPI_GetMemorySelection() Retrieve the nCS used for memory selection.

  • HAL_XSPI_EnableFreeRunningClock() Enable the free-running clock.

  • HAL_XSPI_DisableFreeRunningClock() Disable the free-running clock.

  • HAL_XSPI_IsEnabledFreeRunningClock() Check whether the free-running clock is enabled.

  • HAL_XSPI_EnablePrefetchData() Enable automatic prefetch in the external memory (reset value).

  • HAL_XSPI_DisablePrefetchData() Disable automatic prefetch in the external memory.

  • HAL_XSPI_IsEnabledPrefetchData() Check the state of automatic prefetch in the external memory.

  • HAL_XSPI_EnablePrefetchAXI() Enable prefetch for signaled AXI transactions (reset value).

  • HAL_XSPI_DisablePrefetchAXI() Disable prefetch for signaled AXI transactions.

  • HAL_XSPI_IsEnabledPrefetchAXI() Check the state of prefetch for signaled AXI transactions.

Command and I/O operation functions

• In Regular mode, use HAL_XSPI_SendRegularCmd() or HAL_XSPI_SendRegularCmd_IT() function to configure the command sequence.

• In Hyperbus mode, use HAL_XSPI_SendHyperbusCmd() function to configure the command sequence.

• If no data is required for the command (only for Regular Command mode, not for Hyperbus mode), it is sent directly to the memory:

  • In polling mode, the function returns when the command is complete.

  • In interrupt mode, the function starts the process and returns, the process continues in the background (based on the various interrupts). The HAL_XSPI_CmdCpltCallback() is called when the process is complete.

• For the indirect write mode, use HAL_XSPI_Transmit(), HAL_XSPI_Transmit_DMA(), HAL_XSPI_Transmit_DMA_Opt() or HAL_XSPI_Transmit_IT() after the command configuration:

  • In polling mode, the function returns when the transfer is complete.

  • In interrupt mode, the function starts the process and returns, the process continues in the background (based on the various interrupts). The HAL_XSPI_TxCpltCallback() is called when the process is complete.

  • In DMA mode:

    • HAL_XSPI_TxHalfCpltCallback() is called at the half transfer and HAL_XSPI_TxCpltCallback() is called when the transfer is complete.

    • The half transfer is filtered with HAL_XSPI_Transmit_DMA_Opt() and HAL_XSPI_TxCpltCallback() is called when the transfer is complete.

• For the indirect read mode, use HAL_XSPI_Receive(), HAL_XSPI_Receive_DMA(), HAL_XSPI_Receive_DMA_Opt() or HAL_XSPI_Receive_IT() after the command configuration:

  • In polling mode, the function returns when the receive is complete.

  • In interrupt mode, the function starts the process and returns, the process continues in the background (based on the various interrupts). The HAL_XSPI_RxCpltCallback() is called when the process is complete.

  • In DMA mode:

    • HAL_XSPI_RxHalfCpltCallback() is called at the half transfer and HAL_XSPI_RxCpltCallback() is called when the transfer is complete.

    • The half transfer is filtered with HAL_XSPI_Receive_DMA_Opt() and HAL_XSPI_RxCpltCallback() is called when the transfer is complete.

• Use HAL_XSPI_ExecRegularAutoPoll() or HAL_XSPI_ExecRegularAutoPoll_IT() function to configure the auto-polling functional mode:

  • In polling mode, the function returns when the status match is reached. The automatic stop is activated to avoid an infinite loop.

  • In interrupt mode, HAL_XSPI_StatusMatchCallback() is called each time the status match is reached.

• Use HAL_XSPI_Abort() or HAL_XSPI_Abort_IT() function to abort any ongoing operation and to flush the FIFO:

  • In polling mode, the function returns when the transfer-complete bit is set and the busy bit is cleared.

  • In interrupt mode, the function starts the process and returns, the process continues in the background (based on the various interrupts). The HAL_XSPI_AbortCpltCallback() is called when the process is complete.

• Use HAL_XSPI_StartMemoryMappedMode() function to start the memory-mapped functional mode.

• Use HAL_XSPI_StopMemoryMappedMode() function to stop the memory-mapped functional mode.

XSPI IRQHandler, link DMA, and callback functions

• XSPI IRQHandler

  • Use HAL_XSPI_IRQHandler() function called under XSPI_IRQHandler interrupt subroutine to handle any XSPI interrupt.

• Link DMA

  • Use HAL_XSPI_SetTxDMA() function to link/store Tx HAL DMA handle into the HAL XSPI handle.

  • Use HAL_XSPI_SetRxDMA() function to link/store Rx HAL DMA handle into the HAL XSPI handle.

• Callback functions

  • Call the function HAL_XSPI_RegisterErrorCallback() to register the XSPI error callback to be used instead of the weak HAL_XSPI_ErrorCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterAbortCpltCallback() to register the XSPI abort-complete callback to be used instead of the weak HAL_XSPI_AbortCpltCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterFifoThresholdCallback() to register the XSPI FIFO Threshold callback to be used instead of the weak HAL_XSPI_FifoThresholdCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterStatusMatchCallback() to register the XSPI Status Match callback to be used instead of the weak HAL_XSPI_StatusMatchCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterTxCpltCallback() to register the XSPI Transfer-Complete callback to be used instead of the weak HAL_XSPI_TxCpltCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterTxHalfCpltCallback() to register the XSPI Half-Transfer complete callback to be used instead of the weak HAL_XSPI_TxHalfCpltCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterRxCpltCallback() to register the XSPI Receive-Complete callback to be used instead of the weak HAL_XSPI_RxCpltCallback() predefined callback.

  • Call the function HAL_XSPI_RegisterRxHalfCpltCallback() to register the XSPI Half-Receive complete callback to be used instead of the weak HAL_XSPI_RxHalfCpltCallback() predefined callback.

State functions

• Use HAL_XSPI_GetState() function to get the current state of the HAL XSPI driver.

Clock frequency of the XSPI peripheral

• Use HAL_XSPI_GetClockFreq() to retrieve the current clock frequency of the XSPI peripheral.

XSPI Delay Block functions

• The delay block (DLYB) is used to generate an output clock that is dephased from the input clock.

  • Use HAL_XSPI_DLYB_SetConfigDelay() to set the delay configuration of the delay block peripheral.

  • Use HAL_XSPI_DLYB_GetConfigDelay() to get the delay output clock phase of the delay block peripheral.

  • Use HAL_XSPI_DLYB_CalculateMaxClockPhase() to calculate the maximum output clock phase of the delay block peripheral.

  • Use HAL_XSPI_DLYB_Enable() to enable the delay block peripheral.

  • Use HAL_XSPI_DLYB_Disable() to disable the delay block peripheral.

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

Interrupt functions

• Use HAL_XSPI_EnableIT() function to enable the interrupts.

• Use HAL_XSPI_DisableIT() function to disable the interrupts.

• Use HAL_XSPI_IsEnabledIT() function to get the interrupt source.

• Use HAL_XSPI_IsActiveFlag() function to get flags.

• Use HAL_XSPI_ClearFlag() function to clear flags.