2 * spi.c - SPI init/core code
4 * Copyright (C) 2005 David Brownell
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
21 #include <linux/kernel.h>
22 #include <linux/device.h>
23 #include <linux/init.h>
24 #include <linux/cache.h>
25 #include <linux/mutex.h>
26 #include <linux/spi/spi.h>
29 /* SPI bustype and spi_master class are registered after board init code
30 * provides the SPI device tables, ensuring that both are present by the
31 * time controller driver registration causes spi_devices to "enumerate".
33 static void spidev_release(struct device
*dev
)
35 struct spi_device
*spi
= to_spi_device(dev
);
37 /* spi masters may cleanup for released devices */
38 if (spi
->master
->cleanup
)
39 spi
->master
->cleanup(spi
);
41 spi_master_put(spi
->master
);
46 modalias_show(struct device
*dev
, struct device_attribute
*a
, char *buf
)
48 const struct spi_device
*spi
= to_spi_device(dev
);
50 return snprintf(buf
, BUS_ID_SIZE
+ 1, "%s\n", spi
->modalias
);
53 static struct device_attribute spi_dev_attrs
[] = {
58 /* modalias support makes "modprobe $MODALIAS" new-style hotplug work,
59 * and the sysfs version makes coldplug work too.
62 static int spi_match_device(struct device
*dev
, struct device_driver
*drv
)
64 const struct spi_device
*spi
= to_spi_device(dev
);
66 return strncmp(spi
->modalias
, drv
->name
, BUS_ID_SIZE
) == 0;
69 static int spi_uevent(struct device
*dev
, struct kobj_uevent_env
*env
)
71 const struct spi_device
*spi
= to_spi_device(dev
);
73 add_uevent_var(env
, "MODALIAS=%s", spi
->modalias
);
79 static int spi_suspend(struct device
*dev
, pm_message_t message
)
82 struct spi_driver
*drv
= to_spi_driver(dev
->driver
);
84 /* suspend will stop irqs and dma; no more i/o */
87 value
= drv
->suspend(to_spi_device(dev
), message
);
89 dev_dbg(dev
, "... can't suspend\n");
94 static int spi_resume(struct device
*dev
)
97 struct spi_driver
*drv
= to_spi_driver(dev
->driver
);
99 /* resume may restart the i/o queue */
102 value
= drv
->resume(to_spi_device(dev
));
104 dev_dbg(dev
, "... can't resume\n");
110 #define spi_suspend NULL
111 #define spi_resume NULL
114 struct bus_type spi_bus_type
= {
116 .dev_attrs
= spi_dev_attrs
,
117 .match
= spi_match_device
,
118 .uevent
= spi_uevent
,
119 .suspend
= spi_suspend
,
120 .resume
= spi_resume
,
122 EXPORT_SYMBOL_GPL(spi_bus_type
);
125 static int spi_drv_probe(struct device
*dev
)
127 const struct spi_driver
*sdrv
= to_spi_driver(dev
->driver
);
129 return sdrv
->probe(to_spi_device(dev
));
132 static int spi_drv_remove(struct device
*dev
)
134 const struct spi_driver
*sdrv
= to_spi_driver(dev
->driver
);
136 return sdrv
->remove(to_spi_device(dev
));
139 static void spi_drv_shutdown(struct device
*dev
)
141 const struct spi_driver
*sdrv
= to_spi_driver(dev
->driver
);
143 sdrv
->shutdown(to_spi_device(dev
));
147 * spi_register_driver - register a SPI driver
148 * @sdrv: the driver to register
151 int spi_register_driver(struct spi_driver
*sdrv
)
153 sdrv
->driver
.bus
= &spi_bus_type
;
155 sdrv
->driver
.probe
= spi_drv_probe
;
157 sdrv
->driver
.remove
= spi_drv_remove
;
159 sdrv
->driver
.shutdown
= spi_drv_shutdown
;
160 return driver_register(&sdrv
->driver
);
162 EXPORT_SYMBOL_GPL(spi_register_driver
);
164 /*-------------------------------------------------------------------------*/
166 /* SPI devices should normally not be created by SPI device drivers; that
167 * would make them board-specific. Similarly with SPI master drivers.
168 * Device registration normally goes into like arch/.../mach.../board-YYY.c
169 * with other readonly (flashable) information about mainboard devices.
173 struct list_head list
;
174 unsigned n_board_info
;
175 struct spi_board_info board_info
[0];
178 static LIST_HEAD(board_list
);
179 static DEFINE_MUTEX(board_lock
);
183 * spi_new_device - instantiate one new SPI device
184 * @master: Controller to which device is connected
185 * @chip: Describes the SPI device
188 * On typical mainboards, this is purely internal; and it's not needed
189 * after board init creates the hard-wired devices. Some development
190 * platforms may not be able to use spi_register_board_info though, and
191 * this is exported so that for example a USB or parport based adapter
192 * driver could add devices (which it would learn about out-of-band).
194 * Returns the new device, or NULL.
196 struct spi_device
*spi_new_device(struct spi_master
*master
,
197 struct spi_board_info
*chip
)
199 struct spi_device
*proxy
;
200 struct device
*dev
= master
->dev
.parent
;
203 /* NOTE: caller did any chip->bus_num checks necessary.
205 * Also, unless we change the return value convention to use
206 * error-or-pointer (not NULL-or-pointer), troubleshootability
207 * suggests syslogged diagnostics are best here (ugh).
210 /* Chipselects are numbered 0..max; validate. */
211 if (chip
->chip_select
>= master
->num_chipselect
) {
212 dev_err(dev
, "cs%d > max %d\n",
214 master
->num_chipselect
);
218 if (!spi_master_get(master
))
221 WARN_ON(strlen(chip
->modalias
) >= sizeof(proxy
->modalias
));
223 proxy
= kzalloc(sizeof *proxy
, GFP_KERNEL
);
225 dev_err(dev
, "can't alloc dev for cs%d\n",
229 proxy
->master
= master
;
230 proxy
->chip_select
= chip
->chip_select
;
231 proxy
->max_speed_hz
= chip
->max_speed_hz
;
232 proxy
->mode
= chip
->mode
;
233 proxy
->irq
= chip
->irq
;
234 strlcpy(proxy
->modalias
, chip
->modalias
, sizeof(proxy
->modalias
));
236 snprintf(proxy
->dev
.bus_id
, sizeof proxy
->dev
.bus_id
,
237 "%s.%u", master
->dev
.bus_id
,
239 proxy
->dev
.parent
= dev
;
240 proxy
->dev
.bus
= &spi_bus_type
;
241 proxy
->dev
.platform_data
= (void *) chip
->platform_data
;
242 proxy
->controller_data
= chip
->controller_data
;
243 proxy
->controller_state
= NULL
;
244 proxy
->dev
.release
= spidev_release
;
246 /* drivers may modify this initial i/o setup */
247 status
= master
->setup(proxy
);
249 dev_err(dev
, "can't %s %s, status %d\n",
250 "setup", proxy
->dev
.bus_id
, status
);
254 /* driver core catches callers that misbehave by defining
255 * devices that already exist.
257 status
= device_register(&proxy
->dev
);
259 dev_err(dev
, "can't %s %s, status %d\n",
260 "add", proxy
->dev
.bus_id
, status
);
263 dev_dbg(dev
, "registered child %s\n", proxy
->dev
.bus_id
);
267 spi_master_put(master
);
271 EXPORT_SYMBOL_GPL(spi_new_device
);
274 * spi_register_board_info - register SPI devices for a given board
275 * @info: array of chip descriptors
276 * @n: how many descriptors are provided
279 * Board-specific early init code calls this (probably during arch_initcall)
280 * with segments of the SPI device table. Any device nodes are created later,
281 * after the relevant parent SPI controller (bus_num) is defined. We keep
282 * this table of devices forever, so that reloading a controller driver will
283 * not make Linux forget about these hard-wired devices.
285 * Other code can also call this, e.g. a particular add-on board might provide
286 * SPI devices through its expansion connector, so code initializing that board
287 * would naturally declare its SPI devices.
289 * The board info passed can safely be __initdata ... but be careful of
290 * any embedded pointers (platform_data, etc), they're copied as-is.
293 spi_register_board_info(struct spi_board_info
const *info
, unsigned n
)
295 struct boardinfo
*bi
;
297 bi
= kmalloc(sizeof(*bi
) + n
* sizeof *info
, GFP_KERNEL
);
300 bi
->n_board_info
= n
;
301 memcpy(bi
->board_info
, info
, n
* sizeof *info
);
303 mutex_lock(&board_lock
);
304 list_add_tail(&bi
->list
, &board_list
);
305 mutex_unlock(&board_lock
);
309 /* FIXME someone should add support for a __setup("spi", ...) that
310 * creates board info from kernel command lines
313 static void scan_boardinfo(struct spi_master
*master
)
315 struct boardinfo
*bi
;
317 mutex_lock(&board_lock
);
318 list_for_each_entry(bi
, &board_list
, list
) {
319 struct spi_board_info
*chip
= bi
->board_info
;
322 for (n
= bi
->n_board_info
; n
> 0; n
--, chip
++) {
323 if (chip
->bus_num
!= master
->bus_num
)
325 /* NOTE: this relies on spi_new_device to
326 * issue diagnostics when given bogus inputs
328 (void) spi_new_device(master
, chip
);
331 mutex_unlock(&board_lock
);
334 /*-------------------------------------------------------------------------*/
336 static void spi_master_release(struct device
*dev
)
338 struct spi_master
*master
;
340 master
= container_of(dev
, struct spi_master
, dev
);
344 static struct class spi_master_class
= {
345 .name
= "spi_master",
346 .owner
= THIS_MODULE
,
347 .dev_release
= spi_master_release
,
352 * spi_alloc_master - allocate SPI master controller
353 * @dev: the controller, possibly using the platform_bus
354 * @size: how much zeroed driver-private data to allocate; the pointer to this
355 * memory is in the driver_data field of the returned device,
356 * accessible with spi_master_get_devdata().
359 * This call is used only by SPI master controller drivers, which are the
360 * only ones directly touching chip registers. It's how they allocate
361 * an spi_master structure, prior to calling spi_register_master().
363 * This must be called from context that can sleep. It returns the SPI
364 * master structure on success, else NULL.
366 * The caller is responsible for assigning the bus number and initializing
367 * the master's methods before calling spi_register_master(); and (after errors
368 * adding the device) calling spi_master_put() to prevent a memory leak.
370 struct spi_master
*spi_alloc_master(struct device
*dev
, unsigned size
)
372 struct spi_master
*master
;
377 master
= kzalloc(size
+ sizeof *master
, GFP_KERNEL
);
381 device_initialize(&master
->dev
);
382 master
->dev
.class = &spi_master_class
;
383 master
->dev
.parent
= get_device(dev
);
384 spi_master_set_devdata(master
, &master
[1]);
388 EXPORT_SYMBOL_GPL(spi_alloc_master
);
391 * spi_register_master - register SPI master controller
392 * @master: initialized master, originally from spi_alloc_master()
395 * SPI master controllers connect to their drivers using some non-SPI bus,
396 * such as the platform bus. The final stage of probe() in that code
397 * includes calling spi_register_master() to hook up to this SPI bus glue.
399 * SPI controllers use board specific (often SOC specific) bus numbers,
400 * and board-specific addressing for SPI devices combines those numbers
401 * with chip select numbers. Since SPI does not directly support dynamic
402 * device identification, boards need configuration tables telling which
403 * chip is at which address.
405 * This must be called from context that can sleep. It returns zero on
406 * success, else a negative error code (dropping the master's refcount).
407 * After a successful return, the caller is responsible for calling
408 * spi_unregister_master().
410 int spi_register_master(struct spi_master
*master
)
412 static atomic_t dyn_bus_id
= ATOMIC_INIT((1<<15) - 1);
413 struct device
*dev
= master
->dev
.parent
;
414 int status
= -ENODEV
;
420 /* even if it's just one always-selected device, there must
421 * be at least one chipselect
423 if (master
->num_chipselect
== 0)
426 /* convention: dynamically assigned bus IDs count down from the max */
427 if (master
->bus_num
< 0) {
428 /* FIXME switch to an IDR based scheme, something like
429 * I2C now uses, so we can't run out of "dynamic" IDs
431 master
->bus_num
= atomic_dec_return(&dyn_bus_id
);
435 /* register the device, then userspace will see it.
436 * registration fails if the bus ID is in use.
438 snprintf(master
->dev
.bus_id
, sizeof master
->dev
.bus_id
,
439 "spi%u", master
->bus_num
);
440 status
= device_add(&master
->dev
);
443 dev_dbg(dev
, "registered master %s%s\n", master
->dev
.bus_id
,
444 dynamic
? " (dynamic)" : "");
446 /* populate children from any spi device tables */
447 scan_boardinfo(master
);
452 EXPORT_SYMBOL_GPL(spi_register_master
);
455 static int __unregister(struct device
*dev
, void *master_dev
)
457 /* note: before about 2.6.14-rc1 this would corrupt memory: */
458 if (dev
!= master_dev
)
459 spi_unregister_device(to_spi_device(dev
));
464 * spi_unregister_master - unregister SPI master controller
465 * @master: the master being unregistered
468 * This call is used only by SPI master controller drivers, which are the
469 * only ones directly touching chip registers.
471 * This must be called from context that can sleep.
473 void spi_unregister_master(struct spi_master
*master
)
477 dummy
= device_for_each_child(master
->dev
.parent
, &master
->dev
,
479 device_unregister(&master
->dev
);
481 EXPORT_SYMBOL_GPL(spi_unregister_master
);
483 static int __spi_master_match(struct device
*dev
, void *data
)
485 struct spi_master
*m
;
488 m
= container_of(dev
, struct spi_master
, dev
);
489 return m
->bus_num
== *bus_num
;
493 * spi_busnum_to_master - look up master associated with bus_num
494 * @bus_num: the master's bus number
497 * This call may be used with devices that are registered after
498 * arch init time. It returns a refcounted pointer to the relevant
499 * spi_master (which the caller must release), or NULL if there is
500 * no such master registered.
502 struct spi_master
*spi_busnum_to_master(u16 bus_num
)
505 struct spi_master
*master
= NULL
;
507 dev
= class_find_device(&spi_master_class
, NULL
, &bus_num
,
510 master
= container_of(dev
, struct spi_master
, dev
);
511 /* reference got in class_find_device */
514 EXPORT_SYMBOL_GPL(spi_busnum_to_master
);
517 /*-------------------------------------------------------------------------*/
519 static void spi_complete(void *arg
)
525 * spi_sync - blocking/synchronous SPI data transfers
526 * @spi: device with which data will be exchanged
527 * @message: describes the data transfers
530 * This call may only be used from a context that may sleep. The sleep
531 * is non-interruptible, and has no timeout. Low-overhead controller
532 * drivers may DMA directly into and out of the message buffers.
534 * Note that the SPI device's chip select is active during the message,
535 * and then is normally disabled between messages. Drivers for some
536 * frequently-used devices may want to minimize costs of selecting a chip,
537 * by leaving it selected in anticipation that the next message will go
538 * to the same chip. (That may increase power usage.)
540 * Also, the caller is guaranteeing that the memory associated with the
541 * message will not be freed before this call returns.
543 * It returns zero on success, else a negative error code.
545 int spi_sync(struct spi_device
*spi
, struct spi_message
*message
)
547 DECLARE_COMPLETION_ONSTACK(done
);
550 message
->complete
= spi_complete
;
551 message
->context
= &done
;
552 status
= spi_async(spi
, message
);
554 wait_for_completion(&done
);
555 status
= message
->status
;
557 message
->context
= NULL
;
560 EXPORT_SYMBOL_GPL(spi_sync
);
562 /* portable code must never pass more than 32 bytes */
563 #define SPI_BUFSIZ max(32,SMP_CACHE_BYTES)
568 * spi_write_then_read - SPI synchronous write followed by read
569 * @spi: device with which data will be exchanged
570 * @txbuf: data to be written (need not be dma-safe)
571 * @n_tx: size of txbuf, in bytes
572 * @rxbuf: buffer into which data will be read
573 * @n_rx: size of rxbuf, in bytes (need not be dma-safe)
576 * This performs a half duplex MicroWire style transaction with the
577 * device, sending txbuf and then reading rxbuf. The return value
578 * is zero for success, else a negative errno status code.
579 * This call may only be used from a context that may sleep.
581 * Parameters to this routine are always copied using a small buffer;
582 * portable code should never use this for more than 32 bytes.
583 * Performance-sensitive or bulk transfer code should instead use
584 * spi_{async,sync}() calls with dma-safe buffers.
586 int spi_write_then_read(struct spi_device
*spi
,
587 const u8
*txbuf
, unsigned n_tx
,
588 u8
*rxbuf
, unsigned n_rx
)
590 static DEFINE_MUTEX(lock
);
593 struct spi_message message
;
594 struct spi_transfer x
[2];
597 /* Use preallocated DMA-safe buffer. We can't avoid copying here,
598 * (as a pure convenience thing), but we can keep heap costs
599 * out of the hot path ...
601 if ((n_tx
+ n_rx
) > SPI_BUFSIZ
)
604 spi_message_init(&message
);
605 memset(x
, 0, sizeof x
);
608 spi_message_add_tail(&x
[0], &message
);
612 spi_message_add_tail(&x
[1], &message
);
615 /* ... unless someone else is using the pre-allocated buffer */
616 if (!mutex_trylock(&lock
)) {
617 local_buf
= kmalloc(SPI_BUFSIZ
, GFP_KERNEL
);
623 memcpy(local_buf
, txbuf
, n_tx
);
624 x
[0].tx_buf
= local_buf
;
625 x
[1].rx_buf
= local_buf
+ n_tx
;
628 status
= spi_sync(spi
, &message
);
630 memcpy(rxbuf
, x
[1].rx_buf
, n_rx
);
632 if (x
[0].tx_buf
== buf
)
639 EXPORT_SYMBOL_GPL(spi_write_then_read
);
641 /*-------------------------------------------------------------------------*/
643 static int __init
spi_init(void)
647 buf
= kmalloc(SPI_BUFSIZ
, GFP_KERNEL
);
653 status
= bus_register(&spi_bus_type
);
657 status
= class_register(&spi_master_class
);
663 bus_unregister(&spi_bus_type
);
671 /* board_info is normally registered in arch_initcall(),
672 * but even essential drivers wait till later
674 * REVISIT only boardinfo really needs static linking. the rest (device and
675 * driver registration) _could_ be dynamically linked (modular) ... costs
676 * include needing to have boardinfo data structures be much more public.
678 subsys_initcall(spi_init
);