espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-02 16:11:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/spi_master_support_8-line_mode' into 'master'

Browse Source 
spi_master: support 8-line mode

Closes IDF-3354 and IDFGH-4553

See merge request espressif/esp-idf!14397
This commit is contained in:
morris
2021-08-19 13:19:34 +00:00
parent 406d1728f5 71d475149d
commit 29e7456f37
31 changed files with 848 additions and 541 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/en/api-reference/peripherals/spi_master.rst
View File

@@ -47,12 +47,16 @@ Term Definition
**Host** The SPI controller peripheral inside {IDF_TARGET_NAME} that initiates SPI transmissions over the bus, and acts as an SPI Master.
**Device** SPI slave device. An SPI bus may be connected to one or more Devices. 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.
**MOSI** Master Out, Slave In, a.k.a. D. Data transmission from a Host to Device. Also data0 signal in Octal/OPI mode.
**MISO** Master In, Slave Out, a.k.a. Q. Data transmission from a Device to Host. Also data1 signal in Octal/OPI mode.
**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.
**QUADWP** Write Protect signal. Used for 4-bit (qio/qout) transactions. Also for data2 signal in Octal/OPI mode.
**QUADHD** Hold signal. Used for 4-bit (qio/qout) transactions. Also for data3 signal in Octal/OPI mode.
**DATA4** Data4 signal in Octal/OPI mode.
**DATA5** Data5 signal in Octal/OPI mode.
**DATA6** Data6 signal in Octal/OPI mode.
**DATA7** Data7 signal in Octal/OPI mode.
**Assertion** The action of activating a line.
**De-assertion** The action of returning the line back to inactive (back to idle) status.
**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.
@@ -144,6 +148,59 @@ All the tasks that use interrupt transactions can be blocked by the queue. At th
The :cpp:func:`spi_device_polling_end` routine needs an overhead of at least 1 us to unblock other tasks when the transaction is finished. It is strongly recommended to wrap a series of polling transactions using the functions :cpp:func:`spi_device_acquire_bus` and :cpp:func:`spi_device_release_bus` to avoid the overhead. For more information, see :ref:`bus_acquiring`.
.. _transaction-line-mode:
Transaction Line Mode
^^^^^^^^^^^^^^^^^^^^^
Supported line modes for {IDF_TARGET_NAME} are listed as follows, to make use of these modes, set the member `flags` in the struct :cpp:type:`spi_transaction_t` as shown in the `Transaction Flag` column. If you want to check if corresponding IO pins are set or not, set the member `flags` in the :cpp:type:`spi_bus_config_t` as shown in the `Bus IO setting Flag` column.
.. only:: not SOC_SPI_SUPPORT_OCT
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Mode name | Command Line Width | Address Line Width | Data Line Width | Transaction Flag | Bus IO setting Flag |
+==============+====================+====================+=================+============================+=========================+
| Normal SPI | 1 | 1 | 1 | 0 | 0 |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Dual Output | 1 | 1 | 2 | SPI_TRANS_MODE_DIO | |
| | | | | | |
| | | | | | SPICOMMON_BUSFLAG_DUAL |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Dual I/O | 1 | 2 | 2 | SPI_TRANS_MODE_DIO | | |
| | | | | SPI_TRANS_MULTILINE_ADDR | |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Quad Output | 1 | 1 | 4 | SPI_TRANS_MODE_QIO | |
+--------------+--------------------+--------------------+-----------------+----------------------------+ |
| Quad I/O | 1 | 4 | 4 | SPI_TRANS_MODE_QIO | | SPICOMMON_BUSFLAG_QUAD |
| | | | | SPI_TRANS_MULTILINE_ADDR | |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
.. only:: SOC_SPI_SUPPORT_OCT
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Mode name | Command Line Width | Address Line Width | Data Line Width | Transaction Flag | Bus IO setting Flag |
+==============+====================+====================+=================+============================+=========================+
| Normal SPI | 1 | 1 | 1 | 0 | 0 |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Dual Output | 1 | 1 | 2 | SPI_TRANS_MODE_DIO | |
| | | | | | |
| | | | | | SPICOMMON_BUSFLAG_DUAL |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Dual I/O | 1 | 2 | 2 | SPI_TRANS_MODE_DIO | | |
| | | | | SPI_TRANS_MULTILINE_ADDR | |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Quad Output | 1 | 1 | 4 | SPI_TRANS_MODE_QIO | |
+--------------+--------------------+--------------------+-----------------+----------------------------+ |
| Quad I/O | 1 | 4 | 4 | SPI_TRANS_MODE_QIO | | SPICOMMON_BUSFLAG_QUAD |
| | | | | SPI_TRANS_MULTILINE_ADDR | |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
| Octal Output | 1 | 1 | 8 | SPI_TRANS_MODE_OCT | |
+--------------+--------------------+--------------------+-----------------+----------------------------+ |
| OPI | 8 | 8 | 8 | SPI_TRANS_MODE_OCT | | SPICOMMON_BUSFLAG_OCTAL |
| | | | | SPI_TRANS_MULTILINE_ADDR | | |
| | | | | SPI_TRANS_MULTILINE_CMD | |
+--------------+--------------------+--------------------+-----------------+----------------------------+-------------------------+
Command and Address Phases
^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -152,6 +209,8 @@ During the command and address phases, the members :cpp:member:`cmd` and :cpp:me
If the lengths of the command and address phases need to be variable, declare the struct :cpp:type:`spi_transaction_ext_t`, set the flags :cpp:type:`SPI_TRANS_VARIABLE_CMD` and/or :cpp:type:`SPI_TRANS_VARIABLE_ADDR` in the member :cpp:member:`spi_transaction_ext_t::base` and configure the rest of base as usual. Then the length of each phase will be equal to :cpp:member:`command_bits` and :cpp:member:`address_bits` set in the struct :cpp:type:`spi_transaction_ext_t`.
If the command and address phase need to be as the same number of lines as data phase, you need to set `SPI_TRANS_MULTILINE_CMD` and/or `SPI_TRANS_MULTILINE_ADDR` to the `flags` member in the struct :cpp:type:`spi_transaction_t`. Also see :ref:`transaction-line-mode`.
Write and Read Phases
^^^^^^^^^^^^^^^^^^^^^
@@ -163,6 +222,8 @@ Normally, the data that needs to be transferred to or from a Device will be read
If these requirements are not satisfied, the transaction efficiency will be affected due to the allocation and copying of temporary buffers.
If using more than one data lines to transmit, please set `SPI_DEVICE_HALFDUPLEX` flag for the member `flags` in the struct :cpp:type:`spi_device_interface_config_t`. And the member `flags` in the struct :cpp:type:`spi_transaction_t` should be set as described in :ref:`transaction-line-mode`.
.. only:: esp32
.. note::

2
docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
View File

@@ -31,7 +31,7 @@ Introduction
------------
In the half duplex mode, the master has to use the protocol defined by the slave to communicate
with the slave. Each transaction may consists of the following phases (list by the order they
with the slave. Each transaction may consist of the following phases (list by the order they
should exist):
- Command: 8-bit, master to slave