SPI

group SPI

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

Defines

PI_SPI_DUMMY_CLK_CYCLE_MODE_DEFAULT

PI_SPI_DUMMY_CLK_CYCLE_DEFAULT

PI_SPI_DUMMY_CLK_CYCLE_MIN

PI_SPI_DUMMY_CLK_CYCLE_MAX

PI_SPI_IS_VALID_DUMMY_CLK_CYCLE(cycle)

PI_SPI_IS_VALID_DUMMY_CLK_CYCLE_MODE(mode)

Enums

enum pi_spi_wordsize_e

Wordsize of the SPI bitstream elements.

This is used to know how the endianness must be applied. Not all sizes are supported on all chips, check the chip-specific section to get more information.

Values:

enumerator PI_SPI_WORDSIZE_8 = 0: Each element is 8 bits. Thus the endianness has no effect.

enumerator PI_SPI_WORDSIZE_16 = 1: Each element is 16 bits. The way each element is stored in memory can then be specified with the endianness.

enumerator PI_SPI_WORDSIZE_32 = 2: Each element is 32 bits. The way each element is stored in memory can then be specified with the endianness.

enum pi_spi_polarity_e

Clock polarity.

Values:

enumerator PI_SPI_POLARITY_0 = 0: Leading edge is rising edge, trailing edge is falling edge.

enumerator PI_SPI_POLARITY_1 = 1: Leading edge is falling edge, trailing edge is rising edge.

enum pi_spi_dummy_clk_cycle_mode_e

Values:

enumerator PI_SPI_DUMMY_CLK_CYCLE_BEFORE_CS = 0: Dummy clock cycles are sent before toggling Chip select

enumerator PI_SPI_DUMMY_CLK_CYCLE_AFTER_CS = 1: Dummy clock cycles are sent after toggling Chip select

enum pi_spi_phase_e

Clock phase.

Values:

enumerator PI_SPI_PHASE_0 = 0: Data shifted out on trailing edge of preceding clock cycle. Data sampled on leading edge of clock cycle.

enumerator PI_SPI_PHASE_1 = 1: Data shifted out on leading edge of current clock cycle. Data sampled on trailing edge of clock cycle.

enum pi_spi_ioctl_e

Possible parameters which can be set through the pi_spi_control API function.

This is used to reconfigure dynamically some of the parameters of an opened device.

Values:

enumerator PI_SPI_CTRL_CPOL0 = 1 << __PI_SPI_CTRL_CPOL_BIT: Set the clock polarity to 0.

enumerator PI_SPI_CTRL_CPOL1 = 2 << __PI_SPI_CTRL_CPOL_BIT: Set the clock polarity to 1.

enumerator PI_SPI_CTRL_CPHA0 = 1 << __PI_SPI_CTRL_CPHA_BIT: Set the clock phase to 0.

enumerator PI_SPI_CTRL_CPHA1 = 2 << __PI_SPI_CTRL_CPHA_BIT: Set the clock phase to 1.

enumerator PI_SPI_CTRL_WORDSIZE_8 = 1 << __PI_SPI_CTRL_WORDSIZE_BIT: Set the wordsize to 8 bits.

enumerator PI_SPI_CTRL_WORDSIZE_32 = 2 << __PI_SPI_CTRL_WORDSIZE_BIT: Set the wordsize to 32 bits.

enumerator PI_SPI_CTRL_BIG_ENDIAN = 1 << __PI_SPI_CTRL_ENDIANNESS_BIT: Handle the elements in memory in a big-endian way.

enumerator PI_SPI_CTRL_LITTLE_ENDIAN = 2 << __PI_SPI_CTRL_ENDIANNESS_BIT: Handle the elements in memory in a little-endian way.

enumerator PI_SPI_CTRL_SET_MAX_BAUDRATE = 1 << __PI_SPI_CTRL_SET_MAX_BAUDRATE_BIT: Change maximum baudrate.

enumerator PI_SPI_CTRL_SET_TIMESTAMP = 1 << __PI_SPI_CTRL_SET_TIMESTAMP: Enable the timestamp for SPI.

enum pi_spi_flags_e

Specifies additional behaviors for transfers.

This flags can be given when transfering data.

Values:

enumerator PI_SPI_CS_AUTO = 0 << 0: Handles the chip select automatically. It is set low just before the transfer is started and set back high when the transfer is finished.

enumerator PI_SPI_CS_KEEP = 1 << 0: Handle the chip select manually. It is set low just before the transfer is started and is kept low until the next transfer.

enumerator PI_SPI_CS_NONE = 2 << 0: Don’t do anything with the chip select.

enumerator PI_SPI_LINES_SINGLE = 0 << 2: Use a single MISO line.

enumerator PI_SPI_LINES_QUAD = 1 << 2: Use quad MISO lines.

enumerator PI_SPI_LINES_OCTAL = 2 << 2: Use octal MISO lines.

enumerator PI_SPI_COPY_EXT2LOC = 1 << 4: Do a copy from external memory to local chip memory.

enumerator PI_SPI_COPY_LOC2EXT = 0 << 4: Do a copy from local chip memory to external memory.

Functions

void pi_spi_conf_init(struct pi_spi_conf *conf)

Initialize an SPI master configuration with default values.

This function can be called to get default values for all parameters before setting some of them. The structure containing the configuration must be kept alive until the SPI device is opened.

Parameters:

conf – A pointer to the SPI master configuration.

int pi_spi_open(struct pi_device *device)

Open an SPI device.

This function must be called before the SPI 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. The caller is blocked until the operation is finished.

Parameters:

device – A pointer to the device structure of the device to open. This structure is allocated by the caller 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_spi_close(struct pi_device *device)

Close an opened SPI device.

This function can be called to close an opened SPI 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. The caller is blocked until the operation is finished.

Parameters:

device – A pointer to the structure describing the device.

void pi_spi_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.

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.

void pi_spi_send(struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag)

Enqueue a write copy to the SPI (from Chip to SPI device).

This function can be used to send data to the SPI device. The copy will make a synchronous transfer between the SPI and one of the chip memory. This is by default using classic SPI transfer with MOSI and MISO lines, but other kind of transfers like quad SPI can be used by specifying additional flags. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
data – The address in the chip where the data to be sent must be read.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.

void pi_spi_receive(struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag)

Enqueue a read copy to the SPI (from Chip to SPI device).

This function can be used to receive data from the SPI device. The copy will make a synchronous transfer between the SPI and one of the chip memory. This is by default using classic SPI transfer with MOSI and MISO lines, but other kind of transfers like quad SPI can be used by specifying additional flags. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
data – The address in the chip where the received data must be written.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.

void pi_spi_transfer(struct pi_device *device, void *tx_data, void *rx_data, size_t len, pi_spi_flags_e flag)

Enqueue a read and write copy to the SPI (using full duplex mode).

This function can be used to send and receive data with the SPI device using full duplex mode. The copy will make a synchronous transfer between the SPI and one of the chip memory. This is using classic SPI transfer with MOSI and MISO lines. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
tx_data – The address in the chip where the data to be sent must be read.
rx_data – The address in the chip where the received data must be written.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.

void pi_spi_send_async(struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag, pi_evt_t *task)

Enqueue an asynchronous write copy to the SPI (from Chip to SPI device).

This function can be used to send data to the SPI device. The copy will make an asynchronous transfer between the SPI and one of the chip memory. This is by default using classic SPI transfer with MOSI and MISO lines, but other kind of transfers like quad SPI can be used by specifying additional flags. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
data – The address in the chip where the data to be sent must be read.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.
task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.details.

void pi_spi_receive_async(struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag, pi_evt_t *task)

Enqueue an asynchronous read copy to the SPI (from Chip to SPI device).

This function can be used to receive data from the SPI device. The copy will make an asynchronous transfer between the SPI and one of the chip memory. This is by default using classic SPI transfer with MOSI and MISO lines, but other kind of transfers like quad SPI can be used by specifying additional flags. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
data – The address in the chip where the received data must be written.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.
task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.details.details.

void pi_spi_transfer_async(struct pi_device *device, void *tx_data, void *rx_data, size_t len, pi_spi_flags_e flag, pi_evt_t *task)

Enqueue an asynchronous read and write copy to the SPI (using full duplex mode).

This function can be used to send and receive data with the SPI device using full duplex flag. The copy will make an asynchronous transfer between the SPI and one of the chip memory. This is using classic SPI transfer with MOSI and MISO lines. Due to hardware constraints, the address of the buffer must be aligned on 4 bytes and the size must be a multiple of 4. 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 – A pointer to the structure describing the device.
tx_data – The address in the chip where the data to be sent must be read.
rx_data – The address in the chip where the received data must be written.
len – The size in bits of the copy.
flag – Additional behaviors for the transfer can be specified using this flag. Can be 0 to use the default flag, which is using PI_SPI_CS_AUTO and PI_SPI_LINES_SINGLE.
task – The task used to notify the end of transfer. See the documentation of pi_evt_t for more details.details.details.

struct pi_spi_conf

Public Members

int max_baudrate: Maximum baudrate for the SPI bitstream which can be used with the opened device .

char wordsize: Wordsize of the elements in the bitstream. Can be PI_SPI_WORDSIZE_8 for 8 bits data or PI_SPI_WORDSIZE_32 for 32 bits data. This is used to interpret the endianness.

char big_endian: If 1, the elements are stored in memory in a big-endian way, i.e. the most significant byte is stored at the lowest address. This is taken into account only if the wordsize is 32 bits.

pi_spi_polarity_e polarity: Polarity of the clock.

pi_spi_phase_e phase: Phase of the clock.

signed char cs: Specifies which SPI chip select is used for the device.

signed char itf: Specifies on which SPI interface the device is connected.

int max_rcv_chunk_size: Specifies maximum chunk size for reception when using copies.

int max_snd_chunk_size: Specifies maximum chunk size for sending when using copies.

int is_slave: If 1, the SPI interface is configured as a slave.

uint8_t ts_ch: Enable the timestamp on TX (0) or RX (1)

uint8_t ts_evt_id: UDMA Config Event ID for generating the timestamp

uint8_t dummy_clk_cycle: Number of clock cycles to send before sending the data.

pi_spi_dummy_clk_cycle_mode_e dummy_clk_cycle_mode: Select if dummy clock cycles are sent before or after toggling the chip select.

struct pi_spi_conf_t

#include <spi.h>

SPI master configuration structure.

This structure is used to pass the desired SPI master configuration to the runtime when opening a device.