Lines Matching +full:spi +full:- +full:controller
1 /* SPDX-License-Identifier: GPL-2.0-or-later
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
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
113 * @controller: SPI controller used with the device.
114 * @master: Copy of controller, for backwards compatibility.
118 * @chip_select: Chipselect, distinguishing chips handled by @controller.
119 * @mode: The spi mode defines how data is clocked out and in.
125 * like eight or 12 bits are common. In-memory wordsizes are
133 * @controller_state: Controller's runtime state
134 * @controller_data: Board-specific definitions for controller, such as
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
156 * to its controller. One example might be an identifier for a chip
162 struct spi_controller *controller; member
176 #define SPI_LSB_FIRST 0x08 /* per-word bits-on-wire */
196 struct spi_delay word_delay; /* inter-word delay */
206 * the controller talks to each chip, like:
207 * - memory packing (12 bit samples into low bits, others zeroed)
208 * - priority
209 * - chipselect delays
210 * - ...
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()
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
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
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
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.
337 * @mode_bits: flags understood by this controller driver
338 * @buswidth_override_bits: flags to override for this controller driver
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
357 * device's SPI controller; protocol code may call this. This
361 * @set_cs_timing: optional hook for SPI devices to request SPI master
362 * controller for configuring specific CS setup time, hold time and inactive
364 * @transfer: adds a message to the controller's transfer queue.
365 * @cleanup: frees controller-specific state
366 * @can_dma: determine whether this controller supports DMA
367 * @queued: whether this controller is providing an internal message queue
373 * @cur_msg: the currently in-flight message
375 * in-flight message
401 * @prepare_message: set up the controller to transfer a single message,
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.
418 * controller has native support for memory like operations.
420 * @slave_abort: abort the ongoing transfer request on an SPI slave controller
421 * @cs_setup: delay to be introduced by the controller after CS is asserted
422 * @cs_hold: delay to be introduced by the controller before CS is deasserted
423 * @cs_inactive: delay to be introduced by the controller after CS is
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
439 * controller drivers that need to drive a native CS when using GPIO CS.
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
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
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
481 * would normally use bus_num=2 for that controller.
486 * might use board-specific GPIOs.
490 /* some SPI controllers pose alignment requirements on DMAable
495 /* spi_device.mode flags understood by this controller driver */
498 /* spi_device.mode flags override flags for this controller */
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 */
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).
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
567 * + The controller's main job is to process its message queue,
575 * + The message transfers use clock and SPI mode parameters
578 int (*transfer)(struct spi_device *spi,
582 void (*cleanup)(struct spi_device *spi);
592 struct spi_device *spi,
597 * controller transfer queueing mechanism. If these are used, the
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 */
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
817 * between the controller and memory buffers.
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
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,
871 * for this controller), it will set @ptp_sts_word_pre to 0, and
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
884 * transmit confirmation from the controller for the "post" word.
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
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
1044 * complete(), that's the spi_controller controller driver.
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
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.
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.
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
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.
1436 * from the chip datasheet and board-specific signal quality issues.
1445 * When adding new SPI devices to the device tree, these structures serve
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
1455 * spi_new_device() call, which happens after those controller drivers
1496 * - quirks like clock rate mattering when not selected
1504 /* board init code may ignore whether SPI is configured or not */
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()