Rename SPI Master IO pins to more common terminology, add better explanation to queue_length initialization value

components/driver/include/driver/spi_master.h

@@ -46,11 +46,11 @@ typedef enum {
  * the IO_MUX or are -1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
  */
 typedef struct {
-    int spid_io_num;                ///< GPIO pin for spi_d (=MOSI)signal, or -1 if not used.
-    int spiq_io_num;                ///< GPIO pin for spi_q (=MISO) signal, or -1 if not used.
-    int spiclk_io_num;              ///< GPIO pin for spi_clk signal, or -1 if not used.
-    int spiwp_io_num;               ///< GPIO pin for spi_wp signal, or -1 if not used.
-    int spihd_io_num;               ///< GPIO pin for spi_hd signal, or -1 if not used.
+    int mosi_io_num;                ///< GPIO pin for Master Out Slave In (=spi_d) signal, or -1 if not used.
+    int miso_io_num;                ///< GPIO pin for Master In Slave Out (=spi_q) signal, or -1 if not used.
+    int sclk_io_num;                ///< GPIO pin for Spi CLocK signal, or -1 if not used.
+    int quadwp_io_num;              ///< GPIO pin for WP (Write Protect) signal which is used as D2 in 4-bit communication modes, or -1 if not used.
+    int quadhd_io_num;              ///< GPIO pin for HD (HolD) signal which is used as D3 in 4-bit communication modes, or -1 if not used.
 } spi_bus_config_t;
 
 
@@ -80,7 +80,7 @@ typedef struct {
     int clock_speed_hz;             ///< Clock speed, in Hz
     int spics_io_num;               ///< CS GPIO pin for this device, or -1 if not used
     uint32_t flags;                 ///< Bitwise OR of SPI_DEVICE_* flags
-    int queue_size;                 ///< Transaction queue size
+    int queue_size;                 ///< Transaction queue size. This sets how many transactions can be 'in the air' (queued using spi_device_queue_trans but not yet finished using spi_device_get_trans_result) at the same time
     transaction_cb_t pre_cb;        ///< Callback to be called before a transmission is started. This callback is called within interrupt context.
     transaction_cb_t post_cb;       ///< Callback to be called after a transmission has completed. This callback is called within interrupt context.
 } spi_device_interface_config_t;

components/driver/spi_master.c

@@ -200,11 +200,11 @@ esp_err_t spi_bus_initialize(spi_host_device_t host, spi_bus_config_t *bus_confi
     SPI_CHECK(host>=SPI_HOST && host<=VSPI_HOST, "invalid host", ESP_ERR_INVALID_ARG);
     SPI_CHECK(spihost[host]==NULL, "host already in use", ESP_ERR_INVALID_STATE);
     
-    SPI_CHECK(bus_config->spid_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->spid_io_num), "spid pin invalid", ESP_ERR_INVALID_ARG);
-    SPI_CHECK(bus_config->spiclk_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->spiclk_io_num), "spiclk pin invalid", ESP_ERR_INVALID_ARG);
-    SPI_CHECK(bus_config->spiq_io_num<0 || GPIO_IS_VALID_GPIO(bus_config->spiq_io_num), "spiq pin invalid", ESP_ERR_INVALID_ARG);
-    SPI_CHECK(bus_config->spiwp_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->spiwp_io_num), "spiwp pin invalid", ESP_ERR_INVALID_ARG);
-    SPI_CHECK(bus_config->spihd_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->spihd_io_num), "spihd pin invalid", ESP_ERR_INVALID_ARG);
+    SPI_CHECK(bus_config->mosi_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->mosi_io_num), "spid pin invalid", ESP_ERR_INVALID_ARG);
+    SPI_CHECK(bus_config->sclk_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->sclk_io_num), "spiclk pin invalid", ESP_ERR_INVALID_ARG);
+    SPI_CHECK(bus_config->miso_io_num<0 || GPIO_IS_VALID_GPIO(bus_config->miso_io_num), "spiq pin invalid", ESP_ERR_INVALID_ARG);
+    SPI_CHECK(bus_config->quadwp_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->quadwp_io_num), "spiwp pin invalid", ESP_ERR_INVALID_ARG);
+    SPI_CHECK(bus_config->quadhd_io_num<0 || GPIO_IS_VALID_OUTPUT_GPIO(bus_config->quadhd_io_num), "spihd pin invalid", ESP_ERR_INVALID_ARG);
 
     //The host struct contains two dma descriptors, so we need DMA'able memory for this.
     spihost[host]=pvPortMallocCaps(sizeof(spi_host_t), MALLOC_CAP_DMA);
@@ -212,51 +212,51 @@ esp_err_t spi_bus_initialize(spi_host_device_t host, spi_bus_config_t *bus_confi
     memset(spihost[host], 0, sizeof(spi_host_t));
     
     //Check if the selected pins correspond to the native pins of the peripheral
-    if (bus_config->spid_io_num >= 0 && bus_config->spid_io_num!=io_signal[host].spid_native) native=false;
-    if (bus_config->spiq_io_num >= 0 && bus_config->spiq_io_num!=io_signal[host].spiq_native) native=false;
-    if (bus_config->spiclk_io_num >= 0 && bus_config->spiclk_io_num!=io_signal[host].spiclk_native) native=false;
-    if (bus_config->spiwp_io_num >= 0 && bus_config->spiwp_io_num!=io_signal[host].spiwp_native) native=false;
-    if (bus_config->spihd_io_num >= 0 && bus_config->spihd_io_num!=io_signal[host].spihd_native) native=false;
+    if (bus_config->mosi_io_num >= 0 && bus_config->mosi_io_num!=io_signal[host].spid_native) native=false;
+    if (bus_config->miso_io_num >= 0 && bus_config->miso_io_num!=io_signal[host].spiq_native) native=false;
+    if (bus_config->sclk_io_num >= 0 && bus_config->sclk_io_num!=io_signal[host].spiclk_native) native=false;
+    if (bus_config->quadwp_io_num >= 0 && bus_config->quadwp_io_num!=io_signal[host].spiwp_native) native=false;
+    if (bus_config->quadhd_io_num >= 0 && bus_config->quadhd_io_num!=io_signal[host].spihd_native) native=false;
     
     spihost[host]->no_gpio_matrix=native;
     if (native) {
         //All SPI native pin selections resolve to 1, so we put that here instead of trying to figure
         //out which FUNC_GPIOx_xSPIxx to grab; they all are defined to 1 anyway.
-        if (bus_config->spid_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spid_io_num], 1);
-        if (bus_config->spiq_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiq_io_num], 1);
-        if (bus_config->spiwp_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiwp_io_num], 1);
-        if (bus_config->spihd_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spihd_io_num], 1);
-        if (bus_config->spiclk_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiclk_io_num], 1);
+        if (bus_config->mosi_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->mosi_io_num], 1);
+        if (bus_config->miso_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->miso_io_num], 1);
+        if (bus_config->quadwp_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->quadwp_io_num], 1);
+        if (bus_config->quadhd_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->quadhd_io_num], 1);
+        if (bus_config->sclk_io_num > 0) PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->sclk_io_num], 1);
     } else {
         //Use GPIO 
-        if (bus_config->spid_io_num>0) {
-            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spid_io_num], PIN_FUNC_GPIO);
-            gpio_set_direction(bus_config->spid_io_num, GPIO_MODE_OUTPUT);
-            gpio_matrix_out(bus_config->spid_io_num, io_signal[host].spid_out, false, false);
-            gpio_matrix_in(bus_config->spid_io_num, io_signal[host].spid_in, false);
+        if (bus_config->mosi_io_num>0) {
+            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->mosi_io_num], PIN_FUNC_GPIO);
+            gpio_set_direction(bus_config->mosi_io_num, GPIO_MODE_OUTPUT);
+            gpio_matrix_out(bus_config->mosi_io_num, io_signal[host].spid_out, false, false);
+            gpio_matrix_in(bus_config->mosi_io_num, io_signal[host].spid_in, false);
         }
-        if (bus_config->spiq_io_num>0) {
-            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiq_io_num], PIN_FUNC_GPIO);
-            gpio_set_direction(bus_config->spiq_io_num, GPIO_MODE_INPUT);
-            gpio_matrix_out(bus_config->spiq_io_num, io_signal[host].spiq_out, false, false);
-            gpio_matrix_in(bus_config->spiq_io_num, io_signal[host].spiq_in, false);
+        if (bus_config->miso_io_num>0) {
+            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->miso_io_num], PIN_FUNC_GPIO);
+            gpio_set_direction(bus_config->miso_io_num, GPIO_MODE_INPUT);
+            gpio_matrix_out(bus_config->miso_io_num, io_signal[host].spiq_out, false, false);
+            gpio_matrix_in(bus_config->miso_io_num, io_signal[host].spiq_in, false);
         }
-        if (bus_config->spiwp_io_num>0) {
-            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiwp_io_num], PIN_FUNC_GPIO);
-            gpio_set_direction(bus_config->spiwp_io_num, GPIO_MODE_OUTPUT);
-            gpio_matrix_out(bus_config->spiwp_io_num, io_signal[host].spiwp_out, false, false);
-            gpio_matrix_in(bus_config->spiwp_io_num, io_signal[host].spiwp_in, false);
+        if (bus_config->quadwp_io_num>0) {
+            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->quadwp_io_num], PIN_FUNC_GPIO);
+            gpio_set_direction(bus_config->quadwp_io_num, GPIO_MODE_OUTPUT);
+            gpio_matrix_out(bus_config->quadwp_io_num, io_signal[host].spiwp_out, false, false);
+            gpio_matrix_in(bus_config->quadwp_io_num, io_signal[host].spiwp_in, false);
         }
-        if (bus_config->spihd_io_num>0) {
-            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spihd_io_num], PIN_FUNC_GPIO);
-            gpio_set_direction(bus_config->spihd_io_num, GPIO_MODE_OUTPUT);
-            gpio_matrix_out(bus_config->spihd_io_num, io_signal[host].spihd_out, false, false);
-            gpio_matrix_in(bus_config->spihd_io_num, io_signal[host].spihd_in, false);
+        if (bus_config->quadhd_io_num>0) {
+            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->quadhd_io_num], PIN_FUNC_GPIO);
+            gpio_set_direction(bus_config->quadhd_io_num, GPIO_MODE_OUTPUT);
+            gpio_matrix_out(bus_config->quadhd_io_num, io_signal[host].spihd_out, false, false);
+            gpio_matrix_in(bus_config->quadhd_io_num, io_signal[host].spihd_in, false);
         }
-        if (bus_config->spiclk_io_num>0) {
-            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->spiclk_io_num], PIN_FUNC_GPIO);
-            gpio_set_direction(bus_config->spiclk_io_num, GPIO_MODE_OUTPUT);
-            gpio_matrix_out(bus_config->spiclk_io_num, io_signal[host].spiclk_out, false, false);
+        if (bus_config->sclk_io_num>0) {
+            PIN_FUNC_SELECT(GPIO_PIN_MUX_REG[bus_config->sclk_io_num], PIN_FUNC_GPIO);
+            gpio_set_direction(bus_config->sclk_io_num, GPIO_MODE_OUTPUT);
+            gpio_matrix_out(bus_config->sclk_io_num, io_signal[host].spiclk_out, false, false);
         }
     }
     periph_module_enable(io_signal[host].module);

components/driver/test/test_spi_master.c

@@ -21,11 +21,11 @@
 TEST_CASE("SPI Master test", "[spi]")
 {
     spi_bus_config_t buscfg={
-        .spid_io_num=4,
-        .spiq_io_num=16,
-        .spiclk_io_num=25,
-        .spiwp_io_num=-1,
-        .spihd_io_num=-1
+        .mosi_io_num=4,
+        .miso_io_num=16,
+        .sclk_io_num=25,
+        .quadwp_io_num=-1,
+        .quadhd_io_num=-1
     };
     spi_device_interface_config_t devcfg={
         .command_bits=8,
@@ -33,8 +33,6 @@ TEST_CASE("SPI Master test", "[spi]")
         .dummy_bits=0,
         .clock_speed_hz=8000,
         .duty_cycle_pos=128,
-        .cs_ena_pretrans=7,
-        .cs_ena_posttrans=7,
         .mode=0,
         .spics_io_num=21,
         .queue_size=3

examples/26_spi_master/main/spi_master.c

@@ -249,11 +249,11 @@ void app_main()
     esp_err_t ret;
     spi_device_handle_t spi;
     spi_bus_config_t buscfg={
-        .spiq_io_num=PIN_NUM_MISO,
-        .spid_io_num=PIN_NUM_MOSI,
-        .spiclk_io_num=PIN_NUM_CLK,
-        .spiwp_io_num=-1,
-        .spihd_io_num=-1
+        .miso_io_num=PIN_NUM_MISO,
+        .mosi_io_num=PIN_NUM_MOSI,
+        .sclk_io_num=PIN_NUM_CLK,
+        .quadwp_io_num=-1,
+        .quadhd_io_num=-1
     };
     spi_device_interface_config_t devcfg={
         .clock_speed_hz=10000000,               //Clock out at 10 MHz