12#ifndef ZEPHYR_INCLUDE_DRIVERS_SPI_H_
13#define ZEPHYR_INCLUDE_DRIVERS_SPI_H_
42#define SPI_OP_MODE_MASTER 0U
43#define SPI_OP_MODE_SLAVE BIT(0)
45#define SPI_OP_MODE_MASK 0x1U
48#define SPI_OP_MODE_GET(_operation_) ((_operation_) & SPI_OP_MODE_MASK)
61#define SPI_MODE_CPOL BIT(1)
70#define SPI_MODE_CPHA BIT(2)
77#define SPI_MODE_LOOP BIT(3)
79#define SPI_MODE_MASK (0xEU)
82#define SPI_MODE_GET(_mode_) \
83 ((_mode_) & SPI_MODE_MASK)
91#define SPI_TRANSFER_MSB (0U)
92#define SPI_TRANSFER_LSB BIT(4)
100#define SPI_WORD_SIZE_SHIFT (5U)
101#define SPI_WORD_SIZE_MASK (0x3FU << SPI_WORD_SIZE_SHIFT)
104#define SPI_WORD_SIZE_GET(_operation_) \
105 (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)
107#define SPI_WORD_SET(_word_size_) \
108 ((_word_size_) << SPI_WORD_SIZE_SHIFT)
116#define SPI_HOLD_ON_CS BIT(12)
122#define SPI_LOCK_ON BIT(13)
131#define SPI_CS_ACTIVE_HIGH BIT(14)
143#define SPI_LINES_SINGLE (0U << 16)
144#define SPI_LINES_DUAL (1U << 16)
145#define SPI_LINES_QUAD (2U << 16)
146#define SPI_LINES_OCTAL (3U << 16)
148#define SPI_LINES_MASK (0x3U << 16)
212#define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev) \
213 GPIO_DT_SPEC_GET_BY_IDX_OR(DT_BUS(spi_dev), cs_gpios, \
214 DT_REG_ADDR_RAW(spi_dev), {})
225#define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
226 SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))
266#define SPI_CS_CONTROL_INIT(node_id, delay_) \
268 .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id), \
285#define SPI_CS_CONTROL_INIT_INST(inst, delay_) \
286 SPI_CS_CONTROL_INIT(DT_DRV_INST(inst), delay_)
292#if defined(CONFIG_SPI_EXTENDED_MODES)
347#define SPI_CONFIG_DT(node_id, operation_, delay_) \
349 .frequency = DT_PROP(node_id, spi_max_frequency), \
350 .operation = (operation_) | \
351 DT_PROP(node_id, duplex) | \
352 DT_PROP(node_id, frame_format) | \
353 COND_CODE_1(DT_PROP(node_id, spi_cpol), SPI_MODE_CPOL, (0)) | \
354 COND_CODE_1(DT_PROP(node_id, spi_cpha), SPI_MODE_CPHA, (0)) | \
355 COND_CODE_1(DT_PROP(node_id, spi_hold_cs), SPI_HOLD_ON_CS, (0)), \
356 .slave = DT_REG_ADDR(node_id), \
357 .cs = SPI_CS_CONTROL_INIT(node_id, delay_), \
371#define SPI_CONFIG_DT_INST(inst, operation_, delay_) \
372 SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)
401#define SPI_DT_SPEC_GET(node_id, operation_, delay_) \
403 .bus = DEVICE_DT_GET(DT_BUS(node_id)), \
404 .config = SPI_CONFIG_DT(node_id, operation_, delay_) \
418#define SPI_DT_SPEC_INST_GET(inst, operation_, delay_) \
419 SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)
424#define SPI_MOSI_OVERRUN_UNKNOWN 0x100
438#define SPI_MOSI_OVERRUN_DT(node_id) \
439 DT_PROP_OR(node_id, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
452#define SPI_MOSI_OVERRUN_DT_INST(inst) \
453 DT_INST_PROP_OR(inst, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)
478#if defined(CONFIG_SPI_STATS)
494struct spi_device_state {
496 struct stats_spi stats;
502#define Z_SPI_GET_STATS(dev_) \
503 CONTAINER_OF(dev_->state, struct spi_device_state, devstate)->stats
510#define SPI_STATS_RX_BYTES_INCN(dev_, n) \
511 STATS_INCN(Z_SPI_GET_STATS(dev_), rx_bytes, n)
518#define SPI_STATS_TX_BYTES_INCN(dev_, n) \
519 STATS_INCN(Z_SPI_GET_STATS(dev_), tx_bytes, n)
528#define SPI_STATS_TRANSFER_ERROR_INC(dev_) \
529 STATS_INC(Z_SPI_GET_STATS(dev_), transfer_error)
534#define Z_SPI_DEVICE_STATE_DEFINE(dev_id) \
535 static struct spi_device_state Z_DEVICE_STATE_NAME(dev_id) \
536 __attribute__((__section__(".z_devstate")));
544#define Z_SPI_INIT_FN(dev_id, init_fn) \
545 static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
547 struct spi_device_state *state = \
548 CONTAINER_OF(dev->state, struct spi_device_state, devstate); \
549 stats_init(&state->stats.s_hdr, STATS_SIZE_32, 3, \
550 STATS_NAME_INIT_PARMS(spi)); \
551 stats_register(dev->name, &(state->stats.s_hdr)); \
552 return init_fn(dev); \
574#define SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm_device, \
575 data_ptr, cfg_ptr, level, prio, \
577 Z_SPI_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
578 Z_SPI_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn) \
579 Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
580 DEVICE_DT_NAME(node_id), \
581 &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init), \
583 data_ptr, cfg_ptr, level, prio, \
585 &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
601 SPI_STATS_TX_BYTES_INCN(dev, tx_bytes);
606 SPI_STATS_RX_BYTES_INCN(dev, rx_bytes);
612#define SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, \
613 data, config, level, prio, \
615 Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
616 Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
617 DEVICE_DT_NAME(node_id), init_fn, pm, data, config, \
619 &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)), \
622#define SPI_STATS_RX_BYTES_INC(dev_)
623#define SPI_STATS_TX_BYTES_INC(dev_)
624#define SPI_STATS_TRANSFER_ERROR_INC(dev_)
626#define spi_transceive_stats(dev, error, tx_bufs, rx_bufs)
661#if defined(CONFIG_SPI_RTIO) || defined(DOXYGEN)
667typedef void (*spi_api_iodev_submit)(
const struct device *dev,
686#ifdef CONFIG_SPI_ASYNC
689#ifdef CONFIG_SPI_RTIO
690 spi_api_iodev_submit iodev_submit;
764static inline int z_impl_spi_transceive(
const struct device *dev,
773 ret = api->transceive(dev, config, tx_bufs, rx_bufs);
884#if defined(CONFIG_SPI_ASYNC) || defined(__DOXYGEN__)
922 return api->transceive_async(dev, config, tx_bufs, rx_bufs, callback, userdata);
925#if defined(CONFIG_POLL) || defined(__DOXYGEN__)
928void z_spi_transfer_signal_cb(
const struct device *dev,
int result,
void *userdata);
964 spi_callback_t cb = (sig == NULL) ? NULL : z_spi_transfer_signal_cb;
966 return api->transceive_async(dev, config, tx_bufs, rx_bufs, cb, sig);
1037#if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)
1049 const struct device *dev = dt_spec->
bus;
1052 api->iodev_submit(dt_spec->
bus, iodev_sqe);
1068#define SPI_DT_IODEV_DEFINE(name, node_id, operation_, delay_) \
1069 const struct spi_dt_spec _spi_dt_spec_##name = \
1070 SPI_DT_SPEC_GET(node_id, operation_, delay_); \
1071 RTIO_IODEV_DEFINE(name, &spi_iodev_api, (void *)&_spi_dt_spec_##name)
1113static inline int z_impl_spi_release(
const struct device *dev,
1119 return api->release(dev, config);
1146#include <zephyr/syscalls/spi.h>
Public APIs for GPIO drivers.
bool device_is_ready(const struct device *dev)
Verify that a device is ready for use.
static bool gpio_is_ready_dt(const struct gpio_dt_spec *spec)
Validate that GPIO port is ready.
Definition gpio.h:835
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)
Definition spi.h:654
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.
void(* spi_callback_t)(const struct device *dev, int result, void *data)
SPI callback for asynchronous transfer requests.
Definition spi.h:647
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.
Definition spi.h:878
static bool spi_is_ready_dt(const struct spi_dt_spec *spec)
Validate that SPI bus (and CS gpio if defined) is ready.
Definition spi.h:727
uint16_t spi_operation_t
Opaque type to hold the SPI operation flags.
Definition spi.h:295
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.
Definition spi.h:635
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.
Definition spi.h:956
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.
Definition spi.h:818
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.
Definition spi.h:794
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.
Definition spi.h:912
#define SPI_STATS_TRANSFER_ERROR_INC(dev_)
Definition spi.h:624
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.
Definition spi.h:837
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.
Definition spi.h:859
static int spi_release_dt(const struct spi_dt_spec *spec)
Release the SPI device specified in spi_dt_spec.
Definition spi.h:1133
static void spi_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
Submit a SPI device with a request.
Definition spi.h:1046
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.
Definition spi.h:993
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.
Definition spi.h:714
int(* spi_api_release)(const struct device *dev, const struct spi_config *config)
Callback API for unlocking SPI device.
Definition spi.h:676
const struct rtio_iodev_api spi_iodev_api
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.
#define spi_transceive_stats(dev, error, tx_bufs, rx_bufs)
Definition spi.h:626
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.
Definition spi.h:1024
static bool spi_cs_is_gpio(const struct spi_config *config)
Check if SPI CS is controlled using a GPIO.
Definition spi.h:702
static bool spi_is_ready_iodev(const struct rtio_iodev *spi_iodev)
Validate that SPI bus (and CS gpio if defined) is ready.
Definition spi.h:1081
Real-Time IO device API for moving bytes with low effort.
#define STATS_NAME_END(name__)
Definition stats.h:391
#define STATS_NAME(name__, entry__)
Definition stats.h:390
#define STATS_SECT_END
Ends a stats group struct definition.
Definition stats.h:89
#define STATS_SECT_ENTRY32(var__)
Definition stats.h:359
#define STATS_NAME_START(name__)
Definition stats.h:389
#define STATS_SECT_START(group__)
Definition stats.h:354
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
Runtime device dynamic structure (in RAM) per driver instance.
Definition device.h:380
Runtime device structure (in ROM) per driver instance.
Definition device.h:412
void * data
Address of the device instance private data.
Definition device.h:422
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:418
Container for GPIO pin information specified in devicetree.
Definition gpio.h:288
const struct device * port
GPIO device controlling the pin.
Definition gpio.h:290
API that an RTIO IO device should implement.
Definition rtio.h:439
Compute the mempool block index for a given pointer.
Definition rtio.h:429
struct rtio_sqe sqe
Definition rtio.h:430
An IO device with a function table for submitting requests.
Definition rtio.h:454
void * data
Definition rtio.h:459
const struct rtio_iodev * iodev
Device to operation on.
Definition rtio.h:243
SPI buffer array structure.
Definition spi.h:471
const struct spi_buf * buffers
Pointer to an array of spi_buf, or NULL.
Definition spi.h:473
size_t count
Length of the array pointed by buffers.
Definition spi.h:475
SPI buffer structure.
Definition spi.h:458
size_t len
Length of the buffer buf.
Definition spi.h:465
void * buf
Valid pointer to a data buffer, or NULL otherwise.
Definition spi.h:460
SPI controller configuration structure.
Definition spi.h:301
uint16_t slave
Slave number from 0 to host controller slave limit.
Definition spi.h:326
struct spi_cs_control cs
GPIO chip-select line (optional, must be initialized to zero if not used).
Definition spi.h:331
spi_operation_t operation
Operation flags.
Definition spi.h:324
uint32_t frequency
Bus frequency in Hertz.
Definition spi.h:303
SPI Chip Select control structure.
Definition spi.h:159
uint32_t delay
Delay in microseconds to wait before starting the transmission and before releasing the CS line.
Definition spi.h:172
struct gpio_dt_spec gpio
GPIO devicetree specification of CS GPIO.
Definition spi.h:167
SPI driver API This is the mandatory API any SPI driver needs to expose.
Definition spi.h:684
spi_api_io transceive
Definition spi.h:685
spi_api_release release
Definition spi.h:692
Complete SPI DT information.
Definition spi.h:377
const struct device * bus
SPI bus.
Definition spi.h:379
struct spi_config config
Slave specific configuration.
Definition spi.h:381