Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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 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
 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.
 

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
 

Detailed Description

Public API for SPI drivers and applications.