]>
Commit | Line | Data |
---|---|---|
8ae12a0d DB |
1 | /* |
2 | * Copyright (C) 2005 David Brownell | |
3 | * | |
4 | * This program is free software; you can redistribute it and/or modify | |
5 | * it under the terms of the GNU General Public License as published by | |
6 | * the Free Software Foundation; either version 2 of the License, or | |
7 | * (at your option) any later version. | |
8 | * | |
9 | * This program is distributed in the hope that it will be useful, | |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 | * GNU General Public License for more details. | |
8ae12a0d DB |
13 | */ |
14 | ||
15 | #ifndef __LINUX_SPI_H | |
16 | #define __LINUX_SPI_H | |
17 | ||
0a30c5ce | 18 | #include <linux/device.h> |
75368bf6 | 19 | #include <linux/mod_devicetable.h> |
5a0e3ad6 | 20 | #include <linux/slab.h> |
ffbbdd21 | 21 | #include <linux/kthread.h> |
b158935f | 22 | #include <linux/completion.h> |
6ad45a27 | 23 | #include <linux/scatterlist.h> |
0a30c5ce | 24 | |
99adef31 | 25 | struct dma_chan; |
eca2ebc7 MS |
26 | struct spi_master; |
27 | struct spi_transfer; | |
0a30c5ce | 28 | |
8ae12a0d | 29 | /* |
b885244e | 30 | * INTERFACES between SPI master-side drivers and SPI infrastructure. |
8ae12a0d | 31 | * (There's no SPI slave support for Linux yet...) |
8ae12a0d DB |
32 | */ |
33 | extern struct bus_type spi_bus_type; | |
34 | ||
eca2ebc7 MS |
35 | /** |
36 | * struct spi_statistics - statistics for spi transfers | |
0243ed44 | 37 | * @lock: lock protecting this structure |
eca2ebc7 MS |
38 | * |
39 | * @messages: number of spi-messages handled | |
40 | * @transfers: number of spi_transfers handled | |
41 | * @errors: number of errors during spi_transfer | |
42 | * @timedout: number of timeouts during spi_transfer | |
43 | * | |
44 | * @spi_sync: number of times spi_sync is used | |
45 | * @spi_sync_immediate: | |
46 | * number of times spi_sync is executed immediately | |
47 | * in calling context without queuing and scheduling | |
48 | * @spi_async: number of times spi_async is used | |
49 | * | |
50 | * @bytes: number of bytes transferred to/from device | |
51 | * @bytes_tx: number of bytes sent to device | |
52 | * @bytes_rx: number of bytes received from device | |
53 | * | |
6b7bc061 MS |
54 | * @transfer_bytes_histo: |
55 | * transfer bytes histogramm | |
eca2ebc7 MS |
56 | */ |
57 | struct spi_statistics { | |
58 | spinlock_t lock; /* lock for the whole structure */ | |
59 | ||
60 | unsigned long messages; | |
61 | unsigned long transfers; | |
62 | unsigned long errors; | |
63 | unsigned long timedout; | |
64 | ||
65 | unsigned long spi_sync; | |
66 | unsigned long spi_sync_immediate; | |
67 | unsigned long spi_async; | |
68 | ||
69 | unsigned long long bytes; | |
70 | unsigned long long bytes_rx; | |
71 | unsigned long long bytes_tx; | |
72 | ||
6b7bc061 MS |
73 | #define SPI_STATISTICS_HISTO_SIZE 17 |
74 | unsigned long transfer_bytes_histo[SPI_STATISTICS_HISTO_SIZE]; | |
eca2ebc7 MS |
75 | }; |
76 | ||
77 | void spi_statistics_add_transfer_stats(struct spi_statistics *stats, | |
78 | struct spi_transfer *xfer, | |
79 | struct spi_master *master); | |
80 | ||
81 | #define SPI_STATISTICS_ADD_TO_FIELD(stats, field, count) \ | |
82 | do { \ | |
83 | unsigned long flags; \ | |
84 | spin_lock_irqsave(&(stats)->lock, flags); \ | |
85 | (stats)->field += count; \ | |
86 | spin_unlock_irqrestore(&(stats)->lock, flags); \ | |
87 | } while (0) | |
88 | ||
89 | #define SPI_STATISTICS_INCREMENT_FIELD(stats, field) \ | |
90 | SPI_STATISTICS_ADD_TO_FIELD(stats, field, 1) | |
91 | ||
8ae12a0d DB |
92 | /** |
93 | * struct spi_device - Master side proxy for an SPI slave device | |
94 | * @dev: Driver model representation of the device. | |
95 | * @master: SPI controller used with the device. | |
96 | * @max_speed_hz: Maximum clock rate to be used with this chip | |
97 | * (on this board); may be changed by the device's driver. | |
4cff33f9 | 98 | * The spi_transfer.speed_hz can override this for each transfer. |
33e34dc6 | 99 | * @chip_select: Chipselect, distinguishing chips handled by @master. |
8ae12a0d DB |
100 | * @mode: The spi mode defines how data is clocked out and in. |
101 | * This may be changed by the device's driver. | |
33e34dc6 DB |
102 | * The "active low" default for chipselect mode can be overridden |
103 | * (by specifying SPI_CS_HIGH) as can the "MSB first" default for | |
104 | * each word in a transfer (by specifying SPI_LSB_FIRST). | |
8ae12a0d | 105 | * @bits_per_word: Data transfers involve one or more words; word sizes |
747d844e | 106 | * like eight or 12 bits are common. In-memory wordsizes are |
8ae12a0d | 107 | * powers of two bytes (e.g. 20 bit samples use 32 bits). |
ccf77cc4 DB |
108 | * This may be changed by the device's driver, or left at the |
109 | * default (0) indicating protocol words are eight bit bytes. | |
4cff33f9 | 110 | * The spi_transfer.bits_per_word can override this for each transfer. |
8ae12a0d | 111 | * @irq: Negative, or the number passed to request_irq() to receive |
747d844e | 112 | * interrupts from this device. |
8ae12a0d | 113 | * @controller_state: Controller's runtime state |
b885244e | 114 | * @controller_data: Board-specific definitions for controller, such as |
747d844e | 115 | * FIFO initialization parameters; from board_info.controller_data |
33e34dc6 DB |
116 | * @modalias: Name of the driver to use with this device, or an alias |
117 | * for that name. This appears in the sysfs "modalias" attribute | |
118 | * for driver coldplugging, and in uevents used for hotplugging | |
446411e1 | 119 | * @cs_gpio: gpio number of the chipselect line (optional, -ENOENT when |
095c3752 | 120 | * when not using a GPIO line) |
8ae12a0d | 121 | * |
eca2ebc7 MS |
122 | * @statistics: statistics for the spi_device |
123 | * | |
33e34dc6 | 124 | * A @spi_device is used to interchange data between an SPI slave |
8ae12a0d DB |
125 | * (usually a discrete chip) and CPU memory. |
126 | * | |
33e34dc6 | 127 | * In @dev, the platform_data is used to hold information about this |
8ae12a0d DB |
128 | * device that's meaningful to the device's protocol driver, but not |
129 | * to its controller. One example might be an identifier for a chip | |
33e34dc6 DB |
130 | * variant with slightly different functionality; another might be |
131 | * information about how this particular board wires the chip's pins. | |
8ae12a0d DB |
132 | */ |
133 | struct spi_device { | |
134 | struct device dev; | |
135 | struct spi_master *master; | |
136 | u32 max_speed_hz; | |
137 | u8 chip_select; | |
89c1f607 | 138 | u8 bits_per_word; |
f477b7fb | 139 | u16 mode; |
b885244e DB |
140 | #define SPI_CPHA 0x01 /* clock phase */ |
141 | #define SPI_CPOL 0x02 /* clock polarity */ | |
0c868461 DB |
142 | #define SPI_MODE_0 (0|0) /* (original MicroWire) */ |
143 | #define SPI_MODE_1 (0|SPI_CPHA) | |
8ae12a0d DB |
144 | #define SPI_MODE_2 (SPI_CPOL|0) |
145 | #define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) | |
b885244e | 146 | #define SPI_CS_HIGH 0x04 /* chipselect active high? */ |
ccf77cc4 | 147 | #define SPI_LSB_FIRST 0x08 /* per-word bits-on-wire */ |
c06e677a | 148 | #define SPI_3WIRE 0x10 /* SI/SO signals shared */ |
4ef7af50 | 149 | #define SPI_LOOP 0x20 /* loopback mode */ |
b55f627f DB |
150 | #define SPI_NO_CS 0x40 /* 1 dev/bus, no chipselect */ |
151 | #define SPI_READY 0x80 /* slave pulls low to pause */ | |
f477b7fb | 152 | #define SPI_TX_DUAL 0x100 /* transmit with 2 wires */ |
153 | #define SPI_TX_QUAD 0x200 /* transmit with 4 wires */ | |
154 | #define SPI_RX_DUAL 0x400 /* receive with 2 wires */ | |
155 | #define SPI_RX_QUAD 0x800 /* receive with 4 wires */ | |
8ae12a0d DB |
156 | int irq; |
157 | void *controller_state; | |
b885244e | 158 | void *controller_data; |
75368bf6 | 159 | char modalias[SPI_NAME_SIZE]; |
74317984 | 160 | int cs_gpio; /* chip select gpio */ |
8ae12a0d | 161 | |
eca2ebc7 MS |
162 | /* the statistics */ |
163 | struct spi_statistics statistics; | |
164 | ||
33e34dc6 DB |
165 | /* |
166 | * likely need more hooks for more protocol options affecting how | |
167 | * the controller talks to each chip, like: | |
168 | * - memory packing (12 bit samples into low bits, others zeroed) | |
169 | * - priority | |
170 | * - drop chipselect after each word | |
171 | * - chipselect delays | |
172 | * - ... | |
173 | */ | |
8ae12a0d DB |
174 | }; |
175 | ||
176 | static inline struct spi_device *to_spi_device(struct device *dev) | |
177 | { | |
b885244e | 178 | return dev ? container_of(dev, struct spi_device, dev) : NULL; |
8ae12a0d DB |
179 | } |
180 | ||
181 | /* most drivers won't need to care about device refcounting */ | |
182 | static inline struct spi_device *spi_dev_get(struct spi_device *spi) | |
183 | { | |
184 | return (spi && get_device(&spi->dev)) ? spi : NULL; | |
185 | } | |
186 | ||
187 | static inline void spi_dev_put(struct spi_device *spi) | |
188 | { | |
189 | if (spi) | |
190 | put_device(&spi->dev); | |
191 | } | |
192 | ||
193 | /* ctldata is for the bus_master driver's runtime state */ | |
194 | static inline void *spi_get_ctldata(struct spi_device *spi) | |
195 | { | |
196 | return spi->controller_state; | |
197 | } | |
198 | ||
199 | static inline void spi_set_ctldata(struct spi_device *spi, void *state) | |
200 | { | |
201 | spi->controller_state = state; | |
202 | } | |
203 | ||
9b40ff4d BD |
204 | /* device driver data */ |
205 | ||
206 | static inline void spi_set_drvdata(struct spi_device *spi, void *data) | |
207 | { | |
208 | dev_set_drvdata(&spi->dev, data); | |
209 | } | |
210 | ||
211 | static inline void *spi_get_drvdata(struct spi_device *spi) | |
212 | { | |
213 | return dev_get_drvdata(&spi->dev); | |
214 | } | |
8ae12a0d DB |
215 | |
216 | struct spi_message; | |
b158935f | 217 | struct spi_transfer; |
b885244e | 218 | |
2604288f DB |
219 | /** |
220 | * struct spi_driver - Host side "protocol" driver | |
75368bf6 | 221 | * @id_table: List of SPI devices supported by this driver |
2604288f DB |
222 | * @probe: Binds this driver to the spi device. Drivers can verify |
223 | * that the device is actually present, and may need to configure | |
224 | * characteristics (such as bits_per_word) which weren't needed for | |
225 | * the initial configuration done during system setup. | |
226 | * @remove: Unbinds this driver from the spi device | |
227 | * @shutdown: Standard shutdown callback used during system state | |
228 | * transitions such as powerdown/halt and kexec | |
2604288f DB |
229 | * @driver: SPI device drivers should initialize the name and owner |
230 | * field of this structure. | |
231 | * | |
232 | * This represents the kind of device driver that uses SPI messages to | |
233 | * interact with the hardware at the other end of a SPI link. It's called | |
234 | * a "protocol" driver because it works through messages rather than talking | |
235 | * directly to SPI hardware (which is what the underlying SPI controller | |
236 | * driver does to pass those messages). These protocols are defined in the | |
237 | * specification for the device(s) supported by the driver. | |
238 | * | |
239 | * As a rule, those device protocols represent the lowest level interface | |
240 | * supported by a driver, and it will support upper level interfaces too. | |
241 | * Examples of such upper levels include frameworks like MTD, networking, | |
242 | * MMC, RTC, filesystem character device nodes, and hardware monitoring. | |
243 | */ | |
b885244e | 244 | struct spi_driver { |
75368bf6 | 245 | const struct spi_device_id *id_table; |
b885244e DB |
246 | int (*probe)(struct spi_device *spi); |
247 | int (*remove)(struct spi_device *spi); | |
248 | void (*shutdown)(struct spi_device *spi); | |
b885244e DB |
249 | struct device_driver driver; |
250 | }; | |
251 | ||
252 | static inline struct spi_driver *to_spi_driver(struct device_driver *drv) | |
253 | { | |
254 | return drv ? container_of(drv, struct spi_driver, driver) : NULL; | |
255 | } | |
256 | ||
ca5d2485 | 257 | extern int __spi_register_driver(struct module *owner, struct spi_driver *sdrv); |
b885244e | 258 | |
33e34dc6 DB |
259 | /** |
260 | * spi_unregister_driver - reverse effect of spi_register_driver | |
261 | * @sdrv: the driver to unregister | |
262 | * Context: can sleep | |
263 | */ | |
b885244e DB |
264 | static inline void spi_unregister_driver(struct spi_driver *sdrv) |
265 | { | |
ddc1e975 BD |
266 | if (sdrv) |
267 | driver_unregister(&sdrv->driver); | |
b885244e DB |
268 | } |
269 | ||
ca5d2485 AD |
270 | /* use a define to avoid include chaining to get THIS_MODULE */ |
271 | #define spi_register_driver(driver) \ | |
272 | __spi_register_driver(THIS_MODULE, driver) | |
273 | ||
3acbb014 LPC |
274 | /** |
275 | * module_spi_driver() - Helper macro for registering a SPI driver | |
276 | * @__spi_driver: spi_driver struct | |
277 | * | |
278 | * Helper macro for SPI drivers which do not do anything special in module | |
279 | * init/exit. This eliminates a lot of boilerplate. Each module may only | |
280 | * use this macro once, and calling it replaces module_init() and module_exit() | |
281 | */ | |
282 | #define module_spi_driver(__spi_driver) \ | |
283 | module_driver(__spi_driver, spi_register_driver, \ | |
284 | spi_unregister_driver) | |
b885244e | 285 | |
8ae12a0d DB |
286 | /** |
287 | * struct spi_master - interface to SPI master controller | |
49dce689 | 288 | * @dev: device interface to this driver |
2b9603a0 | 289 | * @list: link with the global spi_master list |
8ae12a0d | 290 | * @bus_num: board-specific (and often SOC-specific) identifier for a |
747d844e | 291 | * given SPI controller. |
b885244e | 292 | * @num_chipselect: chipselects are used to distinguish individual |
747d844e DB |
293 | * SPI slaves, and are numbered from zero to num_chipselects. |
294 | * each slave has a chipselect signal, but it's common that not | |
295 | * every chipselect is connected to a slave. | |
fd5e191e | 296 | * @dma_alignment: SPI controller constraint on DMA buffers alignment. |
b73b2559 | 297 | * @mode_bits: flags understood by this controller driver |
543bb255 SW |
298 | * @bits_per_word_mask: A mask indicating which values of bits_per_word are |
299 | * supported by the driver. Bit n indicates that a bits_per_word n+1 is | |
e227867f | 300 | * supported. If set, the SPI core will reject any transfer with an |
543bb255 SW |
301 | * unsupported bits_per_word. If not set, this value is simply ignored, |
302 | * and it's up to the individual driver to perform any validation. | |
a2fd4f9f MB |
303 | * @min_speed_hz: Lowest supported transfer speed |
304 | * @max_speed_hz: Highest supported transfer speed | |
b73b2559 | 305 | * @flags: other constraints relevant to this driver |
5c79a5ae ES |
306 | * @bus_lock_spinlock: spinlock for SPI bus locking |
307 | * @bus_lock_mutex: mutex for SPI bus locking | |
308 | * @bus_lock_flag: indicates that the SPI bus is locked for exclusive use | |
8ae12a0d | 309 | * @setup: updates the device mode and clocking records used by a |
80224561 DB |
310 | * device's SPI controller; protocol code may call this. This |
311 | * must fail if an unrecognized or unsupported mode is requested. | |
33e34dc6 DB |
312 | * It's always safe to call this unless transfers are pending on |
313 | * the device whose settings are being modified. | |
8ae12a0d DB |
314 | * @transfer: adds a message to the controller's transfer queue. |
315 | * @cleanup: frees controller-specific state | |
2c675689 | 316 | * @can_dma: determine whether this master supports DMA |
ffbbdd21 LW |
317 | * @queued: whether this master is providing an internal message queue |
318 | * @kworker: thread struct for message pump | |
319 | * @kworker_task: pointer to task for message pump kworker thread | |
320 | * @pump_messages: work struct for scheduling work to the message pump | |
321 | * @queue_lock: spinlock to syncronise access to message queue | |
322 | * @queue: message queue | |
0461a414 | 323 | * @idling: the device is entering idle state |
ffbbdd21 | 324 | * @cur_msg: the currently in-flight message |
2841a5fc MB |
325 | * @cur_msg_prepared: spi_prepare_message was called for the currently |
326 | * in-flight message | |
2c675689 | 327 | * @cur_msg_mapped: message has been mapped for DMA |
e227867f | 328 | * @xfer_completion: used by core transfer_one_message() |
ffbbdd21 LW |
329 | * @busy: message pump is busy |
330 | * @running: message pump is running | |
331 | * @rt: whether this queue is set to run as a realtime task | |
49834de2 MB |
332 | * @auto_runtime_pm: the core should ensure a runtime PM reference is held |
333 | * while the hardware is prepared, using the parent | |
334 | * device for the spidev | |
6ad45a27 | 335 | * @max_dma_len: Maximum length of a DMA transfer for the device. |
ffbbdd21 LW |
336 | * @prepare_transfer_hardware: a message will soon arrive from the queue |
337 | * so the subsystem requests the driver to prepare the transfer hardware | |
338 | * by issuing this call | |
339 | * @transfer_one_message: the subsystem calls the driver to transfer a single | |
340 | * message while queuing transfers that arrive in the meantime. When the | |
341 | * driver is finished with this message, it must call | |
342 | * spi_finalize_current_message() so the subsystem can issue the next | |
e9305331 | 343 | * message |
dbabe0d6 | 344 | * @unprepare_transfer_hardware: there are currently no more messages on the |
ffbbdd21 LW |
345 | * queue so the subsystem notifies the driver that it may relax the |
346 | * hardware by issuing this call | |
bd6857a0 | 347 | * @set_cs: set the logic level of the chip select line. May be called |
b158935f | 348 | * from interrupt context. |
2841a5fc MB |
349 | * @prepare_message: set up the controller to transfer a single message, |
350 | * for example doing DMA mapping. Called from threaded | |
351 | * context. | |
0516712c GU |
352 | * @transfer_one: transfer a single spi_transfer. |
353 | * - return 0 if the transfer is finished, | |
354 | * - return 1 if the transfer is still in progress. When | |
355 | * the driver is finished with this transfer it must | |
356 | * call spi_finalize_current_transfer() so the subsystem | |
6e5f5267 BS |
357 | * can issue the next transfer. Note: transfer_one and |
358 | * transfer_one_message are mutually exclusive; when both | |
359 | * are set, the generic subsystem does not call your | |
360 | * transfer_one callback. | |
ff61eb42 | 361 | * @handle_err: the subsystem calls the driver to handle an error that occurs |
b716c4ff | 362 | * in the generic implementation of transfer_one_message(). |
2841a5fc | 363 | * @unprepare_message: undo any work done by prepare_message(). |
095c3752 | 364 | * @cs_gpios: Array of GPIOs to use as chip select lines; one per CS |
446411e1 | 365 | * number. Any individual value may be -ENOENT for CS lines that |
095c3752 | 366 | * are not GPIOs (driven by the SPI controller itself). |
eca2ebc7 | 367 | * @statistics: statistics for the spi_master |
2c675689 TR |
368 | * @dma_tx: DMA transmit channel |
369 | * @dma_rx: DMA receive channel | |
370 | * @dummy_rx: dummy receive buffer for full-duplex devices | |
371 | * @dummy_tx: dummy transmit buffer for full-duplex devices | |
8ae12a0d | 372 | * |
33e34dc6 | 373 | * Each SPI master controller can communicate with one or more @spi_device |
8ae12a0d DB |
374 | * children. These make a small bus, sharing MOSI, MISO and SCK signals |
375 | * but not chip select signals. Each device may be configured to use a | |
376 | * different clock rate, since those shared signals are ignored unless | |
377 | * the chip is selected. | |
378 | * | |
379 | * The driver for an SPI controller manages access to those devices through | |
33e34dc6 DB |
380 | * a queue of spi_message transactions, copying data between CPU memory and |
381 | * an SPI slave device. For each such message it queues, it calls the | |
8ae12a0d DB |
382 | * message's completion function when the transaction completes. |
383 | */ | |
384 | struct spi_master { | |
49dce689 | 385 | struct device dev; |
8ae12a0d | 386 | |
2b9603a0 FT |
387 | struct list_head list; |
388 | ||
a020ed75 | 389 | /* other than negative (== assign one dynamically), bus_num is fully |
8ae12a0d | 390 | * board-specific. usually that simplifies to being SOC-specific. |
a020ed75 | 391 | * example: one SOC has three SPI controllers, numbered 0..2, |
8ae12a0d DB |
392 | * and one board's schematics might show it using SPI-2. software |
393 | * would normally use bus_num=2 for that controller. | |
394 | */ | |
a020ed75 | 395 | s16 bus_num; |
8ae12a0d DB |
396 | |
397 | /* chipselects will be integral to many controllers; some others | |
398 | * might use board-specific GPIOs. | |
399 | */ | |
400 | u16 num_chipselect; | |
401 | ||
fd5e191e MR |
402 | /* some SPI controllers pose alignment requirements on DMAable |
403 | * buffers; let protocol drivers know about these requirements. | |
404 | */ | |
405 | u16 dma_alignment; | |
406 | ||
e7db06b5 DB |
407 | /* spi_device.mode flags understood by this controller driver */ |
408 | u16 mode_bits; | |
409 | ||
543bb255 SW |
410 | /* bitmask of supported bits_per_word for transfers */ |
411 | u32 bits_per_word_mask; | |
2922a8de | 412 | #define SPI_BPW_MASK(bits) BIT((bits) - 1) |
b6aa23cc | 413 | #define SPI_BIT_MASK(bits) (((bits) == 32) ? ~0U : (BIT(bits) - 1)) |
eca8960a | 414 | #define SPI_BPW_RANGE_MASK(min, max) (SPI_BIT_MASK(max) - SPI_BIT_MASK(min - 1)) |
543bb255 | 415 | |
a2fd4f9f MB |
416 | /* limits on transfer speed */ |
417 | u32 min_speed_hz; | |
418 | u32 max_speed_hz; | |
419 | ||
70d6027f DB |
420 | /* other constraints relevant to this driver */ |
421 | u16 flags; | |
422 | #define SPI_MASTER_HALF_DUPLEX BIT(0) /* can't do full duplex */ | |
568d0697 DB |
423 | #define SPI_MASTER_NO_RX BIT(1) /* can't do buffer read */ |
424 | #define SPI_MASTER_NO_TX BIT(2) /* can't do buffer write */ | |
3a2eba9b MB |
425 | #define SPI_MASTER_MUST_RX BIT(3) /* requires rx */ |
426 | #define SPI_MASTER_MUST_TX BIT(4) /* requires tx */ | |
70d6027f | 427 | |
4acad4aa MS |
428 | /* |
429 | * on some hardware transfer size may be constrained | |
430 | * the limit may depend on device transfer settings | |
431 | */ | |
432 | size_t (*max_transfer_size)(struct spi_device *spi); | |
433 | ||
cf32b71e ES |
434 | /* lock and mutex for SPI bus locking */ |
435 | spinlock_t bus_lock_spinlock; | |
436 | struct mutex bus_lock_mutex; | |
437 | ||
438 | /* flag indicating that the SPI bus is locked for exclusive use */ | |
439 | bool bus_lock_flag; | |
440 | ||
6e538aaf DB |
441 | /* Setup mode and clock, etc (spi driver may call many times). |
442 | * | |
443 | * IMPORTANT: this may be called when transfers to another | |
444 | * device are active. DO NOT UPDATE SHARED REGISTERS in ways | |
445 | * which could break those transfers. | |
446 | */ | |
8ae12a0d DB |
447 | int (*setup)(struct spi_device *spi); |
448 | ||
449 | /* bidirectional bulk transfers | |
450 | * | |
451 | * + The transfer() method may not sleep; its main role is | |
452 | * just to add the message to the queue. | |
453 | * + For now there's no remove-from-queue operation, or | |
454 | * any other request management | |
455 | * + To a given spi_device, message queueing is pure fifo | |
456 | * | |
457 | * + The master's main job is to process its message queue, | |
458 | * selecting a chip then transferring data | |
459 | * + If there are multiple spi_device children, the i/o queue | |
460 | * arbitration algorithm is unspecified (round robin, fifo, | |
461 | * priority, reservations, preemption, etc) | |
462 | * | |
463 | * + Chipselect stays active during the entire message | |
464 | * (unless modified by spi_transfer.cs_change != 0). | |
465 | * + The message transfers use clock and SPI mode parameters | |
466 | * previously established by setup() for this device | |
467 | */ | |
468 | int (*transfer)(struct spi_device *spi, | |
469 | struct spi_message *mesg); | |
470 | ||
471 | /* called on release() to free memory provided by spi_master */ | |
0ffa0285 | 472 | void (*cleanup)(struct spi_device *spi); |
ffbbdd21 | 473 | |
99adef31 MB |
474 | /* |
475 | * Used to enable core support for DMA handling, if can_dma() | |
476 | * exists and returns true then the transfer will be mapped | |
477 | * prior to transfer_one() being called. The driver should | |
478 | * not modify or store xfer and dma_tx and dma_rx must be set | |
479 | * while the device is prepared. | |
480 | */ | |
481 | bool (*can_dma)(struct spi_master *master, | |
482 | struct spi_device *spi, | |
483 | struct spi_transfer *xfer); | |
484 | ||
ffbbdd21 LW |
485 | /* |
486 | * These hooks are for drivers that want to use the generic | |
487 | * master transfer queueing mechanism. If these are used, the | |
488 | * transfer() function above must NOT be specified by the driver. | |
489 | * Over time we expect SPI drivers to be phased over to this API. | |
490 | */ | |
491 | bool queued; | |
492 | struct kthread_worker kworker; | |
493 | struct task_struct *kworker_task; | |
494 | struct kthread_work pump_messages; | |
495 | spinlock_t queue_lock; | |
496 | struct list_head queue; | |
497 | struct spi_message *cur_msg; | |
0461a414 | 498 | bool idling; |
ffbbdd21 LW |
499 | bool busy; |
500 | bool running; | |
501 | bool rt; | |
49834de2 | 502 | bool auto_runtime_pm; |
2841a5fc | 503 | bool cur_msg_prepared; |
99adef31 | 504 | bool cur_msg_mapped; |
b158935f | 505 | struct completion xfer_completion; |
6ad45a27 | 506 | size_t max_dma_len; |
ffbbdd21 LW |
507 | |
508 | int (*prepare_transfer_hardware)(struct spi_master *master); | |
509 | int (*transfer_one_message)(struct spi_master *master, | |
510 | struct spi_message *mesg); | |
511 | int (*unprepare_transfer_hardware)(struct spi_master *master); | |
2841a5fc MB |
512 | int (*prepare_message)(struct spi_master *master, |
513 | struct spi_message *message); | |
514 | int (*unprepare_message)(struct spi_master *master, | |
515 | struct spi_message *message); | |
49834de2 | 516 | |
b158935f MB |
517 | /* |
518 | * These hooks are for drivers that use a generic implementation | |
519 | * of transfer_one_message() provied by the core. | |
520 | */ | |
521 | void (*set_cs)(struct spi_device *spi, bool enable); | |
522 | int (*transfer_one)(struct spi_master *master, struct spi_device *spi, | |
523 | struct spi_transfer *transfer); | |
b716c4ff AS |
524 | void (*handle_err)(struct spi_master *master, |
525 | struct spi_message *message); | |
b158935f | 526 | |
74317984 JCPV |
527 | /* gpio chip select */ |
528 | int *cs_gpios; | |
99adef31 | 529 | |
eca2ebc7 MS |
530 | /* statistics */ |
531 | struct spi_statistics statistics; | |
532 | ||
99adef31 MB |
533 | /* DMA channels for use with core dmaengine helpers */ |
534 | struct dma_chan *dma_tx; | |
535 | struct dma_chan *dma_rx; | |
3a2eba9b MB |
536 | |
537 | /* dummy data for full duplex devices */ | |
538 | void *dummy_rx; | |
539 | void *dummy_tx; | |
8ae12a0d DB |
540 | }; |
541 | ||
0c868461 DB |
542 | static inline void *spi_master_get_devdata(struct spi_master *master) |
543 | { | |
49dce689 | 544 | return dev_get_drvdata(&master->dev); |
0c868461 DB |
545 | } |
546 | ||
547 | static inline void spi_master_set_devdata(struct spi_master *master, void *data) | |
548 | { | |
49dce689 | 549 | dev_set_drvdata(&master->dev, data); |
0c868461 DB |
550 | } |
551 | ||
552 | static inline struct spi_master *spi_master_get(struct spi_master *master) | |
553 | { | |
49dce689 | 554 | if (!master || !get_device(&master->dev)) |
0c868461 DB |
555 | return NULL; |
556 | return master; | |
557 | } | |
558 | ||
559 | static inline void spi_master_put(struct spi_master *master) | |
560 | { | |
561 | if (master) | |
49dce689 | 562 | put_device(&master->dev); |
0c868461 DB |
563 | } |
564 | ||
ffbbdd21 LW |
565 | /* PM calls that need to be issued by the driver */ |
566 | extern int spi_master_suspend(struct spi_master *master); | |
567 | extern int spi_master_resume(struct spi_master *master); | |
568 | ||
569 | /* Calls the driver make to interact with the message queue */ | |
570 | extern struct spi_message *spi_get_next_queued_message(struct spi_master *master); | |
571 | extern void spi_finalize_current_message(struct spi_master *master); | |
b158935f | 572 | extern void spi_finalize_current_transfer(struct spi_master *master); |
0c868461 | 573 | |
8ae12a0d DB |
574 | /* the spi driver core manages memory for the spi_master classdev */ |
575 | extern struct spi_master * | |
576 | spi_alloc_master(struct device *host, unsigned size); | |
577 | ||
578 | extern int spi_register_master(struct spi_master *master); | |
666d5b4c MB |
579 | extern int devm_spi_register_master(struct device *dev, |
580 | struct spi_master *master); | |
8ae12a0d DB |
581 | extern void spi_unregister_master(struct spi_master *master); |
582 | ||
583 | extern struct spi_master *spi_busnum_to_master(u16 busnum); | |
584 | ||
585 | /*---------------------------------------------------------------------------*/ | |
586 | ||
587 | /* | |
588 | * I/O INTERFACE between SPI controller and protocol drivers | |
589 | * | |
590 | * Protocol drivers use a queue of spi_messages, each transferring data | |
591 | * between the controller and memory buffers. | |
592 | * | |
593 | * The spi_messages themselves consist of a series of read+write transfer | |
594 | * segments. Those segments always read the same number of bits as they | |
595 | * write; but one or the other is easily ignored by passing a null buffer | |
596 | * pointer. (This is unlike most types of I/O API, because SPI hardware | |
597 | * is full duplex.) | |
598 | * | |
599 | * NOTE: Allocation of spi_transfer and spi_message memory is entirely | |
600 | * up to the protocol driver, which guarantees the integrity of both (as | |
601 | * well as the data buffers) for as long as the message is queued. | |
602 | */ | |
603 | ||
604 | /** | |
605 | * struct spi_transfer - a read/write buffer pair | |
8275c642 VW |
606 | * @tx_buf: data to be written (dma-safe memory), or NULL |
607 | * @rx_buf: data to be read (dma-safe memory), or NULL | |
33e34dc6 DB |
608 | * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped |
609 | * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped | |
e227867f | 610 | * @tx_nbits: number of bits used for writing. If 0 the default |
f477b7fb | 611 | * (SPI_NBITS_SINGLE) is used. |
612 | * @rx_nbits: number of bits used for reading. If 0 the default | |
613 | * (SPI_NBITS_SINGLE) is used. | |
8ae12a0d | 614 | * @len: size of rx and tx buffers (in bytes) |
025dfdaf | 615 | * @speed_hz: Select a speed other than the device default for this |
33e34dc6 | 616 | * transfer. If 0 the default (from @spi_device) is used. |
025dfdaf | 617 | * @bits_per_word: select a bits_per_word other than the device default |
33e34dc6 | 618 | * for this transfer. If 0 the default (from @spi_device) is used. |
8ae12a0d DB |
619 | * @cs_change: affects chipselect after this transfer completes |
620 | * @delay_usecs: microseconds to delay after this transfer before | |
747d844e | 621 | * (optionally) changing the chipselect status, then starting |
33e34dc6 DB |
622 | * the next transfer or completing this @spi_message. |
623 | * @transfer_list: transfers are sequenced through @spi_message.transfers | |
6ad45a27 MB |
624 | * @tx_sg: Scatterlist for transmit, currently not for client use |
625 | * @rx_sg: Scatterlist for receive, currently not for client use | |
8ae12a0d DB |
626 | * |
627 | * SPI transfers always write the same number of bytes as they read. | |
33e34dc6 | 628 | * Protocol drivers should always provide @rx_buf and/or @tx_buf. |
8ae12a0d DB |
629 | * In some cases, they may also want to provide DMA addresses for |
630 | * the data being transferred; that may reduce overhead, when the | |
631 | * underlying driver uses dma. | |
632 | * | |
4b1badf5 | 633 | * If the transmit buffer is null, zeroes will be shifted out |
33e34dc6 | 634 | * while filling @rx_buf. If the receive buffer is null, the data |
8275c642 VW |
635 | * shifted in will be discarded. Only "len" bytes shift out (or in). |
636 | * It's an error to try to shift out a partial word. (For example, by | |
637 | * shifting out three bytes with word size of sixteen or twenty bits; | |
638 | * the former uses two bytes per word, the latter uses four bytes.) | |
639 | * | |
80224561 DB |
640 | * In-memory data values are always in native CPU byte order, translated |
641 | * from the wire byte order (big-endian except with SPI_LSB_FIRST). So | |
642 | * for example when bits_per_word is sixteen, buffers are 2N bytes long | |
33e34dc6 | 643 | * (@len = 2N) and hold N sixteen bit words in CPU byte order. |
80224561 DB |
644 | * |
645 | * When the word size of the SPI transfer is not a power-of-two multiple | |
646 | * of eight bits, those in-memory words include extra bits. In-memory | |
647 | * words are always seen by protocol drivers as right-justified, so the | |
648 | * undefined (rx) or unused (tx) bits are always the most significant bits. | |
649 | * | |
8275c642 VW |
650 | * All SPI transfers start with the relevant chipselect active. Normally |
651 | * it stays selected until after the last transfer in a message. Drivers | |
33e34dc6 | 652 | * can affect the chipselect signal using cs_change. |
8ae12a0d DB |
653 | * |
654 | * (i) If the transfer isn't the last one in the message, this flag is | |
655 | * used to make the chipselect briefly go inactive in the middle of the | |
656 | * message. Toggling chipselect in this way may be needed to terminate | |
657 | * a chip command, letting a single spi_message perform all of group of | |
658 | * chip transactions together. | |
659 | * | |
660 | * (ii) When the transfer is the last one in the message, the chip may | |
f5a9c77d DB |
661 | * stay selected until the next transfer. On multi-device SPI busses |
662 | * with nothing blocking messages going to other devices, this is just | |
663 | * a performance hint; starting a message to another device deselects | |
664 | * this one. But in other cases, this can be used to ensure correctness. | |
665 | * Some devices need protocol transactions to be built from a series of | |
666 | * spi_message submissions, where the content of one message is determined | |
667 | * by the results of previous messages and where the whole transaction | |
668 | * ends when the chipselect goes intactive. | |
0c868461 | 669 | * |
e227867f | 670 | * When SPI can transfer in 1x,2x or 4x. It can get this transfer information |
f477b7fb | 671 | * from device through @tx_nbits and @rx_nbits. In Bi-direction, these |
672 | * two should both be set. User can set transfer mode with SPI_NBITS_SINGLE(1x) | |
673 | * SPI_NBITS_DUAL(2x) and SPI_NBITS_QUAD(4x) to support these three transfer. | |
674 | * | |
0c868461 DB |
675 | * The code that submits an spi_message (and its spi_transfers) |
676 | * to the lower layers is responsible for managing its memory. | |
677 | * Zero-initialize every field you don't set up explicitly, to | |
8275c642 VW |
678 | * insulate against future API updates. After you submit a message |
679 | * and its transfers, ignore them until its completion callback. | |
8ae12a0d DB |
680 | */ |
681 | struct spi_transfer { | |
682 | /* it's ok if tx_buf == rx_buf (right?) | |
683 | * for MicroWire, one buffer must be null | |
0c868461 DB |
684 | * buffers must work with dma_*map_single() calls, unless |
685 | * spi_message.is_dma_mapped reports a pre-existing mapping | |
8ae12a0d DB |
686 | */ |
687 | const void *tx_buf; | |
688 | void *rx_buf; | |
689 | unsigned len; | |
690 | ||
691 | dma_addr_t tx_dma; | |
692 | dma_addr_t rx_dma; | |
6ad45a27 MB |
693 | struct sg_table tx_sg; |
694 | struct sg_table rx_sg; | |
8ae12a0d DB |
695 | |
696 | unsigned cs_change:1; | |
d3fbd457 MB |
697 | unsigned tx_nbits:3; |
698 | unsigned rx_nbits:3; | |
f477b7fb | 699 | #define SPI_NBITS_SINGLE 0x01 /* 1bit transfer */ |
700 | #define SPI_NBITS_DUAL 0x02 /* 2bits transfer */ | |
701 | #define SPI_NBITS_QUAD 0x04 /* 4bits transfer */ | |
4cff33f9 | 702 | u8 bits_per_word; |
8ae12a0d | 703 | u16 delay_usecs; |
4cff33f9 | 704 | u32 speed_hz; |
8275c642 VW |
705 | |
706 | struct list_head transfer_list; | |
8ae12a0d DB |
707 | }; |
708 | ||
709 | /** | |
710 | * struct spi_message - one multi-segment SPI transaction | |
8275c642 | 711 | * @transfers: list of transfer segments in this transaction |
8ae12a0d DB |
712 | * @spi: SPI device to which the transaction is queued |
713 | * @is_dma_mapped: if true, the caller provided both dma and cpu virtual | |
714 | * addresses for each transfer buffer | |
715 | * @complete: called to report transaction completions | |
716 | * @context: the argument to complete() when it's called | |
2c675689 | 717 | * @frame_length: the total number of bytes in the message |
b885244e DB |
718 | * @actual_length: the total number of bytes that were transferred in all |
719 | * successful segments | |
8ae12a0d DB |
720 | * @status: zero for success, else negative errno |
721 | * @queue: for use by whichever driver currently owns the message | |
722 | * @state: for use by whichever driver currently owns the message | |
0c868461 | 723 | * |
33e34dc6 | 724 | * A @spi_message is used to execute an atomic sequence of data transfers, |
8275c642 VW |
725 | * each represented by a struct spi_transfer. The sequence is "atomic" |
726 | * in the sense that no other spi_message may use that SPI bus until that | |
727 | * sequence completes. On some systems, many such sequences can execute as | |
728 | * as single programmed DMA transfer. On all systems, these messages are | |
729 | * queued, and might complete after transactions to other devices. Messages | |
c6331ba3 | 730 | * sent to a given spi_device are always executed in FIFO order. |
8275c642 | 731 | * |
0c868461 DB |
732 | * The code that submits an spi_message (and its spi_transfers) |
733 | * to the lower layers is responsible for managing its memory. | |
734 | * Zero-initialize every field you don't set up explicitly, to | |
8275c642 VW |
735 | * insulate against future API updates. After you submit a message |
736 | * and its transfers, ignore them until its completion callback. | |
8ae12a0d DB |
737 | */ |
738 | struct spi_message { | |
747d844e | 739 | struct list_head transfers; |
8ae12a0d DB |
740 | |
741 | struct spi_device *spi; | |
742 | ||
743 | unsigned is_dma_mapped:1; | |
744 | ||
745 | /* REVISIT: we might want a flag affecting the behavior of the | |
746 | * last transfer ... allowing things like "read 16 bit length L" | |
747 | * immediately followed by "read L bytes". Basically imposing | |
748 | * a specific message scheduling algorithm. | |
749 | * | |
750 | * Some controller drivers (message-at-a-time queue processing) | |
751 | * could provide that as their default scheduling algorithm. But | |
b885244e | 752 | * others (with multi-message pipelines) could need a flag to |
8ae12a0d DB |
753 | * tell them about such special cases. |
754 | */ | |
755 | ||
756 | /* completion is reported through a callback */ | |
747d844e | 757 | void (*complete)(void *context); |
8ae12a0d | 758 | void *context; |
078726ce | 759 | unsigned frame_length; |
8ae12a0d DB |
760 | unsigned actual_length; |
761 | int status; | |
762 | ||
763 | /* for optional use by whatever driver currently owns the | |
764 | * spi_message ... between calls to spi_async and then later | |
765 | * complete(), that's the spi_master controller driver. | |
766 | */ | |
767 | struct list_head queue; | |
768 | void *state; | |
769 | }; | |
770 | ||
8275c642 VW |
771 | static inline void spi_message_init(struct spi_message *m) |
772 | { | |
773 | memset(m, 0, sizeof *m); | |
774 | INIT_LIST_HEAD(&m->transfers); | |
775 | } | |
776 | ||
777 | static inline void | |
778 | spi_message_add_tail(struct spi_transfer *t, struct spi_message *m) | |
779 | { | |
780 | list_add_tail(&t->transfer_list, &m->transfers); | |
781 | } | |
782 | ||
783 | static inline void | |
784 | spi_transfer_del(struct spi_transfer *t) | |
785 | { | |
786 | list_del(&t->transfer_list); | |
787 | } | |
788 | ||
6d9eecd4 LPC |
789 | /** |
790 | * spi_message_init_with_transfers - Initialize spi_message and append transfers | |
791 | * @m: spi_message to be initialized | |
792 | * @xfers: An array of spi transfers | |
793 | * @num_xfers: Number of items in the xfer array | |
794 | * | |
795 | * This function initializes the given spi_message and adds each spi_transfer in | |
796 | * the given array to the message. | |
797 | */ | |
798 | static inline void | |
799 | spi_message_init_with_transfers(struct spi_message *m, | |
800 | struct spi_transfer *xfers, unsigned int num_xfers) | |
801 | { | |
802 | unsigned int i; | |
803 | ||
804 | spi_message_init(m); | |
805 | for (i = 0; i < num_xfers; ++i) | |
806 | spi_message_add_tail(&xfers[i], m); | |
807 | } | |
808 | ||
0c868461 DB |
809 | /* It's fine to embed message and transaction structures in other data |
810 | * structures so long as you don't free them while they're in use. | |
811 | */ | |
812 | ||
813 | static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags) | |
814 | { | |
815 | struct spi_message *m; | |
816 | ||
817 | m = kzalloc(sizeof(struct spi_message) | |
818 | + ntrans * sizeof(struct spi_transfer), | |
819 | flags); | |
820 | if (m) { | |
8f53602b | 821 | unsigned i; |
8275c642 VW |
822 | struct spi_transfer *t = (struct spi_transfer *)(m + 1); |
823 | ||
824 | INIT_LIST_HEAD(&m->transfers); | |
825 | for (i = 0; i < ntrans; i++, t++) | |
826 | spi_message_add_tail(t, m); | |
0c868461 DB |
827 | } |
828 | return m; | |
829 | } | |
830 | ||
831 | static inline void spi_message_free(struct spi_message *m) | |
832 | { | |
833 | kfree(m); | |
834 | } | |
835 | ||
7d077197 | 836 | extern int spi_setup(struct spi_device *spi); |
568d0697 | 837 | extern int spi_async(struct spi_device *spi, struct spi_message *message); |
cf32b71e ES |
838 | extern int spi_async_locked(struct spi_device *spi, |
839 | struct spi_message *message); | |
8ae12a0d | 840 | |
4acad4aa MS |
841 | static inline size_t |
842 | spi_max_transfer_size(struct spi_device *spi) | |
843 | { | |
844 | struct spi_master *master = spi->master; | |
845 | if (!master->max_transfer_size) | |
846 | return SIZE_MAX; | |
847 | return master->max_transfer_size(spi); | |
848 | } | |
849 | ||
8ae12a0d DB |
850 | /*---------------------------------------------------------------------------*/ |
851 | ||
852 | /* All these synchronous SPI transfer routines are utilities layered | |
853 | * over the core async transfer primitive. Here, "synchronous" means | |
854 | * they will sleep uninterruptibly until the async transfer completes. | |
855 | */ | |
856 | ||
857 | extern int spi_sync(struct spi_device *spi, struct spi_message *message); | |
cf32b71e ES |
858 | extern int spi_sync_locked(struct spi_device *spi, struct spi_message *message); |
859 | extern int spi_bus_lock(struct spi_master *master); | |
860 | extern int spi_bus_unlock(struct spi_master *master); | |
8ae12a0d DB |
861 | |
862 | /** | |
863 | * spi_write - SPI synchronous write | |
864 | * @spi: device to which data will be written | |
865 | * @buf: data buffer | |
866 | * @len: data buffer size | |
33e34dc6 | 867 | * Context: can sleep |
8ae12a0d | 868 | * |
a1fdeaa7 | 869 | * This function writes the buffer @buf. |
8ae12a0d | 870 | * Callable only from contexts that can sleep. |
a1fdeaa7 JMC |
871 | * |
872 | * Return: zero on success, else a negative error code. | |
8ae12a0d DB |
873 | */ |
874 | static inline int | |
0c4a1590 | 875 | spi_write(struct spi_device *spi, const void *buf, size_t len) |
8ae12a0d DB |
876 | { |
877 | struct spi_transfer t = { | |
878 | .tx_buf = buf, | |
8ae12a0d | 879 | .len = len, |
8ae12a0d | 880 | }; |
8275c642 | 881 | struct spi_message m; |
8ae12a0d | 882 | |
8275c642 VW |
883 | spi_message_init(&m); |
884 | spi_message_add_tail(&t, &m); | |
8ae12a0d DB |
885 | return spi_sync(spi, &m); |
886 | } | |
887 | ||
888 | /** | |
889 | * spi_read - SPI synchronous read | |
890 | * @spi: device from which data will be read | |
891 | * @buf: data buffer | |
892 | * @len: data buffer size | |
33e34dc6 | 893 | * Context: can sleep |
8ae12a0d | 894 | * |
a1fdeaa7 | 895 | * This function reads the buffer @buf. |
8ae12a0d | 896 | * Callable only from contexts that can sleep. |
a1fdeaa7 JMC |
897 | * |
898 | * Return: zero on success, else a negative error code. | |
8ae12a0d DB |
899 | */ |
900 | static inline int | |
0c4a1590 | 901 | spi_read(struct spi_device *spi, void *buf, size_t len) |
8ae12a0d DB |
902 | { |
903 | struct spi_transfer t = { | |
8ae12a0d DB |
904 | .rx_buf = buf, |
905 | .len = len, | |
8ae12a0d | 906 | }; |
8275c642 | 907 | struct spi_message m; |
8ae12a0d | 908 | |
8275c642 VW |
909 | spi_message_init(&m); |
910 | spi_message_add_tail(&t, &m); | |
8ae12a0d DB |
911 | return spi_sync(spi, &m); |
912 | } | |
913 | ||
6d9eecd4 LPC |
914 | /** |
915 | * spi_sync_transfer - synchronous SPI data transfer | |
916 | * @spi: device with which data will be exchanged | |
917 | * @xfers: An array of spi_transfers | |
918 | * @num_xfers: Number of items in the xfer array | |
919 | * Context: can sleep | |
920 | * | |
921 | * Does a synchronous SPI data transfer of the given spi_transfer array. | |
922 | * | |
923 | * For more specific semantics see spi_sync(). | |
924 | * | |
a1fdeaa7 | 925 | * Return: Return: zero on success, else a negative error code. |
6d9eecd4 LPC |
926 | */ |
927 | static inline int | |
928 | spi_sync_transfer(struct spi_device *spi, struct spi_transfer *xfers, | |
929 | unsigned int num_xfers) | |
930 | { | |
931 | struct spi_message msg; | |
932 | ||
933 | spi_message_init_with_transfers(&msg, xfers, num_xfers); | |
934 | ||
935 | return spi_sync(spi, &msg); | |
936 | } | |
937 | ||
0c868461 | 938 | /* this copies txbuf and rxbuf data; for small transfers only! */ |
8ae12a0d | 939 | extern int spi_write_then_read(struct spi_device *spi, |
0c4a1590 MB |
940 | const void *txbuf, unsigned n_tx, |
941 | void *rxbuf, unsigned n_rx); | |
8ae12a0d DB |
942 | |
943 | /** | |
944 | * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read | |
945 | * @spi: device with which data will be exchanged | |
946 | * @cmd: command to be written before data is read back | |
33e34dc6 | 947 | * Context: can sleep |
8ae12a0d | 948 | * |
a1fdeaa7 JMC |
949 | * Callable only from contexts that can sleep. |
950 | * | |
951 | * Return: the (unsigned) eight bit number returned by the | |
952 | * device, or else a negative error code. | |
8ae12a0d DB |
953 | */ |
954 | static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd) | |
955 | { | |
956 | ssize_t status; | |
957 | u8 result; | |
958 | ||
959 | status = spi_write_then_read(spi, &cmd, 1, &result, 1); | |
960 | ||
961 | /* return negative errno or unsigned value */ | |
962 | return (status < 0) ? status : result; | |
963 | } | |
964 | ||
965 | /** | |
966 | * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read | |
967 | * @spi: device with which data will be exchanged | |
968 | * @cmd: command to be written before data is read back | |
33e34dc6 | 969 | * Context: can sleep |
8ae12a0d | 970 | * |
8ae12a0d DB |
971 | * The number is returned in wire-order, which is at least sometimes |
972 | * big-endian. | |
a1fdeaa7 JMC |
973 | * |
974 | * Callable only from contexts that can sleep. | |
975 | * | |
976 | * Return: the (unsigned) sixteen bit number returned by the | |
977 | * device, or else a negative error code. | |
8ae12a0d DB |
978 | */ |
979 | static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd) | |
980 | { | |
981 | ssize_t status; | |
982 | u16 result; | |
983 | ||
269ccca8 | 984 | status = spi_write_then_read(spi, &cmd, 1, &result, 2); |
8ae12a0d DB |
985 | |
986 | /* return negative errno or unsigned value */ | |
987 | return (status < 0) ? status : result; | |
988 | } | |
989 | ||
05071aa8 LPC |
990 | /** |
991 | * spi_w8r16be - SPI synchronous 8 bit write followed by 16 bit big-endian read | |
992 | * @spi: device with which data will be exchanged | |
993 | * @cmd: command to be written before data is read back | |
994 | * Context: can sleep | |
995 | * | |
05071aa8 LPC |
996 | * This function is similar to spi_w8r16, with the exception that it will |
997 | * convert the read 16 bit data word from big-endian to native endianness. | |
998 | * | |
a1fdeaa7 JMC |
999 | * Callable only from contexts that can sleep. |
1000 | * | |
1001 | * Return: the (unsigned) sixteen bit number returned by the device in cpu | |
1002 | * endianness, or else a negative error code. | |
05071aa8 LPC |
1003 | */ |
1004 | static inline ssize_t spi_w8r16be(struct spi_device *spi, u8 cmd) | |
1005 | ||
1006 | { | |
1007 | ssize_t status; | |
1008 | __be16 result; | |
1009 | ||
1010 | status = spi_write_then_read(spi, &cmd, 1, &result, 2); | |
1011 | if (status < 0) | |
1012 | return status; | |
1013 | ||
1014 | return be16_to_cpu(result); | |
1015 | } | |
1016 | ||
8ae12a0d DB |
1017 | /*---------------------------------------------------------------------------*/ |
1018 | ||
1019 | /* | |
1020 | * INTERFACE between board init code and SPI infrastructure. | |
1021 | * | |
1022 | * No SPI driver ever sees these SPI device table segments, but | |
1023 | * it's how the SPI core (or adapters that get hotplugged) grows | |
1024 | * the driver model tree. | |
1025 | * | |
1026 | * As a rule, SPI devices can't be probed. Instead, board init code | |
1027 | * provides a table listing the devices which are present, with enough | |
1028 | * information to bind and set up the device's driver. There's basic | |
1029 | * support for nonstatic configurations too; enough to handle adding | |
1030 | * parport adapters, or microcontrollers acting as USB-to-SPI bridges. | |
1031 | */ | |
1032 | ||
2604288f DB |
1033 | /** |
1034 | * struct spi_board_info - board-specific template for a SPI device | |
1035 | * @modalias: Initializes spi_device.modalias; identifies the driver. | |
1036 | * @platform_data: Initializes spi_device.platform_data; the particular | |
1037 | * data stored there is driver-specific. | |
1038 | * @controller_data: Initializes spi_device.controller_data; some | |
1039 | * controllers need hints about hardware setup, e.g. for DMA. | |
1040 | * @irq: Initializes spi_device.irq; depends on how the board is wired. | |
1041 | * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits | |
1042 | * from the chip datasheet and board-specific signal quality issues. | |
1043 | * @bus_num: Identifies which spi_master parents the spi_device; unused | |
1044 | * by spi_new_device(), and otherwise depends on board wiring. | |
1045 | * @chip_select: Initializes spi_device.chip_select; depends on how | |
1046 | * the board is wired. | |
1047 | * @mode: Initializes spi_device.mode; based on the chip datasheet, board | |
1048 | * wiring (some devices support both 3WIRE and standard modes), and | |
1049 | * possibly presence of an inverter in the chipselect path. | |
1050 | * | |
1051 | * When adding new SPI devices to the device tree, these structures serve | |
1052 | * as a partial device template. They hold information which can't always | |
1053 | * be determined by drivers. Information that probe() can establish (such | |
1054 | * as the default transfer wordsize) is not included here. | |
1055 | * | |
1056 | * These structures are used in two places. Their primary role is to | |
1057 | * be stored in tables of board-specific device descriptors, which are | |
1058 | * declared early in board initialization and then used (much later) to | |
1059 | * populate a controller's device tree after the that controller's driver | |
1060 | * initializes. A secondary (and atypical) role is as a parameter to | |
1061 | * spi_new_device() call, which happens after those controller drivers | |
1062 | * are active in some dynamic board configuration models. | |
1063 | */ | |
8ae12a0d DB |
1064 | struct spi_board_info { |
1065 | /* the device name and module name are coupled, like platform_bus; | |
1066 | * "modalias" is normally the driver name. | |
1067 | * | |
1068 | * platform_data goes to spi_device.dev.platform_data, | |
b885244e | 1069 | * controller_data goes to spi_device.controller_data, |
8ae12a0d DB |
1070 | * irq is copied too |
1071 | */ | |
75368bf6 | 1072 | char modalias[SPI_NAME_SIZE]; |
8ae12a0d | 1073 | const void *platform_data; |
b885244e | 1074 | void *controller_data; |
8ae12a0d DB |
1075 | int irq; |
1076 | ||
1077 | /* slower signaling on noisy or low voltage boards */ | |
1078 | u32 max_speed_hz; | |
1079 | ||
1080 | ||
1081 | /* bus_num is board specific and matches the bus_num of some | |
1082 | * spi_master that will probably be registered later. | |
1083 | * | |
1084 | * chip_select reflects how this chip is wired to that master; | |
1085 | * it's less than num_chipselect. | |
1086 | */ | |
1087 | u16 bus_num; | |
1088 | u16 chip_select; | |
1089 | ||
980a01c9 DB |
1090 | /* mode becomes spi_device.mode, and is essential for chips |
1091 | * where the default of SPI_CS_HIGH = 0 is wrong. | |
1092 | */ | |
f477b7fb | 1093 | u16 mode; |
980a01c9 | 1094 | |
8ae12a0d DB |
1095 | /* ... may need additional spi_device chip config data here. |
1096 | * avoid stuff protocol drivers can set; but include stuff | |
1097 | * needed to behave without being bound to a driver: | |
8ae12a0d DB |
1098 | * - quirks like clock rate mattering when not selected |
1099 | */ | |
1100 | }; | |
1101 | ||
1102 | #ifdef CONFIG_SPI | |
1103 | extern int | |
1104 | spi_register_board_info(struct spi_board_info const *info, unsigned n); | |
1105 | #else | |
1106 | /* board init code may ignore whether SPI is configured or not */ | |
1107 | static inline int | |
1108 | spi_register_board_info(struct spi_board_info const *info, unsigned n) | |
1109 | { return 0; } | |
1110 | #endif | |
1111 | ||
1112 | ||
1113 | /* If you're hotplugging an adapter with devices (parport, usb, etc) | |
0c868461 DB |
1114 | * use spi_new_device() to describe each device. You can also call |
1115 | * spi_unregister_device() to start making that device vanish, but | |
1116 | * normally that would be handled by spi_unregister_master(). | |
dc87c98e GL |
1117 | * |
1118 | * You can also use spi_alloc_device() and spi_add_device() to use a two | |
1119 | * stage registration sequence for each spi_device. This gives the caller | |
1120 | * some more control over the spi_device structure before it is registered, | |
1121 | * but requires that caller to initialize fields that would otherwise | |
1122 | * be defined using the board info. | |
8ae12a0d | 1123 | */ |
dc87c98e GL |
1124 | extern struct spi_device * |
1125 | spi_alloc_device(struct spi_master *master); | |
1126 | ||
1127 | extern int | |
1128 | spi_add_device(struct spi_device *spi); | |
1129 | ||
8ae12a0d DB |
1130 | extern struct spi_device * |
1131 | spi_new_device(struct spi_master *, struct spi_board_info *); | |
1132 | ||
1133 | static inline void | |
1134 | spi_unregister_device(struct spi_device *spi) | |
1135 | { | |
1136 | if (spi) | |
1137 | device_unregister(&spi->dev); | |
1138 | } | |
1139 | ||
75368bf6 AV |
1140 | extern const struct spi_device_id * |
1141 | spi_get_device_id(const struct spi_device *sdev); | |
1142 | ||
b671358a BG |
1143 | static inline bool |
1144 | spi_transfer_is_last(struct spi_master *master, struct spi_transfer *xfer) | |
1145 | { | |
1146 | return list_is_last(&xfer->transfer_list, &master->cur_msg->transfers); | |
1147 | } | |
1148 | ||
8ae12a0d | 1149 | #endif /* __LINUX_SPI_H */ |