SPI

Data Structures
struct	pi_spi_conf
struct	pi_spi_conf_t
	SPI master configuration structure. More...

Enumerations
enum	pi_spi_wordsize_e
	Wordsize of the SPI bitstream elements. More...
enum	pi_spi_polarity_e
enum	pi_spi_phase_e
enum	pi_spi_ioctl_e
	Possible parameters which can be set through the pi_spi_control API function. More...
enum	pi_spi_flags_e
	Specifies additional behaviors for transfers. More...

Functions
void	pi_spi_conf_init (struct pi_spi_conf *conf)
	Initialize an SPI master configuration with default values. More...
int	pi_spi_open (struct pi_device *device)
	Open an SPI device. More...
void	pi_spi_close (struct pi_device *device)
	Close an opened SPI device. More...
void	pi_spi_ioctl (struct pi_device *device, uint32_t cmd, void *arg)
	Dynamically change the device configuration. More...
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). More...
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). More...
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). More...
void	pi_spi_send_async (struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag, pi_task_t *task)
	Enqueue an asynchronous write copy to the SPI (from Chip to SPI device). More...
void	pi_spi_receive_async (struct pi_device *device, void *data, size_t len, pi_spi_flags_e flag, pi_task_t *task)
	Enqueue an asynchronous read copy to the SPI (from Chip to SPI device). More...
void	pi_spi_transfer_async (struct pi_device *device, void *tx_data, void *rx_data, size_t len, pi_spi_flags_e flag, pi_task_t *task)
	Enqueue an asynchronous read and write copy to the SPI (using full duplex mode). More...

Description

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

Enumeration Type Documentation

enum pi_spi_flags_e

This flags can be given when transfering data.

Enumerator
PI_SPI_CS_AUTO	Handles the chip select automatically. It is set low just before the transfer is started and set back high when the transfer is finished.
PI_SPI_CS_KEEP	Handle the chip select manually. It is set low just before the transfer is started and is kept low until the next transfer.
PI_SPI_CS_NONE	Don't do anything with the chip select.
PI_SPI_LINES_SINGLE	Use a single MISO line.
PI_SPI_LINES_QUAD	Use quad MISO lines.
PI_SPI_LINES_OCTAL	Use octal MISO lines.
PI_SPI_COPY_EXT2LOC	Do a copy from external memory to local chip memory.
PI_SPI_COPY_LOC2EXT	Do a copy from local chip memory to external memory.

enum pi_spi_ioctl_e

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

Enumerator
PI_SPI_CTRL_CPOL0	Set the clock polarity to 0.
PI_SPI_CTRL_CPOL1	Set the clock polarity to 1.
PI_SPI_CTRL_CPHA0	Set the clock phase to 0.
PI_SPI_CTRL_CPHA1	Set the clock phase to 1.
PI_SPI_CTRL_WORDSIZE_8	Set the wordsize to 8 bits.
PI_SPI_CTRL_WORDSIZE_32	Set the wordsize to 32 bits.
PI_SPI_CTRL_BIG_ENDIAN	Handle the elements in memory in a big-endian way.
PI_SPI_CTRL_LITTLE_ENDIAN	Handle the elements in memory in a little-endian way.
PI_SPI_CTRL_SET_MAX_BAUDRATE	Change maximum baudrate.

enum pi_spi_phase_e

Clock phase.

Enumerator
PI_SPI_PHASE_0	Data shifted out on trailing edge of preceding clock cycle. Data sampled on leading edge of clock cycle.
PI_SPI_PHASE_1	Data shifted out on leading edge of current clock cycle. Data sampled on trailing edge of clock cycle.

enum pi_spi_polarity_e

Clock polarity.

Enumerator
PI_SPI_POLARITY_0	Leading edge is rising edge, trailing edge is falling edge.
PI_SPI_POLARITY_1	Leading edge is falling edge, trailing edge is rising edge.

enum pi_spi_wordsize_e

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.

Enumerator
PI_SPI_WORDSIZE_8	Each element is 8 bits. Thus the endianness has no effect.
PI_SPI_WORDSIZE_16	Each element is 16 bits. The way each element is stored in memory can then be specified with the endianness.
PI_SPI_WORDSIZE_32	Each element is 32 bits. The way each element is stored in memory can then be specified with the endianness.

Function Documentation

void pi_spi_close

(

struct pi_device *

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_conf_init

(

struct pi_spi_conf *

conf

)

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.

void pi_spi_ioctl	(	struct pi_device *	device,
		uint32_t	cmd,
		void *	arg
	)

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.

int pi_spi_open

(

struct pi_device *

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_receive	(	struct pi_device *	device,
		void *	data,
		size_t	len,
		pi_spi_flags_e	flag
	)

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_receive_async	(	struct pi_device *	device,
		void *	data,
		size_t	len,
		pi_spi_flags_e	flag,
		pi_task_t *	task
	)

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_task_t for more details.details.details.

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

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_send_async	(	struct pi_device *	device,
		void *	data,
		size_t	len,
		pi_spi_flags_e	flag,
		pi_task_t *	task
	)

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_task_t for more details.details.

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

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_transfer_async	(	struct pi_device *	device,
		void *	tx_data,
		void *	rx_data,
		size_t	len,
		pi_spi_flags_e	flag,
		pi_task_t *	task
	)

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_task_t for more details.details.details.