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
);
182 * spi_alloc_device - Allocate a new SPI device
183 * @master: Controller to which device is connected
186 * Allows a driver to allocate and initialize a spi_device without
187 * registering it immediately. This allows a driver to directly
188 * fill the spi_device with device parameters before calling
189 * spi_add_device() on it.
191 * Caller is responsible to call spi_add_device() on the returned
192 * spi_device structure to add it to the SPI master. If the caller
193 * needs to discard the spi_device without adding it, then it should
194 * call spi_dev_put() on it.
196 * Returns a pointer to the new device, or NULL.
198 struct spi_device
*spi_alloc_device(struct spi_master
*master
)
200 struct spi_device
*spi
;
201 struct device
*dev
= master
->dev
.parent
;
203 if (!spi_master_get(master
))
206 spi
= kzalloc(sizeof *spi
, GFP_KERNEL
);
208 dev_err(dev
, "cannot alloc spi_device\n");
209 spi_master_put(master
);
213 spi
->master
= master
;
214 spi
->dev
.parent
= dev
;
215 spi
->dev
.bus
= &spi_bus_type
;
216 spi
->dev
.release
= spidev_release
;
217 device_initialize(&spi
->dev
);
220 EXPORT_SYMBOL_GPL(spi_alloc_device
);
223 * spi_add_device - Add spi_device allocated with spi_alloc_device
224 * @spi: spi_device to register
226 * Companion function to spi_alloc_device. Devices allocated with
227 * spi_alloc_device can be added onto the spi bus with this function.
229 * Returns 0 on success; non-zero on failure
231 int spi_add_device(struct spi_device
*spi
)
233 struct device
*dev
= spi
->master
->dev
.parent
;
236 /* Chipselects are numbered 0..max; validate. */
237 if (spi
->chip_select
>= spi
->master
->num_chipselect
) {
238 dev_err(dev
, "cs%d >= max %d\n",
240 spi
->master
->num_chipselect
);
244 /* Set the bus ID string */
245 snprintf(spi
->dev
.bus_id
, sizeof spi
->dev
.bus_id
,
246 "%s.%u", spi
->master
->dev
.bus_id
,
249 /* drivers may modify this initial i/o setup */
250 status
= spi
->master
->setup(spi
);
252 dev_err(dev
, "can't %s %s, status %d\n",
253 "setup", spi
->dev
.bus_id
, status
);
257 /* driver core catches callers that misbehave by defining
258 * devices that already exist.
260 status
= device_add(&spi
->dev
);
262 dev_err(dev
, "can't %s %s, status %d\n",
263 "add", spi
->dev
.bus_id
, status
);
267 dev_dbg(dev
, "registered child %s\n", spi
->dev
.bus_id
);
270 EXPORT_SYMBOL_GPL(spi_add_device
);
273 * spi_new_device - instantiate one new SPI device
274 * @master: Controller to which device is connected
275 * @chip: Describes the SPI device
278 * On typical mainboards, this is purely internal; and it's not needed
279 * after board init creates the hard-wired devices. Some development
280 * platforms may not be able to use spi_register_board_info though, and
281 * this is exported so that for example a USB or parport based adapter
282 * driver could add devices (which it would learn about out-of-band).
284 * Returns the new device, or NULL.
286 struct spi_device
*spi_new_device(struct spi_master
*master
,
287 struct spi_board_info
*chip
)
289 struct spi_device
*proxy
;
292 /* NOTE: caller did any chip->bus_num checks necessary.
294 * Also, unless we change the return value convention to use
295 * error-or-pointer (not NULL-or-pointer), troubleshootability
296 * suggests syslogged diagnostics are best here (ugh).
299 proxy
= spi_alloc_device(master
);
303 WARN_ON(strlen(chip
->modalias
) >= sizeof(proxy
->modalias
));
305 proxy
->chip_select
= chip
->chip_select
;
306 proxy
->max_speed_hz
= chip
->max_speed_hz
;
307 proxy
->mode
= chip
->mode
;
308 proxy
->irq
= chip
->irq
;
309 strlcpy(proxy
->modalias
, chip
->modalias
, sizeof(proxy
->modalias
));
310 proxy
->dev
.platform_data
= (void *) chip
->platform_data
;
311 proxy
->controller_data
= chip
->controller_data
;
312 proxy
->controller_state
= NULL
;
314 status
= spi_add_device(proxy
);
322 EXPORT_SYMBOL_GPL(spi_new_device
);
325 * spi_register_board_info - register SPI devices for a given board
326 * @info: array of chip descriptors
327 * @n: how many descriptors are provided
330 * Board-specific early init code calls this (probably during arch_initcall)
331 * with segments of the SPI device table. Any device nodes are created later,
332 * after the relevant parent SPI controller (bus_num) is defined. We keep
333 * this table of devices forever, so that reloading a controller driver will
334 * not make Linux forget about these hard-wired devices.
336 * Other code can also call this, e.g. a particular add-on board might provide
337 * SPI devices through its expansion connector, so code initializing that board
338 * would naturally declare its SPI devices.
340 * The board info passed can safely be __initdata ... but be careful of
341 * any embedded pointers (platform_data, etc), they're copied as-is.
344 spi_register_board_info(struct spi_board_info
const *info
, unsigned n
)
346 struct boardinfo
*bi
;
348 bi
= kmalloc(sizeof(*bi
) + n
* sizeof *info
, GFP_KERNEL
);
351 bi
->n_board_info
= n
;
352 memcpy(bi
->board_info
, info
, n
* sizeof *info
);
354 mutex_lock(&board_lock
);
355 list_add_tail(&bi
->list
, &board_list
);
356 mutex_unlock(&board_lock
);
360 /* FIXME someone should add support for a __setup("spi", ...) that
361 * creates board info from kernel command lines
364 static void scan_boardinfo(struct spi_master
*master
)
366 struct boardinfo
*bi
;
368 mutex_lock(&board_lock
);
369 list_for_each_entry(bi
, &board_list
, list
) {
370 struct spi_board_info
*chip
= bi
->board_info
;
373 for (n
= bi
->n_board_info
; n
> 0; n
--, chip
++) {
374 if (chip
->bus_num
!= master
->bus_num
)
376 /* NOTE: this relies on spi_new_device to
377 * issue diagnostics when given bogus inputs
379 (void) spi_new_device(master
, chip
);
382 mutex_unlock(&board_lock
);
385 /*-------------------------------------------------------------------------*/
387 static void spi_master_release(struct device
*dev
)
389 struct spi_master
*master
;
391 master
= container_of(dev
, struct spi_master
, dev
);
395 static struct class spi_master_class
= {
396 .name
= "spi_master",
397 .owner
= THIS_MODULE
,
398 .dev_release
= spi_master_release
,
403 * spi_alloc_master - allocate SPI master controller
404 * @dev: the controller, possibly using the platform_bus
405 * @size: how much zeroed driver-private data to allocate; the pointer to this
406 * memory is in the driver_data field of the returned device,
407 * accessible with spi_master_get_devdata().
410 * This call is used only by SPI master controller drivers, which are the
411 * only ones directly touching chip registers. It's how they allocate
412 * an spi_master structure, prior to calling spi_register_master().
414 * This must be called from context that can sleep. It returns the SPI
415 * master structure on success, else NULL.
417 * The caller is responsible for assigning the bus number and initializing
418 * the master's methods before calling spi_register_master(); and (after errors
419 * adding the device) calling spi_master_put() to prevent a memory leak.
421 struct spi_master
*spi_alloc_master(struct device
*dev
, unsigned size
)
423 struct spi_master
*master
;
428 master
= kzalloc(size
+ sizeof *master
, GFP_KERNEL
);
432 device_initialize(&master
->dev
);
433 master
->dev
.class = &spi_master_class
;
434 master
->dev
.parent
= get_device(dev
);
435 spi_master_set_devdata(master
, &master
[1]);
439 EXPORT_SYMBOL_GPL(spi_alloc_master
);
442 * spi_register_master - register SPI master controller
443 * @master: initialized master, originally from spi_alloc_master()
446 * SPI master controllers connect to their drivers using some non-SPI bus,
447 * such as the platform bus. The final stage of probe() in that code
448 * includes calling spi_register_master() to hook up to this SPI bus glue.
450 * SPI controllers use board specific (often SOC specific) bus numbers,
451 * and board-specific addressing for SPI devices combines those numbers
452 * with chip select numbers. Since SPI does not directly support dynamic
453 * device identification, boards need configuration tables telling which
454 * chip is at which address.
456 * This must be called from context that can sleep. It returns zero on
457 * success, else a negative error code (dropping the master's refcount).
458 * After a successful return, the caller is responsible for calling
459 * spi_unregister_master().
461 int spi_register_master(struct spi_master
*master
)
463 static atomic_t dyn_bus_id
= ATOMIC_INIT((1<<15) - 1);
464 struct device
*dev
= master
->dev
.parent
;
465 int status
= -ENODEV
;
471 /* even if it's just one always-selected device, there must
472 * be at least one chipselect
474 if (master
->num_chipselect
== 0)
477 /* convention: dynamically assigned bus IDs count down from the max */
478 if (master
->bus_num
< 0) {
479 /* FIXME switch to an IDR based scheme, something like
480 * I2C now uses, so we can't run out of "dynamic" IDs
482 master
->bus_num
= atomic_dec_return(&dyn_bus_id
);
486 /* register the device, then userspace will see it.
487 * registration fails if the bus ID is in use.
489 snprintf(master
->dev
.bus_id
, sizeof master
->dev
.bus_id
,
490 "spi%u", master
->bus_num
);
491 status
= device_add(&master
->dev
);
494 dev_dbg(dev
, "registered master %s%s\n", master
->dev
.bus_id
,
495 dynamic
? " (dynamic)" : "");
497 /* populate children from any spi device tables */
498 scan_boardinfo(master
);
503 EXPORT_SYMBOL_GPL(spi_register_master
);
506 static int __unregister(struct device
*dev
, void *master_dev
)
508 /* note: before about 2.6.14-rc1 this would corrupt memory: */
509 if (dev
!= master_dev
)
510 spi_unregister_device(to_spi_device(dev
));
515 * spi_unregister_master - unregister SPI master controller
516 * @master: the master being unregistered
519 * This call is used only by SPI master controller drivers, which are the
520 * only ones directly touching chip registers.
522 * This must be called from context that can sleep.
524 void spi_unregister_master(struct spi_master
*master
)
528 dummy
= device_for_each_child(master
->dev
.parent
, &master
->dev
,
530 device_unregister(&master
->dev
);
532 EXPORT_SYMBOL_GPL(spi_unregister_master
);
534 static int __spi_master_match(struct device
*dev
, void *data
)
536 struct spi_master
*m
;
539 m
= container_of(dev
, struct spi_master
, dev
);
540 return m
->bus_num
== *bus_num
;
544 * spi_busnum_to_master - look up master associated with bus_num
545 * @bus_num: the master's bus number
548 * This call may be used with devices that are registered after
549 * arch init time. It returns a refcounted pointer to the relevant
550 * spi_master (which the caller must release), or NULL if there is
551 * no such master registered.
553 struct spi_master
*spi_busnum_to_master(u16 bus_num
)
556 struct spi_master
*master
= NULL
;
558 dev
= class_find_device(&spi_master_class
, NULL
, &bus_num
,
561 master
= container_of(dev
, struct spi_master
, dev
);
562 /* reference got in class_find_device */
565 EXPORT_SYMBOL_GPL(spi_busnum_to_master
);
568 /*-------------------------------------------------------------------------*/
570 static void spi_complete(void *arg
)
576 * spi_sync - blocking/synchronous SPI data transfers
577 * @spi: device with which data will be exchanged
578 * @message: describes the data transfers
581 * This call may only be used from a context that may sleep. The sleep
582 * is non-interruptible, and has no timeout. Low-overhead controller
583 * drivers may DMA directly into and out of the message buffers.
585 * Note that the SPI device's chip select is active during the message,
586 * and then is normally disabled between messages. Drivers for some
587 * frequently-used devices may want to minimize costs of selecting a chip,
588 * by leaving it selected in anticipation that the next message will go
589 * to the same chip. (That may increase power usage.)
591 * Also, the caller is guaranteeing that the memory associated with the
592 * message will not be freed before this call returns.
594 * It returns zero on success, else a negative error code.
596 int spi_sync(struct spi_device
*spi
, struct spi_message
*message
)
598 DECLARE_COMPLETION_ONSTACK(done
);
601 message
->complete
= spi_complete
;
602 message
->context
= &done
;
603 status
= spi_async(spi
, message
);
605 wait_for_completion(&done
);
606 status
= message
->status
;
608 message
->context
= NULL
;
611 EXPORT_SYMBOL_GPL(spi_sync
);
613 /* portable code must never pass more than 32 bytes */
614 #define SPI_BUFSIZ max(32,SMP_CACHE_BYTES)
619 * spi_write_then_read - SPI synchronous write followed by read
620 * @spi: device with which data will be exchanged
621 * @txbuf: data to be written (need not be dma-safe)
622 * @n_tx: size of txbuf, in bytes
623 * @rxbuf: buffer into which data will be read
624 * @n_rx: size of rxbuf, in bytes (need not be dma-safe)
627 * This performs a half duplex MicroWire style transaction with the
628 * device, sending txbuf and then reading rxbuf. The return value
629 * is zero for success, else a negative errno status code.
630 * This call may only be used from a context that may sleep.
632 * Parameters to this routine are always copied using a small buffer;
633 * portable code should never use this for more than 32 bytes.
634 * Performance-sensitive or bulk transfer code should instead use
635 * spi_{async,sync}() calls with dma-safe buffers.
637 int spi_write_then_read(struct spi_device
*spi
,
638 const u8
*txbuf
, unsigned n_tx
,
639 u8
*rxbuf
, unsigned n_rx
)
641 static DEFINE_MUTEX(lock
);
644 struct spi_message message
;
645 struct spi_transfer x
[2];
648 /* Use preallocated DMA-safe buffer. We can't avoid copying here,
649 * (as a pure convenience thing), but we can keep heap costs
650 * out of the hot path ...
652 if ((n_tx
+ n_rx
) > SPI_BUFSIZ
)
655 spi_message_init(&message
);
656 memset(x
, 0, sizeof x
);
659 spi_message_add_tail(&x
[0], &message
);
663 spi_message_add_tail(&x
[1], &message
);
666 /* ... unless someone else is using the pre-allocated buffer */
667 if (!mutex_trylock(&lock
)) {
668 local_buf
= kmalloc(SPI_BUFSIZ
, GFP_KERNEL
);
674 memcpy(local_buf
, txbuf
, n_tx
);
675 x
[0].tx_buf
= local_buf
;
676 x
[1].rx_buf
= local_buf
+ n_tx
;
679 status
= spi_sync(spi
, &message
);
681 memcpy(rxbuf
, x
[1].rx_buf
, n_rx
);
683 if (x
[0].tx_buf
== buf
)
690 EXPORT_SYMBOL_GPL(spi_write_then_read
);
692 /*-------------------------------------------------------------------------*/
694 static int __init
spi_init(void)
698 buf
= kmalloc(SPI_BUFSIZ
, GFP_KERNEL
);
704 status
= bus_register(&spi_bus_type
);
708 status
= class_register(&spi_master_class
);
714 bus_unregister(&spi_bus_type
);
722 /* board_info is normally registered in arch_initcall(),
723 * but even essential drivers wait till later
725 * REVISIT only boardinfo really needs static linking. the rest (device and
726 * driver registration) _could_ be dynamically linked (modular) ... costs
727 * include needing to have boardinfo data structures be much more public.
729 subsys_initcall(spi_init
);