Lines Matching +full:spi +full:- +full:device
1 /* SPDX-License-Identifier: GPL-2.0-or-later
12 #include <linux/device.h>
21 #include <uapi/linux/spi/spi.h>
33 * INTERFACES between SPI master-side drivers and SPI slave protocol handlers,
34 * and SPI infrastructure.
39 * struct spi_statistics - statistics for spi transfers
40 * @syncp: seqcount to protect members in this struct for per-cpu update
41 * on 32-bit systems
43 * @messages: number of spi-messages handled
54 * @bytes: number of bytes transferred to/from device
55 * @bytes_tx: number of bytes sent to device
56 * @bytes_rx: number of bytes received from device
92 u64_stats_update_begin(&__lstats->syncp); \
93 u64_stats_add(&__lstats->field, count); \
94 u64_stats_update_end(&__lstats->syncp); \
103 u64_stats_update_begin(&__lstats->syncp); \
104 u64_stats_inc(&__lstats->field); \
105 u64_stats_update_end(&__lstats->syncp); \
110 * struct spi_delay - SPI delay information
128 * struct spi_device - Controller side proxy for an SPI slave device
129 * @dev: Driver model representation of the device.
130 * @controller: SPI controller used with the device.
133 * (on this board); may be changed by the device's driver.
136 * @mode: The spi mode defines how data is clocked out and in.
137 * This may be changed by the device's driver.
142 * like eight or 12 bits are common. In-memory wordsizes are
144 * This may be changed by the device's driver, or left at the
149 * interrupts from this device.
151 * @controller_data: Board-specific definitions for controller, such as
153 * @modalias: Name of the driver to use with this device, or an alias
157 * the device will bind to the named driver and only the named driver.
171 * A @spi_device is used to interchange data between an SPI slave
175 * device that's meaningful to the device's protocol driver, but not
181 struct device dev;
191 * TPM specification defines flow control over SPI. Client device
195 * only half-duplex, the wait state detection needs to be implemented
197 * control is expected from SPI controller.
203 * which is defined in 'include/uapi/linux/spi/spi.h'.
209 #define SPI_MODE_KERNEL_MASK (~(BIT(29) - 1))
217 struct spi_delay word_delay; /* Inter-word delay */
229 * - memory packing (12 bit samples into low bits, others zeroed)
230 * - priority
231 * - chipselect delays
232 * - ...
240 static inline struct spi_device *to_spi_device(const struct device *dev) in to_spi_device()
245 /* Most drivers won't need to care about device refcounting */
246 static inline struct spi_device *spi_dev_get(struct spi_device *spi) in spi_dev_get() argument
248 return (spi && get_device(&spi->dev)) ? spi : NULL; in spi_dev_get()
251 static inline void spi_dev_put(struct spi_device *spi) in spi_dev_put() argument
253 if (spi) in spi_dev_put()
254 put_device(&spi->dev); in spi_dev_put()
258 static inline void *spi_get_ctldata(const struct spi_device *spi) in spi_get_ctldata() argument
260 return spi->controller_state; in spi_get_ctldata()
263 static inline void spi_set_ctldata(struct spi_device *spi, void *state) in spi_set_ctldata() argument
265 spi->controller_state = state; in spi_set_ctldata()
268 /* Device driver data */
270 static inline void spi_set_drvdata(struct spi_device *spi, void *data) in spi_set_drvdata() argument
272 dev_set_drvdata(&spi->dev, data); in spi_set_drvdata()
275 static inline void *spi_get_drvdata(const struct spi_device *spi) in spi_get_drvdata() argument
277 return dev_get_drvdata(&spi->dev); in spi_get_drvdata()
280 static inline u8 spi_get_chipselect(const struct spi_device *spi, u8 idx) in spi_get_chipselect() argument
282 return spi->chip_select; in spi_get_chipselect()
285 static inline void spi_set_chipselect(struct spi_device *spi, u8 idx, u8 chipselect) in spi_set_chipselect() argument
287 spi->chip_select = chipselect; in spi_set_chipselect()
290 static inline struct gpio_desc *spi_get_csgpiod(const struct spi_device *spi, u8 idx) in spi_get_csgpiod() argument
292 return spi->cs_gpiod; in spi_get_csgpiod()
295 static inline void spi_set_csgpiod(struct spi_device *spi, u8 idx, struct gpio_desc *csgpiod) in spi_set_csgpiod() argument
297 spi->cs_gpiod = csgpiod; in spi_set_csgpiod()
301 * struct spi_driver - Host side "protocol" driver
302 * @id_table: List of SPI devices supported by this driver
303 * @probe: Binds this driver to the SPI device. Drivers can verify
304 * that the device is actually present, and may need to configure
307 * @remove: Unbinds this driver from the SPI device
310 * @driver: SPI device drivers should initialize the name and owner
313 * This represents the kind of device driver that uses SPI messages to
314 * interact with the hardware at the other end of a SPI link. It's called
316 * directly to SPI hardware (which is what the underlying SPI controller
318 * specification for the device(s) supported by the driver.
320 * As a rule, those device protocols represent the lowest level interface
323 * MMC, RTC, filesystem character device nodes, and hardware monitoring.
327 int (*probe)(struct spi_device *spi);
328 void (*remove)(struct spi_device *spi);
329 void (*shutdown)(struct spi_device *spi);
341 * spi_unregister_driver - reverse effect of spi_register_driver
348 driver_unregister(&sdrv->driver); in spi_unregister_driver()
351 extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 chip_select);
358 * module_spi_driver() - Helper macro for registering a SPI driver
361 * Helper macro for SPI drivers which do not do anything special in module
370 * struct spi_controller - interface to SPI master or slave controller
371 * @dev: device interface to this driver
373 * @bus_num: board-specific (and often SOC-specific) identifier for a
374 * given SPI controller.
376 * SPI slaves, and are numbered from zero to num_chipselects.
379 * @dma_alignment: SPI controller constraint on DMA buffers alignment.
384 * supported. If set, the SPI core will reject any transfer with an
390 * @slave: indicates that this is an SPI slave controller
391 * @target: indicates that this is an SPI target controller
392 * @devm_allocated: whether the allocation of this struct is devres-managed
399 * @bus_lock_spinlock: spinlock for SPI bus locking
401 * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use
402 * @setup: updates the device mode and clocking records used by a
403 * device's SPI controller; protocol code may call this. This
406 * the device whose settings are being modified.
407 * @set_cs_timing: optional hook for SPI devices to request SPI master
411 * @cleanup: frees controller-specific state
413 * @dma_map_dev: device which can be used for DMA mapping
414 * @cur_rx_dma_dev: device which is currently used for RX DMA mapping
415 * @cur_tx_dma_dev: device which is currently used for TX DMA mapping
421 * @cur_msg: the currently in-flight message
422 * @cur_msg_completion: a completion for the current in-flight message
430 * @last_cs: the last chip_select that is recorded by set_cs, -1 on non chip
439 * device for the spidev
440 * @max_dma_len: Maximum length of a DMA transfer for the device.
460 * - return 0 if the transfer is finished,
461 * - return 1 if the transfer is still in progress. When
470 * @mem_ops: optimized/dedicated operations for interactions with SPI memory.
475 * @slave_abort: abort the ongoing transfer request on an SPI slave controller
476 * @target_abort: abort the ongoing transfer request on an SPI target controller
479 * are not GPIOs (driven by the SPI controller itself).
480 * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab
481 * GPIO descriptors. This will fill in @cs_gpiods and SPI devices will have
484 * fill in this field with the first unused native CS, to be used by SPI
492 * @dummy_rx: dummy receive buffer for full-duplex devices
493 * @dummy_tx: dummy transmit buffer for full-duplex devices
498 * time snapshot in @spi_transfer->ptp_sts as close as possible to the
499 * moment in time when @spi_transfer->ptp_sts_word_pre and
500 * @spi_transfer->ptp_sts_word_post were transmitted.
501 * If the driver does not set this, the SPI core takes the snapshot as
502 * close to the driver hand-over as possible.
510 * Each SPI controller can communicate with one or more @spi_device
512 * but not chip select signals. Each device may be configured to use a
516 * The driver for an SPI controller manages access to those devices through
518 * an SPI slave device. For each such message it queues, it calls the
522 struct device dev;
528 * board-specific. Usually that simplifies to being SoC-specific.
529 * example: one SoC has three SPI controllers, numbered 0..2,
530 * and one board's schematics might show it using SPI-2. Software
537 * might use board-specific GPIOs.
541 /* Some SPI controllers pose alignment requirements on DMAable
554 #define SPI_BPW_MASK(bits) BIT((bits) - 1)
555 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1)
571 /* Flag indicating if the allocation of this struct is devres-managed */
575 /* Flag indicating this is an SPI slave controller */
577 /* Flag indicating this is an SPI target controller */
583 * the limit may depend on device transfer settings.
585 size_t (*max_transfer_size)(struct spi_device *spi);
586 size_t (*max_message_size)(struct spi_device *spi);
594 /* Lock and mutex for SPI bus locking */
598 /* Flag indicating that the SPI bus is locked for exclusive use */
602 * Setup mode and clock, etc (SPI driver may call many times).
605 * device are active. DO NOT UPDATE SHARED REGISTERS in ways
608 int (*setup)(struct spi_device *spi);
611 * set_cs_timing() method is for SPI controllers that supports
614 * This hook allows SPI client drivers to request SPI controllers
618 int (*set_cs_timing)(struct spi_device *spi);
625 * + For now there's no remove-from-queue operation, or
637 * + The message transfers use clock and SPI mode parameters
638 * previously established by setup() for this device
640 int (*transfer)(struct spi_device *spi,
644 void (*cleanup)(struct spi_device *spi);
651 * while the device is prepared.
654 struct spi_device *spi,
656 struct device *dma_map_dev;
657 struct device *cur_rx_dma_dev;
658 struct device *cur_tx_dma_dev;
664 * Over time we expect SPI drivers to be phased over to this API.
703 void (*set_cs)(struct spi_device *spi, bool enable);
704 int (*transfer_one)(struct spi_controller *ctlr, struct spi_device *spi,
709 /* Optimized handlers for SPI memory-like operations. */
733 * Driver sets this field to indicate it is able to snapshot SPI
748 return dev_get_drvdata(&ctlr->dev); in spi_controller_get_devdata()
754 dev_set_drvdata(&ctlr->dev, data); in spi_controller_set_devdata()
759 if (!ctlr || !get_device(&ctlr->dev)) in spi_controller_get()
767 put_device(&ctlr->dev); in spi_controller_put()
772 return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->slave; in spi_controller_is_slave()
777 return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->target; in spi_controller_is_target()
797 /* The SPI driver core manages memory for the spi_controller classdev */
798 extern struct spi_controller *__spi_alloc_controller(struct device *host,
801 static inline struct spi_controller *spi_alloc_master(struct device *host, in spi_alloc_master()
807 static inline struct spi_controller *spi_alloc_slave(struct device *host, in spi_alloc_slave()
816 static inline struct spi_controller *spi_alloc_host(struct device *dev, in spi_alloc_host()
822 static inline struct spi_controller *spi_alloc_target(struct device *dev, in spi_alloc_target()
831 struct spi_controller *__devm_spi_alloc_controller(struct device *dev,
835 static inline struct spi_controller *devm_spi_alloc_master(struct device *dev, in devm_spi_alloc_master()
841 static inline struct spi_controller *devm_spi_alloc_slave(struct device *dev, in devm_spi_alloc_slave()
850 static inline struct spi_controller *devm_spi_alloc_host(struct device *dev, in devm_spi_alloc_host()
856 static inline struct spi_controller *devm_spi_alloc_target(struct device *dev, in devm_spi_alloc_target()
866 extern int devm_spi_register_controller(struct device *dev,
878 * SPI resource management while processing a SPI message
886 * struct spi_res - SPI resource management structure
889 * @data: extra data allocated for the specific use-case
891 * This is based on ideas from devres, but focused on life-cycle
900 /*---------------------------------------------------------------------------*/
903 * I/O INTERFACE between SPI controller and protocol drivers
911 * pointer. (This is unlike most types of I/O API, because SPI hardware
920 * struct spi_transfer - a read/write buffer pair
921 * @tx_buf: data to be written (DMA-safe memory), or NULL
922 * @rx_buf: data to be read (DMA-safe memory), or NULL
930 * @speed_hz: Select a speed other than the device default for this
932 * @bits_per_word: select a bits_per_word other than the device default
944 * @effective_speed_hz: the effective SCK-speed that was used to
945 * transfer this transfer. Set to 0 if the SPI bus driver does
951 * within @tx_buf for which the SPI device is requesting that the time
952 * snapshot for this transfer begins. Upon completing the SPI transfer,
961 * purposefully (instead of setting to spi_transfer->len - 1) to denote
962 * that a transfer-level snapshot taken from within the driver may still
964 * @ptp_sts: Pointer to a memory location held by the SPI slave device where a
969 * The timestamp must represent the time at which the SPI slave device has
974 * @error: Error status logged by SPI controller driver.
976 * SPI transfers always write the same number of bytes as they read.
989 * In-memory data values are always in native CPU byte order, translated
990 * from the wire byte order (big-endian except with SPI_LSB_FIRST). So
994 * When the word size of the SPI transfer is not a power-of-two multiple
995 * of eight bits, those in-memory words include extra bits. In-memory
996 * words are always seen by protocol drivers as right-justified, so the
999 * All SPI transfers start with the relevant chipselect active. Normally
1010 * stay selected until the next transfer. On multi-device SPI busses
1012 * a performance hint; starting a message to another device deselects
1019 * When SPI can transfer in 1x,2x or 4x. It can get this transfer information
1020 * from device through @tx_nbits and @rx_nbits. In Bi-direction, these
1026 * Zero-initialize every field you don't set up explicitly, to
1035 * spi_message.is_dma_mapped reports a pre-existing mapping.
1055 #define SPI_NBITS_SINGLE 0x01 /* 1-bit transfer */
1056 #define SPI_NBITS_DUAL 0x02 /* 2-bit transfer */
1057 #define SPI_NBITS_QUAD 0x04 /* 4-bit transfer */
1075 * struct spi_message - one multi-segment SPI transaction
1077 * @spi: SPI device to which the transaction is queued
1088 * @resources: for resource management when the SPI message is processed
1095 * in the sense that no other spi_message may use that SPI bus until that
1103 * Zero-initialize every field you don't set up explicitly, to
1110 struct spi_device *spi; member
1123 * Some controller drivers (message-at-a-time queue processing)
1125 * others (with multi-message pipelines) could need a flag to
1144 /* List of spi_res resources when the SPI message is processed */
1153 INIT_LIST_HEAD(&m->transfers); in spi_message_init_no_memset()
1154 INIT_LIST_HEAD(&m->resources); in spi_message_init_no_memset()
1166 list_add_tail(&t->transfer_list, &m->transfers); in spi_message_add_tail()
1172 list_del(&t->transfer_list); in spi_transfer_del()
1178 return spi_delay_exec(&t->delay, t); in spi_transfer_delay_exec()
1182 * spi_message_init_with_transfers - Initialize spi_message and append transfers
1184 * @xfers: An array of SPI transfers
1215 spi_message_add_tail(&m->t[i], m); in spi_message_alloc()
1225 extern int spi_setup(struct spi_device *spi);
1226 extern int spi_async(struct spi_device *spi, struct spi_message *message);
1227 extern int spi_slave_abort(struct spi_device *spi);
1228 extern int spi_target_abort(struct spi_device *spi);
1231 spi_max_message_size(struct spi_device *spi) in spi_max_message_size() argument
1233 struct spi_controller *ctlr = spi->controller; in spi_max_message_size()
1235 if (!ctlr->max_message_size) in spi_max_message_size()
1237 return ctlr->max_message_size(spi); in spi_max_message_size()
1241 spi_max_transfer_size(struct spi_device *spi) in spi_max_transfer_size() argument
1243 struct spi_controller *ctlr = spi->controller; in spi_max_transfer_size()
1245 size_t msg_max = spi_max_message_size(spi); in spi_max_transfer_size()
1247 if (ctlr->max_transfer_size) in spi_max_transfer_size()
1248 tr_max = ctlr->max_transfer_size(spi); in spi_max_transfer_size()
1255 * spi_is_bpw_supported - Check if bits per word is supported
1256 * @spi: SPI device
1259 * This function checks to see if the SPI controller supports @bpw.
1264 static inline bool spi_is_bpw_supported(struct spi_device *spi, u32 bpw) in spi_is_bpw_supported() argument
1266 u32 bpw_mask = spi->master->bits_per_word_mask; in spi_is_bpw_supported()
1275 * spi_controller_xfer_timeout - Compute a suitable timeout value
1276 * @ctlr: SPI device
1288 return max(xfer->len * 8 * 2 / (xfer->speed_hz / 1000), 500U); in spi_controller_xfer_timeout()
1291 /*---------------------------------------------------------------------------*/
1293 /* SPI transfer replacement methods which make use of spi_res */
1300 * struct spi_replaced_transfers - structure describing the spi_transfer
1309 * are to get re-inserted
1311 * @inserted_transfers: array of spi_transfers of array-size @inserted,
1327 /*---------------------------------------------------------------------------*/
1329 /* SPI transfer transformation methods */
1340 /*---------------------------------------------------------------------------*/
1343 * All these synchronous SPI transfer routines are utilities layered
1348 extern int spi_sync(struct spi_device *spi, struct spi_message *message);
1349 extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message);
1354 * spi_sync_transfer - synchronous SPI data transfer
1355 * @spi: device with which data will be exchanged
1360 * Does a synchronous SPI data transfer of the given spi_transfer array.
1367 spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers, in spi_sync_transfer() argument
1374 return spi_sync(spi, &msg); in spi_sync_transfer()
1378 * spi_write - SPI synchronous write
1379 * @spi: device to which data will be written
1390 spi_write(struct spi_device *spi, const void *buf, size_t len) in spi_write() argument
1397 return spi_sync_transfer(spi, &t, 1); in spi_write()
1401 * spi_read - SPI synchronous read
1402 * @spi: device from which data will be read
1413 spi_read(struct spi_device *spi, void *buf, size_t len) in spi_read() argument
1420 return spi_sync_transfer(spi, &t, 1); in spi_read()
1424 extern int spi_write_then_read(struct spi_device *spi,
1429 * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read
1430 * @spi: device with which data will be exchanged
1437 * device, or else a negative error code.
1439 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd) in spi_w8r8() argument
1444 status = spi_write_then_read(spi, &cmd, 1, &result, 1); in spi_w8r8()
1451 * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read
1452 * @spi: device with which data will be exchanged
1456 * The number is returned in wire-order, which is at least sometimes
1457 * big-endian.
1462 * device, or else a negative error code.
1464 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd) in spi_w8r16() argument
1469 status = spi_write_then_read(spi, &cmd, 1, &result, 2); in spi_w8r16()
1476 * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read
1477 * @spi: device with which data will be exchanged
1482 * convert the read 16 bit data word from big-endian to native endianness.
1486 * Return: the (unsigned) sixteen bit number returned by the device in CPU
1489 static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd) in spi_w8r16be() argument
1495 status = spi_write_then_read(spi, &cmd, 1, &result, 2); in spi_w8r16be()
1502 /*---------------------------------------------------------------------------*/
1505 * INTERFACE between board init code and SPI infrastructure.
1507 * No SPI driver ever sees these SPI device table segments, but
1508 * it's how the SPI core (or adapters that get hotplugged) grows
1511 * As a rule, SPI devices can't be probed. Instead, board init code
1513 * information to bind and set up the device's driver. There's basic
1514 * support for non-static configurations too; enough to handle adding
1515 * parport adapters, or microcontrollers acting as USB-to-SPI bridges.
1519 * struct spi_board_info - board-specific template for a SPI device
1522 * data stored there is driver-specific.
1523 * @swnode: Software node for the device.
1528 * from the chip datasheet and board-specific signal quality issues.
1537 * When adding new SPI devices to the device tree, these structures serve
1538 * as a partial device template. They hold information which can't always
1543 * be stored in tables of board-specific device descriptors, which are
1545 * populate a controller's device tree after the that controller's driver
1552 * The device name and module name are coupled, like platform_bus;
1589 * - quirks like clock rate mattering when not selected
1597 /* Board init code may ignore whether SPI is configured or not */
1605 * use spi_new_device() to describe each device. You can also call
1606 * spi_unregister_device() to start making that device vanish, but
1619 spi_add_device(struct spi_device *spi);
1624 extern void spi_unregister_device(struct spi_device *spi);
1635 return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers); in spi_transfer_is_last()