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