1 /* SPDX-License-Identifier: GPL-2.0-or-later
28  * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
34  * struct spi_statistics - statistics for spi transfers
37  * @messages:      number of spi-messages handled
53  *                 transfer bytes histogramm
88 		spin_lock_irqsave(&(stats)->lock, flags);	\
89 		(stats)->field += count;			\
90 		spin_unlock_irqrestore(&(stats)->lock, flags);	\
97  * struct spi_delay - SPI delay information
113  * struct spi_device - Controller side proxy for an SPI slave device
119  *	The spi_transfer.speed_hz can override this for each transfer.
121  * @mode: The spi mode defines how data is clocked out and in.
125  *	each word in a transfer (by specifying SPI_LSB_FIRST).
126  * @bits_per_word: Data transfers involve one or more words; word sizes
127  *	like eight or 12 bits are common.  In-memory wordsizes are
131  *	The spi_transfer.bits_per_word can override this for each transfer.
136  * @controller_data: Board-specific definitions for controller, such as
143  * @cs_gpio: LEGACY: gpio number of the chipselect line (optional, -ENOENT when
149  *	words of a transfer
157  * A @spi_device is used to interchange data between an SPI slave
185 #define SPI_MODE_KERNEL_MASK	(~(BIT(30) - 1))
194 	struct spi_delay	word_delay; /* inter-word delay */
206 	 *  - memory packing (12 bit samples into low bits, others zeroed)
207 	 *  - priority
208 	 *  - chipselect delays
209 	 *  - ...
225 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
231 		put_device(&spi->dev);  in spi_dev_put()
237 	return spi->controller_state;  in spi_get_ctldata()
242 	spi->controller_state = state;  in spi_set_ctldata()
245 /* device driver data */
247 static inline void spi_set_drvdata(struct spi_device *spi, void *data)  in spi_set_drvdata()  argument
249 	dev_set_drvdata(&spi->dev, data);  in spi_set_drvdata()
254 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
260  * struct spi_driver - Host side "protocol" driver
300  * spi_unregister_driver - reverse effect of spi_register_driver
307 		driver_unregister(&sdrv->driver);  in spi_unregister_driver()
317  * module_spi_driver() - Helper macro for registering a SPI driver
329  * struct spi_controller - interface to SPI master or slave controller
332  * @bus_num: board-specific (and often SOC-specific) identifier for a
343  *	supported. If set, the SPI core will reject any transfer with an
346  * @min_speed_hz: Lowest supported transfer speed
347  * @max_speed_hz: Highest supported transfer speed
350  * @devm_allocated: whether the allocation of this struct is devres-managed
351  * @max_transfer_size: function that returns the max transfer size for
367  * @transfer: adds a message to the controller's transfer queue.
368  * @cleanup: frees controller-specific state
376  * @cur_msg: the currently in-flight message
378  *                    in-flight message
389  * @max_dma_len: Maximum length of a DMA transfer for the device.
391  *	so the subsystem requests the driver to prepare the transfer hardware
393  * @transfer_one_message: the subsystem calls the driver to transfer a single
404  * @prepare_message: set up the controller to transfer a single message,
407  * @transfer_one: transfer a single spi_transfer.
409  *                  - return 0 if the transfer is finished,
410  *                  - return 1 if the transfer is still in progress. When
411  *                    the driver is finished with this transfer it must
413  *                    can issue the next transfer. Note: transfer_one and
423  * @slave_abort: abort the ongoing transfer request on an SPI slave controller
425  *	CS number. Any individual value may be -ENOENT for CS lines that
444  * @dummy_rx: dummy receive buffer for full-duplex devices
445  * @dummy_tx: dummy transmit buffer for full-duplex devices
450  *	time snapshot in @spi_transfer->ptp_sts as close as possible to the
451  *	moment in time when @spi_transfer->ptp_sts_word_pre and
452  *	@spi_transfer->ptp_sts_word_post were transmitted.
454  *	close to the driver hand-over as possible.
456  * @fallback: fallback to pio if dma transfer return failure with
466  * a queue of spi_message transactions, copying data between CPU memory and
476 	 * board-specific.  usually that simplifies to being SOC-specific.
478 	 * and one board's schematics might show it using SPI-2.  software
484 	 * might use board-specific GPIOs.
501 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
502 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
504 	/* limits on transfer speed */
518 	/* flag indicating if the allocation of this struct is devres-managed */
525 	 * on some hardware transfer / message size may be constrained
526 	 * the limit may depend on device transfer settings
564 	 * + The transfer() method may not sleep; its main role is
566 	 * + For now there's no remove-from-queue operation, or
571 	 *   selecting a chip (for masters), then transferring data
581 	int			(*transfer)(struct spi_device *spi,  member
589 	 * exists and returns true then the transfer will be mapped
601 	 * controller transfer queueing mechanism. If these are used, the
602 	 * transfer() function above must NOT be specified by the driver.
640 			    struct spi_transfer *transfer);
644 	/* Optimized handlers for SPI memory-like operations. */
661 	/* dummy data for full duplex devices */
679 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
683 					      void *data)  in spi_controller_set_devdata()  argument
685 	dev_set_drvdata(&ctlr->dev, data);  in spi_controller_set_devdata()
690 	if (!ctlr || !get_device(&ctlr->dev))  in spi_controller_get()
698 		put_device(&ctlr->dev);  in spi_controller_put()
703 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->slave;  in spi_controller_is_slave()
715 /* Helper calls for driver to timestamp transfer */
777  * struct spi_res - spi resource management structure
780  * @data:    extra data allocated for the specific use-case
782  * this is based on ideas from devres, but focused on life-cycle
788 	unsigned long long      data[]; /* guarantee ull alignment */  member
800 /*---------------------------------------------------------------------------*/
805  * Protocol drivers use a queue of spi_messages, each transferring data
808  * The spi_messages themselves consist of a series of read+write transfer
816  * well as the data buffers) for as long as the message is queued.
820  * struct spi_transfer - a read/write buffer pair
821  * @tx_buf: data to be written (dma-safe memory), or NULL
822  * @rx_buf: data to be read (dma-safe memory), or NULL
831  *      transfer. If 0 the default (from @spi_device) is used.
833  *      for this transfer. If 0 the default (from @spi_device) is used.
834  * @dummy_data: indicates transfer is dummy bytes transfer.
835  * @cs_change: affects chipselect after this transfer completes
838  * @delay: delay to be introduced after this transfer before
840  *	the next transfer or completing this @spi_message.
843  * @effective_speed_hz: the effective SCK-speed that was used to
844  *      transfer this transfer. Set to 0 if the spi bus driver does
851  *	snapshot for this transfer begins. Upon completing the SPI transfer,
853  *	on the available snapshotting resolution (DMA transfer,
859  *	@ptp_sts_word_post to the length of the transfer. This is done
860  *	purposefully (instead of setting to spi_transfer->len - 1) to denote
861  *	that a transfer-level snapshot taken from within the driver may still
865  *	hardware has some sort of assist for retrieving exact transfer timing,
872  * @timestamped: true if the transfer has been timestamped
878  * the data being transferred; that may reduce overhead, when the
882  * while filling @rx_buf.  If the receive buffer is null, the data
888  * In-memory data values are always in native CPU byte order, translated
889  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
893  * When the word size of the SPI transfer is not a power-of-two multiple
894  * of eight bits, those in-memory words include extra bits.  In-memory
895  * words are always seen by protocol drivers as right-justified, so the
899  * it stays selected until after the last transfer in a message.  Drivers
902  * (i) If the transfer isn't the last one in the message, this flag is
908  * (ii) When the transfer is the last one in the message, the chip may
909  * stay selected until the next transfer.  On multi-device SPI busses
918  * When SPI can transfer in 1x,2x or 4x. It can get this transfer information
919  * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
920  * two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x)
921  * SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer.
925  * Zero-initialize every field you don't set up explicitly, to
933 	 *   spi_message.is_dma_mapped reports a pre-existing mapping
948 #define	SPI_NBITS_SINGLE	0x01 /* 1bit transfer */
949 #define	SPI_NBITS_DUAL		0x02 /* 2bits transfer */
950 #define	SPI_NBITS_QUAD		0x04 /* 4bits transfer */
973  * struct spi_message - one multi-segment SPI transaction
974  * @transfers: list of transfer segments in this transaction
977  *	addresses for each transfer buffer
988  * A @spi_message is used to execute an atomic sequence of data transfers,
992  * a single programmed DMA transfer.  On all systems, these messages are
998  * Zero-initialize every field you don't set up explicitly, to
1010 	 * last transfer ... allowing things like "read 16 bit length L"
1014 	 * Some controller drivers (message-at-a-time queue processing)
1016 	 * others (with multi-message pipelines) could need a flag to
1040 	INIT_LIST_HEAD(&m->transfers);  in spi_message_init_no_memset()
1041 	INIT_LIST_HEAD(&m->resources);  in spi_message_init_no_memset()
1053 	list_add_tail(&t->transfer_list, &m->transfers);  in spi_message_add_tail()
1059 	list_del(&t->transfer_list);  in spi_transfer_del()
1065 	return spi_delay_exec(&t->delay, t);  in spi_transfer_delay_exec()
1069  * spi_message_init_with_transfers - Initialize spi_message and append transfers
1088 /* It's fine to embed message and transaction structures in other data
1124 	struct spi_controller *ctlr = spi->controller;  in spi_max_message_size()
1126 	if (!ctlr->max_message_size)  in spi_max_message_size()
1128 	return ctlr->max_message_size(spi);  in spi_max_message_size()
1134 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1138 	if (ctlr->max_transfer_size)  in spi_max_transfer_size()
1139 		tr_max = ctlr->max_transfer_size(spi);  in spi_max_transfer_size()
1141 	/* transfer size limit must not be greater than messsage size limit */  in spi_max_transfer_size()
1146  * spi_is_bpw_supported - Check if bits per word is supported
1157 	u32 bpw_mask = spi->master->bits_per_word_mask;  in spi_is_bpw_supported()
1165 /*---------------------------------------------------------------------------*/
1167 /* SPI transfer replacement methods which make use of spi_res */
1174  * struct spi_replaced_transfers - structure describing the spi_transfer
1179  * @extradata:          pointer to some extra data if requested or NULL
1182  * @replaced_after:     the transfer after which the @replaced_transfers
1183  *                      are to get re-inserted
1185  * @inserted_transfers: array of spi_transfers of array-size @inserted,
1210 /*---------------------------------------------------------------------------*/
1212 /* SPI transfer transformation methods */
1219 /*---------------------------------------------------------------------------*/
1221 /* All these synchronous SPI transfer routines are utilities layered
1222  * over the core async transfer primitive.  Here, "synchronous" means
1223  * they will sleep uninterruptibly until the async transfer completes.
1232  * spi_sync_transfer - synchronous SPI data transfer
1233  * @spi: device with which data will be exchanged
1238  * Does a synchronous SPI data transfer of the given spi_transfer array.
1256  * spi_write - SPI synchronous write
1257  * @spi: device to which data will be written
1258  * @buf: data buffer
1259  * @len: data buffer size
1279  * spi_read - SPI synchronous read
1280  * @spi: device from which data will be read
1281  * @buf: data buffer
1282  * @len: data buffer size
1301 /* this copies txbuf and rxbuf data; for small transfers only! */
1307  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1308  * @spi: device with which data will be exchanged
1309  * @cmd: command to be written before data is read back
1329  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1330  * @spi: device with which data will be exchanged
1331  * @cmd: command to be written before data is read back
1334  * The number is returned in wire-order, which is at least sometimes
1335  * big-endian.
1354  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1355  * @spi: device with which data will be exchanged
1356  * @cmd: command to be written before data is read back
1360  * convert the read 16 bit data word from big-endian to native endianness.
1380 /*---------------------------------------------------------------------------*/
1393  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1397  * struct spi_board_info - board-specific template for a SPI device
1400  *	data stored there is driver-specific.
1406  *	from the chip datasheet and board-specific signal quality issues.
1418  * as the default transfer wordsize) is not included here.
1421  * be stored in tables of board-specific device descriptors, which are
1460 	/* ... may need additional spi_device chip config data here.
1463 	 *  - quirks like clock rate mattering when not selected
1505 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()