chore(spi): fix the terms of native to iomux

[esp-idf] / components / driver / include / driver / spi_common.h

diff --git a/components/driver/include/driver/spi_common.h b/components/driver/include/driver/spi_common.h
index 6adcc06a91d9b11339adf322c9a935a21a2474dd..d81a9430b74c387dfdf328db23e80fca32d8de28 100644 (file)
--- a/components/driver/include/driver/spi_common.h
+++ b/components/driver/include/driver/spi_common.h
@@ -58,6 +58,7 @@ typedef struct {
     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.
     int max_transfer_sz;            ///< Maximum transfer size, in bytes. Defaults to 4094 if 0.
+    uint32_t flags;                 ///< Abilities of bus to be checked by the driver. Or-ed value of ``SPICOMMON_BUSFLAG_*`` flags.
 } spi_bus_config_t;
 
 
@@ -99,9 +100,15 @@ bool spicommon_dma_chan_claim(int dma_chan);
  */
 bool spicommon_dma_chan_free(int dma_chan);
 
-#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_QUAD   (1<<1)     ///< Also initialize WP/HD pins, if specified
+#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_NATIVE_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_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.
 
 /**
  * @brief Connect a SPI peripheral to GPIO pins
@@ -113,14 +120,28 @@ bool spicommon_dma_chan_free(int dma_chan);
  * @param host SPI peripheral to be routed
  * @param bus_config Pointer to a spi_bus_config struct detailing the GPIO pins
  * @param dma_chan DMA-channel (1 or 2) to use, or 0 for no DMA.
- * @param flags Combination of SPICOMMON_BUSFLAG_* flags
- * @param[out] is_native A value of 'true' will be written to this address if the GPIOs can be
- *                  routed using the IO_mux, 'false' if the GPIO matrix is used.
+ * @param flags Combination of SPICOMMON_BUSFLAG_* flags, set to ensure the pins set are capable with some functions:
+ *              - ``SPICOMMON_BUSFLAG_MASTER``: Initialize I/O in master mode
+ *              - ``SPICOMMON_BUSFLAG_SLAVE``: Initialize I/O in slave mode
+ *              - ``SPICOMMON_BUSFLAG_NATIVE_PINS``: Pins set should match the iomux pins of the controller.
+ *              - ``SPICOMMON_BUSFLAG_SCLK``, ``SPICOMMON_BUSFLAG_MISO``, ``SPICOMMON_BUSFLAG_MOSI``: 
+ *                  Make sure SCLK/MISO/MOSI is/are set to a valid GPIO. Also check output capability according to the mode.
+ *              - ``SPICOMMON_BUSFLAG_DUAL``: Make sure both MISO and MOSI are output capable so that DIO mode is capable.
+ *              - ``SPICOMMON_BUSFLAG_WPHD`` Make sure WP and HD are set to valid output GPIOs.
+ *              - ``SPICOMMON_BUSFLAG_QUAD``: Combination of ``SPICOMMON_BUSFLAG_DUAL`` and ``SPICOMMON_BUSFLAG_WPHD``.
+ * @param[out] flags_o A SPICOMMON_BUSFLAG_* flag combination of bus abilities will be written to this address.
+ *              Leave to NULL if not needed.
+ *              - ``SPICOMMON_BUSFLAG_NATIVE_PINS``: The bus is connected to iomux pins.
+ *              - ``SPICOMMON_BUSFLAG_SCLK``, ``SPICOMMON_BUSFLAG_MISO``, ``SPICOMMON_BUSFLAG_MOSI``: The bus has
+ *                  CLK/MISO/MOSI connected.
+ *              - ``SPICOMMON_BUSFLAG_DUAL``: The bus is capable with DIO mode.
+ *              - ``SPICOMMON_BUSFLAG_WPHD`` The bus has WP and HD connected.
+ *              - ``SPICOMMON_BUSFLAG_QUAD``: Combination of ``SPICOMMON_BUSFLAG_DUAL`` and ``SPICOMMON_BUSFLAG_WPHD``.
  * @return 
  *         - ESP_ERR_INVALID_ARG   if parameter is invalid
  *         - ESP_OK                on success
  */
-esp_err_t spicommon_bus_initialize_io(spi_host_device_t host, const spi_bus_config_t *bus_config, int dma_chan, int flags, bool *is_native);
+esp_err_t spicommon_bus_initialize_io(spi_host_device_t host, const spi_bus_config_t *bus_config, int dma_chan, uint32_t flags, uint32_t *flags_o);
 
 /**
  * @brief Free the IO used by a SPI peripheral