Zephyr API Documentation
2.7.0-rc2
A Scalable Open Source RTOS
|
SPI Interface. More...
Data Structures | |
struct | spi_cs_control |
SPI Chip Select control structure. More... | |
struct | spi_config |
SPI controller configuration structure. More... | |
struct | spi_dt_spec |
Complete SPI DT information. More... | |
struct | spi_buf |
SPI buffer structure. More... | |
struct | spi_buf_set |
SPI buffer array structure. More... | |
struct | spi_driver_api |
SPI driver API This is the mandatory API any SPI driver needs to expose. More... | |
Macros | |
#define | SPI_OP_MODE_MASTER 0 |
SPI operational mode. More... | |
#define | SPI_OP_MODE_SLAVE BIT(0) |
#define | SPI_OP_MODE_MASK 0x1 |
#define | SPI_OP_MODE_GET(_operation_) ((_operation_) & SPI_OP_MODE_MASK) |
#define | SPI_MODE_CPOL BIT(1) |
SPI Polarity & Phase Modes. More... | |
#define | SPI_MODE_CPHA BIT(2) |
#define | SPI_MODE_LOOP BIT(3) |
#define | SPI_MODE_MASK (0xE) |
#define | SPI_MODE_GET(_mode_) ((_mode_) & SPI_MODE_MASK) |
#define | SPI_TRANSFER_MSB (0) |
SPI Transfer modes (host controller dependent) More... | |
#define | SPI_TRANSFER_LSB BIT(4) |
#define | SPI_WORD_SIZE_SHIFT (5) |
SPI word size. More... | |
#define | SPI_WORD_SIZE_MASK (0x3F << 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_LINES_SINGLE (0 << 11) |
SPI MISO lines. More... | |
#define | SPI_LINES_DUAL (1 << 11) |
#define | SPI_LINES_QUAD (2 << 11) |
#define | SPI_LINES_OCTAL (3 << 11) |
#define | SPI_LINES_MASK (0x3 << 11) |
#define | SPI_HOLD_ON_CS BIT(13) |
Specific SPI devices control bits. More... | |
#define | SPI_LOCK_ON BIT(14) |
#define | SPI_CS_ACTIVE_HIGH BIT(15) |
#define | SPI_CS_CONTROL_PTR_DT(node_id, delay_) |
Initialize and get a pointer to a spi_cs_control from a devicetree node identifier. More... | |
#define | SPI_CS_CONTROL_PTR_DT_INST(inst, delay_) SPI_CS_CONTROL_PTR_DT(DT_DRV_INST(inst), delay_) |
Get a pointer to a spi_cs_control from a devicetree node. More... | |
#define | SPI_CONFIG_DT(node_id, operation_, delay_) |
Structure initializer for spi_config from devicetree. More... | |
#define | SPI_CONFIG_DT_INST(inst, operation_, delay_) SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_) |
Structure initializer for spi_config from devicetree instance. More... | |
#define | SPI_DT_SPEC_GET(node_id, operation_, delay_) |
Structure initializer for spi_dt_spec from devicetree. More... | |
#define | SPI_DT_SPEC_INST_GET(inst, operation_, delay_) SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_) |
Structure initializer for spi_dt_spec from devicetree instance. More... | |
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. More... | |
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. More... | |
Functions | |
static bool | spi_is_ready (const struct spi_dt_spec *spec) |
Validate that SPI bus is ready. More... | |
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. More... | |
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 . More... | |
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. More... | |
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 . More... | |
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. More... | |
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 . More... | |
static 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. More... | |
static 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. More... | |
static 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. More... | |
int | spi_release (const struct device *dev, const struct spi_config *config) |
Release the SPI device locked on by the current config. More... | |
static int | spi_release_dt (const struct spi_dt_spec *spec) |
Release the SPI device specified in spi_dt_spec . More... | |
SPI Interface.
#define SPI_CONFIG_DT | ( | node_id, | |
operation_, | |||
delay_ | |||
) |
#include <include/drivers/spi.h>
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++.
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 |
#define SPI_CONFIG_DT_INST | ( | inst, | |
operation_, | |||
delay_ | |||
) | SPI_CONFIG_DT(DT_DRV_INST(inst), operation_, delay_) |
#include <include/drivers/spi.h>
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++.
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 |
#define SPI_CS_ACTIVE_HIGH BIT(15) |
#include <include/drivers/spi.h>
#define SPI_CS_CONTROL_PTR_DT | ( | node_id, | |
delay_ | |||
) |
#include <include/drivers/spi.h>
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++.
node_id | Devicetree node identifier for a device on a SPI bus |
delay_ | The delay field to set in the spi_cs_control |
spi_cs_control
structure #define SPI_CS_CONTROL_PTR_DT_INST | ( | inst, | |
delay_ | |||
) | SPI_CS_CONTROL_PTR_DT(DT_DRV_INST(inst), delay_) |
#include <include/drivers/spi.h>
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++.
inst | Devicetree node instance number |
delay_ | The delay field to set in the spi_cs_control |
spi_cs_control
structure #define SPI_DT_SPEC_GET | ( | node_id, | |
operation_, | |||
delay_ | |||
) |
#include <include/drivers/spi.h>
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++.
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 |
#define SPI_DT_SPEC_INST_GET | ( | inst, | |
operation_, | |||
delay_ | |||
) | SPI_DT_SPEC_GET(DT_DRV_INST(inst), operation_, delay_) |
#include <include/drivers/spi.h>
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++.
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 |
#define SPI_HOLD_ON_CS BIT(13) |
#include <include/drivers/spi.h>
Specific SPI devices control bits.
#define SPI_LINES_DUAL (1 << 11) |
#include <include/drivers/spi.h>
#define SPI_LINES_MASK (0x3 << 11) |
#include <include/drivers/spi.h>
#define SPI_LINES_OCTAL (3 << 11) |
#include <include/drivers/spi.h>
#define SPI_LINES_QUAD (2 << 11) |
#include <include/drivers/spi.h>
#define SPI_LINES_SINGLE (0 << 11) |
#include <include/drivers/spi.h>
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.
#define SPI_LOCK_ON BIT(14) |
#include <include/drivers/spi.h>
#define SPI_MODE_CPHA BIT(2) |
#include <include/drivers/spi.h>
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.
#define SPI_MODE_CPOL BIT(1) |
#include <include/drivers/spi.h>
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.
#define SPI_MODE_GET | ( | _mode_ | ) | ((_mode_) & SPI_MODE_MASK) |
#include <include/drivers/spi.h>
#define SPI_MODE_LOOP BIT(3) |
#include <include/drivers/spi.h>
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.
#define SPI_MODE_MASK (0xE) |
#include <include/drivers/spi.h>
#define SPI_OP_MODE_GET | ( | _operation_ | ) | ((_operation_) & SPI_OP_MODE_MASK) |
#include <include/drivers/spi.h>
#define SPI_OP_MODE_MASK 0x1 |
#include <include/drivers/spi.h>
#define SPI_OP_MODE_MASTER 0 |
#include <include/drivers/spi.h>
SPI operational mode.
#define SPI_OP_MODE_SLAVE BIT(0) |
#include <include/drivers/spi.h>
#define SPI_TRANSFER_LSB BIT(4) |
#include <include/drivers/spi.h>
#define SPI_TRANSFER_MSB (0) |
#include <include/drivers/spi.h>
SPI Transfer modes (host controller dependent)
#define SPI_WORD_SET | ( | _word_size_ | ) | ((_word_size_) << SPI_WORD_SIZE_SHIFT) |
#include <include/drivers/spi.h>
#define SPI_WORD_SIZE_GET | ( | _operation_ | ) | (((_operation_) & SPI_WORD_SIZE_MASK) >> SPI_WORD_SIZE_SHIFT) |
#include <include/drivers/spi.h>
#define SPI_WORD_SIZE_MASK (0x3F << SPI_WORD_SIZE_SHIFT) |
#include <include/drivers/spi.h>
#define SPI_WORD_SIZE_SHIFT (5) |
#include <include/drivers/spi.h>
SPI word size.
spi_api_io |
#include <include/drivers/spi.h>
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) |
#include <include/drivers/spi.h>
spi_api_release |
#include <include/drivers/spi.h>
Callback API for unlocking SPI device. See spi_release() for argument descriptions.
|
inlinestatic |
#include <include/drivers/spi.h>
Validate that SPI bus is ready.
spec | SPI specification from devicetree |
true | if the SPI bus is ready for use. |
false | if the SPI bus is not ready for use. |
|
inlinestatic |
#include <include/drivers/spi.h>
Read the specified amount of data from the SPI driver.
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. |
0 | If successful. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Read the specified amount of data from the SPI driver.
embed:rst:inline :kconfig:`CONFIG_SPI_ASYNC`is selected.
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). |
0 | If successful |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Read data from a SPI bus specified in spi_dt_spec
.
This is equivalent to:
spi_read(spec->bus, &spec->config, rx_bufs);
spec | SPI specification from devicetree |
rx_bufs | Buffer array where data to be read will be written to. |
int spi_release | ( | const struct device * | dev, |
const struct spi_config * | config | ||
) |
#include <include/drivers/spi.h>
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.
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. |
0 | If successful. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Release the SPI device specified in spi_dt_spec
.
This is equivalent to:
spi_release(spec->bus, &spec->config);
spec | SPI specification from devicetree |
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 | ||
) |
#include <include/drivers/spi.h>
Read/write the specified amount of data from the SPI driver.
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. |
frames | Positive number of frames received in slave mode. |
0 | If successful in master mode. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Read/write the specified amount of data from the SPI driver.
embed:rst:inline :kconfig:`CONFIG_SPI_ASYNC`is selected.
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). |
frames | Positive number of frames received in slave mode. |
0 | If successful in master mode. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
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);
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. |
|
inlinestatic |
#include <include/drivers/spi.h>
Write the specified amount of data from the SPI driver.
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. |
0 | If successful. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Write the specified amount of data from the SPI driver.
embed:rst:inline :kconfig:`CONFIG_SPI_ASYNC`is selected.
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). |
0 | If successful. |
-errno | Negative errno code on failure. |
|
inlinestatic |
#include <include/drivers/spi.h>
Write data to a SPI bus specified in spi_dt_spec
.
This is equivalent to:
spi_write(spec->bus, &spec->config, tx_bufs);
spec | SPI specification from devicetree |
tx_bufs | Buffer array where data to be sent originates from. |