1 /* SPDX-License-Identifier: GPL-2.0-or-later
21 #include <uapi/linux/spi/spi.h>
23 /* Max no. of CS supported per spi device */
38  * INTERFACES between SPI controller-side drivers and SPI target protocol handlers,
39  * and SPI infrastructure.
44  * struct spi_statistics - statistics for spi transfers
45  * @syncp:         seqcount to protect members in this struct for per-cpu update
46  *                 on 32-bit systems
48  * @messages:      number of spi-messages handled
97 		u64_stats_update_begin(&__lstats->syncp);		\
98 		u64_stats_add(&__lstats->field, count);			\
99 		u64_stats_update_end(&__lstats->syncp);			\
108 		u64_stats_update_begin(&__lstats->syncp);		\
109 		u64_stats_inc(&__lstats->field);			\
110 		u64_stats_update_end(&__lstats->syncp);			\
115  * struct spi_delay - SPI delay information
116  * @value: Value for the delay
117  * @unit: Unit for the delay
133  * struct spi_device - Controller side proxy for an SPI target device
135  * @controller: SPI controller used with the device.
139  * @chip_select: Array of physical chipselect, spi->chipselect[i] gives
140  *	the corresponding physical CS for logical CS i.
141  * @mode: The spi mode defines how data is clocked out and in.
147  *	like eight or 12 bits are common.  In-memory wordsizes are
156  * @controller_data: Board-specific definitions for controller, such as
167  * @word_delay: delay to be inserted between consecutive
169  * @cs_setup: delay to be introduced by the controller after CS is asserted
170  * @cs_hold: delay to be introduced by the controller before CS is deasserted
171  * @cs_inactive: delay to be introduced by the controller after CS is
177  * A @spi_device is used to interchange data between an SPI target device
196 	 * TPM specification defines flow control over SPI. Client device
200 	 * only half-duplex, the wait state detection needs to be implemented
202 	 * control is expected from SPI controller.
208 	 * which is defined in 'include/uapi/linux/spi/spi.h'.
214 #define SPI_MODE_KERNEL_MASK	(~(BIT(29) - 1))
222 	struct spi_delay	word_delay; /* Inter-word delay */
223 	/* CS delays */
241 	 *  - memory packing (12 bit samples into low bits, others zeroed)
242 	 *  - priority
243 	 *  - chipselect delays
244 	 *  - ...
255 static inline struct spi_device *spi_dev_get(struct spi_device *spi)  in spi_dev_get()  argument
257 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
260 static inline void spi_dev_put(struct spi_device *spi)  in spi_dev_put()  argument
262 	if (spi)  in spi_dev_put()
263 		put_device(&spi->dev);  in spi_dev_put()
267 static inline void *spi_get_ctldata(const struct spi_device *spi)  in spi_get_ctldata()  argument
269 	return spi->controller_state;  in spi_get_ctldata()
272 static inline void spi_set_ctldata(struct spi_device *spi, void *state)  in spi_set_ctldata()  argument
274 	spi->controller_state = state;  in spi_set_ctldata()
279 static inline void spi_set_drvdata(struct spi_device *spi, void *data)  in spi_set_drvdata()  argument
281 	dev_set_drvdata(&spi->dev, data);  in spi_set_drvdata()
284 static inline void *spi_get_drvdata(const struct spi_device *spi)  in spi_get_drvdata()  argument
286 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
289 static inline u8 spi_get_chipselect(const struct spi_device *spi, u8 idx)  in spi_get_chipselect()  argument
291 	return spi->chip_select[idx];  in spi_get_chipselect()
294 static inline void spi_set_chipselect(struct spi_device *spi, u8 idx, u8 chipselect)  in spi_set_chipselect()  argument
296 	spi->chip_select[idx] = chipselect;  in spi_set_chipselect()
299 static inline struct gpio_desc *spi_get_csgpiod(const struct spi_device *spi, u8 idx)  in spi_get_csgpiod()  argument
301 	return spi->cs_gpiod[idx];  in spi_get_csgpiod()
304 static inline void spi_set_csgpiod(struct spi_device *spi, u8 idx, struct gpio_desc *csgpiod)  in spi_set_csgpiod()  argument
306 	spi->cs_gpiod[idx] = csgpiod;  in spi_set_csgpiod()
309 static inline bool spi_is_csgpiod(struct spi_device *spi)  in spi_is_csgpiod()  argument
314 		if (spi_get_csgpiod(spi, idx))  in spi_is_csgpiod()
321  * struct spi_driver - Host side "protocol" driver
322  * @id_table: List of SPI devices supported by this driver
323  * @probe: Binds this driver to the SPI device.  Drivers can verify
327  * @remove: Unbinds this driver from the SPI device
330  * @driver: SPI device drivers should initialize the name and owner
333  * This represents the kind of device driver that uses SPI messages to
334  * interact with the hardware at the other end of a SPI link.  It's called
336  * directly to SPI hardware (which is what the underlying SPI controller
347 	int			(*probe)(struct spi_device *spi);
348 	void			(*remove)(struct spi_device *spi);
349 	void			(*shutdown)(struct spi_device *spi);
359  * spi_unregister_driver - reverse effect of spi_register_driver
366 		driver_unregister(&sdrv->driver);  in spi_unregister_driver()
369 extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 chip_select);
376  * module_spi_driver() - Helper macro for registering a SPI driver
379  * Helper macro for SPI drivers which do not do anything special in module
388  * struct spi_controller - interface to SPI host or target controller
391  * @bus_num: board-specific (and often SOC-specific) identifier for a
392  *	given SPI controller.
394  *	SPI targets, and are numbered from zero to num_chipselects.
397  * @dma_alignment: SPI controller constraint on DMA buffers alignment.
402  *	supported. If set, the SPI core will reject any transfer with an
408  * @slave: indicates that this is an SPI slave controller
409  * @target: indicates that this is an SPI target controller
410  * @devm_allocated: whether the allocation of this struct is devres-managed
417  * @bus_lock_spinlock: spinlock for SPI bus locking
419  * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
421  *	device's SPI controller; protocol code may call this.  This
425  * @set_cs_timing: optional hook for SPI devices to request SPI
426  * controller for configuring specific CS setup time, hold time and inactive
427  * delay in terms of clock counts
429  * @cleanup: frees controller-specific state
439  * @cur_msg: the currently in-flight message
440  * @cur_msg_completion: a completion for the current in-flight message
450  * @last_cs: the last chip_select that is recorded by set_cs, -1 on non chip
482  *                  - return 0 if the transfer is finished,
483  *                  - return 1 if the transfer is still in progress. When
488  *                    spi_transfer->error first, before calling
495  * @mem_ops: optimized/dedicated operations for interactions with SPI memory.
499  *	offload instance. Implementations should return -ENODEV if no match is
504  * @target_abort: abort the ongoing transfer request on an SPI target controller
505  * @cs_gpiods: Array of GPIO descriptors to use as chip select lines; one per CS
506  *	number. Any individual value may be NULL for CS lines that
507  *	are not GPIOs (driven by the SPI controller itself).
508  * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab
509  *	GPIO descriptors. This will fill in @cs_gpiods and SPI devices will have
512  *	fill in this field with the first unused native CS, to be used by SPI
513  *	controller drivers that need to drive a native CS when using GPIO CS.
515  *	spi_register_controller() will validate all native CS (including the
516  *	unused native CS) against this value.
520  * @dummy_rx: dummy receive buffer for full-duplex devices
521  * @dummy_tx: dummy transmit buffer for full-duplex devices
526  *	time snapshot in @spi_transfer->ptp_sts as close as possible to the
527  *	moment in time when @spi_transfer->ptp_sts_word_pre and
528  *	@spi_transfer->ptp_sts_word_post were transmitted.
529  *	If the driver does not set this, the SPI core takes the snapshot as
530  *	close to the driver hand-over as possible.
535  * @defer_optimize_message: set to true if controller cannot pre-optimize messages
539  * Each SPI controller can communicate with one or more @spi_device
540  * children.  These make a small bus, sharing MOSI, MISO and SCK signals
545  * The driver for an SPI controller manages access to those devices through
547  * an SPI target device.  For each such message it queues, it calls the
557 	 * board-specific. Usually that simplifies to being SoC-specific.
558 	 * example: one SoC has three SPI controllers, numbered 0..2,
559 	 * and one board's schematics might show it using SPI-2. Software
566 	 * might use board-specific GPIOs.
570 	/* Some SPI controllers pose alignment requirements on DMAable
583 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
584 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
597 #define SPI_CONTROLLER_GPIO_SS		BIT(5)	/* GPIO CS must select target device */
600 	 * The spi-controller has multi chip select capability and can
601 	 * assert/de-assert more than one chip select at once.
605 	/* Flag indicating if the allocation of this struct is devres-managed */
609 		/* Flag indicating this is an SPI slave controller */
611 		/* Flag indicating this is an SPI target controller */
619 	size_t (*max_transfer_size)(struct spi_device *spi);
620 	size_t (*max_message_size)(struct spi_device *spi);
625 	/* Used to avoid adding the same CS twice */
628 	/* Lock and mutex for SPI bus locking */
632 	/* Flag indicating that the SPI bus is locked for exclusive use */
636 	 * Setup mode and clock, etc (SPI driver may call many times).
642 	int			(*setup)(struct spi_device *spi);
645 	 * set_cs_timing() method is for SPI controllers that supports
646 	 * configuring CS timing.
648 	 * This hook allows SPI client drivers to request SPI controllers
649 	 * to configure specific CS timing through spi_set_cs_timing() after
652 	int (*set_cs_timing)(struct spi_device *spi);
659 	 * + For now there's no remove-from-queue operation, or
671 	 * + The message transfers use clock and SPI mode parameters
674 	int			(*transfer)(struct spi_device *spi,
678 	void			(*cleanup)(struct spi_device *spi);
688 					   struct spi_device *spi,
698 	 * Over time we expect SPI drivers to be phased over to this API.
736 	void (*set_cs)(struct spi_device *spi, bool enable);
737 	int (*transfer_one)(struct spi_controller *ctlr, struct spi_device *spi,
742 	/* Optimized handlers for SPI memory-like operations. */
746 	struct spi_offload *(*get_offload)(struct spi_device *spi,
767 	int (*fw_translate_cs)(struct spi_controller *ctlr, unsigned cs);
770 	 * Driver sets this field to indicate it is able to snapshot SPI
786 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
792 	dev_set_drvdata(&ctlr->dev, data);  in spi_controller_set_devdata()
797 	if (!ctlr || !get_device(&ctlr->dev))  in spi_controller_get()
805 		put_device(&ctlr->dev);  in spi_controller_put()
810 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->target;  in spi_controller_is_target()
830 /* The SPI driver core manages memory for the spi_controller classdev */
889 	return ERR_PTR(-ENODEV);  in acpi_spi_device_alloc()
899  * SPI resource management while processing a SPI message
907  * struct spi_res - SPI resource management structure
910  * @data:    extra data allocated for the specific use-case
912  * This is based on ideas from devres, but focused on life-cycle
921 /*---------------------------------------------------------------------------*/
924  * I/O INTERFACE between SPI controller and protocol drivers
932  * pointer.  (This is unlike most types of I/O API, because SPI hardware
941  * struct spi_transfer - a read/write buffer pair
942  * @tx_buf: data to be written (DMA-safe memory), or NULL
943  * @rx_buf: data to be read (DMA-safe memory), or NULL
958  * @cs_change_delay: delay between cs deassert and assert when
960  * @delay: delay to be introduced after this transfer before
963  * @word_delay: inter word delay to be introduced after each word size
965  * @effective_speed_hz: the effective SCK-speed that was used to
966  *      transfer this transfer. Set to 0 if the SPI bus driver does
973  * @offload_flags: Flags that are only applicable to specialized SPI offload
974  *	transfers. See %SPI_OFFLOAD_XFER_* in spi-offload.h.
976  *	within @tx_buf for which the SPI device is requesting that the time
977  *	snapshot for this transfer begins. Upon completing the SPI transfer,
986  *	purposefully (instead of setting to spi_transfer->len - 1) to denote
987  *	that a transfer-level snapshot taken from within the driver may still
989  * @ptp_sts: Pointer to a memory location held by the SPI target device where a
994  *	The timestamp must represent the time at which the SPI target device has
999  * @error: Error status logged by SPI controller driver.
1001  * SPI transfers always write the same number of bytes as they read.
1014  * In-memory data values are always in native CPU byte order, translated
1015  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
1019  * When the word size of the SPI transfer is not a power-of-two multiple
1020  * of eight bits, those in-memory words include extra bits.  In-memory
1021  * words are always seen by protocol drivers as right-justified, so the
1024  * All SPI transfers start with the relevant chipselect active.  Normally
1035  * stay selected until the next transfer.  On multi-device SPI busses
1044  * When SPI can transfer in 1x,2x or 4x. It can get this transfer information
1045  * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
1051  * Zero-initialize every field you don't set up explicitly, to
1083 #define	SPI_NBITS_SINGLE	0x01 /* 1-bit transfer */
1084 #define	SPI_NBITS_DUAL		0x02 /* 2-bit transfer */
1085 #define	SPI_NBITS_QUAD		0x04 /* 4-bit transfer */
1086 #define	SPI_NBITS_OCTAL	0x08 /* 8-bit transfer */
1088 	struct spi_delay	delay;  member
1095 	/* Use %SPI_OFFLOAD_XFER_* from spi-offload.h */
1107  * struct spi_message - one multi-segment SPI transaction
1109  * @spi: SPI device to which the transaction is queued
1110  * @pre_optimized: peripheral driver pre-optimized the message
1122  * @resources: for resource management when the SPI message is processed
1127  * in the sense that no other spi_message may use that SPI bus until that
1135  * Zero-initialize every field you don't set up explicitly, to
1142 	struct spi_device	*spi;  member
1158 	 * Some controller drivers (message-at-a-time queue processing)
1160 	 * others (with multi-message pipelines) could need a flag to
1190 	/* List of spi_res resources when the SPI message is processed */
1196 	INIT_LIST_HEAD(&m->transfers);  in spi_message_init_no_memset()
1197 	INIT_LIST_HEAD(&m->resources);  in spi_message_init_no_memset()
1209 	list_add_tail(&t->transfer_list, &m->transfers);  in spi_message_add_tail()
1215 	list_del(&t->transfer_list);  in spi_transfer_del()
1221 	return spi_delay_exec(&t->delay, t);  in spi_transfer_delay_exec()
1225  * spi_message_init_with_transfers - Initialize spi_message and append transfers
1227  * @xfers: An array of SPI transfers
1260 	spi_message_init_no_memset(&mwt->m);  in spi_message_alloc()
1262 		spi_message_add_tail(&mwt->t[i], &mwt->m);  in spi_message_alloc()
1264 	return &mwt->m;  in spi_message_alloc()
1272 extern int spi_optimize_message(struct spi_device *spi, struct spi_message *msg);
1274 extern int devm_spi_optimize_message(struct device *dev, struct spi_device *spi,
1277 extern int spi_setup(struct spi_device *spi);
1278 extern int spi_async(struct spi_device *spi, struct spi_message *message);
1279 extern int spi_target_abort(struct spi_device *spi);
1282 spi_max_message_size(struct spi_device *spi)  in spi_max_message_size()  argument
1284 	struct spi_controller *ctlr = spi->controller;  in spi_max_message_size()
1286 	if (!ctlr->max_message_size)  in spi_max_message_size()
1288 	return ctlr->max_message_size(spi);  in spi_max_message_size()
1292 spi_max_transfer_size(struct spi_device *spi)  in spi_max_transfer_size()  argument
1294 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1296 	size_t msg_max = spi_max_message_size(spi);  in spi_max_transfer_size()
1298 	if (ctlr->max_transfer_size)  in spi_max_transfer_size()
1299 		tr_max = ctlr->max_transfer_size(spi);  in spi_max_transfer_size()
1306  * spi_is_bpw_supported - Check if bits per word is supported
1307  * @spi: SPI device
1310  * This function checks to see if the SPI controller supports @bpw.
1315 static inline bool spi_is_bpw_supported(struct spi_device *spi, u32 bpw)  in spi_is_bpw_supported()  argument
1317 	u32 bpw_mask = spi->controller->bits_per_word_mask;  in spi_is_bpw_supported()
1326  * spi_controller_xfer_timeout - Compute a suitable timeout value
1327  * @ctlr: SPI device
1339 	return max(xfer->len * 8 * 2 / (xfer->speed_hz / 1000), 500U);  in spi_controller_xfer_timeout()
1342 /*---------------------------------------------------------------------------*/
1344 /* SPI transfer replacement methods which make use of spi_res */
1351  * struct spi_replaced_transfers - structure describing the spi_transfer
1360  *                      are to get re-inserted
1362  * @inserted_transfers: array of spi_transfers of array-size @inserted,
1378 /*---------------------------------------------------------------------------*/
1380 /* SPI transfer transformation methods */
1389 /*---------------------------------------------------------------------------*/
1392  * All these synchronous SPI transfer routines are utilities layered
1397 extern int spi_sync(struct spi_device *spi, struct spi_message *message);
1398 extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message);
1403  * spi_sync_transfer - synchronous SPI data transfer
1404  * @spi: device with which data will be exchanged
1409  * Does a synchronous SPI data transfer of the given spi_transfer array.
1416 spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers,  in spi_sync_transfer()  argument
1423 	return spi_sync(spi, &msg);  in spi_sync_transfer()
1427  * spi_write - SPI synchronous write
1428  * @spi: device to which data will be written
1439 spi_write(struct spi_device *spi, const void *buf, size_t len)  in spi_write()  argument
1446 	return spi_sync_transfer(spi, &t, 1);  in spi_write()
1450  * spi_read - SPI synchronous read
1451  * @spi: device from which data will be read
1462 spi_read(struct spi_device *spi, void *buf, size_t len)  in spi_read()  argument
1469 	return spi_sync_transfer(spi, &t, 1);  in spi_read()
1473 extern int spi_write_then_read(struct spi_device *spi,
1478  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1479  * @spi: device with which data will be exchanged
1488 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)  in spi_w8r8()  argument
1493 	status = spi_write_then_read(spi, &cmd, 1, &result, 1);  in spi_w8r8()
1500  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1501  * @spi: device with which data will be exchanged
1505  * The number is returned in wire-order, which is at least sometimes
1506  * big-endian.
1513 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)  in spi_w8r16()  argument
1518 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16()
1525  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1526  * @spi: device with which data will be exchanged
1531  * convert the read 16 bit data word from big-endian to native endianness.
1538 static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd)  in spi_w8r16be()  argument
1544 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16be()
1551 /*---------------------------------------------------------------------------*/
1554  * INTERFACE between board init code and SPI infrastructure.
1556  * No SPI driver ever sees these SPI device table segments, but
1557  * it's how the SPI core (or adapters that get hotplugged) grows
1560  * As a rule, SPI devices can't be probed.  Instead, board init code
1563  * support for non-static configurations too; enough to handle adding
1564  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1568  * struct spi_board_info - board-specific template for a SPI device
1571  *	data stored there is driver-specific.
1577  *	from the chip datasheet and board-specific signal quality issues.
1586  * When adding new SPI devices to the device tree, these structures serve
1592  * be stored in tables of board-specific device descriptors, which are
1638 	 *  - quirks like clock rate mattering when not selected
1646 /* Board init code may ignore whether SPI is configured or not */
1668 spi_add_device(struct spi_device *spi);
1673 extern void spi_unregister_device(struct spi_device *spi);
1684 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()