Hyperbus

group Hyperbus

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

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

Typedefs

typedef struct pi_hyper_conf pi_hyper_conf_t
typedef struct pi_cl_hyper_req_s pi_cl_hyper_req_t

Hyperbus cluster request structure.

This structure is used by the runtime to manage a cluster remote copy with the Hyperbus. 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_hyper_type_e

Type of the device connected to the hyperbus interface.

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

Values:

enumerator PI_HYPER_TYPE_FLASH

Device is an Hyperflash.

enumerator PI_HYPER_TYPE_RAM

Device is an Hyperram.

enum pi_hyper_ioctl_cmd

IOCTL command

Values:

enumerator PI_HYPER_IOCTL_SET_LATENCY

Set the device latency.

This command can be used when the interface has been opened to configure the latency suitable for the device.

Functions

void pi_hyper_conf_init(struct pi_hyper_conf *conf)

Initialize an Hyperbus configuration with default values.

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

Parameters:

  • conf – A pointer to the Hyperbus configuration.

int32_t pi_hyper_open(pi_device_t *device)

Open an Hyperbus device.

This function must be called before the Hyperbus 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_hyper_close(pi_device_t *device)

Close an opened Hyperbus device.

This function can be called to close an opened Hyperbus 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_hyper_ioctl(pi_device_t *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_hyper_ioctl_e.

  • arg – An additional value which is required for some parameters when they are set.

PI_INLINE_HYPER_LVL_0 void pi_hyper_read(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size)

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

The copy will make a transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

PI_INLINE_HYPER_LVL_0 void pi_hyper_read_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, pi_evt_t *task)

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

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_HYPER_LVL_0 void pi_hyper_write(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size)

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

The copy will make a transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

PI_INLINE_HYPER_LVL_0 void pi_hyper_write_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, pi_evt_t *task)

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

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_HYPER_LVL_0 void pi_hyper_read_2d(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length)

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

The copy will make a transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

PI_INLINE_HYPER_LVL_0 void pi_hyper_read_2d_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_evt_t *task)

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

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_HYPER_LVL_0 void pi_hyper_write_2d(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length)

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

The copy will make a transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

PI_INLINE_HYPER_LVL_0 void pi_hyper_write_2d_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_evt_t *task)

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

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_HYPER_LVL_0 void pi_hyper_copy_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, int ext2loc, pi_evt_t *task)

Enqueue an asynchronous copy to the Hyperbus.

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task must be specified in order to specify how the caller should be notified when the transfer is finished. The transfer can be either a read or a write. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details. The hyper address specified with this function must be added the offset returned by pi_hyper_offset.

Parameters:

  • device – The device descriptor of the Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus, which must contain the hyper offset.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • ext2loc – 1 if the copy is from HyperBus to the chip or 0 for the contrary.

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

PI_INLINE_HYPER_LVL_0 void pi_hyper_copy_2d_async(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, int ext2loc, pi_evt_t *task)

Enqueue an asynchronous 2D copy (rectangle area) to the Hyperbus.

The copy will make an asynchronous transfer between the Hyperbus and one of the processor memory areas. A task must be specified in order to specify how the caller should be notified when the transfer is finished. The transfer can be either a read or a write. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details. The hyper address specified with this function must be added the offset returned by pi_hyper_offset.

Parameters:

  • device – The device descriptor of the Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus, which must contain the hyper offset.

  • 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 HyperBus to the chip or 0 for the contrary.

  • task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.

static inline void pi_cl_hyper_read(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, pi_cl_hyper_req_t *req)

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

This function is a remote call that the cluster can do to the fabric-controller in order to ask for an HyperBus read copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_hyper_read_2d(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_cl_hyper_req_t *req)

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

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an HyperBus read copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_hyper_read_wait(pi_cl_hyper_req_t *req)

Wait until the specified hyperbus 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_hyper_write(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, pi_cl_hyper_req_t *req)

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

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an HyperBus write copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_hyper_write_2d(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, pi_cl_hyper_req_t *req)

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

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an HyperBus write copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

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

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_hyper_write_wait(pi_cl_hyper_req_t *req)

Wait until the specified hyperbus 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_hyper_copy(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, int ext2loc, pi_cl_hyper_req_t *req)

Enqueue a copy with the Hyperbus from cluster side.

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an HyperBus copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • addr – The address of the copy in the processor.

  • size – The size in bytes of the copy

  • ext2loc – 1 if the copy is from HyperBus to the chip or 0 for the contrary.

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

static inline void pi_cl_hyper_copy_2d(pi_device_t *device, uint32_t hyper_addr, void *addr, uint32_t size, uint32_t stride, uint32_t length, int ext2loc, pi_cl_hyper_req_t *req)

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

This function is a remote call that the cluster can issue to the fabric-controller in order to ask for an HyperBus copy. The copy will make an asynchronous transfer between the Hyperbus 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 Hyperbus chip on which to do the copy.

  • hyper_addr – The address of the copy in the Hyperbus.

  • 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 HyperBus to the chip or 0 for the contrary.

  • req – A pointer to the HyperBus request structure. It must be allocated by the caller and kept alive until the copy is finished.

void pi_hyper_xip_lock(pi_device_t *device)

Forbid XIP refills.

This function can be called to prevent the hyperbus 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_hyper_xip_unlock(pi_device_t *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.

PI_INLINE_HYPER_LVL_0 uint32_t pi_hyper_offset(struct pi_device *device)

Return hyperbus address offset.

Some functions of the API require that an offset is added to the hyperbus address. This functions can be called to retrieve the offset to be applied. See the documentation of each function to see which ones need this offset.

Parameters:

  • device – The device structure of the device.

struct pi_hyper_conf
#include <hyperbus.h>

Hyperbus configuration structure.

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

Public Members

signed char id

Hyperbus interface where the device is connected.

uint32_t cs

Chip select where the device is connected.

pi_hyper_type_e type

Type of device connected on the hyperbus interface.

uint32_t baudrate

Baudrate (in bytes/second).