* You can use this structure to specify the GPIO pins of the bus. Normally, the driver will use the
* GPIO matrix to route the signals. An exception is made when all signals either can be routed through
* the IO_MUX or are -1. In that case, the IO_MUX is used, allowing for >40MHz speeds.
+ *
+ * @note Be advised that the slave driver does not use the quadwp/quadhd lines and fields in spi_bus_config_t refering to these lines will be ignored and can thus safely be left uninitialized.
*/
typedef struct {
int mosi_io_num; ///< GPIO pin for Master Out Slave In (=spi_d) 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.
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;
/**
* @brief Return the SPI peripheral so another driver can claim it.
*
- * @param host Peripheral to claim
+ * @param host Peripheral to return
* @return True if peripheral is returned successfully; false if peripheral was free to claim already.
*/
bool spicommon_periph_free(spi_host_device_t host);
+/**
+ * @brief Try to claim a SPI DMA channel
+ *
+ * Call this if your driver wants to use SPI with a DMA channnel.
+ *
+ * @param dma_chan channel to claim
+ *
+ * @return True if success; false otherwise.
+ */
+bool spicommon_dma_chan_claim(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
+/**
+ * @brief Return the SPI DMA channel so other driver can claim it, or just to power down DMA.
+ *
+ * @param dma_chan channel to return
+ *
+ * @return True if success; false otherwise.
+ */
+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_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
* @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
*/
int spicommon_irqsource_for_host(spi_host_device_t host);
-
-
-
/**
* Callback, to be called when a DMA engine reset is completed
*/
}
#endif
-#endif
\ No newline at end of file
+#endif