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