1 /* 2 * spi.c - SPI init/core code 3 * 4 * Copyright (C) 2005 David Brownell 5 * 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. 10 * 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. 15 * 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. 19 */ 20 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> 27 28 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". 32 */ 33 static void spidev_release(struct device *dev) 34 { 35 struct spi_device *spi = to_spi_device(dev); 36 37 /* spi masters may cleanup for released devices */ 38 if (spi->master->cleanup) 39 spi->master->cleanup(spi); 40 41 spi_master_put(spi->master); 42 kfree(dev); 43 } 44 45 static ssize_t 46 modalias_show(struct device *dev, struct device_attribute *a, char *buf) 47 { 48 const struct spi_device *spi = to_spi_device(dev); 49 50 return snprintf(buf, BUS_ID_SIZE + 1, "%s\n", spi->modalias); 51 } 52 53 static struct device_attribute spi_dev_attrs[] = { 54 __ATTR_RO(modalias), 55 __ATTR_NULL, 56 }; 57 58 /* modalias support makes "modprobe $MODALIAS" new-style hotplug work, 59 * and the sysfs version makes coldplug work too. 60 */ 61 62 static int spi_match_device(struct device *dev, struct device_driver *drv) 63 { 64 const struct spi_device *spi = to_spi_device(dev); 65 66 return strncmp(spi->modalias, drv->name, BUS_ID_SIZE) == 0; 67 } 68 69 static int spi_uevent(struct device *dev, struct kobj_uevent_env *env) 70 { 71 const struct spi_device *spi = to_spi_device(dev); 72 73 add_uevent_var(env, "MODALIAS=%s", spi->modalias); 74 return 0; 75 } 76 77 #ifdef CONFIG_PM 78 79 static int spi_suspend(struct device *dev, pm_message_t message) 80 { 81 int value = 0; 82 struct spi_driver *drv = to_spi_driver(dev->driver); 83 84 /* suspend will stop irqs and dma; no more i/o */ 85 if (drv) { 86 if (drv->suspend) 87 value = drv->suspend(to_spi_device(dev), message); 88 else 89 dev_dbg(dev, "... can't suspend\n"); 90 } 91 return value; 92 } 93 94 static int spi_resume(struct device *dev) 95 { 96 int value = 0; 97 struct spi_driver *drv = to_spi_driver(dev->driver); 98 99 /* resume may restart the i/o queue */ 100 if (drv) { 101 if (drv->resume) 102 value = drv->resume(to_spi_device(dev)); 103 else 104 dev_dbg(dev, "... can't resume\n"); 105 } 106 return value; 107 } 108 109 #else 110 #define spi_suspend NULL 111 #define spi_resume NULL 112 #endif 113 114 struct bus_type spi_bus_type = { 115 .name = "spi", 116 .dev_attrs = spi_dev_attrs, 117 .match = spi_match_device, 118 .uevent = spi_uevent, 119 .suspend = spi_suspend, 120 .resume = spi_resume, 121 }; 122 EXPORT_SYMBOL_GPL(spi_bus_type); 123 124 125 static int spi_drv_probe(struct device *dev) 126 { 127 const struct spi_driver *sdrv = to_spi_driver(dev->driver); 128 129 return sdrv->probe(to_spi_device(dev)); 130 } 131 132 static int spi_drv_remove(struct device *dev) 133 { 134 const struct spi_driver *sdrv = to_spi_driver(dev->driver); 135 136 return sdrv->remove(to_spi_device(dev)); 137 } 138 139 static void spi_drv_shutdown(struct device *dev) 140 { 141 const struct spi_driver *sdrv = to_spi_driver(dev->driver); 142 143 sdrv->shutdown(to_spi_device(dev)); 144 } 145 146 /** 147 * spi_register_driver - register a SPI driver 148 * @sdrv: the driver to register 149 * Context: can sleep 150 */ 151 int spi_register_driver(struct spi_driver *sdrv) 152 { 153 sdrv->driver.bus = &spi_bus_type; 154 if (sdrv->probe) 155 sdrv->driver.probe = spi_drv_probe; 156 if (sdrv->remove) 157 sdrv->driver.remove = spi_drv_remove; 158 if (sdrv->shutdown) 159 sdrv->driver.shutdown = spi_drv_shutdown; 160 return driver_register(&sdrv->driver); 161 } 162 EXPORT_SYMBOL_GPL(spi_register_driver); 163 164 /*-------------------------------------------------------------------------*/ 165 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. 170 */ 171 172 struct boardinfo { 173 struct list_head list; 174 unsigned n_board_info; 175 struct spi_board_info board_info[0]; 176 }; 177 178 static LIST_HEAD(board_list); 179 static DEFINE_MUTEX(board_lock); 180 181 182 /** 183 * spi_new_device - instantiate one new SPI device 184 * @master: Controller to which device is connected 185 * @chip: Describes the SPI device 186 * Context: can sleep 187 * 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). 193 * 194 * Returns the new device, or NULL. 195 */ 196 struct spi_device *spi_new_device(struct spi_master *master, 197 struct spi_board_info *chip) 198 { 199 struct spi_device *proxy; 200 struct device *dev = master->dev.parent; 201 int status; 202 203 /* NOTE: caller did any chip->bus_num checks necessary. 204 * 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). 208 */ 209 210 /* Chipselects are numbered 0..max; validate. */ 211 if (chip->chip_select >= master->num_chipselect) { 212 dev_err(dev, "cs%d > max %d\n", 213 chip->chip_select, 214 master->num_chipselect); 215 return NULL; 216 } 217 218 if (!spi_master_get(master)) 219 return NULL; 220 221 proxy = kzalloc(sizeof *proxy, GFP_KERNEL); 222 if (!proxy) { 223 dev_err(dev, "can't alloc dev for cs%d\n", 224 chip->chip_select); 225 goto fail; 226 } 227 proxy->master = master; 228 proxy->chip_select = chip->chip_select; 229 proxy->max_speed_hz = chip->max_speed_hz; 230 proxy->mode = chip->mode; 231 proxy->irq = chip->irq; 232 proxy->modalias = chip->modalias; 233 234 snprintf(proxy->dev.bus_id, sizeof proxy->dev.bus_id, 235 "%s.%u", master->dev.bus_id, 236 chip->chip_select); 237 proxy->dev.parent = dev; 238 proxy->dev.bus = &spi_bus_type; 239 proxy->dev.platform_data = (void *) chip->platform_data; 240 proxy->controller_data = chip->controller_data; 241 proxy->controller_state = NULL; 242 proxy->dev.release = spidev_release; 243 244 /* drivers may modify this initial i/o setup */ 245 status = master->setup(proxy); 246 if (status < 0) { 247 dev_err(dev, "can't %s %s, status %d\n", 248 "setup", proxy->dev.bus_id, status); 249 goto fail; 250 } 251 252 /* driver core catches callers that misbehave by defining 253 * devices that already exist. 254 */ 255 status = device_register(&proxy->dev); 256 if (status < 0) { 257 dev_err(dev, "can't %s %s, status %d\n", 258 "add", proxy->dev.bus_id, status); 259 goto fail; 260 } 261 dev_dbg(dev, "registered child %s\n", proxy->dev.bus_id); 262 return proxy; 263 264 fail: 265 spi_master_put(master); 266 kfree(proxy); 267 return NULL; 268 } 269 EXPORT_SYMBOL_GPL(spi_new_device); 270 271 /** 272 * spi_register_board_info - register SPI devices for a given board 273 * @info: array of chip descriptors 274 * @n: how many descriptors are provided 275 * Context: can sleep 276 * 277 * Board-specific early init code calls this (probably during arch_initcall) 278 * with segments of the SPI device table. Any device nodes are created later, 279 * after the relevant parent SPI controller (bus_num) is defined. We keep 280 * this table of devices forever, so that reloading a controller driver will 281 * not make Linux forget about these hard-wired devices. 282 * 283 * Other code can also call this, e.g. a particular add-on board might provide 284 * SPI devices through its expansion connector, so code initializing that board 285 * would naturally declare its SPI devices. 286 * 287 * The board info passed can safely be __initdata ... but be careful of 288 * any embedded pointers (platform_data, etc), they're copied as-is. 289 */ 290 int __init 291 spi_register_board_info(struct spi_board_info const *info, unsigned n) 292 { 293 struct boardinfo *bi; 294 295 bi = kmalloc(sizeof(*bi) + n * sizeof *info, GFP_KERNEL); 296 if (!bi) 297 return -ENOMEM; 298 bi->n_board_info = n; 299 memcpy(bi->board_info, info, n * sizeof *info); 300 301 mutex_lock(&board_lock); 302 list_add_tail(&bi->list, &board_list); 303 mutex_unlock(&board_lock); 304 return 0; 305 } 306 307 /* FIXME someone should add support for a __setup("spi", ...) that 308 * creates board info from kernel command lines 309 */ 310 311 static void scan_boardinfo(struct spi_master *master) 312 { 313 struct boardinfo *bi; 314 315 mutex_lock(&board_lock); 316 list_for_each_entry(bi, &board_list, list) { 317 struct spi_board_info *chip = bi->board_info; 318 unsigned n; 319 320 for (n = bi->n_board_info; n > 0; n--, chip++) { 321 if (chip->bus_num != master->bus_num) 322 continue; 323 /* NOTE: this relies on spi_new_device to 324 * issue diagnostics when given bogus inputs 325 */ 326 (void) spi_new_device(master, chip); 327 } 328 } 329 mutex_unlock(&board_lock); 330 } 331 332 /*-------------------------------------------------------------------------*/ 333 334 static void spi_master_release(struct device *dev) 335 { 336 struct spi_master *master; 337 338 master = container_of(dev, struct spi_master, dev); 339 kfree(master); 340 } 341 342 static struct class spi_master_class = { 343 .name = "spi_master", 344 .owner = THIS_MODULE, 345 .dev_release = spi_master_release, 346 }; 347 348 349 /** 350 * spi_alloc_master - allocate SPI master controller 351 * @dev: the controller, possibly using the platform_bus 352 * @size: how much zeroed driver-private data to allocate; the pointer to this 353 * memory is in the driver_data field of the returned device, 354 * accessible with spi_master_get_devdata(). 355 * Context: can sleep 356 * 357 * This call is used only by SPI master controller drivers, which are the 358 * only ones directly touching chip registers. It's how they allocate 359 * an spi_master structure, prior to calling spi_register_master(). 360 * 361 * This must be called from context that can sleep. It returns the SPI 362 * master structure on success, else NULL. 363 * 364 * The caller is responsible for assigning the bus number and initializing 365 * the master's methods before calling spi_register_master(); and (after errors 366 * adding the device) calling spi_master_put() to prevent a memory leak. 367 */ 368 struct spi_master *spi_alloc_master(struct device *dev, unsigned size) 369 { 370 struct spi_master *master; 371 372 if (!dev) 373 return NULL; 374 375 master = kzalloc(size + sizeof *master, GFP_KERNEL); 376 if (!master) 377 return NULL; 378 379 device_initialize(&master->dev); 380 master->dev.class = &spi_master_class; 381 master->dev.parent = get_device(dev); 382 spi_master_set_devdata(master, &master[1]); 383 384 return master; 385 } 386 EXPORT_SYMBOL_GPL(spi_alloc_master); 387 388 /** 389 * spi_register_master - register SPI master controller 390 * @master: initialized master, originally from spi_alloc_master() 391 * Context: can sleep 392 * 393 * SPI master controllers connect to their drivers using some non-SPI bus, 394 * such as the platform bus. The final stage of probe() in that code 395 * includes calling spi_register_master() to hook up to this SPI bus glue. 396 * 397 * SPI controllers use board specific (often SOC specific) bus numbers, 398 * and board-specific addressing for SPI devices combines those numbers 399 * with chip select numbers. Since SPI does not directly support dynamic 400 * device identification, boards need configuration tables telling which 401 * chip is at which address. 402 * 403 * This must be called from context that can sleep. It returns zero on 404 * success, else a negative error code (dropping the master's refcount). 405 * After a successful return, the caller is responsible for calling 406 * spi_unregister_master(). 407 */ 408 int spi_register_master(struct spi_master *master) 409 { 410 static atomic_t dyn_bus_id = ATOMIC_INIT((1<<15) - 1); 411 struct device *dev = master->dev.parent; 412 int status = -ENODEV; 413 int dynamic = 0; 414 415 if (!dev) 416 return -ENODEV; 417 418 /* even if it's just one always-selected device, there must 419 * be at least one chipselect 420 */ 421 if (master->num_chipselect == 0) 422 return -EINVAL; 423 424 /* convention: dynamically assigned bus IDs count down from the max */ 425 if (master->bus_num < 0) { 426 /* FIXME switch to an IDR based scheme, something like 427 * I2C now uses, so we can't run out of "dynamic" IDs 428 */ 429 master->bus_num = atomic_dec_return(&dyn_bus_id); 430 dynamic = 1; 431 } 432 433 /* register the device, then userspace will see it. 434 * registration fails if the bus ID is in use. 435 */ 436 snprintf(master->dev.bus_id, sizeof master->dev.bus_id, 437 "spi%u", master->bus_num); 438 status = device_add(&master->dev); 439 if (status < 0) 440 goto done; 441 dev_dbg(dev, "registered master %s%s\n", master->dev.bus_id, 442 dynamic ? " (dynamic)" : ""); 443 444 /* populate children from any spi device tables */ 445 scan_boardinfo(master); 446 status = 0; 447 done: 448 return status; 449 } 450 EXPORT_SYMBOL_GPL(spi_register_master); 451 452 453 static int __unregister(struct device *dev, void *master_dev) 454 { 455 /* note: before about 2.6.14-rc1 this would corrupt memory: */ 456 if (dev != master_dev) 457 spi_unregister_device(to_spi_device(dev)); 458 return 0; 459 } 460 461 /** 462 * spi_unregister_master - unregister SPI master controller 463 * @master: the master being unregistered 464 * Context: can sleep 465 * 466 * This call is used only by SPI master controller drivers, which are the 467 * only ones directly touching chip registers. 468 * 469 * This must be called from context that can sleep. 470 */ 471 void spi_unregister_master(struct spi_master *master) 472 { 473 int dummy; 474 475 dummy = device_for_each_child(master->dev.parent, &master->dev, 476 __unregister); 477 device_unregister(&master->dev); 478 } 479 EXPORT_SYMBOL_GPL(spi_unregister_master); 480 481 static int __spi_master_match(struct device *dev, void *data) 482 { 483 struct spi_master *m; 484 u16 *bus_num = data; 485 486 m = container_of(dev, struct spi_master, dev); 487 return m->bus_num == *bus_num; 488 } 489 490 /** 491 * spi_busnum_to_master - look up master associated with bus_num 492 * @bus_num: the master's bus number 493 * Context: can sleep 494 * 495 * This call may be used with devices that are registered after 496 * arch init time. It returns a refcounted pointer to the relevant 497 * spi_master (which the caller must release), or NULL if there is 498 * no such master registered. 499 */ 500 struct spi_master *spi_busnum_to_master(u16 bus_num) 501 { 502 struct device *dev; 503 struct spi_master *master = NULL; 504 505 dev = class_find_device(&spi_master_class, &bus_num, 506 __spi_master_match); 507 if (dev) 508 master = container_of(dev, struct spi_master, dev); 509 /* reference got in class_find_device */ 510 return master; 511 } 512 EXPORT_SYMBOL_GPL(spi_busnum_to_master); 513 514 515 /*-------------------------------------------------------------------------*/ 516 517 static void spi_complete(void *arg) 518 { 519 complete(arg); 520 } 521 522 /** 523 * spi_sync - blocking/synchronous SPI data transfers 524 * @spi: device with which data will be exchanged 525 * @message: describes the data transfers 526 * Context: can sleep 527 * 528 * This call may only be used from a context that may sleep. The sleep 529 * is non-interruptible, and has no timeout. Low-overhead controller 530 * drivers may DMA directly into and out of the message buffers. 531 * 532 * Note that the SPI device's chip select is active during the message, 533 * and then is normally disabled between messages. Drivers for some 534 * frequently-used devices may want to minimize costs of selecting a chip, 535 * by leaving it selected in anticipation that the next message will go 536 * to the same chip. (That may increase power usage.) 537 * 538 * Also, the caller is guaranteeing that the memory associated with the 539 * message will not be freed before this call returns. 540 * 541 * It returns zero on success, else a negative error code. 542 */ 543 int spi_sync(struct spi_device *spi, struct spi_message *message) 544 { 545 DECLARE_COMPLETION_ONSTACK(done); 546 int status; 547 548 message->complete = spi_complete; 549 message->context = &done; 550 status = spi_async(spi, message); 551 if (status == 0) { 552 wait_for_completion(&done); 553 status = message->status; 554 } 555 message->context = NULL; 556 return status; 557 } 558 EXPORT_SYMBOL_GPL(spi_sync); 559 560 /* portable code must never pass more than 32 bytes */ 561 #define SPI_BUFSIZ max(32,SMP_CACHE_BYTES) 562 563 static u8 *buf; 564 565 /** 566 * spi_write_then_read - SPI synchronous write followed by read 567 * @spi: device with which data will be exchanged 568 * @txbuf: data to be written (need not be dma-safe) 569 * @n_tx: size of txbuf, in bytes 570 * @rxbuf: buffer into which data will be read 571 * @n_rx: size of rxbuf, in bytes (need not be dma-safe) 572 * Context: can sleep 573 * 574 * This performs a half duplex MicroWire style transaction with the 575 * device, sending txbuf and then reading rxbuf. The return value 576 * is zero for success, else a negative errno status code. 577 * This call may only be used from a context that may sleep. 578 * 579 * Parameters to this routine are always copied using a small buffer; 580 * portable code should never use this for more than 32 bytes. 581 * Performance-sensitive or bulk transfer code should instead use 582 * spi_{async,sync}() calls with dma-safe buffers. 583 */ 584 int spi_write_then_read(struct spi_device *spi, 585 const u8 *txbuf, unsigned n_tx, 586 u8 *rxbuf, unsigned n_rx) 587 { 588 static DEFINE_MUTEX(lock); 589 590 int status; 591 struct spi_message message; 592 struct spi_transfer x[2]; 593 u8 *local_buf; 594 595 /* Use preallocated DMA-safe buffer. We can't avoid copying here, 596 * (as a pure convenience thing), but we can keep heap costs 597 * out of the hot path ... 598 */ 599 if ((n_tx + n_rx) > SPI_BUFSIZ) 600 return -EINVAL; 601 602 spi_message_init(&message); 603 memset(x, 0, sizeof x); 604 if (n_tx) { 605 x[0].len = n_tx; 606 spi_message_add_tail(&x[0], &message); 607 } 608 if (n_rx) { 609 x[1].len = n_rx; 610 spi_message_add_tail(&x[1], &message); 611 } 612 613 /* ... unless someone else is using the pre-allocated buffer */ 614 if (!mutex_trylock(&lock)) { 615 local_buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL); 616 if (!local_buf) 617 return -ENOMEM; 618 } else 619 local_buf = buf; 620 621 memcpy(local_buf, txbuf, n_tx); 622 x[0].tx_buf = local_buf; 623 x[1].rx_buf = local_buf + n_tx; 624 625 /* do the i/o */ 626 status = spi_sync(spi, &message); 627 if (status == 0) 628 memcpy(rxbuf, x[1].rx_buf, n_rx); 629 630 if (x[0].tx_buf == buf) 631 mutex_unlock(&lock); 632 else 633 kfree(local_buf); 634 635 return status; 636 } 637 EXPORT_SYMBOL_GPL(spi_write_then_read); 638 639 /*-------------------------------------------------------------------------*/ 640 641 static int __init spi_init(void) 642 { 643 int status; 644 645 buf = kmalloc(SPI_BUFSIZ, GFP_KERNEL); 646 if (!buf) { 647 status = -ENOMEM; 648 goto err0; 649 } 650 651 status = bus_register(&spi_bus_type); 652 if (status < 0) 653 goto err1; 654 655 status = class_register(&spi_master_class); 656 if (status < 0) 657 goto err2; 658 return 0; 659 660 err2: 661 bus_unregister(&spi_bus_type); 662 err1: 663 kfree(buf); 664 buf = NULL; 665 err0: 666 return status; 667 } 668 669 /* board_info is normally registered in arch_initcall(), 670 * but even essential drivers wait till later 671 * 672 * REVISIT only boardinfo really needs static linking. the rest (device and 673 * driver registration) _could_ be dynamically linked (modular) ... costs 674 * include needing to have boardinfo data structures be much more public. 675 */ 676 subsys_initcall(spi_init); 677 678