1 /* SPDX-License-Identifier: GPL-2.0-or-later
19 #include <uapi/linux/spi/spi.h>
28  * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
29  * and SPI infrastructure.
34  * struct spi_statistics - statistics for spi transfers
37  * @messages:      number of spi-messages handled
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
115  * @controller: SPI controller used with the device.
116  * @master: Copy of controller, for backwards compatibility.
120  * @chip_select: Chipselect, distinguishing chips handled by @controller.
121  * @mode: The spi mode defines how data is clocked out and in.
127  *	like eight or 12 bits are common.  In-memory wordsizes are
135  * @controller_state: Controller's runtime state
136  * @controller_data: Board-specific definitions for controller, such as
143  * @cs_gpio: LEGACY: gpio number of the chipselect line (optional, -ENOENT when
150  * @cs_setup: delay to be introduced by the controller after CS is asserted
151  * @cs_hold: delay to be introduced by the controller before CS is deasserted
152  * @cs_inactive: delay to be introduced by the controller after CS is
157  * A @spi_device is used to interchange data between an SPI slave
162  * to its controller.  One example might be an identifier for a chip
168 	struct spi_controller	*controller;  member
179 	 * which is defined in 'include/uapi/linux/spi/spi.h'.
185 #define SPI_MODE_KERNEL_MASK	(~(BIT(30) - 1))
194 	struct spi_delay	word_delay; /* inter-word delay */
205 	 * the controller talks to each chip, like:
206 	 *  - memory packing (12 bit samples into low bits, others zeroed)
207 	 *  - priority
208 	 *  - chipselect delays
209 	 *  - ...
223 static inline struct spi_device *spi_dev_get(struct spi_device *spi)  in spi_dev_get()  argument
225 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
228 static inline void spi_dev_put(struct spi_device *spi)  in spi_dev_put()  argument
230 	if (spi)  in spi_dev_put()
231 		put_device(&spi->dev);  in spi_dev_put()
235 static inline void *spi_get_ctldata(struct spi_device *spi)  in spi_get_ctldata()  argument
237 	return spi->controller_state;  in spi_get_ctldata()
240 static inline void spi_set_ctldata(struct spi_device *spi, void *state)  in spi_set_ctldata()  argument
242 	spi->controller_state = state;  in spi_set_ctldata()
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()
252 static inline void *spi_get_drvdata(struct spi_device *spi)  in spi_get_drvdata()  argument
254 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
260  * struct spi_driver - Host side "protocol" driver
261  * @id_table: List of SPI devices supported by this driver
262  * @probe: Binds this driver to the spi device.  Drivers can verify
266  * @remove: Unbinds this driver from the spi device
269  * @driver: SPI device drivers should initialize the name and owner
272  * This represents the kind of device driver that uses SPI messages to
273  * interact with the hardware at the other end of a SPI link.  It's called
275  * directly to SPI hardware (which is what the underlying SPI controller
286 	int			(*probe)(struct spi_device *spi);
287 	int			(*remove)(struct spi_device *spi);
288 	void			(*shutdown)(struct spi_device *spi);
300  * spi_unregister_driver - reverse effect of spi_register_driver
307 		driver_unregister(&sdrv->driver);  in spi_unregister_driver()
310 extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 chip_select);
317  * module_spi_driver() - Helper macro for registering a SPI driver
320  * Helper macro for SPI drivers which do not do anything special in module
329  * struct spi_controller - interface to SPI master or slave controller
332  * @bus_num: board-specific (and often SOC-specific) identifier for a
333  *	given SPI controller.
335  *	SPI slaves, and are numbered from zero to num_chipselects.
338  * @dma_alignment: SPI controller constraint on DMA buffers alignment.
339  * @mode_bits: flags understood by this controller driver
340  * @buswidth_override_bits: flags to override for this controller driver
343  *	supported. If set, the SPI core will reject any transfer with an
349  * @slave: indicates that this is an SPI slave controller
350  * @devm_allocated: whether the allocation of this struct is devres-managed
356  * @bus_lock_spinlock: spinlock for SPI bus locking
358  * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
360  *	device's SPI controller; protocol code may call this.  This
364  * @set_cs_timing: optional hook for SPI devices to request SPI master
365  * controller for configuring specific CS setup time, hold time and inactive
367  * @transfer: adds a message to the controller's transfer queue.
368  * @cleanup: frees controller-specific state
369  * @can_dma: determine whether this controller supports DMA
370  * @queued: whether this controller is providing an internal message queue
376  * @cur_msg: the currently in-flight message
378  *                    in-flight message
404  * @prepare_message: set up the controller to transfer a single message,
409  *                  - return 0 if the transfer is finished,
410  *                  - return 1 if the transfer is still in progress. When
419  * @mem_ops: optimized/dedicated operations for interactions with SPI memory.
421  *	     controller has native support for memory like operations.
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
426  *	are not GPIOs (driven by the SPI controller itself). Use the cs_gpiods
430  *	are not GPIOs (driven by the SPI controller itself).
431  * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab
434  *	and SPI devices will have the cs_gpiod assigned rather than cs_gpio.
436  *	fill in this field with the first unused native CS, to be used by SPI
437  *	controller drivers that need to drive a native CS when using GPIO CS.
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.
453  *	If the driver does not set this, the SPI core takes the snapshot as
454  *	close to the driver hand-over as possible.
459  * Each SPI controller can communicate with one or more @spi_device
465  * The driver for an SPI controller manages access to those devices through
467  * an SPI slave device.  For each such message it queues, it calls the
476 	 * board-specific.  usually that simplifies to being SOC-specific.
477 	 * example:  one SOC has three SPI controllers, numbered 0..2,
478 	 * and one board's schematics might show it using SPI-2.  software
479 	 * would normally use bus_num=2 for that controller.
484 	 * might use board-specific GPIOs.
488 	/* some SPI controllers pose alignment requirements on DMAable
493 	/* spi_device.mode flags understood by this controller driver */
496 	/* spi_device.mode flags override flags for this controller */
501 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
502 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
518 	/* flag indicating if the allocation of this struct is devres-managed */
521 	/* flag indicating this is an SPI slave controller */
528 	size_t (*max_transfer_size)(struct spi_device *spi);
529 	size_t (*max_message_size)(struct spi_device *spi);
537 	/* lock and mutex for SPI bus locking */
541 	/* flag indicating that the SPI bus is locked for exclusive use */
544 	/* Setup mode and clock, etc (spi driver may call many times).
550 	int			(*setup)(struct spi_device *spi);
553 	 * set_cs_timing() method is for SPI controllers that supports
556 	 * This hook allows SPI client drivers to request SPI controllers
560 	int (*set_cs_timing)(struct spi_device *spi);
566 	 * + For now there's no remove-from-queue operation, or
570 	 * + The controller's main job is to process its message queue,
578 	 * + The message transfers use clock and SPI mode parameters
581 	int			(*transfer)(struct spi_device *spi,
585 	void			(*cleanup)(struct spi_device *spi);
595 					   struct spi_device *spi,
601 	 * controller transfer queueing mechanism. If these are used, the
603 	 * Over time we expect SPI drivers to be phased over to this API.
638 	void (*set_cs)(struct spi_device *spi, bool enable);
639 	int (*transfer_one)(struct spi_controller *ctlr, struct spi_device *spi,
644 	/* Optimized handlers for SPI memory-like operations. */
668 	 * Driver sets this field to indicate it is able to snapshot SPI
679 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
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()
723 /* the spi driver core manages memory for the spi_controller classdev */
769  * SPI resource management while processing a SPI message
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
791 extern void *spi_res_alloc(struct spi_device *spi,
800 /*---------------------------------------------------------------------------*/
803  * I/O INTERFACE between SPI controller and protocol drivers
806  * between the controller and memory buffers.
811  * pointer.  (This is unlike most types of I/O API, because SPI hardware
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
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
850  *	within @tx_buf for which the SPI device is requesting that the time
851  *	snapshot for this transfer begins. Upon completing the SPI transfer,
858  *	for this controller), it will set @ptp_sts_word_pre to 0, and
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
863  * @ptp_sts: Pointer to a memory location held by the SPI slave device where a
868  *	The timestamp must represent the time at which the SPI slave device has
871  *	transmit confirmation from the controller for the "post" word.
873  * @error: Error status logged by spi controller driver.
875  * SPI transfers always write the same number of bytes as they read.
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
898  * All SPI transfers start with the relevant chipselect active.  Normally
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
925  * Zero-initialize every field you don't set up explicitly, to
933 	 *   spi_message.is_dma_mapped reports a pre-existing mapping
973  * struct spi_message - one multi-segment SPI transaction
975  * @spi: SPI device to which the transaction is queued
986  * @resources: for resource management when the spi message is processed
990  * in the sense that no other spi_message may use that SPI bus until that
998  * Zero-initialize every field you don't set up explicitly, to
1005 	struct spi_device	*spi;  member
1014 	 * Some controller drivers (message-at-a-time queue processing)
1016 	 * others (with multi-message pipelines) could need a flag to
1029 	 * complete(), that's the spi_controller controller driver.
1034 	/* list of spi_res reources when the spi message is processed */
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
1071  * @xfers: An array of spi transfers
1115 extern int spi_setup(struct spi_device *spi);
1116 extern int spi_async(struct spi_device *spi, struct spi_message *message);
1117 extern int spi_async_locked(struct spi_device *spi,
1119 extern int spi_slave_abort(struct spi_device *spi);
1122 spi_max_message_size(struct spi_device *spi)  in spi_max_message_size()  argument
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()
1132 spi_max_transfer_size(struct spi_device *spi)  in spi_max_transfer_size()  argument
1134 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1136 	size_t msg_max = spi_max_message_size(spi);  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()
1146  * spi_is_bpw_supported - Check if bits per word is supported
1147  * @spi: SPI device
1150  * This function checks to see if the SPI controller supports @bpw.
1155 static inline bool spi_is_bpw_supported(struct spi_device *spi, u32 bpw)  in spi_is_bpw_supported()  argument
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
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
1226 extern int spi_sync(struct spi_device *spi, struct spi_message *message);
1227 extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message);
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.
1245 spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers,  in spi_sync_transfer()  argument
1252 	return spi_sync(spi, &msg);  in spi_sync_transfer()
1256  * spi_write - SPI synchronous write
1257  * @spi: device to which data will be written
1268 spi_write(struct spi_device *spi, const void *buf, size_t len)  in spi_write()  argument
1275 	return spi_sync_transfer(spi, &t, 1);  in spi_write()
1279  * spi_read - SPI synchronous read
1280  * @spi: device from which data will be read
1291 spi_read(struct spi_device *spi, void *buf, size_t len)  in spi_read()  argument
1298 	return spi_sync_transfer(spi, &t, 1);  in spi_read()
1302 extern int spi_write_then_read(struct spi_device *spi,
1307  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1308  * @spi: device with which data will be exchanged
1317 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)  in spi_w8r8()  argument
1322 	status = spi_write_then_read(spi, &cmd, 1, &result, 1);  in spi_w8r8()
1329  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1330  * @spi: device with which data will be exchanged
1334  * The number is returned in wire-order, which is at least sometimes
1335  * big-endian.
1342 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)  in spi_w8r16()  argument
1347 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16()
1354  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1355  * @spi: device with which data will be exchanged
1360  * convert the read 16 bit data word from big-endian to native endianness.
1367 static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd)  in spi_w8r16be()  argument
1373 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16be()
1380 /*---------------------------------------------------------------------------*/
1383  * INTERFACE between board init code and SPI infrastructure.
1385  * No SPI driver ever sees these SPI device table segments, but
1386  * it's how the SPI core (or adapters that get hotplugged) grows
1389  * As a rule, SPI devices can't be probed.  Instead, board init code
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.
1415  * When adding new SPI devices to the device tree, these structures serve
1421  * be stored in tables of board-specific device descriptors, which are
1423  * populate a controller's device tree after the that controller's driver
1425  * spi_new_device() call, which happens after those controller drivers
1463 	 *  - quirks like clock rate mattering when not selected
1471 /* board init code may ignore whether SPI is configured or not */
1492 spi_add_device(struct spi_device *spi);
1497 extern void spi_unregister_device(struct spi_device *spi);
1505 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()