OSPI Flash (r_ospi_b)

Functions
fsp_err_t	R_OSPI_B_Open (spi_flash_ctrl_t *const p_ctrl, spi_flash_cfg_t const *const p_cfg)
fsp_err_t	R_OSPI_B_DirectWrite (spi_flash_ctrl_t *p_ctrl, uint8_t const *const p_src, uint32_t const bytes, bool const read_after_write)
fsp_err_t	R_OSPI_B_DirectRead (spi_flash_ctrl_t *p_ctrl, uint8_t *const p_dest, uint32_t const bytes)
fsp_err_t	R_OSPI_B_DirectTransfer (spi_flash_ctrl_t *p_ctrl, spi_flash_direct_transfer_t *const p_transfer, spi_flash_direct_transfer_dir_t direction)
fsp_err_t	R_OSPI_B_XipEnter (spi_flash_ctrl_t *p_ctrl)
fsp_err_t	R_OSPI_B_XipExit (spi_flash_ctrl_t *p_ctrl)
fsp_err_t	R_OSPI_B_Write (spi_flash_ctrl_t *p_ctrl, uint8_t const *const p_src, uint8_t *const p_dest, uint32_t byte_count)
fsp_err_t	R_OSPI_B_Erase (spi_flash_ctrl_t *p_ctrl, uint8_t *const p_device_address, uint32_t byte_count)
fsp_err_t	R_OSPI_B_StatusGet (spi_flash_ctrl_t *p_ctrl, spi_flash_status_t *const p_status)
fsp_err_t	R_OSPI_B_BankSet (spi_flash_ctrl_t *p_ctrl, uint32_t bank)
fsp_err_t	R_OSPI_B_SpiProtocolSet (spi_flash_ctrl_t *p_ctrl, spi_flash_protocol_t spi_protocol)
fsp_err_t	R_OSPI_B_Close (spi_flash_ctrl_t *p_ctrl)
fsp_err_t	R_OSPI_B_AutoCalibrate (spi_flash_ctrl_t *const p_ctrl)
fsp_err_t	R_OSPI_B_DOTF_Configure (spi_flash_ctrl_t *const p_ctrl, ospi_b_dotf_cfg_t *const p_dotf_cfg)

Detailed Description

Driver for the OSPI_B peripheral on RA MCUs. This module implements the SPI Flash Interface.

Overview

The OSPI_B peripheral supports xSPI (or OSPI) compatible external memory devices, and it interfaces with these devices to perform data I/O Operations. The OSPI_B peripheral does not support addressable devices, so all connected memory devices must be connected to an individual chip-select pin. Please note that this document will reference the xSPI protocol to which OSPI is a subset. The OSPI_B peripheral is compatible with a variety of xSPI protocol operating modes.

Features

The OSPI_B driver has the following key features to support the xSPI device:

• Perform data I/O Operation
• Direct memory-mapped access to the xSPI device memory up to 256 MB.
• Can be configured with xSPI devices on either of the 2 channels
• Programming the xSPI device using combination write (up to 64 bytes)
• Erasing the xSPI device
• Sending device specific commands and reading back responses of up to 8 bytes
• 3 byte addressing
• 4 byte addressing
• Auto-calibration
• Decryption-on-the-fly

Additional build-time features:

• Optional (build-time) DMAC support for data transmission when used with OSPI_B.
• Optional (build-time) XiP support for entering/exiting XiP mode of the target device.
• Optional (build-time) Data-strobe (DS) auto-calibration support for target devices using the DS signal.
• Optional (build-time) Decryption on the fly (DOTF)

Note

For OSPI_B, use of DMAC for data transmission is strongly recommended. Without the use of DMAC, due to the high-speed hardware design of the OSPI peripheral, data transmission can be sensitive to timing variance, which could cause software-based memory-mapped operations to fail unexpectedly.

Configuration

OSPI_B Flash:

Build Time Configurations for r_ospi_b

The following build time configurations are defined in fsp_cfg/r_ospi_b_cfg.h:

Configuration	Options	Default	Description
Memory-mapping Support
Prefetch Function	Enable Disable	Enable	Enable prefetch function on memory-mapped reads.
Combination Function	Refer to the RA Configuration tool for available options.	64 Byte	Enable combination function on memory-mapped writes.
XiP Support	Enable Disable	Disable	Enable the use of XiP enter and exit codes.
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
DMAC Support	Enable Disable	Disable	Enable DMAC support for the OSPI module.
Autocalibration Support	Enable Disable	Disable	Enable DS autocalibration for dual-data-rate modes.
DOTF Support	Enable (Protected Mode) Enable (Compatibility Mode) Disable	Disable	Enable DOTF support for the OSPI module.

Configurations for Storage > OSPI Flash (r_ospi_b)

This module can be added to the Stacks tab via New Stack > Storage > OSPI Flash (r_ospi_b).

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_ospi0	Module name.
Channel	Channel should be 0 or 1	0	Specify the OSPI chip select line to use.
Initial Protocol Mode	SPI (1S-1S-1S) DSPI (1S-2S-2S) DSPI (2S-2S-2S) QSPI (1S-4S-4S) QSPI (4S-4S-4S) QSPI (4S-4D-4D) Dual data rate OPI (8D-8D-8D)	SPI (1S-1S-1S)	Select the initial protocol mode of the xSPI target device. Please see the documentation for examples of changing the protocol mode.
Initial Address Bytes	3 4	4	Select the number of address bytes.
Write Status Bit	Must be an integer between 0 and 7	0	Which bit contains the write in progress status returned from the Write Status Command.
Write Enable Bit	Must be an integer between 0 and 7	1	Which bit contains the write enable status returned from the Write Enable Command.
Sector Erase Size	Must be an integer greater than or equal to 0	4096	The sector erase size. Set Sector Erase Size to 0 if Sector Erase is not supported.
Block Erase Size	Must be an integer greater than or equal to 0	262144	The block erase size. Set Block Erase Size to 0 if Block Erase is not supported.
Command Set Table	Must be a vaild C symbol		Specify the custom command set table (ospi_b_xspi_command_set_t[]) to use. If provided, all properties for High-speed Mode will be ignored.
Command Set Table Length	Length must be an integer greater than or equal to zero.	0	Length of the custom command set table.
Defaults
Defaults > Command Definitions
Page Program Command	Must be a 8-bit OSPI Page Program Command under SPI Mode|Command Definitions	0x12	Default command to program a page.
Read Command	Must be a 8-bit OSPI Read Command under SPI Mode|Command Definitions	0x13	Default command to read.
Write Enable Command	Must be a 16-bit OSPI Write Enable Command under SPI Mode|Command Definitions	0x06	Default command to enable write.
Status Command	Must be a 16-bit OSPI Status Command under SPI Mode|Command Definitions	0x05	Default command to query the status of a write or erase command.
Defaults > Erase Command Definitions
Sector Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0x2121	Default command to erase a sector. The lowwer byte will be used for 1-byte commands. Set to 0 if unused.
Block Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0xDCDC	Default command to erase a block. The lowwer byte will be used for 1-byte commands. Set to 0 if unused.
Chip Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0x6060	Default command to erase the entire chip. The lowwer byte will be used for 1-byte commands. Set to 0 if unused.
Defaults > Dummy Cycles
Memory Read Dummy Cycles	Must be an integer between 0 and 31	0	Default memory read dummy cycles
Status Read Dummy Cycles	Must be an integer between 0 and 31	0	Default status read dummy cycles
High-speed Mode
High-speed Mode > Auto-Calibration
Data latching delay	Must be a valid non-negative integer with maximum configurable value of 0x1F	0x08	If auto-calibration support is enabled, set this to 0 to trigger auto-calibration when appropriate.
Auto-Calibration Address	Must be a valid non-negative integer with maximum configurable value of 0xFFFFFFFF	0x00	Set the address of the read/write destination to be performed for auto-calibration.
High-speed Mode > Command Definitions
Page Program Command	Must be a 16-bit OSPI Page Program Command under High-speed Mode|Command Definitions	0x1212	The command to program a page in OPI mode.
Dual Read Command	Must be a 16-bit OSPI Dual Read Command under High-speed Mode|Command Definitions	0xEEEE	The command to read in High-speed mode (8DTRD).
Write Enable Command	Must be a 16-bit OSPI Write Enable Command under High-speed Mode|Command Definitions	0x0606	The command to enable write in OPI mode. Set to 0 to ignore.
Status Command	Must be a 16-bit OSPI Status Command under High-speed Mode|Command Definitions	0x0505	The command to query the status of a write or erase command in OPI mode. Set to 0 to ignore.
Sector Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0	The command to erase a sector for high-speed mode. Set to 0 if unused.
Block Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0	The command to erase a block for high-speed mode. Set to 0 if unused.
Chip Erase Command	Must be an integer between 0x01 and 0xFFFF, inclusive.	0	The command to erase the entire chip for high-speed mode. Set to 0 if unused.
Protocol	SPI (1S-1S-1S) DSPI (1S-2S-2S) DSPI (2S-2S-2S) QSPI (1S-4S-4S) QSPI (4S-4S-4S) QSPI (4S-4D-4D) Dual data rate OPI (8D-8D-8D)	Dual data rate OPI (8D-8D-8D)	Select the High-Speed xSPI protocol.
Command Length Bytes	1 2	2	Command length in bytes
Memory Read Dummy Cycles	Must be an integer between 0 and 31	20	Memory read dummy cycles
Status Read Dummy Cycles	Must be an integer between 0 and 31	3	Status read dummy cycles
Chip Select Timing Setting
Command Interval	Refer to the RA Configuration tool for available options.	2	Command execution interval setting in OCTACLK units
Pull-up Timing	No Extension 1 Cycle	No Extension	Signal pull-up timing (CS asserting extention) setting in OCTACLK units
Pull-down Timing	No Extension 1 Cycle	No Extension	Signal pull-down timing (CS negating extention) setting in OCTACLK units
XiP Mode
XiP Enter Code	Must be an integer between 0 and 255	0	XiP enter code.
XiP Exit Code	Must be an integer between 0 and 255	0	XiP exit code.
DOTF
Name	Name must be a valid C symbol	g_ospi_dotf	DOTF Configuration name.
AES Key	Name must be a valid C symbol	g_ospi_dotf_key	Name of Key variable.
AES IV	Name must be a valid C symbol	g_ospi_dotf_iv	Name of IV variable
AES Key Length	MCU Specific Options		Select AES key length
Key Format	MCU Specific Options		Select key format
Decryption start address	Value must be an integer between 0x80000000 and 0x9FFFFFFF	0x90000000	OSPI decryption start address
Decryption end address	Value must be an integer between 0x80000000 and 0x9FFFFFFF	0x90001FFF	OSPI decryption end address

Note

The user is expected to modify the command definitions based on the xSPI chip and SPI communication mode. The default mode is SPI mode and default erase commands are set for DOPI mode based on Infineon S28HS256.

Clock Configuration

PCLKA is the Octal-SPI bus interface, and PCLKB is used to set OSPI registers.

The signals to the xSPI target device are derived from OCTASPICLK. The OMSCLK signal is OCTASPICLK / 2. Data can be output at the OCTASPICLK rate if protocol mode is set to a Dual Data Rate mode (8D-8D-8D or 4S-4D-4D).

The PCLKB, PCLKA, and OCTASPICLK frequencies can be set on the Clocks tab of the RA Configuration editor.

Pin Configuration

The following pins are available to connect to an external OSPI device:

• OMSCLK: OSPI clock output (OCTASPICLK / 2)
• OMDQS: OSPI data strobe signal
• OMCS0: OSPI device 0 select
• OMCS1: OSPI device 1 select
• OMSIO0: Data 0 I/O
• OMSIO1: Data 1 I/O
• OMSIO2: Data 2 I/O
• OMSIO3: Data 3 I/O
• OMSIO4: Data 4 I/O
• OMSIO5: Data 5 I/O
• OMSIO6: Data 6 I/O
• OMSIO7: Data 7 I/O

Note

Data pins must be configured with IOPORT_CFG_DRIVE_HS_HIGH.

Chip Select pins should be configured with at least IOPORT_CFG_DRIVE_MEDIUM.

Usage Notes

Usage Notes for xSPI support

After R_OSPI_B_Open() completes successfully, the xSPI device contents are mapped to address 0x80000000 (bank CS0) or 0x90000000 (bank CS1) and can be read like on-chip flash. Bank CS0 is only accessible from OSPI_B channel/slave 0 and likewise, bank CS1 is only accessible from OSPI_B channel/slave 1. Bank CS0 and CS1 support up to 256 MB of address space each.

Auto-calibration

If support is enabled, auto-calibration procedures are triggered automatically when the 'Data latching delay' field in the configurator properties is set to 0. The user application is responsible for setting the appropriate preamble pattern before calling R_OSPI_B_Open() when using a data strobe (DS) mode or changing the SPI protocol to a DS mode using the R_OSPI_B_SpiProtocolSet() API. The appropriate preamble pattern can be written to the desired address using the R_OSPI_B_Write() API while in simple SPI mode (recommended), or a non-DS mode. Ensure that the same address is passed through the configurator. If the xSPI device is already in a DS mode, the preamble pattern must be programmed using the debugger before calling R_OSPI_B_Open().

The preamble pattern is expected to be { 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0x00, 0x08, 0x00, 0x00, 0xF7, 0xFF, 0x00, 0x08, 0xF7, 0x00, 0xF7 }.

Chip Select Latencies

Chip select latencies can be set through the configurator. The default settings support SPI at minimum latency. In case the driver is opened in SPI mode and will be switched to DOPI mode later using R_OSPI_B_SpiProtocolSet(), please select latencies required for DOPI before calling R_OSPI_B_Open().

XiP Support

OSPI_B supports eXecute in Place (XiP) modes of operation. This can be used for read-only memory-mapped accesses to reduce overall read latency by skipping the command sequence in the xSPI transaction. Separate XiP enter and exit codes may be specified for either attached target device. Upon calling R_OSPI_B_XipEnter(), the associated memory region for the target device is switched to read-only mode and the enter code sent to the device. Calling R_OSPI_B_XipExit() will transmit the exit code and transition the memory region back to read-write access.

Only one flash device should be used after entering XiP mode. Once entered, XiP codes will be transmitted to all attached devices.

xSPI Commands

Command sets and erase commands may be specified individually for each supported protocol mode. By default, the configurator only supports an alternative command set for DOPI (8D-8D-8D) mode. The command sets cannot be changed during run-time. The appropriate command set will be selected when changing protocol modes. If a command set is not found, it defaults to the SPI command set.

If custom DOPI erase commands are not specified, ensure the erase commands are the appropriate 2-byte DOPI commands. The lower byte will be used for 1-byte command protocols.

DOTF Support

Decryption-On-The-Fly is configurable for OSPI Flash and is disabled from the build by default.

Supported Key Formats

• When the Compatibility Mode stack is added for the crypto engine, the user can provide either a wrapped or plaintext AES key to the DOTF module.
• When the Protected Mode stack is used, only wrapped keys are supported.

When configuring the DOTF options, make sure that the key format is specified.

Note

For a detailed description of the Crypto Engine operating modes, refer to Application Note R11AN0498.

Using the DOTF feature requires first creating the encrypted blob on the PC and then configuring the DOTF module with the appropriate parameters to allow decryption of the blob once it is programmed into OSPI. Use the Security Key Management Tool (https://www.renesas.com/us/en/software-tool/security-key-management-tool) to create the encrypted blob. Example: To encrypt a 4096 byte area in a input srec file from 0x90000000 to 0x90000FFF using a 128 AES encryption key "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF" and iv "00000000000000000000000000000000" use SKMT with the following arguments: skmt.exe /encdotf /keytype "AES-128" /enckey "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF" /nonce "00000000000000000000000000000000" /startaddr "90000000" /endaddr "90000FFF" /prg "input.srec" /incplain /output "encrypted_output.srec"

The values for key, iv and decryption area start and end addresses that were used to create the blob using SKMT must be set in the DOTF configuration in FSP.

Make sure that the Key and IV passed into DOTF configuration are 4 byte aligned. This can be done using a compiler alignment attribute as shown below: uint8_t aes_key[] attribute((aligned(4))) = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f };

Limitations

Developers should be aware of the following limitations when using the OSPI_B driver:

OSPI_B

• Problems may occur with using CS0/bank0. OSPI_B channel 1 with CS1/bank1 has been tested and confirmed working.
• Prefetch and combination support for memory-mapped access is applied globally to all slave devices.
• Combination writes are limited to a maximum of 64 bytes. The user should verify the write has completed before attempting to write more bytes.
• Writing to the memory-mapped regions with the CPU is restricted to 64-bit accesses with 8-byte destination alignments. This restriction is not applicable to other bus masters (e.g. DTC or DMAC).
• When using Arm LLVM ensure any read-only (const) data used with R_OSPI_B_Write() is word (4-byte) aligned if the DMAC is not being used. If parameter checking is enabled, the source pointer alignment will be verified for calls to R_OSPI_B_Write().
• Take care to restrict concurrent accesses of the OSPI memory area. Collisions on the bus can occur if other bus masters attempt to write to the OSPI memory area while another master is reading the OSPI memory area.
• When using 8D-8D-8D mode, care should be taken to access on even-aligned addresses. Problems may occur if odd address alignment is used. This restriction applies to all bus masters using OSPI_B.
• DOTF: AES-192 is not supported when the Protected Mode stack is used.

Examples

OSPI Flash:

Basic Example

This is a basic example of minimal use of the OSPI in an application with OctaFlash.

#define OSPI_B_EXAMPLE_DATA_LENGTH    (1024)

uint8_t g_dest[OSPI_B_EXAMPLE_DATA_LENGTH];

/* Place data in the .ospi_flash section to flash it during programming. */
const uint8_t g_src[OSPI_B_EXAMPLE_DATA_LENGTH] BSP_PLACE_IN_SECTION(".ospi_flash") = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

/* Place code in the .code_in_ospi section to flash it during programming. */
void r_ospi_b_example_function(void) BSP_PLACE_IN_SECTION(".code_in_ospi") __attribute__((noinline));

void r_ospi_b_example_function (void)
{
    /* Add code here. */
}

void r_ospi_b_basic_example (void)
{

    /* Open the OSPI instancee */
    fsp_err_t err = R_OSPI_B_Open(&g_ospi0_ctrl, &g_ospi0_cfg);

    assert(FSP_SUCCESS == err);

    /* (Optional) Change SPI to DOPI mode */
    r_ospi_b_example_spi_to_dopi();

    /* After R_OSPI_B_Open() and any required device specific initialization, data can be read directly from the OSPI flash. */
    memcpy(&g_dest[0], &g_src[0], OSPI_B_EXAMPLE_DATA_LENGTH);

    /* After R_OSPI_B_Open() and any required device specific initialization, functions in the OSPI flash can be called. */
    r_ospi_b_example_function();
}

Reading Status Register Example (R_OSPI_B_DirectTransfer)

This is an example of using R_OSPI_B_DirectWrite followed by R_OSPI_B_DirectRead to send the read status register command and read back the status register from the device.

#define OSPI_B_COMMAND_READ_STATUS_REGISTER    (0x05U)

void r_ospi_b_direct_example (void)
{
    spi_flash_direct_transfer_t ospi_b_test_direct_transfer =
    {
        .command        = OSPI_B_TEST_READ_STATUS_COMMAND_SPI_MODE,
        .address        = 0U,
        .data           = 0U,
        .command_length = 1U,
        .address_length = 0U,
        .data_length    = 0U,
        .dummy_cycles   = 0U
    };

    /* Open the OSPI instance. */
    fsp_err_t err = R_OSPI_B_Open(&g_ospi0_ctrl, &g_ospi0_cfg);
    assert(FSP_SUCCESS == err);


    /* Write Enable */
    err = R_OSPI_B_DirectTransfer(&g_ospi0_ctrl, &ospi_b_test_direct_transfer, SPI_FLASH_DIRECT_TRANSFER_DIR_WRITE);
    assert(FSP_SUCCESS == err);


    /* Read Status Register */
    ospi_b_test_direct_transfer.command     = OSPI_B_TEST_READ_STATUS_COMMAND_SPI_MODE;
    ospi_b_test_direct_transfer.data_length = 1U;
    err = R_OSPI_B_DirectTransfer(&g_ospi0_ctrl, &ospi_b_test_direct_transfer, SPI_FLASH_DIRECT_TRANSFER_DIR_READ);
    assert(FSP_SUCCESS == err);

    /* Check if Write Enable is set */
    if (OSPI_B_WEN_BIT_MASK != (ospi_b_test_direct_transfer.data & OSPI_B_WEN_BIT_MASK))
    {
        __BKPT(0);
    }
}

Auto-calibration Example (R_OSPI_B_DirectTransfer, R_OSPI_B_Write, R_OSPI_B_SpiProtocolSet)

This is an example of using R_OSPI_B_SpiProtocolSet to change the operating mode from SPI to DOPI and allow the driver to initiate auto-calibration.

#define OSPI_B_DOPI_PREAMBLE_PATTERN_LENGTH_BYTES    (16U)
#define OSPI_B_EXAMPLE_PREAMBLE_ADDRESS              (0x90000000U) /* Device connected to CS1 */
const uint8_t g_preamble_bytes[OSPI_B_DOPI_PREAMBLE_PATTERN_LENGTH_BYTES] =
{
    0x00, 0x00, 0xFF, 0xFF, 0xFF, 0x00, 0x08, 0x00, 0x00, 0xF7, 0xFF, 0x00, 0x08, 0xF7, 0x00, 0xF7
};

void ospi_b_example_wait_until_wip (void)
{
    fsp_err_t          err = FSP_SUCCESS;
    spi_flash_status_t status;
    status.write_in_progress = true;
    uint32_t timeout = UINT32_MAX;
    while ((status.write_in_progress) && (--timeout))
    {

        err = R_OSPI_B_StatusGet(&g_ospi0_ctrl, &status);
        assert(FSP_SUCCESS == err);

    }

    if (0 == timeout)
    {
        assert(FSP_SUCCESS == err);
    }
}

void r_ospi_b_auto_calibrate_example (void)
{
    /* Open the OSPI instance. */
    /* Set data_latch_delay_clocks to 0x0 to enable auto-calibration */
    fsp_err_t err = R_OSPI_B_Open(&g_ospi0_ctrl, &g_ospi0_cfg);
    assert(FSP_SUCCESS == err);

    uint8_t * preamble_pattern_addr = (uint8_t *) OSPI_B_EXAMPLE_PREAMBLE_ADDRESS;


    err = R_OSPI_B_Write(&g_ospi0_ctrl, g_preamble_bytes, preamble_pattern_addr, OSPI_B_EXAMPLE_PREAMBLE_ADDRESS);
    assert(FSP_SUCCESS == err);


    /* Wait until write has been completed */
    ospi_b_example_wait_until_wip();

    /* Change from SPI to DOPI mode */
    r_ospi_b_example_spi_to_dopi();
}

Octaclk Update Example (R_OSPI_B_SpiProtocolSet)

This is an example of using R_BSP_OctaclkUpdate to change the Octal-SPI clock frequency during run time. The OCTACLK frequency must be updated before calling the R_OSPI_B_SpiProtocolSet with appropriate clock source and divider settings required to be set for the new SPI protocol mode. Ensure that the clock source selected is started.

static void ospi_b_example_change_omclk (void)
{
    /* Ensure clock source (PLL2 in this example) is running before changing the OCTACLK frequency */
    bsp_octaclk_settings_t octaclk_settings;
    octaclk_settings.source_clock = BSP_CLOCKS_CLOCK_PLL2;
    octaclk_settings.divider      = BSP_CLOCKS_OCTACLK_DIV_2;
    R_BSP_OctaclkUpdate(&octaclk_settings);
}

Change Protocol Mode Example (R_OSPI_B_DirectTransfer, R_OSPI_B_SpiProtocolSet)

This is an example of using R_OSPI_B_DirectTransfer to change the attached flash device to a new protocol mode during run time.

static void r_ospi_b_example_spi_to_dopi (void)
{
    r_ospi_b_write_enable_and_verify();
    spi_flash_direct_transfer_t ospi_b_test_direct_transfer =
    {
        .command        = OSPI_B_COMMAND_WRITE_REGISTER_SPI_MODE,
        .address        = OSPI_B_CFR5V_ADDRESS,
        .data           = OSPI_B_DOPI_REGISTER_SETTING,
        .command_length = 1U,
        .address_length = 3U,
        .data_length    = 1U,
        .dummy_cycles   = 0U
    };

    /* The OctaFlash chip is in SPI mode. Change DOPI mode */
    fsp_err_t err = R_OSPI_B_DirectTransfer(&g_ospi0_ctrl,
                                            &ospi_b_test_direct_transfer,
                                            SPI_FLASH_DIRECT_TRANSFER_DIR_WRITE);
    assert(FSP_SUCCESS == err);

    /* Change OMCLK appropriately. */
    ospi_b_example_change_omclk();

    /* Transition the OSPI peripheral to DOPI mode. This will initiate auto calibration as MDTR is 0 */
    err = R_OSPI_B_SpiProtocolSet(&g_ospi0_ctrl, SPI_FLASH_PROTOCOL_DOPI);
    assert(FSP_SUCCESS == err);

    /* Verify that the chip is in requested OPI mode */
    ospi_b_test_direct_transfer.command      = OSPI_B_COMMAND_READ_REGISTER_SPI_MODE;
    ospi_b_test_direct_transfer.dummy_cycles = 3U;
    err = R_OSPI_B_DirectTransfer(&g_ospi0_ctrl, &ospi_b_test_direct_transfer, SPI_FLASH_DIRECT_TRANSFER_DIR_READ);
    assert(FSP_SUCCESS == err);

    if (OSPI_B_DOPI_REGISTER_SETTING != ospi_b_test_direct_transfer.data)
    {
        __BKPT(0);
    }
}

Using a Custom xSPI Command Set Example

This is an example of using custom command sets for 8D-8D-8D and 4S-4S-4S protocol modes.

spi_flash_cfg_t       g_ospi0_cfg_w_table;
ospi_b_extended_cfg_t g_ospi0_ext_w_table;

/* Custom two-byte erase commands. */
spi_flash_erase_command_t g_2B_erase_commands[] =
{
    {.command = OSPI_B_TEST_BLOCK_ERASE_COMMAND_DOPI_MODE,  .size = OSPI_B_TEST_BLOCK_ERASE_SIZE   },
    {.command = OSPI_B_TEST_SECTOR_ERASE_COMMAND_DOPI_MODE, .size = OSPI_B_TEST_SECTOR_ERASE_SIZE  },
    {.command = OSPI_B_TEST_CHIP_ERASE_COMMAND_DOPI_MODE,   .size = SPI_FLASH_ERASE_SIZE_CHIP_ERASE},
};

/* Custom command sets. */
ospi_b_xspi_command_set_t g_command_sets[] =
{
    /* 8D-8D-8D example with inverted lower command byte. */
    {
        .protocol                  = SPI_FLASH_PROTOCOL_8D_8D_8D,
        .command_bytes             = OSPI_B_COMMAND_BYTES_2,
        .read_command              = OSPI_B_TEST_READ_COMMAND_DOPI_MODE,
        .page_program_command      = OSPI_B_TEST_PROGRAM_COMMAND_DOPI_MODE,
        .write_enable_command      = OSPI_B_TEST_WRITE_ENABLE_COMMAND_DOPI_MODE,
        .status_command            = OSPI_B_TEST_STATUS_COMMAND_DOPI_MODE,
        .read_dummy_cycles         = 20U,
        .program_dummy_cycles      = 0U,
        .status_dummy_cycles       = 3U,
        .erase_command_list_length = sizeof(g_2B_erase_commands) / sizeof(g_2B_erase_commands[0]),
        .p_erase_command_list      = g_2B_erase_commands,
    },

    /* 4S-4S-4S example with different .read_command and dummy cycles. */
    {
        .protocol                  = SPI_FLASH_PROTOCOL_4S_4S_4S,
        .command_bytes             = OSPI_B_COMMAND_BYTES_1,
        .read_command              = OSPI_B_TEST_READ_COMMAND_QSPI_MODE,
        .page_program_command      = OSPI_B_TEST_PROGRAM_COMMAND_QSPI_MODE,
        .write_enable_command      = OSPI_B_TEST_WRITE_ENABLE_COMMAND_QSPI_MODE,
        .status_command            = OSPI_B_TEST_STATUS_COMMAND_QSPI_MODE,
        .read_dummy_cycles         = 10U,
        .program_dummy_cycles      = 0U,
        .status_dummy_cycles       = 1U,
        .erase_command_list_length = 0U,
        .p_erase_command_list      = NULL, // Use the common erase definitions.
    },
};

void r_ospi_command_table_example (void)
{
    /* Open the OSPI instance.
     * Specify `g_command_sets` using the configurator. */
    fsp_err_t err = R_OSPI_B_Open(&g_ospi0_ctrl, &g_ospi0_cfg);

    assert(FSP_SUCCESS == err);

    /* Change SPI to DOPI mode */
    r_ospi_b_example_spi_to_dopi();

    /* After R_OSPI_B_Open() and any required device specific initialization, data can be read directly from the OSPI flash. */
    memcpy(&g_dest[0], &g_src[0], OSPI_B_EXAMPLE_DATA_LENGTH);

    /* After R_OSPI_B_Open() and any required device specific initialization, functions in the OSPI flash can be called. */
    r_ospi_b_example_function();

    /* Change SPI to QSPI mode */
    r_ospi_b_example_spi_to_qspi();

    /* Read data from an external device, this time in QSPI mode. */
    memcpy(&g_dest[0], &g_src[0], OSPI_B_EXAMPLE_DATA_LENGTH);

    /* Run the example function again in QSPI mode. */
    r_ospi_b_example_function();
}

OSPI Data and IAR

When using the IAR compiler, OSPI data must be const qualified to be downloaded by the debugger.

Data Structures
struct	ospi_b_timing_setting_t
struct	ospi_b_xspi_command_set_t
struct	ospi_b_extended_cfg_t
struct	ospi_b_instance_ctrl_t

Enumerations
enum	ospi_b_device_number_t
enum	ospi_b_command_bytes_t
enum	ospi_b_command_interval_clocks_t
enum	ospi_b_command_cs_pullup_clocks_t
enum	ospi_b_command_cs_pulldown_clocks_t
enum	ospi_b_prefetch_function_t
enum	ospi_b_combination_function_t

---

Data Structure Documentation

ospi_b_timing_setting_t

struct ospi_b_timing_setting_t

Memory mapped timing

Data Fields
ospi_b_command_interval_clocks_t	command_to_command_interval	Interval between 2 consecutive commands.
ospi_b_command_cs_pullup_clocks_t	cs_pullup_lag	Duration to de-assert CS line after the last command.
ospi_b_command_cs_pulldown_clocks_t	cs_pulldown_lead	Duration to assert CS line before the first command.

ospi_b_xspi_command_set_t

struct ospi_b_xspi_command_set_t

Command set used for a protocol mode other than normal (1S-1S-1S) SPI.

Data Fields
spi_flash_protocol_t	protocol	Protocol mode associated with this command set.
ospi_b_command_bytes_t	command_bytes	Number of command bytes for each command code.
uint16_t	read_command	Read command.
uint16_t	page_program_command	Page program/write command.
uint16_t	write_enable_command	Command to enable write or erase, set to 0x00 to ignore.
uint16_t	status_command	Command to read the write status, set to 0x00 to ignore.
uint8_t	read_dummy_cycles	Dummy cycles to be inserted for read commands.
uint8_t	program_dummy_cycles	Dummy cycles to be inserted for page program commands.
uint8_t	status_dummy_cycles	Dummy cycles to be inserted for status read commands.
uint8_t	erase_command_list_length	Length of erase command list.
spi_flash_erase_command_t const *	p_erase_command_list	List of all erase commands and associated sizes.

ospi_b_extended_cfg_t

struct ospi_b_extended_cfg_t

OSPI_B Extended configuration.

Data Fields
ospi_b_device_number_t	channel	Device number to be used for memory device.
ospi_b_timing_setting_t const *	p_timing_settings	Memory-mapped timing settings.
ospi_b_xspi_command_set_t const *	p_xspi_command_set_list	Additional protocol command sets; if additional protocol commands set are not used set this to NULL.
uint8_t	xspi_command_set_list_length	Number of additional protocol command set defined.
uint8_t *	p_autocalibration_preamble_pattern_addr	OctaFlash memory address holding the preamble pattern.
uint8_t	data_latch_delay_clocks	Specify delay between OM_DQS and OM_DQS Strobe. Set to 0 to auto-calibrate. Typical value is 0x80.
transfer_instance_t const *	p_lower_lvl_transfer	DMA Transfer instance used for data transmission.
uint8_t	read_dummy_cycles	Dummy cycles to be inserted for read commands.
uint8_t	program_dummy_cycles	Dummy cycles to be inserted for page program commands.
uint8_t	status_dummy_cycles	Dummy cycles to be inserted for status read commands.

ospi_b_instance_ctrl_t

struct ospi_b_instance_ctrl_t

Instance control block. DO NOT INITIALIZE. Initialization occurs when spi_flash_api_t::open is called

Enumeration Type Documentation

ospi_b_device_number_t

enum ospi_b_device_number_t

OSPI Flash chip select

Enumerator
OSPI_B_DEVICE_NUMBER_0	Device connected to Chip-Select 0.
OSPI_B_DEVICE_NUMBER_1	Device connected to Chip-Select 1.

ospi_b_command_bytes_t

enum ospi_b_command_bytes_t

OSPI flash number of command code bytes.

Enumerator
OSPI_B_COMMAND_BYTES_1	Command codes are 1 byte long.
OSPI_B_COMMAND_BYTES_2	Command codes are 2 bytes long.

ospi_b_command_interval_clocks_t

enum ospi_b_command_interval_clocks_t

OSPI frame to frame interval

Enumerator
OSPI_B_COMMAND_INTERVAL_CLOCKS_1	1 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_2	2 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_3	3 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_4	4 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_5	5 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_6	6 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_7	7 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_8	8 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_9	9 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_10	10 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_11	11 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_12	12 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_13	13 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_14	14 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_15	15 interval clocks
OSPI_B_COMMAND_INTERVAL_CLOCKS_16	16 interval clocks

ospi_b_command_cs_pullup_clocks_t

enum ospi_b_command_cs_pullup_clocks_t

OSPI chip select de-assertion duration

Enumerator
OSPI_B_COMMAND_CS_PULLUP_CLOCKS_NO_EXTENSION	CS asserting No extension.
OSPI_B_COMMAND_CS_PULLUP_CLOCKS_1	CS asserting Extend 1 cycle.

ospi_b_command_cs_pulldown_clocks_t

enum ospi_b_command_cs_pulldown_clocks_t

OSPI chip select assertion duration

Enumerator
OSPI_B_COMMAND_CS_PULLDOWN_CLOCKS_NO_EXTENSION	CS negating No extension.
OSPI_B_COMMAND_CS_PULLDOWN_CLOCKS_1	CS negating Extend 1 cycle.

ospi_b_prefetch_function_t

enum ospi_b_prefetch_function_t

Prefetch function settings

Enumerator
OSPI_B_PREFETCH_FUNCTION_DISABLE	Prefetch function disable.
OSPI_B_PREFETCH_FUNCTION_ENABLE	Prefetch function enable.

ospi_b_combination_function_t

enum ospi_b_combination_function_t

Combination function settings

Enumerator
OSPI_B_COMBINATION_FUNCTION_DISABLE	Combination function disable.
OSPI_B_COMBINATION_FUNCTION_4BYTE	Combine up to 4 bytes.
OSPI_B_COMBINATION_FUNCTION_8BYTE	Combine up to 8 bytes.
OSPI_B_COMBINATION_FUNCTION_12BYTE	Combine up to 12 bytes.
OSPI_B_COMBINATION_FUNCTION_16BYTE	Combine up to 16 bytes.
OSPI_B_COMBINATION_FUNCTION_20BYTE	Combine up to 20 bytes.
OSPI_B_COMBINATION_FUNCTION_24BYTE	Combine up to 24 bytes.
OSPI_B_COMBINATION_FUNCTION_28BYTE	Combine up to 28 bytes.
OSPI_B_COMBINATION_FUNCTION_32BYTE	Combine up to 32 bytes.
OSPI_B_COMBINATION_FUNCTION_36BYTE	Combine up to 36 bytes.
OSPI_B_COMBINATION_FUNCTION_40BYTE	Combine up to 40 bytes.
OSPI_B_COMBINATION_FUNCTION_44BYTE	Combine up to 44 bytes.
OSPI_B_COMBINATION_FUNCTION_48BYTE	Combine up to 48 bytes.
OSPI_B_COMBINATION_FUNCTION_52BYTE	Combine up to 52 bytes.
OSPI_B_COMBINATION_FUNCTION_56BYTE	Combine up to 56 bytes.
OSPI_B_COMBINATION_FUNCTION_60BYTE	Combine up to 60 bytes.
OSPI_B_COMBINATION_FUNCTION_64BYTE	Combine up to 64 bytes.
OSPI_B_COMBINATION_FUNCTION_2BYTE	Combine up to 2 bytes.

Function Documentation

R_OSPI_B_Open()

fsp_err_t R_OSPI_B_Open	(	spi_flash_ctrl_t *const	p_ctrl,
		spi_flash_cfg_t const *const	p_cfg
	)

Open the xSPI device. After the driver is open, the xSPI device can be accessed like internal flash memory.

Implements spi_flash_api_t::open.

Return values

FSP_SUCCESS	Configuration was successful.
FSP_ERR_ASSERTION	The parameter p_ctrl or p_cfg is NULL.
FSP_ERR_ALREADY_OPEN	Driver has already been opened with the same p_ctrl.
FSP_ERR_CALIBRATE_FAILED	Failed to perform auto-calibrate.

R_OSPI_B_DirectWrite()

fsp_err_t R_OSPI_B_DirectWrite	(	spi_flash_ctrl_t *	p_ctrl,
		uint8_t const *const	p_src,
		uint32_t const	bytes,
		bool const	read_after_write
	)

Writes raw data directly to the OctaFlash. API not supported. Use R_OSPI_B_DirectTransfer

Implements spi_flash_api_t::directWrite.

Return values

FSP_ERR_UNSUPPORTED

API not supported by OSPI.

R_OSPI_B_DirectRead()

fsp_err_t R_OSPI_B_DirectRead	(	spi_flash_ctrl_t *	p_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes
	)

Reads raw data directly from the OctaFlash. API not supported. Use R_OSPI_B_DirectTransfer.

Implements spi_flash_api_t::directRead.

Return values

FSP_ERR_UNSUPPORTED

API not supported by OSPI.

R_OSPI_B_DirectTransfer()

fsp_err_t R_OSPI_B_DirectTransfer	(	spi_flash_ctrl_t *	p_ctrl,
		spi_flash_direct_transfer_t *const	p_transfer,
		spi_flash_direct_transfer_dir_t	direction
	)

Read/Write raw data directly with the OctaFlash.

Implements spi_flash_api_t::directTransfer.

Return values

FSP_SUCCESS	The flash was programmed successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.

R_OSPI_B_XipEnter()

fsp_err_t R_OSPI_B_XipEnter

(

spi_flash_ctrl_t *

p_ctrl

)

Enters XIP (execute in place) mode.

Implements spi_flash_api_t::xipEnter.

Return values

FSP_SUCCESS	XiP mode was entered successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_UNSUPPORTED	XiP support is not enabled.

R_OSPI_B_XipExit()

fsp_err_t R_OSPI_B_XipExit

(

spi_flash_ctrl_t *

p_ctrl

)

Exits XIP (execute in place) mode.

Implements spi_flash_api_t::xipExit.

Return values

FSP_SUCCESS	XiP mode was entered successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_UNSUPPORTED	XiP support is not enabled.

R_OSPI_B_Write()

fsp_err_t R_OSPI_B_Write	(	spi_flash_ctrl_t *	p_ctrl,
		uint8_t const *const	p_src,
		uint8_t *const	p_dest,
		uint32_t	byte_count
	)

Program a page of data to the flash.

Implements spi_flash_api_t::write.

Return values

FSP_SUCCESS	The flash was programmed successfully.
FSP_ERR_ASSERTION	p_instance_ctrl, p_dest or p_src is NULL, or byte_count crosses a page boundary.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_INVALID_SIZE	Insufficient space remaining in page or write length is not a multiple of CPU access size when not using the DMAC.
FSP_ERR_DEVICE_BUSY	Another Write/Erase transaction is in progress.
FSP_ERR_WRITE_FAILED	Write operation failed.
FSP_ERR_INVALID_ADDRESS	Destination or source is not aligned to CPU access alignment when not using the DMAC.

R_OSPI_B_Erase()

fsp_err_t R_OSPI_B_Erase	(	spi_flash_ctrl_t *	p_ctrl,
		uint8_t *const	p_device_address,
		uint32_t	byte_count
	)

Erase a block or sector of flash. The byte_count must exactly match one of the erase sizes defined in spi_flash_cfg_t. For chip erase, byte_count must be SPI_FLASH_ERASE_SIZE_CHIP_ERASE.

Implements spi_flash_api_t::erase.

Return values

FSP_SUCCESS	The command to erase the flash was executed successfully.
FSP_ERR_ASSERTION	p_instance_ctrl or p_device_address is NULL, byte_count doesn't match an erase size defined in spi_flash_cfg_t, or byte_count is set to 0.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_DEVICE_BUSY	The device is busy.
FSP_ERR_WRITE_FAILED	Write operation failed.

R_OSPI_B_StatusGet()

fsp_err_t R_OSPI_B_StatusGet	(	spi_flash_ctrl_t *	p_ctrl,
		spi_flash_status_t *const	p_status
	)

Gets the write or erase status of the flash.

Implements spi_flash_api_t::statusGet.

Return values

FSP_SUCCESS	The write status is in p_status.
FSP_ERR_ASSERTION	p_instance_ctrl or p_status is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.

R_OSPI_B_BankSet()

fsp_err_t R_OSPI_B_BankSet	(	spi_flash_ctrl_t *	p_ctrl,
		uint32_t	bank
	)

Selects the bank to access. Use ospi_b_bank_select_t as the bank value.

Implements spi_flash_api_t::bankSet.

Return values

FSP_ERR_UNSUPPORTED

This function is unsupported.

R_OSPI_B_SpiProtocolSet()

fsp_err_t R_OSPI_B_SpiProtocolSet	(	spi_flash_ctrl_t *	p_ctrl,
		spi_flash_protocol_t	spi_protocol
	)

Sets the SPI protocol.

Implements spi_flash_api_t::spiProtocolSet.

Return values

FSP_SUCCESS	SPI protocol updated on MPU peripheral.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_CALIBRATE_FAILED	Failed to perform auto-calibrate.

R_OSPI_B_Close()

fsp_err_t R_OSPI_B_Close

(

spi_flash_ctrl_t *

p_ctrl

)

Close the OSPI driver module.

Implements spi_flash_api_t::close.

Return values

FSP_SUCCESS	Configuration was successful.
FSP_ERR_ASSERTION	p_instance_ctrl is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.

R_OSPI_B_AutoCalibrate()

fsp_err_t R_OSPI_B_AutoCalibrate

(

spi_flash_ctrl_t *const

p_ctrl

)

AutoCalibrate the OSPI_B DS signal.

Implements spi_flash_api_t::autoCalibrate.

Return values

FSP_SUCCESS	Autocalibration completed successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	Driver is not opened.
FSP_ERR_UNSUPPORTED	Autocalibration support is not enabled.
FSP_ERR_CALIBRATE_FAILED	Failed to perform auto-calibrate.

R_OSPI_B_DOTF_Configure()

fsp_err_t R_OSPI_B_DOTF_Configure	(	spi_flash_ctrl_t *const	p_ctrl,
		ospi_b_dotf_cfg_t *const	p_dotf_cfg
	)

Configure DOTF

Parameters

[in]	p_ctrl	Pointer to OSPI specific control structure
[in]	p_dotf_cfg	Pointer to DOTF configuration structure

Return values

FSP_SUCCESS	DOTF enabled successfully
FSP_ERR_CRYPTO_SCE_KEY_SET_FAIL	Key initialization failed.
FSP_ERR_CRYPTO_SCE_FAIL	Key wrapping failed.
FSP_ERR_INVALID_ARGUMENT	Invalid key type argument.
FSP_ERR_UNSUPPORTED	DOTF support is not enabled