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