4.19. OSPI

4.19.1. Introduction

OSPI driver enables communication for OSPI with flash memories. QSPI/OSPI is a variant of SPI supports four/eight receive data lanes.

4.19.1.1. Modes of Operation

Following modes of operations are supported:

OSPI_MODE_BLOCKING OSPI_transfer() API blocks code execution until transaction has completed. By default, OSPI driver operates in blocking mode. This ensures only one OSPI transaction operates at a given time. This mode is supported in both interrupt or non-interrupt configurations.

OSPI_MODE_CALLBACK OSPI_transfer() API returns without waiting for completion of transaction in this case. Callback function registered by application is invoked once transaction is complete.This mode is supported only in interrupt configuration.

4.19.2. Driver Configuration

4.19.2.1. Board Specific Configuration

All board specific configurations eg:enabling clock and pin-mux for OSPI pins are required before calling any driver APIs.By default Board_Init() API supports all initialization sequence for TI supported EVMs. In addition it initializes UART instance for Console/STDIO.Refer PDK Board Support for additional details. Once board specific configuration is completeOSPI_init() API should be called to initialize driver.

4.19.2.2. SoC Specific Configuration

All SoC specific configurations (eg: OSPI module registers base address, interrupt configurations, etc.) can be set using OSPI_socSetInitCfg() SoC driver API before calling any SPI driver APIs. The default SoC specific configurations can be retrieved using SPI_socGetInitCfg() SoC driver API.Use the APIs OSPI_socSetInitCfg and OSPI_socGetInitCfg for changing the SoC specific configurations for OSPI.

4.19.2.3. OSPI Configuration Structure

The SPI_soc.c file binds driver with hardware attributes on the board through OSPI_v0_HwAttrs structure. This structure must be provided to the OSPI driver.

4.19.3. APIs

API Reference for application:

#include <ti/board/board.h>
#include <ti/board/src/flash/include/board_flash.h>

#include <ti/board/src/flash/nor/ospi/nor_ospi.h>
#include <ti/board/src/flash/nor/device/m35xu512.h>

4.19.3.1. Open OSPI

...
Board_init(boardCfg);
...
OSPI_socGetInitCfg(BOARD_OSPI_DOMAIN, BOARD_OSPI_NOR_INSTANCE, &ospi_cfg);
...
OSPI_socSetInitCfg(BOARD_OSPI_DOMAIN, BOARD_OSPI_NOR_INSTANCE, &ospi_cfg);
...
OSPI_init();
...
Refer board_flash.h for BOARD_FLASH_ID of flash you want to program
Board_flashHandle boardHandle = Board_flashOpen(BOARD_FLASH_ID, BOARD_OSPI_NOR_INSTANCE, &tuneEnable);

At this point OSPI driver is ready for data transfer in blocking mode on specific instance identified by handle. Pseudo/Sample code for OSPI read/write transaction is included below. Refer example for additional details

...
readMode can be either OSPI_FLASH_SINGLE_READ or OSPI_FLASH_OCTAL_READ
if(Board_flashRead(boardHandle, flashOffset, rdBufferPtr, xferLen, (void *)(&readMode)) != BOARD_FLASH_EOK)
{
    //failed to read
}
else
{
    //successfully read data
}

...
writeMode can be either OSPI_FLASH_SINGLE_READ or OSPI_FLASH_OCTAL_READ
if(Board_flashWrite(boardHandle, offset, writeBufferPtr, xferLen, (void *)(&writeMode)) != BOARD_FLASH_EOK)
{
    //failed to write
}
else
{
    //successful writing data
}

Note

1. OSPI PHY Pipeline requires to read at least four AHB 4-byte-sized words (16 bytes) in a sequential manner. Hence PHY Pipeline mode is supported only when either DMA or Cache is enabled to OSPI direct-mapped space in the system..

2. When PHY is disabled, the value for baudRateDiv needs to atleast 4 in SDR mode, atleast 8 in DDR mode.

3. DDR PHY tuning algo is updated to support both full and half cycle lock modes:

   1. phyLockCycle parameter is provided in OSPI_v0_HwAttrs for user to configure PHY lock cycle mode.

   2. OSPI driver by default uses half clock cycle lock.

   3. User needs to reduce the tuning window ranges to half, when they use full cycle lock mode.

4. All writes to flash needs to be performed in INDAC mode.

5. In order obtain better read performance do DAC reads with DMA.

4.19.4. Examples

S.No	Flash Type	Test Case	Description	Cache Configuration	Application	Supported SOC
	NOR	OSPI_TEST_ID_DAC_133M_SPI	Performs 1MB data transfer in 1S-1S-1S DAC mode without PHY at frequencies: 4MHz for NOR OSPI 33 MHz for NOR XSPI.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721e, J721s2, J784s4, j7200
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_DAC_DMA_133M	Performs 1MB data transfer using DMA in 8D-8D-8D DAC mode with PHY at 133 MHz.	Disabled	OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_Dma_TestApp_freertos	J721e, J721s2, J784s4, j7200
				Enabled	OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_Dma_Cache_TestApp_freertos	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_DAC_133M	Performs 1MB data transfer in 8D-8D-8D DAC mode with PHY at 133 MHz.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721e, J721s2, J784s4, j7200
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_INDAC_133M	Performs 1MB data transfer in 8D-8D-8D INDAC mode without PHY at frequencies: 4MHz for NOR OSPI 33 MHz for NOR XSPI.	NA*	ALL	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_DAC_DMA_166M	Performs 1MB data transfer using DMA in 8D-8D-8D DAC mode with PHY at 166 MHz.	Disabled	OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_Dma_TestApp_freertos	J721e, J721s2, J784s4, j7200
				Enabled	OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_Dma_Cache_TestApp_freertos	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_DAC_166M	Performs 1MB data transfer in 8D-8D-8D DAC mode with PHY at 166 MHz.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721e, J721s2, J784s4, j7200
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721e, J721s2, J784s4, j7200
	NOR	OSPI_TEST_ID_INDAC_166M	Performs 1MB data transfer in 8D-8D-8D INDAC mode without PHY at frequencies: 5MHz for NOR OSPI	NA*	ALL	J721e
	NAND	OSPI_NAND_TEST_ID_DAC_133M_SPI	Performs 1MB data transfer in 1S-1S-1S DAC mode without PHY at frequency 4 MHz.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721s2, J784s4
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_DAC_DMA_133M	Performs 1MB data transfer using DMA in 8D-8D-8D DAC mode without PHY at 22 MHz.	Disabled	OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_Dma_TestApp_freertos	J721s2, J784s4
				Enabled	OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_Dma_Cache_TestApp_freertos	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_DAC_133M	Performs 1MB data transfer in 8D-8D-8D DAC mode with PHY at 22 MHz.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721s2, J784s4
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_INDAC_133M	Performs 1MB data transfer in 8D-8D-8D INDAC mode without PHY at frequency 4 MHz.	NA*	ALL	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_INDAC_166M	Performs 1MB data transfer in 8D-8D-8D INDAC mode without PHY at frequency 5 MHz.	NA*	ALL	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_DAC_OSDR_166M	Performs 1MB data transfer in 1S-1S-8S DAC mode, using dma with PHY at frequency 166MHz.	Disabled	OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_Dma_TestApp_freertos	J721s2, J784s4
				Enabled	OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_Dma_Cache_TestApp_freertos	J721s2, J784s4
	NAND	OSPI_NAND_TEST_ID_DAC_OSDR_50M	Performs 1MB data transfer in 1S-1S-8S DAC mode without PHY at frequency 50 MHz.	Disabled	OSPI_Baremetal_Flash_TestApp OSPI_Baremetal_Flash_Dma_TestApp OSPI_Flash_TestApp_freertos OSPI_Flash_Dma_TestApp_freertos	J721s2, J784s4
				Enabled	OSPI_Baremetal_Flash_Cache_TestApp OSPI_Baremetal_Flash_Dma_Cache_TestApp OSPI_Flash_TestApp_Cache_freertos OSPI_Flash_Dma_Cache_TestApp_freertos	J721s2, J784s4

• NA: INDAC transfer mode uses controllers SRAM, cache configuration for flash direct mapped address is not-applicable here.

4.19.5. OSPI Driver Configuration to support QSPI flash

If the board has a QSPI flash, the PDK driver needs to be updated to support the QSPI flash:

• Board QSPI Flash Instance Configuration in board_cfg.h

#define BOARD_QSPI_NOR_INSTANCE  <OSPI instance connected to QSPI flash>

• SPI SoC Driver Configurations:

...
OSPI_v0_HwAttrs ospi_cfg;

OSPI_init();

OSPI_socGetInitCfg(SPI_OSPI_DOMAIN_MCU, BOARD_QSPI_NOR_INSTANCE, &ospi_cfg);
ospi_cfg.xferLines      = OSPI_XFER_LINES_QUAD;
ospi_cfg.pageSize       = <QSPI flash page size>;
ospi_cfg.devDelays[0]   = <QSPI device delay>;
ospi_cfg.devDelays[1]   = <QSPI device delay>;
ospi_cfg.devDelays[2]   = <QSPI device delay>;
ospi_cfg.devDelays[3]   = <QSPI device delay>;
ospi_cfg.rdDataCapDelay = <QSPI read capture delay>;
OSPI_socSetInitCfg(SPI_OSPI_DOMAIN_MCU, BOARD_OSPI_NOR_INSTANCE, &ospi_cfg);

4.19.6. Support for Benchmark Testing

Name	Description	Expected Results	SOC/Core Suppported
OSPI flash Dma Test App	Test application used for performance benchmarking, with cache disabled for Flash Data Region.	Test application will print on the UART console: Board_flashWrite ### bytes at transfer rate #### KBps Board_flashRead ### bytes at transfer rate #### KBps Board_flashWrite CPU Load %## Board_flashRead CPU Load %##	j721e/mcux_0 j721e/mcux_1 j7200/mcux_0 j7200/mcux_1 j721s2/mcux_0 j721s2/mcux_1 j784s4/mcux_0 j784s4/mcux_1
OSPI flash Dma Cache Test App	Test application used for performance benchmarking, with cache enable for Flash Data Region.	Test application will print on the UART console: Board_flashWrite ### bytes at transfer rate #### KBps Board_flashRead ### bytes at transfer rate #### KBps Board_flashWrite CPU Load %## Board_flashRead CPU Load %##	j721e/mcux_0 j721e/mcux_1 j7200/mcux_0 j7200/mcux_1 j721s2/mcux_0 j721s2/mcux_1 j784s4/mcux_0 j784s4/mcux_1

Note

1. Data transfer happens between DDR and OSPI flash memory, performance measurement does not include time to invalidate/write back cache

2. GTC counter (200MHz) is used for throughput measurement.

3. Read/write transfer size is 1MB

4. Write transfer size is 1MB with DMA chunk size of 16 bytes in DAC DMA mode