Zephyr API Documentation: zephyr/drivers/spi.h File Reference (2025)

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

#defineSPI_CS_GPIOS_DT_SPEC_GET(spi_dev)
Get a struct gpio_dt_spec for a SPI device's chip select pin.
#defineSPI_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.
#defineSPI_CS_CONTROL_INIT(node_id, delay_)
Initialize and get a pointer to a spi_cs_control from a devicetree node identifier.
#defineSPI_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.
#defineSPI_CONFIG_DT(node_id, operation_, delay_)
Structure initializer for spi_config from devicetree.
#defineSPI_CONFIG_DT_INST(inst, operation_, delay_) SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)
Structure initializer for spi_config from devicetree instance.
#defineSPI_DT_SPEC_GET(node_id, operation_, delay_)
Structure initializer for spi_dt_spec from devicetree.
#defineSPI_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.
#defineSPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
#defineSPI_STATS_RX_BYTES_INC(dev_)
#defineSPI_STATS_TX_BYTES_INC(dev_)
#defineSPI_STATS_TRANSFER_ERROR_INC(dev_)
#definespi_transceive_stats(dev, error, tx_bufs, rx_bufs)
#defineSPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_)
Define an iodev for a given dt node on the bus.

SPI operational mode

#defineSPI_OP_MODE_MASTER0U
Master mode.
#defineSPI_OP_MODE_SLAVEBIT(0)
Slave mode.
#defineSPI_OP_MODE_GET(_operation_)((_operation_) & SPI_OP_MODE_MASK)
Get SPI operational mode.

SPI Polarity & Phase Modes

#defineSPI_MODE_CPOLBIT(1)
Clock Polarity: if set, clock idle state will be 1 and active state will be 0.
#defineSPI_MODE_CPHABIT(2)
Clock Phase: this dictates when is the data captured, and depends clock's polarity.
#defineSPI_MODE_LOOPBIT(3)
Whatever data is transmitted is looped-back to the receiving buffer of the controller.
#defineSPI_MODE_GET(_mode_) ((_mode_) & SPI_MODE_MASK)
Get SPI polarity and phase mode bits.

SPI Transfer modes (host controller dependent)

#defineSPI_TRANSFER_MSB(0U)
Most significant bit first.
#defineSPI_TRANSFER_LSBBIT(4)
Least significant bit first.

SPI word size

#defineSPI_WORD_SIZE_GET(_operation_) (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)
Get SPI word size.
#defineSPI_WORD_SET(_word_size_) ((_word_size_) << SPI_WORD_SIZE_SHIFT)
Set SPI word size.

Specific SPI devices control bits

#defineSPI_HOLD_ON_CSBIT(12)
Requests - if possible - to keep CS asserted after the transaction.
#defineSPI_LOCK_ONBIT(13)
Keep the device locked after the transaction for the current config.
#defineSPI_CS_ACTIVE_HIGHBIT(14)
Active high logic on CS.

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.

#defineSPI_LINES_SINGLE(0U << 16)
Single line.
#defineSPI_LINES_DUAL(1U << 16)
Dual lines.
#defineSPI_LINES_QUAD(2U << 16)
Quad lines.
#defineSPI_LINES_OCTAL(3U << 16)
Octal lines.
#defineSPI_LINES_MASK(0x3U << 16)
Mask for MISO lines in spi_operation_t.

Typedefs

typedef uint16_tspi_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 boolspi_cs_is_gpio (const struct spi_config *config)
Check if SPI CS is controlled using a GPIO.
static boolspi_cs_is_gpio_dt (const struct spi_dt_spec *spec)
Check if SPI CS in spi_dt_spec is controlled using a GPIO.
static boolspi_is_ready_dt (const struct spi_dt_spec *spec)
Validate that SPI bus (and CS gpio if defined) is ready.
intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 intspi_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 voidspi_iodev_submit (struct rtio_iodev_sqe *iodev_sqe)
Submit a SPI device with a request.
static boolspi_is_ready_iodev (const struct rtio_iodev *spi_iodev)
Validate that SPI bus (and CS gpio if defined) is ready.
static intspi_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.
intspi_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 intspi_release_dt (const struct spi_dt_spec *spec)
Release the SPI device specified in spi_dt_spec.

Variables

const struct rtio_iodev_apispi_iodev_api

Detailed Description

Public API for SPI drivers and applications.

Zephyr API Documentation: zephyr/drivers/spi.h File Reference (2025)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: The Hon. Margery Christiansen

Last Updated:

Views: 6242

Rating: 5 / 5 (50 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: The Hon. Margery Christiansen

Birthday: 2000-07-07

Address: 5050 Breitenberg Knoll, New Robert, MI 45409

Phone: +2556892639372

Job: Investor Mining Engineer

Hobby: Sketching, Cosplaying, Glassblowing, Genealogy, Crocheting, Archery, Skateboarding

Introduction: My name is The Hon. Margery Christiansen, I am a bright, adorable, precious, inexpensive, gorgeous, comfortable, happy person who loves writing and wants to share my knowledge and understanding with you.