mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-26 12:50:30 +00:00
docs: provide CN translation for spi_slave and spi_features
This commit is contained in:
Shang Zhou
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user