spi.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_SPI_H_
#define ZEPHYR_INCLUDE_DRIVERS_SPI_H_

 
#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>
 
#ifdef __cplusplus
extern "C" {
#endif


#define SPI_OP_MODE_MASTER      0U

#define SPI_OP_MODE_SLAVE       BIT(0)  

#define SPI_OP_MODE_MASK        0x1U

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


#define SPI_MODE_CPOL           BIT(1)

#define SPI_MODE_CPHA           BIT(2)

#define SPI_MODE_LOOP           BIT(3)

#define SPI_MODE_MASK           (0xEU)

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

 


#define SPI_TRANSFER_MSB        (0U)
#define SPI_TRANSFER_LSB        BIT(4)

#define SPI_WORD_SIZE_SHIFT     (5U)
#define SPI_WORD_SIZE_MASK      (0x3FU << SPI_WORD_SIZE_SHIFT)

#define SPI_WORD_SIZE_GET(operation)                                    \
        (((operation) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT)

#define SPI_WORD_SET(word_size)                 \
        ((word_size) << SPI_WORD_SIZE_SHIFT)

 


#define SPI_HOLD_ON_CS          BIT(12)

#define SPI_LOCK_ON             BIT(13)

#define SPI_CS_ACTIVE_HIGH      BIT(14)

 

#define SPI_LINES_SINGLE        (0U << 16)     
#define SPI_LINES_DUAL          (1U << 16)     
#define SPI_LINES_QUAD          (2U << 16)     
#define SPI_LINES_OCTAL         (3U << 16)     
 
#define SPI_LINES_MASK          (0x3U << 16)   



struct spi_cs_control {
        union {
                struct {
                        struct gpio_dt_spec gpio;
                        uint32_t delay;
                };
                struct {
                        uint32_t setup_ns;
                        uint32_t hold_ns;
                };
        };
        /* To keep track of which form of this struct is valid */
        bool cs_is_gpio;
};

#define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev)                       \
        GPIO_DT_SPEC_GET_BY_IDX_OR(DT_BUS(spi_dev), cs_gpios,   \
                                   DT_REG_ADDR_RAW(spi_dev), {})

#define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
        SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))

#define SPI_CS_CONTROL_MAX_DELAY(node_id)                       \
        MAX(DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0),      \
            DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0))
 
 
#define SPI_CS_CONTROL_INIT_GPIO(node_id, ...)                                          \
        .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id),                                      \
        .delay = COND_CODE_1(IS_EMPTY(__VA_ARGS__),                                     \
                        (DIV_ROUND_UP(SPI_CS_CONTROL_MAX_DELAY(node_id), 1000)),        \
                        (__VA_ARGS__)),
 
#define SPI_CS_CONTROL_INIT_NATIVE(node_id)                                             \
        .setup_ns = DT_PROP_OR(node_id, spi_cs_setup_delay_ns, 0),                      \
        .hold_ns = DT_PROP_OR(node_id, spi_cs_hold_delay_ns, 0),
 
#define SPI_DEPRECATE_DELAY_WARN                                                        \
        __WARN("Delay parameter in SPI DT macros is deprecated, use DT prop instead")

#define SPI_CS_CONTROL_INIT(node_id, ...)                                       \
{                                                                               \
        COND_CODE_0(IS_EMPTY(__VA_ARGS__), (SPI_DEPRECATE_DELAY_WARN), ())      \
        COND_CODE_1(DT_SPI_DEV_HAS_CS_GPIOS(node_id),                           \
                        (SPI_CS_CONTROL_INIT_GPIO(node_id, __VA_ARGS__)),       \
                        (SPI_CS_CONTROL_INIT_NATIVE(node_id)))                  \
        .cs_is_gpio = DT_SPI_DEV_HAS_CS_GPIOS(node_id),                         \
}

#define SPI_CS_CONTROL_INIT_INST(inst)                  \
        SPI_CS_CONTROL_INIT(DT_DRV_INST(inst))


#if defined(CONFIG_SPI_EXTENDED_MODES)
typedef uint32_t spi_operation_t;
#else
typedef uint16_t spi_operation_t;
#endif

struct spi_config {
        uint32_t frequency;
        spi_operation_t operation;
        uint16_t slave;
        struct spi_cs_control cs;
        uint16_t word_delay;
};

/* converts from the special DT zero value to half of the frequency, for drivers usage mostly */
static inline uint16_t spi_get_word_delay(const struct spi_config *cfg)
{
        uint32_t freq = cfg->frequency;
 
        if (cfg->word_delay != 0) {
                return cfg->word_delay;
        }
 
        if (freq == 0) {
                return 0;
        }
 
        uint64_t period_ns = NSEC_PER_SEC / freq;
 
        period_ns = MIN(period_ns, UINT16_MAX);
        period_ns /= 2;
 
        return (uint16_t)period_ns;
}

#define SPI_CONFIG_DT(node_id, operation_, ...)                         \
        {                                                               \
                .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)) | \
                        COND_CODE_1(DT_PROP(node_id, spi_lsb_first), SPI_TRANSFER_LSB, (0)) |   \
                        COND_CODE_1(DT_PROP(node_id, spi_cs_high), SPI_CS_ACTIVE_HIGH, (0)),    \
                .slave = DT_REG_ADDR(node_id),                          \
                .cs = SPI_CS_CONTROL_INIT(node_id, __VA_ARGS__),        \
                .word_delay = DT_PROP(node_id, spi_interframe_delay_ns),\
        }

#define SPI_CONFIG_DT_INST(inst, operation_, ...)               \
        SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, __VA_ARGS__)

struct spi_dt_spec {
        const struct device *bus;
        struct spi_config config;
};

#define SPI_DT_SPEC_GET(node_id, operation_, ...)                               \
        {                                                                       \
                .bus = DEVICE_DT_GET(DT_BUS(node_id)),                          \
                .config = SPI_CONFIG_DT(node_id, operation_, __VA_ARGS__),      \
        }

#define SPI_DT_SPEC_INST_GET(inst, operation_, ...) \
        SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, __VA_ARGS__)

#define SPI_MOSI_OVERRUN_UNKNOWN 0x100

#define SPI_MOSI_OVERRUN_DT(node_id) \
        DT_PROP_OR(node_id, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)

#define SPI_MOSI_OVERRUN_DT_INST(inst) \
        DT_INST_PROP_OR(inst, overrun_character, SPI_MOSI_OVERRUN_UNKNOWN)

struct spi_buf {
        void *buf;
        size_t len;
};

struct spi_buf_set {
        const struct spi_buf *buffers;
        size_t count;
};

#if defined(CONFIG_SPI_STATS)
STATS_SECT_START(spi)
STATS_SECT_ENTRY32(rx_bytes)
STATS_SECT_ENTRY32(tx_bytes)
STATS_SECT_ENTRY32(transfer_error)
STATS_SECT_END;
 
STATS_NAME_START(spi)
STATS_NAME(spi, rx_bytes)
STATS_NAME(spi, tx_bytes)
STATS_NAME(spi, transfer_error)
STATS_NAME_END(spi);

struct spi_device_state {
        struct device_state devstate;
        struct stats_spi stats;
};

#define Z_SPI_GET_STATS(dev_)                           \
        CONTAINER_OF(dev_->state, struct spi_device_state, devstate)->stats

#define SPI_STATS_RX_BYTES_INCN(dev_, n)                        \
        STATS_INCN(Z_SPI_GET_STATS(dev_), rx_bytes, n)

#define SPI_STATS_TX_BYTES_INCN(dev_, n)                        \
        STATS_INCN(Z_SPI_GET_STATS(dev_), tx_bytes, n)

#define SPI_STATS_TRANSFER_ERROR_INC(dev_)                      \
        STATS_INC(Z_SPI_GET_STATS(dev_), transfer_error)

#define Z_SPI_DEVICE_STATE_DEFINE(dev_id)       \
        static struct spi_device_state Z_DEVICE_STATE_NAME(dev_id)      \
        __attribute__((__section__(".z_devstate")));

#define Z_SPI_INIT_FN(dev_id, init_fn)                                  \
        static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
        {                                                               \
                struct spi_device_state *state =                        \
                        CONTAINER_OF(dev->state, struct spi_device_state, devstate); \
                stats_init(&state->stats.s_hdr, STATS_SIZE_32, 3,       \
                           STATS_NAME_INIT_PARMS(spi));                 \
                stats_register(dev->name, &(state->stats.s_hdr));       \
                return init_fn(dev);                                    \
        }
 
#define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn,        \
                                    pm_device, data_ptr, cfg_ptr,       \
                                    level, prio, api_ptr, ...)          \
        Z_SPI_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));         \
        Z_SPI_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn)             \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),           \
                        DEVICE_DT_NAME(node_id),                        \
                        &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init),  \
                        deinit_fn, Z_DEVICE_DT_FLAGS(node_id),          \
                        pm_device, data_ptr, cfg_ptr, level, prio,      \
                        api_ptr,                                        \
                        &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
                        __VA_ARGS__)
 
static inline void spi_transceive_stats(const struct device *dev, int error,
                                        const struct spi_buf_set *tx_bufs,
                                        const struct spi_buf_set *rx_bufs)
{
        uint32_t tx_bytes;
        uint32_t rx_bytes;
 
        if (error) {
                SPI_STATS_TRANSFER_ERROR_INC(dev);
        }
 
        if (tx_bufs) {
                tx_bytes = tx_bufs->count ? tx_bufs->buffers->len : 0;
                SPI_STATS_TX_BYTES_INCN(dev, tx_bytes);
        }
 
        if (rx_bufs) {
                rx_bytes = rx_bufs->count ? rx_bufs->buffers->len : 0;
                SPI_STATS_RX_BYTES_INCN(dev, rx_bytes);
        }
}
 
#else /*CONFIG_SPI_STATS*/


#define SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, data,      \
                                    config, level, prio, api, ...)              \
        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, deinit_fn,            \
                        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__)

 
#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)
 
#endif /*CONFIG_SPI_STATS*/

#define SPI_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio,   \
                             api, ...)                                          \
        SPI_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, NULL, pm, data, config,   \
                                    level, prio, api, __VA_ARGS__)

#define SPI_DEVICE_DT_INST_DEINIT_DEFINE(inst, ...) \
        SPI_DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)

#define SPI_DEVICE_DT_INST_DEFINE(inst, ...)                                       \
        SPI_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)


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

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

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);
 
#if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)

typedef void (*spi_api_iodev_submit)(const struct device *dev,
                                     struct rtio_iodev_sqe *iodev_sqe);
#endif /* CONFIG_SPI_RTIO */

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

__subsystem struct spi_driver_api {
        spi_api_io transceive;
#if defined(CONFIG_SPI_ASYNC) || defined(__DOXYGEN__)
        spi_api_io_async transceive_async;
#endif /* CONFIG_SPI_ASYNC */
#if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)
        spi_api_iodev_submit iodev_submit;
#endif /* CONFIG_SPI_RTIO */
        spi_api_release release;
};


static inline bool spi_cs_is_gpio(const struct spi_config *config)
{
        return config->cs.cs_is_gpio;
}

static inline bool spi_cs_is_gpio_dt(const struct spi_dt_spec *spec)
{
        return spi_cs_is_gpio(&spec->config);
}

static inline bool spi_is_ready_dt(const struct spi_dt_spec *spec)
{
        /* Validate bus is ready */
        if (!device_is_ready(spec->bus)) {
                return false;
        }
        /* Validate CS gpio port is ready, if it is used */
        if (spi_cs_is_gpio_dt(spec) &&
            !gpio_is_ready_dt(&spec->config.cs.gpio)) {
                return false;
        }
        return true;
}


__syscall 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);
 
static inline int z_impl_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)
{
        const struct spi_driver_api *api =
                (const struct spi_driver_api *)dev->api;
        int ret;
 
        ret = api->transceive(dev, config, tx_bufs, rx_bufs);
        spi_transceive_stats(dev, ret, tx_bufs, rx_bufs);
 
        return ret;
}

static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
                                    const struct spi_buf_set *tx_bufs,
                                    const struct spi_buf_set *rx_bufs)
{
        return spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
}

static inline int spi_read(const struct device *dev,
                           const struct spi_config *config,
                           const struct spi_buf_set *rx_bufs)
{
        return spi_transceive(dev, config, NULL, rx_bufs);
}

static inline int spi_read_dt(const struct spi_dt_spec *spec,
                              const struct spi_buf_set *rx_bufs)
{
        return spi_read(spec->bus, &spec->config, rx_bufs);
}

static inline int spi_write(const struct device *dev,
                            const struct spi_config *config,
                            const struct spi_buf_set *tx_bufs)
{
        return spi_transceive(dev, config, tx_bufs, NULL);
}

static inline int spi_write_dt(const struct spi_dt_spec *spec,
                               const struct spi_buf_set *tx_bufs)
{
        return spi_write(spec->bus, &spec->config, tx_bufs);
}

 
#if defined(CONFIG_SPI_ASYNC) || defined(__DOXYGEN__)

static inline 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)
{
        const struct spi_driver_api *api =
                (const struct spi_driver_api *)dev->api;
 
        return api->transceive_async(dev, config, tx_bufs, rx_bufs, callback, userdata);
}
 
#if defined(CONFIG_POLL) || defined(__DOXYGEN__)

void z_spi_transfer_signal_cb(const struct device *dev, int result, void *userdata);

static inline 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)
{
        const struct spi_driver_api *api =
                (const struct spi_driver_api *)dev->api;
        spi_callback_t cb = (sig == NULL) ? NULL : z_spi_transfer_signal_cb;
 
        return api->transceive_async(dev, config, tx_bufs, rx_bufs, cb, sig);
}

static inline 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)
{
        return spi_transceive_signal(dev, config, NULL, rx_bufs, sig);
}

static inline 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)
{
        return spi_transceive_signal(dev, config, tx_bufs, NULL, sig);
}
 
#endif /* CONFIG_POLL */

#endif /* CONFIG_SPI_ASYNC */
 
 
#if defined(CONFIG_SPI_RTIO) || defined(__DOXYGEN__)

static inline void spi_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
{
        const struct spi_dt_spec *dt_spec = (const struct spi_dt_spec *)iodev_sqe->sqe.iodev->data;
        const struct device *dev = dt_spec->bus;
        const struct spi_driver_api *api = (const struct spi_driver_api *)dev->api;
 
        api->iodev_submit(dt_spec->bus, iodev_sqe);
}

extern const struct rtio_iodev_api spi_iodev_api;

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

#define SPI_DT_INST_IODEV_DEFINE(name, inst, operation_, ...)                   \
        SPI_DT_IODEV_DEFINE(name, DT_DRV_INST(inst), operation_, __VA_ARGS__)

static inline bool spi_is_ready_iodev(const struct rtio_iodev *spi_iodev)
{
        struct spi_dt_spec *spec = (struct spi_dt_spec *)spi_iodev->data;
 
        return spi_is_ready_dt(spec);
}

 
#endif /* CONFIG_SPI_RTIO */

__syscall int spi_release(const struct device *dev,
                          const struct spi_config *config);
 
static inline int z_impl_spi_release(const struct device *dev,
                                     const struct spi_config *config)
{
        const struct spi_driver_api *api =
                (const struct spi_driver_api *)dev->api;
 
        return api->release(dev, config);
}

static inline int spi_release_dt(const struct spi_dt_spec *spec)
{
        return spi_release(spec->bus, &spec->config);
}
 
#ifdef __cplusplus
}
#endif

 
#include <zephyr/syscalls/spi.h>

#endif /* ZEPHYR_INCLUDE_DRIVERS_SPI_H_ */