# SPI 从机驱动程序

[English]

SPI 从机驱动程序控制在 ESP32-H4 中作为从机的 GP-SPI 外设。

有关 GP-SPI 硬件相关信息，请参考 ESP32-H4 技术参考手册 > SPI 控制器 [PDF]。

## 术语

下表为 SPI 从机驱动的相关术语。

术语 | 定义
--- | ---
主机 (Host) | ESP32-H4 外部的 SPI 控制器外设。用作 SPI 主机，在总线上发起 SPI 传输。
从机设备 (Device) | SPI 从机设备（通用 SPI 控制器）。每个从机设备共享 MOSI、MISO 和 SCLK 信号，但只有当主机向从机设备的专属 CS 线发出信号时，从机设备才会在总线上处于激活状态。
总线 (Bus) | 信号总线，由连接到同一主机的所有从机设备共用。一般来说，一条总线包括以下线路：MISO、MOSI、SCLK、一条或多条 CS 线，以及可选的 QUADWP 和 QUADHD。每个从机设备都有单独的 CS 线，除此之外，所有从机设备都连接在相同的线路下。如果以菊花链的方式连接，几个从机设备也可以共享一条 CS 线。
MISO | 主机输入，从机输出，也写作 Q。数据从从机设备发送至主机。
MOSI | 主机输出，从机输入，也写作 D。数据从主机发送至从机设备。
SCLK | 串行时钟。由主机产生的振荡信号，使数据位的传输保持同步。
CS | 片选。允许主机选择连接到总线上的单个从机设备，以便发送或接收数据。
QUADWP | 写保护信号。只用于 4 位 (qio/qout) 传输。
QUADHD | 保持信号。只用于 4 位 (qio/qout) 传输。
断言 (Assertion) | 指激活一条线的操作。反之，将线路恢复到非活动状态（回到空闲状态）的操作则称为 去断言。
传输事务 (Transaction) | 即主机断言从机设备的 CS 线，向从机设备传输数据，接着去断言 CS 线的过程。传输事务为原子操作，不可打断。
发射沿 (Launch Edge) | 源寄存器将信号 发射 到线路上的时钟边沿。
锁存沿 (Latch Edge) | 目的寄存器 锁存 信号的时钟边沿。

## 驱动程序的功能

SPI 从机驱动程序允许将 SPI 外设作为全双工设备使用。驱动程序可以发送/接收长度不超过 64 字节的传输事务，或者利用 DMA 来发送/接收更长的传输事务。然而，存在一些与 DMA 有关的 已知问题。

SPI 从机驱动程序支持将 SPI ISR 注册至指定 CPU 内核。如果多个任务同时尝试访问一个 SPI 设备，建议重构应用程序，以使每个 SPI 外设一次只由一个任务访问。此外，请使用 `spi_bus_config_t::isr_cpu_id` 将 SPI ISR 注册至与 SPI 外设相关任务相同的内核，确保线程安全。

### 睡眠保留

ESP32-H4 支持在进入 Light Sleep 之前保留 SPI 寄存器中的内容，并在唤醒后恢复。即程序不需要在 Light Sleep 唤醒后重新配置 SPI。

该特性可以通过置位配置中的 `SPICOMMON_BUSFLAG_SLP_ALLOW_PD` 标志位启用。启用后驱动允许系统在 Light Sleep 时对 SPI 掉电，同时保存寄存器配置。它可以帮助降低轻度睡眠时的功耗，但需要花费一些额外的存储来保存寄存器的配置。

注意在 Slave 角色下，不支持在所有传输（发送和接收）未完成时进入睡眠，否则将会出错。

## SPI 传输事务

主机断言 CS 线并在 SCLK 线上发出时钟脉冲时，一次全双工 SPI 传输事务就此开始。每个时钟脉冲都意味着通过 MOSI 线从主机转移一个数据位到从机设备上，并同时通过 MISO 线返回一个数据位。传输事务结束后，主机去断言 CS 线。

传输事务的属性由作为从机设备的 SPI 外设的配置结构体 `spi_slave_interface_config_t` 和传输事务配置结构体 `spi_slave_transaction_t` 决定。

由于并非每次传输事务都需要写入和读取数据，可以选择配置 `spi_transaction_t` 为仅 TX、仅 RX 或同时 TX 和 RX 传输事务。如果将 `spi_slave_transaction_t::rx_buffer` 设置为 `NULL`，读取阶段将被跳过。与之类似，如果将 `spi_slave_transaction_t::tx_buffer` 设置为 `NULL`，则写入阶段将被跳过。

备注

主机应在从机设备准备好接收数据之后再进行传输事务。建议使用另外一个 GPIO 管脚作为握手信号来同步设备。更多细节，请参阅 传输事务间隔。

### 使用 PSRAM 的传输

SPI Slave 驱动程序支持使用 PSRAM 进行传输。直接传入 PSRAM 地址作为 `spi_slave_transaction_t::tx_buffer` 或 `spi_slave_transaction_t::rx_buffer` 即可。对于 rx_buffer ，其地址和传输长度有对齐要求，使用 `heap_caps_malloc()` 分配内存可以自动处理对齐要求。对于不能控制的内存，也可以使用 `SPI_SLAVE_TRANS_DMA_BUFFER_ALIGN_AUTO` 标志位，驱动会自动从 PSRAM 重新分配满足要求的内存。

请注意该功能共享 MSPI 总线带宽（总线频率 * 总线位宽），因此主机对该设备的传输带宽应小于 PSRAM 带宽，否则 可能会丢失传输数据，此时 `spi_slave_transmit` 函数将会返回 `ESP_ERR_INVALID_STATE` 错误。

## 使用驱动程序

- 调用函数 `spi_slave_initialize()`，将 SPI 外设初始化为从机设备。请确保在 bus_config 中设置正确的 I/O 管脚，并将未使用的信号设置为 `-1`。

- 传输事务开始前，需用要求的事务参数填充一个或多个 `spi_slave_transaction_t` 结构体。可以通过调用函数 `spi_slave_queue_trans()` 来将所有传输事务排进队列，并在稍后使用函数 `spi_slave_get_trans_result()` 查询结果；也可以将所有请求输入 `spi_slave_transmit()` 中单独处理。后两个函数将阻塞，直到主机发起并完成传输事务，以便发送并接收队列中的数据，或直到 `ticks_to_wait` 超时。

- （可选）启用/禁用驱动程序功能：从机驱动程序支持在程序初始化后通过调用 `spi_slave_disable()` / `spi_slave_enable()` 来禁用/启用驱动程序，以便能够更改时钟或电源配置或休眠以节省电量。默认情况下，驱动程序在初始化后为“启用”状态。

- （可选）如需卸载 SPI 从机驱动程序，请调用 `spi_slave_free()`。

## 传输事务数据和主/从机长度不匹配

通常，通过从机设备进行传输的数据会被读取或写入到由 `spi_slave_transaction_t::rx_buffer` 和 `spi_slave_transaction_t::tx_buffer` 指示的大块内存中。可以配置 SPI 驱动程序，使用 DMA 进行传输。在这种情况下，则必须使用 `pvPortMallocCaps(size, MALLOC_CAP_DMA)` 将缓存区分配到具备 DMA 功能的内存中。

驱动程序可以读取或写入缓存区的数据量取决于 `spi_slave_transaction_t::length`，但其并不会定义一次 SPI 传输的实际长度。传输事务的长度由主机的时钟线和 CS 线决定，且只有在传输事务完成后，才能从 `spi_slave_transaction_t::trans_len` 中读取实际长度。

如果传输长度超过缓存区长度，则只有在 `spi_slave_transaction_t::length` 中指定的初始比特数会被发送和接收。此时， `spi_slave_transaction_t::trans_len` 被设置为 `spi_slave_transaction_t::length` 而非实际传输事务长度。若需满足实际传输事务长度的要求，请将 `spi_slave_transaction_t::length` 设置为大于 `spi_slave_transaction_t::trans_len` 预期最大值的值。如果传输长度短于缓存区长度，则只传输与缓存区长度相等的数据。

当需要在一次传输中单独指定不同的 TX/RX 长度时，可以使用 `spi_slave_transaction_t::tx_length` 和 `spi_slave_transaction_t::rx_length` 来分别指定 TX 和 RX 的长度。该配置和 `spi_slave_transaction_t::length` 互斥，不可同时使用。

## GPIO 交换矩阵和 IO_MUX

ESP32-H4 的大多数外设信号都直接连接到其专用的 IO_MUX 管脚。不过，也可以使用 GPIO 交换矩阵，将信号路由到任何可用的其他管脚。如果通过 GPIO 交换矩阵路由了至少一个信号，则所有信号都将通过 GPIO 交换矩阵路由。

当 SPI 主机频率配置为 80 MHz 或更低时，则通过 GPIO 交换矩阵或 IO_MUX 路由 SPI 管脚效果相同。

下表列出了 SPI 总线的 IO_MUX 管脚。

管脚名称 | GPIO 编号 (SPI2)
--- | ---
CS0 | N/A
SCLK | N/A
MISO | N/A
MOSI | N/A
QUADWP | N/A
QUADHD | N/A

## 速度与时钟

### 传输事务间隔

ESP32-H4 的 SPI 从机外设是由 CPU 控制的通用从机设备。与专用的从机相比，在内嵌 CPU 的 SPI 从机设备中，预定义寄存器的数量有限，所有的传输事务都必须由 CPU 处理。也就是说，传输和响应并不是实时的，且可能存在明显的延迟。

解决方案为，首先使用函数 `spi_slave_queue_trans()`，然后使用 `spi_slave_get_trans_result()`，来代替 `spi_slave_transmit()`。由此一来，可使从机设备的响应速度提高一倍。

也可以配置一个 GPIO 管脚，当从机设备开始新一次传输事务前，它将通过该管脚向主机发出信号。示例代码存放在 peripherals/spi_slave 目录下。

### 时钟频率要求

SPI 从机的工作频率最高可达 60 MHz。如果时钟频率过快或占空比不足 50%，数据就无法被正确识别或接收。

## 限制条件和已知问题

1. 若启用了 DMA，则 RX 缓冲区应该以字对齐（从 32 位边界开始，字节长度为 4 的倍数）。否则，DMA 可能无法正确写入或无法实现边界对齐。若此项条件不满足，驱动程序将会报错。

   此外，主机写入字节长度应为 4 的倍数。长度不符合的数据将被丢弃。

## 应用示例

如需查看从机/主机通信的代码示例，请前往 peripherals/spi_slave_hd 目录。

- example:

    peripherals/spi_slave/receiver 演示了如何配置 SPI 从机以接收来自 SPI 主机的数据，并通过握手机制管理数据传输的准备状态。

- example:

    peripherals/spi_slave/sender 演示了如何配置 SPI 主机将数据发送到 SPI 从机，并通过握手来确保数据传输的时机恰当。

## API 参考

### Header File

- components/esp_driver_spi/include/driver/spi_slave.h

- This header file can be included with:

  >     #include "driver/spi_slave.h"

- This header file is a part of the API provided by the `esp_driver_spi` component. To declare that your component depends on `esp_driver_spi`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_spi

  > or

  >     PRIV_REQUIRES esp_driver_spi

### Functions

esp_err_t spi_slave_initialize(spi_host_device_t host, const spi_bus_config_t *bus_config, const spi_slave_interface_config_t *slave_config, spi_dma_chan_t dma_chan)

  Initialize a SPI bus as a slave interface and enable it by default.

  警告

  SPI0/1 is not supported

  警告

  If a DMA channel is selected, any transmit and receive buffer used should be allocated in DMA-capable memory.

  警告

  The ISR of SPI is always executed on the core which calls this function. Never starve the ISR on this core or the SPI transactions will not be handled.

  参数:

    - host -- SPI peripheral to use as a SPI slave interface

    - bus_config -- Pointer to a spi_bus_config_t struct specifying how the host should be initialized

    - slave_config -- Pointer to a spi_slave_interface_config_t struct specifying the details for the slave interface

    - dma_chan -- - Selecting a DMA channel for an SPI bus allows transactions on the bus with size only limited by the amount of internal memory.

      - Selecting SPI_DMA_DISABLED limits the size of transactions.

      - Set to SPI_DMA_DISABLED if only the SPI flash uses this bus.

      - Set to SPI_DMA_CH_AUTO to let the driver to allocate the DMA channel.

  返回:

    - ESP_ERR_INVALID_ARG if configuration is invalid

    - ESP_ERR_INVALID_STATE if host already is in use

    - ESP_ERR_NOT_FOUND if there is no available DMA channel

    - ESP_ERR_NO_MEM if out of memory

    - ESP_OK on success

esp_err_t spi_slave_free(spi_host_device_t host)

  Free a SPI bus claimed as a SPI slave interface.

  参数:

    host -- SPI peripheral to free

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_INVALID_STATE if not all devices on the bus are freed

    - ESP_OK on success

esp_err_t spi_slave_enable(spi_host_device_t host)

  Enable the spi slave function for an initialized spi host.

  备注

  No need to call this function additionally after `spi_slave_initialize`, because it has been enabled already during the initialization.

  参数:

    host -- SPI peripheral to be enabled

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Unsupported host

    - ESP_ERR_INVALID_STATE Peripheral already enabled

esp_err_t spi_slave_disable(spi_host_device_t host)

  Disable the spi slave function for an initialized spi host.

  参数:

    host -- SPI peripheral to be disabled

  返回:

    - ESP_OK On success

    - ESP_ERR_INVALID_ARG Unsupported host

    - ESP_ERR_INVALID_STATE Peripheral already disabled

esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transaction_t *trans_desc, uint32_t ticks_to_wait)

  Queue a SPI transaction for execution.

  Queues a SPI transaction to be executed by this slave device. (The transaction queue size was specified when the slave device was initialised via spi_slave_initialize.) This function may block if the queue is full (depending on the ticks_to_wait parameter). No SPI operation is directly initiated by this function, the next queued transaction will happen when the master initiates a SPI transaction by pulling down CS and sending out clock signals.

  This function hands over ownership of the buffers in `trans_desc` to the SPI slave driver; the application is not to access this memory until `spi_slave_queue_trans` is called to hand ownership back to the application.

  备注

  On esp32, if trans length not WORD aligned, the rx buffer last word memory will still overwritten by DMA HW

  参数:

    - host -- SPI peripheral that is acting as a slave

    - trans_desc -- Description of transaction to execute. Not const because we may want to write status back into the transaction description.

    - ticks_to_wait -- Ticks to wait until there's room in the queue; use portMAX_DELAY to never time out.

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_NO_MEM if set flag `SPI_SLAVE_TRANS_DMA_BUFFER_ALIGN_AUTO` but there is no free memory

    - ESP_ERR_INVALID_STATE if sync data between Cache and memory failed

    - ESP_ERR_TIMEOUT if there was no room in the queue before `ticks_to_wait` expired

    - ESP_OK on success

esp_err_t spi_slave_get_trans_result(spi_host_device_t host, spi_slave_transaction_t **trans_desc, uint32_t ticks_to_wait)

  Get the result of a SPI transaction queued earlier.

  This routine will wait until a transaction to the given device (queued earlier with spi_slave_queue_trans) has successfully completed. It will then return the description of the completed transaction so software can inspect the result and e.g. free the memory or reuse the buffers.

  It is mandatory to eventually use this function for any transaction queued by `spi_slave_queue_trans`.

  参数:

    - host -- SPI peripheral to that is acting as a slave

    - trans_desc -- [out] Pointer to variable able to contain a pointer to the description of the transaction that is executed

    - ticks_to_wait -- Ticks to wait until there's a returned item; use portMAX_DELAY to never time out.

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_NOT_SUPPORTED if flag `SPI_SLAVE_NO_RETURN_RESULT` is set

    - ESP_ERR_INVALID_STATE if dma over/underflow error occurs during psram transfer

    - ESP_ERR_TIMEOUT if there was no completed transaction before `ticks_to_wait` expired

    - ESP_OK on success

esp_err_t spi_slave_transmit(spi_host_device_t host, spi_slave_transaction_t *trans_desc, uint32_t ticks_to_wait)

  Do a SPI transaction.

  Essentially does the same as spi_slave_queue_trans followed by spi_slave_get_trans_result. Do not use this when there is still a transaction queued that hasn't been finalized using spi_slave_get_trans_result.

  参数:

    - host -- SPI peripheral to that is acting as a slave

    - trans_desc -- Pointer to variable able to contain a pointer to the description of the transaction that is executed. Not const because we may want to write status back into the transaction description.

    - ticks_to_wait -- Ticks to wait until there's a returned item; use portMAX_DELAY to never time out.

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_INVALID_STATE if dma over/underflow error occurs during psram transfer

    - ESP_ERR_TIMEOUT if the transaction cannot be queued or finished before `ticks_to_wait` expired

    - ESP_OK on success

### Structures

struct spi_slave_interface_config_t

  This is a configuration for a SPI host acting as a slave device.

  Public Members

  int spics_io_num

    CS GPIO pin for this device.

  uint32_t flags

    Bitwise OR of SPI_SLAVE_* flags.

  int queue_size

    Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_slave_queue_trans but not yet finished using spi_slave_get_trans_result) at the same time.

  uint8_t mode

    SPI mode, representing a pair of (CPOL, CPHA) configuration:

    - 0: (0, 0)

    - 1: (0, 1)

    - 2: (1, 0)

    - 3: (1, 1)

  slave_transaction_cb_t post_setup_cb

    Callback called after the SPI registers are loaded with new data.

    This callback is called within interrupt context should be in IRAM for best performance, see "Transferring Speed" section in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.

  slave_transaction_cb_t post_trans_cb

    Callback called after a transaction is done.

    This callback is called within interrupt context should be in IRAM for best performance, see "Transferring Speed" section in the SPI Master documentation for full details. If not, the callback may crash during flash operation when the driver is initialized with ESP_INTR_FLAG_IRAM.

struct spi_slave_transaction_t

  This structure describes one SPI transaction

  Public Members

  uint32_t flags

    Bitwise OR of SPI_SLAVE_TRANS_* flags.

  size_t length

    Total data length, in bits. It both for TX and RX, do NOT use together with independent length.

  size_t tx_length

    Independent Tx data length, in bits, using with tx_buffer. do NOT use together with `length`

  size_t rx_length

    Independent Rx data length, in bits, using with rx_buffer. do NOT use together with `length`

  size_t trans_len

    Transaction data length, in bits.

  const void *tx_buffer

    Pointer to transmit buffer, or NULL for no MOSI phase.

  void *rx_buffer

    Pointer to receive buffer, or NULL for no MISO phase. When the DMA is enabled, must start at WORD boundary (`rx_buffer%4==0`), and has length of a multiple of 4 bytes.

  void *user

    User-defined variable. Can be used to store eg transaction ID.

### Macros

SPI_SLAVE_TXBIT_LSBFIRST

  Transmit command/address/data LSB first instead of the default MSB first.

SPI_SLAVE_RXBIT_LSBFIRST

  Receive data LSB first instead of the default MSB first.

SPI_SLAVE_BIT_LSBFIRST

  Transmit and receive LSB first.

SPI_SLAVE_NO_RETURN_RESULT

  Don't return the descriptor to the host on completion (use `post_trans_cb` to notify instead)

SPI_SLAVE_TRANS_DMA_BUFFER_ALIGN_AUTO

  Automatically re-malloc dma buffer if user buffer doesn't meet hardware alignment or dma_capable, this process may loss some memory and performance.

### Type Definitions

typedef void (*slave_transaction_cb_t)(spi_slave_transaction_t *trans)

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。