1 /* SPDX-License-Identifier: GPL-2.0-or-later 2 * 3 * Copyright (C) 2005 David Brownell 4 */ 5 6 #ifndef __LINUX_SPI_H 7 #define __LINUX_SPI_H 8 9 #include <linux/acpi.h> 10 #include <linux/bits.h> 11 #include <linux/completion.h> 12 #include <linux/device.h> 13 #include <linux/gpio/consumer.h> 14 #include <linux/kthread.h> 15 #include <linux/mod_devicetable.h> 16 #include <linux/overflow.h> 17 #include <linux/scatterlist.h> 18 #include <linux/slab.h> 19 #include <linux/u64_stats_sync.h> 20 21 #include <uapi/linux/spi/spi.h> 22 23 /* Max no. of CS supported per spi device */ 24 #define SPI_DEVICE_CS_CNT_MAX 4 25 26 /* Max no. of data lanes supported per spi device */ 27 #define SPI_DEVICE_DATA_LANE_CNT_MAX 8 28 29 struct dma_chan; 30 struct software_node; 31 struct ptp_system_timestamp; 32 struct spi_controller; 33 struct spi_transfer; 34 struct spi_controller_mem_ops; 35 struct spi_controller_mem_caps; 36 struct spi_message; 37 struct spi_offload; 38 struct spi_offload_config; 39 40 /* 41 * INTERFACES between SPI controller-side drivers and SPI target protocol handlers, 42 * and SPI infrastructure. 43 */ 44 extern const struct bus_type spi_bus_type; 45 46 /** 47 * struct spi_statistics - statistics for spi transfers 48 * @syncp: seqcount to protect members in this struct for per-cpu update 49 * on 32-bit systems 50 * 51 * @messages: number of spi-messages handled 52 * @transfers: number of spi_transfers handled 53 * @errors: number of errors during spi_transfer 54 * @timedout: number of timeouts during spi_transfer 55 * 56 * @spi_sync: number of times spi_sync is used 57 * @spi_sync_immediate: 58 * number of times spi_sync is executed immediately 59 * in calling context without queuing and scheduling 60 * @spi_async: number of times spi_async is used 61 * 62 * @bytes: number of bytes transferred to/from device 63 * @bytes_tx: number of bytes sent to device 64 * @bytes_rx: number of bytes received from device 65 * 66 * @transfer_bytes_histo: 67 * transfer bytes histogram 68 * 69 * @transfers_split_maxsize: 70 * number of transfers that have been split because of 71 * maxsize limit 72 */ 73 struct spi_statistics { 74 struct u64_stats_sync syncp; 75 76 u64_stats_t messages; 77 u64_stats_t transfers; 78 u64_stats_t errors; 79 u64_stats_t timedout; 80 81 u64_stats_t spi_sync; 82 u64_stats_t spi_sync_immediate; 83 u64_stats_t spi_async; 84 85 u64_stats_t bytes; 86 u64_stats_t bytes_rx; 87 u64_stats_t bytes_tx; 88 89 #define SPI_STATISTICS_HISTO_SIZE 17 90 u64_stats_t transfer_bytes_histo[SPI_STATISTICS_HISTO_SIZE]; 91 92 u64_stats_t transfers_split_maxsize; 93 }; 94 95 #define SPI_STATISTICS_ADD_TO_FIELD(pcpu_stats, field, count) \ 96 do { \ 97 struct spi_statistics *__lstats; \ 98 get_cpu(); \ 99 __lstats = this_cpu_ptr(pcpu_stats); \ 100 u64_stats_update_begin(&__lstats->syncp); \ 101 u64_stats_add(&__lstats->field, count); \ 102 u64_stats_update_end(&__lstats->syncp); \ 103 put_cpu(); \ 104 } while (0) 105 106 #define SPI_STATISTICS_INCREMENT_FIELD(pcpu_stats, field) \ 107 do { \ 108 struct spi_statistics *__lstats; \ 109 get_cpu(); \ 110 __lstats = this_cpu_ptr(pcpu_stats); \ 111 u64_stats_update_begin(&__lstats->syncp); \ 112 u64_stats_inc(&__lstats->field); \ 113 u64_stats_update_end(&__lstats->syncp); \ 114 put_cpu(); \ 115 } while (0) 116 117 /** 118 * struct spi_delay - SPI delay information 119 * @value: Value for the delay 120 * @unit: Unit for the delay 121 */ 122 struct spi_delay { 123 #define SPI_DELAY_UNIT_USECS 0 124 #define SPI_DELAY_UNIT_NSECS 1 125 #define SPI_DELAY_UNIT_SCK 2 126 u16 value; 127 u8 unit; 128 }; 129 130 extern int spi_delay_to_ns(struct spi_delay *_delay, struct spi_transfer *xfer); 131 extern int spi_delay_exec(struct spi_delay *_delay, struct spi_transfer *xfer); 132 extern void spi_transfer_cs_change_delay_exec(struct spi_message *msg, 133 struct spi_transfer *xfer); 134 135 /** 136 * struct spi_device - Controller side proxy for an SPI target device 137 * @dev: Driver model representation of the device. 138 * @controller: SPI controller used with the device. 139 * @max_speed_hz: Maximum clock rate to be used with this chip 140 * (on this board); may be changed by the device's driver. 141 * The spi_transfer.speed_hz can override this for each transfer. 142 * @bits_per_word: Data transfers involve one or more words; word sizes 143 * like eight or 12 bits are common. In-memory wordsizes are 144 * powers of two bytes (e.g. 20 bit samples use 32 bits). 145 * This may be changed by the device's driver, or left at the 146 * default (0) indicating protocol words are eight bit bytes. 147 * The spi_transfer.bits_per_word can override this for each transfer. 148 * @rt: Make the pump thread real time priority. 149 * @mode: The spi mode defines how data is clocked out and in. 150 * This may be changed by the device's driver. 151 * The "active low" default for chipselect mode can be overridden 152 * (by specifying SPI_CS_HIGH) as can the "MSB first" default for 153 * each word in a transfer (by specifying SPI_LSB_FIRST). 154 * @irq: Negative, or the number passed to request_irq() to receive 155 * interrupts from this device. 156 * @controller_state: Controller's runtime state 157 * @controller_data: Board-specific definitions for controller, such as 158 * FIFO initialization parameters; from board_info.controller_data 159 * @modalias: Name of the driver to use with this device, or an alias 160 * for that name. This appears in the sysfs "modalias" attribute 161 * for driver coldplugging, and in uevents used for hotplugging 162 * @pcpu_statistics: statistics for the spi_device 163 * @word_delay: delay to be inserted between consecutive 164 * words of a transfer 165 * @cs_setup: delay to be introduced by the controller after CS is asserted 166 * @cs_hold: delay to be introduced by the controller before CS is deasserted 167 * @cs_inactive: delay to be introduced by the controller after CS is 168 * deasserted. If @cs_change_delay is used from @spi_transfer, then the 169 * two delays will be added up. 170 * @chip_select: Array of physical chipselect, spi->chipselect[i] gives 171 * the corresponding physical CS for logical CS i. 172 * @num_chipselect: Number of physical chipselects used. 173 * @cs_index_mask: Bit mask of the active chipselect(s) in the chipselect array 174 * @cs_gpiod: Array of GPIO descriptors of the corresponding chipselect lines 175 * (optional, NULL when not using a GPIO line) 176 * @tx_lane_map: Map of peripheral lanes (index) to controller lanes (value). 177 * @num_tx_lanes: Number of transmit lanes wired up. 178 * @rx_lane_map: Map of peripheral lanes (index) to controller lanes (value). 179 * @num_rx_lanes: Number of receive lanes wired up. 180 * 181 * A @spi_device is used to interchange data between an SPI target device 182 * (usually a discrete chip) and CPU memory. 183 * 184 * In @dev, the platform_data is used to hold information about this 185 * device that's meaningful to the device's protocol driver, but not 186 * to its controller. One example might be an identifier for a chip 187 * variant with slightly different functionality; another might be 188 * information about how this particular board wires the chip's pins. 189 */ 190 struct spi_device { 191 struct device dev; 192 struct spi_controller *controller; 193 u32 max_speed_hz; 194 u8 bits_per_word; 195 bool rt; 196 #define SPI_NO_TX BIT(31) /* No transmit wire */ 197 #define SPI_NO_RX BIT(30) /* No receive wire */ 198 /* 199 * TPM specification defines flow control over SPI. Client device 200 * can insert a wait state on MISO when address is transmitted by 201 * controller on MOSI. Detecting the wait state in software is only 202 * possible for full duplex controllers. For controllers that support 203 * only half-duplex, the wait state detection needs to be implemented 204 * in hardware. TPM devices would set this flag when hardware flow 205 * control is expected from SPI controller. 206 */ 207 #define SPI_TPM_HW_FLOW BIT(29) /* TPM HW flow control */ 208 /* 209 * All bits defined above should be covered by SPI_MODE_KERNEL_MASK. 210 * The SPI_MODE_KERNEL_MASK has the SPI_MODE_USER_MASK counterpart, 211 * which is defined in 'include/uapi/linux/spi/spi.h'. 212 * The bits defined here are from bit 31 downwards, while in 213 * SPI_MODE_USER_MASK are from 0 upwards. 214 * These bits must not overlap. A static assert check should make sure of that. 215 * If adding extra bits, make sure to decrease the bit index below as well. 216 */ 217 #define SPI_MODE_KERNEL_MASK (~(BIT(29) - 1)) 218 u32 mode; 219 int irq; 220 void *controller_state; 221 void *controller_data; 222 char modalias[SPI_NAME_SIZE]; 223 224 /* The statistics */ 225 struct spi_statistics __percpu *pcpu_statistics; 226 227 struct spi_delay word_delay; /* Inter-word delay */ 228 229 /* CS delays */ 230 struct spi_delay cs_setup; 231 struct spi_delay cs_hold; 232 struct spi_delay cs_inactive; 233 234 u8 chip_select[SPI_DEVICE_CS_CNT_MAX]; 235 u8 num_chipselect; 236 237 /* 238 * Bit mask of the chipselect(s) that the driver need to use from 239 * the chipselect array. When the controller is capable to handle 240 * multiple chip selects & memories are connected in parallel 241 * then more than one bit need to be set in cs_index_mask. 242 */ 243 u32 cs_index_mask : SPI_DEVICE_CS_CNT_MAX; 244 245 struct gpio_desc *cs_gpiod[SPI_DEVICE_CS_CNT_MAX]; /* Chip select gpio desc */ 246 247 /* Multi-lane SPI controller support. */ 248 u8 tx_lane_map[SPI_DEVICE_DATA_LANE_CNT_MAX]; 249 u8 num_tx_lanes; 250 u8 rx_lane_map[SPI_DEVICE_DATA_LANE_CNT_MAX]; 251 u8 num_rx_lanes; 252 253 /* 254 * Likely need more hooks for more protocol options affecting how 255 * the controller talks to each chip, like: 256 * - memory packing (12 bit samples into low bits, others zeroed) 257 * - priority 258 * - chipselect delays 259 * - ... 260 */ 261 }; 262 263 /* Make sure that SPI_MODE_KERNEL_MASK & SPI_MODE_USER_MASK don't overlap */ 264 static_assert((SPI_MODE_KERNEL_MASK & SPI_MODE_USER_MASK) == 0, 265 "SPI_MODE_USER_MASK & SPI_MODE_KERNEL_MASK must not overlap"); 266 267 #define to_spi_device(__dev) container_of_const(__dev, struct spi_device, dev) 268 269 /* Most drivers won't need to care about device refcounting */ 270 static inline struct spi_device *spi_dev_get(struct spi_device *spi) 271 { 272 return (spi && get_device(&spi->dev)) ? spi : NULL; 273 } 274 275 static inline void spi_dev_put(struct spi_device *spi) 276 { 277 if (spi) 278 put_device(&spi->dev); 279 } 280 281 /* ctldata is for the bus_controller driver's runtime state */ 282 static inline void *spi_get_ctldata(const struct spi_device *spi) 283 { 284 return spi->controller_state; 285 } 286 287 static inline void spi_set_ctldata(struct spi_device *spi, void *state) 288 { 289 spi->controller_state = state; 290 } 291 292 /* Device driver data */ 293 294 static inline void spi_set_drvdata(struct spi_device *spi, void *data) 295 { 296 dev_set_drvdata(&spi->dev, data); 297 } 298 299 static inline void *spi_get_drvdata(const struct spi_device *spi) 300 { 301 return dev_get_drvdata(&spi->dev); 302 } 303 304 static inline u8 spi_get_chipselect(const struct spi_device *spi, u8 idx) 305 { 306 return spi->chip_select[idx]; 307 } 308 309 static inline void spi_set_chipselect(struct spi_device *spi, u8 idx, u8 chipselect) 310 { 311 spi->chip_select[idx] = chipselect; 312 } 313 314 static inline struct gpio_desc *spi_get_csgpiod(const struct spi_device *spi, u8 idx) 315 { 316 return spi->cs_gpiod[idx]; 317 } 318 319 static inline void spi_set_csgpiod(struct spi_device *spi, u8 idx, struct gpio_desc *csgpiod) 320 { 321 spi->cs_gpiod[idx] = csgpiod; 322 } 323 324 static inline bool spi_is_csgpiod(struct spi_device *spi) 325 { 326 u8 idx; 327 328 for (idx = 0; idx < spi->num_chipselect; idx++) { 329 if (spi_get_csgpiod(spi, idx)) 330 return true; 331 } 332 return false; 333 } 334 335 /** 336 * struct spi_driver - Host side "protocol" driver 337 * @id_table: List of SPI devices supported by this driver 338 * @probe: Binds this driver to the SPI device. Drivers can verify 339 * that the device is actually present, and may need to configure 340 * characteristics (such as bits_per_word) which weren't needed for 341 * the initial configuration done during system setup. 342 * @remove: Unbinds this driver from the SPI device 343 * @shutdown: Standard shutdown callback used during system state 344 * transitions such as powerdown/halt and kexec 345 * @driver: SPI device drivers should initialize the name and owner 346 * field of this structure. 347 * 348 * This represents the kind of device driver that uses SPI messages to 349 * interact with the hardware at the other end of a SPI link. It's called 350 * a "protocol" driver because it works through messages rather than talking 351 * directly to SPI hardware (which is what the underlying SPI controller 352 * driver does to pass those messages). These protocols are defined in the 353 * specification for the device(s) supported by the driver. 354 * 355 * As a rule, those device protocols represent the lowest level interface 356 * supported by a driver, and it will support upper level interfaces too. 357 * Examples of such upper levels include frameworks like MTD, networking, 358 * MMC, RTC, filesystem character device nodes, and hardware monitoring. 359 */ 360 struct spi_driver { 361 const struct spi_device_id *id_table; 362 int (*probe)(struct spi_device *spi); 363 void (*remove)(struct spi_device *spi); 364 void (*shutdown)(struct spi_device *spi); 365 struct device_driver driver; 366 }; 367 368 #define to_spi_driver(__drv) \ 369 ( __drv ? container_of_const(__drv, struct spi_driver, driver) : NULL ) 370 371 extern int __spi_register_driver(struct module *owner, struct spi_driver *sdrv); 372 373 /** 374 * spi_unregister_driver - reverse effect of spi_register_driver 375 * @sdrv: the driver to unregister 376 * Context: can sleep 377 */ 378 static inline void spi_unregister_driver(struct spi_driver *sdrv) 379 { 380 if (sdrv) 381 driver_unregister(&sdrv->driver); 382 } 383 384 extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 chip_select); 385 extern struct spi_device *devm_spi_new_ancillary_device(struct spi_device *spi, u8 chip_select); 386 387 /* Use a define to avoid include chaining to get THIS_MODULE */ 388 #define spi_register_driver(driver) \ 389 __spi_register_driver(THIS_MODULE, driver) 390 391 /** 392 * module_spi_driver() - Helper macro for registering a SPI driver 393 * @__spi_driver: spi_driver struct 394 * 395 * Helper macro for SPI drivers which do not do anything special in module 396 * init/exit. This eliminates a lot of boilerplate. Each module may only 397 * use this macro once, and calling it replaces module_init() and module_exit() 398 */ 399 #define module_spi_driver(__spi_driver) \ 400 module_driver(__spi_driver, spi_register_driver, \ 401 spi_unregister_driver) 402 403 /** 404 * struct spi_controller - interface to SPI host or target controller 405 * @dev: device interface to this driver 406 * @list: link with the global spi_controller list 407 * @bus_num: board-specific (and often SOC-specific) identifier for a 408 * given SPI controller. 409 * @num_chipselect: chipselects are used to distinguish individual 410 * SPI targets, and are numbered from zero to num_chipselects. 411 * each target has a chipselect signal, but it's common that not 412 * every chipselect is connected to a target. 413 * @num_data_lanes: Number of data lanes supported by this controller. Default is 1. 414 * @dma_alignment: SPI controller constraint on DMA buffers alignment. 415 * @mode_bits: flags understood by this controller driver 416 * @buswidth_override_bits: flags to override for this controller driver 417 * @bits_per_word_mask: A mask indicating which values of bits_per_word are 418 * supported by the driver. Bit n indicates that a bits_per_word n+1 is 419 * supported. If set, the SPI core will reject any transfer with an 420 * unsupported bits_per_word. If not set, this value is simply ignored, 421 * and it's up to the individual driver to perform any validation. 422 * @min_speed_hz: Lowest supported transfer speed 423 * @max_speed_hz: Highest supported transfer speed 424 * @flags: other constraints relevant to this driver 425 * @slave: indicates that this is an SPI slave controller 426 * @target: indicates that this is an SPI target controller 427 * @devm_allocated: whether the allocation of this struct is devres-managed 428 * @max_transfer_size: function that returns the max transfer size for 429 * a &spi_device; may be %NULL, so the default %SIZE_MAX will be used. 430 * @max_message_size: function that returns the max message size for 431 * a &spi_device; may be %NULL, so the default %SIZE_MAX will be used. 432 * @io_mutex: mutex for physical bus access 433 * @add_lock: mutex to avoid adding devices to the same chipselect 434 * @bus_lock_spinlock: spinlock for SPI bus locking 435 * @bus_lock_mutex: mutex for exclusion of multiple callers 436 * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use 437 * @setup: updates the device mode and clocking records used by a 438 * device's SPI controller; protocol code may call this. This 439 * must fail if an unrecognized or unsupported mode is requested. 440 * It's always safe to call this unless transfers are pending on 441 * the device whose settings are being modified. 442 * @set_cs_timing: optional hook for SPI devices to request SPI 443 * controller for configuring specific CS setup time, hold time and inactive 444 * delay in terms of clock counts 445 * @transfer: adds a message to the controller's transfer queue. 446 * @cleanup: frees controller-specific state 447 * @can_dma: determine whether this controller supports DMA 448 * @dma_map_dev: device which can be used for DMA mapping 449 * @cur_rx_dma_dev: device which is currently used for RX DMA mapping 450 * @cur_tx_dma_dev: device which is currently used for TX DMA mapping 451 * @queued: whether this controller is providing an internal message queue 452 * @kworker: pointer to thread struct for message pump 453 * @pump_messages: work struct for scheduling work to the message pump 454 * @queue_lock: spinlock to synchronise access to message queue 455 * @queue: message queue 456 * @cur_msg: the currently in-flight message 457 * @cur_msg_completion: a completion for the current in-flight message 458 * @cur_msg_incomplete: Flag used internally to opportunistically skip 459 * the @cur_msg_completion. This flag is used to check if the driver has 460 * already called spi_finalize_current_message(). 461 * @cur_msg_need_completion: Flag used internally to opportunistically skip 462 * the @cur_msg_completion. This flag is used to signal the context that 463 * is running spi_finalize_current_message() that it needs to complete() 464 * @fallback: fallback to PIO if DMA transfer return failure with 465 * SPI_TRANS_FAIL_NO_START. 466 * @last_cs_mode_high: was (mode & SPI_CS_HIGH) true on the last call to set_cs. 467 * @last_cs: the last chip_select that is recorded by set_cs, -1 on non chip 468 * selected 469 * @last_cs_index_mask: bit mask the last chip selects that were used 470 * @xfer_completion: used by core transfer_one_message() 471 * @busy: message pump is busy 472 * @running: message pump is running 473 * @rt: whether this queue is set to run as a realtime task 474 * @auto_runtime_pm: the core should ensure a runtime PM reference is held 475 * while the hardware is prepared, using the parent 476 * device for the spidev 477 * @max_dma_len: Maximum length of a DMA transfer for the device. 478 * @prepare_transfer_hardware: a message will soon arrive from the queue 479 * so the subsystem requests the driver to prepare the transfer hardware 480 * by issuing this call 481 * @transfer_one_message: the subsystem calls the driver to transfer a single 482 * message while queuing transfers that arrive in the meantime. When the 483 * driver is finished with this message, it must call 484 * spi_finalize_current_message() so the subsystem can issue the next 485 * message 486 * @unprepare_transfer_hardware: there are currently no more messages on the 487 * queue so the subsystem notifies the driver that it may relax the 488 * hardware by issuing this call 489 * 490 * @set_cs: set the logic level of the chip select line. May be called 491 * from interrupt context. 492 * @optimize_message: optimize the message for reuse 493 * @unoptimize_message: release resources allocated by optimize_message 494 * @prepare_message: set up the controller to transfer a single message, 495 * for example doing DMA mapping. Called from threaded 496 * context. 497 * @transfer_one: transfer a single spi_transfer. 498 * 499 * - return 0 if the transfer is finished, 500 * - return 1 if the transfer is still in progress. When 501 * the driver is finished with this transfer it must 502 * call spi_finalize_current_transfer() so the subsystem 503 * can issue the next transfer. If the transfer fails, the 504 * driver must set the flag SPI_TRANS_FAIL_IO to 505 * spi_transfer->error first, before calling 506 * spi_finalize_current_transfer(). 507 * Note: transfer_one and transfer_one_message are mutually 508 * exclusive; when both are set, the generic subsystem does 509 * not call your transfer_one callback. 510 * @handle_err: the subsystem calls the driver to handle an error that occurs 511 * in the generic implementation of transfer_one_message(). 512 * @mem_ops: optimized/dedicated operations for interactions with SPI memory. 513 * This field is optional and should only be implemented if the 514 * controller has native support for memory like operations. 515 * @get_offload: callback for controllers with offload support to get matching 516 * offload instance. Implementations should return -ENODEV if no match is 517 * found. 518 * @put_offload: release the offload instance acquired by @get_offload. 519 * @mem_caps: controller capabilities for the handling of memory operations. 520 * @dtr_caps: true if controller has dtr(single/dual transfer rate) capability. 521 * QSPI based controller should fill this based on controller's capability. 522 * @unprepare_message: undo any work done by prepare_message(). 523 * @target_abort: abort the ongoing transfer request on an SPI target controller 524 * @cs_gpiods: Array of GPIO descriptors to use as chip select lines; one per CS 525 * number. Any individual value may be NULL for CS lines that 526 * are not GPIOs (driven by the SPI controller itself). 527 * @use_gpio_descriptors: Turns on the code in the SPI core to parse and grab 528 * GPIO descriptors. This will fill in @cs_gpiods and SPI devices will have 529 * the cs_gpiod assigned if a GPIO line is found for the chipselect. 530 * @unused_native_cs: When cs_gpiods is used, spi_register_controller() will 531 * fill in this field with the first unused native CS, to be used by SPI 532 * controller drivers that need to drive a native CS when using GPIO CS. 533 * @max_native_cs: When cs_gpiods is used, and this field is filled in, 534 * spi_register_controller() will validate all native CS (including the 535 * unused native CS) against this value. 536 * @pcpu_statistics: statistics for the spi_controller 537 * @dma_tx: DMA transmit channel 538 * @dma_rx: DMA receive channel 539 * @dummy_rx: dummy receive buffer for full-duplex devices 540 * @dummy_tx: dummy transmit buffer for full-duplex devices 541 * @fw_translate_cs: If the boot firmware uses different numbering scheme 542 * what Linux expects, this optional hook can be used to translate 543 * between the two. 544 * @ptp_sts_supported: If the driver sets this to true, it must provide a 545 * time snapshot in @spi_transfer->ptp_sts as close as possible to the 546 * moment in time when @spi_transfer->ptp_sts_word_pre and 547 * @spi_transfer->ptp_sts_word_post were transmitted. 548 * If the driver does not set this, the SPI core takes the snapshot as 549 * close to the driver hand-over as possible. 550 * @irq_flags: Interrupt enable state during PTP system timestamping 551 * @queue_empty: signal green light for opportunistically skipping the queue 552 * for spi_sync transfers. 553 * @must_async: disable all fast paths in the core 554 * @defer_optimize_message: set to true if controller cannot pre-optimize messages 555 * and needs to defer the optimization step until the message is actually 556 * being transferred 557 * 558 * Each SPI controller can communicate with one or more @spi_device 559 * children. These make a small bus, sharing MOSI, MISO and SCK signals 560 * but not chip select signals. Each device may be configured to use a 561 * different clock rate, since those shared signals are ignored unless 562 * the chip is selected. 563 * 564 * The driver for an SPI controller manages access to those devices through 565 * a queue of spi_message transactions, copying data between CPU memory and 566 * an SPI target device. For each such message it queues, it calls the 567 * message's completion function when the transaction completes. 568 */ 569 struct spi_controller { 570 struct device dev; 571 572 struct list_head list; 573 574 /* 575 * Other than negative (== assign one dynamically), bus_num is fully 576 * board-specific. Usually that simplifies to being SoC-specific. 577 * example: one SoC has three SPI controllers, numbered 0..2, 578 * and one board's schematics might show it using SPI-2. Software 579 * would normally use bus_num=2 for that controller. 580 */ 581 s16 bus_num; 582 583 /* 584 * Chipselects will be integral to many controllers; some others 585 * might use board-specific GPIOs. 586 */ 587 u16 num_chipselect; 588 589 /* 590 * Some specialized SPI controllers can have more than one physical 591 * data lane interface per controller (each having it's own serializer). 592 * This specifies the number of data lanes in that case. Other 593 * controllers do not need to set this (defaults to 1). 594 */ 595 u16 num_data_lanes; 596 597 /* Some SPI controllers pose alignment requirements on DMAable 598 * buffers; let protocol drivers know about these requirements. 599 */ 600 u16 dma_alignment; 601 602 /* spi_device.mode flags understood by this controller driver */ 603 u32 mode_bits; 604 605 /* spi_device.mode flags override flags for this controller */ 606 u32 buswidth_override_bits; 607 608 /* Bitmask of supported bits_per_word for transfers */ 609 u32 bits_per_word_mask; 610 #define SPI_BPW_MASK(bits) BIT((bits) - 1) 611 #define SPI_BPW_RANGE_MASK(min, max) GENMASK((max) - 1, (min) - 1) 612 613 /* Limits on transfer speed */ 614 u32 min_speed_hz; 615 u32 max_speed_hz; 616 617 /* Other constraints relevant to this driver */ 618 u16 flags; 619 #define SPI_CONTROLLER_HALF_DUPLEX BIT(0) /* Can't do full duplex */ 620 #define SPI_CONTROLLER_NO_RX BIT(1) /* Can't do buffer read */ 621 #define SPI_CONTROLLER_NO_TX BIT(2) /* Can't do buffer write */ 622 #define SPI_CONTROLLER_MUST_RX BIT(3) /* Requires rx */ 623 #define SPI_CONTROLLER_MUST_TX BIT(4) /* Requires tx */ 624 #define SPI_CONTROLLER_GPIO_SS BIT(5) /* GPIO CS must select target device */ 625 #define SPI_CONTROLLER_SUSPENDED BIT(6) /* Currently suspended */ 626 /* 627 * The spi-controller has multi chip select capability and can 628 * assert/de-assert more than one chip select at once. 629 */ 630 #define SPI_CONTROLLER_MULTI_CS BIT(7) 631 632 /* Flag indicating if the allocation of this struct is devres-managed */ 633 bool devm_allocated; 634 635 union { 636 /* Flag indicating this is an SPI slave controller */ 637 bool slave; 638 /* Flag indicating this is an SPI target controller */ 639 bool target; 640 }; 641 642 /* 643 * On some hardware transfer / message size may be constrained 644 * the limit may depend on device transfer settings. 645 */ 646 size_t (*max_transfer_size)(struct spi_device *spi); 647 size_t (*max_message_size)(struct spi_device *spi); 648 649 /* I/O mutex */ 650 struct mutex io_mutex; 651 652 /* Used to avoid adding the same CS twice */ 653 struct mutex add_lock; 654 655 /* Lock and mutex for SPI bus locking */ 656 spinlock_t bus_lock_spinlock; 657 struct mutex bus_lock_mutex; 658 659 /* Flag indicating that the SPI bus is locked for exclusive use */ 660 bool bus_lock_flag; 661 662 /* 663 * Setup mode and clock, etc (SPI driver may call many times). 664 * 665 * IMPORTANT: this may be called when transfers to another 666 * device are active. DO NOT UPDATE SHARED REGISTERS in ways 667 * which could break those transfers. 668 */ 669 int (*setup)(struct spi_device *spi); 670 671 /* 672 * set_cs_timing() method is for SPI controllers that supports 673 * configuring CS timing. 674 * 675 * This hook allows SPI client drivers to request SPI controllers 676 * to configure specific CS timing through spi_set_cs_timing() after 677 * spi_setup(). 678 */ 679 int (*set_cs_timing)(struct spi_device *spi); 680 681 /* 682 * Bidirectional bulk transfers 683 * 684 * + The transfer() method may not sleep; its main role is 685 * just to add the message to the queue. 686 * + For now there's no remove-from-queue operation, or 687 * any other request management 688 * + To a given spi_device, message queueing is pure FIFO 689 * 690 * + The controller's main job is to process its message queue, 691 * selecting a chip (for controllers), then transferring data 692 * + If there are multiple spi_device children, the i/o queue 693 * arbitration algorithm is unspecified (round robin, FIFO, 694 * priority, reservations, preemption, etc) 695 * 696 * + Chipselect stays active during the entire message 697 * (unless modified by spi_transfer.cs_change != 0). 698 * + The message transfers use clock and SPI mode parameters 699 * previously established by setup() for this device 700 */ 701 int (*transfer)(struct spi_device *spi, 702 struct spi_message *mesg); 703 704 /* Called on release() to free memory provided by spi_controller */ 705 void (*cleanup)(struct spi_device *spi); 706 707 /* 708 * Used to enable core support for DMA handling, if can_dma() 709 * exists and returns true then the transfer will be mapped 710 * prior to transfer_one() being called. The driver should 711 * not modify or store xfer and dma_tx and dma_rx must be set 712 * while the device is prepared. 713 */ 714 bool (*can_dma)(struct spi_controller *ctlr, 715 struct spi_device *spi, 716 struct spi_transfer *xfer); 717 struct device *dma_map_dev; 718 struct device *cur_rx_dma_dev; 719 struct device *cur_tx_dma_dev; 720 721 /* 722 * These hooks are for drivers that want to use the generic 723 * controller transfer queueing mechanism. If these are used, the 724 * transfer() function above must NOT be specified by the driver. 725 * Over time we expect SPI drivers to be phased over to this API. 726 */ 727 bool queued; 728 struct kthread_worker *kworker; 729 struct kthread_work pump_messages; 730 spinlock_t queue_lock; 731 struct list_head queue; 732 struct spi_message *cur_msg; 733 struct completion cur_msg_completion; 734 bool cur_msg_incomplete; 735 bool cur_msg_need_completion; 736 bool busy; 737 bool running; 738 bool rt; 739 bool auto_runtime_pm; 740 bool fallback; 741 bool last_cs_mode_high; 742 s8 last_cs[SPI_DEVICE_CS_CNT_MAX]; 743 u32 last_cs_index_mask : SPI_DEVICE_CS_CNT_MAX; 744 struct completion xfer_completion; 745 size_t max_dma_len; 746 747 int (*optimize_message)(struct spi_message *msg); 748 int (*unoptimize_message)(struct spi_message *msg); 749 int (*prepare_transfer_hardware)(struct spi_controller *ctlr); 750 int (*transfer_one_message)(struct spi_controller *ctlr, 751 struct spi_message *mesg); 752 int (*unprepare_transfer_hardware)(struct spi_controller *ctlr); 753 int (*prepare_message)(struct spi_controller *ctlr, 754 struct spi_message *message); 755 int (*unprepare_message)(struct spi_controller *ctlr, 756 struct spi_message *message); 757 int (*target_abort)(struct spi_controller *ctlr); 758 759 /* 760 * These hooks are for drivers that use a generic implementation 761 * of transfer_one_message() provided by the core. 762 */ 763 void (*set_cs)(struct spi_device *spi, bool enable); 764 int (*transfer_one)(struct spi_controller *ctlr, struct spi_device *spi, 765 struct spi_transfer *transfer); 766 void (*handle_err)(struct spi_controller *ctlr, 767 struct spi_message *message); 768 769 /* Optimized handlers for SPI memory-like operations. */ 770 const struct spi_controller_mem_ops *mem_ops; 771 const struct spi_controller_mem_caps *mem_caps; 772 773 /* SPI or QSPI controller can set to true if supports SDR/DDR transfer rate */ 774 bool dtr_caps; 775 776 struct spi_offload *(*get_offload)(struct spi_device *spi, 777 const struct spi_offload_config *config); 778 void (*put_offload)(struct spi_offload *offload); 779 780 /* GPIO chip select */ 781 struct gpio_desc **cs_gpiods; 782 bool use_gpio_descriptors; 783 s8 unused_native_cs; 784 s8 max_native_cs; 785 786 /* Statistics */ 787 struct spi_statistics __percpu *pcpu_statistics; 788 789 /* DMA channels for use with core dmaengine helpers */ 790 struct dma_chan *dma_tx; 791 struct dma_chan *dma_rx; 792 793 /* Dummy data for full duplex devices */ 794 void *dummy_rx; 795 void *dummy_tx; 796 797 int (*fw_translate_cs)(struct spi_controller *ctlr, unsigned cs); 798 799 /* 800 * Driver sets this field to indicate it is able to snapshot SPI 801 * transfers (needed e.g. for reading the time of POSIX clocks) 802 */ 803 bool ptp_sts_supported; 804 805 /* Interrupt enable state during PTP system timestamping */ 806 unsigned long irq_flags; 807 808 /* Flag for enabling opportunistic skipping of the queue in spi_sync */ 809 bool queue_empty; 810 bool must_async; 811 bool defer_optimize_message; 812 }; 813 814 static inline void *spi_controller_get_devdata(struct spi_controller *ctlr) 815 { 816 return dev_get_drvdata(&ctlr->dev); 817 } 818 819 static inline void spi_controller_set_devdata(struct spi_controller *ctlr, 820 void *data) 821 { 822 dev_set_drvdata(&ctlr->dev, data); 823 } 824 825 static inline struct spi_controller *spi_controller_get(struct spi_controller *ctlr) 826 { 827 if (!ctlr || !get_device(&ctlr->dev)) 828 return NULL; 829 return ctlr; 830 } 831 832 static inline void spi_controller_put(struct spi_controller *ctlr) 833 { 834 if (ctlr) 835 put_device(&ctlr->dev); 836 } 837 838 static inline bool spi_controller_is_target(struct spi_controller *ctlr) 839 { 840 return IS_ENABLED(CONFIG_SPI_SLAVE) && ctlr->target; 841 } 842 843 /* PM calls that need to be issued by the driver */ 844 extern int spi_controller_suspend(struct spi_controller *ctlr); 845 extern int spi_controller_resume(struct spi_controller *ctlr); 846 847 /* Calls the driver make to interact with the message queue */ 848 extern struct spi_message *spi_get_next_queued_message(struct spi_controller *ctlr); 849 extern void spi_finalize_current_message(struct spi_controller *ctlr); 850 extern void spi_finalize_current_transfer(struct spi_controller *ctlr); 851 852 /* Helper calls for driver to timestamp transfer */ 853 void spi_take_timestamp_pre(struct spi_controller *ctlr, 854 struct spi_transfer *xfer, 855 size_t progress, bool irqs_off); 856 void spi_take_timestamp_post(struct spi_controller *ctlr, 857 struct spi_transfer *xfer, 858 size_t progress, bool irqs_off); 859 860 /* The SPI driver core manages memory for the spi_controller classdev */ 861 extern struct spi_controller *__spi_alloc_controller(struct device *host, 862 unsigned int size, bool target); 863 864 static inline struct spi_controller *spi_alloc_host(struct device *dev, 865 unsigned int size) 866 { 867 return __spi_alloc_controller(dev, size, false); 868 } 869 870 static inline struct spi_controller *spi_alloc_target(struct device *dev, 871 unsigned int size) 872 { 873 if (!IS_ENABLED(CONFIG_SPI_SLAVE)) 874 return NULL; 875 876 return __spi_alloc_controller(dev, size, true); 877 } 878 879 struct spi_controller *__devm_spi_alloc_controller(struct device *dev, 880 unsigned int size, 881 bool target); 882 883 static inline struct spi_controller *devm_spi_alloc_host(struct device *dev, 884 unsigned int size) 885 { 886 return __devm_spi_alloc_controller(dev, size, false); 887 } 888 889 static inline struct spi_controller *devm_spi_alloc_target(struct device *dev, 890 unsigned int size) 891 { 892 if (!IS_ENABLED(CONFIG_SPI_SLAVE)) 893 return NULL; 894 895 return __devm_spi_alloc_controller(dev, size, true); 896 } 897 898 extern int spi_register_controller(struct spi_controller *ctlr); 899 extern int devm_spi_register_controller(struct device *dev, 900 struct spi_controller *ctlr); 901 extern void spi_unregister_controller(struct spi_controller *ctlr); 902 903 #if IS_ENABLED(CONFIG_OF) 904 extern struct spi_controller *of_find_spi_controller_by_node(struct device_node *node); 905 #else 906 static inline struct spi_controller *of_find_spi_controller_by_node(struct device_node *node) 907 { 908 return NULL; 909 } 910 #endif 911 912 #if IS_ENABLED(CONFIG_ACPI) && IS_ENABLED(CONFIG_SPI_MASTER) 913 extern struct spi_controller *acpi_spi_find_controller_by_adev(struct acpi_device *adev); 914 extern struct spi_device *acpi_spi_device_alloc(struct spi_controller *ctlr, 915 struct acpi_device *adev, 916 int index); 917 int acpi_spi_count_resources(struct acpi_device *adev); 918 #else 919 static inline struct spi_controller *acpi_spi_find_controller_by_adev(struct acpi_device *adev) 920 { 921 return NULL; 922 } 923 924 static inline struct spi_device *acpi_spi_device_alloc(struct spi_controller *ctlr, 925 struct acpi_device *adev, 926 int index) 927 { 928 return ERR_PTR(-ENODEV); 929 } 930 931 static inline int acpi_spi_count_resources(struct acpi_device *adev) 932 { 933 return 0; 934 } 935 #endif 936 937 /* 938 * SPI resource management while processing a SPI message 939 */ 940 941 typedef void (*spi_res_release_t)(struct spi_controller *ctlr, 942 struct spi_message *msg, 943 void *res); 944 945 /** 946 * struct spi_res - SPI resource management structure 947 * @entry: list entry 948 * @release: release code called prior to freeing this resource 949 * @data: extra data allocated for the specific use-case 950 * 951 * This is based on ideas from devres, but focused on life-cycle 952 * management during spi_message processing. 953 */ 954 struct spi_res { 955 struct list_head entry; 956 spi_res_release_t release; 957 unsigned long long data[]; /* Guarantee ull alignment */ 958 }; 959 960 /*---------------------------------------------------------------------------*/ 961 962 /* 963 * I/O INTERFACE between SPI controller and protocol drivers 964 * 965 * Protocol drivers use a queue of spi_messages, each transferring data 966 * between the controller and memory buffers. 967 * 968 * The spi_messages themselves consist of a series of read+write transfer 969 * segments. Those segments always read the same number of bits as they 970 * write; but one or the other is easily ignored by passing a NULL buffer 971 * pointer. (This is unlike most types of I/O API, because SPI hardware 972 * is full duplex.) 973 * 974 * NOTE: Allocation of spi_transfer and spi_message memory is entirely 975 * up to the protocol driver, which guarantees the integrity of both (as 976 * well as the data buffers) for as long as the message is queued. 977 */ 978 979 /** 980 * struct spi_transfer - a read/write buffer pair 981 * @tx_buf: data to be written (DMA-safe memory), or NULL 982 * @rx_buf: data to be read (DMA-safe memory), or NULL 983 * @tx_dma: DMA address of tx_buf, currently not for client use 984 * @rx_dma: DMA address of rx_buf, currently not for client use 985 * @tx_nbits: number of bits used for writing. If 0 the default 986 * (SPI_NBITS_SINGLE) is used. 987 * @rx_nbits: number of bits used for reading. If 0 the default 988 * (SPI_NBITS_SINGLE) is used. 989 * @multi_lane_mode: How to serialize data on multiple lanes. One of the 990 * SPI_MULTI_LANE_MODE_* values. 991 * @len: size of rx and tx buffers (in bytes) 992 * @speed_hz: Select a speed other than the device default for this 993 * transfer. If 0 the default (from @spi_device) is used. 994 * @bits_per_word: select a bits_per_word other than the device default 995 * for this transfer. If 0 the default (from @spi_device) is used. 996 * @dummy_data: indicates transfer is dummy bytes transfer. 997 * @cs_off: performs the transfer with chipselect off. 998 * @cs_change: affects chipselect after this transfer completes 999 * @cs_change_delay: delay between cs deassert and assert when 1000 * @cs_change is set and @spi_transfer is not the last in @spi_message 1001 * @delay: delay to be introduced after this transfer before 1002 * (optionally) changing the chipselect status, then starting 1003 * the next transfer or completing this @spi_message. 1004 * @word_delay: inter word delay to be introduced after each word size 1005 * (set by bits_per_word) transmission. 1006 * @effective_speed_hz: the effective SCK-speed that was used to 1007 * transfer this transfer. Set to 0 if the SPI bus driver does 1008 * not support it. 1009 * @transfer_list: transfers are sequenced through @spi_message.transfers 1010 * @tx_sg_mapped: If true, the @tx_sg is mapped for DMA 1011 * @rx_sg_mapped: If true, the @rx_sg is mapped for DMA 1012 * @tx_sg: Scatterlist for transmit, currently not for client use 1013 * @rx_sg: Scatterlist for receive, currently not for client use 1014 * @offload_flags: Flags that are only applicable to specialized SPI offload 1015 * transfers. See %SPI_OFFLOAD_XFER_* in spi-offload.h. 1016 * @ptp_sts_word_pre: The word (subject to bits_per_word semantics) offset 1017 * within @tx_buf for which the SPI device is requesting that the time 1018 * snapshot for this transfer begins. Upon completing the SPI transfer, 1019 * this value may have changed compared to what was requested, depending 1020 * on the available snapshotting resolution (DMA transfer, 1021 * @ptp_sts_supported is false, etc). 1022 * @ptp_sts_word_post: See @ptp_sts_word_post. The two can be equal (meaning 1023 * that a single byte should be snapshotted). 1024 * If the core takes care of the timestamp (if @ptp_sts_supported is false 1025 * for this controller), it will set @ptp_sts_word_pre to 0, and 1026 * @ptp_sts_word_post to the length of the transfer. This is done 1027 * purposefully (instead of setting to spi_transfer->len - 1) to denote 1028 * that a transfer-level snapshot taken from within the driver may still 1029 * be of higher quality. 1030 * @ptp_sts: Pointer to a memory location held by the SPI target device where a 1031 * PTP system timestamp structure may lie. If drivers use PIO or their 1032 * hardware has some sort of assist for retrieving exact transfer timing, 1033 * they can (and should) assert @ptp_sts_supported and populate this 1034 * structure using the ptp_read_system_*ts helper functions. 1035 * The timestamp must represent the time at which the SPI target device has 1036 * processed the word, i.e. the "pre" timestamp should be taken before 1037 * transmitting the "pre" word, and the "post" timestamp after receiving 1038 * transmit confirmation from the controller for the "post" word. 1039 * @dtr_mode: true if supports double transfer rate. 1040 * @timestamped: true if the transfer has been timestamped 1041 * @error: Error status logged by SPI controller driver. 1042 * 1043 * SPI transfers always write the same number of bytes as they read. 1044 * Protocol drivers should always provide @rx_buf and/or @tx_buf. 1045 * In some cases, they may also want to provide DMA addresses for 1046 * the data being transferred; that may reduce overhead, when the 1047 * underlying driver uses DMA. 1048 * 1049 * If the transmit buffer is NULL, zeroes will be shifted out 1050 * while filling @rx_buf. If the receive buffer is NULL, the data 1051 * shifted in will be discarded. Only "len" bytes shift out (or in). 1052 * It's an error to try to shift out a partial word. (For example, by 1053 * shifting out three bytes with word size of sixteen or twenty bits; 1054 * the former uses two bytes per word, the latter uses four bytes.) 1055 * 1056 * In-memory data values are always in native CPU byte order, translated 1057 * from the wire byte order (big-endian except with SPI_LSB_FIRST). So 1058 * for example when bits_per_word is sixteen, buffers are 2N bytes long 1059 * (@len = 2N) and hold N sixteen bit words in CPU byte order. 1060 * 1061 * When the word size of the SPI transfer is not a power-of-two multiple 1062 * of eight bits, those in-memory words include extra bits. In-memory 1063 * words are always seen by protocol drivers as right-justified, so the 1064 * undefined (rx) or unused (tx) bits are always the most significant bits. 1065 * 1066 * All SPI transfers start with the relevant chipselect active. Normally 1067 * it stays selected until after the last transfer in a message. Drivers 1068 * can affect the chipselect signal using cs_change. 1069 * 1070 * (i) If the transfer isn't the last one in the message, this flag is 1071 * used to make the chipselect briefly go inactive in the middle of the 1072 * message. Toggling chipselect in this way may be needed to terminate 1073 * a chip command, letting a single spi_message perform all of group of 1074 * chip transactions together. 1075 * 1076 * (ii) When the transfer is the last one in the message, the chip may 1077 * stay selected until the next transfer. On multi-device SPI busses 1078 * with nothing blocking messages going to other devices, this is just 1079 * a performance hint; starting a message to another device deselects 1080 * this one. But in other cases, this can be used to ensure correctness. 1081 * Some devices need protocol transactions to be built from a series of 1082 * spi_message submissions, where the content of one message is determined 1083 * by the results of previous messages and where the whole transaction 1084 * ends when the chipselect goes inactive. 1085 * 1086 * When SPI can transfer in 1x,2x or 4x. It can get this transfer information 1087 * from device through @tx_nbits and @rx_nbits. In Bi-direction, these 1088 * two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x) 1089 * SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer. 1090 * 1091 * User may also set dtr_mode to true to use dual transfer mode if desired. if 1092 * not, default considered as single transfer mode. 1093 * 1094 * The code that submits an spi_message (and its spi_transfers) 1095 * to the lower layers is responsible for managing its memory. 1096 * Zero-initialize every field you don't set up explicitly, to 1097 * insulate against future API updates. After you submit a message 1098 * and its transfers, ignore them until its completion callback. 1099 */ 1100 struct spi_transfer { 1101 /* 1102 * It's okay if tx_buf == rx_buf (right?). 1103 * For MicroWire, one buffer must be NULL. 1104 * Buffers must work with dma_*map_single() calls. 1105 */ 1106 const void *tx_buf; 1107 void *rx_buf; 1108 unsigned len; 1109 1110 #define SPI_TRANS_FAIL_NO_START BIT(0) 1111 #define SPI_TRANS_FAIL_IO BIT(1) 1112 u16 error; 1113 1114 bool tx_sg_mapped; 1115 bool rx_sg_mapped; 1116 1117 struct sg_table tx_sg; 1118 struct sg_table rx_sg; 1119 dma_addr_t tx_dma; 1120 dma_addr_t rx_dma; 1121 1122 unsigned dummy_data:1; 1123 unsigned cs_off:1; 1124 unsigned cs_change:1; 1125 unsigned tx_nbits:4; 1126 unsigned rx_nbits:4; 1127 1128 #define SPI_MULTI_LANE_MODE_SINGLE 0 /* only use single lane */ 1129 #define SPI_MULTI_LANE_MODE_STRIPE 1 /* one data word per lane */ 1130 #define SPI_MULTI_LANE_MODE_MIRROR 2 /* same word sent on all lanes */ 1131 unsigned multi_lane_mode: 2; 1132 1133 unsigned timestamped:1; 1134 bool dtr_mode; 1135 #define SPI_NBITS_SINGLE 0x01 /* 1-bit transfer */ 1136 #define SPI_NBITS_DUAL 0x02 /* 2-bit transfer */ 1137 #define SPI_NBITS_QUAD 0x04 /* 4-bit transfer */ 1138 #define SPI_NBITS_OCTAL 0x08 /* 8-bit transfer */ 1139 u8 bits_per_word; 1140 struct spi_delay delay; 1141 struct spi_delay cs_change_delay; 1142 struct spi_delay word_delay; 1143 u32 speed_hz; 1144 1145 u32 effective_speed_hz; 1146 1147 /* Use %SPI_OFFLOAD_XFER_* from spi-offload.h */ 1148 unsigned int offload_flags; 1149 1150 unsigned int ptp_sts_word_pre; 1151 unsigned int ptp_sts_word_post; 1152 1153 struct ptp_system_timestamp *ptp_sts; 1154 1155 struct list_head transfer_list; 1156 }; 1157 1158 /** 1159 * struct spi_message - one multi-segment SPI transaction 1160 * @transfers: list of transfer segments in this transaction 1161 * @spi: SPI device to which the transaction is queued 1162 * @pre_optimized: peripheral driver pre-optimized the message 1163 * @optimized: the message is in the optimized state 1164 * @prepared: spi_prepare_message was called for the this message 1165 * @status: zero for success, else negative errno 1166 * @complete: called to report transaction completions 1167 * @context: the argument to complete() when it's called 1168 * @frame_length: the total number of bytes in the message 1169 * @actual_length: the total number of bytes that were transferred in all 1170 * successful segments 1171 * @queue: for use by whichever driver currently owns the message 1172 * @state: for use by whichever driver currently owns the message 1173 * @opt_state: for use by whichever driver currently owns the message 1174 * @resources: for resource management when the SPI message is processed 1175 * @offload: (optional) offload instance used by this message 1176 * 1177 * A @spi_message is used to execute an atomic sequence of data transfers, 1178 * each represented by a struct spi_transfer. The sequence is "atomic" 1179 * in the sense that no other spi_message may use that SPI bus until that 1180 * sequence completes. On some systems, many such sequences can execute as 1181 * a single programmed DMA transfer. On all systems, these messages are 1182 * queued, and might complete after transactions to other devices. Messages 1183 * sent to a given spi_device are always executed in FIFO order. 1184 * 1185 * The code that submits an spi_message (and its spi_transfers) 1186 * to the lower layers is responsible for managing its memory. 1187 * Zero-initialize every field you don't set up explicitly, to 1188 * insulate against future API updates. After you submit a message 1189 * and its transfers, ignore them until its completion callback. 1190 */ 1191 struct spi_message { 1192 struct list_head transfers; 1193 1194 struct spi_device *spi; 1195 1196 /* spi_optimize_message() was called for this message */ 1197 bool pre_optimized; 1198 /* __spi_optimize_message() was called for this message */ 1199 bool optimized; 1200 1201 /* spi_prepare_message() was called for this message */ 1202 bool prepared; 1203 1204 /* 1205 * REVISIT: we might want a flag affecting the behavior of the 1206 * last transfer ... allowing things like "read 16 bit length L" 1207 * immediately followed by "read L bytes". Basically imposing 1208 * a specific message scheduling algorithm. 1209 * 1210 * Some controller drivers (message-at-a-time queue processing) 1211 * could provide that as their default scheduling algorithm. But 1212 * others (with multi-message pipelines) could need a flag to 1213 * tell them about such special cases. 1214 */ 1215 1216 /* Completion is reported through a callback */ 1217 int status; 1218 void (*complete)(void *context); 1219 void *context; 1220 unsigned frame_length; 1221 unsigned actual_length; 1222 1223 /* 1224 * For optional use by whatever driver currently owns the 1225 * spi_message ... between calls to spi_async and then later 1226 * complete(), that's the spi_controller controller driver. 1227 */ 1228 struct list_head queue; 1229 void *state; 1230 /* 1231 * Optional state for use by controller driver between calls to 1232 * __spi_optimize_message() and __spi_unoptimize_message(). 1233 */ 1234 void *opt_state; 1235 1236 /* 1237 * Optional offload instance used by this message. This must be set 1238 * by the peripheral driver before calling spi_optimize_message(). 1239 */ 1240 struct spi_offload *offload; 1241 1242 /* List of spi_res resources when the SPI message is processed */ 1243 struct list_head resources; 1244 }; 1245 1246 static inline void spi_message_init_no_memset(struct spi_message *m) 1247 { 1248 INIT_LIST_HEAD(&m->transfers); 1249 INIT_LIST_HEAD(&m->resources); 1250 } 1251 1252 static inline void spi_message_init(struct spi_message *m) 1253 { 1254 memset(m, 0, sizeof *m); 1255 spi_message_init_no_memset(m); 1256 } 1257 1258 static inline void 1259 spi_message_add_tail(struct spi_transfer *t, struct spi_message *m) 1260 { 1261 list_add_tail(&t->transfer_list, &m->transfers); 1262 } 1263 1264 static inline void 1265 spi_transfer_del(struct spi_transfer *t) 1266 { 1267 list_del(&t->transfer_list); 1268 } 1269 1270 static inline int 1271 spi_transfer_delay_exec(struct spi_transfer *t) 1272 { 1273 return spi_delay_exec(&t->delay, t); 1274 } 1275 1276 /** 1277 * spi_message_init_with_transfers - Initialize spi_message and append transfers 1278 * @m: spi_message to be initialized 1279 * @xfers: An array of SPI transfers 1280 * @num_xfers: Number of items in the xfer array 1281 * 1282 * This function initializes the given spi_message and adds each spi_transfer in 1283 * the given array to the message. 1284 */ 1285 static inline void 1286 spi_message_init_with_transfers(struct spi_message *m, 1287 struct spi_transfer *xfers, unsigned int num_xfers) 1288 { 1289 unsigned int i; 1290 1291 spi_message_init(m); 1292 for (i = 0; i < num_xfers; ++i) 1293 spi_message_add_tail(&xfers[i], m); 1294 } 1295 1296 /* 1297 * It's fine to embed message and transaction structures in other data 1298 * structures so long as you don't free them while they're in use. 1299 */ 1300 static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags) 1301 { 1302 struct spi_message_with_transfers { 1303 struct spi_message m; 1304 struct spi_transfer t[]; 1305 } *mwt; 1306 unsigned i; 1307 1308 mwt = kzalloc_flex(*mwt, t, ntrans, flags); 1309 if (!mwt) 1310 return NULL; 1311 1312 spi_message_init_no_memset(&mwt->m); 1313 for (i = 0; i < ntrans; i++) 1314 spi_message_add_tail(&mwt->t[i], &mwt->m); 1315 1316 return &mwt->m; 1317 } 1318 1319 static inline void spi_message_free(struct spi_message *m) 1320 { 1321 kfree(m); 1322 } 1323 1324 extern int spi_optimize_message(struct spi_device *spi, struct spi_message *msg); 1325 extern void spi_unoptimize_message(struct spi_message *msg); 1326 extern int devm_spi_optimize_message(struct device *dev, struct spi_device *spi, 1327 struct spi_message *msg); 1328 1329 extern int spi_setup(struct spi_device *spi); 1330 extern int spi_async(struct spi_device *spi, struct spi_message *message); 1331 extern int spi_target_abort(struct spi_device *spi); 1332 1333 static inline size_t 1334 spi_max_message_size(struct spi_device *spi) 1335 { 1336 struct spi_controller *ctlr = spi->controller; 1337 1338 if (!ctlr->max_message_size) 1339 return SIZE_MAX; 1340 return ctlr->max_message_size(spi); 1341 } 1342 1343 static inline size_t 1344 spi_max_transfer_size(struct spi_device *spi) 1345 { 1346 struct spi_controller *ctlr = spi->controller; 1347 size_t tr_max = SIZE_MAX; 1348 size_t msg_max = spi_max_message_size(spi); 1349 1350 if (ctlr->max_transfer_size) 1351 tr_max = ctlr->max_transfer_size(spi); 1352 1353 /* Transfer size limit must not be greater than message size limit */ 1354 return min(tr_max, msg_max); 1355 } 1356 1357 /** 1358 * spi_is_bpw_supported - Check if bits per word is supported 1359 * @spi: SPI device 1360 * @bpw: Bits per word 1361 * 1362 * This function checks to see if the SPI controller supports @bpw. 1363 * 1364 * Returns: 1365 * True if @bpw is supported, false otherwise. 1366 */ 1367 static inline bool spi_is_bpw_supported(struct spi_device *spi, u32 bpw) 1368 { 1369 u32 bpw_mask = spi->controller->bits_per_word_mask; 1370 1371 if (bpw == 8 || (bpw <= 32 && bpw_mask & SPI_BPW_MASK(bpw))) 1372 return true; 1373 1374 return false; 1375 } 1376 1377 /** 1378 * spi_bpw_to_bytes - Covert bits per word to bytes 1379 * @bpw: Bits per word 1380 * 1381 * This function converts the given @bpw to bytes. The result is always 1382 * power-of-two, e.g., 1383 * 1384 * =============== ================= 1385 * Input (in bits) Output (in bytes) 1386 * =============== ================= 1387 * 5 1 1388 * 9 2 1389 * 21 4 1390 * 37 8 1391 * =============== ================= 1392 * 1393 * It will return 0 for the 0 input. 1394 * 1395 * Returns: 1396 * Bytes for the given @bpw. 1397 */ 1398 static inline u32 spi_bpw_to_bytes(u32 bpw) 1399 { 1400 return roundup_pow_of_two(BITS_TO_BYTES(bpw)); 1401 } 1402 1403 /** 1404 * spi_controller_xfer_timeout - Compute a suitable timeout value 1405 * @ctlr: SPI device 1406 * @xfer: Transfer descriptor 1407 * 1408 * Compute a relevant timeout value for the given transfer. We derive the time 1409 * that it would take on a single data line and take twice this amount of time 1410 * with a minimum of 500ms to avoid false positives on loaded systems. 1411 * 1412 * Returns: Transfer timeout value in milliseconds. 1413 */ 1414 static inline unsigned int spi_controller_xfer_timeout(struct spi_controller *ctlr, 1415 struct spi_transfer *xfer) 1416 { 1417 return max(xfer->len * 8 * 2 / (xfer->speed_hz / 1000), 500U); 1418 } 1419 1420 /*---------------------------------------------------------------------------*/ 1421 1422 /* SPI transfer replacement methods which make use of spi_res */ 1423 1424 struct spi_replaced_transfers; 1425 typedef void (*spi_replaced_release_t)(struct spi_controller *ctlr, 1426 struct spi_message *msg, 1427 struct spi_replaced_transfers *res); 1428 /** 1429 * struct spi_replaced_transfers - structure describing the spi_transfer 1430 * replacements that have occurred 1431 * so that they can get reverted 1432 * @release: some extra release code to get executed prior to 1433 * releasing this structure 1434 * @extradata: pointer to some extra data if requested or NULL 1435 * @replaced_transfers: transfers that have been replaced and which need 1436 * to get restored 1437 * @replaced_after: the transfer after which the @replaced_transfers 1438 * are to get re-inserted 1439 * @inserted: number of transfers inserted 1440 * @inserted_transfers: array of spi_transfers of array-size @inserted, 1441 * that have been replacing replaced_transfers 1442 * 1443 * Note: that @extradata will point to @inserted_transfers[@inserted] 1444 * if some extra allocation is requested, so alignment will be the same 1445 * as for spi_transfers. 1446 */ 1447 struct spi_replaced_transfers { 1448 spi_replaced_release_t release; 1449 void *extradata; 1450 struct list_head replaced_transfers; 1451 struct list_head *replaced_after; 1452 size_t inserted; 1453 struct spi_transfer inserted_transfers[]; 1454 }; 1455 1456 /*---------------------------------------------------------------------------*/ 1457 1458 /* SPI transfer transformation methods */ 1459 1460 extern int spi_split_transfers_maxsize(struct spi_controller *ctlr, 1461 struct spi_message *msg, 1462 size_t maxsize); 1463 extern int spi_split_transfers_maxwords(struct spi_controller *ctlr, 1464 struct spi_message *msg, 1465 size_t maxwords); 1466 1467 /*---------------------------------------------------------------------------*/ 1468 1469 /* 1470 * All these synchronous SPI transfer routines are utilities layered 1471 * over the core async transfer primitive. Here, "synchronous" means 1472 * they will sleep uninterruptibly until the async transfer completes. 1473 */ 1474 1475 extern int spi_sync(struct spi_device *spi, struct spi_message *message); 1476 extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message); 1477 extern int spi_bus_lock(struct spi_controller *ctlr); 1478 extern int spi_bus_unlock(struct spi_controller *ctlr); 1479 1480 /** 1481 * spi_sync_transfer - synchronous SPI data transfer 1482 * @spi: device with which data will be exchanged 1483 * @xfers: An array of spi_transfers 1484 * @num_xfers: Number of items in the xfer array 1485 * Context: can sleep 1486 * 1487 * Does a synchronous SPI data transfer of the given spi_transfer array. 1488 * 1489 * For more specific semantics see spi_sync(). 1490 * 1491 * Return: zero on success, else a negative error code. 1492 */ 1493 static inline int 1494 spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers, 1495 unsigned int num_xfers) 1496 { 1497 struct spi_message msg; 1498 1499 spi_message_init_with_transfers(&msg, xfers, num_xfers); 1500 1501 return spi_sync(spi, &msg); 1502 } 1503 1504 /** 1505 * spi_write - SPI synchronous write 1506 * @spi: device to which data will be written 1507 * @buf: data buffer 1508 * @len: data buffer size 1509 * Context: can sleep 1510 * 1511 * This function writes the buffer @buf. 1512 * Callable only from contexts that can sleep. 1513 * 1514 * Return: zero on success, else a negative error code. 1515 */ 1516 static inline int 1517 spi_write(struct spi_device *spi, const void *buf, size_t len) 1518 { 1519 struct spi_transfer t = { 1520 .tx_buf = buf, 1521 .len = len, 1522 }; 1523 1524 return spi_sync_transfer(spi, &t, 1); 1525 } 1526 1527 /** 1528 * spi_read - SPI synchronous read 1529 * @spi: device from which data will be read 1530 * @buf: data buffer 1531 * @len: data buffer size 1532 * Context: can sleep 1533 * 1534 * This function reads the buffer @buf. 1535 * Callable only from contexts that can sleep. 1536 * 1537 * Return: zero on success, else a negative error code. 1538 */ 1539 static inline int 1540 spi_read(struct spi_device *spi, void *buf, size_t len) 1541 { 1542 struct spi_transfer t = { 1543 .rx_buf = buf, 1544 .len = len, 1545 }; 1546 1547 return spi_sync_transfer(spi, &t, 1); 1548 } 1549 1550 /* This copies txbuf and rxbuf data; for small transfers only! */ 1551 extern int spi_write_then_read(struct spi_device *spi, 1552 const void *txbuf, unsigned n_tx, 1553 void *rxbuf, unsigned n_rx); 1554 1555 /** 1556 * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read 1557 * @spi: device with which data will be exchanged 1558 * @cmd: command to be written before data is read back 1559 * Context: can sleep 1560 * 1561 * Callable only from contexts that can sleep. 1562 * 1563 * Return: the (unsigned) eight bit number returned by the 1564 * device, or else a negative error code. 1565 */ 1566 static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd) 1567 { 1568 ssize_t status; 1569 u8 result; 1570 1571 status = spi_write_then_read(spi, &cmd, 1, &result, 1); 1572 1573 /* Return negative errno or unsigned value */ 1574 return (status < 0) ? status : result; 1575 } 1576 1577 /** 1578 * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read 1579 * @spi: device with which data will be exchanged 1580 * @cmd: command to be written before data is read back 1581 * Context: can sleep 1582 * 1583 * The number is returned in wire-order, which is at least sometimes 1584 * big-endian. 1585 * 1586 * Callable only from contexts that can sleep. 1587 * 1588 * Return: the (unsigned) sixteen bit number returned by the 1589 * device, or else a negative error code. 1590 */ 1591 static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd) 1592 { 1593 ssize_t status; 1594 u16 result; 1595 1596 status = spi_write_then_read(spi, &cmd, 1, &result, 2); 1597 1598 /* Return negative errno or unsigned value */ 1599 return (status < 0) ? status : result; 1600 } 1601 1602 /** 1603 * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read 1604 * @spi: device with which data will be exchanged 1605 * @cmd: command to be written before data is read back 1606 * Context: can sleep 1607 * 1608 * This function is similar to spi_w8r16, with the exception that it will 1609 * convert the read 16 bit data word from big-endian to native endianness. 1610 * 1611 * Callable only from contexts that can sleep. 1612 * 1613 * Return: the (unsigned) sixteen bit number returned by the device in CPU 1614 * endianness, or else a negative error code. 1615 */ 1616 static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd) 1617 1618 { 1619 ssize_t status; 1620 __be16 result; 1621 1622 status = spi_write_then_read(spi, &cmd, 1, &result, 2); 1623 if (status < 0) 1624 return status; 1625 1626 return be16_to_cpu(result); 1627 } 1628 1629 /*---------------------------------------------------------------------------*/ 1630 1631 /* 1632 * INTERFACE between board init code and SPI infrastructure. 1633 * 1634 * No SPI driver ever sees these SPI device table segments, but 1635 * it's how the SPI core (or adapters that get hotplugged) grows 1636 * the driver model tree. 1637 * 1638 * As a rule, SPI devices can't be probed. Instead, board init code 1639 * provides a table listing the devices which are present, with enough 1640 * information to bind and set up the device's driver. There's basic 1641 * support for non-static configurations too; enough to handle adding 1642 * parport adapters, or microcontrollers acting as USB-to-SPI bridges. 1643 */ 1644 1645 /** 1646 * struct spi_board_info - board-specific template for a SPI device 1647 * @modalias: Initializes spi_device.modalias; identifies the driver. 1648 * @platform_data: Initializes spi_device.platform_data; the particular 1649 * data stored there is driver-specific. 1650 * @swnode: Software node for the device. 1651 * @controller_data: Initializes spi_device.controller_data; some 1652 * controllers need hints about hardware setup, e.g. for DMA. 1653 * @irq: Initializes spi_device.irq; depends on how the board is wired. 1654 * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits 1655 * from the chip datasheet and board-specific signal quality issues. 1656 * @bus_num: Identifies which spi_controller parents the spi_device; unused 1657 * by spi_new_device(), and otherwise depends on board wiring. 1658 * @chip_select: Initializes spi_device.chip_select; depends on how 1659 * the board is wired. 1660 * @mode: Initializes spi_device.mode; based on the chip datasheet, board 1661 * wiring (some devices support both 3WIRE and standard modes), and 1662 * possibly presence of an inverter in the chipselect path. 1663 * 1664 * When adding new SPI devices to the device tree, these structures serve 1665 * as a partial device template. They hold information which can't always 1666 * be determined by drivers. Information that probe() can establish (such 1667 * as the default transfer wordsize) is not included here. 1668 * 1669 * These structures are used in two places. Their primary role is to 1670 * be stored in tables of board-specific device descriptors, which are 1671 * declared early in board initialization and then used (much later) to 1672 * populate a controller's device tree after the that controller's driver 1673 * initializes. A secondary (and atypical) role is as a parameter to 1674 * spi_new_device() call, which happens after those controller drivers 1675 * are active in some dynamic board configuration models. 1676 */ 1677 struct spi_board_info { 1678 /* 1679 * The device name and module name are coupled, like platform_bus; 1680 * "modalias" is normally the driver name. 1681 * 1682 * platform_data goes to spi_device.dev.platform_data, 1683 * controller_data goes to spi_device.controller_data, 1684 * IRQ is copied too. 1685 */ 1686 char modalias[SPI_NAME_SIZE]; 1687 const void *platform_data; 1688 const struct software_node *swnode; 1689 void *controller_data; 1690 int irq; 1691 1692 /* Slower signaling on noisy or low voltage boards */ 1693 u32 max_speed_hz; 1694 1695 1696 /* 1697 * bus_num is board specific and matches the bus_num of some 1698 * spi_controller that will probably be registered later. 1699 * 1700 * chip_select reflects how this chip is wired to that controller; 1701 * it's less than num_chipselect. 1702 */ 1703 u16 bus_num; 1704 u16 chip_select; 1705 1706 /* 1707 * mode becomes spi_device.mode, and is essential for chips 1708 * where the default of SPI_CS_HIGH = 0 is wrong. 1709 */ 1710 u32 mode; 1711 1712 /* 1713 * ... may need additional spi_device chip config data here. 1714 * avoid stuff protocol drivers can set; but include stuff 1715 * needed to behave without being bound to a driver: 1716 * - quirks like clock rate mattering when not selected 1717 */ 1718 }; 1719 1720 #ifdef CONFIG_SPI 1721 extern int 1722 spi_register_board_info(struct spi_board_info const *info, unsigned n); 1723 #else 1724 /* Board init code may ignore whether SPI is configured or not */ 1725 static inline int 1726 spi_register_board_info(struct spi_board_info const *info, unsigned n) 1727 { return 0; } 1728 #endif 1729 1730 /* 1731 * If you're hotplugging an adapter with devices (parport, USB, etc) 1732 * use spi_new_device() to describe each device. You can also call 1733 * spi_unregister_device() to start making that device vanish, but 1734 * normally that would be handled by spi_unregister_controller(). 1735 * 1736 * You can also use spi_alloc_device() and spi_add_device() to use a two 1737 * stage registration sequence for each spi_device. This gives the caller 1738 * some more control over the spi_device structure before it is registered, 1739 * but requires that caller to initialize fields that would otherwise 1740 * be defined using the board info. 1741 */ 1742 extern struct spi_device * 1743 spi_alloc_device(struct spi_controller *ctlr); 1744 1745 extern int 1746 spi_add_device(struct spi_device *spi); 1747 1748 extern struct spi_device * 1749 spi_new_device(struct spi_controller *, struct spi_board_info *); 1750 1751 extern void spi_unregister_device(struct spi_device *spi); 1752 1753 extern const struct spi_device_id * 1754 spi_get_device_id(const struct spi_device *sdev); 1755 1756 extern const void * 1757 spi_get_device_match_data(const struct spi_device *sdev); 1758 1759 static inline bool 1760 spi_transfer_is_last(struct spi_controller *ctlr, struct spi_transfer *xfer) 1761 { 1762 return list_is_last(&xfer->transfer_list, &ctlr->cur_msg->transfers); 1763 } 1764 1765 #endif /* __LINUX_SPI_H */ 1766