Zephyr API Documentation  3.7.0-rc1
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
SPI Interface

SPI Interface. More...

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.
 

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

SPI operational mode

#define SPI_OP_MODE_MASTER   0U
 Master mode.
 
#define SPI_OP_MODE_SLAVE   BIT(0)
 Slave mode.
 
#define SPI_OP_MODE_GET(_operation_)   ((_operation_) & SPI_OP_MODE_MASK)
 Get SPI operational mode.
 

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_GET(_mode_)    ((_mode_) & SPI_MODE_MASK)
 Get SPI polarity and phase mode bits.
 

SPI Transfer modes (host controller dependent)

#define SPI_TRANSFER_MSB   (0U)
 Most significant bit first.
 
#define SPI_TRANSFER_LSB   BIT(4)
 Least significant bit first.
 

SPI word size

#define SPI_WORD_SIZE_GET(_operation_)    (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)
 Get SPI word size.
 
#define SPI_WORD_SET(_word_size_)    ((_word_size_) << SPI_WORD_SIZE_SHIFT)
 Set SPI word size.
 

Specific SPI devices control bits

#define SPI_HOLD_ON_CS   BIT(12)
 Requests - if possible - to keep CS asserted after the transaction.
 
#define SPI_LOCK_ON   BIT(13)
 Keep the device locked after the transaction for the current config.
 
#define SPI_CS_ACTIVE_HIGH   BIT(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.

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

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_), \
}
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition: devicetree.h:663
#define DT_REG_ADDR(node_id)
Get a node's (only) register block address.
Definition: devicetree.h:2276
#define SPI_MODE_CPHA
Clock Phase: this dictates when is the data captured, and depends clock's polarity.
Definition: spi.h:70
#define SPI_CS_CONTROL_INIT(node_id, delay_)
Initialize and get a pointer to a spi_cs_control from a devicetree node identifier.
Definition: spi.h:266
#define SPI_MODE_CPOL
Clock Polarity: if set, clock idle state will be 1 and active state will be 0.
Definition: spi.h:61
#define SPI_HOLD_ON_CS
Requests - if possible - to keep CS asserted after the transaction.
Definition: spi.h:116

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_idDevicetree 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_ 
)     SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)

#include <zephyr/drivers/spi.h>

Structure initializer for spi_config from devicetree instance.

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

Parameters
instDevicetree 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>

Active high logic on CS.

Usually, and by default, CS logic is active low. However, some devices may require the reverse logic: active high. This bit will request the controller to use that logic. Note that not all controllers are able to handle that natively. In this case deferring the CS control to a gpio line through struct spi_cs_control would be the solution.

◆ 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_), \
}
#define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev)
Get a struct gpio_dt_spec for a SPI device's chip select pin.
Definition: spi.h:212

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 =
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:200
SPI Chip Select control structure.
Definition: spi.h:159

This example is equivalent to:

struct spi_cs_control ctrl = {
.delay = 2,
};
struct gpio_dt_spec gpio
GPIO devicetree specification of CS GPIO.
Definition: spi.h:167
Parameters
node_idDevicetree 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_ 
)     SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)

#include <zephyr/drivers/spi.h>

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
instDevicetree 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(spi_dev), {})
#define DT_BUS(node_id)
Node's bus controller.
Definition: devicetree.h:3556
#define GPIO_DT_SPEC_GET_BY_IDX_OR(node_id, prop, idx, default_value)
Like GPIO_DT_SPEC_GET_BY_IDX(), with a fallback to a default value.
Definition: gpio.h:355

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:

// { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
// { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }
Parameters
spi_deva 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)     SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))

#include <zephyr/drivers/spi.h>

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
instDevicetree 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, pm, data, config, \
level, prio, api, \
&Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)), \
__VA_ARGS__)
#define DEVICE_DT_NAME(node_id)
Return a string name for a devicetree node.
Definition: device.h:152

◆ 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)
const struct rtio_iodev_api spi_iodev_api
Complete SPI DT information.
Definition: spi.h:377

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
nameSymbolic name to use for defining the iodev
node_idDevicetree 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_) \
}
#define DEVICE_DT_GET(node_id)
Get a device reference from a devicetree node identifier.
Definition: device.h:246
#define SPI_CONFIG_DT(node_id, operation_, delay_)
Structure initializer for spi_config from devicetree.
Definition: spi.h:347

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_idDevicetree 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_ 
)     SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)

#include <zephyr/drivers/spi.h>

Structure initializer for spi_dt_spec from devicetree instance.

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

Parameters
instDevicetree 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)

◆ SPI_FRAME_FORMAT_TI

#define SPI_FRAME_FORMAT_TI   (1U << 15)

◆ SPI_FULL_DUPLEX

#define SPI_FULL_DUPLEX   (0U << 11)

◆ SPI_HALF_DUPLEX

#define SPI_HALF_DUPLEX   (1U << 11)

◆ SPI_HOLD_ON_CS

#define SPI_HOLD_ON_CS   BIT(12)

#include <zephyr/drivers/spi.h>

Requests - if possible - to keep CS asserted after the transaction.

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

Keep the device locked after the transaction for the current config.

Use this with extreme caution (see spi_release() below) as it will prevent other callers to access the SPI device until spi_release() is properly called.

◆ SPI_MODE_CPHA

#define SPI_MODE_CPHA   BIT(2)

#include <zephyr/drivers/spi.h>

Clock Phase: this dictates when is the data captured, and depends clock's polarity.

When SPI_MODE_CPOL is set and this bit as well, capture will occur on low to high transition and high to low if this bit is not set (default). This is fully reversed if CPOL is not set.

◆ SPI_MODE_CPOL

#define SPI_MODE_CPOL   BIT(1)

#include <zephyr/drivers/spi.h>

Clock Polarity: if set, clock idle state will be 1 and active state will be 0.

If untouched, the inverse will be true which is the default.

◆ SPI_MODE_GET

#define SPI_MODE_GET (   _mode_)     ((_mode_) & SPI_MODE_MASK)

#include <zephyr/drivers/spi.h>

Get SPI polarity and phase mode bits.

◆ SPI_MODE_LOOP

#define SPI_MODE_LOOP   BIT(3)

#include <zephyr/drivers/spi.h>

Whatever data is transmitted is looped-back to the receiving buffer of the controller.

This is fully controller dependent as some may not support this, and can be used for testing purposes only.

◆ SPI_OP_MODE_GET

#define SPI_OP_MODE_GET (   _operation_)    ((_operation_) & SPI_OP_MODE_MASK)

#include <zephyr/drivers/spi.h>

Get SPI operational mode.

◆ SPI_OP_MODE_MASTER

#define SPI_OP_MODE_MASTER   0U

#include <zephyr/drivers/spi.h>

Master mode.

◆ SPI_OP_MODE_SLAVE

#define SPI_OP_MODE_SLAVE   BIT(0)

#include <zephyr/drivers/spi.h>

Slave mode.

◆ SPI_STATS_RX_BYTES_INC

#define SPI_STATS_RX_BYTES_INC (   dev_)

◆ SPI_STATS_TRANSFER_ERROR_INC

#define SPI_STATS_TRANSFER_ERROR_INC (   dev_)

◆ SPI_STATS_TX_BYTES_INC

#define SPI_STATS_TX_BYTES_INC (   dev_)

◆ spi_transceive_stats

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

◆ SPI_TRANSFER_LSB

#define SPI_TRANSFER_LSB   BIT(4)

#include <zephyr/drivers/spi.h>

Least significant bit first.

◆ SPI_TRANSFER_MSB

#define SPI_TRANSFER_MSB   (0U)

#include <zephyr/drivers/spi.h>

Most significant bit first.

◆ SPI_WORD_SET

#define SPI_WORD_SET (   _word_size_)     ((_word_size_) << SPI_WORD_SIZE_SHIFT)

#include <zephyr/drivers/spi.h>

Set SPI word size.

◆ SPI_WORD_SIZE_GET

#define SPI_WORD_SIZE_GET (   _operation_)     (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)

#include <zephyr/drivers/spi.h>

Get SPI word size.

Typedef Documentation

◆ spi_api_io

spi_api_io

#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)

◆ spi_api_release

spi_api_release

#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
devSPI device which is notifying of transfer completion or error
resultResult code of the transfer request. 0 is success, -errno for failure.
dataTransfer requester supplied data which is passed along to the callback.

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

Check if SPI CS is controlled using a GPIO.

Parameters
configSPI configuration.
Returns
true If CS is controlled using a GPIO.
false If CS is controlled by hardware or any other means.

◆ spi_cs_is_gpio_dt()

static bool spi_cs_is_gpio_dt ( const struct spi_dt_spec spec)
inlinestatic

#include <zephyr/drivers/spi.h>

Check if SPI CS in spi_dt_spec is controlled using a GPIO.

Parameters
specSPI specification from devicetree.
Returns
true If CS is controlled using a GPIO.
false If CS is controlled by hardware or any other means.

◆ 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_sqePrepared 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
specSPI specification from devicetree
Return values
trueif the SPI bus is ready for use.
falseif 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_iodevSPI iodev defined with SPI_DT_IODEV_DEFINE
Return values
trueif the SPI bus is ready for use.
falseif 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
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
rx_bufsBuffer array where data to be read will be written to.
Return values
framesPositive number of frames received in slave mode.
0If successful.
-errnoNegative 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
specSPI specification from devicetree
rx_bufsBuffer 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
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
rx_bufsBuffer array where data to be read will be written to.
sigA 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
framesPositive number of frames received in slave mode.
0If successful
-errnoNegative 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
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance.
Return values
0If successful.
-errnoNegative 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
specSPI specification from devicetree
Returns
a value from spi_release().

◆ spi_rtio_copy()

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 
)
inlinestatic

#include <zephyr/drivers/spi.h>

Copy the tx_bufs and rx_bufs into a set of RTIO requests.

Parameters
[in]rrtio context
[in]iodeviodev to transceive with
[in]tx_bufstransmit buffer set
[in]rx_bufsreceive buffer set
[out]last_sqelast sqe submitted, NULL if not enough memory
Return values
Numberof submission queue entries
-ENOMEMout of memory

◆ 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.
Parameters
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufsBuffer array where data to be sent originates from, or NULL if none.
rx_bufsBuffer array where data to be read will be written to, or NULL if none.
Return values
framesPositive number of frames received in slave mode.
0If successful in master mode.
-errnoNegative 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.
Parameters
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufsBuffer array where data to be sent originates from, or NULL if none.
rx_bufsBuffer array where data to be read will be written to, or NULL if none.
callbackFunction pointer to completion callback. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).
userdataUserdata passed to callback
Return values
framesPositive number of frames received in slave mode.
0If successful in master mode.
-errnoNegative 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
specSPI specification from devicetree
tx_bufsBuffer array where data to be sent originates from, or NULL if none.
rx_bufsBuffer 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.
This function is available only if CONFIG_SPI_ASYNC and CONFIG_POLL are selected.
Parameters
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufsBuffer array where data to be sent originates from, or NULL if none.
rx_bufsBuffer array where data to be read will be written to, or NULL if none.
sigA 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
framesPositive number of frames received in slave mode.
0If successful in master mode.
-errnoNegative 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
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufsBuffer array where data to be sent originates from.
Return values
0If successful.
-errnoNegative 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
specSPI specification from devicetree
tx_bufsBuffer 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
devPointer to the device structure for the driver instance
configPointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.
tx_bufsBuffer array where data to be sent originates from.
sigA 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
0If successful.
-errnoNegative errno code on failure.

Variable Documentation

◆ spi_iodev_api

const struct rtio_iodev_api spi_iodev_api
extern