fix(spi): correct some signals and dummy bits docs

2023-12-06 16:05:36 +08:00
parent a4bfa19ebd
commit 572a66b62e
9 changed files with 143 additions and 104 deletions
--- a/components/soc/esp32c2/spi_periph.c
+++ b/components/soc/esp32c2/spi_periph.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -12,29 +12,30 @@
 */
 const spi_signal_conn_t spi_periph_signal[SOC_SPI_PERIPH_NUM] = {
    {
-        .spiclk_out = SPICLK_OUT_MUX_IDX,
-        .spiclk_in = 0,/* SPI clock is not an input signal*/
-        .spid_out = SPID_OUT_IDX,
-        .spiq_out = SPIQ_OUT_IDX,
-        .spiwp_out = SPIWP_OUT_IDX,
-        .spihd_out = SPIHD_OUT_IDX,
-        .spid_in = SPID_IN_IDX,
-        .spiq_in = SPIQ_IN_IDX,
-        .spiwp_in = SPIWP_IN_IDX,
-        .spihd_in = SPIHD_IN_IDX,
-        .spics_out = {SPICS0_OUT_IDX, SPICS1_OUT_IDX},/* SPI0/1 do not have CS2 now */
-        .spics_in = 0,/* SPI cs is not an input signal*/
-        .spiclk_iomux_pin = SPI_IOMUX_PIN_NUM_CLK,
-        .spid_iomux_pin = SPI_IOMUX_PIN_NUM_MOSI,
-        .spiq_iomux_pin = SPI_IOMUX_PIN_NUM_MISO,
-        .spiwp_iomux_pin = SPI_IOMUX_PIN_NUM_WP,
-        .spihd_iomux_pin = SPI_IOMUX_PIN_NUM_HD,
-        .spics0_iomux_pin = SPI_IOMUX_PIN_NUM_CS,
-        .irq = ETS_SPI1_INTR_SOURCE,
+        // MSPI has dedicated iomux pins
+        .spiclk_out = -1,
+        .spiclk_in = -1,
+        .spid_out = -1,
+        .spiq_out = -1,
+        .spiwp_out = -1,
+        .spihd_out = -1,
+        .spid_in = -1,
+        .spiq_in = -1,
+        .spiwp_in = -1,
+        .spihd_in = -1,
+        .spics_out = {-1},
+        .spics_in = -1,
+        .spiclk_iomux_pin = -1,
+        .spid_iomux_pin = -1,
+        .spiq_iomux_pin = -1,
+        .spiwp_iomux_pin = -1,
+        .spihd_iomux_pin = -1,
+        .spics0_iomux_pin = -1,
+        .irq = -1,
        .irq_dma = -1,
-        .module = PERIPH_SPI_MODULE,
-        .hw = (spi_dev_t *) &SPIMEM1,
-        .func = SPI_FUNC_NUM,
+        .module = -1,
+        .hw = NULL,
+        .func = -1,
    }, {
        .spiclk_out = FSPICLK_OUT_IDX,
        .spiclk_in = FSPICLK_IN_IDX,
--- a/components/soc/esp32c3/spi_periph.c
+++ b/components/soc/esp32c3/spi_periph.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -12,29 +12,30 @@
 */
 const spi_signal_conn_t spi_periph_signal[SOC_SPI_PERIPH_NUM] = {
    {
-        .spiclk_out = SPICLK_OUT_MUX_IDX,
-        .spiclk_in = 0,/* SPI clock is not an input signal*/
-        .spid_out = SPID_OUT_IDX,
-        .spiq_out = SPIQ_OUT_IDX,
-        .spiwp_out = SPIWP_OUT_IDX,
-        .spihd_out = SPIHD_OUT_IDX,
-        .spid_in = SPID_IN_IDX,
-        .spiq_in = SPIQ_IN_IDX,
-        .spiwp_in = SPIWP_IN_IDX,
-        .spihd_in = SPIHD_IN_IDX,
-        .spics_out = {SPICS0_OUT_IDX, SPICS1_OUT_IDX},/* SPI0/1 do not have CS2 now */
-        .spics_in = 0,/* SPI cs is not an input signal*/
-        .spiclk_iomux_pin = SPI_IOMUX_PIN_NUM_CLK,
-        .spid_iomux_pin = SPI_IOMUX_PIN_NUM_MOSI,
-        .spiq_iomux_pin = SPI_IOMUX_PIN_NUM_MISO,
-        .spiwp_iomux_pin = SPI_IOMUX_PIN_NUM_WP,
-        .spihd_iomux_pin = SPI_IOMUX_PIN_NUM_HD,
-        .spics0_iomux_pin = SPI_IOMUX_PIN_NUM_CS,
-        .irq = ETS_SPI1_INTR_SOURCE,
+        // MSPI has dedicated iomux pins
+        .spiclk_out = -1,
+        .spiclk_in = -1,
+        .spid_out = -1,
+        .spiq_out = -1,
+        .spiwp_out = -1,
+        .spihd_out = -1,
+        .spid_in = -1,
+        .spiq_in = -1,
+        .spiwp_in = -1,
+        .spihd_in = -1,
+        .spics_out = {-1},
+        .spics_in = -1,
+        .spiclk_iomux_pin = -1,
+        .spid_iomux_pin = -1,
+        .spiq_iomux_pin = -1,
+        .spiwp_iomux_pin = -1,
+        .spihd_iomux_pin = -1,
+        .spics0_iomux_pin = -1,
+        .irq = -1,
        .irq_dma = -1,
-        .module = PERIPH_SPI_MODULE,
-        .hw = (spi_dev_t *) &SPIMEM1,
-        .func = SPI_FUNC_NUM,
+        .module = -1,
+        .hw = NULL,
+        .func = -1,
    }, {
        .spiclk_out = FSPICLK_OUT_IDX,
        .spiclk_in = FSPICLK_IN_IDX,
--- a/components/soc/esp32c6/include/soc/soc_caps.h
+++ b/components/soc/esp32c6/include/soc/soc_caps.h
@@ -371,7 +371,6 @@
 #define SOC_SDM_CLK_SUPPORT_PLL_F80M 1
 #define SOC_SDM_CLK_SUPPORT_XTAL     1

-// TODO: IDF-5334 (Copy from esp32c3, need check)
 /*-------------------------- SPI CAPS ----------------------------------------*/
 #define SOC_SPI_PERIPH_NUM          2
 #define SOC_SPI_PERIPH_CS_NUM(i)    6
--- a/components/soc/esp32c6/spi_periph.c
+++ b/components/soc/esp32c6/spi_periph.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -12,20 +12,31 @@
 */
 const spi_signal_conn_t spi_periph_signal[SOC_SPI_PERIPH_NUM] = {
    {
-        .spiclk_in = 0,/* SPI clock is not an input signal*/
-        .spics_in = 0,/* SPI cs is not an input signal*/
-        .spiclk_iomux_pin = SPI_IOMUX_PIN_NUM_CLK,
-        .spid_iomux_pin = SPI_IOMUX_PIN_NUM_MOSI,
-        .spiq_iomux_pin = SPI_IOMUX_PIN_NUM_MISO,
-        .spiwp_iomux_pin = SPI_IOMUX_PIN_NUM_WP,
-        .spihd_iomux_pin = SPI_IOMUX_PIN_NUM_HD,
-        .spics0_iomux_pin = SPI_IOMUX_PIN_NUM_CS,
-        .irq = ETS_MSPI_INTR_SOURCE,
+        // MSPI has dedicated iomux pins
+        .spiclk_out = -1,
+        .spiclk_in = -1,
+        .spid_out = -1,
+        .spiq_out = -1,
+        .spiwp_out = -1,
+        .spihd_out = -1,
+        .spid_in = -1,
+        .spiq_in = -1,
+        .spiwp_in = -1,
+        .spihd_in = -1,
+        .spics_out = {-1},
+        .spics_in = -1,
+        .spiclk_iomux_pin = -1,
+        .spid_iomux_pin = -1,
+        .spiq_iomux_pin = -1,
+        .spiwp_iomux_pin = -1,
+        .spihd_iomux_pin = -1,
+        .spics0_iomux_pin = -1,
+        .irq = -1,
        .irq_dma = -1,
-        .module = PERIPH_SPI_MODULE,
-        .hw = (spi_dev_t *) &SPIMEM1,
-        .func = SPI_FUNC_NUM,
-    }, { // TODO: IDF-5334 Need check
+        .module = -1,
+        .hw = NULL,
+        .func = -1,
+    }, {
        .spiclk_out = FSPICLK_OUT_IDX,
        .spiclk_in = FSPICLK_IN_IDX,
        .spid_out = FSPID_OUT_IDX,
--- a/components/soc/esp32h2/include/soc/soc_caps.h
+++ b/components/soc/esp32h2/include/soc/soc_caps.h
@@ -365,7 +365,6 @@
 #define SOC_SDM_CLK_SUPPORT_PLL_F48M 1
 #define SOC_SDM_CLK_SUPPORT_XTAL     1

-// TODO: IDF-6245 (Copy from esp32c6, need check)
 /*-------------------------- SPI CAPS ----------------------------------------*/
 #define SOC_SPI_PERIPH_NUM          2
 #define SOC_SPI_PERIPH_CS_NUM(i)    6
--- a/components/soc/esp32h2/spi_periph.c
+++ b/components/soc/esp32h2/spi_periph.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -11,20 +11,31 @@
 Bunch of constants for every SPI peripheral: GPIO signals, irqs, hw addr of registers etc
 */
 const spi_signal_conn_t spi_periph_signal[SOC_SPI_PERIPH_NUM] = {
-    {// ESP32H2-TODO: IDF-6245 Need check
-        .spiclk_in = 0,/* SPI clock is not an input signal*/
-        .spics_in = 0,/* SPI cs is not an input signal*/
-        .spiclk_iomux_pin = SPI_IOMUX_PIN_NUM_CLK,
-        .spid_iomux_pin = SPI_IOMUX_PIN_NUM_MOSI,
-        .spiq_iomux_pin = SPI_IOMUX_PIN_NUM_MISO,
-        .spiwp_iomux_pin = SPI_IOMUX_PIN_NUM_WP,
-        .spihd_iomux_pin = SPI_IOMUX_PIN_NUM_HD,
-        .spics0_iomux_pin = SPI_IOMUX_PIN_NUM_CS,
-        .irq = ETS_MSPI_INTR_SOURCE,
+    {
+        // MSPI has dedicated iomux pins
+        .spiclk_out = -1,
+        .spiclk_in = -1,
+        .spid_out = -1,
+        .spiq_out = -1,
+        .spiwp_out = -1,
+        .spihd_out = -1,
+        .spid_in = -1,
+        .spiq_in = -1,
+        .spiwp_in = -1,
+        .spihd_in = -1,
+        .spics_out = {-1},
+        .spics_in = -1,
+        .spiclk_iomux_pin = -1,
+        .spid_iomux_pin = -1,
+        .spiq_iomux_pin = -1,
+        .spiwp_iomux_pin = -1,
+        .spihd_iomux_pin = -1,
+        .spics0_iomux_pin = -1,
+        .irq = -1,
        .irq_dma = -1,
-        .module = PERIPH_SPI_MODULE,
-        .hw = (spi_dev_t *) &SPIMEM1,
-        .func = SPI_FUNC_NUM,
+        .module = -1,
+        .hw = NULL,
+        .func = -1,
    }, {
        .spiclk_out = FSPICLK_OUT_IDX,
        .spiclk_in = FSPICLK_IN_IDX,
--- a/components/soc/esp32s3/spi_periph.c
+++ b/components/soc/esp32s3/spi_periph.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -12,29 +12,30 @@
 */
 const spi_signal_conn_t spi_periph_signal[SOC_SPI_PERIPH_NUM] = {
    {
-        .spiclk_out = SPICLK_OUT_IDX,
-        .spiclk_in = 0,/* SPI clock is not an input signal*/
-        .spid_out = SPID_OUT_IDX,
-        .spiq_out = SPIQ_OUT_IDX,
-        .spiwp_out = SPIWP_OUT_IDX,
-        .spihd_out = SPIHD_OUT_IDX,
-        .spid_in = SPID_IN_IDX,
-        .spiq_in = SPIQ_IN_IDX,
-        .spiwp_in = SPIWP_IN_IDX,
-        .spihd_in = SPIHD_IN_IDX,
-        .spics_out = {SPICS0_OUT_IDX, SPICS1_OUT_IDX},/* SPI0/1 do not have CS2 now */
-        .spics_in = 0,/* SPI cs is not an input signal*/
-        .spiclk_iomux_pin = SPI_IOMUX_PIN_NUM_CLK,
-        .spid_iomux_pin = SPI_IOMUX_PIN_NUM_MOSI,
-        .spiq_iomux_pin = SPI_IOMUX_PIN_NUM_MISO,
-        .spiwp_iomux_pin = SPI_IOMUX_PIN_NUM_WP,
-        .spihd_iomux_pin = SPI_IOMUX_PIN_NUM_HD,
-        .spics0_iomux_pin = SPI_IOMUX_PIN_NUM_CS,
-        .irq = ETS_SPI1_INTR_SOURCE,
+        // MSPI has dedicated iomux pins
+        .spiclk_out = -1,
+        .spiclk_in = -1,
+        .spid_out = -1,
+        .spiq_out = -1,
+        .spiwp_out = -1,
+        .spihd_out = -1,
+        .spid_in = -1,
+        .spiq_in = -1,
+        .spiwp_in = -1,
+        .spihd_in = -1,
+        .spics_out = {-1},
+        .spics_in = -1,
+        .spiclk_iomux_pin = -1,
+        .spid_iomux_pin = -1,
+        .spiq_iomux_pin = -1,
+        .spiwp_iomux_pin = -1,
+        .spihd_iomux_pin = -1,
+        .spics0_iomux_pin = -1,
+        .irq = -1,
        .irq_dma = -1,
-        .module = PERIPH_SPI_MODULE,
-        .hw = (spi_dev_t *) &SPIMEM1,
-        .func = SPI_FUNC_NUM,
+        .module = -1,
+        .hw = NULL,
+        .func = -1,
    }, {
        .spiclk_out = FSPICLK_OUT_IDX,
        .spiclk_in = FSPICLK_IN_IDX,
--- a/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
+++ b/docs/en/api-reference/protocols/esp_spi_slave_protocol.rst
@@ -43,9 +43,17 @@ In the half duplex mode, the master has to use the protocol defined by the slave

    For some commands (WRBUF, RDBUF), this phase specifies the address of the shared register to write to/read from. For other commands with this phase, they are meaningless but still have to exist in the transaction.

- Dummy: 8-bit, floating, optional
+.. only:: esp32s2

-    This phase is the turnaround time between the master and the slave on the bus, and also provides enough time for the slave to prepare the data to send to the master.
+    - Dummy: 8-bit (for 1-bit mode) or 4-bit (for 2/4-bit mode), floating, optional
+
+        This phase is the turnaround time between the master and the slave on the bus, and also provides enough time for the slave to prepare the data to send to the master.
+
+.. only:: not esp32s2
+
+    - Dummy: 8-bit, floating, optional
+
+        This phase is the turnaround time between the master and the slave on the bus, and also provides enough time for the slave to prepare the data to send to the master.

 - Data: variable length, the direction is also determined by the command.

--- a/docs/zh_CN/api-reference/protocols/esp_spi_slave_protocol.rst
+++ b/docs/zh_CN/api-reference/protocols/esp_spi_slave_protocol.rst
@@ -43,9 +43,17 @@ ESP SPI 从机 HD（半双工）模式协议

    对于某些命令（如 WRBUF、RDBUF），此阶段指定要写入/读取的共享寄存器地址。对于其他包括此阶段的命令，这没有实际意义，但仍必须存在于事务中。

- Dummy 阶段：8 位，浮动，可选
+.. only:: esp32s2

-    此阶段是主机和从机在总线上的周转时间，并为从机向主机发送数据提供了充分的准备时间。
+    - Dummy 阶段：8 位 (1线模式) 或 4 位 (2/4线模式)，浮动，可选
+
+        此阶段是主机和从机在总线上的周转时间，并为从机向主机发送数据提供了充分的准备时间。
+
+.. only:: not esp32s2
+
+    - Dummy 阶段：8 位，浮动，可选
+
+        此阶段是主机和从机在总线上的周转时间，并为从机向主机发送数据提供了充分的准备时间。

 - 数据阶段：长度可变，方向由命令确定。

@@ -59,7 +67,7 @@ ESP SPI 从机 HD（半双工）模式协议
 在某些 IO 模式下，可以使用更多数据线来发送数据。因此，与 1 位模式相比，发送相同数据量所需的 SPI 时钟周期更少。例如，在 QIO 模式下，地址和数据（IN 和 OUT）应发送到全部 4 条数据线上（MOSI、MISO、WP 和 HD）。下表展示了 ESP32-S2 SPI 从机支持的模式，以及相应模式下使用的数据线数量。

 +-------+----------+----------+------------+----------+
-| Mode  | 命令线数 | 地址线数 | dummy 次数 | 数据线数 |
+| Mode  | 命令线数 | 地址线数 | dummy 线数 | 数据线数 |
 +-------+----------+----------+------------+----------+
 | 1-bit | 1        | 1        | 1          | 1        |
 +-------+----------+----------+------------+----------+