qspipsu
Vitis Drivers API Documentation
Functions
xqspipsu_generic_flash_non_blocking_read_example.c File Reference

Overview

This file contains a design example using the QSPIPSU driver (XQspiPsu) The example writes to flash in IO mode and reads it back using non-blocking APIs in DMA mode.

This examples runs with GENFIFO Manual start. It runs in polled mode. This example illustrates single, parallel and stacked modes. Both the flash devices have to be of the same make and size. The hardware which this example runs on, must have a serial Flash (Micron N25Q) for it to run. In order to test in single, parallel or stacked flash configurations the necessary HW must be present and QSPI_MODE (also reflected in ConnectionMode in the instance) has to be in sync with HW flash configuration being tested.

This example has been tested with the Micron Serial Flash (N25Q512) and ISSI Serial Flash parts of IS25WP and IS25LP series flashes in single and parallel modes using A53 and R5 processors.

Note

None.

 MODIFICATION HISTORY:
 Ver   Who Date     Changes






 1.11   akm  02/19/20 First release
 1.13   akm  11/30/20 Removed unwanted header files.
 1.13   akm  12/10/20 Set Read command as per the qspi bus width.
 1.14   akm  07/16/21 Enable Quad Mode for Winbond flashes.
 1.15   akm  11/19/21 Fix read/write failures on Spansion flash parts.
 1.15   akm  12/22/21 Initialize variables before use.
 1.16   akm  08/16/22 Fix logical error in NumSect calculation.
 1.17   akm  12/16/22 Add timeout in QSPIPSU driver examples.
 1.18   sb   05/19/23 Update number of sector calculation logic
             in flash erase API.
 1.18   sb   06/07/23 Added support for system device-tree flow.
 1.18   sb   07/24/23 Fix wrong init sequence for spansion byte ID.
 1.18   sb   08/02/23 Add status check for XQspiPsu_SetClkPrescaler API.
 1.19   sb   01/12/24 Added support to set QSPI clock based on baud rate divisior
 1.20   sb  09/13/24 Updated examples to configure correct baud rate value
 



Functions


int QspiPsuFlashNonBlockingReadExample (XQspiPsu *QspiPsuInstancePtr, u16 QspiPsuDeviceId)


 The purpose of this function is to illustrate how to use the XQspiPsu device driver in single, parallel and stacked modes using flash devices greater than or equal to 128Mb.  More...


 


int FlashReadID (XQspiPsu *QspiPsuPtr)


 Reads the flash ID and identifies the flash in FCT table.  More...


 


int FlashErase (XQspiPsu *QspiPsuPtr, u32 Address, u32 ByteCount, u8 *WriteBfrPtr)


 This function erases the sectors in the serial Flash connected to the QSPIPSU interface.  More...


 


int FlashWrite (XQspiPsu *QspiPsuPtr, u32 Address, u32 ByteCount, u8 Command, u8 *WriteBfrPtr)


 This function writes to the serial Flash connected to the QSPIPSU interface.  More...


 


int FlashRead (XQspiPsu *QspiPsuPtr, u32 Address, u32 ByteCount, u8 Command, u8 *WriteBfrPtr, u8 *ReadBfrPtr)


 This function performs read.  More...


 


int MultiDieRead (XQspiPsu *QspiPsuPtr, u32 Address, u32 ByteCount, u8 Command, u8 *WriteBfrPtr, u8 *ReadBfrPtr)


 This functions performs a read operation for multi die flash devices.  More...


 


u32 GetRealAddr (XQspiPsu *QspiPsuPtr, u32 Address)


 This functions translates the address based on the type of interconnection.  More...


 


int BulkErase (XQspiPsu *QspiPsuPtr, u8 *WriteBfrPtr)


 This functions performs a bulk erase operation when the flash device has a single die.  More...


 


int DieErase (XQspiPsu *QspiPsuPtr, u8 *WriteBfrPtr)


 This functions performs a die erase operation on all the die in the flash device.  More...


 


int FlashRegisterRead (XQspiPsu *QspiPsuPtr, u32 ByteCount, u8 Command, u8 *ReadBfrPtr)


 This API can be used to write to a flash register.  More...


 


int FlashRegisterWrite (XQspiPsu *QspiPsuPtr, u32 ByteCount, u8 Command, u8 *WriteBfrPtr, u8 WrEn)


 This API can be used to write to a flash register.  More...


 


int FlashEnterExit4BAddMode (XQspiPsu *QspiPsuPtr, unsigned int Enable)


 This API enters the flash device into 4 bytes addressing mode.  More...


 


int FlashEnableQuadMode (XQspiPsu *QspiPsuPtr)


 This API enables Quad mode for the flash parts which require to enable quad mode before using Quad commands.  More...


 


int main (void)


 Main function to call the QSPIPSU Flash Polled example.  More...


 




Function Documentation






      

        

          int BulkErase 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u8 * 
          WriteBfrPtr 
        

        

          
          )
          
        

      





This functions performs a bulk erase operation when the flash device has a single die. 


Works for both Spansion and Micron


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
WriteBfrPtris the pointer to command+address to be sent

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int DieErase 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u8 * 
          WriteBfrPtr 
        

        

          
          )
          
        

      





This functions performs a die erase operation on all the die in the flash device. 


This function uses the die erase command for Micron 512Mbit and 1Gbit


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
WriteBfrPtris the pointer to command+address to be sent

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int FlashEnableQuadMode 
          (
          XQspiPsu * 
          QspiPsuPtr)
          
        

      





This API enables Quad mode for the flash parts which require to enable quad mode before using Quad commands. 


For S25FL-L series flash parts this is required as the default configuration is x1/x2 mode.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use.

  

  




Returns
    

  • XST_SUCCESS if successful.
    • 

  • XST_FAILURE if it fails. 
    • 














      

        

          int FlashEnterExit4BAddMode 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          unsigned int 
          Enable 
        

        

          
          )
          
        

      





This API enters the flash device into 4 bytes addressing mode. 


As per the Micron and ISSI spec, before issuing the command to enter into 4 byte addr mode, a write enable command is issued. For Macronix and Winbond flash parts write enable is not required.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Enableis a either 1 or 0 if 1 then enters 4 byte if 0 exits.

  

  




Returns
    

  • XST_SUCCESS if successful.
    • 

  • XST_FAILURE if it fails. 
    • 














      

        

          int FlashErase 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          Address, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 * 
          WriteBfrPtr 
        

        

          
          )
          
        

      





This function erases the sectors in the serial Flash connected to the QSPIPSU interface. 


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Addresscontains the address of the first sector which needs to be erased. 

    
ByteCountcontains the total size to be erased. 

    
WriteBfrPtris pointer to the write buffer (which is to be transmitted)

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int FlashRead 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          Address, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 
          Command, 
        

        

          
          
          u8 * 
          WriteBfrPtr, 
        

        

          
          
          u8 * 
          ReadBfrPtr 
        

        

          
          )
          
        

      





This function performs read. 


DMA is the default setting.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Addresscontains the address of the first sector which needs to be erased. 

    
ByteCountcontains the total size to be erased. 

    
Commandis the command used to read data from the flash. Supports normal, fast, dual and quad read commands. 

    
WriteBfrPtris Pointer to the write buffer which contains data to be transmitted 

    
ReadBfrPtris Pointer to the read buffer to which valid received data should be written

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int FlashReadID 
          (
          XQspiPsu * 
          QspiPsuPtr)
          
        

      





Reads the flash ID and identifies the flash in FCT table. 


Parameters

  

    
QspiPsuPtris a pointer to the instance of the QspiPsu device.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int FlashRegisterRead 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 
          Command, 
        

        

          
          
          u8 * 
          ReadBfrPtr 
        

        

          
          )
          
        

      





This API can be used to write to a flash register. 


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
ByteCountis the number of bytes to write. 

    
Commandis specific register write command. 

    
ReadBfrPtris Pointer to the read buffer to which valid received data should be written

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
This API can only be used for one flash at a time.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
ByteCountis the number of bytes to write. 

    
Commandis specific register write command. 

    
ReadBfrPtris the pointer to value to be read.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
This API can only be used for one flash at a time.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
ByteCountis the number of bytes to write. 

    
Commandis specific register write command. 

    
ReadBfrPtris the pointer to value to be written.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
This API can only be used for one flash at a time. 



References XQspiPsu_Msg::BusWidth, XQspiPsu_Msg::ByteCount, XQspiPsu_Msg::Flags, XQspiPsu_Msg::RxBfrPtr, XQspiPsu_Msg::TxBfrPtr, XQSPIPSU_MSG_FLAG_RX, XQSPIPSU_MSG_FLAG_TX, XQspiPsu_PolledTransfer(), and XQSPIPSU_SELECT_MODE_SPI.











      

        

          int FlashRegisterWrite 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 
          Command, 
        

        

          
          
          u8 * 
          WriteBfrPtr, 
        

        

          
          
          u8 
          WrEn 
        

        

          
          )
          
        

      





This API can be used to write to a flash register. 


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
ByteCountis the number of bytes to write. 

    
Commandis specific register write command. 

    
WriteBfrPtris the pointer to value to be written. 

    
WrEnis a flag to mention if WREN has to be sent before write.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
This API can only be used for one flash at a time. 



References XQspiPsu_Msg::BusWidth, XQspiPsu_Msg::ByteCount, XQspiPsu_Msg::Flags, MAX_DELAY_CNT, XQspiPsu_Msg::RxBfrPtr, XQspiPsu_Msg::TxBfrPtr, XQSPIPSU_MSG_FLAG_RX, XQSPIPSU_MSG_FLAG_TX, XQspiPsu_PolledTransfer(), and XQSPIPSU_SELECT_MODE_SPI.











      

        

          int FlashWrite 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          Address, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 
          Command, 
        

        

          
          
          u8 * 
          WriteBfrPtr 
        

        

          
          )
          
        

      





This function writes to the serial Flash connected to the QSPIPSU interface. 


All the data put into the buffer must be in the same page of the device with page boundaries being on 256 byte boundaries.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Addresscontains the address to write data to in the Flash. 

    
ByteCountcontains the number of bytes to write. 

    
Commandis the command used to write data to the flash. QSPIPSU device supports only Page Program command to write data to the flash. 

    
WriteBfrPtris Pointer to the write buffer (which is to be transmitted)

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          u32 GetRealAddr 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          Address 
        

        

          
          )
          
        

      





This functions translates the address based on the type of interconnection. 


In case of stacked, this function asserts the corresponding slave select.


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Addresswhich is to be accessed (for erase, write or read)

  

  




Returns
RealAddr is the translated address - for single it is unchanged; for stacked, the lower flash size is subtracted; for parallel the address is divided by 2.


Note
In addition to get the actual address to work on flash this function also selects the CS and BUS based on the configuration detected. 











      

        

          int main 
          (
          void 
          )
          
        

      





Main function to call the QSPIPSU Flash Polled example. 


Returns
XST_SUCCESS if successful, otherwise XST_FAILURE.


Note
None 



References QspiPsuFlashNonBlockingReadExample().











      

        

          int MultiDieRead 
          (
          XQspiPsu * 
          QspiPsuPtr, 
        

        

          
          
          u32 
          Address, 
        

        

          
          
          u32 
          ByteCount, 
        

        

          
          
          u8 
          Command, 
        

        

          
          
          u8 * 
          WriteBfrPtr, 
        

        

          
          
          u8 * 
          ReadBfrPtr 
        

        

          
          )
          
        

      





This functions performs a read operation for multi die flash devices. 


Parameters

  

    
QspiPsuPtris a pointer to the QSPIPSU driver component to use. 

    
Addresscontains the address of the first sector which needs to be erased. 

    
ByteCountcontains the total size to be erased. 

    
Commandis the command used to read data from the flash. Supports normal, fast, dual and quad read commands. 

    
WriteBfrPtris pointer to the write buffer which contains data to be transmitted 

    
ReadBfrPtris pointer to the read buffer to which valid received data should be written.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 











      

        

          int QspiPsuFlashNonBlockingReadExample 
          (
          XQspiPsu * 
          QspiPsuInstancePtr, 
        

        

          
          
          u16 
          QspiPsuDeviceId 
        

        

          
          )
          
        

      





The purpose of this function is to illustrate how to use the XQspiPsu device driver in single, parallel and stacked modes using flash devices greater than or equal to 128Mb. 


This function reads data in DMA mode.


Parameters

  

    
QspiPsuInstancePtris a pointer to the instance of the QspiPsu device. 

    
QspiPsuDeviceIdis the Device ID of the Qspi Device and is the XPAR_<QSPI_instance>_DEVICE_ID value from xparameters.h.

  

  




Returns
XST_SUCCESS if successful, else XST_FAILURE.


Note
None. 



References XQspiPsu_Config::BaseAddress, XQspiPsu_Config::BaudRateDiv, XQspiPsu_Config::BusWidth, XQspiPsu::Config, XQspiPsu_Config::ConnectionMode, FlashEnableQuadMode(), FlashEnterExit4BAddMode(), FlashErase(), FlashRead(), FlashReadID(), FlashWrite(), XQspiPsu_CfgInitialize(), XQSPIPSU_CLK_PRESCALE_8, XQSPIPSU_CONNECTION_MODE_PARALLEL, XQspiPsu_LookupConfig(), XQSPIPSU_MANUAL_START_OPTION, XQSPIPSU_SELECT_FLASH_BUS_LOWER, XQSPIPSU_SELECT_FLASH_CS_LOWER, XQspiPsu_SelectFlash(), XQspiPsu_SetClkPrescaler(), and XQspiPsu_SetOptions().



Referenced by main().