LXR linux/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-2007 Greg Kroah-Hartman <gregkh@suse.de>
   6 *
   7 * This file is released under the GPLv2
   8 *
   9 * See Documentation/driver-model/ for more information.
  10 */
  11
  12#ifndef _DEVICE_H_
  13#define _DEVICE_H_
  14
  15#include <linux/ioport.h>
  16#include <linux/kobject.h>
  17#include <linux/klist.h>
  18#include <linux/list.h>
  19#include <linux/compiler.h>
  20#include <linux/types.h>
  21#include <linux/module.h>
  22#include <linux/pm.h>
  23#include <asm/semaphore.h>
  24#include <asm/atomic.h>
  25#include <asm/device.h>
  26
  27#define DEVICE_NAME_SIZE        50
  28#define DEVICE_NAME_HALF        __stringify(20) /* Less than half to accommodate slop */
  29#define DEVICE_ID_SIZE          32
  30#define BUS_ID_SIZE             KOBJ_NAME_LEN
  31
  32
  33struct device;
  34struct device_driver;
  35struct class;
  36struct class_device;
  37struct bus_type;
  38
  39struct bus_attribute {
  40        struct attribute        attr;
  41        ssize_t (*show)(struct bus_type *, char * buf);
  42        ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
  43};
  44
  45#define BUS_ATTR(_name,_mode,_show,_store)      \
  46struct bus_attribute bus_attr_##_name = __ATTR(_name,_mode,_show,_store)
  47
  48extern int __must_check bus_create_file(struct bus_type *,
  49                                        struct bus_attribute *);
  50extern void bus_remove_file(struct bus_type *, struct bus_attribute *);
  51
  52struct bus_type {
  53        const char              * name;
  54        struct module           * owner;
  55
  56        struct kset             subsys;
  57        struct kset             drivers;
  58        struct kset             devices;
  59        struct klist            klist_devices;
  60        struct klist            klist_drivers;
  61
  62        struct blocking_notifier_head bus_notifier;
  63
  64        struct bus_attribute    * bus_attrs;
  65        struct device_attribute * dev_attrs;
  66        struct driver_attribute * drv_attrs;
  67        struct bus_attribute drivers_autoprobe_attr;
  68        struct bus_attribute drivers_probe_attr;
  69
  70        int             (*match)(struct device * dev, struct device_driver * drv);
  71        int             (*uevent)(struct device *dev, char **envp,
  72                                  int num_envp, char *buffer, int buffer_size);
  73        int             (*probe)(struct device * dev);
  74        int             (*remove)(struct device * dev);
  75        void            (*shutdown)(struct device * dev);
  76
  77        int (*suspend)(struct device * dev, pm_message_t state);
  78        int (*suspend_late)(struct device * dev, pm_message_t state);
  79        int (*resume_early)(struct device * dev);
  80        int (*resume)(struct device * dev);
  81
  82        unsigned int drivers_autoprobe:1;
  83};
  84
  85extern int __must_check bus_register(struct bus_type * bus);
  86extern void bus_unregister(struct bus_type * bus);
  87
  88extern int __must_check bus_rescan_devices(struct bus_type * bus);
  89
  90/* iterator helpers for buses */
  91
  92int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,
  93                     int (*fn)(struct device *, void *));
  94struct device * bus_find_device(struct bus_type *bus, struct device *start,
  95                                void *data, int (*match)(struct device *, void *));
  96
  97int __must_check bus_for_each_drv(struct bus_type *bus,
  98                struct device_driver *start, void *data,
  99                int (*fn)(struct device_driver *, void *));
 100
 101/*
 102 * Bus notifiers: Get notified of addition/removal of devices
 103 * and binding/unbinding of drivers to devices.
 104 * In the long run, it should be a replacement for the platform
 105 * notify hooks.
 106 */
 107struct notifier_block;
 108
 109extern int bus_register_notifier(struct bus_type *bus,
 110                                 struct notifier_block *nb);
 111extern int bus_unregister_notifier(struct bus_type *bus,
 112                                   struct notifier_block *nb);
 113
 114/* All 4 notifers below get called with the target struct device *
 115 * as an argument. Note that those functions are likely to be called
 116 * with the device semaphore held in the core, so be careful.
 117 */
 118#define BUS_NOTIFY_ADD_DEVICE           0x00000001 /* device added */
 119#define BUS_NOTIFY_DEL_DEVICE           0x00000002 /* device removed */
 120#define BUS_NOTIFY_BOUND_DRIVER         0x00000003 /* driver bound to device */
 121#define BUS_NOTIFY_UNBIND_DRIVER        0x00000004 /* driver about to be
 122                                                      unbound */
 123
 124struct device_driver {
 125        const char              * name;
 126        struct bus_type         * bus;
 127
 128        struct kobject          kobj;
 129        struct klist            klist_devices;
 130        struct klist_node       knode_bus;
 131
 132        struct module           * owner;
 133        const char              * mod_name;     /* used for built-in modules */
 134        struct module_kobject   * mkobj;
 135
 136        int     (*probe)        (struct device * dev);
 137        int     (*remove)       (struct device * dev);
 138        void    (*shutdown)     (struct device * dev);
 139        int     (*suspend)      (struct device * dev, pm_message_t state);
 140        int     (*resume)       (struct device * dev);
 141};
 142
 143
 144extern int __must_check driver_register(struct device_driver * drv);
 145extern void driver_unregister(struct device_driver * drv);
 146
 147extern struct device_driver * get_driver(struct device_driver * drv);
 148extern void put_driver(struct device_driver * drv);
 149extern struct device_driver *driver_find(const char *name, struct bus_type *bus);
 150extern int driver_probe_done(void);
 151
 152/* sysfs interface for exporting driver attributes */
 153
 154struct driver_attribute {
 155        struct attribute        attr;
 156        ssize_t (*show)(struct device_driver *, char * buf);
 157        ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
 158};
 159
 160#define DRIVER_ATTR(_name,_mode,_show,_store)   \
 161struct driver_attribute driver_attr_##_name = __ATTR(_name,_mode,_show,_store)
 162
 163extern int __must_check driver_create_file(struct device_driver *,
 164                                        struct driver_attribute *);
 165extern void driver_remove_file(struct device_driver *, struct driver_attribute *);
 166
 167extern int __must_check driver_for_each_device(struct device_driver * drv,
 168                struct device *start, void *data,
 169                int (*fn)(struct device *, void *));
 170struct device * driver_find_device(struct device_driver *drv,
 171                                   struct device *start, void *data,
 172                                   int (*match)(struct device *, void *));
 173
 174/*
 175 * device classes
 176 */
 177struct class {
 178        const char              * name;
 179        struct module           * owner;
 180
 181        struct kset             subsys;
 182        struct list_head        children;
 183        struct list_head        devices;
 184        struct list_head        interfaces;
 185        struct kset             class_dirs;
 186        struct semaphore        sem;    /* locks both the children and interfaces lists */
 187
 188        struct class_attribute          * class_attrs;
 189        struct class_device_attribute   * class_dev_attrs;
 190        struct device_attribute         * dev_attrs;
 191
 192        int     (*uevent)(struct class_device *dev, char **envp,
 193                           int num_envp, char *buffer, int buffer_size);
 194        int     (*dev_uevent)(struct device *dev, char **envp, int num_envp,
 195                                char *buffer, int buffer_size);
 196
 197        void    (*release)(struct class_device *dev);
 198        void    (*class_release)(struct class *class);
 199        void    (*dev_release)(struct device *dev);
 200
 201        int     (*suspend)(struct device *, pm_message_t state);
 202        int     (*resume)(struct device *);
 203};
 204
 205extern int __must_check class_register(struct class *);
 206extern void class_unregister(struct class *);
 207
 208
 209struct class_attribute {
 210        struct attribute        attr;
 211        ssize_t (*show)(struct class *, char * buf);
 212        ssize_t (*store)(struct class *, const char * buf, size_t count);
 213};
 214
 215#define CLASS_ATTR(_name,_mode,_show,_store)                    \
 216struct class_attribute class_attr_##_name = __ATTR(_name,_mode,_show,_store) 
 217
 218extern int __must_check class_create_file(struct class *,
 219                                        const struct class_attribute *);
 220extern void class_remove_file(struct class *, const struct class_attribute *);
 221
 222struct class_device_attribute {
 223        struct attribute        attr;
 224        ssize_t (*show)(struct class_device *, char * buf);
 225        ssize_t (*store)(struct class_device *, const char * buf, size_t count);
 226};
 227
 228#define CLASS_DEVICE_ATTR(_name,_mode,_show,_store)             \
 229struct class_device_attribute class_device_attr_##_name =       \
 230        __ATTR(_name,_mode,_show,_store)
 231
 232extern int __must_check class_device_create_file(struct class_device *,
 233                                    const struct class_device_attribute *);
 234
 235/**
 236 * struct class_device - class devices
 237 * @class: pointer to the parent class for this class device.  This is required.
 238 * @devt: for internal use by the driver core only.
 239 * @node: for internal use by the driver core only.
 240 * @kobj: for internal use by the driver core only.
 241 * @devt_attr: for internal use by the driver core only.
 242 * @groups: optional additional groups to be created
 243 * @dev: if set, a symlink to the struct device is created in the sysfs
 244 * directory for this struct class device.
 245 * @class_data: pointer to whatever you want to store here for this struct
 246 * class_device.  Use class_get_devdata() and class_set_devdata() to get and
 247 * set this pointer.
 248 * @parent: pointer to a struct class_device that is the parent of this struct
 249 * class_device.  If NULL, this class_device will show up at the root of the
 250 * struct class in sysfs (which is probably what you want to have happen.)
 251 * @release: pointer to a release function for this struct class_device.  If
 252 * set, this will be called instead of the class specific release function.
 253 * Only use this if you want to override the default release function, like
 254 * when you are nesting class_device structures.
 255 * @uevent: pointer to a uevent function for this struct class_device.  If
 256 * set, this will be called instead of the class specific uevent function.
 257 * Only use this if you want to override the default uevent function, like
 258 * when you are nesting class_device structures.
 259 */
 260struct class_device {
 261        struct list_head        node;
 262
 263        struct kobject          kobj;
 264        struct class            * class;        /* required */
 265        dev_t                   devt;           /* dev_t, creates the sysfs "dev" */
 266        struct class_device_attribute *devt_attr;
 267        struct class_device_attribute uevent_attr;
 268        struct device           * dev;          /* not necessary, but nice to have */
 269        void                    * class_data;   /* class-specific data */
 270        struct class_device     *parent;        /* parent of this child device, if there is one */
 271        struct attribute_group  ** groups;      /* optional groups */
 272
 273        void    (*release)(struct class_device *dev);
 274        int     (*uevent)(struct class_device *dev, char **envp,
 275                           int num_envp, char *buffer, int buffer_size);
 276        char    class_id[BUS_ID_SIZE];  /* unique to this class */
 277};
 278
 279static inline void *
 280class_get_devdata (struct class_device *dev)
 281{
 282        return dev->class_data;
 283}
 284
 285static inline void
 286class_set_devdata (struct class_device *dev, void *data)
 287{
 288        dev->class_data = data;
 289}
 290
 291
 292extern int __must_check class_device_register(struct class_device *);
 293extern void class_device_unregister(struct class_device *);
 294extern void class_device_initialize(struct class_device *);
 295extern int __must_check class_device_add(struct class_device *);
 296extern void class_device_del(struct class_device *);
 297
 298extern struct class_device * class_device_get(struct class_device *);
 299extern void class_device_put(struct class_device *);
 300
 301extern void class_device_remove_file(struct class_device *, 
 302                                     const struct class_device_attribute *);
 303extern int __must_check class_device_create_bin_file(struct class_device *,
 304                                        struct bin_attribute *);
 305extern void class_device_remove_bin_file(struct class_device *,
 306                                         struct bin_attribute *);
 307
 308struct class_interface {
 309        struct list_head        node;
 310        struct class            *class;
 311
 312        int (*add)      (struct class_device *, struct class_interface *);
 313        void (*remove)  (struct class_device *, struct class_interface *);
 314        int (*add_dev)          (struct device *, struct class_interface *);
 315        void (*remove_dev)      (struct device *, struct class_interface *);
 316};
 317
 318extern int __must_check class_interface_register(struct class_interface *);
 319extern void class_interface_unregister(struct class_interface *);
 320
 321extern struct class *class_create(struct module *owner, const char *name);
 322extern void class_destroy(struct class *cls);
 323extern struct class_device *class_device_create(struct class *cls,
 324                                                struct class_device *parent,
 325                                                dev_t devt,
 326                                                struct device *device,
 327                                                const char *fmt, ...)
 328                                        __attribute__((format(printf,5,6)));
 329extern void class_device_destroy(struct class *cls, dev_t devt);
 330
 331/*
 332 * The type of device, "struct device" is embedded in. A class
 333 * or bus can contain devices of different types
 334 * like "partitions" and "disks", "mouse" and "event".
 335 * This identifies the device type and carries type-specific
 336 * information, equivalent to the kobj_type of a kobject.
 337 * If "name" is specified, the uevent will contain it in
 338 * the DEVTYPE variable.
 339 */
 340struct device_type {
 341        const char *name;
 342        struct attribute_group **groups;
 343        int (*uevent)(struct device *dev, char **envp, int num_envp,
 344                      char *buffer, int buffer_size);
 345        void (*release)(struct device *dev);
 346        int (*suspend)(struct device * dev, pm_message_t state);
 347        int (*resume)(struct device * dev);
 348};
 349
 350/* interface for exporting device attributes */
 351struct device_attribute {
 352        struct attribute        attr;
 353        ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 354                        char *buf);
 355        ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 356                         const char *buf, size_t count);
 357};
 358
 359#define DEVICE_ATTR(_name,_mode,_show,_store) \
 360struct device_attribute dev_attr_##_name = __ATTR(_name,_mode,_show,_store)
 361
 362extern int __must_check device_create_file(struct device *device,
 363                                        struct device_attribute * entry);
 364extern void device_remove_file(struct device * dev, struct device_attribute * attr);
 365extern int __must_check device_create_bin_file(struct device *dev,
 366                                               struct bin_attribute *attr);
 367extern void device_remove_bin_file(struct device *dev,
 368                                   struct bin_attribute *attr);
 369extern int device_schedule_callback_owner(struct device *dev,
 370                void (*func)(struct device *), struct module *owner);
 371
 372/* This is a macro to avoid include problems with THIS_MODULE */
 373#define device_schedule_callback(dev, func)                     \
 374        device_schedule_callback_owner(dev, func, THIS_MODULE)
 375
 376/* device resource management */
 377typedef void (*dr_release_t)(struct device *dev, void *res);
 378typedef int (*dr_match_t)(struct device *dev, void *res, void *match_data);
 379
 380#ifdef CONFIG_DEBUG_DEVRES
 381extern void * __devres_alloc(dr_release_t release, size_t size, gfp_t gfp,
 382                             const char *name);
 383#define devres_alloc(release, size, gfp) \
 384        __devres_alloc(release, size, gfp, #release)
 385#else
 386extern void * devres_alloc(dr_release_t release, size_t size, gfp_t gfp);
 387#endif
 388extern void devres_free(void *res);
 389extern void devres_add(struct device *dev, void *res);
 390extern void * devres_find(struct device *dev, dr_release_t release,
 391                          dr_match_t match, void *match_data);
 392extern void * devres_get(struct device *dev, void *new_res,
 393                         dr_match_t match, void *match_data);
 394extern void * devres_remove(struct device *dev, dr_release_t release,
 395                            dr_match_t match, void *match_data);
 396extern int devres_destroy(struct device *dev, dr_release_t release,
 397                          dr_match_t match, void *match_data);
 398
 399/* devres group */
 400extern void * __must_check devres_open_group(struct device *dev, void *id,
 401                                             gfp_t gfp);
 402extern void devres_close_group(struct device *dev, void *id);
 403extern void devres_remove_group(struct device *dev, void *id);
 404extern int devres_release_group(struct device *dev, void *id);
 405
 406/* managed kzalloc/kfree for device drivers, no kmalloc, always use kzalloc */
 407extern void *devm_kzalloc(struct device *dev, size_t size, gfp_t gfp);
 408extern void devm_kfree(struct device *dev, void *p);
 409
 410struct device {
 411        struct klist            klist_children;
 412        struct klist_node       knode_parent;           /* node in sibling list */
 413        struct klist_node       knode_driver;
 414        struct klist_node       knode_bus;
 415        struct device           *parent;
 416
 417        struct kobject kobj;
 418        char    bus_id[BUS_ID_SIZE];    /* position on parent bus */
 419        struct device_type      *type;
 420        unsigned                is_registered:1;
 421        unsigned                uevent_suppress:1;
 422        struct device_attribute uevent_attr;
 423        struct device_attribute *devt_attr;
 424
 425        struct semaphore        sem;    /* semaphore to synchronize calls to
 426                                         * its driver.
 427                                         */
 428
 429        struct bus_type * bus;          /* type of bus device is on */
 430        struct device_driver *driver;   /* which driver has allocated this
 431                                           device */
 432        void            *driver_data;   /* data private to the driver */
 433        void            *platform_data; /* Platform specific data, device
 434                                           core doesn't touch it */
 435        struct dev_pm_info      power;
 436
 437#ifdef CONFIG_NUMA
 438        int             numa_node;      /* NUMA node this device is close to */
 439#endif
 440        u64             *dma_mask;      /* dma mask (if dma'able device) */
 441        u64             coherent_dma_mask;/* Like dma_mask, but for
 442                                             alloc_coherent mappings as
 443                                             not all hardware supports
 444                                             64 bit addresses for consistent
 445                                             allocations such descriptors. */
 446
 447        struct list_head        dma_pools;      /* dma pools (if dma'ble) */
 448
 449        struct dma_coherent_mem *dma_mem; /* internal for coherent mem
 450                                             override */
 451        /* arch specific additions */
 452        struct dev_archdata     archdata;
 453
 454        spinlock_t              devres_lock;
 455        struct list_head        devres_head;
 456
 457        /* class_device migration path */
 458        struct list_head        node;
 459        struct class            *class;
 460        dev_t                   devt;           /* dev_t, creates the sysfs "dev" */
 461        struct attribute_group  **groups;       /* optional groups */
 462
 463        void    (*release)(struct device * dev);
 464};
 465
 466#ifdef CONFIG_NUMA
 467static inline int dev_to_node(struct device *dev)
 468{
 469        return dev->numa_node;
 470}
 471static inline void set_dev_node(struct device *dev, int node)
 472{
 473        dev->numa_node = node;
 474}
 475#else
 476static inline int dev_to_node(struct device *dev)
 477{
 478        return -1;
 479}
 480static inline void set_dev_node(struct device *dev, int node)
 481{
 482}
 483#endif
 484
 485static inline void *
 486dev_get_drvdata (struct device *dev)
 487{
 488        return dev->driver_data;
 489}
 490
 491static inline void
 492dev_set_drvdata (struct device *dev, void *data)
 493{
 494        dev->driver_data = data;
 495}
 496
 497static inline int device_is_registered(struct device *dev)
 498{
 499        return dev->is_registered;
 500}
 501
 502void driver_init(void);
 503
 504/*
 505 * High level routines for use by the bus drivers
 506 */
 507extern int __must_check device_register(struct device * dev);
 508extern void device_unregister(struct device * dev);
 509extern void device_initialize(struct device * dev);
 510extern int __must_check device_add(struct device * dev);
 511extern void device_del(struct device * dev);
 512extern int device_for_each_child(struct device *, void *,
 513                     int (*fn)(struct device *, void *));
 514extern struct device *device_find_child(struct device *, void *data,
 515                                        int (*match)(struct device *, void *));
 516extern int device_rename(struct device *dev, char *new_name);
 517extern int device_move(struct device *dev, struct device *new_parent);
 518
 519/*
 520 * Manual binding of a device to driver. See drivers/base/bus.c
 521 * for information on use.
 522 */
 523extern int __must_check device_bind_driver(struct device *dev);
 524extern void device_release_driver(struct device * dev);
 525extern int  __must_check device_attach(struct device * dev);
 526extern int __must_check driver_attach(struct device_driver *drv);
 527extern int __must_check device_reprobe(struct device *dev);
 528
 529/*
 530 * Easy functions for dynamically creating devices on the fly
 531 */
 532extern struct device *device_create(struct class *cls, struct device *parent,
 533                                    dev_t devt, const char *fmt, ...)
 534                                    __attribute__((format(printf,4,5)));
 535extern void device_destroy(struct class *cls, dev_t devt);
 536
 537/*
 538 * Platform "fixup" functions - allow the platform to have their say
 539 * about devices and actions that the general device layer doesn't
 540 * know about.
 541 */
 542/* Notify platform of device discovery */
 543extern int (*platform_notify)(struct device * dev);
 544
 545extern int (*platform_notify_remove)(struct device * dev);
 546
 547
 548/**
 549 * get_device - atomically increment the reference count for the device.
 550 *
 551 */
 552extern struct device * get_device(struct device * dev);
 553extern void put_device(struct device * dev);
 554
 555
 556/* drivers/base/power/shutdown.c */
 557extern void device_shutdown(void);
 558
 559
 560/* drivers/base/firmware.c */
 561extern int __must_check firmware_register(struct kset *);
 562extern void firmware_unregister(struct kset *);
 563
 564/* debugging and troubleshooting/diagnostic helpers. */
 565extern const char *dev_driver_string(struct device *dev);
 566#define dev_printk(level, dev, format, arg...)  \
 567        printk(level "%s %s: " format , dev_driver_string(dev) , (dev)->bus_id , ## arg)
 568
 569#ifdef DEBUG
 570#define dev_dbg(dev, format, arg...)            \
 571        dev_printk(KERN_DEBUG , dev , format , ## arg)
 572#else
 573static inline int __attribute__ ((format (printf, 2, 3)))
 574dev_dbg(struct device * dev, const char * fmt, ...)
 575{
 576        return 0;
 577}
 578#endif
 579
 580#define dev_err(dev, format, arg...)            \
 581        dev_printk(KERN_ERR , dev , format , ## arg)
 582#define dev_info(dev, format, arg...)           \
 583        dev_printk(KERN_INFO , dev , format , ## arg)
 584#define dev_warn(dev, format, arg...)           \
 585        dev_printk(KERN_WARNING , dev , format , ## arg)
 586#define dev_notice(dev, format, arg...)         \
 587        dev_printk(KERN_NOTICE , dev , format , ## arg)
 588
 589/* Create alias, so I can be autoloaded. */
 590#define MODULE_ALIAS_CHARDEV(major,minor) \
 591        MODULE_ALIAS("char-major-" __stringify(major) "-" __stringify(minor))
 592#define MODULE_ALIAS_CHARDEV_MAJOR(major) \
 593        MODULE_ALIAS("char-major-" __stringify(major) "-*")
 594#endif /* _DEVICE_H_ */
 595