1 /* 2 * device.h - generic, centralized driver model 3 * 4 * Copyright (c) 2001-2003 Patrick Mochel <[email protected]> 5 * Copyright (c) 2004-2009 Greg Kroah-Hartman <[email protected]> 6 * Copyright (c) 2008-2009 Novell Inc. 7 * 8 * This file is released under the GPLv2 9 * 10 * See Documentation/driver-model/ for more information. 11 */ 12 13 #ifndef _DEVICE_H_ 14 #define _DEVICE_H_ 15 16 #include <linux/ioport.h> 17 #include <linux/kobject.h> 18 #include <linux/klist.h> 19 #include <linux/list.h> 20 #include <linux/lockdep.h> 21 #include <linux/compiler.h> 22 #include <linux/types.h> 23 #include <linux/module.h> 24 #include <linux/pm.h> 25 #include <asm/atomic.h> 26 #include <asm/device.h> 27 28 struct device; 29 struct device_private; 30 struct device_driver; 31 struct driver_private; 32 struct class; 33 struct class_private; 34 struct bus_type; 35 struct bus_type_private; 36 37 struct bus_attribute { 38 struct attribute attr; 39 ssize_t (*show)(struct bus_type *bus, char *buf); 40 ssize_t (*store)(struct bus_type *bus, const char *buf, size_t count); 41 }; 42 43 #define BUS_ATTR(_name, _mode, _show, _store) \ 44 struct bus_attribute bus_attr_##_name = __ATTR(_name, _mode, _show, _store) 45 46 extern int __must_check bus_create_file(struct bus_type *, 47 struct bus_attribute *); 48 extern void bus_remove_file(struct bus_type *, struct bus_attribute *); 49 50 struct bus_type { 51 const char *name; 52 struct bus_attribute *bus_attrs; 53 struct device_attribute *dev_attrs; 54 struct driver_attribute *drv_attrs; 55 56 int (*match)(struct device *dev, struct device_driver *drv); 57 int (*uevent)(struct device *dev, struct kobj_uevent_env *env); 58 int (*probe)(struct device *dev); 59 int (*remove)(struct device *dev); 60 void (*shutdown)(struct device *dev); 61 62 int (*suspend)(struct device *dev, pm_message_t state); 63 int (*resume)(struct device *dev); 64 65 const struct dev_pm_ops *pm; 66 67 struct bus_type_private *p; 68 }; 69 70 extern int __must_check bus_register(struct bus_type *bus); 71 extern void bus_unregister(struct bus_type *bus); 72 73 extern int __must_check bus_rescan_devices(struct bus_type *bus); 74 75 /* iterator helpers for buses */ 76 77 int bus_for_each_dev(struct bus_type *bus, struct device *start, void *data, 78 int (*fn)(struct device *dev, void *data)); 79 struct device *bus_find_device(struct bus_type *bus, struct device *start, 80 void *data, 81 int (*match)(struct device *dev, void *data)); 82 struct device *bus_find_device_by_name(struct bus_type *bus, 83 struct device *start, 84 const char *name); 85 86 int __must_check bus_for_each_drv(struct bus_type *bus, 87 struct device_driver *start, void *data, 88 int (*fn)(struct device_driver *, void *)); 89 90 void bus_sort_breadthfirst(struct bus_type *bus, 91 int (*compare)(const struct device *a, 92 const struct device *b)); 93 /* 94 * Bus notifiers: Get notified of addition/removal of devices 95 * and binding/unbinding of drivers to devices. 96 * In the long run, it should be a replacement for the platform 97 * notify hooks. 98 */ 99 struct notifier_block; 100 101 extern int bus_register_notifier(struct bus_type *bus, 102 struct notifier_block *nb); 103 extern int bus_unregister_notifier(struct bus_type *bus, 104 struct notifier_block *nb); 105 106 /* All 4 notifers below get called with the target struct device * 107 * as an argument. Note that those functions are likely to be called 108 * with the device lock held in the core, so be careful. 109 */ 110 #define BUS_NOTIFY_ADD_DEVICE 0x00000001 /* device added */ 111 #define BUS_NOTIFY_DEL_DEVICE 0x00000002 /* device removed */ 112 #define BUS_NOTIFY_BOUND_DRIVER 0x00000003 /* driver bound to device */ 113 #define BUS_NOTIFY_UNBIND_DRIVER 0x00000004 /* driver about to be 114 unbound */ 115 #define BUS_NOTIFY_UNBOUND_DRIVER 0x00000005 /* driver is unbound 116 from the device */ 117 118 extern struct kset *bus_get_kset(struct bus_type *bus); 119 extern struct klist *bus_get_device_klist(struct bus_type *bus); 120 121 struct device_driver { 122 const char *name; 123 struct bus_type *bus; 124 125 struct module *owner; 126 const char *mod_name; /* used for built-in modules */ 127 128 bool suppress_bind_attrs; /* disables bind/unbind via sysfs */ 129 130 int (*probe) (struct device *dev); 131 int (*remove) (struct device *dev); 132 void (*shutdown) (struct device *dev); 133 int (*suspend) (struct device *dev, pm_message_t state); 134 int (*resume) (struct device *dev); 135 const struct attribute_group **groups; 136 137 const struct dev_pm_ops *pm; 138 139 struct driver_private *p; 140 }; 141 142 143 extern int __must_check driver_register(struct device_driver *drv); 144 extern void driver_unregister(struct device_driver *drv); 145 146 extern struct device_driver *get_driver(struct device_driver *drv); 147 extern void put_driver(struct device_driver *drv); 148 extern struct device_driver *driver_find(const char *name, 149 struct bus_type *bus); 150 extern int driver_probe_done(void); 151 extern void wait_for_device_probe(void); 152 153 154 /* sysfs interface for exporting driver attributes */ 155 156 struct driver_attribute { 157 struct attribute attr; 158 ssize_t (*show)(struct device_driver *driver, char *buf); 159 ssize_t (*store)(struct device_driver *driver, const char *buf, 160 size_t count); 161 }; 162 163 #define DRIVER_ATTR(_name, _mode, _show, _store) \ 164 struct driver_attribute driver_attr_##_name = \ 165 __ATTR(_name, _mode, _show, _store) 166 167 extern int __must_check driver_create_file(struct device_driver *driver, 168 const struct driver_attribute *attr); 169 extern void driver_remove_file(struct device_driver *driver, 170 const struct driver_attribute *attr); 171 172 extern int __must_check driver_add_kobj(struct device_driver *drv, 173 struct kobject *kobj, 174 const char *fmt, ...); 175 176 extern int __must_check driver_for_each_device(struct device_driver *drv, 177 struct device *start, 178 void *data, 179 int (*fn)(struct device *dev, 180 void *)); 181 struct device *driver_find_device(struct device_driver *drv, 182 struct device *start, void *data, 183 int (*match)(struct device *dev, void *data)); 184 185 /* 186 * device classes 187 */ 188 struct class { 189 const char *name; 190 struct module *owner; 191 192 struct class_attribute *class_attrs; 193 struct device_attribute *dev_attrs; 194 struct kobject *dev_kobj; 195 196 int (*dev_uevent)(struct device *dev, struct kobj_uevent_env *env); 197 char *(*devnode)(struct device *dev, mode_t *mode); 198 199 void (*class_release)(struct class *class); 200 void (*dev_release)(struct device *dev); 201 202 int (*suspend)(struct device *dev, pm_message_t state); 203 int (*resume)(struct device *dev); 204 205 const struct kobj_ns_type_operations *ns_type; 206 const void *(*namespace)(struct device *dev); 207 208 const struct dev_pm_ops *pm; 209 210 struct class_private *p; 211 }; 212 213 struct class_dev_iter { 214 struct klist_iter ki; 215 const struct device_type *type; 216 }; 217 218 extern struct kobject *sysfs_dev_block_kobj; 219 extern struct kobject *sysfs_dev_char_kobj; 220 extern int __must_check __class_register(struct class *class, 221 struct lock_class_key *key); 222 extern void class_unregister(struct class *class); 223 224 /* This is a #define to keep the compiler from merging different 225 * instances of the __key variable */ 226 #define class_register(class) \ 227 ({ \ 228 static struct lock_class_key __key; \ 229 __class_register(class, &__key); \ 230 }) 231 232 struct class_compat; 233 struct class_compat *class_compat_register(const char *name); 234 void class_compat_unregister(struct class_compat *cls); 235 int class_compat_create_link(struct class_compat *cls, struct device *dev, 236 struct device *device_link); 237 void class_compat_remove_link(struct class_compat *cls, struct device *dev, 238 struct device *device_link); 239 240 extern void class_dev_iter_init(struct class_dev_iter *iter, 241 struct class *class, 242 struct device *start, 243 const struct device_type *type); 244 extern struct device *class_dev_iter_next(struct class_dev_iter *iter); 245 extern void class_dev_iter_exit(struct class_dev_iter *iter); 246 247 extern int class_for_each_device(struct class *class, struct device *start, 248 void *data, 249 int (*fn)(struct device *dev, void *data)); 250 extern struct device *class_find_device(struct class *class, 251 struct device *start, void *data, 252 int (*match)(struct device *, void *)); 253 254 struct class_attribute { 255 struct attribute attr; 256 ssize_t (*show)(struct class *class, struct class_attribute *attr, 257 char *buf); 258 ssize_t (*store)(struct class *class, struct class_attribute *attr, 259 const char *buf, size_t count); 260 }; 261 262 #define CLASS_ATTR(_name, _mode, _show, _store) \ 263 struct class_attribute class_attr_##_name = __ATTR(_name, _mode, _show, _store) 264 265 extern int __must_check class_create_file(struct class *class, 266 const struct class_attribute *attr); 267 extern void class_remove_file(struct class *class, 268 const struct class_attribute *attr); 269 270 /* Simple class attribute that is just a static string */ 271 272 struct class_attribute_string { 273 struct class_attribute attr; 274 char *str; 275 }; 276 277 /* Currently read-only only */ 278 #define _CLASS_ATTR_STRING(_name, _mode, _str) \ 279 { __ATTR(_name, _mode, show_class_attr_string, NULL), _str } 280 #define CLASS_ATTR_STRING(_name, _mode, _str) \ 281 struct class_attribute_string class_attr_##_name = \ 282 _CLASS_ATTR_STRING(_name, _mode, _str) 283 284 extern ssize_t show_class_attr_string(struct class *class, struct class_attribute *attr, 285 char *buf); 286 287 struct class_interface { 288 struct list_head node; 289 struct class *class; 290 291 int (*add_dev) (struct device *, struct class_interface *); 292 void (*remove_dev) (struct device *, struct class_interface *); 293 }; 294 295 extern int __must_check class_interface_register(struct class_interface *); 296 extern void class_interface_unregister(struct class_interface *); 297 298 extern struct class * __must_check __class_create(struct module *owner, 299 const char *name, 300 struct lock_class_key *key); 301 extern void class_destroy(struct class *cls); 302 303 /* This is a #define to keep the compiler from merging different 304 * instances of the __key variable */ 305 #define class_create(owner, name) \ 306 ({ \ 307 static struct lock_class_key __key; \ 308 __class_create(owner, name, &__key); \ 309 }) 310 311 /* 312 * The type of device, "struct device" is embedded in. A class 313 * or bus can contain devices of different types 314 * like "partitions" and "disks", "mouse" and "event". 315 * This identifies the device type and carries type-specific 316 * information, equivalent to the kobj_type of a kobject. 317 * If "name" is specified, the uevent will contain it in 318 * the DEVTYPE variable. 319 */ 320 struct device_type { 321 const char *name; 322 const struct attribute_group **groups; 323 int (*uevent)(struct device *dev, struct kobj_uevent_env *env); 324 char *(*devnode)(struct device *dev, mode_t *mode); 325 void (*release)(struct device *dev); 326 327 const struct dev_pm_ops *pm; 328 }; 329 330 /* interface for exporting device attributes */ 331 struct device_attribute { 332 struct attribute attr; 333 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 334 char *buf); 335 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 336 const char *buf, size_t count); 337 }; 338 339 #define DEVICE_ATTR(_name, _mode, _show, _store) \ 340 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) 341 342 extern int __must_check device_create_file(struct device *device, 343 const struct device_attribute *entry); 344 extern void device_remove_file(struct device *dev, 345 const struct device_attribute *attr); 346 extern int __must_check device_create_bin_file(struct device *dev, 347 const struct bin_attribute *attr); 348 extern void device_remove_bin_file(struct device *dev, 349 const struct bin_attribute *attr); 350 extern int device_schedule_callback_owner(struct device *dev, 351 void (*func)(struct device *dev), struct module *owner); 352 353 /* This is a macro to avoid include problems with THIS_MODULE */ 354 #define device_schedule_callback(dev, func) \ 355 device_schedule_callback_owner(dev, func, THIS_MODULE) 356 357 /* device resource management */ 358 typedef void (*dr_release_t)(struct device *dev, void *res); 359 typedef int (*dr_match_t)(struct device *dev, void *res, void *match_data); 360 361 #ifdef CONFIG_DEBUG_DEVRES 362 extern void *__devres_alloc(dr_release_t release, size_t size, gfp_t gfp, 363 const char *name); 364 #define devres_alloc(release, size, gfp) \ 365 __devres_alloc(release, size, gfp, #release) 366 #else 367 extern void *devres_alloc(dr_release_t release, size_t size, gfp_t gfp); 368 #endif 369 extern void devres_free(void *res); 370 extern void devres_add(struct device *dev, void *res); 371 extern void *devres_find(struct device *dev, dr_release_t release, 372 dr_match_t match, void *match_data); 373 extern void *devres_get(struct device *dev, void *new_res, 374 dr_match_t match, void *match_data); 375 extern void *devres_remove(struct device *dev, dr_release_t release, 376 dr_match_t match, void *match_data); 377 extern int devres_destroy(struct device *dev, dr_release_t release, 378 dr_match_t match, void *match_data); 379 380 /* devres group */ 381 extern void * __must_check devres_open_group(struct device *dev, void *id, 382 gfp_t gfp); 383 extern void devres_close_group(struct device *dev, void *id); 384 extern void devres_remove_group(struct device *dev, void *id); 385 extern int devres_release_group(struct device *dev, void *id); 386 387 /* managed kzalloc/kfree for device drivers, no kmalloc, always use kzalloc */ 388 extern void *devm_kzalloc(struct device *dev, size_t size, gfp_t gfp); 389 extern void devm_kfree(struct device *dev, void *p); 390 391 struct device_dma_parameters { 392 /* 393 * a low level driver may set these to teach IOMMU code about 394 * sg limitations. 395 */ 396 unsigned int max_segment_size; 397 unsigned long segment_boundary_mask; 398 }; 399 400 struct device { 401 struct device *parent; 402 403 struct device_private *p; 404 405 struct kobject kobj; 406 const char *init_name; /* initial name of the device */ 407 struct device_type *type; 408 409 struct mutex mutex; /* mutex to synchronize calls to 410 * its driver. 411 */ 412 413 struct bus_type *bus; /* type of bus device is on */ 414 struct device_driver *driver; /* which driver has allocated this 415 device */ 416 void *platform_data; /* Platform specific data, device 417 core doesn't touch it */ 418 struct dev_pm_info power; 419 420 #ifdef CONFIG_NUMA 421 int numa_node; /* NUMA node this device is close to */ 422 #endif 423 u64 *dma_mask; /* dma mask (if dma'able device) */ 424 u64 coherent_dma_mask;/* Like dma_mask, but for 425 alloc_coherent mappings as 426 not all hardware supports 427 64 bit addresses for consistent 428 allocations such descriptors. */ 429 430 struct device_dma_parameters *dma_parms; 431 432 struct list_head dma_pools; /* dma pools (if dma'ble) */ 433 434 struct dma_coherent_mem *dma_mem; /* internal for coherent mem 435 override */ 436 /* arch specific additions */ 437 struct dev_archdata archdata; 438 439 dev_t devt; /* dev_t, creates the sysfs "dev" */ 440 441 spinlock_t devres_lock; 442 struct list_head devres_head; 443 444 struct klist_node knode_class; 445 struct class *class; 446 const struct attribute_group **groups; /* optional groups */ 447 448 void (*release)(struct device *dev); 449 }; 450 451 /* Get the wakeup routines, which depend on struct device */ 452 #include <linux/pm_wakeup.h> 453 454 static inline const char *dev_name(const struct device *dev) 455 { 456 /* Use the init name until the kobject becomes available */ 457 if (dev->init_name) 458 return dev->init_name; 459 460 return kobject_name(&dev->kobj); 461 } 462 463 extern int dev_set_name(struct device *dev, const char *name, ...) 464 __attribute__((format(printf, 2, 3))); 465 466 #ifdef CONFIG_NUMA 467 static inline int dev_to_node(struct device *dev) 468 { 469 return dev->numa_node; 470 } 471 static inline void set_dev_node(struct device *dev, int node) 472 { 473 dev->numa_node = node; 474 } 475 #else 476 static inline int dev_to_node(struct device *dev) 477 { 478 return -1; 479 } 480 static inline void set_dev_node(struct device *dev, int node) 481 { 482 } 483 #endif 484 485 static inline unsigned int dev_get_uevent_suppress(const struct device *dev) 486 { 487 return dev->kobj.uevent_suppress; 488 } 489 490 static inline void dev_set_uevent_suppress(struct device *dev, int val) 491 { 492 dev->kobj.uevent_suppress = val; 493 } 494 495 static inline int device_is_registered(struct device *dev) 496 { 497 return dev->kobj.state_in_sysfs; 498 } 499 500 static inline void device_enable_async_suspend(struct device *dev) 501 { 502 if (dev->power.status == DPM_ON) 503 dev->power.async_suspend = true; 504 } 505 506 static inline void device_disable_async_suspend(struct device *dev) 507 { 508 if (dev->power.status == DPM_ON) 509 dev->power.async_suspend = false; 510 } 511 512 static inline bool device_async_suspend_enabled(struct device *dev) 513 { 514 return !!dev->power.async_suspend; 515 } 516 517 static inline void device_lock(struct device *dev) 518 { 519 mutex_lock(&dev->mutex); 520 } 521 522 static inline int device_trylock(struct device *dev) 523 { 524 return mutex_trylock(&dev->mutex); 525 } 526 527 static inline void device_unlock(struct device *dev) 528 { 529 mutex_unlock(&dev->mutex); 530 } 531 532 void driver_init(void); 533 534 /* 535 * High level routines for use by the bus drivers 536 */ 537 extern int __must_check device_register(struct device *dev); 538 extern void device_unregister(struct device *dev); 539 extern void device_initialize(struct device *dev); 540 extern int __must_check device_add(struct device *dev); 541 extern void device_del(struct device *dev); 542 extern int device_for_each_child(struct device *dev, void *data, 543 int (*fn)(struct device *dev, void *data)); 544 extern struct device *device_find_child(struct device *dev, void *data, 545 int (*match)(struct device *dev, void *data)); 546 extern int device_rename(struct device *dev, char *new_name); 547 extern int device_move(struct device *dev, struct device *new_parent, 548 enum dpm_order dpm_order); 549 extern const char *device_get_devnode(struct device *dev, 550 mode_t *mode, const char **tmp); 551 extern void *dev_get_drvdata(const struct device *dev); 552 extern void dev_set_drvdata(struct device *dev, void *data); 553 554 /* 555 * Root device objects for grouping under /sys/devices 556 */ 557 extern struct device *__root_device_register(const char *name, 558 struct module *owner); 559 static inline struct device *root_device_register(const char *name) 560 { 561 return __root_device_register(name, THIS_MODULE); 562 } 563 extern void root_device_unregister(struct device *root); 564 565 static inline void *dev_get_platdata(const struct device *dev) 566 { 567 return dev->platform_data; 568 } 569 570 /* 571 * Manual binding of a device to driver. See drivers/base/bus.c 572 * for information on use. 573 */ 574 extern int __must_check device_bind_driver(struct device *dev); 575 extern void device_release_driver(struct device *dev); 576 extern int __must_check device_attach(struct device *dev); 577 extern int __must_check driver_attach(struct device_driver *drv); 578 extern int __must_check device_reprobe(struct device *dev); 579 580 /* 581 * Easy functions for dynamically creating devices on the fly 582 */ 583 extern struct device *device_create_vargs(struct class *cls, 584 struct device *parent, 585 dev_t devt, 586 void *drvdata, 587 const char *fmt, 588 va_list vargs); 589 extern struct device *device_create(struct class *cls, struct device *parent, 590 dev_t devt, void *drvdata, 591 const char *fmt, ...) 592 __attribute__((format(printf, 5, 6))); 593 extern void device_destroy(struct class *cls, dev_t devt); 594 595 /* 596 * Platform "fixup" functions - allow the platform to have their say 597 * about devices and actions that the general device layer doesn't 598 * know about. 599 */ 600 /* Notify platform of device discovery */ 601 extern int (*platform_notify)(struct device *dev); 602 603 extern int (*platform_notify_remove)(struct device *dev); 604 605 606 /** 607 * get_device - atomically increment the reference count for the device. 608 * 609 */ 610 extern struct device *get_device(struct device *dev); 611 extern void put_device(struct device *dev); 612 613 extern void wait_for_device_probe(void); 614 615 #ifdef CONFIG_DEVTMPFS 616 extern int devtmpfs_create_node(struct device *dev); 617 extern int devtmpfs_delete_node(struct device *dev); 618 extern int devtmpfs_mount(const char *mntdir); 619 #else 620 static inline int devtmpfs_create_node(struct device *dev) { return 0; } 621 static inline int devtmpfs_delete_node(struct device *dev) { return 0; } 622 static inline int devtmpfs_mount(const char *mountpoint) { return 0; } 623 #endif 624 625 /* drivers/base/power/shutdown.c */ 626 extern void device_shutdown(void); 627 628 /* drivers/base/sys.c */ 629 extern void sysdev_shutdown(void); 630 631 /* debugging and troubleshooting/diagnostic helpers. */ 632 extern const char *dev_driver_string(const struct device *dev); 633 #define dev_printk(level, dev, format, arg...) \ 634 printk(level "%s %s: " format , dev_driver_string(dev) , \ 635 dev_name(dev) , ## arg) 636 637 #define dev_emerg(dev, format, arg...) \ 638 dev_printk(KERN_EMERG , dev , format , ## arg) 639 #define dev_alert(dev, format, arg...) \ 640 dev_printk(KERN_ALERT , dev , format , ## arg) 641 #define dev_crit(dev, format, arg...) \ 642 dev_printk(KERN_CRIT , dev , format , ## arg) 643 #define dev_err(dev, format, arg...) \ 644 dev_printk(KERN_ERR , dev , format , ## arg) 645 #define dev_warn(dev, format, arg...) \ 646 dev_printk(KERN_WARNING , dev , format , ## arg) 647 #define dev_notice(dev, format, arg...) \ 648 dev_printk(KERN_NOTICE , dev , format , ## arg) 649 #define dev_info(dev, format, arg...) \ 650 dev_printk(KERN_INFO , dev , format , ## arg) 651 652 #if defined(DEBUG) 653 #define dev_dbg(dev, format, arg...) \ 654 dev_printk(KERN_DEBUG , dev , format , ## arg) 655 #elif defined(CONFIG_DYNAMIC_DEBUG) 656 #define dev_dbg(dev, format, ...) do { \ 657 dynamic_dev_dbg(dev, format, ##__VA_ARGS__); \ 658 } while (0) 659 #else 660 #define dev_dbg(dev, format, arg...) \ 661 ({ if (0) dev_printk(KERN_DEBUG, dev, format, ##arg); 0; }) 662 #endif 663 664 #ifdef VERBOSE_DEBUG 665 #define dev_vdbg dev_dbg 666 #else 667 668 #define dev_vdbg(dev, format, arg...) \ 669 ({ if (0) dev_printk(KERN_DEBUG, dev, format, ##arg); 0; }) 670 #endif 671 672 /* 673 * dev_WARN() acts like dev_printk(), but with the key difference 674 * of using a WARN/WARN_ON to get the message out, including the 675 * file/line information and a backtrace. 676 */ 677 #define dev_WARN(dev, format, arg...) \ 678 WARN(1, "Device: %s\n" format, dev_driver_string(dev), ## arg); 679 680 /* Create alias, so I can be autoloaded. */ 681 #define MODULE_ALIAS_CHARDEV(major,minor) \ 682 MODULE_ALIAS("char-major-" __stringify(major) "-" __stringify(minor)) 683 #define MODULE_ALIAS_CHARDEV_MAJOR(major) \ 684 MODULE_ALIAS("char-major-" __stringify(major) "-*") 685 #endif /* _DEVICE_H_ */ 686