SPI Interface

SPI Interface . More...

Topics
	Spi_dt_dev
	Like SPI_DEVICE_DT_DEFINE(), but uses an instance of a DT_DRV_COMPAT compatible instead of a node identifier.
	Spi_gpio_cs
	Check if SPI CS is controlled using a GPIO.

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, ...)

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 RTIO API
Theses functions are for using the SPI driver class through an RTIO-based API
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.
#define	SPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_)
	Define an iodev for a given dt node on the bus.

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

SPI duplex mode
Some controllers support half duplex transfer, which results in 3-wire usage. By default, full duplex will prevail.
#define	SPI_FULL_DUPLEX   (0U << 11)
#define	SPI_HALF_DUPLEX   (1U << 11)

SPI Frame Format
2 frame formats are exposed: Motorola and TI. The main difference is the behavior of the CS line. In Motorola it stays active the whole transfer. In TI, it's active only one serial clock period prior to actually make the transfer, it is thus inactive during the transfer, which ends when the clocks ends as well. By default, as it is the most commonly used, the Motorola frame format will prevail.
#define	SPI_FRAME_FORMAT_MOTOROLA   (0U << 15)
#define	SPI_FRAME_FORMAT_TI   (1U << 15)

Detailed Description

SPI Interface .

SPI Interface .

Since

1.0

Version

1.0.0

Macro Definition Documentation

SPI_CONFIG_DT

#define SPI_CONFIG_DT	(		node_id,
			operation_,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        {                                                               \
                .frequency = DT_PROP(node_id, spi_max_frequency),       \
                .operation = (operation_) |                             \
                        DT_PROP(node_id, duplex) |                      \
                        DT_PROP(node_id, frame_format) |                        \
                        COND_CODE_1(DT_PROP(node_id, spi_cpol), SPI_MODE_CPOL, (0)) |   \
                        COND_CODE_1(DT_PROP(node_id, spi_cpha), SPI_MODE_CPHA, (0)) |   \
                        COND_CODE_1(DT_PROP(node_id, spi_hold_cs), SPI_HOLD_ON_CS, (0)),        \
                .slave = DT_REG_ADDR(node_id),                          \
                .cs = SPI_CS_CONTROL_INIT(node_id, delay_),             \
        }

Structure initializer for spi_config from devicetree.

This helper macro expands to a static initializer for a struct spi_config by reading the relevant frequency, slave, and cs data from the devicetree.

Parameters

node_id	Devicetree node identifier for the SPI device whose struct spi_config to create an initializer for
operation_	the desired operation field in the struct spi_config
delay_	the desired delay field in the struct spi_config's spi_cs_control, if there is one

SPI_CONFIG_DT_INST

#define SPI_CONFIG_DT_INST	(		inst,
			operation_,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)

Structure initializer for spi_config from devicetree instance.

This is equivalent to SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_).

Parameters

inst	Devicetree instance number
operation_	the desired operation field in the struct spi_config
delay_	the desired delay field in the struct spi_config's spi_cs_control, if there is one

SPI_CS_ACTIVE_HIGH

#define SPI_CS_ACTIVE_HIGH   BIT(14)

#include <zephyr/drivers/spi.h>

Chip select active state configuration.

If this flag is set, the CS will be active high. If this flag is unset, the CS will be active low.

Default is active low (unset) as that is most common for spi peripherals.

Not all controllers are able to handle this natively, in which case a gpio can still be used to control the CS through software with a spi_cs_control

SPI_CS_CONTROL_INIT

#define SPI_CS_CONTROL_INIT	(		node_id,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        {                                                         \
                .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id),        \
                .delay = (delay_),                                \
        }

Initialize and get a pointer to a spi_cs_control from a devicetree node identifier.

This helper is useful for initializing a device on a SPI bus. It initializes a struct spi_cs_control and returns a pointer to it. Here, node_id is a node identifier for a SPI device, not a SPI controller.

Example devicetree fragment:

spi@abcd0001 {
        cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
        spidev: spi-device@0 { ... };
};

Example usage:

struct spi_cs_control ctrl =
        SPI_CS_CONTROL_INIT(DT_NODELABEL(spidev), 2);

This example is equivalent to:

struct spi_cs_control ctrl = {
        .gpio = SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(spidev)),
        .delay = 2,
};

Parameters

node_id	Devicetree node identifier for a device on a SPI bus
delay_	The delay field to set in the spi_cs_control

Returns

a pointer to the spi_cs_control structure

SPI_CS_CONTROL_INIT_INST

#define SPI_CS_CONTROL_INIT_INST	(		inst,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)

Get a pointer to a spi_cs_control from a devicetree node.

This is equivalent to SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay).

Therefore, DT_DRV_COMPAT must already be defined before using this macro.

Parameters

inst	Devicetree node instance number
delay_	The delay field to set in the spi_cs_control

Returns

a pointer to the spi_cs_control structure

SPI_CS_GPIOS_DT_SPEC_GET

#define SPI_CS_GPIOS_DT_SPEC_GET

(

spi_dev

)

#include <zephyr/drivers/spi.h>

Value:

        GPIO_DT_SPEC_GET_BY_IDX_OR(DT_BUS(spi_dev), cs_gpios,   \
                                   DT_REG_ADDR_RAW(spi_dev), {})

Get a struct gpio_dt_spec for a SPI device's chip select pin.

Example devicetree fragment:

gpio1: gpio@abcd0001 { ... };
 
gpio2: gpio@abcd0002 { ... };
 
spi@abcd0003 {
        compatible = "vnd,spi";
        cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
                   <&gpio2 20 GPIO_ACTIVE_LOW>;
 
        a: spi-dev-a@0 {
                reg = <0>;
        };
 
        b: spi-dev-b@1 {
                reg = <1>;
        };
};

Example usage:

SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(a)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(b)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }

Parameters

spi_dev

a SPI device node identifier

Returns

gpio_dt_spec struct corresponding with spi_dev's chip select

SPI_CS_GPIOS_DT_SPEC_INST_GET

#define SPI_CS_GPIOS_DT_SPEC_INST_GET

(

inst

)

#include <zephyr/drivers/spi.h>

Value:

        SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))

Get a struct gpio_dt_spec for a SPI device's chip select pin.

This is equivalent to SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst)).

Parameters

inst	Devicetree instance number

Returns

gpio_dt_spec struct corresponding with spi_dev's chip select

SPI_DEVICE_DT_DEFINE

#define SPI_DEVICE_DT_DEFINE	(		node_id,
			init_fn,
			pm,
			data,
			config,
			level,
			prio,
			api,
			... )

#include <zephyr/drivers/spi.h>

Value:

        Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));                     \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),                   \
                        DEVICE_DT_NAME(node_id), init_fn, NULL,                 \
                        Z_DEVICE_DT_FLAGS(node_id), pm, data, config,           \
                        level, prio, api,                                       \
                        &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)),      \
                        __VA_ARGS__)

Like DEVICE_DT_DEFINE() with SPI specifics.

Defines a device which implements the SPI API. May generate a custom device_state container struct and init_fn wrapper when needed depending on SPI CONFIG_SPI_STATS.

Parameters

node_id	The devicetree node identifier.
init_fn	Name of the init function of the driver.
pm	PM device resources reference (NULL if device does not use PM).
data	Pointer to the device's private data.
config	The address to the structure containing the configuration information for this instance of the driver.
level	The initialization level. See SYS_INIT() for details.
prio	Priority within the selected initialization level. See SYS_INIT() for details.
api	Provides an initial pointer to the API function struct used by the driver. Can be NULL.

SPI_DEVICE_DT_INST_DEFINE

#define SPI_DEVICE_DT_INST_DEFINE	(		inst,
			... )

#include <zephyr/drivers/spi.h>

Value:

        SPI_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

SPI_DT_IODEV_DEFINE

#define SPI_DT_IODEV_DEFINE	(		name,
			node_id,
			operation_,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        const struct spi_dt_spec _spi_dt_spec_##name =                          \
                SPI_DT_SPEC_GET(node_id, operation_, delay_);                   \
        RTIO_IODEV_DEFINE(name, &spi_iodev_api, (void *)&_spi_dt_spec_##name)

Define an iodev for a given dt node on the bus.

These do not need to be shared globally but doing so will save a small amount of memory.

Parameters

name	Symbolic name to use for defining the iodev
node_id	Devicetree node identifier
operation_	SPI operational mode
delay_	Chip select delay in microseconds

SPI_DT_SPEC_GET

#define SPI_DT_SPEC_GET	(		node_id,
			operation_,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        {                                                            \
                .bus = DEVICE_DT_GET(DT_BUS(node_id)),               \
                .config = SPI_CONFIG_DT(node_id, operation_, delay_) \
        }

Structure initializer for spi_dt_spec from devicetree.

This helper macro expands to a static initializer for a struct spi_dt_spec by reading the relevant bus, frequency, slave, and cs data from the devicetree.

Important: multiple fields are automatically constructed by this macro which must be checked before use. spi_is_ready_dt performs the required device_is_ready checks.

Parameters

node_id	Devicetree node identifier for the SPI device whose struct spi_dt_spec to create an initializer for
operation_	the desired operation field in the struct spi_config
delay_	the desired delay field in the struct spi_config's spi_cs_control, if there is one

SPI_DT_SPEC_INST_GET

#define SPI_DT_SPEC_INST_GET	(		inst,
			operation_,
			delay_ )

#include <zephyr/drivers/spi.h>

Value:

        SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)

Structure initializer for spi_dt_spec from devicetree instance.

This is equivalent to SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_).

Parameters

inst	Devicetree instance number
operation_	the desired operation field in the struct spi_config
delay_	the desired delay field in the struct spi_config's spi_cs_control, if there is one

SPI_FRAME_FORMAT_MOTOROLA

#define SPI_FRAME_FORMAT_MOTOROLA   (0U << 15)

#include <zephyr/dt-bindings/spi/spi.h>

SPI_FRAME_FORMAT_TI

#define SPI_FRAME_FORMAT_TI   (1U << 15)

#include <zephyr/dt-bindings/spi/spi.h>

SPI_FULL_DUPLEX

#define SPI_FULL_DUPLEX   (0U << 11)

#include <zephyr/dt-bindings/spi/spi.h>

SPI_HALF_DUPLEX

#define SPI_HALF_DUPLEX   (1U << 11)

#include <zephyr/dt-bindings/spi/spi.h>

SPI_HOLD_ON_CS

#define SPI_HOLD_ON_CS   BIT(12)

#include <zephyr/drivers/spi.h>

Keep chip select active after transaction.

After one of the spi transceive calls described in this API, if this flag is set in the spi config operation, then attempt to keep the CS active after the call, if supported and possible.

SPI_LINES_DUAL

#define SPI_LINES_DUAL   (1U << 16)

#include <zephyr/drivers/spi.h>

Dual lines.

SPI_LINES_MASK

#define SPI_LINES_MASK   (0x3U << 16)

#include <zephyr/drivers/spi.h>

Mask for MISO lines in spi_operation_t.

SPI_LINES_OCTAL

#define SPI_LINES_OCTAL   (3U << 16)

#include <zephyr/drivers/spi.h>

Octal lines.

SPI_LINES_QUAD

#define SPI_LINES_QUAD   (2U << 16)

#include <zephyr/drivers/spi.h>

Quad lines.

SPI_LINES_SINGLE

#define SPI_LINES_SINGLE   (0U << 16)

#include <zephyr/drivers/spi.h>

Single line.

SPI_LOCK_ON

#define SPI_LOCK_ON   BIT(13)

#include <zephyr/drivers/spi.h>

Retain ownership of the spi device.

This is a software control parameter that will prevent the spi device from being accessed by other API callers after the transaction, and therefore should be used with caution.

The identifying piece of information for who "locks" the device is the spi_config pointer given to the transaction API, so this same config should be re-used to do another transaction or release the lock.

See spi_release for how to release the lock.

SPI_MODE_CPHA

#define SPI_MODE_CPHA   BIT(2)

#include <zephyr/drivers/spi.h>

Clock Phase (Clock data capture edge)

Used in spi_operation_t definition. If set, data is captured on transition from active to idle CLK state. If unset, data is captured on transition from idle to active state. Unset is the default.

SPI_MODE_CPOL

#define SPI_MODE_CPOL   BIT(1)

#include <zephyr/drivers/spi.h>

Clock Polarity (Clock Idle State)

Used in spi_operation_t definition. If set, clock idle state will be 1 and active state will be 0. If unset, clock idle state will be 0 and active state will be 1. Unset is the default.

SPI_MODE_GET

#define SPI_MODE_GET

(

_mode_

)

#include <zephyr/drivers/spi.h>

Value:

        ((_mode_) & SPI_MODE_MASK)

Get SPI clock polarity and phase mode bitmask from a spi_operation_t.

SPI_MODE_LOOP

#define SPI_MODE_LOOP   BIT(3)

#include <zephyr/drivers/spi.h>

Controller loopback mode.

For testing purposes, enable hardware loopback, which means that transmit data is fed back to the receiver of the same controller.

Not all controllers support this feature.

SPI_MOSI_OVERRUN_DT

#define SPI_MOSI_OVERRUN_DT

(

node_id

)

#include <zephyr/drivers/spi.h>

Value:

        DT_PROP_OR(node_id, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)

The value sent on MOSI when all TX bytes are sent, but RX continues.

For drivers where the MOSI line state when receiving is important, this value can be queried at compile-time to determine whether allocating a constant array is necessary.

Parameters

node_id

Devicetree node identifier for the SPI device to query

Return values

SPI_MOSI_OVERRUN_UNKNOWN	if controller does not export the value
byte	default MOSI value otherwise

SPI_MOSI_OVERRUN_DT_INST

#define SPI_MOSI_OVERRUN_DT_INST

(

inst

)

#include <zephyr/drivers/spi.h>

Value:

        DT_INST_PROP_OR(inst, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)

The value sent on MOSI when all TX bytes are sent, but RX continues.

This is equivalent to SPI_MOSI_OVERRUN_DT(DT_DRV_INST(inst)).

Parameters

inst	Devicetree instance number

Return values

SPI_MOSI_OVERRUN_UNKNOWN	if controller does not export the value
byte	default MOSI value otherwise

SPI_MOSI_OVERRUN_UNKNOWN

#define SPI_MOSI_OVERRUN_UNKNOWN   0x100

#include <zephyr/drivers/spi.h>

Value that will never compare true with any valid overrun character.

SPI_OP_MODE_GET

#define SPI_OP_MODE_GET

(

_operation_

)

#include <zephyr/drivers/spi.h>

Value:

((_operation_) & SPI_OP_MODE_MASK)

Get SPI Operational mode bitmask from a spi_operation_t.

SPI_OP_MODE_MASTER

#define SPI_OP_MODE_MASTER   0U

#include <zephyr/drivers/spi.h>

Master (controller) mode.

In this case the device used with the API will function as a controller, meaning it will control the CLK line on the SPI bus and the chip select, and therefore have full control over the timing of the transaction.

SPI_OP_MODE_SLAVE

#define SPI_OP_MODE_SLAVE   BIT(0)

#include <zephyr/drivers/spi.h>

Slave (peripheral) mode.

With this mode, the device will function as a peripheral, meaning it will need to wait for it's select line to be asserted, and will be need to be subject to pacing by a controller's clock in order to send and receive data during a transaction. Slave mode.

SPI_STATS_RX_BYTES_INC

#define SPI_STATS_RX_BYTES_INC

(

dev_

)

#include <zephyr/drivers/spi.h>

SPI_STATS_TRANSFER_ERROR_INC

#define SPI_STATS_TRANSFER_ERROR_INC

(

dev_

)

#include <zephyr/drivers/spi.h>

SPI_STATS_TX_BYTES_INC

#define SPI_STATS_TX_BYTES_INC

(

dev_

)

#include <zephyr/drivers/spi.h>

spi_transceive_stats

#define spi_transceive_stats	(		dev,
			error,
			tx_bufs,
			rx_bufs )

#include <zephyr/drivers/spi.h>

SPI_TRANSFER_LSB

#define SPI_TRANSFER_LSB   BIT(4)

#include <zephyr/drivers/spi.h>

Words are least significant bit first, used for spi_operation_t.

SPI_TRANSFER_MSB

#define SPI_TRANSFER_MSB   (0U)

#include <zephyr/drivers/spi.h>

Words are most significant bit first, used for spi_operation_t.

SPI_WORD_SET

#define SPI_WORD_SET

(

word_size

)

#include <zephyr/drivers/spi.h>

Value:

        ((word_size) << SPI_WORD_SIZE_SHIFT)

Get a bitmask to set the word size in a spi_operation_t.

Parameters

word_size

The size of a SPI data frame in bits.

Return values

A	bitmask to apply to a spi_operation_t

SPI_WORD_SIZE_GET

#define SPI_WORD_SIZE_GET

(

operation

)

#include <zephyr/drivers/spi.h>

Value:

        (((operation) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)

Get SPI word size in bits from a spi_operation_t.

Parameters

operation

A spi_operation_t from which to get the configured word size.

Return values

The	size (in bits) of a spi word for the operation.

Typedef Documentation

spi_api_io

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)

#include <zephyr/drivers/spi.h>

Callback API for I/O See spi_transceive() for argument descriptions.

Callback API for asynchronous I/O See spi_transceive_signal() for argument descriptions.

spi_api_io_async

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)

#include <zephyr/drivers/spi.h>

spi_api_release

typedef int(* spi_api_release) (const struct device *dev, const struct spi_config *config)

#include <zephyr/drivers/spi.h>

Callback API for unlocking SPI device.

See spi_release() for argument descriptions

spi_callback_t

typedef void(* spi_callback_t) (const struct device *dev, int result, void *data)

#include <zephyr/drivers/spi.h>

SPI callback for asynchronous transfer requests.

Parameters

dev	SPI device which is notifying of transfer completion or error
result	Result code of the transfer request. 0 is success, -errno for failure.
data	Transfer requester supplied data which is passed along to the callback.

spi_operation_t

typedef uint16_t spi_operation_t

#include <zephyr/drivers/spi.h>

Opaque type to hold the SPI operation flags.

Function Documentation

spi_cs_is_gpio()

static bool spi_cs_is_gpio ( const struct spi_config * config )

inlinestatic

#include <zephyr/drivers/spi.h>

spi_cs_is_gpio_dt()

static bool spi_cs_is_gpio_dt ( const struct spi_dt_spec * spec )

inlinestatic

#include <zephyr/drivers/spi.h>

spi_iodev_submit()

static void spi_iodev_submit ( struct rtio_iodev_sqe * iodev_sqe )

inlinestatic

#include <zephyr/drivers/spi.h>

Submit a SPI device with a request.

Parameters

iodev_sqe

Prepared submissions queue entry connected to an iodev defined by SPI_IODEV_DEFINE. Must live as long as the request is in flight.

spi_is_ready_dt()

static bool spi_is_ready_dt ( const struct spi_dt_spec * spec )

inlinestatic

#include <zephyr/drivers/spi.h>

Validate that SPI bus (and CS gpio if defined) is ready.

Parameters

spec	SPI specification from devicetree

Return values

true	if the SPI bus is ready for use.
false	if the SPI bus (or the CS gpio defined) is not ready for use.

spi_is_ready_iodev()

static bool spi_is_ready_iodev ( const struct rtio_iodev * spi_iodev )

inlinestatic

#include <zephyr/drivers/spi.h>

Validate that SPI bus (and CS gpio if defined) is ready.

Parameters

spi_iodev

SPI iodev defined with SPI_DT_IODEV_DEFINE

Return values

true	if the SPI bus is ready for use.
false	if the SPI bus (or the CS gpio defined) is not ready for use.

spi_read()

static int spi_read ( const struct device * dev, const struct spi_config * config, const struct spi_buf_set * rx_bufs )

inlinestatic

#include <zephyr/drivers/spi.h>

Read the specified amount of data from the SPI driver.

Note

This function is synchronous.

This function is a helper function calling spi_transceive.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
rx_bufs	Buffer array where data to be read will be written to.

Return values

frames	Positive number of frames received in slave mode.
0	If successful.
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

spi_read_dt()

static int spi_read_dt ( const struct spi_dt_spec * spec, const struct spi_buf_set * rx_bufs )

inlinestatic

#include <zephyr/drivers/spi.h>

Read data from a SPI bus specified in spi_dt_spec.

This is equivalent to:

spi_read(spec->bus, &spec->config, rx_bufs);

Parameters

spec	SPI specification from devicetree
rx_bufs	Buffer array where data to be read will be written to.

Returns

a value from spi_read().

spi_read_signal()

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 )

inlinestatic

#include <zephyr/drivers/spi.h>

Read the specified amount of data from the SPI driver.

Note

This function is asynchronous.

This function is a helper function calling spi_transceive_signal.

This function is available only if CONFIG_SPI_ASYNC and CONFIG_POLL are selected.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
rx_bufs	Buffer array where data to be read will be written to.
sig	A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

Return values

frames	Positive number of frames received in slave mode.
0	If successful
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

spi_release()

int spi_release	(	const struct device *	dev,
		const struct spi_config *	config )

#include <zephyr/drivers/spi.h>

Release the SPI device locked on and/or the CS by the current config.

Note: This synchronous function is used to release either the lock on the SPI device and/or the CS line that was kept if, and if only, given config parameter was the last one to be used (in any of the above functions) and if it has the SPI_LOCK_ON bit set and/or the SPI_HOLD_ON_CS bit set into its operation bits field. This can be used if the caller needs to keep its hand on the SPI device for consecutive transactions and/or if it needs the device to stay selected. Usually both bits will be used along each other, so the the device is locked and stays on until another operation is necessary or until it gets released with the present function.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance.

Return values

0	If successful.
-errno	Negative errno code on failure.

spi_release_dt()

static int spi_release_dt ( const struct spi_dt_spec * spec )

inlinestatic

#include <zephyr/drivers/spi.h>

Release the SPI device specified in spi_dt_spec.

This is equivalent to:

spi_release(spec->bus, &spec->config);

Parameters

spec	SPI specification from devicetree

Returns

a value from spi_release().

spi_transceive()

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 )

#include <zephyr/drivers/spi.h>

Read/write the specified amount of data from the SPI driver.

Note

This function is synchronous.

In master mode, the chip select line will remain asserted (active) for the entire duration of the transfer of all buffers in the provided buf sets. Only after all buffers have been transferred will CS be deasserted.

In peripheral mode, data transfer happens when the master asserts CS and provides the clock. The function will wait for the master to complete the transfer before returning. The CS is controlled by master and therefore may not be continuously asserted for the whole transfer.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufs	Buffer array where data to be sent originates from, or NULL if none.
rx_bufs	Buffer array where data to be read will be written to, or NULL if none.

Return values

frames	Positive number of frames received in slave mode.
0	If successful in master mode.
-ENOTSUP	means some part of the spi config is not supported either by the device hardware or the driver software.
-EINVAL	means that some parameter of the spi_config is invalid for the device.
-errno	Negative errno code on failure.

spi_transceive_cb()

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 )

inlinestatic

#include <zephyr/drivers/spi.h>

Read/write the specified amount of data from the SPI driver.

Note

This function is asynchronous.

This function is available only if CONFIG_SPI_ASYNC is selected.

The chip select behavior as described by spi_transceive and the function of controller/peripheral modes is the same.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufs	Buffer array where data to be sent originates from, or NULL if none.
rx_bufs	Buffer array where data to be read will be written to, or NULL if none.
callback	Function pointer to completion callback. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).
userdata	Userdata passed to callback

Return values

frames	Positive number of frames received in slave mode.
0	If successful in master mode.
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

spi_transceive_dt()

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 )

inlinestatic

#include <zephyr/drivers/spi.h>

Read/write data from an SPI bus specified in spi_dt_spec.

This is equivalent to:

spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);

Parameters

spec	SPI specification from devicetree
tx_bufs	Buffer array where data to be sent originates from, or NULL if none.
rx_bufs	Buffer array where data to be read will be written to, or NULL if none.

Returns

a value from spi_transceive().

spi_transceive_signal()

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 )

inlinestatic

#include <zephyr/drivers/spi.h>

Read/write the specified amount of data from the SPI driver.

Note

This function is asynchronous.

The chip select behavior as described by spi_transceive and the function of controller/peripheral modes is the same.

This function is available only if CONFIG_SPI_ASYNC and CONFIG_POLL are selected.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufs	Buffer array where data to be sent originates from, or NULL if none.
rx_bufs	Buffer array where data to be read will be written to, or NULL if none.
sig	A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

Return values

frames	Positive number of frames received in slave mode.
0	If successful in master mode.
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

spi_write()

static int spi_write ( const struct device * dev, const struct spi_config * config, const struct spi_buf_set * tx_bufs )

inlinestatic

#include <zephyr/drivers/spi.h>

Write the specified amount of data from the SPI driver.

Note

This function is synchronous.

This function is a helper function calling spi_transceive.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufs	Buffer array where data to be sent originates from.

Return values

0	If successful.
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

spi_write_dt()

static int spi_write_dt ( const struct spi_dt_spec * spec, const struct spi_buf_set * tx_bufs )

inlinestatic

#include <zephyr/drivers/spi.h>

Write data to a SPI bus specified in spi_dt_spec.

This is equivalent to:

spi_write(spec->bus, &spec->config, tx_bufs);

Parameters

spec	SPI specification from devicetree
tx_bufs	Buffer array where data to be sent originates from.

Returns

a value from spi_write().

spi_write_signal()

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 )

inlinestatic

#include <zephyr/drivers/spi.h>

Write the specified amount of data from the SPI driver.

Note

This function is asynchronous.

This function is a helper function calling spi_transceive_signal.

This function is available only if CONFIG_SPI_ASYNC and CONFIG_POLL are selected.

Parameters

dev	Pointer to the device structure for the driver instance
config	Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufs	Buffer array where data to be sent originates from.
sig	A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

Return values

0	If successful.
-ENOTSUP	or -EINVAL means some part of the spi config is not possible for device
-errno	Negative errno code on failure.

Variable Documentation

spi_iodev_api

const struct rtio_iodev_api spi_iodev_api

extern

#include <zephyr/drivers/spi.h>