mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/translate_spi_slave_and_spi_master' into 'master'
docs: provide CN translation for spi_slave and spi_features Closes DOC-2921 and DOC-3179 See merge request espressif/esp-idf!18338
This commit is contained in:
Shang Zhou
commit
b20aa0612b
@ -11,29 +11,18 @@ SPI Master
|
||||
SPI Bus Lock
|
||||
^^^^^^^^^^^^
|
||||
|
||||
To realize the multiplexing of different devices from different drivers (SPI Master, SPI Flash,
|
||||
etc.), an SPI bus lock is applied on each SPI bus. Drivers can attach their devices onto the bus
|
||||
with the arbitration of the lock.
|
||||
To realize the multiplexing of different devices from different drivers, including SPI Master, SPI Flash, etc., an SPI bus lock is applied on each SPI bus. Drivers can attach their devices onto the bus with the arbitration of the lock.
|
||||
|
||||
Each bus lock are initialized with a BG (background) service registered, all devices request to
|
||||
do transactions on the bus should wait until the BG to be successfully disabled.
|
||||
Each bus lock is initialized with a BG (background) service registered. All devices that request transactions on the bus should wait until the BG is successfully disabled.
|
||||
|
||||
- For SPI1 bus, the BG is the cache, the bus lock will help to disable the cache before device
|
||||
operations starts, and enable it again after device releasing the lock. No devices on SPI1 is
|
||||
allowed using ISR (it's meaningless for the task to yield to other tasks when the cache is
|
||||
disabled).
|
||||
- For SPI1 bus, the BG is the cache. The bus lock will disable the cache before device operations start, and enable it again after device releases the lock. No devices on SPI1 is allowed to use ISR, since it is meaningless for the task to yield to other tasks when the cache is disabled.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
There are quite a few limitations when using SPI Master driver on the SPI1 bus, see
|
||||
:ref:`spi_master_on_spi1_bus`.
|
||||
There are quite a few limitations when using SPI Master driver on the SPI1 bus. See :ref:`spi_master_on_spi1_bus`.
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
The SPI Master driver hasn't supported SPI1 bus. Only SPI Flash driver can attach to the bus.
|
||||
|
||||
- For other buses, the driver may register its ISR as the BG. The bus lock will block a device
|
||||
task when it requests for exclusive use of the bus, try to disable the ISR, and unblock the
|
||||
device task allowed to exclusively use the bus when the ISR is successfully disabled. When the
|
||||
task releases the lock, the lock will also try to resume the ISR if there are pending
|
||||
transactions to be done in the ISR.
|
||||
- For other buses, the driver may register its ISR as the BG. When a device task requests for exclusive use of the bus, the bus lock will block the task and try to disable ISR. After ISR is successfully disabled, the bus lock will then unblock the device task and allow it to exclusively use the bus. When the task releases the lock, the lock will also try to resume ISR if there are pending transactions in ISR.
|
||||
|
||||
@ -9,7 +9,7 @@ Overview of {IDF_TARGET_NAME}'s SPI peripherals
|
||||
|
||||
.. only:: esp32 or esp32s2 or esp32s3
|
||||
|
||||
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master
|
||||
{IDF_TARGET_NAME} integrates two general purpose SPI controllers which can be used as slave nodes driven by an off-chip SPI master.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
@ -20,7 +20,7 @@ Overview of {IDF_TARGET_NAME}'s SPI peripherals
|
||||
|
||||
.. only:: esp32c3 or esp32c2
|
||||
|
||||
{IDF_TARGET_NAME} integrates one general purpose SPI controller which can be used as slave node driven by an off-chip SPI master. The controller is called SPI2 and has an independent signal bus with the same name.
|
||||
{IDF_TARGET_NAME} integrates one general purpose SPI controller which can be used as a slave node driven by an off-chip SPI master. The controller is called SPI2 and has an independent signal bus with the same name.
|
||||
|
||||
|
||||
Terminology
|
||||
@ -28,24 +28,38 @@ Terminology
|
||||
|
||||
The terms used in relation to the SPI slave driver are given in the table below.
|
||||
|
||||
================= =========================================================================================
|
||||
Term Definition
|
||||
================= =========================================================================================
|
||||
**Host** The SPI controller peripheral external to {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
|
||||
**Device** SPI slave device (general purpose SPI controller). Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
|
||||
**Bus** A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner.
|
||||
- **MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
|
||||
- **MOSI** Master Out, Slave in, a.k.a. D. Data transmission from a Host to Device.
|
||||
- **SCLK** Serial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
|
||||
- **CS** Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data.
|
||||
- **QUADWP** Write Protect signal. Only used for 4-bit (qio/qout) transactions.
|
||||
- **QUADHD** Hold signal. Only used for 4-bit (qio/qout) transactions.
|
||||
- **Assertion** The action of activating a line. The opposite action of returning the line back to inactive (back to idle) is called *de-assertion*.
|
||||
**Transaction** One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS line. Transactions are atomic, which means they can never be interrupted by another transaction.
|
||||
**Launch edge** Edge of the clock at which the source register *launches* the signal onto the line.
|
||||
**Latch edge** Edge of the clock at which the destination register *latches in* the signal.
|
||||
================= =========================================================================================
|
||||
.. list-table::
|
||||
:widths: 30 70
|
||||
:header-rows: 1
|
||||
|
||||
* - Term
|
||||
- Definition
|
||||
* - Host
|
||||
- The SPI controller peripheral external to {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
|
||||
* - Device
|
||||
- SPI slave device (general purpose SPI controller). Each Device shares the MOSI, MISO and SCLK signals but is only active on the bus when the Host asserts the Device's individual CS line.
|
||||
* - Bus
|
||||
- A signal bus, common to all Devices connected to one Host. In general, a bus includes the following lines: MISO, MOSI, SCLK, one or more CS lines, and, optionally, QUADWP and QUADHD. So Devices are connected to the same lines, with the exception that each Device has its own CS line. Several Devices can also share one CS line if connected in the daisy-chain manner.
|
||||
* - MISO
|
||||
- Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host.
|
||||
* - MOSI
|
||||
- Master Out, Slave In, a.k.a. D. Data transmission from a Host to Device.
|
||||
* - SCLK
|
||||
- Serial Clock. Oscillating signal generated by a Host that keeps the transmission of data bits in sync.
|
||||
* - CS
|
||||
- Chip Select. Allows a Host to select individual Device(s) connected to the bus in order to send or receive data.
|
||||
* - QUADWP
|
||||
- Write Protect signal. Only used for 4-bit (qio/qout) transactions.
|
||||
* - QUADHD
|
||||
- Hold signal. Only used for 4-bit (qio/qout) transactions.
|
||||
* - Assertion
|
||||
- The action of activating a line. The opposite action of returning the line back to inactive (back to idle) is called *de-assertion*.
|
||||
* - Transaction
|
||||
- One instance of a Host asserting a CS line, transferring data to and from a Device, and de-asserting the CS line. Transactions are atomic, which means they can never be interrupted by another transaction.
|
||||
* - Launch Edge
|
||||
- Edge of the clock at which the source register *launches* the signal onto the line.
|
||||
* - Latch Edge
|
||||
- Edge of the clock at which the destination register *latches in* the signal.
|
||||
|
||||
|
||||
Driver Features
|
||||
@ -61,7 +75,7 @@ SPI Transactions
|
||||
|
||||
A full-duplex SPI transaction begins when the Host asserts the CS line and starts sending out clock pulses on the SCLK line. Every clock pulse, a data bit is shifted from the Host to the Device on the MOSI line and back on the MISO line at the same time. At the end of the transaction, the Host de-asserts the CS line.
|
||||
|
||||
The attributes of a transaction are determined by the configuration structure for an SPI host acting as a slave device :cpp:type:`spi_slave_interface_config_t`, and transaction configuration structure :cpp:type:`spi_slave_transaction_t`.
|
||||
The attributes of a transaction are determined by the configuration structure for an SPI peripheral acting as a slave device :cpp:type:`spi_slave_interface_config_t`, and transaction configuration structure :cpp:type:`spi_slave_transaction_t`.
|
||||
|
||||
As not every transaction requires both writing and reading data, you have a choice to configure the :cpp:type:`spi_transaction_t` structure for TX only, RX only, or TX and RX transactions. If :cpp:member:`spi_slave_transaction_t::rx_buffer` is set to NULL, the read phase will be skipped. If :cpp:member:`spi_slave_transaction_t::tx_buffer` is set to NULL, the write phase will be skipped.
|
||||
|
||||
@ -93,7 +107,7 @@ Transaction Data and Master/Slave Length Mismatches
|
||||
|
||||
Normally, the data that needs to be transferred to or from a Device is read or written to a chunk of memory indicated by the :cpp:member:`spi_slave_transaction_t::rx_buffer` and :cpp:member:`spi_slave_transaction_t::tx_buffer`. The SPI driver can be configured to use DMA for transfers, in which case these buffers must be allocated in DMA-capable memory using ``pvPortMallocCaps(size, MALLOC_CAP_DMA)``.
|
||||
|
||||
The amount of data that the driver can read or write to the buffers is limited by :cpp:member:`spi_slave_transaction_t::length`. However, this member does not define the actual length of an SPI transaction. A transaction's length is determined by a Host which drives the clock and CS lines. The actual length of the transmission can be read only after a transaction is finished from the member :cpp:member:`spi_slave_transaction_t::trans_len`.
|
||||
The amount of data that the driver can read or write to the buffers is limited by :cpp:member:`spi_slave_transaction_t::length`. However, this member does not define the actual length of an SPI transaction. A transaction's length is determined by the clock and CS lines driven by the Host. The actual length of the transmission can be read only after a transaction is finished from the member :cpp:member:`spi_slave_transaction_t::trans_len`.
|
||||
|
||||
If the length of the transmission is greater than the buffer length, only the initial number of bits specified in the :cpp:member:`spi_slave_transaction_t::length` member will be sent and received. In this case, :cpp:member:`spi_slave_transaction_t::trans_len` is set to :cpp:member:`spi_slave_transaction_t::length` instead of the actual transaction length. To meet the actual transaction length requirements, set :cpp:member:`spi_slave_transaction_t::length` to a value greater than the maximum :cpp:member:`spi_slave_transaction_t::trans_len` expected. If the transmission length is shorter than the buffer length, only the data equal to the length of the buffer will be transmitted.
|
||||
|
||||
@ -118,24 +132,31 @@ If the length of the transmission is greater than the buffer length, only the in
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
+----------+------+------+
|
||||
| Pin Name | SPI2 | SPI3 |
|
||||
+ +------+------+
|
||||
| | GPIO Number |
|
||||
+==========+======+======+
|
||||
| CS0* | 15 | 5 |
|
||||
+----------+------+------+
|
||||
| SCLK | 14 | 18 |
|
||||
+----------+------+------+
|
||||
| MISO | 12 | 19 |
|
||||
+----------+------+------+
|
||||
| MOSI | 13 | 23 |
|
||||
+----------+------+------+
|
||||
| QUADWP | 2 | 22 |
|
||||
+----------+------+------+
|
||||
| QUADHD | 4 | 21 |
|
||||
+----------+------+------+
|
||||
.. list-table::
|
||||
:widths: 40 30 30
|
||||
:header-rows: 1
|
||||
|
||||
* - Pin Name
|
||||
- GPIO Number (SPI2)
|
||||
- GPIO Number (SPI3)
|
||||
* - CS0*
|
||||
- 15
|
||||
- 5
|
||||
* - SCLK
|
||||
- 14
|
||||
- 18
|
||||
* - MISO
|
||||
- 12
|
||||
- 19
|
||||
* - MOSI
|
||||
- 13
|
||||
- 23
|
||||
* - QUADWP
|
||||
- 2
|
||||
- 22
|
||||
* - QUADHD
|
||||
- 4
|
||||
- 21
|
||||
|
||||
* Only the first Device attached to the bus can use the CS0 pin.
|
||||
|
||||
@ -172,17 +193,23 @@ The SPI slaves are designed to operate at up to {IDF_TARGET_MAX_FREQ} MHz. The d
|
||||
- Write (MISO):
|
||||
The output delay of the MISO signal needs to be shorter than half of a clock cycle period so that the MISO line is stable before the next latch edge. Given that the clock is balanced, the output delay and frequency limitations in different cases are given below.
|
||||
|
||||
+-------------+---------------------------+------------------------+
|
||||
| | Output delay of MISO (ns) | Freq. limit (MHz) |
|
||||
+=============+===========================+========================+
|
||||
| IO_MUX | 43.75 | <11.4 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
| GPIO matrix | 68.75 | <7.2 |
|
||||
+-------------+---------------------------+------------------------+
|
||||
.. list-table::
|
||||
:widths: 30 40 40
|
||||
:header-rows: 1
|
||||
|
||||
* - /
|
||||
- Output delay of MISO (ns)
|
||||
- Freq. limit (MHz)
|
||||
* - IO_MUX
|
||||
- 43.75
|
||||
- <11.4
|
||||
* - GPIO matrix
|
||||
- 68.75
|
||||
- <7.2
|
||||
|
||||
Note:
|
||||
1. If the frequency is equal to the limitation, it can lead to random errors.
|
||||
2. The clock uncertainty between Host and Device (12.5ns) is included.
|
||||
1. If the frequency reaches the maximum limitation, random errors may occur.
|
||||
2. The clock uncertainty between the Host and the Device (12.5 ns) is included.
|
||||
3. The output delay is measured under ideal circumstances (no load). If the MISO pin is heavily loaded, the output delay will be longer, and the maximum allowed frequency will be lower.
|
||||
|
||||
Exception: The frequency is allowed to be higher if the master has more tolerance for the MISO setup time, e.g., latch data at the next edge, or configurable latching time.
|
||||
|
||||
@ -1 +1,28 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/spi_features.rst
|
||||
SPI 特性
|
||||
============
|
||||
|
||||
.. _spi_master_features:
|
||||
|
||||
SPI 主机
|
||||
----------
|
||||
|
||||
.. _spi_bus_lock:
|
||||
|
||||
SPI 总线锁
|
||||
^^^^^^^^^^^^
|
||||
|
||||
为了多路复用来自不同驱动的不同设备，包括 SPI 主机、SPI Flash 等驱动，每个 SPI 总线上都有一个 SPI 总线锁。驱动程序可以通过对锁的仲裁，将设备连接到总线上。
|
||||
|
||||
每个总线锁都已初始化并注册了后台服务 (BG)。所有请求在总线上进行传输的设备都应等到 BG 被成功禁用后再开始传输。
|
||||
|
||||
- 在 SPI1 总线上，BG 为高速缓存。总线锁可以在设备操作开始前禁用高速缓存，并在设备释放锁后再次启用它。SPI1 上的任何设备都无法使用 ISR，因为当高速缓存被禁用时，让出当前任务的执行权是没有意义的。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
在 SPI1 总线上使用 SPI 主机驱动程序时，存在一些限制。请参见 :ref:`spi_master_on_spi1_bus`。
|
||||
|
||||
.. only:: not esp32
|
||||
|
||||
SPI 主机驱动程序暂不支持 SPI1 总线。只有 SPI Flash 驱动程序可以连接到该总线。
|
||||
|
||||
- 对于其他总线，驱动程序可以将其 ISR 注册为 BG。当一个设备任务要求独占总线时，总线锁将阻塞该任务，同时禁用 ISR，并在 ISR 被成功禁用后，解除对该任务的阻塞。当任务释放锁时，如果 ISR 中还有待处理的事务，锁也将尝试恢复 ISR。
|
||||
|
||||
@ -1 +1,245 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/spi_slave.rst
|
||||
SPI 从机驱动程序
|
||||
================
|
||||
|
||||
SPI 从机驱动程序控制在 {IDF_TARGET_NAME} 中作为从机的 SPI 外设。
|
||||
|
||||
|
||||
{IDF_TARGET_NAME} 中 SPI 外设概述
|
||||
-----------------------------------------------
|
||||
|
||||
.. only:: esp32 or esp32s2 or esp32s3
|
||||
|
||||
{IDF_TARGET_NAME} 集成了 2 个通用的 SPI 控制器，可用作片外 SPI 主机驱动的从机节点。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
- SPI2，有时也称为 HSPI
|
||||
- SPI3，有时也称为 VSPI
|
||||
|
||||
SPI2 和 SPI3 各自具有一个与之同名的独立总线信号。
|
||||
|
||||
.. only:: esp32c3 or esp32c2
|
||||
|
||||
{IDF_TARGET_NAME} 集成了 1 个通用的 SPI 控制器，可用作片外 SPI 主机驱动的从机节点。该控制器为 SPI2，具有一个与之同名的独立总线信号。
|
||||
|
||||
|
||||
术语
|
||||
-----------
|
||||
|
||||
下表为 SPI 主机驱动的相关术语。
|
||||
|
||||
.. list-table::
|
||||
:widths: 30 70
|
||||
:header-rows: 1
|
||||
|
||||
* - 术语
|
||||
- 定义
|
||||
* - 主机 (Host)
|
||||
- {IDF_TARGET_NAME} 外部的 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)
|
||||
- 目的寄存器 *锁存* 信号的时钟边沿。
|
||||
|
||||
|
||||
驱动程序的功能
|
||||
---------------
|
||||
|
||||
{IDF_TARGET_MAX_DATA_BUF:default="64", esp32s2="72"}
|
||||
|
||||
SPI 从机驱动程序允许将 SPI 外设作为全双工设备使用。驱动程序可以发送/接收长度不超过 {IDF_TARGET_MAX_DATA_BUF} 字节的传输事务，或者利用 DMA 来发送/接收更长的传输事务。然而，存在一些与 DMA 有关的 :ref:`已知问题 <spi_dma_known_issues>`。
|
||||
|
||||
|
||||
SPI 传输事务
|
||||
----------------
|
||||
|
||||
主机断言 CS 线并在 SCLK 线上发出时钟脉冲时，一次全双工 SPI 传输事务就此开始。每个时钟脉冲都意味着通过 MOSI 线从主机转移一个数据位到从机设备上，并同时通过 MISO 线返回一个数据位。传输事务结束后，主机去断言 CS 线。
|
||||
|
||||
传输事务的属性由作为从机设备的 SPI 外设的配置结构体 :cpp:type:`spi_slave_interface_config_t` 和传输事务配置结构体 :cpp:type:`spi_slave_transaction_t` 决定。
|
||||
|
||||
由于并非每次传输事务都需要写入和读取数据，您可以选择配置 :cpp:type:`spi_transaction_t` 为仅 TX、仅 RX 或同时 TX 和 RX 传输事务。如果将 :cpp:member:`spi_slave_transaction_t::rx_buffer` 设置为 NULL，读取阶段将被跳过。如果将 :cpp:member:`spi_slave_transaction_t::tx_buffer` 设置为 NULL，则写入阶段将被跳过。
|
||||
|
||||
.. note::
|
||||
|
||||
主机应在从机设备准备好接收数据之后再进行传输事务。建议使用另外一个 GPIO 管脚作为握手信号来同步设备。更多细节，请参阅 :ref:`transaction_interval`。
|
||||
|
||||
|
||||
使用驱动程序
|
||||
------------
|
||||
|
||||
- 调用函数 cpp:func:`spi_slave_initialize`，将 SPI 外设初始化为从机设备。请确保在 `bus_config` 中设置正确的 I/O 管脚，并将未使用的信号设置为 ``-1``。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
如果传输事务的数据大于 32 字节，需要将参数 ``dma_chan`` 分别设置为 ``1`` 或 ``2`` 以使能 DMA 通道 1 或通道 2。若数据小于 32 字节，则应将 ``dma_chan`` 设为 ``0``。
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
如果传输事务的数据大于 32 字节，需要在主机上设置参数 ``dma_chan`` 以使能 DMA 通道。若数据小于 32 字节，则应将 ``dma_chan`` 设为 ``0``。
|
||||
|
||||
- 传输事务开始前，需用要求的事务参数填充一个或多个 :cpp:type:`spi_slave_transaction_t` 结构体。可以通过调用函数 :cpp:func:`spi_slave_queue_trans` 来将所有传输事务排进队列，并在稍后使用函数 :cpp:func:`spi_slave_get_trans_result` 查询结果；也可以将所有请求输入 :cpp:func:`spi_slave_transmit` 中单独处理。主机上的传输事务完成前，后两个函数将被阻塞，以便发送并接收队列中的数据。
|
||||
|
||||
-（可选）如需卸载 SPI 从机驱动程序，请调用 :cpp:func:`spi_slave_free`。
|
||||
|
||||
|
||||
传输事务数据和主/从机长度不匹配
|
||||
---------------------------------------------------
|
||||
|
||||
通常，通过从机设备进行传输的数据会被读取或写入到由 :cpp:member:`spi_slave_transaction_t::rx_buffer` 和 :cpp:member:`spi_slave_transaction_t::tx_buffer` 指示的大块内存中。可以配置 SPI 驱动程序，使用 DMA 进行传输。在这种情况下，则必须使用 ``pvPortMallocCaps(size, MALLOC_CAP_DMA)`` 将缓存区分配到具备 DMA 功能的内存中。
|
||||
|
||||
驱动程序可以读取或写入缓存区的数据量取决于 :cpp:member:`spi_slave_transaction_t::length`，但其并不会定义一次 SPI 传输的实际长度。传输事务的长度由主机的时钟线和 CS 线决定，且只有在传输事务完成后，才能从 :cpp:member:`spi_slave_transaction_t::trans_len` 中读取实际长度。
|
||||
|
||||
如果传输长度超过缓存区长度，则只有在 :cpp:member:`spi_slave_transaction_t::length` 中指定的初始比特数会被发送和接收。此时， :cpp:member:`spi_slave_transaction_t::trans_len` 被设置为 :cpp:member:`spi_slave_transaction_t::length` 而非实际传输事务长度。若需满足实际传输事务长度的要求，请将 :cpp:member:`spi_slave_transaction_t::length` 设置为大于 :cpp:member:`spi_slave_transaction_t::trans_len` 预期最大值的值。如果传输长度短于缓存区长度，则只传输与缓存区长度相等的数据。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
GPIO 交换矩阵和 IO_MUX
|
||||
----------------------
|
||||
|
||||
{IDF_TARGET_NAME} 的大多数外设信号都直接连接到其专用的 IO_MUX 管脚。不过，也可以使用 GPIO 交换矩阵，将信号路由到任何可用的其他管脚。
|
||||
|
||||
如果通过 GPIO 交换矩阵路由了至少一个信号，则所有信号都将通过 GPIO 交换矩阵路由。GPIO 交换矩阵以 80 MHz 的频率对所有信号进行采样，并在 GPIO 和外设之间进行传输。
|
||||
|
||||
如果已经配置过驱动程序，所有的 SPI 信号都已路由到专用的 IO_MUX 管脚，或者根本没有连接到任何管脚，那么 GPIO 交换矩阵将被绕过。
|
||||
|
||||
GPIO 交换矩阵提高了信号传输的灵活性，但也增大了 MISO 信号的输入延迟，导致违反 MISO 设置时间的可能性更高。如需 SPI 高速运行，请使用专用的 IO_MUX 管脚。
|
||||
|
||||
.. note::
|
||||
|
||||
更多有关 MISO 输入延迟对最大时钟频率影响的细节，请参阅 :ref:`timing_considerations`。
|
||||
|
||||
下表列出了 SPI 总线的 IO_MUX 管脚。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
.. list-table::
|
||||
:widths: 40 30 30
|
||||
:header-rows: 1
|
||||
|
||||
* - 管脚名称
|
||||
- GPIO 编号 (SPI2)
|
||||
- GPIO 编号 (SPI3)
|
||||
* - CS0*
|
||||
- 15
|
||||
- 5
|
||||
* - SCLK
|
||||
- 14
|
||||
- 18
|
||||
* - MISO
|
||||
- 12
|
||||
- 19
|
||||
* - MOSI
|
||||
- 13
|
||||
- 23
|
||||
* - QUADWP
|
||||
- 2
|
||||
- 22
|
||||
* - QUADHD
|
||||
- 4
|
||||
- 21
|
||||
|
||||
* 只有连接到总线上的第一个从机设备可以使用 CS0 管脚。
|
||||
|
||||
|
||||
速度与时钟
|
||||
-------------------------------
|
||||
|
||||
.. _transaction_interval:
|
||||
|
||||
传输事务间隔
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} 的 SPI 从机外设是由 CPU 控制的通用从机设备。与专用的从机相比，在内嵌 CPU 的 SPI 从机设备中，预定义寄存器的数量有限，所有的传输事务都必须由 CPU 处理。也就是说，传输和响应并不是实时的，且可能存在明显的延迟。
|
||||
|
||||
解决方案为，首先使用函数 :cpp:func:`spi_slave_queue_trans`，然后使用 :cpp:func:`spi_slave_get_trans_result`，来代替 :cpp:func:`spi_slave_transmit`。由此一来，可使从机设备的响应速度提高一倍。
|
||||
|
||||
您也可以配置一个 GPIO 管脚，当从机设备开始新一次传输事务前，它将通过该管脚向主机发出信号。示例代码存放在 :example:`peripherals/spi_slave` 目录下。
|
||||
|
||||
|
||||
时钟频率要求
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_MAX_FREQ:default="60", esp32="10", esp32s2="40"}
|
||||
|
||||
SPI 从机的工作频率最高可达 {IDF_TARGET_MAX_FREQ} MHz。如果时钟频率过快或占空比不足 50%，数据就无法被正确识别或接收。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
除此之外，在数据方面还有一些额外要求，以满足时间限制：
|
||||
|
||||
- 读取 (MOSI):
|
||||
只有当数据在主机的发射沿准备好时，从机设备才能正确读取数据。此为大多数主机的默认情况。
|
||||
|
||||
- 写入 (MISO):
|
||||
MISO 信号的输出延迟应短于半个时钟周期，以确保 MISO 线在下一个锁存沿之前保持稳定。鉴于时钟同步，不同情况下的输出延迟和频率限制如下。
|
||||
|
||||
.. list-table::
|
||||
:widths: 30 40 40
|
||||
:header-rows: 1
|
||||
|
||||
* - /
|
||||
- MISO 输出延迟 (ns)
|
||||
- 频率限制 (MHz)
|
||||
* - IO_MUX
|
||||
- 43.75
|
||||
- <11.4
|
||||
* - GPIO 交换矩阵
|
||||
- 68.75
|
||||
- <7.2
|
||||
|
||||
注：
|
||||
1. 如果频率达到上限，会导致随机误差。
|
||||
2. 主机和设备之间的时钟不确定性 (12.5 ns) 已被考虑在内。
|
||||
3. 表中的输出延迟为理想情况（无负载）下的数据。如果 MISO 管脚负载较重，则输出延迟更长，且最大允许频率更低。
|
||||
|
||||
例外情况：如果主机支持更多相关 MISO 设置时间的选项，例如，可以在下一个边沿锁存数据，或可以配置锁存时间，则频率限制的上限会更高。
|
||||
|
||||
|
||||
.. _spi_dma_known_issues:
|
||||
|
||||
限制条件和已知问题
|
||||
-----------------------------
|
||||
|
||||
1. 若启用了 DMA，则 RX 缓冲区应该以字对齐（从 32 位边界开始，字节长度为 4 的倍数）。否则，DMA 可能无法正确写入或无法实现边界对齐。若此项条件不满足，驱动程序将会报错。
|
||||
|
||||
此外，主机写入字节长度应为 4 的倍数。长度不符合的数据将被丢弃。
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
2. 此外，使用 DMA 时需启用 SPI 模式 1 和模式 3。在 SPI 模式 0 和模式 2 下，为满足时序要求，MISO 信号必须提前半个时钟周期启动。新的时序如下：
|
||||
|
||||
.. wavedrom:: /../_static/diagrams/spi/spi_slave_miso_dma.json
|
||||
|
||||
如果启用 DMA，从机设备的发射沿会比正常时间提前半个 SPI 时钟周期，变为主机的实际锁存沿。在这种情况下，如果 GPIO 交换矩阵被绕过，数据采样的保持时间将是 68.75 ns，而非半个 SPI 时钟周期。如果使用了 GPIO 交换矩阵，保持时间将增加到 93.75 ns。主机应在锁存沿立即采样数据，或在 SPI 模式 1 或模式 3 中进行通信。如果您的主机无法满足上述时间要求，请在没有 DMA 的情况下初始化从机设备。
|
||||
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
从机设备/主机通信的示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals/spi_slave` 目录下。
|
||||
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/spi_slave.inc
|
||||
|
||||
Loading…
Reference in New Issue
Block a user