include/linux/device.h

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