]>
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. | |
13 | * | |
14 | * You should have received a copy of the GNU General Public License | |
15 | * along with this program; if not, write to the Free Software | |
16 | * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
17 | */ | |
18 | ||
19 | #ifndef __LINUX_SPI_H | |
20 | #define __LINUX_SPI_H | |
21 | ||
0a30c5ce RD |
22 | #include <linux/device.h> |
23 | ||
8ae12a0d | 24 | /* |
b885244e | 25 | * INTERFACES between SPI master-side drivers and SPI infrastructure. |
8ae12a0d | 26 | * (There's no SPI slave support for Linux yet...) |
8ae12a0d DB |
27 | */ |
28 | extern struct bus_type spi_bus_type; | |
29 | ||
30 | /** | |
31 | * struct spi_device - Master side proxy for an SPI slave device | |
32 | * @dev: Driver model representation of the device. | |
33 | * @master: SPI controller used with the device. | |
34 | * @max_speed_hz: Maximum clock rate to be used with this chip | |
35 | * (on this board); may be changed by the device's driver. | |
4cff33f9 | 36 | * The spi_transfer.speed_hz can override this for each transfer. |
33e34dc6 | 37 | * @chip_select: Chipselect, distinguishing chips handled by @master. |
8ae12a0d DB |
38 | * @mode: The spi mode defines how data is clocked out and in. |
39 | * This may be changed by the device's driver. | |
33e34dc6 DB |
40 | * The "active low" default for chipselect mode can be overridden |
41 | * (by specifying SPI_CS_HIGH) as can the "MSB first" default for | |
42 | * each word in a transfer (by specifying SPI_LSB_FIRST). | |
8ae12a0d | 43 | * @bits_per_word: Data transfers involve one or more words; word sizes |
747d844e | 44 | * like eight or 12 bits are common. In-memory wordsizes are |
8ae12a0d | 45 | * powers of two bytes (e.g. 20 bit samples use 32 bits). |
ccf77cc4 DB |
46 | * This may be changed by the device's driver, or left at the |
47 | * default (0) indicating protocol words are eight bit bytes. | |
4cff33f9 | 48 | * The spi_transfer.bits_per_word can override this for each transfer. |
8ae12a0d | 49 | * @irq: Negative, or the number passed to request_irq() to receive |
747d844e | 50 | * interrupts from this device. |
8ae12a0d | 51 | * @controller_state: Controller's runtime state |
b885244e | 52 | * @controller_data: Board-specific definitions for controller, such as |
747d844e | 53 | * FIFO initialization parameters; from board_info.controller_data |
33e34dc6 DB |
54 | * @modalias: Name of the driver to use with this device, or an alias |
55 | * for that name. This appears in the sysfs "modalias" attribute | |
56 | * for driver coldplugging, and in uevents used for hotplugging | |
8ae12a0d | 57 | * |
33e34dc6 | 58 | * A @spi_device is used to interchange data between an SPI slave |
8ae12a0d DB |
59 | * (usually a discrete chip) and CPU memory. |
60 | * | |
33e34dc6 | 61 | * In @dev, the platform_data is used to hold information about this |
8ae12a0d DB |
62 | * device that's meaningful to the device's protocol driver, but not |
63 | * to its controller. One example might be an identifier for a chip | |
33e34dc6 DB |
64 | * variant with slightly different functionality; another might be |
65 | * information about how this particular board wires the chip's pins. | |
8ae12a0d DB |
66 | */ |
67 | struct spi_device { | |
68 | struct device dev; | |
69 | struct spi_master *master; | |
70 | u32 max_speed_hz; | |
71 | u8 chip_select; | |
72 | u8 mode; | |
b885244e DB |
73 | #define SPI_CPHA 0x01 /* clock phase */ |
74 | #define SPI_CPOL 0x02 /* clock polarity */ | |
0c868461 DB |
75 | #define SPI_MODE_0 (0|0) /* (original MicroWire) */ |
76 | #define SPI_MODE_1 (0|SPI_CPHA) | |
8ae12a0d DB |
77 | #define SPI_MODE_2 (SPI_CPOL|0) |
78 | #define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) | |
b885244e | 79 | #define SPI_CS_HIGH 0x04 /* chipselect active high? */ |
ccf77cc4 | 80 | #define SPI_LSB_FIRST 0x08 /* per-word bits-on-wire */ |
c06e677a | 81 | #define SPI_3WIRE 0x10 /* SI/SO signals shared */ |
4ef7af50 | 82 | #define SPI_LOOP 0x20 /* loopback mode */ |
8ae12a0d DB |
83 | u8 bits_per_word; |
84 | int irq; | |
85 | void *controller_state; | |
b885244e | 86 | void *controller_data; |
102eb975 | 87 | char modalias[32]; |
8ae12a0d | 88 | |
33e34dc6 DB |
89 | /* |
90 | * likely need more hooks for more protocol options affecting how | |
91 | * the controller talks to each chip, like: | |
92 | * - memory packing (12 bit samples into low bits, others zeroed) | |
93 | * - priority | |
94 | * - drop chipselect after each word | |
95 | * - chipselect delays | |
96 | * - ... | |
97 | */ | |
8ae12a0d DB |
98 | }; |
99 | ||
100 | static inline struct spi_device *to_spi_device(struct device *dev) | |
101 | { | |
b885244e | 102 | return dev ? container_of(dev, struct spi_device, dev) : NULL; |
8ae12a0d DB |
103 | } |
104 | ||
105 | /* most drivers won't need to care about device refcounting */ | |
106 | static inline struct spi_device *spi_dev_get(struct spi_device *spi) | |
107 | { | |
108 | return (spi && get_device(&spi->dev)) ? spi : NULL; | |
109 | } | |
110 | ||
111 | static inline void spi_dev_put(struct spi_device *spi) | |
112 | { | |
113 | if (spi) | |
114 | put_device(&spi->dev); | |
115 | } | |
116 | ||
117 | /* ctldata is for the bus_master driver's runtime state */ | |
118 | static inline void *spi_get_ctldata(struct spi_device *spi) | |
119 | { | |
120 | return spi->controller_state; | |
121 | } | |
122 | ||
123 | static inline void spi_set_ctldata(struct spi_device *spi, void *state) | |
124 | { | |
125 | spi->controller_state = state; | |
126 | } | |
127 | ||
9b40ff4d BD |
128 | /* device driver data */ |
129 | ||
130 | static inline void spi_set_drvdata(struct spi_device *spi, void *data) | |
131 | { | |
132 | dev_set_drvdata(&spi->dev, data); | |
133 | } | |
134 | ||
135 | static inline void *spi_get_drvdata(struct spi_device *spi) | |
136 | { | |
137 | return dev_get_drvdata(&spi->dev); | |
138 | } | |
8ae12a0d DB |
139 | |
140 | struct spi_message; | |
141 | ||
142 | ||
b885244e | 143 | |
2604288f DB |
144 | /** |
145 | * struct spi_driver - Host side "protocol" driver | |
146 | * @probe: Binds this driver to the spi device. Drivers can verify | |
147 | * that the device is actually present, and may need to configure | |
148 | * characteristics (such as bits_per_word) which weren't needed for | |
149 | * the initial configuration done during system setup. | |
150 | * @remove: Unbinds this driver from the spi device | |
151 | * @shutdown: Standard shutdown callback used during system state | |
152 | * transitions such as powerdown/halt and kexec | |
153 | * @suspend: Standard suspend callback used during system state transitions | |
154 | * @resume: Standard resume callback used during system state transitions | |
155 | * @driver: SPI device drivers should initialize the name and owner | |
156 | * field of this structure. | |
157 | * | |
158 | * This represents the kind of device driver that uses SPI messages to | |
159 | * interact with the hardware at the other end of a SPI link. It's called | |
160 | * a "protocol" driver because it works through messages rather than talking | |
161 | * directly to SPI hardware (which is what the underlying SPI controller | |
162 | * driver does to pass those messages). These protocols are defined in the | |
163 | * specification for the device(s) supported by the driver. | |
164 | * | |
165 | * As a rule, those device protocols represent the lowest level interface | |
166 | * supported by a driver, and it will support upper level interfaces too. | |
167 | * Examples of such upper levels include frameworks like MTD, networking, | |
168 | * MMC, RTC, filesystem character device nodes, and hardware monitoring. | |
169 | */ | |
b885244e DB |
170 | struct spi_driver { |
171 | int (*probe)(struct spi_device *spi); | |
172 | int (*remove)(struct spi_device *spi); | |
173 | void (*shutdown)(struct spi_device *spi); | |
174 | int (*suspend)(struct spi_device *spi, pm_message_t mesg); | |
175 | int (*resume)(struct spi_device *spi); | |
176 | struct device_driver driver; | |
177 | }; | |
178 | ||
179 | static inline struct spi_driver *to_spi_driver(struct device_driver *drv) | |
180 | { | |
181 | return drv ? container_of(drv, struct spi_driver, driver) : NULL; | |
182 | } | |
183 | ||
184 | extern int spi_register_driver(struct spi_driver *sdrv); | |
185 | ||
33e34dc6 DB |
186 | /** |
187 | * spi_unregister_driver - reverse effect of spi_register_driver | |
188 | * @sdrv: the driver to unregister | |
189 | * Context: can sleep | |
190 | */ | |
b885244e DB |
191 | static inline void spi_unregister_driver(struct spi_driver *sdrv) |
192 | { | |
ddc1e975 BD |
193 | if (sdrv) |
194 | driver_unregister(&sdrv->driver); | |
b885244e DB |
195 | } |
196 | ||
197 | ||
8ae12a0d DB |
198 | /** |
199 | * struct spi_master - interface to SPI master controller | |
49dce689 | 200 | * @dev: device interface to this driver |
8ae12a0d | 201 | * @bus_num: board-specific (and often SOC-specific) identifier for a |
747d844e | 202 | * given SPI controller. |
b885244e | 203 | * @num_chipselect: chipselects are used to distinguish individual |
747d844e DB |
204 | * SPI slaves, and are numbered from zero to num_chipselects. |
205 | * each slave has a chipselect signal, but it's common that not | |
206 | * every chipselect is connected to a slave. | |
8ae12a0d | 207 | * @setup: updates the device mode and clocking records used by a |
80224561 DB |
208 | * device's SPI controller; protocol code may call this. This |
209 | * must fail if an unrecognized or unsupported mode is requested. | |
33e34dc6 DB |
210 | * It's always safe to call this unless transfers are pending on |
211 | * the device whose settings are being modified. | |
8ae12a0d DB |
212 | * @transfer: adds a message to the controller's transfer queue. |
213 | * @cleanup: frees controller-specific state | |
214 | * | |
33e34dc6 | 215 | * Each SPI master controller can communicate with one or more @spi_device |
8ae12a0d DB |
216 | * children. These make a small bus, sharing MOSI, MISO and SCK signals |
217 | * but not chip select signals. Each device may be configured to use a | |
218 | * different clock rate, since those shared signals are ignored unless | |
219 | * the chip is selected. | |
220 | * | |
221 | * The driver for an SPI controller manages access to those devices through | |
33e34dc6 DB |
222 | * a queue of spi_message transactions, copying data between CPU memory and |
223 | * an SPI slave device. For each such message it queues, it calls the | |
8ae12a0d DB |
224 | * message's completion function when the transaction completes. |
225 | */ | |
226 | struct spi_master { | |
49dce689 | 227 | struct device dev; |
8ae12a0d | 228 | |
a020ed75 | 229 | /* other than negative (== assign one dynamically), bus_num is fully |
8ae12a0d | 230 | * board-specific. usually that simplifies to being SOC-specific. |
a020ed75 | 231 | * example: one SOC has three SPI controllers, numbered 0..2, |
8ae12a0d DB |
232 | * and one board's schematics might show it using SPI-2. software |
233 | * would normally use bus_num=2 for that controller. | |
234 | */ | |
a020ed75 | 235 | s16 bus_num; |
8ae12a0d DB |
236 | |
237 | /* chipselects will be integral to many controllers; some others | |
238 | * might use board-specific GPIOs. | |
239 | */ | |
240 | u16 num_chipselect; | |
241 | ||
242 | /* setup mode and clock, etc (spi driver may call many times) */ | |
243 | int (*setup)(struct spi_device *spi); | |
244 | ||
245 | /* bidirectional bulk transfers | |
246 | * | |
247 | * + The transfer() method may not sleep; its main role is | |
248 | * just to add the message to the queue. | |
249 | * + For now there's no remove-from-queue operation, or | |
250 | * any other request management | |
251 | * + To a given spi_device, message queueing is pure fifo | |
252 | * | |
253 | * + The master's main job is to process its message queue, | |
254 | * selecting a chip then transferring data | |
255 | * + If there are multiple spi_device children, the i/o queue | |
256 | * arbitration algorithm is unspecified (round robin, fifo, | |
257 | * priority, reservations, preemption, etc) | |
258 | * | |
259 | * + Chipselect stays active during the entire message | |
260 | * (unless modified by spi_transfer.cs_change != 0). | |
261 | * + The message transfers use clock and SPI mode parameters | |
262 | * previously established by setup() for this device | |
263 | */ | |
264 | int (*transfer)(struct spi_device *spi, | |
265 | struct spi_message *mesg); | |
266 | ||
267 | /* called on release() to free memory provided by spi_master */ | |
0ffa0285 | 268 | void (*cleanup)(struct spi_device *spi); |
8ae12a0d DB |
269 | }; |
270 | ||
0c868461 DB |
271 | static inline void *spi_master_get_devdata(struct spi_master *master) |
272 | { | |
49dce689 | 273 | return dev_get_drvdata(&master->dev); |
0c868461 DB |
274 | } |
275 | ||
276 | static inline void spi_master_set_devdata(struct spi_master *master, void *data) | |
277 | { | |
49dce689 | 278 | dev_set_drvdata(&master->dev, data); |
0c868461 DB |
279 | } |
280 | ||
281 | static inline struct spi_master *spi_master_get(struct spi_master *master) | |
282 | { | |
49dce689 | 283 | if (!master || !get_device(&master->dev)) |
0c868461 DB |
284 | return NULL; |
285 | return master; | |
286 | } | |
287 | ||
288 | static inline void spi_master_put(struct spi_master *master) | |
289 | { | |
290 | if (master) | |
49dce689 | 291 | put_device(&master->dev); |
0c868461 DB |
292 | } |
293 | ||
294 | ||
8ae12a0d DB |
295 | /* the spi driver core manages memory for the spi_master classdev */ |
296 | extern struct spi_master * | |
297 | spi_alloc_master(struct device *host, unsigned size); | |
298 | ||
299 | extern int spi_register_master(struct spi_master *master); | |
300 | extern void spi_unregister_master(struct spi_master *master); | |
301 | ||
302 | extern struct spi_master *spi_busnum_to_master(u16 busnum); | |
303 | ||
304 | /*---------------------------------------------------------------------------*/ | |
305 | ||
306 | /* | |
307 | * I/O INTERFACE between SPI controller and protocol drivers | |
308 | * | |
309 | * Protocol drivers use a queue of spi_messages, each transferring data | |
310 | * between the controller and memory buffers. | |
311 | * | |
312 | * The spi_messages themselves consist of a series of read+write transfer | |
313 | * segments. Those segments always read the same number of bits as they | |
314 | * write; but one or the other is easily ignored by passing a null buffer | |
315 | * pointer. (This is unlike most types of I/O API, because SPI hardware | |
316 | * is full duplex.) | |
317 | * | |
318 | * NOTE: Allocation of spi_transfer and spi_message memory is entirely | |
319 | * up to the protocol driver, which guarantees the integrity of both (as | |
320 | * well as the data buffers) for as long as the message is queued. | |
321 | */ | |
322 | ||
323 | /** | |
324 | * struct spi_transfer - a read/write buffer pair | |
8275c642 VW |
325 | * @tx_buf: data to be written (dma-safe memory), or NULL |
326 | * @rx_buf: data to be read (dma-safe memory), or NULL | |
33e34dc6 DB |
327 | * @tx_dma: DMA address of tx_buf, if @spi_message.is_dma_mapped |
328 | * @rx_dma: DMA address of rx_buf, if @spi_message.is_dma_mapped | |
8ae12a0d | 329 | * @len: size of rx and tx buffers (in bytes) |
025dfdaf | 330 | * @speed_hz: Select a speed other than the device default for this |
33e34dc6 | 331 | * transfer. If 0 the default (from @spi_device) is used. |
025dfdaf | 332 | * @bits_per_word: select a bits_per_word other than the device default |
33e34dc6 | 333 | * for this transfer. If 0 the default (from @spi_device) is used. |
8ae12a0d DB |
334 | * @cs_change: affects chipselect after this transfer completes |
335 | * @delay_usecs: microseconds to delay after this transfer before | |
747d844e | 336 | * (optionally) changing the chipselect status, then starting |
33e34dc6 DB |
337 | * the next transfer or completing this @spi_message. |
338 | * @transfer_list: transfers are sequenced through @spi_message.transfers | |
8ae12a0d DB |
339 | * |
340 | * SPI transfers always write the same number of bytes as they read. | |
33e34dc6 | 341 | * Protocol drivers should always provide @rx_buf and/or @tx_buf. |
8ae12a0d DB |
342 | * In some cases, they may also want to provide DMA addresses for |
343 | * the data being transferred; that may reduce overhead, when the | |
344 | * underlying driver uses dma. | |
345 | * | |
4b1badf5 | 346 | * If the transmit buffer is null, zeroes will be shifted out |
33e34dc6 | 347 | * while filling @rx_buf. If the receive buffer is null, the data |
8275c642 VW |
348 | * shifted in will be discarded. Only "len" bytes shift out (or in). |
349 | * It's an error to try to shift out a partial word. (For example, by | |
350 | * shifting out three bytes with word size of sixteen or twenty bits; | |
351 | * the former uses two bytes per word, the latter uses four bytes.) | |
352 | * | |
80224561 DB |
353 | * In-memory data values are always in native CPU byte order, translated |
354 | * from the wire byte order (big-endian except with SPI_LSB_FIRST). So | |
355 | * for example when bits_per_word is sixteen, buffers are 2N bytes long | |
33e34dc6 | 356 | * (@len = 2N) and hold N sixteen bit words in CPU byte order. |
80224561 DB |
357 | * |
358 | * When the word size of the SPI transfer is not a power-of-two multiple | |
359 | * of eight bits, those in-memory words include extra bits. In-memory | |
360 | * words are always seen by protocol drivers as right-justified, so the | |
361 | * undefined (rx) or unused (tx) bits are always the most significant bits. | |
362 | * | |
8275c642 VW |
363 | * All SPI transfers start with the relevant chipselect active. Normally |
364 | * it stays selected until after the last transfer in a message. Drivers | |
33e34dc6 | 365 | * can affect the chipselect signal using cs_change. |
8ae12a0d DB |
366 | * |
367 | * (i) If the transfer isn't the last one in the message, this flag is | |
368 | * used to make the chipselect briefly go inactive in the middle of the | |
369 | * message. Toggling chipselect in this way may be needed to terminate | |
370 | * a chip command, letting a single spi_message perform all of group of | |
371 | * chip transactions together. | |
372 | * | |
373 | * (ii) When the transfer is the last one in the message, the chip may | |
f5a9c77d DB |
374 | * stay selected until the next transfer. On multi-device SPI busses |
375 | * with nothing blocking messages going to other devices, this is just | |
376 | * a performance hint; starting a message to another device deselects | |
377 | * this one. But in other cases, this can be used to ensure correctness. | |
378 | * Some devices need protocol transactions to be built from a series of | |
379 | * spi_message submissions, where the content of one message is determined | |
380 | * by the results of previous messages and where the whole transaction | |
381 | * ends when the chipselect goes intactive. | |
0c868461 DB |
382 | * |
383 | * The code that submits an spi_message (and its spi_transfers) | |
384 | * to the lower layers is responsible for managing its memory. | |
385 | * Zero-initialize every field you don't set up explicitly, to | |
8275c642 VW |
386 | * insulate against future API updates. After you submit a message |
387 | * and its transfers, ignore them until its completion callback. | |
8ae12a0d DB |
388 | */ |
389 | struct spi_transfer { | |
390 | /* it's ok if tx_buf == rx_buf (right?) | |
391 | * for MicroWire, one buffer must be null | |
0c868461 DB |
392 | * buffers must work with dma_*map_single() calls, unless |
393 | * spi_message.is_dma_mapped reports a pre-existing mapping | |
8ae12a0d DB |
394 | */ |
395 | const void *tx_buf; | |
396 | void *rx_buf; | |
397 | unsigned len; | |
398 | ||
399 | dma_addr_t tx_dma; | |
400 | dma_addr_t rx_dma; | |
401 | ||
402 | unsigned cs_change:1; | |
4cff33f9 | 403 | u8 bits_per_word; |
8ae12a0d | 404 | u16 delay_usecs; |
4cff33f9 | 405 | u32 speed_hz; |
8275c642 VW |
406 | |
407 | struct list_head transfer_list; | |
8ae12a0d DB |
408 | }; |
409 | ||
410 | /** | |
411 | * struct spi_message - one multi-segment SPI transaction | |
8275c642 | 412 | * @transfers: list of transfer segments in this transaction |
8ae12a0d DB |
413 | * @spi: SPI device to which the transaction is queued |
414 | * @is_dma_mapped: if true, the caller provided both dma and cpu virtual | |
415 | * addresses for each transfer buffer | |
416 | * @complete: called to report transaction completions | |
417 | * @context: the argument to complete() when it's called | |
b885244e DB |
418 | * @actual_length: the total number of bytes that were transferred in all |
419 | * successful segments | |
8ae12a0d DB |
420 | * @status: zero for success, else negative errno |
421 | * @queue: for use by whichever driver currently owns the message | |
422 | * @state: for use by whichever driver currently owns the message | |
0c868461 | 423 | * |
33e34dc6 | 424 | * A @spi_message is used to execute an atomic sequence of data transfers, |
8275c642 VW |
425 | * each represented by a struct spi_transfer. The sequence is "atomic" |
426 | * in the sense that no other spi_message may use that SPI bus until that | |
427 | * sequence completes. On some systems, many such sequences can execute as | |
428 | * as single programmed DMA transfer. On all systems, these messages are | |
429 | * queued, and might complete after transactions to other devices. Messages | |
430 | * sent to a given spi_device are alway executed in FIFO order. | |
431 | * | |
0c868461 DB |
432 | * The code that submits an spi_message (and its spi_transfers) |
433 | * to the lower layers is responsible for managing its memory. | |
434 | * Zero-initialize every field you don't set up explicitly, to | |
8275c642 VW |
435 | * insulate against future API updates. After you submit a message |
436 | * and its transfers, ignore them until its completion callback. | |
8ae12a0d DB |
437 | */ |
438 | struct spi_message { | |
747d844e | 439 | struct list_head transfers; |
8ae12a0d DB |
440 | |
441 | struct spi_device *spi; | |
442 | ||
443 | unsigned is_dma_mapped:1; | |
444 | ||
445 | /* REVISIT: we might want a flag affecting the behavior of the | |
446 | * last transfer ... allowing things like "read 16 bit length L" | |
447 | * immediately followed by "read L bytes". Basically imposing | |
448 | * a specific message scheduling algorithm. | |
449 | * | |
450 | * Some controller drivers (message-at-a-time queue processing) | |
451 | * could provide that as their default scheduling algorithm. But | |
b885244e | 452 | * others (with multi-message pipelines) could need a flag to |
8ae12a0d DB |
453 | * tell them about such special cases. |
454 | */ | |
455 | ||
456 | /* completion is reported through a callback */ | |
747d844e | 457 | void (*complete)(void *context); |
8ae12a0d DB |
458 | void *context; |
459 | unsigned actual_length; | |
460 | int status; | |
461 | ||
462 | /* for optional use by whatever driver currently owns the | |
463 | * spi_message ... between calls to spi_async and then later | |
464 | * complete(), that's the spi_master controller driver. | |
465 | */ | |
466 | struct list_head queue; | |
467 | void *state; | |
468 | }; | |
469 | ||
8275c642 VW |
470 | static inline void spi_message_init(struct spi_message *m) |
471 | { | |
472 | memset(m, 0, sizeof *m); | |
473 | INIT_LIST_HEAD(&m->transfers); | |
474 | } | |
475 | ||
476 | static inline void | |
477 | spi_message_add_tail(struct spi_transfer *t, struct spi_message *m) | |
478 | { | |
479 | list_add_tail(&t->transfer_list, &m->transfers); | |
480 | } | |
481 | ||
482 | static inline void | |
483 | spi_transfer_del(struct spi_transfer *t) | |
484 | { | |
485 | list_del(&t->transfer_list); | |
486 | } | |
487 | ||
0c868461 DB |
488 | /* It's fine to embed message and transaction structures in other data |
489 | * structures so long as you don't free them while they're in use. | |
490 | */ | |
491 | ||
492 | static inline struct spi_message *spi_message_alloc(unsigned ntrans, gfp_t flags) | |
493 | { | |
494 | struct spi_message *m; | |
495 | ||
496 | m = kzalloc(sizeof(struct spi_message) | |
497 | + ntrans * sizeof(struct spi_transfer), | |
498 | flags); | |
499 | if (m) { | |
8275c642 VW |
500 | int i; |
501 | struct spi_transfer *t = (struct spi_transfer *)(m + 1); | |
502 | ||
503 | INIT_LIST_HEAD(&m->transfers); | |
504 | for (i = 0; i < ntrans; i++, t++) | |
505 | spi_message_add_tail(t, m); | |
0c868461 DB |
506 | } |
507 | return m; | |
508 | } | |
509 | ||
510 | static inline void spi_message_free(struct spi_message *m) | |
511 | { | |
512 | kfree(m); | |
513 | } | |
514 | ||
8ae12a0d | 515 | /** |
33e34dc6 | 516 | * spi_setup - setup SPI mode and clock rate |
8ae12a0d | 517 | * @spi: the device whose settings are being modified |
f5a9c77d | 518 | * Context: can sleep, and no requests are queued to the device |
8ae12a0d DB |
519 | * |
520 | * SPI protocol drivers may need to update the transfer mode if the | |
f5a9c77d | 521 | * device doesn't work with its default. They may likewise need |
8ae12a0d DB |
522 | * to update clock rates or word sizes from initial values. This function |
523 | * changes those settings, and must be called from a context that can sleep. | |
f5a9c77d DB |
524 | * Except for SPI_CS_HIGH, which takes effect immediately, the changes take |
525 | * effect the next time the device is selected and data is transferred to | |
526 | * or from it. When this function returns, the spi device is deselected. | |
80224561 | 527 | * |
33e34dc6 | 528 | * Note that this call will fail if the protocol driver specifies an option |
80224561 DB |
529 | * that the underlying controller or its driver does not support. For |
530 | * example, not all hardware supports wire transfers using nine bit words, | |
531 | * LSB-first wire encoding, or active-high chipselects. | |
8ae12a0d DB |
532 | */ |
533 | static inline int | |
534 | spi_setup(struct spi_device *spi) | |
535 | { | |
536 | return spi->master->setup(spi); | |
537 | } | |
538 | ||
539 | ||
540 | /** | |
33e34dc6 | 541 | * spi_async - asynchronous SPI transfer |
8ae12a0d DB |
542 | * @spi: device with which data will be exchanged |
543 | * @message: describes the data transfers, including completion callback | |
33e34dc6 | 544 | * Context: any (irqs may be blocked, etc) |
8ae12a0d DB |
545 | * |
546 | * This call may be used in_irq and other contexts which can't sleep, | |
547 | * as well as from task contexts which can sleep. | |
548 | * | |
549 | * The completion callback is invoked in a context which can't sleep. | |
550 | * Before that invocation, the value of message->status is undefined. | |
551 | * When the callback is issued, message->status holds either zero (to | |
0c868461 DB |
552 | * indicate complete success) or a negative error code. After that |
553 | * callback returns, the driver which issued the transfer request may | |
554 | * deallocate the associated memory; it's no longer in use by any SPI | |
555 | * core or controller driver code. | |
8ae12a0d DB |
556 | * |
557 | * Note that although all messages to a spi_device are handled in | |
558 | * FIFO order, messages may go to different devices in other orders. | |
559 | * Some device might be higher priority, or have various "hard" access | |
560 | * time requirements, for example. | |
b885244e DB |
561 | * |
562 | * On detection of any fault during the transfer, processing of | |
563 | * the entire message is aborted, and the device is deselected. | |
564 | * Until returning from the associated message completion callback, | |
565 | * no other spi_message queued to that device will be processed. | |
566 | * (This rule applies equally to all the synchronous transfer calls, | |
567 | * which are wrappers around this core asynchronous primitive.) | |
8ae12a0d DB |
568 | */ |
569 | static inline int | |
570 | spi_async(struct spi_device *spi, struct spi_message *message) | |
571 | { | |
572 | message->spi = spi; | |
573 | return spi->master->transfer(spi, message); | |
574 | } | |
575 | ||
576 | /*---------------------------------------------------------------------------*/ | |
577 | ||
578 | /* All these synchronous SPI transfer routines are utilities layered | |
579 | * over the core async transfer primitive. Here, "synchronous" means | |
580 | * they will sleep uninterruptibly until the async transfer completes. | |
581 | */ | |
582 | ||
583 | extern int spi_sync(struct spi_device *spi, struct spi_message *message); | |
584 | ||
585 | /** | |
586 | * spi_write - SPI synchronous write | |
587 | * @spi: device to which data will be written | |
588 | * @buf: data buffer | |
589 | * @len: data buffer size | |
33e34dc6 | 590 | * Context: can sleep |
8ae12a0d DB |
591 | * |
592 | * This writes the buffer and returns zero or a negative error code. | |
593 | * Callable only from contexts that can sleep. | |
594 | */ | |
595 | static inline int | |
596 | spi_write(struct spi_device *spi, const u8 *buf, size_t len) | |
597 | { | |
598 | struct spi_transfer t = { | |
599 | .tx_buf = buf, | |
8ae12a0d | 600 | .len = len, |
8ae12a0d | 601 | }; |
8275c642 | 602 | struct spi_message m; |
8ae12a0d | 603 | |
8275c642 VW |
604 | spi_message_init(&m); |
605 | spi_message_add_tail(&t, &m); | |
8ae12a0d DB |
606 | return spi_sync(spi, &m); |
607 | } | |
608 | ||
609 | /** | |
610 | * spi_read - SPI synchronous read | |
611 | * @spi: device from which data will be read | |
612 | * @buf: data buffer | |
613 | * @len: data buffer size | |
33e34dc6 | 614 | * Context: can sleep |
8ae12a0d | 615 | * |
33e34dc6 | 616 | * This reads the buffer and returns zero or a negative error code. |
8ae12a0d DB |
617 | * Callable only from contexts that can sleep. |
618 | */ | |
619 | static inline int | |
620 | spi_read(struct spi_device *spi, u8 *buf, size_t len) | |
621 | { | |
622 | struct spi_transfer t = { | |
8ae12a0d DB |
623 | .rx_buf = buf, |
624 | .len = len, | |
8ae12a0d | 625 | }; |
8275c642 | 626 | struct spi_message m; |
8ae12a0d | 627 | |
8275c642 VW |
628 | spi_message_init(&m); |
629 | spi_message_add_tail(&t, &m); | |
8ae12a0d DB |
630 | return spi_sync(spi, &m); |
631 | } | |
632 | ||
0c868461 | 633 | /* this copies txbuf and rxbuf data; for small transfers only! */ |
8ae12a0d DB |
634 | extern int spi_write_then_read(struct spi_device *spi, |
635 | const u8 *txbuf, unsigned n_tx, | |
636 | u8 *rxbuf, unsigned n_rx); | |
637 | ||
638 | /** | |
639 | * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read | |
640 | * @spi: device with which data will be exchanged | |
641 | * @cmd: command to be written before data is read back | |
33e34dc6 | 642 | * Context: can sleep |
8ae12a0d DB |
643 | * |
644 | * This returns the (unsigned) eight bit number returned by the | |
645 | * device, or else a negative error code. Callable only from | |
646 | * contexts that can sleep. | |
647 | */ | |
648 | static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd) | |
649 | { | |
650 | ssize_t status; | |
651 | u8 result; | |
652 | ||
653 | status = spi_write_then_read(spi, &cmd, 1, &result, 1); | |
654 | ||
655 | /* return negative errno or unsigned value */ | |
656 | return (status < 0) ? status : result; | |
657 | } | |
658 | ||
659 | /** | |
660 | * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read | |
661 | * @spi: device with which data will be exchanged | |
662 | * @cmd: command to be written before data is read back | |
33e34dc6 | 663 | * Context: can sleep |
8ae12a0d DB |
664 | * |
665 | * This returns the (unsigned) sixteen bit number returned by the | |
666 | * device, or else a negative error code. Callable only from | |
667 | * contexts that can sleep. | |
668 | * | |
669 | * The number is returned in wire-order, which is at least sometimes | |
670 | * big-endian. | |
671 | */ | |
672 | static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd) | |
673 | { | |
674 | ssize_t status; | |
675 | u16 result; | |
676 | ||
677 | status = spi_write_then_read(spi, &cmd, 1, (u8 *) &result, 2); | |
678 | ||
679 | /* return negative errno or unsigned value */ | |
680 | return (status < 0) ? status : result; | |
681 | } | |
682 | ||
683 | /*---------------------------------------------------------------------------*/ | |
684 | ||
685 | /* | |
686 | * INTERFACE between board init code and SPI infrastructure. | |
687 | * | |
688 | * No SPI driver ever sees these SPI device table segments, but | |
689 | * it's how the SPI core (or adapters that get hotplugged) grows | |
690 | * the driver model tree. | |
691 | * | |
692 | * As a rule, SPI devices can't be probed. Instead, board init code | |
693 | * provides a table listing the devices which are present, with enough | |
694 | * information to bind and set up the device's driver. There's basic | |
695 | * support for nonstatic configurations too; enough to handle adding | |
696 | * parport adapters, or microcontrollers acting as USB-to-SPI bridges. | |
697 | */ | |
698 | ||
2604288f DB |
699 | /** |
700 | * struct spi_board_info - board-specific template for a SPI device | |
701 | * @modalias: Initializes spi_device.modalias; identifies the driver. | |
702 | * @platform_data: Initializes spi_device.platform_data; the particular | |
703 | * data stored there is driver-specific. | |
704 | * @controller_data: Initializes spi_device.controller_data; some | |
705 | * controllers need hints about hardware setup, e.g. for DMA. | |
706 | * @irq: Initializes spi_device.irq; depends on how the board is wired. | |
707 | * @max_speed_hz: Initializes spi_device.max_speed_hz; based on limits | |
708 | * from the chip datasheet and board-specific signal quality issues. | |
709 | * @bus_num: Identifies which spi_master parents the spi_device; unused | |
710 | * by spi_new_device(), and otherwise depends on board wiring. | |
711 | * @chip_select: Initializes spi_device.chip_select; depends on how | |
712 | * the board is wired. | |
713 | * @mode: Initializes spi_device.mode; based on the chip datasheet, board | |
714 | * wiring (some devices support both 3WIRE and standard modes), and | |
715 | * possibly presence of an inverter in the chipselect path. | |
716 | * | |
717 | * When adding new SPI devices to the device tree, these structures serve | |
718 | * as a partial device template. They hold information which can't always | |
719 | * be determined by drivers. Information that probe() can establish (such | |
720 | * as the default transfer wordsize) is not included here. | |
721 | * | |
722 | * These structures are used in two places. Their primary role is to | |
723 | * be stored in tables of board-specific device descriptors, which are | |
724 | * declared early in board initialization and then used (much later) to | |
725 | * populate a controller's device tree after the that controller's driver | |
726 | * initializes. A secondary (and atypical) role is as a parameter to | |
727 | * spi_new_device() call, which happens after those controller drivers | |
728 | * are active in some dynamic board configuration models. | |
729 | */ | |
8ae12a0d DB |
730 | struct spi_board_info { |
731 | /* the device name and module name are coupled, like platform_bus; | |
732 | * "modalias" is normally the driver name. | |
733 | * | |
734 | * platform_data goes to spi_device.dev.platform_data, | |
b885244e | 735 | * controller_data goes to spi_device.controller_data, |
8ae12a0d DB |
736 | * irq is copied too |
737 | */ | |
aab0de24 | 738 | char modalias[32]; |
8ae12a0d | 739 | const void *platform_data; |
b885244e | 740 | void *controller_data; |
8ae12a0d DB |
741 | int irq; |
742 | ||
743 | /* slower signaling on noisy or low voltage boards */ | |
744 | u32 max_speed_hz; | |
745 | ||
746 | ||
747 | /* bus_num is board specific and matches the bus_num of some | |
748 | * spi_master that will probably be registered later. | |
749 | * | |
750 | * chip_select reflects how this chip is wired to that master; | |
751 | * it's less than num_chipselect. | |
752 | */ | |
753 | u16 bus_num; | |
754 | u16 chip_select; | |
755 | ||
980a01c9 DB |
756 | /* mode becomes spi_device.mode, and is essential for chips |
757 | * where the default of SPI_CS_HIGH = 0 is wrong. | |
758 | */ | |
759 | u8 mode; | |
760 | ||
8ae12a0d DB |
761 | /* ... may need additional spi_device chip config data here. |
762 | * avoid stuff protocol drivers can set; but include stuff | |
763 | * needed to behave without being bound to a driver: | |
8ae12a0d DB |
764 | * - quirks like clock rate mattering when not selected |
765 | */ | |
766 | }; | |
767 | ||
768 | #ifdef CONFIG_SPI | |
769 | extern int | |
770 | spi_register_board_info(struct spi_board_info const *info, unsigned n); | |
771 | #else | |
772 | /* board init code may ignore whether SPI is configured or not */ | |
773 | static inline int | |
774 | spi_register_board_info(struct spi_board_info const *info, unsigned n) | |
775 | { return 0; } | |
776 | #endif | |
777 | ||
778 | ||
779 | /* If you're hotplugging an adapter with devices (parport, usb, etc) | |
0c868461 DB |
780 | * use spi_new_device() to describe each device. You can also call |
781 | * spi_unregister_device() to start making that device vanish, but | |
782 | * normally that would be handled by spi_unregister_master(). | |
dc87c98e GL |
783 | * |
784 | * You can also use spi_alloc_device() and spi_add_device() to use a two | |
785 | * stage registration sequence for each spi_device. This gives the caller | |
786 | * some more control over the spi_device structure before it is registered, | |
787 | * but requires that caller to initialize fields that would otherwise | |
788 | * be defined using the board info. | |
8ae12a0d | 789 | */ |
dc87c98e GL |
790 | extern struct spi_device * |
791 | spi_alloc_device(struct spi_master *master); | |
792 | ||
793 | extern int | |
794 | spi_add_device(struct spi_device *spi); | |
795 | ||
8ae12a0d DB |
796 | extern struct spi_device * |
797 | spi_new_device(struct spi_master *, struct spi_board_info *); | |
798 | ||
799 | static inline void | |
800 | spi_unregister_device(struct spi_device *spi) | |
801 | { | |
802 | if (spi) | |
803 | device_unregister(&spi->dev); | |
804 | } | |
805 | ||
806 | #endif /* __LINUX_SPI_H */ |