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>
 
#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)
/* Requests - if possible - to keep CS asserted after the transaction */
#define SPI_HOLD_ON_CS          BIT(12)
/* 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.
 */
#define SPI_LOCK_ON             BIT(13)
 
/* 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.
 */
#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 {
        struct gpio_dt_spec gpio;
        uint32_t delay;
};
 
#define SPI_CS_GPIOS_DT_SPEC_GET(spi_dev) \
        GPIO_DT_SPEC_GET_BY_IDX(DT_BUS(spi_dev), cs_gpios, DT_REG_ADDR(spi_dev))
 
#define SPI_CS_GPIOS_DT_SPEC_INST_GET(inst) \
        SPI_CS_GPIOS_DT_SPEC_GET(DT_DRV_INST(inst))
 
#ifndef __cplusplus
#define SPI_CS_CONTROL_PTR_DT(node_id, delay_)                    \
        (&(struct spi_cs_control) {                               \
                .gpio = SPI_CS_GPIOS_DT_SPEC_GET(node_id),        \
                .delay = (delay_),                                \
        })
 
#define SPI_CS_CONTROL_PTR_DT_INST(inst, delay_)                \
        SPI_CS_CONTROL_PTR_DT(DT_DRV_INST(inst), delay_)
#endif
 
struct spi_config {
        uint32_t                frequency;
#if defined(CONFIG_SPI_EXTENDED_MODES)
        uint32_t                operation;
        uint16_t                slave;
        uint16_t                _unused;
#else
        uint16_t                operation;
        uint16_t                slave;
#endif /* CONFIG_SPI_EXTENDED_MODES */
 
        const struct spi_cs_control *cs;
};
 
#ifndef __cplusplus
#define SPI_CONFIG_DT(node_id, operation_, delay_)                      \
        {                                                               \
                .frequency = DT_PROP(node_id, spi_max_frequency),       \
                .operation = (operation_) |                             \
                        DT_PROP(node_id, duplex) |                      \
                        DT_PROP(node_id, frame_format),                 \
                .slave = DT_REG_ADDR(node_id),                          \
                .cs = COND_CODE_1(                                      \
                        DT_SPI_DEV_HAS_CS_GPIOS(node_id),               \
                        (SPI_CS_CONTROL_PTR_DT(node_id, delay_)),       \
                        (NULL)),                                        \
        }
 
#define SPI_CONFIG_DT_INST(inst, operation_, delay_)    \
        SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_)
#endif
 
struct spi_dt_spec {
        const struct device *bus;
        struct spi_config config;
};
 
#ifndef __cplusplus
#define SPI_DT_SPEC_GET(node_id, operation_, delay_)                 \
        {                                                            \
                .bus = DEVICE_DT_GET(DT_BUS(node_id)),               \
                .config = SPI_CONFIG_DT(node_id, operation_, delay_) \
        }
 
#define SPI_DT_SPEC_INST_GET(inst, operation_, delay_) \
        SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_)
#endif
 
struct spi_buf {
        void *buf;
        size_t len;
};
 
struct spi_buf_set {
        const struct spi_buf *buffers;
        size_t count;
};
 
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);
 
typedef int (*spi_api_release)(const struct device *dev,
                               const struct spi_config *config);
 
 
__subsystem struct spi_driver_api {
        spi_api_io transceive;
#ifdef CONFIG_SPI_ASYNC
        spi_api_io_async transceive_async;
#endif /* CONFIG_SPI_ASYNC */
        spi_api_release release;
};
 
__deprecated
static inline bool spi_is_ready(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 (spec->config.cs &&
            !device_is_ready(spec->config.cs->gpio.port)) {
                return false;
        }
        return true;
}
 
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 (spec->config.cs &&
            !device_is_ready(spec->config.cs->gpio.port)) {
                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;
 
        return api->transceive(dev, config, tx_bufs, rx_bufs);
}
 
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);
}
 
/* Doxygen defines this so documentation is generated. */
#ifdef CONFIG_SPI_ASYNC
 
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);
}
 
#ifdef CONFIG_POLL
 
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);
}
 
__deprecated static inline int spi_transceive_async(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)
{
        return spi_transceive_signal(dev, config, tx_bufs, rx_bufs, 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);
}
 
__deprecated static inline int spi_read_async(const struct device *dev,
                                 const struct spi_config *config,
                                 const struct spi_buf_set *rx_bufs,
                                 struct k_poll_signal *sig)
{
        return spi_read_signal(dev, config, 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);
}
 
__deprecated static inline int spi_write_async(const struct device *dev,
                                 const struct spi_config *config,
                                 const struct spi_buf_set *tx_bufs,
                                 struct k_poll_signal *sig)
{
        return spi_write_signal(dev, config, tx_bufs, sig);
}
 
#endif /* CONFIG_POLL */
 
#endif /* CONFIG_SPI_ASYNC */
 
__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 <syscalls/spi.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_SPI_H_ */