SPI

Overview

API Reference

group spi_interface

SPI Interface.

SPI operational mode

SPI_OP_MODE_MASTER
SPI_OP_MODE_SLAVE
SPI_OP_MODE_MASK
SPI_OP_MODE_GET(_operation_)

SPI Polarity & Phase Modes

SPI_MODE_CPOL

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_CPHA

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_LOOP

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_MODE_MASK
SPI_MODE_GET(_mode_)

SPI Transfer modes (host controller dependent)

SPI_TRANSFER_MSB
SPI_TRANSFER_LSB

SPI word size

SPI_WORD_SIZE_SHIFT
SPI_WORD_SIZE_MASK
SPI_WORD_SIZE_GET(_operation_)
SPI_WORD_SET(_word_size_)

Specific SPI devices control bits

SPI_HOLD_ON_CS
SPI_LOCK_ON
SPI_CS_ACTIVE_HIGH

SPI MISO lines (if \htmlonly <code>CONFIG_SPI_EXTENDED_MODES</code> \endhtmlonly \xmlonly <verbatim>embed:rst:inline :kconfig:option:`CONFIG_SPI_EXTENDED_MODES`</verbatim> \endxmlonly is enabled)

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.

SPI_LINES_SINGLE
SPI_LINES_DUAL
SPI_LINES_QUAD
SPI_LINES_OCTAL
SPI_LINES_MASK

SPI duplex mode

Some controllers support half duplex transfer, which results in 3-wire usage. By default, full duplex will prevail.

SPI_FULL_DUPLEX
SPI_HALF_DUPLEX

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.

SPI_FRAME_FORMAT_MOTOROLA
SPI_FRAME_FORMAT_TI

Defines

SPI_CS_GPIOS_DT_SPEC_GET(spi_dev)

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:

SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(a)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio1)), 10, GPIO_ACTIVE_LOW }
SPI_CS_GPIOS_DT_SPEC_GET(DT_NODELABEL(b)) \
      // { DEVICE_DT_GET(DT_NODELABEL(gpio2)), 20, GPIO_ACTIVE_LOW }

Parameters
  • spi_dev – a SPI device node identifier

Returns

gpio_dt_spec struct corresponding with spi_dev’s chip select

SPI_CS_GPIOS_DT_SPEC_INST_GET(inst)

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
  • inst – Devicetree instance number

Returns

gpio_dt_spec struct corresponding with spi_dev’s chip select

SPI_CS_CONTROL_PTR_DT(node_id, delay_)

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@... {
        cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
        spidev: spi-device@0 { ... };
};
Assume that gpio0 follows the standard convention for specifying GPIOs, i.e. it has the following in its binding:
gpio-cells:
- pin
- flags
Example usage:
struct spi_cs_control *ctrl =
        SPI_CS_CONTROL_PTR_DT(DT_NODELABEL(spidev), 2);
This example is equivalent to:
struct spi_cs_control *ctrl =
        &(struct spi_cs_control) {
                .gpio_dev = DEVICE_DT_GET(DT_NODELABEL(gpio0)),
                .delay = 2,
                .gpio_pin = 1,
                .gpio_dt_flags = GPIO_ACTIVE_LOW
        };
This macro is not available in C++.

Parameters
  • node_id – Devicetree 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_PTR_DT_INST(inst, delay_)

Get a pointer to a spi_cs_control from a devicetree node.

This is equivalent to SPI_CS_CONTROL_PTR_DT(DT_DRV_INST(inst), delay).

Therefore, DT_DRV_COMPAT must already be defined before using this macro.

This macro is not available in C++.

Parameters
  • inst – Devicetree node instance number

  • delay_ – The delay field to set in the spi_cs_control

Returns

a pointer to the spi_cs_control structure

SPI_CONFIG_DT(node_id, operation_, delay_)

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.

Important: the cs field is initialized using SPI_CS_CONTROL_PTR_DT(). The gpio_dev value pointed to by this structure must be checked using device_is_ready() before use.

This macro is not available in C++.

Parameters
  • node_id – Devicetree 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(inst, operation_, delay_)

Structure initializer for spi_config from devicetree instance.

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

This macro is not available in C++.

Parameters
  • inst – Devicetree 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_DT_SPEC_GET(node_id, operation_, delay_)

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 performs the required device_is_ready checks.

Deprecated:

Use spi_is_ready_dt instead.

This macro is not available in C++.

Parameters
  • node_id – Devicetree 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(inst, operation_, delay_)

Structure initializer for spi_dt_spec from devicetree instance.

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

This macro is not available in C++.

Parameters
  • inst – Devicetree 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

Typedefs

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.

Callback API for asynchronous I/O See spi_transceive_async() for argument descriptions.

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

SPI callback for asynchronous transfer requests.

Param dev

SPI device which is notifying of transfer completion or error

Param result

Result code of the transfer request. 0 is success, -errno for failure.

Param data

Transfer requester supplied data which is passed along to the callback.

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. See spi_release() for argument descriptions.

Functions

static inline bool spi_is_ready(const struct spi_dt_spec *spec)

Validate that SPI bus is ready.

Parameters
  • spec – SPI specification from devicetree

Return values
  • true – if the SPI bus is ready for use.

  • false – if the SPI bus is not ready for use.

static inline bool spi_is_ready_dt(const struct spi_dt_spec *spec)

Validate that SPI bus (and CS gpio if defined) is ready.

Parameters
  • spec – SPI specification from devicetree

Return values
  • true – if the SPI bus is ready for use.

  • false – if the SPI bus (or the CS gpio defined) is not ready for use.

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.

Note

This function is synchronous.

Parameters
  • dev – Pointer to the device structure for the driver instance

  • config – Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.

  • tx_bufs – Buffer array where data to be sent originates from, or NULL if none.

  • rx_bufs – Buffer array where data to be read will be written to, or NULL if none.

Return values
  • frames – Positive number of frames received in slave mode.

  • 0 – If successful in master mode.

  • -errno – Negative errno code on failure.

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)

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
  • spec – SPI specification from devicetree

  • tx_bufs – Buffer array where data to be sent originates from, or NULL if none.

  • rx_bufs – Buffer array where data to be read will be written to, or NULL if none.

Returns

a value from spi_transceive().

static inline 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.

Note

This function is synchronous.

Note

This function is an helper function calling spi_transceive.

Parameters
  • dev – Pointer to the device structure for the driver instance

  • config – Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.

  • rx_bufs – Buffer array where data to be read will be written to.

Return values
  • 0 – If successful.

  • -errno – Negative errno code on failure.

static inline 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.

This is equivalent to:

spi_read(spec->bus, &spec->config, rx_bufs);

Parameters
  • spec – SPI specification from devicetree

  • rx_bufs – Buffer array where data to be read will be written to.

Returns

a value from spi_read().

static inline 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.

Note

This function is synchronous.

Note

This function is an helper function calling spi_transceive.

Parameters
  • dev – Pointer to the device structure for the driver instance

  • config – Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.

  • tx_bufs – Buffer array where data to be sent originates from.

Return values
  • 0 – If successful.

  • -errno – Negative errno code on failure.

static inline 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.

This is equivalent to:

spi_write(spec->bus, &spec->config, tx_bufs);

Parameters
  • spec – SPI specification from devicetree

  • tx_bufs – Buffer array where data to be sent originates from.

Returns

a value from spi_write().

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)

Read/write the specified amount of data from the SPI driver.

Note

This function is asynchronous.

Note

This function is available only if CONFIG_SPI_ASYNC is selected.

Parameters
  • dev – Pointer to the device structure for the driver instance

  • config – Pointer to a valid spi_config structure instance. Pointer-comparison may be used to detect changes from previous operations.

  • tx_bufs – Buffer array where data to be sent originates from, or NULL if none.

  • rx_bufs – Buffer array where data to be read will be written to, or NULL if none.

  • callback – Function pointer to completion callback. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).

  • userdata – Userdata passed to callback

Return values
  • frames – Positive number of frames received in slave mode.

  • 0 – If successful in master mode.

  • -errno – Negative errno code on failure.

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.

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
  • dev – Pointer to the device structure for the driver instance

  • config – Pointer to a valid spi_config structure instance.

Return values
  • 0 – If successful.

  • -errno – Negative errno code on failure.

static inline int spi_release_dt(const struct spi_dt_spec *spec)

Release the SPI device specified in spi_dt_spec.

This is equivalent to:

spi_release(spec->bus, &spec->config);

Parameters
  • spec – SPI specification from devicetree

Returns

a value from spi_release().

struct spi_cs_control
#include <spi.h>

SPI Chip Select control structure.

This can be used to control a CS line via a GPIO line, instead of using the controller inner CS logic.

Public Members

struct gpio_dt_spec gpio

GPIO devicetree specification of CS GPIO. The device pointer can be set to NULL to fully inhibit CS control if necessary. The GPIO flags GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct spi_config.

uint32_t delay

Delay in microseconds to wait before starting the transmission and before releasing the CS line.

struct spi_config
#include <spi.h>

SPI controller configuration structure.

Warning

Most drivers use pointer comparison to determine whether a passed configuration is different from one used in a previous transaction. Changes to fields in the structure may not be detected.

Param frequency

is the bus frequency in Hertz

Param operation

is a bit field with the following parts:

operational mode    [ 0 ]       - master or slave.
mode                [ 1 : 3 ]   - Polarity, phase and loop mode.
transfer            [ 4 ]       - LSB or MSB first.
word_size           [ 5 : 10 ]  - Size of a data frame in bits.
duplex              [ 11 ]      - full/half duplex.
cs_hold             [ 12 ]      - Hold on the CS line if possible.
lock_on             [ 13 ]      - Keep resource locked for the caller.
cs_active_high      [ 14 ]      - Active high CS logic.
format              [ 15 ]      - Motorola or TI frame format (optional).
if CONFIG_SPI_EXTENDED_MODES is defined: lines [ 16 : 17 ] - MISO lines: Single/Dual/Quad/Octal. reserved [ 18 : 31 ] - reserved for future use.

Param slave

is the slave number from 0 to host controller slave limit.

Param cs

is a valid pointer on a struct spi_cs_control is CS line is emulated through a gpio line, or NULL otherwise.

struct spi_dt_spec
#include <spi.h>

Complete SPI DT information.

Param bus

is the SPI bus

Param config

is the slave specific configuration

struct spi_buf
#include <spi.h>

SPI buffer structure.

Param buf

is a valid pointer on a data buffer, or NULL otherwise.

Param len

is the length of the buffer or, if buf is NULL, will be the length which as to be sent as dummy bytes (as TX buffer) or the length of bytes that should be skipped (as RX buffer).

struct spi_buf_set
#include <spi.h>

SPI buffer array structure.

Param buffers

is a valid pointer on an array of spi_buf, or NULL.

Param count

is the length of the array pointed by buffers.

struct spi_driver_api
#include <spi.h>

SPI driver API This is the mandatory API any SPI driver needs to expose.