spi.h File Reference

Public API for SPI drivers and applications. More...

#include <zephyr/types.h>
#include <stddef.h>
#include <zephyr/device.h>
#include <zephyr/dt-bindings/spi/spi.h>
#include <zephyr/drivers/gpio.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/__assert.h>
#include <zephyr/rtio/rtio.h>
#include <zephyr/stats/stats.h>
#include <zephyr/syscalls/spi.h>

Go to the source code of this file.

Data Structures
struct	spi_cs_control
	SPI Chip Select control structure. More...
struct	spi_config
	SPI controller configuration structure. More...
struct	spi_dt_spec
	Complete SPI DT information. More...
struct	spi_buf
	SPI buffer structure. More...
struct	spi_buf_set
	SPI scatter-gather buffer array structure. More...
struct	spi_driver_api
	SPI driver API This is the mandatory API any SPI driver needs to expose. More...

Macros
#define	SPI_CONFIG_DT(node_id, operation_, delay_)
	Structure initializer for spi_config from devicetree.
#define	SPI_CONFIG_DT_INST(inst, operation_, delay_)
	Structure initializer for spi_config from devicetree instance.
#define	SPI_DT_SPEC_GET(node_id, operation_, delay_)
	Structure initializer for spi_dt_spec from devicetree.
#define	SPI_DT_SPEC_INST_GET(inst, operation_, delay_)
	Structure initializer for spi_dt_spec from devicetree instance.
#define	SPI_MOSI_OVERRUN_UNKNOWN   0x100
	Value that will never compare true with any valid overrun character.
#define	SPI_MOSI_OVERRUN_DT(node_id)
	The value sent on MOSI when all TX bytes are sent, but RX continues.
#define	SPI_MOSI_OVERRUN_DT_INST(inst)
	The value sent on MOSI when all TX bytes are sent, but RX continues.
#define	SPI_STATS_RX_BYTES_INC(dev_)
#define	SPI_STATS_TX_BYTES_INC(dev_)
#define	SPI_STATS_TRANSFER_ERROR_INC(dev_)
#define	spi_transceive_stats(dev, error, tx_bufs, rx_bufs)
#define	SPI_DEVICE_DT_INST_DEFINE(inst, ...)
SPI operational mode
#define	SPI_OP_MODE_MASTER   0U
	Master (controller) mode.
#define	SPI_OP_MODE_SLAVE   BIT(0)
	Slave (peripheral) mode.
#define	SPI_OP_MODE_GET(_operation_)
	Get SPI Operational mode bitmask from a spi_operation_t.
SPI Clock Modes
#define	SPI_MODE_CPOL   BIT(1)
	Clock Polarity (Clock Idle State)
#define	SPI_MODE_CPHA   BIT(2)
	Clock Phase (Clock data capture edge)
#define	SPI_MODE_LOOP   BIT(3)
	Controller loopback mode.
#define	SPI_MODE_GET(_mode_)
	Get SPI clock polarity and phase mode bitmask from a spi_operation_t.
SPI Data Word Configurations
A SPI Data word is a value that is shifted in/out of the controller's hardware FIFO and is the atomic unit of communication on the spi bus. A word is also called a "data frame" in this API. A transfer is made up of an arbitrary number of words. The following options specify configurations of the SPI word for the operation.
#define	SPI_TRANSFER_MSB   (0U)
	Words are most significant bit first, used for spi_operation_t.
#define	SPI_TRANSFER_LSB   BIT(4)
	Words are least significant bit first, used for spi_operation_t.
#define	SPI_WORD_SIZE_GET(operation)
	Get SPI word size in bits from a spi_operation_t.
#define	SPI_WORD_SET(word_size)
	Get a bitmask to set the word size in a spi_operation_t.
SPI Transfer control flags
#define	SPI_HOLD_ON_CS   BIT(12)
	Keep chip select active after transaction.
#define	SPI_LOCK_ON   BIT(13)
	Retain ownership of the spi device.
#define	SPI_CS_ACTIVE_HIGH   BIT(14)
	Chip select active state configuration.
SPI MISO lines
Some controllers support dual, quad or octal MISO lines connected to slaves. Default is single, which is the case most of the time. Without CONFIG_SPI_EXTENDED_MODES being enabled, single is the only supported one.
#define	SPI_LINES_SINGLE   (0U << 16)
	Single line.
#define	SPI_LINES_DUAL   (1U << 16)
	Dual lines.
#define	SPI_LINES_QUAD   (2U << 16)
	Quad lines.
#define	SPI_LINES_OCTAL   (3U << 16)
	Octal lines.
#define	SPI_LINES_MASK   (0x3U << 16)
	Mask for MISO lines in spi_operation_t.
SPI GPIO Chip Select control
#define	SPI_CS_GPIOS_DT_SPEC_GET(spi_dev)
	Get a struct gpio_dt_spec for a SPI device's chip select pin.
#define	SPI_CS_GPIOS_DT_SPEC_INST_GET(inst)
	Get a struct gpio_dt_spec for a SPI device's chip select pin.
#define	SPI_CS_CONTROL_INIT(node_id, delay_)
	Initialize and get a pointer to a spi_cs_control from a devicetree node identifier.
#define	SPI_CS_CONTROL_INIT_INST(inst, delay_)
	Get a pointer to a spi_cs_control from a devicetree node.
SPI DT Device Macros
#define	SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
	Like DEVICE_DT_DEFINE() with SPI specifics.

Typedefs
typedef uint16_t	spi_operation_t
	Opaque type to hold the SPI operation flags.
typedef int(*	spi_api_io) (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs)
	Callback API for I/O See spi_transceive() for argument descriptions.
typedef void(*	spi_callback_t) (const struct device *dev, int result, void *data)
	SPI callback for asynchronous transfer requests.
typedef int(*	spi_api_io_async) (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs, spi_callback_t cb, void *userdata)
typedef int(*	spi_api_release) (const struct device *dev, const struct spi_config *config)
	Callback API for unlocking SPI device.

Functions
static bool	spi_cs_is_gpio (const struct spi_config *config)
static bool	spi_cs_is_gpio_dt (const struct spi_dt_spec *spec)
static bool	spi_is_ready_dt (const struct spi_dt_spec *spec)
	Validate that SPI bus (and CS gpio if defined) is ready.
int	spi_release (const struct device *dev, const struct spi_config *config)
	Release the SPI device locked on and/or the CS by the current config.
static int	spi_release_dt (const struct spi_dt_spec *spec)
	Release the SPI device specified in spi_dt_spec.
SPI Synchronous Transfer Functions
These functions will not return until transfer is complete
int	spi_transceive (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs)
	Read/write the specified amount of data from the SPI driver.
static int	spi_transceive_dt (const struct spi_dt_spec *spec, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs)
	Read/write data from an SPI bus specified in spi_dt_spec.
static int	spi_read (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *rx_bufs)
	Read the specified amount of data from the SPI driver.
static int	spi_read_dt (const struct spi_dt_spec *spec, const struct spi_buf_set *rx_bufs)
	Read data from a SPI bus specified in spi_dt_spec.
static int	spi_write (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs)
	Write the specified amount of data from the SPI driver.
static int	spi_write_dt (const struct spi_dt_spec *spec, const struct spi_buf_set *tx_bufs)
	Write data to a SPI bus specified in spi_dt_spec.
SPI Asynchronous Transfer Functions
With this API the transfer function will return after the transfer is started and report completion through a notification mechanism: callback or signal. Note Note that asynchronous API calls can still be blocking if the bus is already busy. The functions will block until the bus is available to start the requested transfer.
static int	spi_transceive_cb (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs, spi_callback_t callback, void *userdata)
	Read/write the specified amount of data from the SPI driver.
static int	spi_transceive_signal (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs, struct k_poll_signal *sig)
	Read/write the specified amount of data from the SPI driver.
static int	spi_read_signal (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *rx_bufs, struct k_poll_signal *sig)
	Read the specified amount of data from the SPI driver.
static int	spi_write_signal (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, struct k_poll_signal *sig)
	Write the specified amount of data from the SPI driver.

SPI RTIO API
Theses functions are for using the SPI driver class through an RTIO-based API
#define	SPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_)
	Define an iodev for a given dt node on the bus.
const struct rtio_iodev_api	spi_iodev_api
static void	spi_iodev_submit (struct rtio_iodev_sqe *iodev_sqe)
	Submit a SPI device with a request.
static bool	spi_is_ready_iodev (const struct rtio_iodev *spi_iodev)
	Validate that SPI bus (and CS gpio if defined) is ready.

Detailed Description

Public API for SPI drivers and applications.