1 /* SPDX-License-Identifier: GPL-2.0-or-later
10 #include <linux/bits.h>
23 /* Max no. of CS supported per spi device */
36  * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
42  * struct spi_statistics - statistics for spi transfers
43  * @syncp:         seqcount to protect members in this struct for per-cpu update
44  *                 on 32-bit systems
46  * @messages:      number of spi-messages handled
95 		u64_stats_update_begin(&__lstats->syncp);		\
96 		u64_stats_add(&__lstats->field, count);			\
97 		u64_stats_update_end(&__lstats->syncp);			\
106 		u64_stats_update_begin(&__lstats->syncp);		\
107 		u64_stats_inc(&__lstats->field);			\
108 		u64_stats_update_end(&__lstats->syncp);			\
113  * struct spi_delay - SPI delay information
131  * struct spi_device - Controller side proxy for an SPI slave device
138  * @chip_select: Array of physical chipselect, spi->chipselect[i] gives
144  *	each word in a transfer (by specifying SPI_LSB_FIRST).
145  * @bits_per_word: Data transfers involve one or more words; word sizes
146  *	like eight or 12 bits are common.  In-memory wordsizes are
147  *	powers of two bytes (e.g. 20 bit samples use 32 bits).
155  * @controller_data: Board-specific definitions for controller, such as
200 	 * only half-duplex, the wait state detection needs to be implemented
206 	 * All bits defined above should be covered by SPI_MODE_KERNEL_MASK.
209 	 * The bits defined here are from bit 31 downwards, while in
211 	 * These bits must not overlap. A static assert check should make sure of that.
212 	 * If adding extra bits, make sure to decrease the bit index below as well.
214 #define SPI_MODE_KERNEL_MASK	(~(BIT(29) - 1))
222 	struct spi_delay	word_delay; /* Inter-word delay */
241 	 *  - memory packing (12 bit samples into low bits, others zeroed)
242 	 *  - priority
243 	 *  - chipselect delays
244 	 *  - ...
260 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
266 		put_device(&spi->dev);  in spi_dev_put()
272 	return spi->controller_state;  in spi_get_ctldata()
277 	spi->controller_state = state;  in spi_set_ctldata()
284 	dev_set_drvdata(&spi->dev, data);  in spi_set_drvdata()
289 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
294 	return spi->chip_select[idx];  in spi_get_chipselect()
299 	spi->chip_select[idx] = chipselect;  in spi_set_chipselect()
304 	return spi->cs_gpiod[idx];  in spi_get_csgpiod()
309 	spi->cs_gpiod[idx] = csgpiod;  in spi_set_csgpiod()
324  * struct spi_driver - Host side "protocol" driver
364  * spi_unregister_driver - reverse effect of spi_register_driver
371 		driver_unregister(&sdrv->driver);  in spi_unregister_driver()
381  * module_spi_driver() - Helper macro for registering a SPI driver
393  * struct spi_controller - interface to SPI master or slave controller
396  * @bus_num: board-specific (and often SOC-specific) identifier for a
415  * @devm_allocated: whether the allocation of this struct is devres-managed
416  * @max_transfer_size: function that returns the max transfer size for
418  * @max_message_size: function that returns the max message size for
425  * @multi_cs_cap: indicates that the SPI Controller can assert/de-assert
436  * @cleanup: frees controller-specific state
446  * @cur_msg: the currently in-flight message
447  * @cur_msg_completion: a completion for the current in-flight message
455  * @last_cs: the last chip_select that is recorded by set_cs, -1 on non chip
485  *                  - return 0 if the transfer is finished,
486  *                  - return 1 if the transfer is still in progress. When
491  *                    spi_transfer->error first, before calling
505  * @cs_gpiods: Array of GPIO descriptors to use as chip select lines; one per CS
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.
530  *	close to the driver hand-over as possible.
556 	 * board-specific. Usually that simplifies to being SoC-specific.
558 	 * and one board's schematics might show it using SPI-2. Software
565 	 * might use board-specific GPIOs.
582 #define SPI_BPW_MASK(bits) BIT((bits) - 1)  argument
583 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)  argument
599 	 * The spi-controller has multi chip select capability and can
600 	 * assert/de-assert more than one chip select at once.
604 	/* Flag indicating if the allocation of this struct is devres-managed */
658 	 * + For now there's no remove-from-queue operation, or
743 	/* Optimized handlers for SPI memory-like operations. */
782 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
788 	dev_set_drvdata(&ctlr->dev, data);  in spi_controller_set_devdata()
793 	if (!ctlr || !get_device(&ctlr->dev))  in spi_controller_get()
801 		put_device(&ctlr->dev);  in spi_controller_put()
806 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->slave;  in spi_controller_is_slave()
811 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->target;  in spi_controller_is_target()
921  * struct spi_res - SPI resource management structure
924  * @data:    extra data allocated for the specific use-case
926  * This is based on ideas from devres, but focused on life-cycle
935 /*---------------------------------------------------------------------------*/
944  * segments.  Those segments always read the same number of bits as they
955  * struct spi_transfer - a read/write buffer pair
956  * @tx_buf: data to be written (DMA-safe memory), or NULL
957  * @rx_buf: data to be read (DMA-safe memory), or NULL
960  * @tx_nbits: number of bits used for writing. If 0 the default
962  * @rx_nbits: number of bits used for reading. If 0 the default
977  * @word_delay: inter word delay to be introduced after each word size
979  * @effective_speed_hz: the effective SCK-speed that was used to
985  * @ptp_sts_word_pre: The word (subject to bits_per_word semantics) offset
996  *	purposefully (instead of setting to spi_transfer->len - 1) to denote
997  *	that a transfer-level snapshot taken from within the driver may still
1005  *	processed the word, i.e. the "pre" timestamp should be taken before
1006  *	transmitting the "pre" word, and the "post" timestamp after receiving
1007  *	transmit confirmation from the controller for the "post" word.
1020  * It's an error to try to shift out a partial word.  (For example, by
1021  * shifting out three bytes with word size of sixteen or twenty bits;
1022  * the former uses two bytes per word, the latter uses four bytes.)
1024  * In-memory data values are always in native CPU byte order, translated
1025  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
1029  * When the word size of the SPI transfer is not a power-of-two multiple
1030  * of eight bits, those in-memory words include extra bits.  In-memory
1031  * words are always seen by protocol drivers as right-justified, so the
1032  * undefined (rx) or unused (tx) bits are always the most significant bits.
1045  * stay selected until the next transfer.  On multi-device SPI busses
1055  * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
1061  * Zero-initialize every field you don't set up explicitly, to
1070 	 * spi_message.is_dma_mapped reports a pre-existing mapping.
1091 #define	SPI_NBITS_SINGLE	0x01 /* 1-bit transfer */
1092 #define	SPI_NBITS_DUAL		0x02 /* 2-bit transfer */
1093 #define	SPI_NBITS_QUAD		0x04 /* 4-bit transfer */
1111  * struct spi_message - one multi-segment SPI transaction
1137  * Zero-initialize every field you don't set up explicitly, to
1157 	 * Some controller drivers (message-at-a-time queue processing)
1159 	 * others (with multi-message pipelines) could need a flag to
1184 	INIT_LIST_HEAD(&m->transfers);  in spi_message_init_no_memset()
1185 	INIT_LIST_HEAD(&m->resources);  in spi_message_init_no_memset()
1197 	list_add_tail(&t->transfer_list, &m->transfers);  in spi_message_add_tail()
1203 	list_del(&t->transfer_list);  in spi_transfer_del()
1209 	return spi_delay_exec(&t->delay, t);  in spi_transfer_delay_exec()
1213  * spi_message_init_with_transfers - Initialize spi_message and append transfers
1248 	spi_message_init_no_memset(&mwt->m);  in spi_message_alloc()
1250 		spi_message_add_tail(&mwt->t[i], &mwt->m);  in spi_message_alloc()
1252 	return &mwt->m;  in spi_message_alloc()
1268 	struct spi_controller *ctlr = spi->controller;  in spi_max_message_size()
1270 	if (!ctlr->max_message_size)  in spi_max_message_size()
1272 	return ctlr->max_message_size(spi);  in spi_max_message_size()
1278 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1282 	if (ctlr->max_transfer_size)  in spi_max_transfer_size()
1283 		tr_max = ctlr->max_transfer_size(spi);  in spi_max_transfer_size()
1290  * spi_is_bpw_supported - Check if bits per word is supported
1292  * @bpw: Bits per word
1301 	u32 bpw_mask = spi->master->bits_per_word_mask;  in spi_is_bpw_supported()
1310  * spi_controller_xfer_timeout - Compute a suitable timeout value
1323 	return max(xfer->len * 8 * 2 / (xfer->speed_hz / 1000), 500U);  in spi_controller_xfer_timeout()
1326 /*---------------------------------------------------------------------------*/
1335  * struct spi_replaced_transfers - structure describing the spi_transfer
1344  *                      are to get re-inserted
1346  * @inserted_transfers: array of spi_transfers of array-size @inserted,
1362 /*---------------------------------------------------------------------------*/
1375 /*---------------------------------------------------------------------------*/
1389  * spi_sync_transfer - synchronous SPI data transfer
1413  * spi_write - SPI synchronous write
1436  * spi_read - SPI synchronous read
1464  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1486  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1491  * The number is returned in wire-order, which is at least sometimes
1492  * big-endian.
1511  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1517  * convert the read 16 bit data word from big-endian to native endianness.
1537 /*---------------------------------------------------------------------------*/
1549  * support for non-static configurations too; enough to handle adding
1550  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1554  * struct spi_board_info - board-specific template for a SPI device
1557  *	data stored there is driver-specific.
1563  *	from the chip datasheet and board-specific signal quality issues.
1578  * be stored in tables of board-specific device descriptors, which are
1624 	 *  - quirks like clock rate mattering when not selected
1670 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()