VSF Documented
Data Structures | Macros | Typedefs | Enumerations | Functions
spi_master.h File Reference
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"

Go to the source code of this file.

Data Structures

struct  spi_bus_config_t
 Bus-wide configuration. More...
 
struct  spi_device_interface_config_t
 Per-device configuration. More...
 
struct  spi_transaction_t
 One SPI transaction descriptor. More...
 
struct  spi_transaction_ext_t
 Extended transaction with per-transfer bit widths. More...
 

Macros

#define SPI_MASTER_FREQ_8M   (8 * 1000 * 1000)
 
#define SPI_MASTER_FREQ_10M   (10 * 1000 * 1000)
 
#define SPI_MASTER_FREQ_16M   (16 * 1000 * 1000)
 
#define SPI_MASTER_FREQ_20M   (20 * 1000 * 1000)
 
#define SPI_MASTER_FREQ_26M   (80 * 1000 * 1000 / 3)
 
#define SPI_MASTER_FREQ_40M   (40 * 1000 * 1000)
 
#define SPI_MASTER_FREQ_80M   (80 * 1000 * 1000)
 
#define SPI_DEVICE_TXBIT_LSBFIRST   (1U << 0)
 
#define SPI_DEVICE_RXBIT_LSBFIRST   (1U << 1)
 
#define SPI_DEVICE_BIT_LSBFIRST   (SPI_DEVICE_TXBIT_LSBFIRST | SPI_DEVICE_RXBIT_LSBFIRST)
 
#define SPI_DEVICE_3WIRE   (1U << 2)
 
#define SPI_DEVICE_POSITIVE_CS   (1U << 3)
 
#define SPI_DEVICE_HALFDUPLEX   (1U << 4)
 
#define SPI_DEVICE_CLK_AS_CS   (1U << 5)
 
#define SPI_DEVICE_NO_DUMMY   (1U << 6)
 
#define SPI_DEVICE_DDRCLK   (1U << 7)
 
#define SPI_DEVICE_NO_RETURN_RESULT   (1U << 8)
 
#define SPI_TRANS_MODE_DIO   (1U << 0)
 
#define SPI_TRANS_MODE_QIO   (1U << 1)
 
#define SPI_TRANS_USE_RXDATA   (1U << 2)
 
#define SPI_TRANS_USE_TXDATA   (1U << 3)
 
#define SPI_TRANS_MODE_DIOQIO_ADDR   (1U << 4)
 
#define SPI_TRANS_VARIABLE_CMD   (1U << 5)
 
#define SPI_TRANS_VARIABLE_ADDR   (1U << 6)
 
#define SPI_TRANS_VARIABLE_DUMMY   (1U << 7)
 
#define SPI_TRANS_CS_KEEP_ACTIVE   (1U << 8)
 
#define SPI_TRANS_MULTILINE_CMD   (1U << 9)
 
#define SPI_TRANS_MODE_OCT   (1U << 10)
 
#define SPI_TRANS_MULTILINE_ADDR   SPI_TRANS_MODE_DIOQIO_ADDR
 
#define SPICOMMON_BUSFLAG_SLAVE   (1U << 0)
 
#define SPICOMMON_BUSFLAG_MASTER   (1U << 1)
 
#define SPICOMMON_BUSFLAG_IOMUX_PINS   (1U << 2)
 
#define SPICOMMON_BUSFLAG_GPIO_PINS   (1U << 3)
 
#define SPICOMMON_BUSFLAG_SCLK   (1U << 4)
 
#define SPICOMMON_BUSFLAG_MISO   (1U << 5)
 
#define SPICOMMON_BUSFLAG_MOSI   (1U << 6)
 
#define SPICOMMON_BUSFLAG_DUAL   (1U << 7)
 
#define SPICOMMON_BUSFLAG_WPHD   (1U << 8)
 
#define SPICOMMON_BUSFLAG_QUAD   (SPICOMMON_BUSFLAG_DUAL | SPICOMMON_BUSFLAG_WPHD)
 
#define SPICOMMON_BUSFLAG_IO4_IO7   (1U << 9)
 
#define SPICOMMON_BUSFLAG_OCTAL   (SPICOMMON_BUSFLAG_QUAD | SPICOMMON_BUSFLAG_IO4_IO7)
 
#define SPICOMMON_BUSFLAG_NATIVE_PINS   SPICOMMON_BUSFLAG_IOMUX_PINS
 
#define SPI_DMA_CH_AUTO   SPI_DMA_CH_AUTO
 
#define SPI_CLK_SRC_DEFAULT   0
 
#define SPI_SAMPLING_POINT_PHASE_0   0
 

Typedefs

typedef int spi_clock_source_t
 
typedef int spi_sampling_point_t
 
typedef struct spi_device_t * spi_device_handle_t
 
typedef void(* transaction_cb_t) (struct spi_transaction_t *trans)
 
typedef struct spi_transaction_t spi_transaction_t
 One SPI transaction descriptor.
 

Enumerations

enum  spi_common_dma_t {
  SPI_DMA_DISABLED = 0 ,
  SPI_DMA_CH1 = 1 ,
  SPI_DMA_CH2 = 2 ,
  SPI_DMA_CH_AUTO = 3
}
 
enum  spi_host_device_t {
  SPI1_HOST = 0 ,
  SPI2_HOST = 1 ,
  SPI3_HOST = 2 ,
  SPI_HOST_MAX
}
 SPI host controller enumeration. More...
 

Functions

esp_err_t spi_bus_initialize (spi_host_device_t host_id, const spi_bus_config_t *bus_config, spi_common_dma_t dma_chan)
 Initialise an SPI bus.
 
esp_err_t spi_bus_free (spi_host_device_t host_id)
 Release an SPI bus.
 
esp_err_t spi_bus_add_device (spi_host_device_t host_id, const spi_device_interface_config_t *dev_config, spi_device_handle_t *handle)
 Attach a device to an initialised bus.
 
esp_err_t spi_bus_remove_device (spi_device_handle_t handle)
 Detach a device from its bus.
 
esp_err_t spi_device_queue_trans (spi_device_handle_t handle, spi_transaction_t *trans_desc, uint32_t ticks_to_wait)
 Queue a transaction for later completion.
 
esp_err_t spi_device_get_trans_result (spi_device_handle_t handle, spi_transaction_t **trans_desc, uint32_t ticks_to_wait)
 Retrieve a previously queued transaction.
 
esp_err_t spi_device_transmit (spi_device_handle_t handle, spi_transaction_t *trans_desc)
 Blocking, interrupt-backed transaction.
 
esp_err_t spi_device_polling_transmit (spi_device_handle_t handle, spi_transaction_t *trans_desc)
 Blocking polling transaction (shim: same as spi_device_transmit).
 
esp_err_t spi_device_polling_start (spi_device_handle_t handle, spi_transaction_t *trans_desc, uint32_t ticks_to_wait)
 Start a polling transaction without blocking.
 
esp_err_t spi_device_polling_end (spi_device_handle_t handle, uint32_t ticks_to_wait)
 Wait for a previously started polling transaction.
 
esp_err_t spi_device_acquire_bus (spi_device_handle_t device, uint32_t wait)
 Acquire the bus for a series of back-to-back transactions.
 
void spi_device_release_bus (spi_device_handle_t dev)
 Release a previously acquired bus.
 
esp_err_t spi_device_get_actual_freq (spi_device_handle_t handle, int *freq_khz)
 Return the actual clock frequency used for a device.
 

Macro Definition Documentation

◆ SPI_MASTER_FREQ_8M

#define SPI_MASTER_FREQ_8M   (8 * 1000 * 1000)

◆ SPI_MASTER_FREQ_10M

#define SPI_MASTER_FREQ_10M   (10 * 1000 * 1000)

◆ SPI_MASTER_FREQ_16M

#define SPI_MASTER_FREQ_16M   (16 * 1000 * 1000)

◆ SPI_MASTER_FREQ_20M

#define SPI_MASTER_FREQ_20M   (20 * 1000 * 1000)

◆ SPI_MASTER_FREQ_26M

#define SPI_MASTER_FREQ_26M   (80 * 1000 * 1000 / 3)

◆ SPI_MASTER_FREQ_40M

#define SPI_MASTER_FREQ_40M   (40 * 1000 * 1000)

◆ SPI_MASTER_FREQ_80M

#define SPI_MASTER_FREQ_80M   (80 * 1000 * 1000)

◆ SPI_DEVICE_TXBIT_LSBFIRST

#define SPI_DEVICE_TXBIT_LSBFIRST   (1U << 0)

◆ SPI_DEVICE_RXBIT_LSBFIRST

#define SPI_DEVICE_RXBIT_LSBFIRST   (1U << 1)

◆ SPI_DEVICE_BIT_LSBFIRST

#define SPI_DEVICE_BIT_LSBFIRST   (SPI_DEVICE_TXBIT_LSBFIRST | SPI_DEVICE_RXBIT_LSBFIRST)

◆ SPI_DEVICE_3WIRE

#define SPI_DEVICE_3WIRE   (1U << 2)

◆ SPI_DEVICE_POSITIVE_CS

#define SPI_DEVICE_POSITIVE_CS   (1U << 3)

◆ SPI_DEVICE_HALFDUPLEX

#define SPI_DEVICE_HALFDUPLEX   (1U << 4)

◆ SPI_DEVICE_CLK_AS_CS

#define SPI_DEVICE_CLK_AS_CS   (1U << 5)

◆ SPI_DEVICE_NO_DUMMY

#define SPI_DEVICE_NO_DUMMY   (1U << 6)

◆ SPI_DEVICE_DDRCLK

#define SPI_DEVICE_DDRCLK   (1U << 7)

◆ SPI_DEVICE_NO_RETURN_RESULT

#define SPI_DEVICE_NO_RETURN_RESULT   (1U << 8)

◆ SPI_TRANS_MODE_DIO

#define SPI_TRANS_MODE_DIO   (1U << 0)

◆ SPI_TRANS_MODE_QIO

#define SPI_TRANS_MODE_QIO   (1U << 1)

◆ SPI_TRANS_USE_RXDATA

#define SPI_TRANS_USE_RXDATA   (1U << 2)

◆ SPI_TRANS_USE_TXDATA

#define SPI_TRANS_USE_TXDATA   (1U << 3)

◆ SPI_TRANS_MODE_DIOQIO_ADDR

#define SPI_TRANS_MODE_DIOQIO_ADDR   (1U << 4)

◆ SPI_TRANS_VARIABLE_CMD

#define SPI_TRANS_VARIABLE_CMD   (1U << 5)

◆ SPI_TRANS_VARIABLE_ADDR

#define SPI_TRANS_VARIABLE_ADDR   (1U << 6)

◆ SPI_TRANS_VARIABLE_DUMMY

#define SPI_TRANS_VARIABLE_DUMMY   (1U << 7)

◆ SPI_TRANS_CS_KEEP_ACTIVE

#define SPI_TRANS_CS_KEEP_ACTIVE   (1U << 8)

◆ SPI_TRANS_MULTILINE_CMD

#define SPI_TRANS_MULTILINE_CMD   (1U << 9)

◆ SPI_TRANS_MODE_OCT

#define SPI_TRANS_MODE_OCT   (1U << 10)

◆ SPI_TRANS_MULTILINE_ADDR

#define SPI_TRANS_MULTILINE_ADDR   SPI_TRANS_MODE_DIOQIO_ADDR

◆ SPICOMMON_BUSFLAG_SLAVE

#define SPICOMMON_BUSFLAG_SLAVE   (1U << 0)

◆ SPICOMMON_BUSFLAG_MASTER

#define SPICOMMON_BUSFLAG_MASTER   (1U << 1)

◆ SPICOMMON_BUSFLAG_IOMUX_PINS

#define SPICOMMON_BUSFLAG_IOMUX_PINS   (1U << 2)

◆ SPICOMMON_BUSFLAG_GPIO_PINS

#define SPICOMMON_BUSFLAG_GPIO_PINS   (1U << 3)

◆ SPICOMMON_BUSFLAG_SCLK

#define SPICOMMON_BUSFLAG_SCLK   (1U << 4)

◆ SPICOMMON_BUSFLAG_MISO

#define SPICOMMON_BUSFLAG_MISO   (1U << 5)

◆ SPICOMMON_BUSFLAG_MOSI

#define SPICOMMON_BUSFLAG_MOSI   (1U << 6)

◆ SPICOMMON_BUSFLAG_DUAL

#define SPICOMMON_BUSFLAG_DUAL   (1U << 7)

◆ SPICOMMON_BUSFLAG_WPHD

#define SPICOMMON_BUSFLAG_WPHD   (1U << 8)

◆ SPICOMMON_BUSFLAG_QUAD

#define SPICOMMON_BUSFLAG_QUAD   (SPICOMMON_BUSFLAG_DUAL | SPICOMMON_BUSFLAG_WPHD)

◆ SPICOMMON_BUSFLAG_IO4_IO7

#define SPICOMMON_BUSFLAG_IO4_IO7   (1U << 9)

◆ SPICOMMON_BUSFLAG_OCTAL

#define SPICOMMON_BUSFLAG_OCTAL   (SPICOMMON_BUSFLAG_QUAD | SPICOMMON_BUSFLAG_IO4_IO7)

◆ SPICOMMON_BUSFLAG_NATIVE_PINS

#define SPICOMMON_BUSFLAG_NATIVE_PINS   SPICOMMON_BUSFLAG_IOMUX_PINS

◆ SPI_DMA_CH_AUTO

#define SPI_DMA_CH_AUTO   SPI_DMA_CH_AUTO

◆ SPI_CLK_SRC_DEFAULT

#define SPI_CLK_SRC_DEFAULT   0

◆ SPI_SAMPLING_POINT_PHASE_0

#define SPI_SAMPLING_POINT_PHASE_0   0

Typedef Documentation

◆ spi_clock_source_t

typedef int spi_clock_source_t

◆ spi_sampling_point_t

typedef int spi_sampling_point_t

◆ spi_device_handle_t

typedef struct spi_device_t* spi_device_handle_t

◆ transaction_cb_t

typedef void(* transaction_cb_t) (struct spi_transaction_t *trans)

◆ spi_transaction_t

typedef struct spi_transaction_t spi_transaction_t

One SPI transaction descriptor.

The descriptor must remain valid until the transaction completes (spi_device_transmit returns, or spi_device_get_trans_result hands the pointer back to the caller).

Enumeration Type Documentation

◆ spi_common_dma_t

enum spi_common_dma_t
Enumerator
SPI_DMA_DISABLED 
SPI_DMA_CH1 
SPI_DMA_CH2 
SPI_DMA_CH_AUTO 

◆ spi_host_device_t

enum spi_host_device_t

SPI host controller enumeration.

Values map directly into the user-supplied pool index (vsf_espidf_cfg_t::spi.pool[spi_host_device_t]).

Enumerator
SPI1_HOST 
SPI2_HOST 
SPI3_HOST 
SPI_HOST_MAX 

Function Documentation

◆ spi_bus_initialize()

esp_err_t spi_bus_initialize ( spi_host_device_t  host_id,
const spi_bus_config_t *  bus_config,
spi_common_dma_t  dma_chan 
)
extern

Initialise an SPI bus.

Parameters
[in]host_idSPI host (index into the injected vsf_spi_t pool).
[in]bus_configBus configuration (pin fields ignored).
[in]dma_chanDMA channel hint (accepted, ignored).
Returns
ESP_OK / ESP_ERR_INVALID_ARG / ESP_ERR_NOT_FOUND / ESP_ERR_INVALID_STATE (already initialised).

◆ spi_bus_free()

esp_err_t spi_bus_free ( spi_host_device_t  host_id)
extern

Release an SPI bus.

All devices attached to the host must be removed first.

◆ spi_bus_add_device()

esp_err_t spi_bus_add_device ( spi_host_device_t  host_id,
const spi_device_interface_config_t *  dev_config,
spi_device_handle_t *  handle 
)
extern

Attach a device to an initialised bus.

◆ spi_bus_remove_device()

esp_err_t spi_bus_remove_device ( spi_device_handle_t  handle)
extern

Detach a device from its bus.

◆ spi_device_queue_trans()

esp_err_t spi_device_queue_trans ( spi_device_handle_t  handle,
spi_transaction_t *  trans_desc,
uint32_t  ticks_to_wait 
)
extern

Queue a transaction for later completion.

This port executes queued transactions inline (synchronously). The ticks_to_wait parameter bounds the bus-lock wait; once the bus is held the transfer runs to completion and a matching spi_device_get_trans_result() call will return the same pointer immediately.

◆ spi_device_get_trans_result()

esp_err_t spi_device_get_trans_result ( spi_device_handle_t  handle,
spi_transaction_t **  trans_desc,
uint32_t  ticks_to_wait 
)
extern

Retrieve a previously queued transaction.

◆ spi_device_transmit()

esp_err_t spi_device_transmit ( spi_device_handle_t  handle,
spi_transaction_t *  trans_desc 
)
extern

Blocking, interrupt-backed transaction.

◆ spi_device_polling_transmit()

esp_err_t spi_device_polling_transmit ( spi_device_handle_t  handle,
spi_transaction_t *  trans_desc 
)
extern

Blocking polling transaction (shim: same as spi_device_transmit).

◆ spi_device_polling_start()

esp_err_t spi_device_polling_start ( spi_device_handle_t  handle,
spi_transaction_t *  trans_desc,
uint32_t  ticks_to_wait 
)
extern

Start a polling transaction without blocking.

Must be matched by exactly one spi_device_polling_end() call.

◆ spi_device_polling_end()

esp_err_t spi_device_polling_end ( spi_device_handle_t  handle,
uint32_t  ticks_to_wait 
)
extern

Wait for a previously started polling transaction.

◆ spi_device_acquire_bus()

esp_err_t spi_device_acquire_bus ( spi_device_handle_t  device,
uint32_t  wait 
)
extern

Acquire the bus for a series of back-to-back transactions.

While the bus is acquired by one device, other devices sharing the same host will block inside spi_device_transmit() / queue_trans.

◆ spi_device_release_bus()

void spi_device_release_bus ( spi_device_handle_t  dev)
extern

Release a previously acquired bus.

◆ spi_device_get_actual_freq()

esp_err_t spi_device_get_actual_freq ( spi_device_handle_t  handle,
int *  freq_khz 
)
extern

Return the actual clock frequency used for a device.

This port returns dev->clock_speed_hz rounded through the HAL's granularity (typically the configured value).

Generated from commit: vsfteam/vsf@015f4d1