4  * SPDX-License-Identifier: Apache-2.0
9  * @brief Public API for SPI drivers and applications
16  * @brief SPI Interface
17  * @defgroup spi_interface SPI Interface
27 #include <zephyr/dt-bindings/spi/spi.h>
39  * @name SPI operational mode
47 /** Get SPI operational mode. */
52  * @name SPI Polarity & Phase Modes
73  * Whatever data is transmitted is looped-back to the receiving buffer of
81 /** Get SPI polarity and phase mode bits. */
88  * @name SPI Transfer modes (host controller dependent)
96  * @name SPI word size
103 /** Get SPI word size (data frame size) in bits. */
106 /** Set SPI word size (data frame size) in bits. */
112  * @name Specific SPI devices control bits
115 /** Requests - if possible - to keep CS asserted after the transaction */
119  * prevent other callers to access the SPI device until spi_release() is
135  * @name SPI MISO lines
153  * @brief SPI Chip Select control structure
176  * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
185  *     spi@abcd0003 {
186  *             compatible = "vnd,spi";
187  *             cs-gpios = <&gpio1 10 GPIO_ACTIVE_LOW>,
190  *             a: spi-dev-a@0 {
194  *             b: spi-dev-b@1 {
209  * @param spi_dev a SPI device node identifier
217  * @brief Get a <tt>struct gpio_dt_spec</tt> for a SPI device's chip select pin
232  * This helper is useful for initializing a device on a SPI bus. It
234  * Here, @p node_id is a node identifier for a SPI device, not a SPI
240  *     spi@abcd0001 {
241  *             cs-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
242  *             spidev: spi-device@0 { ... };
262  * @param node_id Devicetree node identifier for a device on a SPI bus
290  * Opaque type to hold the SPI operation flags.
299  * @brief SPI controller configuration structure
309 	 * - 0:      Master or slave.
310 	 * - 1..3:   Polarity, phase and loop mode.
311 	 * - 4:      LSB or MSB first.
312 	 * - 5..10:  Size of a data frame (word) in bits.
313 	 * - 11:     Full/half duplex.
314 	 * - 12:     Hold on the CS line if possible.
315 	 * - 13:     Keep resource locked for the caller.
316 	 * - 14:     Active high CS logic.
317 	 * - 15:     Motorola or TI frame format (optional).
321 	 * - 16..17: MISO lines (Single/Dual/Quad/Octal).
322 	 * - 18..31: Reserved for future use.
328 	 * @brief GPIO chip-select line (optional, must be initialized to zero
341  * @param node_id Devicetree node identifier for the SPI device whose
375  * @brief Complete SPI DT information
378 	/** SPI bus */
395  * @param node_id Devicetree node identifier for the SPI device whose
430  * can be queried at compile-time to determine whether allocating a constant
433  * @param node_id Devicetree node identifier for the SPI device to query
456  * @brief SPI buffer structure
469  * @brief SPI buffer array structure
479 STATS_SECT_START(spi)
485 STATS_NAME_START(spi)
486 STATS_NAME(spi, rx_bytes)
487 STATS_NAME(spi, tx_bytes)
488 STATS_NAME(spi, transfer_error)
489 STATS_NAME_END(spi);
492  * @brief SPI specific device state which allows for SPI device class specific additions
500  * @brief Get pointer to SPI statistics structure
503 	CONTAINER_OF(dev_->state, struct spi_device_state, devstate)->stats
506  * @brief Increment the rx bytes for a SPI device
514  * @brief Increment the tx bytes for a SPI device
522  * @brief Increment the transfer error counter for a SPI device
532  * @brief Define a statically allocated and section assigned SPI device state
539  * @brief Define an SPI device init wrapper function
545 	static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
548 			CONTAINER_OF(dev->state, struct spi_device_state, devstate); \
549 		stats_init(&state->stats.s_hdr, STATS_SIZE_32, 3,	\
550 			   STATS_NAME_INIT_PARMS(spi));			\
551 		stats_register(dev->name, &(state->stats.s_hdr));	\
552 		return init_fn(dev);					\
556  * @brief Like DEVICE_DT_DEFINE() with SPI specifics.
558  * @details Defines a device which implements the SPI API. May
560  * wrapper when needed depending on SPI @kconfig{CONFIG_SPI_STATS}.
588 static inline void spi_transceive_stats(const struct device *dev, int error,  in spi_transceive_stats()  argument
596 		SPI_STATS_TRANSFER_ERROR_INC(dev);  in spi_transceive_stats()
600 		tx_bytes = tx_bufs->count ? tx_bufs->buffers->len : 0;  in spi_transceive_stats()
601 		SPI_STATS_TX_BYTES_INCN(dev, tx_bytes);  in spi_transceive_stats()
605 		rx_bytes = rx_bufs->count ? rx_bufs->buffers->len : 0;  in spi_transceive_stats()
606 		SPI_STATS_RX_BYTES_INCN(dev, rx_bytes);  in spi_transceive_stats()
626 #define spi_transceive_stats(dev, error, tx_bufs, rx_bufs)  argument
646 typedef int (*spi_api_io)(const struct device *dev,
652  * @brief SPI callback for asynchronous transfer requests
654  * @param dev SPI device which is notifying of transfer completion or error
655  * @param result Result code of the transfer request. 0 is success, -errno for failure.
658 typedef void (*spi_callback_t)(const struct device *dev, int result, void *data);
665 typedef int (*spi_api_io_async)(const struct device *dev,
676  * @brief Callback API for submitting work to a SPI device with RTIO
678 typedef void (*spi_api_iodev_submit)(const struct device *dev,
684  * @brief Callback API for unlocking SPI device.
687 typedef int (*spi_api_release)(const struct device *dev,
692  * @brief SPI driver API
693  * This is the mandatory API any SPI driver needs to expose.
707  * @brief Check if SPI CS is controlled using a GPIO.
709  * @param config SPI configuration.
715 	return config->cs.gpio.port != NULL;  in spi_cs_is_gpio()
719  * @brief Check if SPI CS in @ref spi_dt_spec is controlled using a GPIO.
721  * @param spec SPI specification from devicetree.
727 	return spi_cs_is_gpio(&spec->config);  in spi_cs_is_gpio_dt()
731  * @brief Validate that SPI bus (and CS gpio if defined) is ready.
733  * @param spec SPI specification from devicetree
735  * @retval true if the SPI bus is ready for use.
736  * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
741 	if (!device_is_ready(spec->bus)) {  in spi_is_ready_dt()
746 	    !gpio_is_ready_dt(&spec->config.cs.gpio)) {  in spi_is_ready_dt()
753  * @brief Read/write the specified amount of data from the SPI driver.
757  * @param dev Pointer to the device structure for the driver instance
759  *        Pointer-comparison may be used to detect changes from
768  * @retval -errno Negative errno code on failure.
770 __syscall int spi_transceive(const struct device *dev,
775 static inline int z_impl_spi_transceive(const struct device *dev,  in z_impl_spi_transceive()  argument
781 		(const struct spi_driver_api *)dev->api;  in z_impl_spi_transceive()
784 	ret = api->transceive(dev, config, tx_bufs, rx_bufs);  in z_impl_spi_transceive()
785 	spi_transceive_stats(dev, ret, tx_bufs, rx_bufs);  in z_impl_spi_transceive()
791  * @brief Read/write data from an SPI bus specified in @p spi_dt_spec.
795  *     spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);
797  * @param spec SPI specification from devicetree
809 	return spi_transceive(spec->bus, &spec->config, tx_bufs, rx_bufs);  in spi_transceive_dt()
813  * @brief Read the specified amount of data from the SPI driver.
819  * @param dev Pointer to the device structure for the driver instance
821  *        Pointer-comparison may be used to detect changes from
827  * @retval -errno Negative errno code on failure.
829 static inline int spi_read(const struct device *dev,  in spi_read()  argument
833 	return spi_transceive(dev, config, NULL, rx_bufs);  in spi_read()
837  * @brief Read data from a SPI bus specified in @p spi_dt_spec.
841  *     spi_read(spec->bus, &spec->config, rx_bufs);
843  * @param spec SPI specification from devicetree
851 	return spi_read(spec->bus, &spec->config, rx_bufs);  in spi_read_dt()
855  * @brief Write the specified amount of data from the SPI driver.
861  * @param dev Pointer to the device structure for the driver instance
863  *        Pointer-comparison may be used to detect changes from
868  * @retval -errno Negative errno code on failure.
870 static inline int spi_write(const struct device *dev,  in spi_write()  argument
874 	return spi_transceive(dev, config, tx_bufs, NULL);  in spi_write()
878  * @brief Write data to a SPI bus specified in @p spi_dt_spec.
882  *     spi_write(spec->bus, &spec->config, tx_bufs);
884  * @param spec SPI specification from devicetree
892 	return spi_write(spec->bus, &spec->config, tx_bufs);  in spi_write_dt()
898  * @brief Read/write the specified amount of data from the SPI driver.
905  * @param dev Pointer to the device structure for the driver instance
907  *        Pointer-comparison may be used to detect changes from
921  * @retval -errno Negative errno code on failure.
923 static inline int spi_transceive_cb(const struct device *dev,  in spi_transceive_cb()  argument
931 		(const struct spi_driver_api *)dev->api;  in spi_transceive_cb()
933 	return api->transceive_async(dev, config, tx_bufs, rx_bufs, callback, userdata);  in spi_transceive_cb()
939 void z_spi_transfer_signal_cb(const struct device *dev, int result, void *userdata);
943  * @brief Read/write the specified amount of data from the SPI driver.
950  * @param dev Pointer to the device structure for the driver instance
952  *        Pointer-comparison may be used to detect changes from
965  * @retval -errno Negative errno code on failure.
967 static inline int spi_transceive_signal(const struct device *dev,  in spi_transceive_signal()  argument
974 		(const struct spi_driver_api *)dev->api;  in spi_transceive_signal()
977 	return api->transceive_async(dev, config, tx_bufs, rx_bufs, cb, sig);  in spi_transceive_signal()
981  * @brief Read the specified amount of data from the SPI driver.
990  * @param dev Pointer to the device structure for the driver instance
992  *        Pointer-comparison may be used to detect changes from
1002  * @retval -errno Negative errno code on failure.
1004 static inline int spi_read_signal(const struct device *dev,  in spi_read_signal()  argument
1009 	return spi_transceive_signal(dev, config, NULL, rx_bufs, sig);  in spi_read_signal()
1013  * @brief Write the specified amount of data from the SPI driver.
1022  * @param dev Pointer to the device structure for the driver instance
1024  *        Pointer-comparison may be used to detect changes from
1033  * @retval -errno Negative errno code on failure.
1035 static inline int spi_write_signal(const struct device *dev,  in spi_write_signal()  argument
1040 	return spi_transceive_signal(dev, config, tx_bufs, NULL, sig);  in spi_write_signal()
1051  * @brief Submit a SPI device with a request
1059 	const struct spi_dt_spec *dt_spec = (const struct spi_dt_spec *)iodev_sqe->sqe.iodev->data;  in spi_iodev_submit()
1060 	const struct device *dev = dt_spec->bus;  in spi_iodev_submit()  local
1061 	const struct spi_driver_api *api = (const struct spi_driver_api *)dev->api;  in spi_iodev_submit()
1063 	api->iodev_submit(dt_spec->bus, iodev_sqe);  in spi_iodev_submit()
1076  * @param operation_ SPI operational mode
1085  * @brief Validate that SPI bus (and CS gpio if defined) is ready.
1087  * @param spi_iodev SPI iodev defined with SPI_DT_IODEV_DEFINE
1089  * @retval true if the SPI bus is ready for use.
1090  * @retval false if the SPI bus (or the CS gpio defined) is not ready for use.
1094 	struct spi_dt_spec *spec = (struct spi_dt_spec *)spi_iodev->data;  in spi_is_ready_iodev()
1102  * @brief Release the SPI device locked on and/or the CS by the current config
1105  *       SPI device and/or the CS line that was kept if, and if only,
1109  *       This can be used if the caller needs to keep its hand on the SPI
1115  * @param dev Pointer to the device structure for the driver instance
1119  * @retval -errno Negative errno code on failure.
1121 __syscall int spi_release(const struct device *dev,
1124 static inline int z_impl_spi_release(const struct device *dev,  in z_impl_spi_release()  argument
1128 		(const struct spi_driver_api *)dev->api;  in z_impl_spi_release()
1130 	return api->release(dev, config);  in z_impl_spi_release()
1134  * @brief Release the SPI device specified in @p spi_dt_spec.
1138  *     spi_release(spec->bus, &spec->config);
1140  * @param spec SPI specification from devicetree
1146 	return spi_release(spec->bus, &spec->config);  in spi_release_dt()
1157 #include <zephyr/syscalls/spi.h>