feat(spi_master): p4 document update

espressif · Oct 8, 2023 · fc20b96 · fc20b96
1 parent eb75aa4
commit fc20b96
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 85 deletions.
diff --git a/docs/docs_not_updated/esp32p4.txt b/docs/docs_not_updated/esp32p4.txt
@@ -117,7 +117,6 @@ api-reference/peripherals/ana_cmpr.rst
 api-reference/peripherals/secure_element.rst
 api-reference/peripherals/ledc.rst
 api-reference/peripherals/temp_sensor.rst
-api-reference/peripherals/spi_features.rst
 api-reference/peripherals/sdio_slave.rst
 api-reference/peripherals/clk_tree.rst
 api-reference/peripherals/spi_flash/xip_from_psram.inc
@@ -136,7 +135,6 @@ api-reference/peripherals/ds.rst
 api-reference/peripherals/i2c.rst
 api-reference/peripherals/dedic_gpio.rst
 api-reference/peripherals/sd_pullup_requirements.rst
-api-reference/peripherals/spi_master.rst
 api-reference/peripherals/index.rst
 api-reference/peripherals/sdmmc_host.rst
 api-reference/peripherals/uart.rst

diff --git a/docs/en/api-reference/peripherals/spi_master.rst b/docs/en/api-reference/peripherals/spi_master.rst
@@ -8,7 +8,7 @@ SPI Master driver is a program that controls {IDF_TARGET_NAME}'s General Purpose
 .. only:: esp32
 
     .. note::
-    
+
         SPI1 is not a GP-SPI. SPI Master driver also supports SPI1 but with quite a few limitations, see :ref:`spi_master_on_spi1_bus`.
 
 For more hardware information about the GP-SPI peripheral(s), see **{IDF_TARGET_NAME} Technical Reference Manual** > **SPI Controller** [`PDF <{IDF_TARGET_TRM_EN_URL}#spi>`__].
@@ -182,28 +182,28 @@ Supported line modes for {IDF_TARGET_NAME} are listed as follows, to make use of
          - 1
          - 1
          - 2
-         - {SPI_TRANS_MODE_DIO}
-         - {SPICOMMON_BUSFLAG_DUAL}
+         - SPI_TRANS_MODE_DIO
+         - SPICOMMON_BUSFLAG_DUAL
        * - Dual I/O
          - 1
          - 2
          - 2
-         - * {SPI_TRANS_MODE_DIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         -
+         - SPI_TRANS_MODE_DIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_DUAL
        * - Quad Output
          - 1
          - 1
          - 4
-         - {SPI_TRANS_MODE_QIO}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+         - SPICOMMON_BUSFLAG_QUAD
        * - Quad I/O
          - 1
          - 4
          - 4
-         - * {SPI_TRANS_MODE_QIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_QUAD
 
 .. only:: SOC_SPI_SUPPORT_OCT
 
@@ -227,42 +227,42 @@ Supported line modes for {IDF_TARGET_NAME} are listed as follows, to make use of
          - 1
          - 1
          - 2
-         - {SPI_TRANS_MODE_DIO}
-         - {SPICOMMON_BUSFLAG_DUAL}
+         - SPI_TRANS_MODE_DIO
+         - SPICOMMON_BUSFLAG_DUAL
        * - Dual I/O
          - 1
          - 2
          - 2
-         - * {SPI_TRANS_MODE_DIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         -
+         - SPI_TRANS_MODE_DIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_DUAL
        * - Quad Output
          - 1
          - 1
          - 4
-         - {SPI_TRANS_MODE_QIO}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+         - SPICOMMON_BUSFLAG_QUAD
        * - Quad I/O
          - 1
          - 4
          - 4
-         - * {SPI_TRANS_MODE_QIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_QUAD
        * - Octal Output
          - 1
          - 1
          - 8
-         - {SPI_TRANS_MODE_OCT}
-         - {SPICOMMON_BUSFLAG_OCTAL}
+         - SPI_TRANS_MODE_OCT
+         - SPICOMMON_BUSFLAG_OCTAL
        * - OPI
          - 8
          - 8
          - 8
-         - * {SPI_TRANS_MODE_OCT}
-           * {SPI_TRANS_MULTILINE_ADDR}
-           * {SPI_TRANS_MULTILINE_CMD}
-         - {SPICOMMON_BUSFLAG_OCTAL} 
+         - SPI_TRANS_MODE_OCT
+           SPI_TRANS_MULTILINE_ADDR
+           SPI_TRANS_MULTILINE_CMD
+         - SPICOMMON_BUSFLAG_OCTAL
 
 Command and Address Phases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -292,7 +292,7 @@ If using more than one data line to transmit, please set ``SPI_DEVICE_HALFDUPLEX
 
         Half-duplex transactions with both Read and Write phases are not supported when using DMA. For details and workarounds, see :ref:`spi_known_issues`.
 
-.. only:: esp32s3 or esp32c3 or esp32c2 or esp32c6 or esp32h2
+.. only:: not SOC_SPI_HD_BOTH_INOUT_SUPPORTED
 
     .. note::
 
@@ -455,7 +455,7 @@ GPIO Matrix and IO_MUX
        * - CS0 [1]_
          - 15
          - 5
-       * - SCLK 
+       * - SCLK
          - 14
          - 18
        * - MISO
@@ -469,16 +469,16 @@ GPIO Matrix and IO_MUX
          - 22
        * - QUADHD
          - 4
-         - 21  
+         - 21
 
 .. only:: not esp32
 
-    {IDF_TARGET_SPI2_IOMUX_PIN_CS:default="N/A",   esp32s2="10", esp32s3="10", esp32c2="10", esp32c3="10", esp32c6="16", esp32h2="1"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_CLK:default="N/A",  esp32s2="12", esp32s3="12", esp32c2="6",  esp32c3="6",  esp32c6="6",  esp32h2="4"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_MOSI:default="N/A", esp32s2="11"  esp32s3="11", esp32c2="7"   esp32c3="7",  esp32c6="7",  esp32h2="5"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_MISO:default="N/A", esp32s2="13"  esp32s3="13", esp32c2="2"   esp32c3="2",  esp32c6="2",  esp32h2="0"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_HD:default="N/A",   esp32s2="9"   esp32s3="9",  esp32c2="4"   esp32c3="4",  esp32c6="4",  esp32h2="3"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_WP:default="N/A",   esp32s2="14"  esp32s3="14", esp32c2="5"   esp32c3="5",  esp32c6="5",  esp32h2="2"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_CS:default="N/A",   esp32s2="10", esp32s3="10", esp32c2="10", esp32c3="10", esp32c6="16", esp32h2="1", esp32p4="7"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_CLK:default="N/A",  esp32s2="12", esp32s3="12", esp32c2="6",  esp32c3="6",  esp32c6="6",  esp32h2="4", esp32p4="9"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MOSI:default="N/A", esp32s2="11"  esp32s3="11", esp32c2="7"   esp32c3="7",  esp32c6="7",  esp32h2="5", esp32p4="8"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MISO:default="N/A", esp32s2="13"  esp32s3="13", esp32c2="2"   esp32c3="2",  esp32c6="2",  esp32h2="0", esp32p4="10"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_HD:default="N/A",   esp32s2="9"   esp32s3="9",  esp32c2="4"   esp32c3="4",  esp32c6="4",  esp32h2="3", esp32p4="6"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_WP:default="N/A",   esp32s2="14"  esp32s3="14", esp32c2="5"   esp32c3="5",  esp32c6="5",  esp32h2="2", esp32p4="11"}
 
     Most of the chip's peripheral signals have a direct connection to their dedicated IO_MUX pins. However, the signals can also be routed to any other available pins using the less direct GPIO matrix. If at least one signal is routed through the GPIO matrix, then all signals will be routed through it.
 
@@ -639,7 +639,7 @@ For an interrupt transaction, the overall cost is **20+8n/Fspi[MHz]** [µs] for
      - 25
      - 128
      - 153
-     - 836.6  
+     - 836.6
 
 When a transaction length is short, the cost of the transaction interval is high. If possible, try to squash several short transactions into one transaction to achieve a higher transfer speed.
 
@@ -769,10 +769,8 @@ Please note that the ISR is disabled during flash operation by default. To keep
          - 11.43
        * - 75
          - 100
-         - 8.89   
-
+         - 8.89
 
-.. only:: esp32
 
     .. _spi_known_issues:
 
@@ -802,6 +800,7 @@ Application Example
 
 The code example for using the SPI master half duplex mode to read/write an AT93C46D EEPROM (8-bit mode) can be found in the :example:`peripherals/spi_master/hd_eeprom` directory of ESP-IDF examples.
 
+The code example for using the SPI master full duplex mode to drive a SPI_LCD (e.g. ST7789V or ILI9341) can be found in the :example:`peripherals/spi_master/lcd` directory of ESP-IDF examples.
 
 API Reference - SPI Common
 --------------------------

diff --git a/docs/zh_CN/api-reference/peripherals/spi_master.rst b/docs/zh_CN/api-reference/peripherals/spi_master.rst
@@ -8,7 +8,7 @@ SPI 主机驱动程序是一个软件程序，用于在 {IDF_TARGET_NAME} 的通
 .. only:: esp32
 
     .. note::
-    
+
         SPI1 不属于 GP-SPI。SPI 主机驱动程序也支持 SPI1。但在 SPI1 总线上使用 SPI 主机驱动程序存在诸多限制，请参阅 :ref:`spi_master_on_spi1_bus`。
 
 有关 GP-SPI 硬件相关信息，请参考 **{IDF_TARGET_NAME} 技术参考手册** > **SPI 控制器** [`PDF <{IDF_TARGET_TRM_CN_URL}#spi>`__]。
@@ -182,28 +182,28 @@ SPI 总线传输事务由五个阶段构成，详见下表（任意阶段均可
          - 1
          - 1
          - 2
-         - {SPI_TRANS_MODE_DIO}
-         - {SPICOMMON_BUSFLAG_DUAL}
+         - SPI_TRANS_MODE_DIO
+         - SPICOMMON_BUSFLAG_DUAL
        * - 双线 I/O 模式
          - 1
          - 2
          - 2
-         - * {SPI_TRANS_MODE_DIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         -
+         - SPI_TRANS_MODE_DIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_DUAL
        * - 四线输出模式
          - 1
          - 1
          - 4
-         - {SPI_TRANS_MODE_QIO}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+         - SPICOMMON_BUSFLAG_QUAD
        * - 四线 I/O 模式
          - 1
          - 4
          - 4
-         - * {SPI_TRANS_MODE_QIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_QUAD
 
 .. only:: SOC_SPI_SUPPORT_OCT
 
@@ -227,42 +227,42 @@ SPI 总线传输事务由五个阶段构成，详见下表（任意阶段均可
          - 1
          - 1
          - 2
-         - {SPI_TRANS_MODE_DIO}
-         - {SPICOMMON_BUSFLAG_DUAL}
+         - SPI_TRANS_MODE_DIO
+         - SPICOMMON_BUSFLAG_DUAL
        * - 双线 I/O 模式
          - 1
          - 2
          - 2
-         - * {SPI_TRANS_MODE_DIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         -
+         - SPI_TRANS_MODE_DIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_DUAL
        * - 四线输出模式
          - 1
          - 1
          - 4
-         - {SPI_TRANS_MODE_QIO}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+         - SPICOMMON_BUSFLAG_QUAD
        * - 四线 I/O 模式
          - 1
          - 4
          - 4
-         - * {SPI_TRANS_MODE_QIO}
-           * {SPI_TRANS_MULTILINE_ADDR}
-         - {SPICOMMON_BUSFLAG_QUAD}
+         - SPI_TRANS_MODE_QIO
+           SPI_TRANS_MULTILINE_ADDR
+         - SPICOMMON_BUSFLAG_QUAD
        * - 八线输出模式
          - 1
          - 1
          - 8
-         - {SPI_TRANS_MODE_OCT}
-         - {SPICOMMON_BUSFLAG_OCTAL}
+         - SPI_TRANS_MODE_OCT
+         - SPICOMMON_BUSFLAG_OCTAL
        * - OPI 模式
          - 8
          - 8
          - 8
-         - * {SPI_TRANS_MODE_OCT}
-           * {SPI_TRANS_MULTILINE_ADDR}
-           * {SPI_TRANS_MULTILINE_CMD}
-         - {SPICOMMON_BUSFLAG_OCTAL}
+         - SPI_TRANS_MODE_OCT
+           SPI_TRANS_MULTILINE_ADDR
+           SPI_TRANS_MULTILINE_CMD
+         - SPICOMMON_BUSFLAG_OCTAL
 
 命令阶段和地址阶段
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -292,7 +292,7 @@ SPI 总线传输事务由五个阶段构成，详见下表（任意阶段均可
 
         当启用 DMA 时，不支持同时具有读取阶段和写入阶段的半双工传输事务。有关细节和解决方法，请参阅 :ref:`spi_known_issues`。
 
-.. only:: esp32s3 or esp32c3 or esp32c2 or esp32c6 or esp32h2
+.. only:: not SOC_SPI_HD_BOTH_INOUT_SUPPORTED
 
     .. note::
 
@@ -364,7 +364,7 @@ SPI 主机逐字节地将数据读入和写入内存。默认情况下，数据
 在某些情况下，要传输的数据大小与 ``uint8_t`` 数组不同，可使用以下宏将数据转换为可由 SPI 驱动直接发送的格式：
 
 - 需传输的数据，使用 :c:macro:`SPI_SWAP_DATA_TX`
-- 接收到的数据，使用 :c:macro:`SPI_SWAP_DATA_RX` 
+- 接收到的数据，使用 :c:macro:`SPI_SWAP_DATA_RX`
 
 
 .. _mixed_transactions:
@@ -393,7 +393,7 @@ ISR 会干扰飞行中的轮询传输事务，以适应中断传输事务。在
 
         因具备 :ref:`spi_bus_lock` 特性，SPI 主机驱动程序可在 SPI1 总线上运行，但该过程十分棘手，且需要许多特殊处理。这是一个适合高级开发者的功能。
 
-    要在 SPI1 总线上运行 SPI 主机驱动程序，需注意以下两个问题： 
+    要在 SPI1 总线上运行 SPI 主机驱动程序，需注意以下两个问题：
 
     1. 当驱动在 SPI1 上运行时，代码和数据应在内部存储器中。
 
@@ -455,7 +455,7 @@ GPIO 矩阵与 IO_MUX 管脚
        * - CS0 [1]_
          - 15
          - 5
-       * - SCLK 
+       * - SCLK
          - 14
          - 18
        * - MISO
@@ -469,16 +469,16 @@ GPIO 矩阵与 IO_MUX 管脚
          - 22
        * - QUADHD
          - 4
-         - 21  
+         - 21
 
 .. only:: not esp32
 
-    {IDF_TARGET_SPI2_IOMUX_PIN_CS:default="N/A",   esp32s2="10", esp32s3="10", esp32c2="10", esp32c3="10", esp32c6="16", esp32h2="1"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_CLK:default="N/A",  esp32s2="12", esp32s3="12", esp32c2="6",  esp32c3="6",  esp32c6="6",  esp32h2="4"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_MOSI:default="N/A", esp32s2="11"  esp32s3="11", esp32c2="7"   esp32c3="7",  esp32c6="7",  esp32h2="5"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_MISO:default="N/A", esp32s2="13"  esp32s3="13", esp32c2="2"   esp32c3="2",  esp32c6="2",  esp32h2="0"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_HD:default="N/A",   esp32s2="9"   esp32s3="9",  esp32c2="4"   esp32c3="4",  esp32c6="4",  esp32h2="3"}
-    {IDF_TARGET_SPI2_IOMUX_PIN_WP:default="N/A",   esp32s2="14"  esp32s3="14", esp32c2="5"   esp32c3="5",  esp32c6="5",  esp32h2="2"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_CS:default="N/A",   esp32s2="10", esp32s3="10", esp32c2="10", esp32c3="10", esp32c6="16", esp32h2="1", esp32p4="7"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_CLK:default="N/A",  esp32s2="12", esp32s3="12", esp32c2="6",  esp32c3="6",  esp32c6="6",  esp32h2="4", esp32p4="9"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MOSI:default="N/A", esp32s2="11"  esp32s3="11", esp32c2="7"   esp32c3="7",  esp32c6="7",  esp32h2="5", esp32p4="8"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MISO:default="N/A", esp32s2="13"  esp32s3="13", esp32c2="2"   esp32c3="2",  esp32c6="2",  esp32h2="0", esp32p4="10"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_HD:default="N/A",   esp32s2="9"   esp32s3="9",  esp32c2="4"   esp32c3="4",  esp32c6="4",  esp32h2="3", esp32p4="6"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_WP:default="N/A",   esp32s2="14"  esp32s3="14", esp32c2="5"   esp32c3="5",  esp32c6="5",  esp32h2="2", esp32p4="11"}
 
     芯片的大多数外围信号都与之专用的 IO_MUX 管脚连接，但这些信号也可以通过较不直接的 GPIO 矩阵路由到任何其他可用的管脚。只要有一个信号是通过 GPIO 矩阵路由的，那么所有的信号都将通过它路由。
 
@@ -639,7 +639,7 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_handle_t::cfg
      - 25
      - 128
      - 153
-     - 836.6  
+     - 836.6
 
 传输事务长度较短时将提高传输事务间隔成本，因此应尽可能将几个短传输事务压缩成一个传输事务，以提升传输速度。
 
@@ -721,7 +721,7 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_handle_t::cfg
        * - 使用 IO_MUX 的 ESP32 从机设备
          - 50
        * - 使用 GPIO_MATRIX 的 ESP32 从机设备
-         - 75 
+         - 75
 
     MISO 路径延迟（有效时间）由从机的 **输入延迟** 与主机的 **GPIO 矩阵延迟** 组成。该延迟决定了频率限制，超过这个频率的全双工传输将无法如半双工交易中使用的 Dummy 位一样工作。该频率限制的计算方法为：
 
@@ -769,10 +769,8 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_handle_t::cfg
          - 11.43
        * - 75
          - 100
-         - 8.89   
-
+         - 8.89
 
-.. only:: esp32
 
     .. _spi_known_issues:
 
@@ -802,6 +800,7 @@ GPSPI 外设的时钟源可以通过设置 :cpp:member:`spi_device_handle_t::cfg
 
 查看使用 SPI 主机驱动程序在半双工模式下读取/写入 AT93C46D EEPROM（8 位模式）的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_master/hd_eeprom` 目录。
 
+查看使用 SPI 主机驱动程序在全双工模式下驱动 LCD 屏幕（如 ST7789V 或 ILI9341）的示例代码，请前往 ESP-IDF 示例的 :example:`peripherals/spi_master/lcd` 目录。
 
 API 参考 - SPI Common
 --------------------------