1 /* SPDX-License-Identifier: GPL-2.0-or-later
25  * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
31  * struct spi_statistics - statistics for spi transfers
34  * @messages:      number of spi-messages handled
85 		spin_lock_irqsave(&(stats)->lock, flags);	\
86 		(stats)->field += count;			\
87 		spin_unlock_irqrestore(&(stats)->lock, flags);	\
94  * struct spi_delay - SPI delay information
110  * struct spi_device - Controller side proxy for an SPI slave device
122  *	each word in a transfer (by specifying SPI_LSB_FIRST).
123  * @bits_per_word: Data transfers involve one or more words; word sizes
124  *	like eight or 12 bits are common.  In-memory wordsizes are
133  * @controller_data: Board-specific definitions for controller, such as
140  * @cs_gpio: LEGACY: gpio number of the chipselect line (optional, -ENOENT when
175 #define	SPI_LSB_FIRST	0x08			/* per-word bits-on-wire */
184 #define	SPI_CS_WORD	0x1000			/* toggle cs after each word */
195 	struct spi_delay	word_delay; /* inter-word delay */
203 	 *  - memory packing (12 bit samples into low bits, others zeroed)
204 	 *  - priority
205 	 *  - chipselect delays
206 	 *  - ...
218 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
224 		put_device(&spi->dev);  in spi_dev_put()
230 	return spi->controller_state;  in spi_get_ctldata()
235 	spi->controller_state = state;  in spi_set_ctldata()
242 	dev_set_drvdata(&spi->dev, data);  in spi_set_drvdata()
247 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
254  * struct spi_driver - Host side "protocol" driver
294  * spi_unregister_driver - reverse effect of spi_register_driver
301 		driver_unregister(&sdrv->driver);  in spi_unregister_driver()
309  * module_spi_driver() - Helper macro for registering a SPI driver
321  * struct spi_controller - interface to SPI master or slave controller
324  * @bus_num: board-specific (and often SOC-specific) identifier for a
359  * @cleanup: frees controller-specific state
367  * @cur_msg: the currently in-flight message
369  *                    in-flight message
400  *                  - return 0 if the transfer is finished,
401  *                  - return 1 if the transfer is still in progress. When
421  *	CS number. Any individual value may be -ENOENT for CS lines that
440  * @dummy_rx: dummy receive buffer for full-duplex devices
441  * @dummy_tx: dummy transmit buffer for full-duplex devices
446  *	time snapshot in @spi_transfer->ptp_sts as close as possible to the
447  *	moment in time when @spi_transfer->ptp_sts_word_pre and
448  *	@spi_transfer->ptp_sts_word_post were transmitted.
450  *	close to the driver hand-over as possible.
472 	 * board-specific.  usually that simplifies to being SOC-specific.
474 	 * and one board's schematics might show it using SPI-2.  software
480 	 * might use board-specific GPIOs.
497 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
498 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
557 	 * + For now there's no remove-from-queue operation, or
634 	/* Optimized handlers for SPI memory-like operations. */
674 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
680 	dev_set_drvdata(&ctlr->dev, data);  in spi_controller_set_devdata()
685 	if (!ctlr || !get_device(&ctlr->dev))  in spi_controller_get()
693 		put_device(&ctlr->dev);  in spi_controller_put()
698 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->slave;  in spi_controller_is_slave()
772  * struct spi_res - spi resource management structure
775  * @data:    extra data allocated for the specific use-case
777  * this is based on ideas from devres, but focused on life-cycle
795 /*---------------------------------------------------------------------------*/
815  * struct spi_transfer - a read/write buffer pair
816  * @tx_buf: data to be written (dma-safe memory), or NULL
817  * @rx_buf: data to be read (dma-safe memory), or NULL
838  * @word_delay: inter word delay to be introduced after each word size
840  * @effective_speed_hz: the effective SCK-speed that was used to
846  * @ptp_sts_word_pre: The word (subject to bits_per_word semantics) offset
857  *	purposefully (instead of setting to spi_transfer->len - 1) to denote
858  *	that a transfer-level snapshot taken from within the driver may still
866  *	processed the word, i.e. the "pre" timestamp should be taken before
867  *	transmitting the "pre" word, and the "post" timestamp after receiving
868  *	transmit confirmation from the controller for the "post" word.
881  * It's an error to try to shift out a partial word.  (For example, by
882  * shifting out three bytes with word size of sixteen or twenty bits;
883  * the former uses two bytes per word, the latter uses four bytes.)
885  * In-memory data values are always in native CPU byte order, translated
886  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
890  * When the word size of the SPI transfer is not a power-of-two multiple
891  * of eight bits, those in-memory words include extra bits.  In-memory
892  * words are always seen by protocol drivers as right-justified, so the
906  * stay selected until the next transfer.  On multi-device SPI busses
916  * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
922  * Zero-initialize every field you don't set up explicitly, to
930 	 *   spi_message.is_dma_mapped reports a pre-existing mapping
970  * struct spi_message - one multi-segment SPI transaction
995  * Zero-initialize every field you don't set up explicitly, to
1011 	 * Some controller drivers (message-at-a-time queue processing)
1013 	 * others (with multi-message pipelines) could need a flag to
1037 	INIT_LIST_HEAD(&m->transfers);  in spi_message_init_no_memset()
1038 	INIT_LIST_HEAD(&m->resources);  in spi_message_init_no_memset()
1050 	list_add_tail(&t->transfer_list, &m->transfers);  in spi_message_add_tail()
1056 	list_del(&t->transfer_list);  in spi_transfer_del()
1064 	if (t->delay_usecs) {  in spi_transfer_delay_exec()
1065 		d.value = t->delay_usecs;  in spi_transfer_delay_exec()
1070 	return spi_delay_exec(&t->delay, t);  in spi_transfer_delay_exec()
1074  * spi_message_init_with_transfers - Initialize spi_message and append transfers
1134 	struct spi_controller *ctlr = spi->controller;  in spi_max_message_size()
1136 	if (!ctlr->max_message_size)  in spi_max_message_size()
1138 	return ctlr->max_message_size(spi);  in spi_max_message_size()
1144 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1148 	if (ctlr->max_transfer_size)  in spi_max_transfer_size()
1149 		tr_max = ctlr->max_transfer_size(spi);  in spi_max_transfer_size()
1156  * spi_is_bpw_supported - Check if bits per word is supported
1158  * @bpw: Bits per word
1167 	u32 bpw_mask = spi->master->bits_per_word_mask;  in spi_is_bpw_supported()
1175 /*---------------------------------------------------------------------------*/
1184  * struct spi_replaced_transfers - structure describing the spi_transfer
1193  *                      are to get re-inserted
1195  * @inserted_transfers: array of spi_transfers of array-size @inserted,
1220 /*---------------------------------------------------------------------------*/
1229 /*---------------------------------------------------------------------------*/
1242  * spi_sync_transfer - synchronous SPI data transfer
1266  * spi_write - SPI synchronous write
1289  * spi_read - SPI synchronous read
1317  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1339  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1344  * The number is returned in wire-order, which is at least sometimes
1345  * big-endian.
1364  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1370  * convert the read 16 bit data word from big-endian to native endianness.
1390 /*---------------------------------------------------------------------------*/
1403  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1407  * struct spi_board_info - board-specific template for a SPI device
1410  *	data stored there is driver-specific.
1416  *	from the chip datasheet and board-specific signal quality issues.
1431  * be stored in tables of board-specific device descriptors, which are
1474 	 *  - quirks like clock rate mattering when not selected
1516 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()