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 <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 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_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)    SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(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_)    SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)
	Get a pointer to a spi_cs_control from a devicetree node.
#define	SPI_CONFIG_DT(node_id, operation_, delay_)
	Structure initializer for spi_config from devicetree.
#define	SPI_CONFIG_DT_INST(inst, operation_, delay_)    SPI_CONFIG_DT(DT_DRV_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_)    SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)
	Structure initializer for spi_dt_spec from devicetree instance.
#define	SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
#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_DT_IODEV_DEFINE(name, node_id, operation_, delay_)
	Define an iodev for a given dt node on the bus.
SPI operational mode
#define	SPI_OP_MODE_MASTER   0U
#define	SPI_OP_MODE_SLAVE   BIT(0)
#define	SPI_OP_MODE_MASK   0x1U
#define	SPI_OP_MODE_GET(_operation_)   ((_operation_) & SPI_OP_MODE_MASK)
SPI Polarity & Phase Modes
#define	SPI_MODE_CPOL   BIT(1)
	Clock Polarity: if set, clock idle state will be 1 and active state will be 0.
#define	SPI_MODE_CPHA   BIT(2)
	Clock Phase: this dictates when is the data captured, and depends clock's polarity.
#define	SPI_MODE_LOOP   BIT(3)
	Whatever data is transmitted is looped-back to the receiving buffer of the controller.
#define	SPI_MODE_MASK   (0xEU)
#define	SPI_MODE_GET(_mode_)    ((_mode_) & SPI_MODE_MASK)
SPI Transfer modes (host controller dependent)
#define	SPI_TRANSFER_MSB   (0U)
#define	SPI_TRANSFER_LSB   BIT(4)
SPI word size
#define	SPI_WORD_SIZE_SHIFT   (5U)
#define	SPI_WORD_SIZE_MASK   (0x3FU << SPI_WORD_SIZE_SHIFT)
#define	SPI_WORD_SIZE_GET(_operation_)    (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)
#define	SPI_WORD_SET(_word_size_)    ((_word_size_) << SPI_WORD_SIZE_SHIFT)
Specific SPI devices control bits
#define	SPI_HOLD_ON_CS   BIT(12)
#define	SPI_LOCK_ON   BIT(13)
#define	SPI_CS_ACTIVE_HIGH   BIT(14)
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)
#define	SPI_LINES_DUAL   (1U << 16)
#define	SPI_LINES_QUAD   (2U << 16)
#define	SPI_LINES_OCTAL   (3U << 16)
#define	SPI_LINES_MASK   (0x3U << 16)

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)
	Check if SPI CS is controlled using a GPIO.
static bool	spi_cs_is_gpio_dt (const struct spi_dt_spec *spec)
	Check if SPI CS in spi_dt_spec is controlled using a GPIO.
static bool	spi_is_ready (const struct spi_dt_spec *spec)
	Validate that SPI bus is ready.
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_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.
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_transceive_async (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)
	Alias for spi_transceive_signal for backwards compatibility.
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_read_async (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *rx_bufs, struct k_poll_signal *sig)
	Alias for spi_read_signal for backwards compatibility.
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.
static int	spi_write_async (const struct device *dev, const struct spi_config *config, const struct spi_buf_set *tx_bufs, struct k_poll_signal *sig)
	Alias for spi_write_signal for backwards compatibility.
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.
static int	spi_rtio_copy (struct rtio *r, struct rtio_iodev *iodev, const struct spi_buf_set *tx_bufs, const struct spi_buf_set *rx_bufs, struct rtio_sqe **last_sqe)
	Copy the tx_bufs and rx_bufs into a set of RTIO requests.
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.

Variables
const struct rtio_iodev_api	spi_iodev_api

Detailed Description

Public API for SPI drivers and applications.