HAL XSPI How to Use ¶

group XSPI_How_To_Use

An explanation on XSPI overall usage :

• XSPI is the abbreviation of Expanded Serial Peripheral Interface. It’s 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 mode.

• The XSPI I/O manager is a low-level interface that enables an efficient XSPIM pin assignment with a full I/O matrix (before alternate function map) and multiplex of single/dual/quad/octal SPI interfaces over the same bus.

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

• Initialization and De-initialization functions

• Configuration functions

• Command and IO operation functions

• IRQHandler, link DMA and Callbacks functions

• Status functions

• Delay Block functions

• High-speed interface and calibration functions

• Interrupt functions

How to use the XSPI HAL module driver ¶

Initialization and de-initialization 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

• Use HAL_XSPI_XSPIM_SetConfig() function to configure the XSPIM IO manager parameters in hal_xspi_xspim_config_t structure.

• Use HAL_XSPI_XSPIM_GetConfig() function to retrieve the current XSPIM I/O Manager configuration

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

  • HAL_XSPI_SetFifoThreshold() Allowing to configure the Fifo threshold according to the user parameters

  • HAL_XSPI_GetFifoThreshold() Allowing to retrieve the Fifo threshold configuration

  • HAL_XSPI_SetPrescaler() Allowing to configure the Prescaler according to the user parameters

  • HAL_XSPI_GetPrescaler() Allowing to retrieve the Prescaler configuration

  • HAL_XSPI_SetMemorySize() Allowing to configure the Size of XSPI memory according to the user parameters

  • HAL_XSPI_GetMemorySize() Allowing to retrieve the Size of XSPI memory configuration

  • HAL_XSPI_SetMemoryType() Allowing to configure the Type of XSPI memory according to the user parameters

  • HAL_XSPI_GetMemoryType() Allowing to retrieve the Type of XSPI memory configuration

  • HAL_XSPI_EnableFreeRunningClock() Allowing to enable the free running clock

  • HAL_XSPI_DisableFreeRunningClock() Allowing to disable the free running clock

  • HAL_XSPI_IsEnabledFreeRunningClock() Allowing to check the state of free running clock, whether it is enable or not

  • HAL_XSPI_EnableSIOO() Allowing to enable the Send Instruction Only Once mode

  • HAL_XSPI_DisableSIOO() Allowing to disable the Send Instruction Only Once mode

  • HAL_XSPI_IsEnabledSIOO() Allowing to check the state of Send Instruction Only Once mode

Command and IO 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, function returns when the command is complete

  • In interrupt mode, the function starts the process and returns, the process continue in 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, function returns when the transfer is complete

  • In interrupt mode, the function starts the process and returns, the process continue in 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 filtred 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, function returns when the receive is complete

  • In interrupt mode, the function starts the process and returns, the process continue in 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 filtred 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, 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 on-going operation and to flush the fifo :

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

  • In interrupt mode, the function starts the process and returns, the process continue in 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 Callbacks 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

• Callbacks 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

XSPI High-speed interface and calibration functions ¶

• The purpose of High-speed interface is primary to shift data or data strobe by one quarter of octal bus clock period, with a correct timing accuracy. DLL must be calibrated versus this clock period The calibration process is automatically enabled when one of the three conditions below is met:

  • The xSPI exits Reset state

  • The Prescaler is set

  • The configuration of communication is set

• Use HAL_XSPI_HSIC_SetConfigDelay() function to configure the delay values of the high-speed interface DLLs

• Use HAL_XSPI_HSIC_GetConfigDelay() to retrieve the delay values of the high-speed interface DLLs

XSPI OTFDEC functions ¶

• The On-The Fly Decryption (OTFDEC) engine is a hardware block used to protect the confidentiality of read-only firmware libraries stored in SPI NOR flash devices. The OTFDEC performs on-the-fly decryption during XSPI memory-mapped read operation.

• The OTFDEC public services can be used as follows :

  1. Configure the OTFDEC region with user values as mentioned below:

     • Declare a hal_xspi_otfdec_config_t structure

     • Declare a hal_xspi_otfdec_key_t structure

     • Fill all parameters of the declared configuration and keys structures

     • Call HAL_XSPI_OTFDEC_SetConfigRegion() with the filled configuration and keys structures, region index.

     • Use HAL_XSPI_OTFDEC_GetConfigRegion() to retrieve the OTFDEC region parameters.

  2. To protect the key from any write operation, call the HAL_XSPI_OTFDEC_LockRegionKey() . When locked, it’s not allowed to write in key registers in region x. Applying new keys is then possible only after a system reset of the OTFDEC peripheral reset through the RCC.This step is optional.

  3. To protect the peripheral from any configuration, call the HAL_XSPI_OTFDEC_LockRegionConfig() . When locked, it’s not allowed to apply any new configuration or any other key for the given region. The region configuration is then possible only after a system reset of the OTFDEC peripheral reset through RCC. This step is optional.

  4. The OTFDEC can perform encryption of plain data with the HAL_XSPI_OTFDEC_Encrypt() function. Note that :

     • During the OTFDEC encryption, it is not possible to run any other XSPI operation.

     • The encrypted buffer is not programmed/written into the target external memory. It is rather available in the RAM and it is up to the user to program the target external memory with the encrypted buffer.

  5. The On the Fly Decrypt can be started for a given region using HAL_XSPI_OTFDEC_EnableRegion().

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 source of interrupt

• Use HAL_XSPI_IsActiveFlag() function to get flags

• Use HAL_XSPI_ClearFlag() function to clear flags