OctoSPI

group Octospi

The Octospi driver provides support for transferring data between an external Octospi chip and the processor running this driver.

This is a driver for the Octospi interface. Higher-level drivers can be built on top of this one to target specific devices such as Octospiflash or Octospiram. Please refer to the PMSIS BSP documentation for such drivers.

Typedefs

typedef struct pi_octospi_op_conf pi_octospi_op_conf_t

typedef struct pi_octospi_conf pi_octospi_conf_t

typedef struct pi_cl_octospi_req_s pi_cl_octospi_req_t

Octospi cluster request structure.

This structure is used by the runtime to manage a cluster remote copy with the Octospi. It must be instantiated once for each copy and must be kept alive until the copy is finished. It can be instantiated as a normal variable, for example as a global variable, a local one on the stack, or through a memory allocator.

Enums

enum pi_octospi_type_e

Type of the device connected to the octospi interface.

This is used to know if the device is a flash or a RAM.

Values:

enumerator PI_OCTOSPI_TYPE_FLASH: Device is an Octospiflash.

enumerator PI_OCTOSPI_TYPE_RAM: Device is an Octospiram.

enum pi_octospi_flags_e

SPI operation flags.

This is used to describe some SPI operation flags like command size, address size and so on.

Values:

enumerator PI_OCTOSPI_FLAG_CMD_SIZE_0 = (0 << PI_OCTOSPI_FLAG_CMD_SIZE_OFFSET): No command.

enumerator PI_OCTOSPI_FLAG_CMD_SIZE_1 = (1 << PI_OCTOSPI_FLAG_CMD_SIZE_OFFSET): Command is 1 byte.

enumerator PI_OCTOSPI_FLAG_CMD_SIZE_2 = (2 << PI_OCTOSPI_FLAG_CMD_SIZE_OFFSET): Command is 2 bytes.

enumerator PI_OCTOSPI_FLAG_ADDR_SIZE_0 = (0 << PI_OCTOSPI_FLAG_ADDR_SIZE_OFFSET): No address.

enumerator PI_OCTOSPI_FLAG_ADDR_SIZE_1 = (1 << PI_OCTOSPI_FLAG_ADDR_SIZE_OFFSET): Address is 1 byte.

enumerator PI_OCTOSPI_FLAG_ADDR_SIZE_2 = (2 << PI_OCTOSPI_FLAG_ADDR_SIZE_OFFSET): Address is 2 bytes.

enumerator PI_OCTOSPI_FLAG_ADDR_SIZE_3 = (3 << PI_OCTOSPI_FLAG_ADDR_SIZE_OFFSET): Address is 3 bytes.

enumerator PI_OCTOSPI_FLAG_ADDR_SIZE_4 = (4 << PI_OCTOSPI_FLAG_ADDR_SIZE_OFFSET): Address is 4 bytes.

enumerator PI_OCTOSPI_FLAG_LINE_SINGLE = (2 << PI_OCTOSPI_FLAG_LINE_OFFSET): Use 1 SPI line.

enumerator PI_OCTOSPI_FLAG_LINE_QUAD = (1 << PI_OCTOSPI_FLAG_LINE_OFFSET): Use 4 SPI lines.

enumerator PI_OCTOSPI_FLAG_LINE_OCTO = (0 << PI_OCTOSPI_FLAG_LINE_OFFSET): Use 8 SPI lines.

enumerator PI_OCTOSPI_FLAG_CMD_DTR = (0 << PI_OCTOSPI_FLAG_CMD_RATE_OFFSET): Use DTR mode for command.

enumerator PI_OCTOSPI_FLAG_CMD_STR = (1 << PI_OCTOSPI_FLAG_CMD_RATE_OFFSET): Use STR mode for command.

enumerator PI_OCTOSPI_FLAG_ADDR_DTR = (0 << PI_OCTOSPI_FLAG_ADDR_RATE_OFFSET): Use DTR mode for address.

enumerator PI_OCTOSPI_FLAG_ADDR_STR = (1 << PI_OCTOSPI_FLAG_ADDR_RATE_OFFSET): Use STR mode for address.

enumerator PI_OCTOSPI_FLAG_DATA_DTR = (0 << PI_OCTOSPI_FLAG_DATA_RATE_OFFSET): Use DTR mode for data.

enumerator PI_OCTOSPI_FLAG_DATA_STR = (1 << PI_OCTOSPI_FLAG_DATA_RATE_OFFSET): Use STR mode for data.

enumerator PI_OCTOSPI_FLAG_DATA_DTR_LSB = (0 << PI_OCTOSPI_FLAG_DATA_RATE_MSB_OFFSET): Use LSB in DTR mode for data.

enumerator PI_OCTOSPI_FLAG_DATA_DTR_MSB = (1 << PI_OCTOSPI_FLAG_DATA_RATE_MSB_OFFSET): Use MSB in DTR mode for data.

enum pi_octospi_cmd_e

SPI operation command flags.

This is used to describe some SPI operation flags for the command.

Values:

enumerator PI_OCTOSPI_CMD_AUTO_RW_BIT_EN = (1 << PI_OCTOSPI_CMD_AUTO_RW_BIT_EN_OFFSET): Automatically generate additional R/W bit at MSB on top of the specified SPI command. When using automatic R/W bit generation, this will generate 1 if the operation is a read.

enumerator PI_OCTOSPI_CMD_AUTO_RW_BIT_SET_READ = (1 << PI_OCTOSPI_CMD_AUTO_RW_BIT_READ_OFFSET): Always send even addresses to the device.

enumerator PI_OCTOSPI_CMD_ADDR_EVEN = (1 << PI_OCTOSPI_CMD_ADDR_OFFSET)

enum pi_octospi_ioctl_cmd

IOCTL command

Values:

enumerator PI_OCTOSPI_IOCTL_SET_OP

Configure the SPI operation.

This command can be used when the interface has been opened to configure the SPI operation used for the next transfer (latency, SPI command, etc). The argument must be a pointer to a variable of type pi_octospi_op_conf_t.

enumerator PI_OCTOSPI_IOCTL_SET_XIP_OP

Configure the SPI operation for XIP.

This command can be used when the interface has been opened to configure the SPI operation used for all XIP transfers (latency, SPI command, etc). The argument must be a pointer to a variable of type pi_octospi_op_conf_t. NOTE: For flash, only set read command, as XIP flash is RO

enumerator PI_OCTOSPI_IOCTL_ENABLE_AES

Enable AES.

This command can be used to enable/disable the on-the-fly AES at runtime

enumerator PI_OCTOSPI_IOCTL_MBA

Functions

void pi_octospi_conf_init(struct pi_octospi_conf *conf)

Initialize an Octospi configuration with default values.

The structure containing the configuration must be kept alive until the device is opened.

Parameters:

conf – A pointer to the Octospi configuration.

int32_t pi_octospi_open(struct pi_device *device)

Open an Octospi device.

This function must be called before the Octospi device can be used. It will do all the needed configuration to make it usable and initialize the handle used to refer to this opened device when calling other functions.

Parameters:

device – A pointer to the device structure of the device to open. This structure is allocated by the called and must be kept alive until the device is closed.

Returns:

0 if the operation is successfull, -1 if there was an error.

void pi_octospi_close(struct pi_device *device)

Close an opened Octospi device.

This function can be called to close an opened Octospi device once it is not needed anymore, in order to free all allocated resources. Once this function is called, the device is not accessible anymore and must be opened again before being used.

Parameters:

device – The device structure of the device to close.

int pi_octospi_ioctl(struct pi_device *device, uint32_t cmd, void *arg)

Dynamically change the device configuration.

This function can be called to change part of the device configuration after it has been opened or to control it.

Parameters:

device – A pointer to the structure describing the device.
cmd – The command which specifies which parameters of the driver to modify and for some of them also their values. The command must be one of those defined in pi_spi_ioctl_e.
arg – An additional value which is required for some parameters when they are set.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_read(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op)

Enqueue a read copy to the Octospi (from Octospi to processor).

The copy will make a transfer between the Octospi and one of the processor memory areas. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.

static inline void pi_octospi_read_async(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op, pi_evt_t *evt)

Enqueue an asynchronous read copy to the Octospi (from Octospi to processor).

The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
evt – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_write(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op)

Enqueue a write copy to the Octospi (from processor to Octospi).

The copy will make a transfer between the Octospi and one of the processor memory areas. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_write_async(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op, pi_evt_t *evt)

Enqueue an asynchronous write copy to the Octospi (from processor to Octospi).

The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
evt – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_read_2d(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op)

Enqueue a 2D read copy (rectangle area) to the Octospi (from Octospi to processor).

The copy will make a transfer between the Octospi and one of the processor memory areas. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_read_2d_async(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op, pi_evt_t *evt)

Enqueue an asynchronous 2D read copy (rectangle area) to the Octospi (from Octospi to processor).

The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
evt – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_write_2d(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op)

Enqueue a 2D write copy (rectangle area) to the Octospi (from processor to Octospi).

The copy will make a transfer between the Octospi and one of the processor memory areas. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.

PI_INLINE_OCTOSPI_LVL_0 void pi_octospi_write_2d_async(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op, pi_evt_t *evt)

Enqueue an asynchronous 2D write copy (rectangle area) to the Octospi (from processor to Octospi).

The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
evt – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

static inline void pi_cl_octospi_read(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a read copy to the Octospi from cluster side (from Octospi to processor).

This function is a remote call that the cluster can do to the fabric-controller in order to ask for an Octospi read copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_octospi_read_2d(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a 2D read copy (rectangle area) to the Octospi from cluster side (from Octospi to processor).

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an Octospi read copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy.
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_octospi_read_wait(pi_cl_octospi_req_t *req)

Wait until the specified octospi request has finished.

This blocks the calling core until the specified cluster remote copy is finished.

Parameters:

req – The request structure used for termination.

static inline void pi_cl_octospi_write(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a write copy to the Octospi from cluster side (from Octospi to processor).

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an Octospi write copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_octospi_write_2d(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a 2D write copy (rectangle area) to the Octospi from cluster side (from Octospi to processor).

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an Octospi write copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_octospi_write_wait(pi_cl_octospi_req_t *req)

Wait until the specified octospi request has finished.

This blocks the calling core until the specified cluster remote copy is finished.

Parameters:

req – The request structure used for termination.

static inline void pi_cl_octospi_copy(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, int ext2loc, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a copy with the Octospi from cluster side.

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an Octospi copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
ext2loc – 1 if the copy is from Octospi to the chip or 0 for the contrary.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_octospi_copy_2d(struct pi_device *device, uint32_t octospi_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, int ext2loc, pi_octospi_op_conf_t *op, pi_cl_octospi_req_t *req)

Enqueue a 2D copy (rectangle area) with the Octospi from cluster side.

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an Octospi copy. The copy will make an asynchronous transfer between the Octospi and one of the processor memory areas. A pointer to a request structure must be provided so that the runtime can properly do the remote call. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – The device descriptor of the Octospi chip on which to do the copy.
octospi_addr – The address of the copy in the Octospi.
addr – The address of the copy in the processor.
size – The size in bytes of the copy
stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.
length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.
ext2loc – 1 if the copy is from Octospi to the chip or 0 for the contrary.
op – The SPI operation configuration. Can be NULL to keep the latest one which was set.
req – A pointer to the Octospi request structure. It must be allocated by the caller and kept alive until the copy is finished.

void pi_octospi_xip_lock(struct pi_device *device)

Forbid XIP refills.

This function can be called to prevent the octospi from triggering any XIP refill transfer. This can be used to do an operation in a device which would make an XIP refill fail, like an erase operation. Be careful that locking XIP refills can lead to a deadlock if XIP code is executed so only local code must be execyted when the XIP refill is locked. This will only apply to the new transfer enqueued after calling this function, not to the pending transfers enqueued before.

Parameters:

device – The device structure of the device to close.

void pi_octospi_xip_unlock(struct pi_device *device)

Allow XIP refills.

This function can be called to allow again XIP refills after they have been forbidden.

Parameters:

device – The device structure of the device to close.

struct pi_octospi_op_conf

#include <octospi.h>

SPI operation configuration structure.

This structure is used to specify the desired SPI operation configuration. It can be passed either with a transfer or through IOCTL to set it permanently.

Public Members

uint32_t cmd: SPI command.

uint32_t latency: SPI dummy cycles.

uint32_t flags: SPI flags (command size, etc).

struct pi_octospi_conf

#include <octospi.h>

Octospi configuration structure.

This structure is used to pass the desired Octospi configuration to the runtime when opening the device.

Public Members

signed char id: Octospi interface where the device is connected.

uint8_t xip_en: Specify whether xip is on

uint32_t cs: Chip select where the device is connected.

pi_octospi_type_e type: Type of device connected on the octospi interface.

uint32_t baudrate: Baudrate (in bytes/second).

pi_aes_utils_conf_t *aes_conf: pointer to the AES configuration for on-the-fly encryption/decryption

uint32_t mba: Mapping base address for a given CS. Allows IP to choose CS based on input address.