David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 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 | |
| 22 | /* |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 23 | * INTERFACES between SPI master-side drivers and SPI infrastructure. |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 24 | * (There's no SPI slave support for Linux yet...) |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 25 | */ |
| 26 | extern struct bus_type spi_bus_type; |
| 27 | |
| 28 | /** |
| 29 | * struct spi_device - Master side proxy for an SPI slave device |
| 30 | * @dev: Driver model representation of the device. |
| 31 | * @master: SPI controller used with the device. |
| 32 | * @max_speed_hz: Maximum clock rate to be used with this chip |
| 33 | * (on this board); may be changed by the device's driver. |
| 34 | * @chip-select: Chipselect, distinguishing chips handled by "master". |
| 35 | * @mode: The spi mode defines how data is clocked out and in. |
| 36 | * This may be changed by the device's driver. |
| 37 | * @bits_per_word: Data transfers involve one or more words; word sizes |
| 38 | * like eight or 12 bits are common. In-memory wordsizes are |
| 39 | * powers of two bytes (e.g. 20 bit samples use 32 bits). |
| 40 | * This may be changed by the device's driver. |
| 41 | * @irq: Negative, or the number passed to request_irq() to receive |
| 42 | * interrupts from this device. |
| 43 | * @controller_state: Controller's runtime state |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 44 | * @controller_data: Board-specific definitions for controller, such as |
| 45 | * FIFO initialization parameters; from board_info.controller_data |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 46 | * |
| 47 | * An spi_device is used to interchange data between an SPI slave |
| 48 | * (usually a discrete chip) and CPU memory. |
| 49 | * |
| 50 | * In "dev", the platform_data is used to hold information about this |
| 51 | * device that's meaningful to the device's protocol driver, but not |
| 52 | * to its controller. One example might be an identifier for a chip |
| 53 | * variant with slightly different functionality. |
| 54 | */ |
| 55 | struct spi_device { |
| 56 | struct device dev; |
| 57 | struct spi_master *master; |
| 58 | u32 max_speed_hz; |
| 59 | u8 chip_select; |
| 60 | u8 mode; |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 61 | #define SPI_CPHA 0x01 /* clock phase */ |
| 62 | #define SPI_CPOL 0x02 /* clock polarity */ |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 63 | #define SPI_MODE_0 (0|0) |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 64 | #define SPI_MODE_1 (0|SPI_CPHA) /* (original MicroWire) */ |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 65 | #define SPI_MODE_2 (SPI_CPOL|0) |
| 66 | #define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 67 | #define SPI_CS_HIGH 0x04 /* chipselect active high? */ |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 68 | u8 bits_per_word; |
| 69 | int irq; |
| 70 | void *controller_state; |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 71 | void *controller_data; |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 72 | const char *modalias; |
| 73 | |
| 74 | // likely need more hooks for more protocol options affecting how |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 75 | // the controller talks to each chip, like: |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 76 | // - bit order (default is wordwise msb-first) |
| 77 | // - memory packing (12 bit samples into low bits, others zeroed) |
| 78 | // - priority |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 79 | // - drop chipselect after each word |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 80 | // - chipselect delays |
| 81 | // - ... |
| 82 | }; |
| 83 | |
| 84 | static inline struct spi_device *to_spi_device(struct device *dev) |
| 85 | { |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 86 | return dev ? container_of(dev, struct spi_device, dev) : NULL; |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 87 | } |
| 88 | |
| 89 | /* most drivers won't need to care about device refcounting */ |
| 90 | static inline struct spi_device *spi_dev_get(struct spi_device *spi) |
| 91 | { |
| 92 | return (spi && get_device(&spi->dev)) ? spi : NULL; |
| 93 | } |
| 94 | |
| 95 | static inline void spi_dev_put(struct spi_device *spi) |
| 96 | { |
| 97 | if (spi) |
| 98 | put_device(&spi->dev); |
| 99 | } |
| 100 | |
| 101 | /* ctldata is for the bus_master driver's runtime state */ |
| 102 | static inline void *spi_get_ctldata(struct spi_device *spi) |
| 103 | { |
| 104 | return spi->controller_state; |
| 105 | } |
| 106 | |
| 107 | static inline void spi_set_ctldata(struct spi_device *spi, void *state) |
| 108 | { |
| 109 | spi->controller_state = state; |
| 110 | } |
| 111 | |
| 112 | |
| 113 | struct spi_message; |
| 114 | |
| 115 | |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 116 | |
| 117 | struct spi_driver { |
| 118 | int (*probe)(struct spi_device *spi); |
| 119 | int (*remove)(struct spi_device *spi); |
| 120 | void (*shutdown)(struct spi_device *spi); |
| 121 | int (*suspend)(struct spi_device *spi, pm_message_t mesg); |
| 122 | int (*resume)(struct spi_device *spi); |
| 123 | struct device_driver driver; |
| 124 | }; |
| 125 | |
| 126 | static inline struct spi_driver *to_spi_driver(struct device_driver *drv) |
| 127 | { |
| 128 | return drv ? container_of(drv, struct spi_driver, driver) : NULL; |
| 129 | } |
| 130 | |
| 131 | extern int spi_register_driver(struct spi_driver *sdrv); |
| 132 | |
| 133 | static inline void spi_unregister_driver(struct spi_driver *sdrv) |
| 134 | { |
| 135 | if (!sdrv) |
| 136 | return; |
| 137 | driver_unregister(&sdrv->driver); |
| 138 | } |
| 139 | |
| 140 | |
| 141 | |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 142 | /** |
| 143 | * struct spi_master - interface to SPI master controller |
| 144 | * @cdev: class interface to this driver |
| 145 | * @bus_num: board-specific (and often SOC-specific) identifier for a |
| 146 | * given SPI controller. |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 147 | * @num_chipselect: chipselects are used to distinguish individual |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 148 | * SPI slaves, and are numbered from zero to num_chipselects. |
| 149 | * each slave has a chipselect signal, but it's common that not |
| 150 | * every chipselect is connected to a slave. |
| 151 | * @setup: updates the device mode and clocking records used by a |
| 152 | * device's SPI controller; protocol code may call this. |
| 153 | * @transfer: adds a message to the controller's transfer queue. |
| 154 | * @cleanup: frees controller-specific state |
| 155 | * |
| 156 | * Each SPI master controller can communicate with one or more spi_device |
| 157 | * children. These make a small bus, sharing MOSI, MISO and SCK signals |
| 158 | * but not chip select signals. Each device may be configured to use a |
| 159 | * different clock rate, since those shared signals are ignored unless |
| 160 | * the chip is selected. |
| 161 | * |
| 162 | * The driver for an SPI controller manages access to those devices through |
| 163 | * a queue of spi_message transactions, copyin data between CPU memory and |
| 164 | * an SPI slave device). For each such message it queues, it calls the |
| 165 | * message's completion function when the transaction completes. |
| 166 | */ |
| 167 | struct spi_master { |
| 168 | struct class_device cdev; |
| 169 | |
| 170 | /* other than zero (== assign one dynamically), bus_num is fully |
| 171 | * board-specific. usually that simplifies to being SOC-specific. |
| 172 | * example: one SOC has three SPI controllers, numbered 1..3, |
| 173 | * and one board's schematics might show it using SPI-2. software |
| 174 | * would normally use bus_num=2 for that controller. |
| 175 | */ |
| 176 | u16 bus_num; |
| 177 | |
| 178 | /* chipselects will be integral to many controllers; some others |
| 179 | * might use board-specific GPIOs. |
| 180 | */ |
| 181 | u16 num_chipselect; |
| 182 | |
| 183 | /* setup mode and clock, etc (spi driver may call many times) */ |
| 184 | int (*setup)(struct spi_device *spi); |
| 185 | |
| 186 | /* bidirectional bulk transfers |
| 187 | * |
| 188 | * + The transfer() method may not sleep; its main role is |
| 189 | * just to add the message to the queue. |
| 190 | * + For now there's no remove-from-queue operation, or |
| 191 | * any other request management |
| 192 | * + To a given spi_device, message queueing is pure fifo |
| 193 | * |
| 194 | * + The master's main job is to process its message queue, |
| 195 | * selecting a chip then transferring data |
| 196 | * + If there are multiple spi_device children, the i/o queue |
| 197 | * arbitration algorithm is unspecified (round robin, fifo, |
| 198 | * priority, reservations, preemption, etc) |
| 199 | * |
| 200 | * + Chipselect stays active during the entire message |
| 201 | * (unless modified by spi_transfer.cs_change != 0). |
| 202 | * + The message transfers use clock and SPI mode parameters |
| 203 | * previously established by setup() for this device |
| 204 | */ |
| 205 | int (*transfer)(struct spi_device *spi, |
| 206 | struct spi_message *mesg); |
| 207 | |
| 208 | /* called on release() to free memory provided by spi_master */ |
| 209 | void (*cleanup)(const struct spi_device *spi); |
| 210 | }; |
| 211 | |
| 212 | /* the spi driver core manages memory for the spi_master classdev */ |
| 213 | extern struct spi_master * |
| 214 | spi_alloc_master(struct device *host, unsigned size); |
| 215 | |
| 216 | extern int spi_register_master(struct spi_master *master); |
| 217 | extern void spi_unregister_master(struct spi_master *master); |
| 218 | |
| 219 | extern struct spi_master *spi_busnum_to_master(u16 busnum); |
| 220 | |
| 221 | /*---------------------------------------------------------------------------*/ |
| 222 | |
| 223 | /* |
| 224 | * I/O INTERFACE between SPI controller and protocol drivers |
| 225 | * |
| 226 | * Protocol drivers use a queue of spi_messages, each transferring data |
| 227 | * between the controller and memory buffers. |
| 228 | * |
| 229 | * The spi_messages themselves consist of a series of read+write transfer |
| 230 | * segments. Those segments always read the same number of bits as they |
| 231 | * write; but one or the other is easily ignored by passing a null buffer |
| 232 | * pointer. (This is unlike most types of I/O API, because SPI hardware |
| 233 | * is full duplex.) |
| 234 | * |
| 235 | * NOTE: Allocation of spi_transfer and spi_message memory is entirely |
| 236 | * up to the protocol driver, which guarantees the integrity of both (as |
| 237 | * well as the data buffers) for as long as the message is queued. |
| 238 | */ |
| 239 | |
| 240 | /** |
| 241 | * struct spi_transfer - a read/write buffer pair |
| 242 | * @tx_buf: data to be written (dma-safe address), or NULL |
| 243 | * @rx_buf: data to be read (dma-safe address), or NULL |
| 244 | * @tx_dma: DMA address of buffer, if spi_message.is_dma_mapped |
| 245 | * @rx_dma: DMA address of buffer, if spi_message.is_dma_mapped |
| 246 | * @len: size of rx and tx buffers (in bytes) |
| 247 | * @cs_change: affects chipselect after this transfer completes |
| 248 | * @delay_usecs: microseconds to delay after this transfer before |
| 249 | * (optionally) changing the chipselect status, then starting |
| 250 | * the next transfer or completing this spi_message. |
| 251 | * |
| 252 | * SPI transfers always write the same number of bytes as they read. |
| 253 | * Protocol drivers should always provide rx_buf and/or tx_buf. |
| 254 | * In some cases, they may also want to provide DMA addresses for |
| 255 | * the data being transferred; that may reduce overhead, when the |
| 256 | * underlying driver uses dma. |
| 257 | * |
| 258 | * All SPI transfers start with the relevant chipselect active. Drivers |
| 259 | * can change behavior of the chipselect after the transfer finishes |
| 260 | * (including any mandatory delay). The normal behavior is to leave it |
| 261 | * selected, except for the last transfer in a message. Setting cs_change |
| 262 | * allows two additional behavior options: |
| 263 | * |
| 264 | * (i) If the transfer isn't the last one in the message, this flag is |
| 265 | * used to make the chipselect briefly go inactive in the middle of the |
| 266 | * message. Toggling chipselect in this way may be needed to terminate |
| 267 | * a chip command, letting a single spi_message perform all of group of |
| 268 | * chip transactions together. |
| 269 | * |
| 270 | * (ii) When the transfer is the last one in the message, the chip may |
| 271 | * stay selected until the next transfer. This is purely a performance |
| 272 | * hint; the controller driver may need to select a different device |
| 273 | * for the next message. |
| 274 | */ |
| 275 | struct spi_transfer { |
| 276 | /* it's ok if tx_buf == rx_buf (right?) |
| 277 | * for MicroWire, one buffer must be null |
| 278 | * buffers must work with dma_*map_single() calls |
| 279 | */ |
| 280 | const void *tx_buf; |
| 281 | void *rx_buf; |
| 282 | unsigned len; |
| 283 | |
| 284 | dma_addr_t tx_dma; |
| 285 | dma_addr_t rx_dma; |
| 286 | |
| 287 | unsigned cs_change:1; |
| 288 | u16 delay_usecs; |
| 289 | }; |
| 290 | |
| 291 | /** |
| 292 | * struct spi_message - one multi-segment SPI transaction |
| 293 | * @transfers: the segements of the transaction |
| 294 | * @n_transfer: how many segments |
| 295 | * @spi: SPI device to which the transaction is queued |
| 296 | * @is_dma_mapped: if true, the caller provided both dma and cpu virtual |
| 297 | * addresses for each transfer buffer |
| 298 | * @complete: called to report transaction completions |
| 299 | * @context: the argument to complete() when it's called |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 300 | * @actual_length: the total number of bytes that were transferred in all |
| 301 | * successful segments |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 302 | * @status: zero for success, else negative errno |
| 303 | * @queue: for use by whichever driver currently owns the message |
| 304 | * @state: for use by whichever driver currently owns the message |
| 305 | */ |
| 306 | struct spi_message { |
| 307 | struct spi_transfer *transfers; |
| 308 | unsigned n_transfer; |
| 309 | |
| 310 | struct spi_device *spi; |
| 311 | |
| 312 | unsigned is_dma_mapped:1; |
| 313 | |
| 314 | /* REVISIT: we might want a flag affecting the behavior of the |
| 315 | * last transfer ... allowing things like "read 16 bit length L" |
| 316 | * immediately followed by "read L bytes". Basically imposing |
| 317 | * a specific message scheduling algorithm. |
| 318 | * |
| 319 | * Some controller drivers (message-at-a-time queue processing) |
| 320 | * could provide that as their default scheduling algorithm. But |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 321 | * others (with multi-message pipelines) could need a flag to |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 322 | * tell them about such special cases. |
| 323 | */ |
| 324 | |
| 325 | /* completion is reported through a callback */ |
| 326 | void FASTCALL((*complete)(void *context)); |
| 327 | void *context; |
| 328 | unsigned actual_length; |
| 329 | int status; |
| 330 | |
| 331 | /* for optional use by whatever driver currently owns the |
| 332 | * spi_message ... between calls to spi_async and then later |
| 333 | * complete(), that's the spi_master controller driver. |
| 334 | */ |
| 335 | struct list_head queue; |
| 336 | void *state; |
| 337 | }; |
| 338 | |
| 339 | /** |
| 340 | * spi_setup -- setup SPI mode and clock rate |
| 341 | * @spi: the device whose settings are being modified |
| 342 | * |
| 343 | * SPI protocol drivers may need to update the transfer mode if the |
| 344 | * device doesn't work with the mode 0 default. They may likewise need |
| 345 | * to update clock rates or word sizes from initial values. This function |
| 346 | * changes those settings, and must be called from a context that can sleep. |
| 347 | */ |
| 348 | static inline int |
| 349 | spi_setup(struct spi_device *spi) |
| 350 | { |
| 351 | return spi->master->setup(spi); |
| 352 | } |
| 353 | |
| 354 | |
| 355 | /** |
| 356 | * spi_async -- asynchronous SPI transfer |
| 357 | * @spi: device with which data will be exchanged |
| 358 | * @message: describes the data transfers, including completion callback |
| 359 | * |
| 360 | * This call may be used in_irq and other contexts which can't sleep, |
| 361 | * as well as from task contexts which can sleep. |
| 362 | * |
| 363 | * The completion callback is invoked in a context which can't sleep. |
| 364 | * Before that invocation, the value of message->status is undefined. |
| 365 | * When the callback is issued, message->status holds either zero (to |
| 366 | * indicate complete success) or a negative error code. |
| 367 | * |
| 368 | * Note that although all messages to a spi_device are handled in |
| 369 | * FIFO order, messages may go to different devices in other orders. |
| 370 | * Some device might be higher priority, or have various "hard" access |
| 371 | * time requirements, for example. |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 372 | * |
| 373 | * On detection of any fault during the transfer, processing of |
| 374 | * the entire message is aborted, and the device is deselected. |
| 375 | * Until returning from the associated message completion callback, |
| 376 | * no other spi_message queued to that device will be processed. |
| 377 | * (This rule applies equally to all the synchronous transfer calls, |
| 378 | * which are wrappers around this core asynchronous primitive.) |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 379 | */ |
| 380 | static inline int |
| 381 | spi_async(struct spi_device *spi, struct spi_message *message) |
| 382 | { |
| 383 | message->spi = spi; |
| 384 | return spi->master->transfer(spi, message); |
| 385 | } |
| 386 | |
| 387 | /*---------------------------------------------------------------------------*/ |
| 388 | |
| 389 | /* All these synchronous SPI transfer routines are utilities layered |
| 390 | * over the core async transfer primitive. Here, "synchronous" means |
| 391 | * they will sleep uninterruptibly until the async transfer completes. |
| 392 | */ |
| 393 | |
| 394 | extern int spi_sync(struct spi_device *spi, struct spi_message *message); |
| 395 | |
| 396 | /** |
| 397 | * spi_write - SPI synchronous write |
| 398 | * @spi: device to which data will be written |
| 399 | * @buf: data buffer |
| 400 | * @len: data buffer size |
| 401 | * |
| 402 | * This writes the buffer and returns zero or a negative error code. |
| 403 | * Callable only from contexts that can sleep. |
| 404 | */ |
| 405 | static inline int |
| 406 | spi_write(struct spi_device *spi, const u8 *buf, size_t len) |
| 407 | { |
| 408 | struct spi_transfer t = { |
| 409 | .tx_buf = buf, |
| 410 | .rx_buf = NULL, |
| 411 | .len = len, |
| 412 | .cs_change = 0, |
| 413 | }; |
| 414 | struct spi_message m = { |
| 415 | .transfers = &t, |
| 416 | .n_transfer = 1, |
| 417 | }; |
| 418 | |
| 419 | return spi_sync(spi, &m); |
| 420 | } |
| 421 | |
| 422 | /** |
| 423 | * spi_read - SPI synchronous read |
| 424 | * @spi: device from which data will be read |
| 425 | * @buf: data buffer |
| 426 | * @len: data buffer size |
| 427 | * |
| 428 | * This writes the buffer and returns zero or a negative error code. |
| 429 | * Callable only from contexts that can sleep. |
| 430 | */ |
| 431 | static inline int |
| 432 | spi_read(struct spi_device *spi, u8 *buf, size_t len) |
| 433 | { |
| 434 | struct spi_transfer t = { |
| 435 | .tx_buf = NULL, |
| 436 | .rx_buf = buf, |
| 437 | .len = len, |
| 438 | .cs_change = 0, |
| 439 | }; |
| 440 | struct spi_message m = { |
| 441 | .transfers = &t, |
| 442 | .n_transfer = 1, |
| 443 | }; |
| 444 | |
| 445 | return spi_sync(spi, &m); |
| 446 | } |
| 447 | |
| 448 | extern int spi_write_then_read(struct spi_device *spi, |
| 449 | const u8 *txbuf, unsigned n_tx, |
| 450 | u8 *rxbuf, unsigned n_rx); |
| 451 | |
| 452 | /** |
| 453 | * spi_w8r8 - SPI synchronous 8 bit write followed by 8 bit read |
| 454 | * @spi: device with which data will be exchanged |
| 455 | * @cmd: command to be written before data is read back |
| 456 | * |
| 457 | * This returns the (unsigned) eight bit number returned by the |
| 458 | * device, or else a negative error code. Callable only from |
| 459 | * contexts that can sleep. |
| 460 | */ |
| 461 | static inline ssize_t spi_w8r8(struct spi_device *spi, u8 cmd) |
| 462 | { |
| 463 | ssize_t status; |
| 464 | u8 result; |
| 465 | |
| 466 | status = spi_write_then_read(spi, &cmd, 1, &result, 1); |
| 467 | |
| 468 | /* return negative errno or unsigned value */ |
| 469 | return (status < 0) ? status : result; |
| 470 | } |
| 471 | |
| 472 | /** |
| 473 | * spi_w8r16 - SPI synchronous 8 bit write followed by 16 bit read |
| 474 | * @spi: device with which data will be exchanged |
| 475 | * @cmd: command to be written before data is read back |
| 476 | * |
| 477 | * This returns the (unsigned) sixteen bit number returned by the |
| 478 | * device, or else a negative error code. Callable only from |
| 479 | * contexts that can sleep. |
| 480 | * |
| 481 | * The number is returned in wire-order, which is at least sometimes |
| 482 | * big-endian. |
| 483 | */ |
| 484 | static inline ssize_t spi_w8r16(struct spi_device *spi, u8 cmd) |
| 485 | { |
| 486 | ssize_t status; |
| 487 | u16 result; |
| 488 | |
| 489 | status = spi_write_then_read(spi, &cmd, 1, (u8 *) &result, 2); |
| 490 | |
| 491 | /* return negative errno or unsigned value */ |
| 492 | return (status < 0) ? status : result; |
| 493 | } |
| 494 | |
| 495 | /*---------------------------------------------------------------------------*/ |
| 496 | |
| 497 | /* |
| 498 | * INTERFACE between board init code and SPI infrastructure. |
| 499 | * |
| 500 | * No SPI driver ever sees these SPI device table segments, but |
| 501 | * it's how the SPI core (or adapters that get hotplugged) grows |
| 502 | * the driver model tree. |
| 503 | * |
| 504 | * As a rule, SPI devices can't be probed. Instead, board init code |
| 505 | * provides a table listing the devices which are present, with enough |
| 506 | * information to bind and set up the device's driver. There's basic |
| 507 | * support for nonstatic configurations too; enough to handle adding |
| 508 | * parport adapters, or microcontrollers acting as USB-to-SPI bridges. |
| 509 | */ |
| 510 | |
| 511 | /* board-specific information about each SPI device */ |
| 512 | struct spi_board_info { |
| 513 | /* the device name and module name are coupled, like platform_bus; |
| 514 | * "modalias" is normally the driver name. |
| 515 | * |
| 516 | * platform_data goes to spi_device.dev.platform_data, |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 517 | * controller_data goes to spi_device.controller_data, |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 518 | * irq is copied too |
| 519 | */ |
| 520 | char modalias[KOBJ_NAME_LEN]; |
| 521 | const void *platform_data; |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 522 | void *controller_data; |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 523 | int irq; |
| 524 | |
| 525 | /* slower signaling on noisy or low voltage boards */ |
| 526 | u32 max_speed_hz; |
| 527 | |
| 528 | |
| 529 | /* bus_num is board specific and matches the bus_num of some |
| 530 | * spi_master that will probably be registered later. |
| 531 | * |
| 532 | * chip_select reflects how this chip is wired to that master; |
| 533 | * it's less than num_chipselect. |
| 534 | */ |
| 535 | u16 bus_num; |
| 536 | u16 chip_select; |
| 537 | |
| 538 | /* ... may need additional spi_device chip config data here. |
| 539 | * avoid stuff protocol drivers can set; but include stuff |
| 540 | * needed to behave without being bound to a driver: |
| 541 | * - chipselect polarity |
| 542 | * - quirks like clock rate mattering when not selected |
| 543 | */ |
| 544 | }; |
| 545 | |
| 546 | #ifdef CONFIG_SPI |
| 547 | extern int |
| 548 | spi_register_board_info(struct spi_board_info const *info, unsigned n); |
| 549 | #else |
| 550 | /* board init code may ignore whether SPI is configured or not */ |
| 551 | static inline int |
| 552 | spi_register_board_info(struct spi_board_info const *info, unsigned n) |
| 553 | { return 0; } |
| 554 | #endif |
| 555 | |
| 556 | |
| 557 | /* If you're hotplugging an adapter with devices (parport, usb, etc) |
David Brownell | b885244 | 2006-01-08 13:34:23 -0800 | [diff] [blame^] | 558 | * use spi_new_device() to describe each device. You would then call |
| 559 | * spi_unregister_device() to start making that device vanish. |
David Brownell | 8ae12a0 | 2006-01-08 13:34:19 -0800 | [diff] [blame] | 560 | */ |
| 561 | extern struct spi_device * |
| 562 | spi_new_device(struct spi_master *, struct spi_board_info *); |
| 563 | |
| 564 | static inline void |
| 565 | spi_unregister_device(struct spi_device *spi) |
| 566 | { |
| 567 | if (spi) |
| 568 | device_unregister(&spi->dev); |
| 569 | } |
| 570 | |
| 571 | #endif /* __LINUX_SPI_H */ |