Merge branch 'feat/spi_slave_hd_esp32s2' into 'master'

spi_slave_hd: new driver for spi slave in half duplex mode

Closes IDF-1589

See merge request espressif/esp-idf!8386

Author: ginkgm

components/driver/CMakeLists.txt

@@ -40,7 +40,9 @@ if(IDF_TARGET STREQUAL "esp32s2")
     list(APPEND srcs "esp32s2/rtc_tempsensor.c"
                      "esp32s2/touch_sensor.c"
                      "esp32s2/adc.c"
-                     "esp32s2/adc2_init_cal.c")
+                     "esp32s2/adc2_init_cal.c"
+                     "spi_slave_hd.c"
+                    )
     # currently only S2 beta has its own target-specific includes
     list(APPEND includes "esp32s2/include")
 endif()

components/driver/component.mk

@@ -2,6 +2,7 @@
 # Component Makefile
 #
 COMPONENT_SRCDIRS := . $(IDF_TARGET)
+COMPONENT_OBJEXCLUDE += spi_slave_hd.o
 
 COMPONENT_ADD_INCLUDEDIRS := include $(IDF_TARGET)/include $(IDF_TARGET)/include/driver
 

components/driver/include/driver/spi_common.h

@@ -62,11 +62,12 @@ extern "C"
 #define SPICOMMON_BUSFLAG_SLAVE         0          ///< Initialize I/O in slave mode
 #define SPICOMMON_BUSFLAG_MASTER        (1<<0)     ///< Initialize I/O in master mode
 #define SPICOMMON_BUSFLAG_IOMUX_PINS    (1<<1)     ///< Check using iomux pins. Or indicates the pins are configured through the IO mux rather than GPIO matrix.
-#define SPICOMMON_BUSFLAG_SCLK          (1<<2)     ///< Check existing of SCLK pin. Or indicates CLK line initialized.
-#define SPICOMMON_BUSFLAG_MISO          (1<<3)     ///< Check existing of MISO pin. Or indicates MISO line initialized.
-#define SPICOMMON_BUSFLAG_MOSI          (1<<4)     ///< Check existing of MOSI pin. Or indicates CLK line initialized.
-#define SPICOMMON_BUSFLAG_DUAL          (1<<5)     ///< Check MOSI and MISO pins can output. Or indicates bus able to work under DIO mode.
-#define SPICOMMON_BUSFLAG_WPHD          (1<<6)     ///< Check existing of WP and HD pins. Or indicates WP & HD pins initialized.
+#define SPICOMMON_BUSFLAG_GPIO_PINS     (1<<2)     ///< Force the signals to be routed through GPIO matrix. Or indicates the pins are routed through the GPIO matrix.
+#define SPICOMMON_BUSFLAG_SCLK          (1<<3)     ///< Check existing of SCLK pin. Or indicates CLK line initialized.
+#define SPICOMMON_BUSFLAG_MISO          (1<<4)     ///< Check existing of MISO pin. Or indicates MISO line initialized.
+#define SPICOMMON_BUSFLAG_MOSI          (1<<5)     ///< Check existing of MOSI pin. Or indicates MOSI line initialized.
+#define SPICOMMON_BUSFLAG_DUAL          (1<<6)     ///< Check MOSI and MISO pins can output. Or indicates bus able to work under DIO mode.
+#define SPICOMMON_BUSFLAG_WPHD          (1<<7)     ///< Check existing of WP and HD pins. Or indicates WP & HD pins initialized.
 #define SPICOMMON_BUSFLAG_QUAD          (SPICOMMON_BUSFLAG_DUAL|SPICOMMON_BUSFLAG_WPHD)     ///< Check existing of MOSI/MISO/WP/HD pins as output. Or indicates bus able to work under QIO mode.
 
 #define SPICOMMON_BUSFLAG_NATIVE_PINS   SPICOMMON_BUSFLAG_IOMUX_PINS

components/driver/include/driver/spi_slave_hd.h

@@ -0,0 +1,168 @@
+// Copyright 2010-2020 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "esp_types.h"
+#include "soc/spi_caps.h"
+#include "freertos/FreeRTOS.h"
+
+#include "hal/spi_types.h"
+#include "driver/spi_common.h"
+#include "sdkconfig.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#if !SOC_SPI_SUPPORT_SLAVE_HD_VER2  && !CI_HEADER_CHECK
+#error The SPI peripheral does not support this feature
+#endif
+
+/// Descriptor of data to send/receive
+typedef struct {
+    uint8_t*    data;       ///< Buffer to send, must be DMA capable
+    size_t      len;        ///< Len of data to send/receive. For receiving the buffer length should be multiples of 4 bytes, otherwise the extra part will be truncated.
+    size_t      trans_len;  ///< Data actually received
+    void*       arg;        ///< Extra argument indiciating this data
+} spi_slave_hd_data_t;
+
+/// Information of SPI Slave HD event
+typedef struct {
+    spi_event_t event;          ///< Event type
+    spi_slave_hd_data_t* trans; ///< Corresponding transaction for SPI_EV_SEND and SPI_EV_RECV events
+} spi_slave_hd_event_t;
+
+/// Callback for SPI Slave HD
+typedef bool (*slave_cb_t)(void* arg, spi_slave_hd_event_t* event, BaseType_t* awoken);
+
+/// Channel of SPI Slave HD to do data transaction
+typedef enum {
+    SPI_SLAVE_CHAN_TX = 0,  ///< The output channel (RDDMA)
+    SPI_SLAVE_CHAN_RX = 1,  ///< The input channel (WRDMA)
+} spi_slave_chan_t;
+
+/// Callback configuration structure for SPI Slave HD
+typedef struct {
+    slave_cb_t cb_recv;         ///< Callback when receive data
+    slave_cb_t cb_sent;         ///< Callback when data sent
+    slave_cb_t cb_buffer_tx;    ///< Callback when master reads from shared buffer
+    slave_cb_t cb_buffer_rx;    ///< Callback when master writes to shared buffer
+    slave_cb_t cb_cmd9;         ///< Callback when CMD9 received
+    slave_cb_t cb_cmdA;         ///< Callback when CMDA received
+    void* arg;                  ///< Argument indicating this SPI Slave HD peripheral instance
+} spi_slave_hd_callback_config_t;
+
+/// Configuration structure for the SPI Slave HD driver
+typedef struct {
+    int spics_io_num;               ///< CS GPIO pin for this device
+    uint32_t flags;                 ///< Bitwise OR of SPI_SLAVE_HD_* flags
+#define SPI_SLAVE_HD_TXBIT_LSBFIRST          (1<<0)  ///< Transmit command/address/data LSB first instead of the default MSB first
+#define SPI_SLAVE_HD_RXBIT_LSBFIRST          (1<<1)  ///< Receive data LSB first instead of the default MSB first
+#define SPI_SLAVE_HD_BIT_LSBFIRST            (SPI_SLAVE_HD_TXBIT_LSBFIRST|SPI_SLAVE_HD_RXBIT_LSBFIRST) ///< Transmit and receive LSB first
+
+    uint8_t mode;                   ///< SPI mode (0-3)
+    int     command_bits;           ///< command field bits, multiples of 8 and at least 8.
+    int     address_bits;           ///< address field bits, multiples of 8 and at least 8.
+    int     dummy_bits;             ///< dummy field bits, multiples of 8 and at least 8.
+
+    int     queue_size;             ///< Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_slave_hd_queue_trans but not yet finished using spi_slave_hd_get_trans_result) at the same time
+
+    int dma_chan;                   ///< DMA channel used
+    spi_slave_hd_callback_config_t cb_config; ///< Callback configuration
+} spi_slave_hd_slot_config_t;
+
+/**
+ * @brief Initialize the SPI Slave HD driver.
+ *
+ * @param host_id       The host to use
+ * @param bus_config    Bus configuration for the bus used
+ * @param config        Configuration for the SPI Slave HD driver
+ * @return
+ *  - ESP_OK: on success
+ *  - ESP_ERR_INVALID_ARG: invalid argument given
+ *  - ESP_ERR_INVALID_STATE: function called in invalid state, may be some resources are already in use
+ *  - ESP_ERR_NO_MEM: memory allocation failed
+ *  - or other return value from `esp_intr_alloc`
+ */
+esp_err_t spi_slave_hd_init(spi_host_device_t host_id, const spi_bus_config_t *bus_config,
+                            const spi_slave_hd_slot_config_t *config);
+
+/**
+ * @brief Deinitialize the SPI Slave HD driver
+ *
+ * @param host_id The host to deinitialize the driver
+ * @return
+ *  - ESP_OK: on success
+ *  - ESP_ERR_INVALID_ARG: if the host_id is not correct
+ */
+esp_err_t spi_slave_hd_deinit(spi_host_device_t host_id);
+
+/**
+ * @brief Queue data transaction
+ *
+ * @param host_id   Host to queue the transaction
+ * @param chan      Channel to queue the data, SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
+ * @param trans     Descriptor of data to queue
+ * @param timeout   Timeout before the data is queued
+ * @return
+ *  - ESP_OK: on success
+ *  - ESP_ERR_INVALID_ARG: The input argument is invalid. Can be the following reason:
+ *      - The buffer given is not DMA capable
+ *      - The length of data is invalid (not larger than 0, or exceed the max transfer length)
+ *      - The function is invalid
+ *  - ESP_ERR_TIMEOUT: Cannot queue the data before timeout. This is quite possible if the master
+ *    doesn't read/write the slave on time.
+ */
+esp_err_t spi_slave_hd_queue_trans(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t* trans, TickType_t timeout);
+
+/**
+ * @brief Get the result of a data transaction
+ *
+ * @param host_id   Host to queue the transaction
+ * @param chan      Channel to get the result, SPI_SLAVE_CHAN_TX or SPI_SLAVE_CHAN_RX
+ * @param[out] out_trans Output descriptor of the returned transaction
+ * @param timeout   Timeout before the result is got
+ * @return
+ *  - ESP_OK: on success
+ *  - ESP_ERR_INVALID_ARG: Function is not valid
+ *  - ESP_ERR_TIMEOUT: There's no transaction done before timeout
+ */
+esp_err_t spi_slave_hd_get_trans_res(spi_host_device_t host_id, spi_slave_chan_t chan, spi_slave_hd_data_t** out_trans, TickType_t timeout);
+
+/**
+ * @brief Read the shared registers
+ *
+ * @param host_id   Host to read the shared registers
+ * @param addr      Address of register to read, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1``
+ * @param[out] out_data Output buffer to store the read data
+ * @param len       Length to read, not larger than ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr``
+ */
+void spi_slave_hd_read_buffer(spi_host_device_t host_id, int addr, uint8_t *out_data, size_t len);
+
+/**
+ * @brief Write the shared registers
+ *
+ * @param host_id   Host to write the shared registers
+ * @param addr      Address of register to write, 0 to ``SOC_SPI_MAXIMUM_BUFFER_SIZE-1``
+ * @param data      Buffer holding the data to write
+ * @param len       Length to write, ``SOC_SPI_MAXIMUM_BUFFER_SIZE-addr``
+ */
+void spi_slave_hd_write_buffer(spi_host_device_t host_id, int addr, uint8_t *data, size_t len);
+
+
+#ifdef __cplusplus
+}
+#endif

components/driver/spi_common.c

@@ -268,8 +268,12 @@ esp_err_t spicommon_bus_initialize_io(spi_host_device_t host, const spi_bus_conf
     }
 
     //check if the selected pins correspond to the iomux pins of the peripheral
-    bool use_iomux = bus_uses_iomux_pins(host, bus_config);
-    if (use_iomux) temp_flag |= SPICOMMON_BUSFLAG_IOMUX_PINS;
+    bool use_iomux = !(flags & SPICOMMON_BUSFLAG_GPIO_PINS) && bus_uses_iomux_pins(host, bus_config);
+    if (use_iomux) {
+        temp_flag |= SPICOMMON_BUSFLAG_IOMUX_PINS;
+    } else {
+        temp_flag |= SPICOMMON_BUSFLAG_GPIO_PINS;
+    }
 
     uint32_t missing_flag = flags & ~temp_flag;
     missing_flag &= ~SPICOMMON_BUSFLAG_MASTER;//don't check this flag