1 /* SPDX-License-Identifier: GPL-2.0-or-later
9 #include <linux/device.h>
26  * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
27  * and SPI infrastructure.
32  * struct spi_statistics - statistics for spi transfers
35  * @messages:      number of spi-messages handled
46  * @bytes:         number of bytes transferred to/from device
47  * @bytes_tx:      number of bytes sent to device
48  * @bytes_rx:      number of bytes received from device
86 		spin_lock_irqsave(&(stats)->lock, flags);	\
87 		(stats)->field += count;			\
88 		spin_unlock_irqrestore(&(stats)->lock, flags);	\
95  * struct spi_delay - SPI delay information
111  * struct spi_device - Controller side proxy for an SPI slave device
112  * @dev: Driver model representation of the device.
113  * @controller: SPI controller used with the device.
116  *	(on this board); may be changed by the device's driver.
119  * @mode: The spi mode defines how data is clocked out and in.
120  *	This may be changed by the device's driver.
125  *	like eight or 12 bits are common.  In-memory wordsizes are
127  *	This may be changed by the device's driver, or left at the
132  *	interrupts from this device.
134  * @controller_data: Board-specific definitions for controller, such as
136  * @modalias: Name of the driver to use with this device, or an alias
140  *	the device will bind to the named driver and only the named driver.
141  * @cs_gpio: LEGACY: gpio number of the chipselect line (optional, -ENOENT when
151  * A @spi_device is used to interchange data between an SPI slave
155  * device that's meaningful to the device's protocol driver, but not
161 	struct device		dev;
176 #define	SPI_LSB_FIRST	0x08			/* per-word bits-on-wire */
196 	struct spi_delay	word_delay; /* inter-word delay */
207 	 *  - memory packing (12 bit samples into low bits, others zeroed)
208 	 *  - priority
209 	 *  - chipselect delays
210 	 *  - ...
214 static inline struct spi_device *to_spi_device(struct device *dev)  in to_spi_device()
219 /* most drivers won't need to care about device refcounting */
220 static inline struct spi_device *spi_dev_get(struct spi_device *spi)  in spi_dev_get()  argument
222 	return (spi && get_device(&spi->dev)) ? spi : NULL;  in spi_dev_get()
225 static inline void spi_dev_put(struct spi_device *spi)  in spi_dev_put()  argument
227 	if (spi)  in spi_dev_put()
228 		put_device(&spi->dev);  in spi_dev_put()
232 static inline void *spi_get_ctldata(struct spi_device *spi)  in spi_get_ctldata()  argument
234 	return spi->controller_state;  in spi_get_ctldata()
237 static inline void spi_set_ctldata(struct spi_device *spi, void *state)  in spi_set_ctldata()  argument
239 	spi->controller_state = state;  in spi_set_ctldata()
242 /* device driver data */
244 static inline void spi_set_drvdata(struct spi_device *spi, void *data)  in spi_set_drvdata()  argument
246 	dev_set_drvdata(&spi->dev, data);  in spi_set_drvdata()
249 static inline void *spi_get_drvdata(struct spi_device *spi)  in spi_get_drvdata()  argument
251 	return dev_get_drvdata(&spi->dev);  in spi_get_drvdata()
258  * struct spi_driver - Host side "protocol" driver
259  * @id_table: List of SPI devices supported by this driver
260  * @probe: Binds this driver to the spi device.  Drivers can verify
261  *	that the device is actually present, and may need to configure
264  * @remove: Unbinds this driver from the spi device
267  * @driver: SPI device drivers should initialize the name and owner
270  * This represents the kind of device driver that uses SPI messages to
271  * interact with the hardware at the other end of a SPI link.  It's called
273  * directly to SPI hardware (which is what the underlying SPI controller
275  * specification for the device(s) supported by the driver.
277  * As a rule, those device protocols represent the lowest level interface
280  * MMC, RTC, filesystem character device nodes, and hardware monitoring.
284 	int			(*probe)(struct spi_device *spi);
285 	int			(*remove)(struct spi_device *spi);
286 	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()
315  * module_spi_driver() - Helper macro for registering a SPI driver
318  * Helper macro for SPI drivers which do not do anything special in module
327  * struct spi_controller - interface to SPI master or slave controller
328  * @dev: device interface to this driver
330  * @bus_num: board-specific (and often SOC-specific) identifier for a
331  *	given SPI controller.
333  *	SPI slaves, and are numbered from zero to num_chipselects.
336  * @dma_alignment: SPI controller constraint on DMA buffers alignment.
341  *	supported. If set, the SPI core will reject any transfer with an
347  * @slave: indicates that this is an SPI slave controller
353  * @bus_lock_spinlock: spinlock for SPI bus locking
355  * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
356  * @setup: updates the device mode and clocking records used by a
357  *	device's SPI controller; protocol code may call this.  This
360  *	the device whose settings are being modified.
361  * @set_cs_timing: optional hook for SPI devices to request SPI master
365  * @cleanup: frees controller-specific state
372  * @idling: the device is entering idle state
373  * @cur_msg: the currently in-flight message
375  *                    in-flight message
385  *                   device for the spidev
386  * @max_dma_len: Maximum length of a DMA transfer for the device.
406  *                  - return 0 if the transfer is finished,
407  *                  - return 1 if the transfer is still in progress. When
416  * @mem_ops: optimized/dedicated operations for interactions with SPI memory.
420  * @slave_abort: abort the ongoing transfer request on an SPI slave controller
427  *	CS number. Any individual value may be -ENOENT for CS lines that
428  *	are not GPIOs (driven by the SPI controller itself). Use the cs_gpiods
432  *	are not GPIOs (driven by the SPI controller itself).
433  * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab
436  *	and SPI devices will have the cs_gpiod assigned rather than cs_gpio.
438  *	fill in this field with the first unused native CS, to be used by SPI
446  * @dummy_rx: dummy receive buffer for full-duplex devices
447  * @dummy_tx: dummy transmit buffer for full-duplex devices
452  *	time snapshot in @spi_transfer->ptp_sts as close as possible to the
453  *	moment in time when @spi_transfer->ptp_sts_word_pre and
454  *	@spi_transfer->ptp_sts_word_post were transmitted.
455  *	If the driver does not set this, the SPI core takes the snapshot as
456  *	close to the driver hand-over as possible.
461  * Each SPI controller can communicate with one or more @spi_device
463  * but not chip select signals.  Each device may be configured to use a
467  * The driver for an SPI controller manages access to those devices through
469  * an SPI slave device.  For each such message it queues, it calls the
473 	struct device	dev;
478 	 * board-specific.  usually that simplifies to being SOC-specific.
479 	 * example:  one SOC has three SPI controllers, numbered 0..2,
480 	 * and one board's schematics might show it using SPI-2.  software
486 	 * might use board-specific GPIOs.
490 	/* some SPI controllers pose alignment requirements on DMAable
503 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
504 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
520 	/* flag indicating this is an SPI slave controller */
525 	 * the limit may depend on device transfer settings
527 	size_t (*max_transfer_size)(struct spi_device *spi);
528 	size_t (*max_message_size)(struct spi_device *spi);
533 	/* lock and mutex for SPI bus locking */
537 	/* flag indicating that the SPI bus is locked for exclusive use */
540 	/* Setup mode and clock, etc (spi driver may call many times).
543 	 * device are active.  DO NOT UPDATE SHARED REGISTERS in ways
546 	int			(*setup)(struct spi_device *spi);
549 	 * set_cs_timing() method is for SPI controllers that supports
552 	 * This hook allows SPI client drivers to request SPI controllers
556 	int (*set_cs_timing)(struct spi_device *spi, struct spi_delay *setup,
563 	 * + For now there's no remove-from-queue operation, or
575 	 * + The message transfers use clock and SPI mode parameters
576 	 *   previously established by setup() for this device
578 	int			(*transfer)(struct spi_device *spi,
582 	void			(*cleanup)(struct spi_device *spi);
589 	 * while the device is prepared.
592 					   struct spi_device *spi,
599 	 * Over time we expect SPI drivers to be phased over to this API.
634 	void (*set_cs)(struct spi_device *spi, bool enable);
635 	int (*transfer_one)(struct spi_controller *ctlr, struct spi_device *spi,
640 	/* Optimized handlers for SPI memory-like operations. */
652 // KABI fix up for 35f3f8504c3b ("spi: Switch to signed types for *_native_cs
653 // SPI controller fields") that showed up in 5.10.63
676 	 * Driver sets this field to indicate it is able to snapshot SPI
690 	return dev_get_drvdata(&ctlr->dev);  in spi_controller_get_devdata()
696 	dev_set_drvdata(&ctlr->dev, data);  in spi_controller_set_devdata()
701 	if (!ctlr || !get_device(&ctlr->dev))  in spi_controller_get()
709 		put_device(&ctlr->dev);  in spi_controller_put()
714 	return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->slave;  in spi_controller_is_slave()
734 /* the spi driver core manages memory for the spi_controller classdev */
735 extern struct spi_controller *__spi_alloc_controller(struct device *host,
738 static inline struct spi_controller *spi_alloc_master(struct device *host,  in spi_alloc_master()
744 static inline struct spi_controller *spi_alloc_slave(struct device *host,  in spi_alloc_slave()
753 struct spi_controller *__devm_spi_alloc_controller(struct device *dev,
757 static inline struct spi_controller *devm_spi_alloc_master(struct device *dev,  in devm_spi_alloc_master()
763 static inline struct spi_controller *devm_spi_alloc_slave(struct device *dev,  in devm_spi_alloc_slave()
773 extern int devm_spi_register_controller(struct device *dev,
780  * SPI resource management while processing a SPI message
788  * struct spi_res - spi resource management structure
791  * @data:    extra data allocated for the specific use-case
793  * this is based on ideas from devres, but focused on life-cycle
802 extern void *spi_res_alloc(struct spi_device *spi,
811 /*---------------------------------------------------------------------------*/
814  * I/O INTERFACE between SPI controller and protocol drivers
822  * pointer.  (This is unlike most types of I/O API, because SPI hardware
831  * struct spi_transfer - a read/write buffer pair
832  * @tx_buf: data to be written (dma-safe memory), or NULL
833  * @rx_buf: data to be read (dma-safe memory), or NULL
841  * @speed_hz: Select a speed other than the device default for this
843  * @bits_per_word: select a bits_per_word other than the device default
856  * @effective_speed_hz: the effective SCK-speed that was used to
857  *      transfer this transfer. Set to 0 if the spi bus driver does
863  *	within @tx_buf for which the SPI device is requesting that the time
864  *	snapshot for this transfer begins. Upon completing the SPI transfer,
873  *	purposefully (instead of setting to spi_transfer->len - 1) to denote
874  *	that a transfer-level snapshot taken from within the driver may still
876  * @ptp_sts: Pointer to a memory location held by the SPI slave device where a
881  *	The timestamp must represent the time at which the SPI slave device has
886  * @error: Error status logged by spi controller driver.
888  * SPI transfers always write the same number of bytes as they read.
901  * In-memory data values are always in native CPU byte order, translated
902  * from the wire byte order (big-endian except with SPI_LSB_FIRST).  So
906  * When the word size of the SPI transfer is not a power-of-two multiple
907  * of eight bits, those in-memory words include extra bits.  In-memory
908  * words are always seen by protocol drivers as right-justified, so the
911  * All SPI transfers start with the relevant chipselect active.  Normally
922  * stay selected until the next transfer.  On multi-device SPI busses
924  * a performance hint; starting a message to another device deselects
931  * When SPI can transfer in 1x,2x or 4x. It can get this transfer information
932  * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
938  * Zero-initialize every field you don't set up explicitly, to
946 	 *   spi_message.is_dma_mapped reports a pre-existing mapping
988  * struct spi_message - one multi-segment SPI transaction
990  * @spi: SPI device to which the transaction is queued
1001  * @resources: for resource management when the spi message is processed
1005  * in the sense that no other spi_message may use that SPI bus until that
1013  * Zero-initialize every field you don't set up explicitly, to
1020 	struct spi_device	*spi;  member
1029 	 * Some controller drivers (message-at-a-time queue processing)
1031 	 * others (with multi-message pipelines) could need a flag to
1049 	/* list of spi_res reources when the spi message is processed */
1057 	INIT_LIST_HEAD(&m->transfers);  in spi_message_init_no_memset()
1058 	INIT_LIST_HEAD(&m->resources);  in spi_message_init_no_memset()
1070 	list_add_tail(&t->transfer_list, &m->transfers);  in spi_message_add_tail()
1076 	list_del(&t->transfer_list);  in spi_transfer_del()
1084 	if (t->delay_usecs) {  in spi_transfer_delay_exec()
1085 		d.value = t->delay_usecs;  in spi_transfer_delay_exec()
1090 	return spi_delay_exec(&t->delay, t);  in spi_transfer_delay_exec()
1094  * spi_message_init_with_transfers - Initialize spi_message and append transfers
1096  * @xfers: An array of spi transfers
1140 extern int spi_set_cs_timing(struct spi_device *spi,
1145 extern int spi_setup(struct spi_device *spi);
1146 extern int spi_async(struct spi_device *spi, struct spi_message *message);
1147 extern int spi_async_locked(struct spi_device *spi,
1149 extern int spi_slave_abort(struct spi_device *spi);
1152 spi_max_message_size(struct spi_device *spi)  in spi_max_message_size()  argument
1154 	struct spi_controller *ctlr = spi->controller;  in spi_max_message_size()
1156 	if (!ctlr->max_message_size)  in spi_max_message_size()
1158 	return ctlr->max_message_size(spi);  in spi_max_message_size()
1162 spi_max_transfer_size(struct spi_device *spi)  in spi_max_transfer_size()  argument
1164 	struct spi_controller *ctlr = spi->controller;  in spi_max_transfer_size()
1166 	size_t msg_max = spi_max_message_size(spi);  in spi_max_transfer_size()
1168 	if (ctlr->max_transfer_size)  in spi_max_transfer_size()
1169 		tr_max = ctlr->max_transfer_size(spi);  in spi_max_transfer_size()
1176  * spi_is_bpw_supported - Check if bits per word is supported
1177  * @spi: SPI device
1180  * This function checks to see if the SPI controller supports @bpw.
1185 static inline bool spi_is_bpw_supported(struct spi_device *spi, u32 bpw)  in spi_is_bpw_supported()  argument
1187 	u32 bpw_mask = spi->master->bits_per_word_mask;  in spi_is_bpw_supported()
1195 /*---------------------------------------------------------------------------*/
1197 /* SPI transfer replacement methods which make use of spi_res */
1204  * struct spi_replaced_transfers - structure describing the spi_transfer
1213  *                      are to get re-inserted
1215  * @inserted_transfers: array of spi_transfers of array-size @inserted,
1240 /*---------------------------------------------------------------------------*/
1242 /* SPI transfer transformation methods */
1249 /*---------------------------------------------------------------------------*/
1251 /* All these synchronous SPI transfer routines are utilities layered
1256 extern int spi_sync(struct spi_device *spi, struct spi_message *message);
1257 extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message);
1262  * spi_sync_transfer - synchronous SPI data transfer
1263  * @spi: device with which data will be exchanged
1268  * Does a synchronous SPI data transfer of the given spi_transfer array.
1275 spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers,  in spi_sync_transfer()  argument
1282 	return spi_sync(spi, &msg);  in spi_sync_transfer()
1286  * spi_write - SPI synchronous write
1287  * @spi: device to which data will be written
1298 spi_write(struct spi_device *spi, const void *buf, size_t len)  in spi_write()  argument
1305 	return spi_sync_transfer(spi, &t, 1);  in spi_write()
1309  * spi_read - SPI synchronous read
1310  * @spi: device from which data will be read
1321 spi_read(struct spi_device *spi, void *buf, size_t len)  in spi_read()  argument
1328 	return spi_sync_transfer(spi, &t, 1);  in spi_read()
1332 extern int spi_write_then_read(struct spi_device *spi,
1337  * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1338  * @spi: device with which data will be exchanged
1345  * device, or else a negative error code.
1347 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd)  in spi_w8r8()  argument
1352 	status = spi_write_then_read(spi, &cmd, 1, &result, 1);  in spi_w8r8()
1359  * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1360  * @spi: device with which data will be exchanged
1364  * The number is returned in wire-order, which is at least sometimes
1365  * big-endian.
1370  * device, or else a negative error code.
1372 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd)  in spi_w8r16()  argument
1377 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16()
1384  * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1385  * @spi: device with which data will be exchanged
1390  * convert the read 16 bit data word from big-endian to native endianness.
1394  * Return: the (unsigned) sixteen bit number returned by the device in cpu
1397 static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd)  in spi_w8r16be()  argument
1403 	status = spi_write_then_read(spi, &cmd, 1, &result, 2);  in spi_w8r16be()
1410 /*---------------------------------------------------------------------------*/
1413  * INTERFACE between board init code and SPI infrastructure.
1415  * No SPI driver ever sees these SPI device table segments, but
1416  * it's how the SPI core (or adapters that get hotplugged) grows
1419  * As a rule, SPI devices can't be probed.  Instead, board init code
1421  * information to bind and set up the device's driver.  There's basic
1423  * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1427  * struct spi_board_info - board-specific template for a SPI device
1430  *	data stored there is driver-specific.
1431  * @properties: Additional device properties for the device.
1436  *	from the chip datasheet and board-specific signal quality issues.
1445  * When adding new SPI devices to the device tree, these structures serve
1446  * as a partial device template.  They hold information which can't always
1451  * be stored in tables of board-specific device descriptors, which are
1453  * populate a controller's device tree after the that controller's driver
1459 	/* the device name and module name are coupled, like platform_bus;
1464 	 * device properties are copied and attached to spi_device,
1496 	 *  - quirks like clock rate mattering when not selected
1504 /* board init code may ignore whether SPI is configured or not */
1511  * use spi_new_device() to describe each device.  You can also call
1512  * spi_unregister_device() to start making that device vanish, but
1525 spi_add_device(struct spi_device *spi);
1530 extern void spi_unregister_device(struct spi_device *spi);
1538 	return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers);  in spi_transfer_is_last()
1544 /* must call put_device() when done with returned spi_device device */