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

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

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 Value
  • 0: If successful, negative errno code otherwise. In case of slave transaction: if successful it will return the amount of frames received, negative errno code otherwise.

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 Value
  • 0: If successful, negative errno code otherwise.

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 Value
  • 0: If successful, negative errno code otherwise.

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.

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

Return Value
  • 0: If successful, negative errno code otherwise. In case of slave transaction: if successful it will return the amount of frames received, negative errno code otherwise.

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.

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

Return Value
  • 0: If successful, negative errno code otherwise.

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.

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

Return Value
  • 0: If successful, negative errno code otherwise.

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.

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_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.