SPI¶
Overview¶
API Reference¶
-
group
spi_interface
SPI Interface.
Defines
-
SPI_OP_MODE_MASTER
¶ SPI operational mode.
-
SPI_OP_MODE_SLAVE
¶
-
SPI_OP_MODE_MASK
¶
-
SPI_OP_MODE_GET
(_operation_)¶
-
SPI_MODE_CPOL
¶ SPI Polarity & Phase Modes.
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_MSB
¶ SPI Transfer modes (host controller dependent)
-
SPI_TRANSFER_LSB
¶
-
SPI_WORD_SIZE_SHIFT
¶ SPI word size.
-
SPI_WORD_SIZE_MASK
¶
-
SPI_WORD_SIZE_GET
(_operation_)¶
-
SPI_WORD_SET
(_word_size_)¶
-
SPI_LINES_SINGLE
¶ 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.
-
SPI_LINES_DUAL
¶
-
SPI_LINES_QUAD
¶
-
SPI_LINES_OCTAL
¶
-
SPI_LINES_MASK
¶
-
SPI_HOLD_ON_CS
¶ Specific SPI devices control bits.
-
SPI_LOCK_ON
¶
-
SPI_CS_ACTIVE_HIGH
¶
-
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:
Assume thatspi@... { cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>; spidev: spi-device@0 { ... }; };
gpio0
follows the standard convention for specifying GPIOs, i.e. it has the following in its binding:Example usage:gpio-cells: - pin - flags
This example is equivalent to:struct spi_cs_control *ctrl = SPI_CS_CONTROL_PTR_DT(DT_NODELABEL(spidev), 2);
This macro is not available in C++.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 };
- Parameters
node_id – Devicetree node identifier for a device on a SPI bus
delay_ – The
delay
field to set in thespi_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 thespi_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 relevantfrequency
,slave
, andcs
data from the devicetree.Important: the
cs
field is initialized using SPI_CS_CONTROL_PTR_DT(). Thegpio_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_configdelay_ – 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_configdelay_ – 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.
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_configdelay_ – 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_configdelay_ – 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 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, struct k_poll_signal *async)¶
-
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
- Returns
true – if the SPI bus is ready for use.
false – if the SPI bus 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.
- Returns
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.
- Returns
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.
- Returns
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_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 *async)¶ Read/write the specified amount of data from the SPI driver.
Note
This function is asynchronous.
Note
This function is available only if :kconfig:`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.
async – A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).
- Returns
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_read_async
(const struct device *dev, const struct spi_config *config, const struct spi_buf_set *rx_bufs, struct k_poll_signal *async)¶ Read the specified amount of data from the SPI driver.
Note
This function is asynchronous.
Note
This function is an helper function calling spi_transceive_async.
Note
This function is available only if :kconfig:`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.
rx_bufs – Buffer array where data to be read will be written to.
async – A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).
- Returns
0 – If successful
-errno – Negative errno code on failure.
-
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 *async)¶ Write the specified amount of data from the SPI driver.
Note
This function is asynchronous.
Note
This function is an helper function calling spi_transceive_async.
Note
This function is available only if :kconfig:`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.
async – A pointer to a valid and ready to be signaled struct k_poll_signal. (Note: if NULL this function will not notify the end of the transaction, and whether it went successfully or not).
- Returns
0 – If successful.
-errno – Negative errno code on failure.
-
int
spi_release
(const struct device *dev, const struct spi_config *config)¶ Release the SPI device locked on by the current config.
Note: This synchronous function is used to release the lock on the SPI device 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 into its operation bits field. This can be used if the caller needs to keep its hand on the SPI device for consecutive transactions.
- 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.
- Returns
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.
- Parameters
gpio_dev – is a valid pointer to an actual GPIO device. A NULL pointer can be provided to full inhibit CS control if necessary.
gpio_pin – is a number representing the gpio PIN that will be used to act as a CS line
delay – is a delay in microseconds to wait before starting the transmission and before releasing the CS line
gpio_dt_flags – is the devicetree flags corresponding to how the CS line should be driven. GPIO_ACTIVE_LOW/GPIO_ACTIVE_HIGH should be equivalent to SPI_CS_ACTIVE_HIGH/SPI_CS_ACTIVE_LOW options in struct spi_config.
-
struct
spi_config
¶ - #include <spi.h>
SPI controller configuration structure.
Note
Only cs_hold and lock_on can be changed between consecutive transceive call. Rest of the attributes are not meant to be tweaked.
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.
- Parameters
frequency – is the bus frequency in Hertz
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. lines [ 11 : 12 ] - MISO lines: Single/Dual/Quad/Octal. cs_hold [ 13 ] - Hold on the CS line if possible. lock_on [ 14 ] - Keep resource locked for the caller. cs_active_high [ 15 ] - Active high CS logic.
slave – is the slave number from 0 to host controller slave limit.
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.
- Parameters
bus – is the SPI bus
config – is the slave specific configuration
-
struct
spi_buf
¶ - #include <spi.h>
SPI buffer structure.
- Parameters
buf – is a valid pointer on a data buffer, or NULL otherwise.
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.
- Parameters
buffers – is a valid pointer on an array of spi_buf, or NULL.
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.
-