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/mutex.h> 24 #include <linux/pinctrl/devinfo.h> 25 #include <linux/pm.h> 26 #include <linux/atomic.h> 27 #include <linux/ratelimit.h> 28 #include <linux/uidgid.h> 29 #include <asm/device.h> 30 31 struct device; 32 struct device_private; 33 struct device_driver; 34 struct driver_private; 35 struct module; 36 struct class; 37 struct subsys_private; 38 struct bus_type; 39 struct device_node; 40 struct iommu_ops; 41 struct iommu_group; 42 43 struct bus_attribute { 44 struct attribute attr; 45 ssize_t (*show)(struct bus_type *bus, char *buf); 46 ssize_t (*store)(struct bus_type *bus, const char *buf, size_t count); 47 }; 48 49 #define BUS_ATTR(_name, _mode, _show, _store) \ 50 struct bus_attribute bus_attr_##_name = __ATTR(_name, _mode, _show, _store) 51 #define BUS_ATTR_RW(_name) \ 52 struct bus_attribute bus_attr_##_name = __ATTR_RW(_name) 53 #define BUS_ATTR_RO(_name) \ 54 struct bus_attribute bus_attr_##_name = __ATTR_RO(_name) 55 56 extern int __must_check bus_create_file(struct bus_type *, 57 struct bus_attribute *); 58 extern void bus_remove_file(struct bus_type *, struct bus_attribute *); 59 60 /** 61 * struct bus_type - The bus type of the device 62 * 63 * @name: The name of the bus. 64 * @dev_name: Used for subsystems to enumerate devices like ("foo%u", dev->id). 65 * @dev_root: Default device to use as the parent. 66 * @bus_attrs: Default attributes of the bus. 67 * @dev_attrs: Default attributes of the devices on the bus. 68 * @drv_attrs: Default attributes of the device drivers on the bus. 69 * @bus_groups: Default attributes of the bus. 70 * @dev_groups: Default attributes of the devices on the bus. 71 * @drv_groups: Default attributes of the device drivers on the bus. 72 * @match: Called, perhaps multiple times, whenever a new device or driver 73 * is added for this bus. It should return a nonzero value if the 74 * given device can be handled by the given driver. 75 * @uevent: Called when a device is added, removed, or a few other things 76 * that generate uevents to add the environment variables. 77 * @probe: Called when a new device or driver add to this bus, and callback 78 * the specific driver's probe to initial the matched device. 79 * @remove: Called when a device removed from this bus. 80 * @shutdown: Called at shut-down time to quiesce the device. 81 * 82 * @online: Called to put the device back online (after offlining it). 83 * @offline: Called to put the device offline for hot-removal. May fail. 84 * 85 * @suspend: Called when a device on this bus wants to go to sleep mode. 86 * @resume: Called to bring a device on this bus out of sleep mode. 87 * @pm: Power management operations of this bus, callback the specific 88 * device driver's pm-ops. 89 * @iommu_ops: IOMMU specific operations for this bus, used to attach IOMMU 90 * driver implementations to a bus and allow the driver to do 91 * bus-specific setup 92 * @p: The private data of the driver core, only the driver core can 93 * touch this. 94 * @lock_key: Lock class key for use by the lock validator 95 * 96 * A bus is a channel between the processor and one or more devices. For the 97 * purposes of the device model, all devices are connected via a bus, even if 98 * it is an internal, virtual, "platform" bus. Buses can plug into each other. 99 * A USB controller is usually a PCI device, for example. The device model 100 * represents the actual connections between buses and the devices they control. 101 * A bus is represented by the bus_type structure. It contains the name, the 102 * default attributes, the bus' methods, PM operations, and the driver core's 103 * private data. 104 */ 105 struct bus_type { 106 const char *name; 107 const char *dev_name; 108 struct device *dev_root; 109 struct bus_attribute *bus_attrs; /* use bus_groups instead */ 110 struct device_attribute *dev_attrs; /* use dev_groups instead */ 111 struct driver_attribute *drv_attrs; /* use drv_groups instead */ 112 const struct attribute_group **bus_groups; 113 const struct attribute_group **dev_groups; 114 const struct attribute_group **drv_groups; 115 116 int (*match)(struct device *dev, struct device_driver *drv); 117 int (*uevent)(struct device *dev, struct kobj_uevent_env *env); 118 int (*probe)(struct device *dev); 119 int (*remove)(struct device *dev); 120 void (*shutdown)(struct device *dev); 121 122 int (*online)(struct device *dev); 123 int (*offline)(struct device *dev); 124 125 int (*suspend)(struct device *dev, pm_message_t state); 126 int (*resume)(struct device *dev); 127 128 const struct dev_pm_ops *pm; 129 130 struct iommu_ops *iommu_ops; 131 132 struct subsys_private *p; 133 struct lock_class_key lock_key; 134 }; 135 136 extern int __must_check bus_register(struct bus_type *bus); 137 138 extern void bus_unregister(struct bus_type *bus); 139 140 extern int __must_check bus_rescan_devices(struct bus_type *bus); 141 142 /* iterator helpers for buses */ 143 struct subsys_dev_iter { 144 struct klist_iter ki; 145 const struct device_type *type; 146 }; 147 void subsys_dev_iter_init(struct subsys_dev_iter *iter, 148 struct bus_type *subsys, 149 struct device *start, 150 const struct device_type *type); 151 struct device *subsys_dev_iter_next(struct subsys_dev_iter *iter); 152 void subsys_dev_iter_exit(struct subsys_dev_iter *iter); 153 154 int bus_for_each_dev(struct bus_type *bus, struct device *start, void *data, 155 int (*fn)(struct device *dev, void *data)); 156 struct device *bus_find_device(struct bus_type *bus, struct device *start, 157 void *data, 158 int (*match)(struct device *dev, void *data)); 159 struct device *bus_find_device_by_name(struct bus_type *bus, 160 struct device *start, 161 const char *name); 162 struct device *subsys_find_device_by_id(struct bus_type *bus, unsigned int id, 163 struct device *hint); 164 int bus_for_each_drv(struct bus_type *bus, struct device_driver *start, 165 void *data, int (*fn)(struct device_driver *, void *)); 166 void bus_sort_breadthfirst(struct bus_type *bus, 167 int (*compare)(const struct device *a, 168 const struct device *b)); 169 /* 170 * Bus notifiers: Get notified of addition/removal of devices 171 * and binding/unbinding of drivers to devices. 172 * In the long run, it should be a replacement for the platform 173 * notify hooks. 174 */ 175 struct notifier_block; 176 177 extern int bus_register_notifier(struct bus_type *bus, 178 struct notifier_block *nb); 179 extern int bus_unregister_notifier(struct bus_type *bus, 180 struct notifier_block *nb); 181 182 /* All 4 notifers below get called with the target struct device * 183 * as an argument. Note that those functions are likely to be called 184 * with the device lock held in the core, so be careful. 185 */ 186 #define BUS_NOTIFY_ADD_DEVICE 0x00000001 /* device added */ 187 #define BUS_NOTIFY_DEL_DEVICE 0x00000002 /* device removed */ 188 #define BUS_NOTIFY_BIND_DRIVER 0x00000003 /* driver about to be 189 bound */ 190 #define BUS_NOTIFY_BOUND_DRIVER 0x00000004 /* driver bound to device */ 191 #define BUS_NOTIFY_UNBIND_DRIVER 0x00000005 /* driver about to be 192 unbound */ 193 #define BUS_NOTIFY_UNBOUND_DRIVER 0x00000006 /* driver is unbound 194 from the device */ 195 196 extern struct kset *bus_get_kset(struct bus_type *bus); 197 extern struct klist *bus_get_device_klist(struct bus_type *bus); 198 199 /** 200 * struct device_driver - The basic device driver structure 201 * @name: Name of the device driver. 202 * @bus: The bus which the device of this driver belongs to. 203 * @owner: The module owner. 204 * @mod_name: Used for built-in modules. 205 * @suppress_bind_attrs: Disables bind/unbind via sysfs. 206 * @of_match_table: The open firmware table. 207 * @acpi_match_table: The ACPI match table. 208 * @probe: Called to query the existence of a specific device, 209 * whether this driver can work with it, and bind the driver 210 * to a specific device. 211 * @remove: Called when the device is removed from the system to 212 * unbind a device from this driver. 213 * @shutdown: Called at shut-down time to quiesce the device. 214 * @suspend: Called to put the device to sleep mode. Usually to a 215 * low power state. 216 * @resume: Called to bring a device from sleep mode. 217 * @groups: Default attributes that get created by the driver core 218 * automatically. 219 * @pm: Power management operations of the device which matched 220 * this driver. 221 * @p: Driver core's private data, no one other than the driver 222 * core can touch this. 223 * 224 * The device driver-model tracks all of the drivers known to the system. 225 * The main reason for this tracking is to enable the driver core to match 226 * up drivers with new devices. Once drivers are known objects within the 227 * system, however, a number of other things become possible. Device drivers 228 * can export information and configuration variables that are independent 229 * of any specific device. 230 */ 231 struct device_driver { 232 const char *name; 233 struct bus_type *bus; 234 235 struct module *owner; 236 const char *mod_name; /* used for built-in modules */ 237 238 bool suppress_bind_attrs; /* disables bind/unbind via sysfs */ 239 240 const struct of_device_id *of_match_table; 241 const struct acpi_device_id *acpi_match_table; 242 243 int (*probe) (struct device *dev); 244 int (*remove) (struct device *dev); 245 void (*shutdown) (struct device *dev); 246 int (*suspend) (struct device *dev, pm_message_t state); 247 int (*resume) (struct device *dev); 248 const struct attribute_group **groups; 249 250 const struct dev_pm_ops *pm; 251 252 struct driver_private *p; 253 }; 254 255 256 extern int __must_check driver_register(struct device_driver *drv); 257 extern void driver_unregister(struct device_driver *drv); 258 259 extern struct device_driver *driver_find(const char *name, 260 struct bus_type *bus); 261 extern int driver_probe_done(void); 262 extern void wait_for_device_probe(void); 263 264 265 /* sysfs interface for exporting driver attributes */ 266 267 struct driver_attribute { 268 struct attribute attr; 269 ssize_t (*show)(struct device_driver *driver, char *buf); 270 ssize_t (*store)(struct device_driver *driver, const char *buf, 271 size_t count); 272 }; 273 274 #define DRIVER_ATTR(_name, _mode, _show, _store) \ 275 struct driver_attribute driver_attr_##_name = __ATTR(_name, _mode, _show, _store) 276 #define DRIVER_ATTR_RW(_name) \ 277 struct driver_attribute driver_attr_##_name = __ATTR_RW(_name) 278 #define DRIVER_ATTR_RO(_name) \ 279 struct driver_attribute driver_attr_##_name = __ATTR_RO(_name) 280 #define DRIVER_ATTR_WO(_name) \ 281 struct driver_attribute driver_attr_##_name = __ATTR_WO(_name) 282 283 extern int __must_check driver_create_file(struct device_driver *driver, 284 const struct driver_attribute *attr); 285 extern void driver_remove_file(struct device_driver *driver, 286 const struct driver_attribute *attr); 287 288 extern int __must_check driver_for_each_device(struct device_driver *drv, 289 struct device *start, 290 void *data, 291 int (*fn)(struct device *dev, 292 void *)); 293 struct device *driver_find_device(struct device_driver *drv, 294 struct device *start, void *data, 295 int (*match)(struct device *dev, void *data)); 296 297 /** 298 * struct subsys_interface - interfaces to device functions 299 * @name: name of the device function 300 * @subsys: subsytem of the devices to attach to 301 * @node: the list of functions registered at the subsystem 302 * @add_dev: device hookup to device function handler 303 * @remove_dev: device hookup to device function handler 304 * 305 * Simple interfaces attached to a subsystem. Multiple interfaces can 306 * attach to a subsystem and its devices. Unlike drivers, they do not 307 * exclusively claim or control devices. Interfaces usually represent 308 * a specific functionality of a subsystem/class of devices. 309 */ 310 struct subsys_interface { 311 const char *name; 312 struct bus_type *subsys; 313 struct list_head node; 314 int (*add_dev)(struct device *dev, struct subsys_interface *sif); 315 int (*remove_dev)(struct device *dev, struct subsys_interface *sif); 316 }; 317 318 int subsys_interface_register(struct subsys_interface *sif); 319 void subsys_interface_unregister(struct subsys_interface *sif); 320 321 int subsys_system_register(struct bus_type *subsys, 322 const struct attribute_group **groups); 323 int subsys_virtual_register(struct bus_type *subsys, 324 const struct attribute_group **groups); 325 326 /** 327 * struct class - device classes 328 * @name: Name of the class. 329 * @owner: The module owner. 330 * @class_attrs: Default attributes of this class. 331 * @dev_groups: Default attributes of the devices that belong to the class. 332 * @dev_attrs: Default attributes of the devices belong to the class. 333 * @dev_bin_attrs: Default binary attributes of the devices belong to the class. 334 * @dev_kobj: The kobject that represents this class and links it into the hierarchy. 335 * @dev_uevent: Called when a device is added, removed from this class, or a 336 * few other things that generate uevents to add the environment 337 * variables. 338 * @devnode: Callback to provide the devtmpfs. 339 * @class_release: Called to release this class. 340 * @dev_release: Called to release the device. 341 * @suspend: Used to put the device to sleep mode, usually to a low power 342 * state. 343 * @resume: Used to bring the device from the sleep mode. 344 * @ns_type: Callbacks so sysfs can detemine namespaces. 345 * @namespace: Namespace of the device belongs to this class. 346 * @pm: The default device power management operations of this class. 347 * @p: The private data of the driver core, no one other than the 348 * driver core can touch this. 349 * 350 * A class is a higher-level view of a device that abstracts out low-level 351 * implementation details. Drivers may see a SCSI disk or an ATA disk, but, 352 * at the class level, they are all simply disks. Classes allow user space 353 * to work with devices based on what they do, rather than how they are 354 * connected or how they work. 355 */ 356 struct class { 357 const char *name; 358 struct module *owner; 359 360 struct class_attribute *class_attrs; 361 struct device_attribute *dev_attrs; /* use dev_groups instead */ 362 const struct attribute_group **dev_groups; 363 struct bin_attribute *dev_bin_attrs; 364 struct kobject *dev_kobj; 365 366 int (*dev_uevent)(struct device *dev, struct kobj_uevent_env *env); 367 char *(*devnode)(struct device *dev, umode_t *mode); 368 369 void (*class_release)(struct class *class); 370 void (*dev_release)(struct device *dev); 371 372 int (*suspend)(struct device *dev, pm_message_t state); 373 int (*resume)(struct device *dev); 374 375 const struct kobj_ns_type_operations *ns_type; 376 const void *(*namespace)(struct device *dev); 377 378 const struct dev_pm_ops *pm; 379 380 struct subsys_private *p; 381 }; 382 383 struct class_dev_iter { 384 struct klist_iter ki; 385 const struct device_type *type; 386 }; 387 388 extern struct kobject *sysfs_dev_block_kobj; 389 extern struct kobject *sysfs_dev_char_kobj; 390 extern int __must_check __class_register(struct class *class, 391 struct lock_class_key *key); 392 extern void class_unregister(struct class *class); 393 394 /* This is a #define to keep the compiler from merging different 395 * instances of the __key variable */ 396 #define class_register(class) \ 397 ({ \ 398 static struct lock_class_key __key; \ 399 __class_register(class, &__key); \ 400 }) 401 402 struct class_compat; 403 struct class_compat *class_compat_register(const char *name); 404 void class_compat_unregister(struct class_compat *cls); 405 int class_compat_create_link(struct class_compat *cls, struct device *dev, 406 struct device *device_link); 407 void class_compat_remove_link(struct class_compat *cls, struct device *dev, 408 struct device *device_link); 409 410 extern void class_dev_iter_init(struct class_dev_iter *iter, 411 struct class *class, 412 struct device *start, 413 const struct device_type *type); 414 extern struct device *class_dev_iter_next(struct class_dev_iter *iter); 415 extern void class_dev_iter_exit(struct class_dev_iter *iter); 416 417 extern int class_for_each_device(struct class *class, struct device *start, 418 void *data, 419 int (*fn)(struct device *dev, void *data)); 420 extern struct device *class_find_device(struct class *class, 421 struct device *start, const void *data, 422 int (*match)(struct device *, const void *)); 423 424 struct class_attribute { 425 struct attribute attr; 426 ssize_t (*show)(struct class *class, struct class_attribute *attr, 427 char *buf); 428 ssize_t (*store)(struct class *class, struct class_attribute *attr, 429 const char *buf, size_t count); 430 const void *(*namespace)(struct class *class, 431 const struct class_attribute *attr); 432 }; 433 434 #define CLASS_ATTR(_name, _mode, _show, _store) \ 435 struct class_attribute class_attr_##_name = __ATTR(_name, _mode, _show, _store) 436 #define CLASS_ATTR_RW(_name) \ 437 struct class_attribute class_attr_##_name = __ATTR_RW(_name) 438 #define CLASS_ATTR_RO(_name) \ 439 struct class_attribute class_attr_##_name = __ATTR_RO(_name) 440 441 extern int __must_check class_create_file(struct class *class, 442 const struct class_attribute *attr); 443 extern void class_remove_file(struct class *class, 444 const struct class_attribute *attr); 445 446 /* Simple class attribute that is just a static string */ 447 struct class_attribute_string { 448 struct class_attribute attr; 449 char *str; 450 }; 451 452 /* Currently read-only only */ 453 #define _CLASS_ATTR_STRING(_name, _mode, _str) \ 454 { __ATTR(_name, _mode, show_class_attr_string, NULL), _str } 455 #define CLASS_ATTR_STRING(_name, _mode, _str) \ 456 struct class_attribute_string class_attr_##_name = \ 457 _CLASS_ATTR_STRING(_name, _mode, _str) 458 459 extern ssize_t show_class_attr_string(struct class *class, struct class_attribute *attr, 460 char *buf); 461 462 struct class_interface { 463 struct list_head node; 464 struct class *class; 465 466 int (*add_dev) (struct device *, struct class_interface *); 467 void (*remove_dev) (struct device *, struct class_interface *); 468 }; 469 470 extern int __must_check class_interface_register(struct class_interface *); 471 extern void class_interface_unregister(struct class_interface *); 472 473 extern struct class * __must_check __class_create(struct module *owner, 474 const char *name, 475 struct lock_class_key *key); 476 extern void class_destroy(struct class *cls); 477 478 /* This is a #define to keep the compiler from merging different 479 * instances of the __key variable */ 480 #define class_create(owner, name) \ 481 ({ \ 482 static struct lock_class_key __key; \ 483 __class_create(owner, name, &__key); \ 484 }) 485 486 /* 487 * The type of device, "struct device" is embedded in. A class 488 * or bus can contain devices of different types 489 * like "partitions" and "disks", "mouse" and "event". 490 * This identifies the device type and carries type-specific 491 * information, equivalent to the kobj_type of a kobject. 492 * If "name" is specified, the uevent will contain it in 493 * the DEVTYPE variable. 494 */ 495 struct device_type { 496 const char *name; 497 const struct attribute_group **groups; 498 int (*uevent)(struct device *dev, struct kobj_uevent_env *env); 499 char *(*devnode)(struct device *dev, umode_t *mode, 500 kuid_t *uid, kgid_t *gid); 501 void (*release)(struct device *dev); 502 503 const struct dev_pm_ops *pm; 504 }; 505 506 /* interface for exporting device attributes */ 507 struct device_attribute { 508 struct attribute attr; 509 ssize_t (*show)(struct device *dev, struct device_attribute *attr, 510 char *buf); 511 ssize_t (*store)(struct device *dev, struct device_attribute *attr, 512 const char *buf, size_t count); 513 }; 514 515 struct dev_ext_attribute { 516 struct device_attribute attr; 517 void *var; 518 }; 519 520 ssize_t device_show_ulong(struct device *dev, struct device_attribute *attr, 521 char *buf); 522 ssize_t device_store_ulong(struct device *dev, struct device_attribute *attr, 523 const char *buf, size_t count); 524 ssize_t device_show_int(struct device *dev, struct device_attribute *attr, 525 char *buf); 526 ssize_t device_store_int(struct device *dev, struct device_attribute *attr, 527 const char *buf, size_t count); 528 ssize_t device_show_bool(struct device *dev, struct device_attribute *attr, 529 char *buf); 530 ssize_t device_store_bool(struct device *dev, struct device_attribute *attr, 531 const char *buf, size_t count); 532 533 #define DEVICE_ATTR(_name, _mode, _show, _store) \ 534 struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) 535 #define DEVICE_ATTR_RW(_name) \ 536 struct device_attribute dev_attr_##_name = __ATTR_RW(_name) 537 #define DEVICE_ATTR_RO(_name) \ 538 struct device_attribute dev_attr_##_name = __ATTR_RO(_name) 539 #define DEVICE_ATTR_WO(_name) \ 540 struct device_attribute dev_attr_##_name = __ATTR_WO(_name) 541 #define DEVICE_ULONG_ATTR(_name, _mode, _var) \ 542 struct dev_ext_attribute dev_attr_##_name = \ 543 { __ATTR(_name, _mode, device_show_ulong, device_store_ulong), &(_var) } 544 #define DEVICE_INT_ATTR(_name, _mode, _var) \ 545 struct dev_ext_attribute dev_attr_##_name = \ 546 { __ATTR(_name, _mode, device_show_int, device_store_int), &(_var) } 547 #define DEVICE_BOOL_ATTR(_name, _mode, _var) \ 548 struct dev_ext_attribute dev_attr_##_name = \ 549 { __ATTR(_name, _mode, device_show_bool, device_store_bool), &(_var) } 550 #define DEVICE_ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) \ 551 struct device_attribute dev_attr_##_name = \ 552 __ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) 553 554 extern int device_create_file(struct device *device, 555 const struct device_attribute *entry); 556 extern void device_remove_file(struct device *dev, 557 const struct device_attribute *attr); 558 extern int __must_check device_create_bin_file(struct device *dev, 559 const struct bin_attribute *attr); 560 extern void device_remove_bin_file(struct device *dev, 561 const struct bin_attribute *attr); 562 extern int device_schedule_callback_owner(struct device *dev, 563 void (*func)(struct device *dev), struct module *owner); 564 565 /* This is a macro to avoid include problems with THIS_MODULE */ 566 #define device_schedule_callback(dev, func) \ 567 device_schedule_callback_owner(dev, func, THIS_MODULE) 568 569 /* device resource management */ 570 typedef void (*dr_release_t)(struct device *dev, void *res); 571 typedef int (*dr_match_t)(struct device *dev, void *res, void *match_data); 572 573 #ifdef CONFIG_DEBUG_DEVRES 574 extern void *__devres_alloc(dr_release_t release, size_t size, gfp_t gfp, 575 const char *name); 576 #define devres_alloc(release, size, gfp) \ 577 __devres_alloc(release, size, gfp, #release) 578 #else 579 extern void *devres_alloc(dr_release_t release, size_t size, gfp_t gfp); 580 #endif 581 extern void devres_for_each_res(struct device *dev, dr_release_t release, 582 dr_match_t match, void *match_data, 583 void (*fn)(struct device *, void *, void *), 584 void *data); 585 extern void devres_free(void *res); 586 extern void devres_add(struct device *dev, void *res); 587 extern void *devres_find(struct device *dev, dr_release_t release, 588 dr_match_t match, void *match_data); 589 extern void *devres_get(struct device *dev, void *new_res, 590 dr_match_t match, void *match_data); 591 extern void *devres_remove(struct device *dev, dr_release_t release, 592 dr_match_t match, void *match_data); 593 extern int devres_destroy(struct device *dev, dr_release_t release, 594 dr_match_t match, void *match_data); 595 extern int devres_release(struct device *dev, dr_release_t release, 596 dr_match_t match, void *match_data); 597 598 /* devres group */ 599 extern void * __must_check devres_open_group(struct device *dev, void *id, 600 gfp_t gfp); 601 extern void devres_close_group(struct device *dev, void *id); 602 extern void devres_remove_group(struct device *dev, void *id); 603 extern int devres_release_group(struct device *dev, void *id); 604 605 /* managed kzalloc/kfree for device drivers, no kmalloc, always use kzalloc */ 606 extern void *devm_kzalloc(struct device *dev, size_t size, gfp_t gfp); 607 extern void devm_kfree(struct device *dev, void *p); 608 609 void __iomem *devm_ioremap_resource(struct device *dev, struct resource *res); 610 void __iomem *devm_request_and_ioremap(struct device *dev, 611 struct resource *res); 612 613 /* allows to add/remove a custom action to devres stack */ 614 int devm_add_action(struct device *dev, void (*action)(void *), void *data); 615 void devm_remove_action(struct device *dev, void (*action)(void *), void *data); 616 617 struct device_dma_parameters { 618 /* 619 * a low level driver may set these to teach IOMMU code about 620 * sg limitations. 621 */ 622 unsigned int max_segment_size; 623 unsigned long segment_boundary_mask; 624 }; 625 626 struct acpi_dev_node { 627 #ifdef CONFIG_ACPI 628 void *handle; 629 #endif 630 }; 631 632 /** 633 * struct device - The basic device structure 634 * @parent: The device's "parent" device, the device to which it is attached. 635 * In most cases, a parent device is some sort of bus or host 636 * controller. If parent is NULL, the device, is a top-level device, 637 * which is not usually what you want. 638 * @p: Holds the private data of the driver core portions of the device. 639 * See the comment of the struct device_private for detail. 640 * @kobj: A top-level, abstract class from which other classes are derived. 641 * @init_name: Initial name of the device. 642 * @type: The type of device. 643 * This identifies the device type and carries type-specific 644 * information. 645 * @mutex: Mutex to synchronize calls to its driver. 646 * @bus: Type of bus device is on. 647 * @driver: Which driver has allocated this 648 * @platform_data: Platform data specific to the device. 649 * Example: For devices on custom boards, as typical of embedded 650 * and SOC based hardware, Linux often uses platform_data to point 651 * to board-specific structures describing devices and how they 652 * are wired. That can include what ports are available, chip 653 * variants, which GPIO pins act in what additional roles, and so 654 * on. This shrinks the "Board Support Packages" (BSPs) and 655 * minimizes board-specific #ifdefs in drivers. 656 * @power: For device power management. 657 * See Documentation/power/devices.txt for details. 658 * @pm_domain: Provide callbacks that are executed during system suspend, 659 * hibernation, system resume and during runtime PM transitions 660 * along with subsystem-level and driver-level callbacks. 661 * @pins: For device pin management. 662 * See Documentation/pinctrl.txt for details. 663 * @numa_node: NUMA node this device is close to. 664 * @dma_mask: Dma mask (if dma'ble device). 665 * @coherent_dma_mask: Like dma_mask, but for alloc_coherent mapping as not all 666 * hardware supports 64-bit addresses for consistent allocations 667 * such descriptors. 668 * @dma_parms: A low level driver may set these to teach IOMMU code about 669 * segment limitations. 670 * @dma_pools: Dma pools (if dma'ble device). 671 * @dma_mem: Internal for coherent mem override. 672 * @cma_area: Contiguous memory area for dma allocations 673 * @archdata: For arch-specific additions. 674 * @of_node: Associated device tree node. 675 * @acpi_node: Associated ACPI device node. 676 * @devt: For creating the sysfs "dev". 677 * @id: device instance 678 * @devres_lock: Spinlock to protect the resource of the device. 679 * @devres_head: The resources list of the device. 680 * @knode_class: The node used to add the device to the class list. 681 * @class: The class of the device. 682 * @groups: Optional attribute groups. 683 * @release: Callback to free the device after all references have 684 * gone away. This should be set by the allocator of the 685 * device (i.e. the bus driver that discovered the device). 686 * @iommu_group: IOMMU group the device belongs to. 687 * 688 * @offline_disabled: If set, the device is permanently online. 689 * @offline: Set after successful invocation of bus type's .offline(). 690 * 691 * At the lowest level, every device in a Linux system is represented by an 692 * instance of struct device. The device structure contains the information 693 * that the device model core needs to model the system. Most subsystems, 694 * however, track additional information about the devices they host. As a 695 * result, it is rare for devices to be represented by bare device structures; 696 * instead, that structure, like kobject structures, is usually embedded within 697 * a higher-level representation of the device. 698 */ 699 struct device { 700 struct device *parent; 701 702 struct device_private *p; 703 704 struct kobject kobj; 705 const char *init_name; /* initial name of the device */ 706 const struct device_type *type; 707 708 struct mutex mutex; /* mutex to synchronize calls to 709 * its driver. 710 */ 711 712 struct bus_type *bus; /* type of bus device is on */ 713 struct device_driver *driver; /* which driver has allocated this 714 device */ 715 void *platform_data; /* Platform specific data, device 716 core doesn't touch it */ 717 struct dev_pm_info power; 718 struct dev_pm_domain *pm_domain; 719 720 #ifdef CONFIG_PINCTRL 721 struct dev_pin_info *pins; 722 #endif 723 724 #ifdef CONFIG_NUMA 725 int numa_node; /* NUMA node this device is close to */ 726 #endif 727 u64 *dma_mask; /* dma mask (if dma'able device) */ 728 u64 coherent_dma_mask;/* Like dma_mask, but for 729 alloc_coherent mappings as 730 not all hardware supports 731 64 bit addresses for consistent 732 allocations such descriptors. */ 733 734 struct device_dma_parameters *dma_parms; 735 736 struct list_head dma_pools; /* dma pools (if dma'ble) */ 737 738 struct dma_coherent_mem *dma_mem; /* internal for coherent mem 739 override */ 740 #ifdef CONFIG_DMA_CMA 741 struct cma *cma_area; /* contiguous memory area for dma 742 allocations */ 743 #endif 744 /* arch specific additions */ 745 struct dev_archdata archdata; 746 747 struct device_node *of_node; /* associated device tree node */ 748 struct acpi_dev_node acpi_node; /* associated ACPI device node */ 749 750 dev_t devt; /* dev_t, creates the sysfs "dev" */ 751 u32 id; /* device instance */ 752 753 spinlock_t devres_lock; 754 struct list_head devres_head; 755 756 struct klist_node knode_class; 757 struct class *class; 758 const struct attribute_group **groups; /* optional groups */ 759 760 void (*release)(struct device *dev); 761 struct iommu_group *iommu_group; 762 763 bool offline_disabled:1; 764 bool offline:1; 765 }; 766 767 static inline struct device *kobj_to_dev(struct kobject *kobj) 768 { 769 return container_of(kobj, struct device, kobj); 770 } 771 772 #ifdef CONFIG_ACPI 773 #define ACPI_HANDLE(dev) ((dev)->acpi_node.handle) 774 #define ACPI_HANDLE_SET(dev, _handle_) (dev)->acpi_node.handle = (_handle_) 775 #else 776 #define ACPI_HANDLE(dev) (NULL) 777 #define ACPI_HANDLE_SET(dev, _handle_) do { } while (0) 778 #endif 779 780 /* Get the wakeup routines, which depend on struct device */ 781 #include <linux/pm_wakeup.h> 782 783 static inline const char *dev_name(const struct device *dev) 784 { 785 /* Use the init name until the kobject becomes available */ 786 if (dev->init_name) 787 return dev->init_name; 788 789 return kobject_name(&dev->kobj); 790 } 791 792 extern __printf(2, 3) 793 int dev_set_name(struct device *dev, const char *name, ...); 794 795 #ifdef CONFIG_NUMA 796 static inline int dev_to_node(struct device *dev) 797 { 798 return dev->numa_node; 799 } 800 static inline void set_dev_node(struct device *dev, int node) 801 { 802 dev->numa_node = node; 803 } 804 #else 805 static inline int dev_to_node(struct device *dev) 806 { 807 return -1; 808 } 809 static inline void set_dev_node(struct device *dev, int node) 810 { 811 } 812 #endif 813 814 static inline struct pm_subsys_data *dev_to_psd(struct device *dev) 815 { 816 return dev ? dev->power.subsys_data : NULL; 817 } 818 819 static inline unsigned int dev_get_uevent_suppress(const struct device *dev) 820 { 821 return dev->kobj.uevent_suppress; 822 } 823 824 static inline void dev_set_uevent_suppress(struct device *dev, int val) 825 { 826 dev->kobj.uevent_suppress = val; 827 } 828 829 static inline int device_is_registered(struct device *dev) 830 { 831 return dev->kobj.state_in_sysfs; 832 } 833 834 static inline void device_enable_async_suspend(struct device *dev) 835 { 836 if (!dev->power.is_prepared) 837 dev->power.async_suspend = true; 838 } 839 840 static inline void device_disable_async_suspend(struct device *dev) 841 { 842 if (!dev->power.is_prepared) 843 dev->power.async_suspend = false; 844 } 845 846 static inline bool device_async_suspend_enabled(struct device *dev) 847 { 848 return !!dev->power.async_suspend; 849 } 850 851 static inline void pm_suspend_ignore_children(struct device *dev, bool enable) 852 { 853 dev->power.ignore_children = enable; 854 } 855 856 static inline void dev_pm_syscore_device(struct device *dev, bool val) 857 { 858 #ifdef CONFIG_PM_SLEEP 859 dev->power.syscore = val; 860 #endif 861 } 862 863 static inline void device_lock(struct device *dev) 864 { 865 mutex_lock(&dev->mutex); 866 } 867 868 static inline int device_trylock(struct device *dev) 869 { 870 return mutex_trylock(&dev->mutex); 871 } 872 873 static inline void device_unlock(struct device *dev) 874 { 875 mutex_unlock(&dev->mutex); 876 } 877 878 void driver_init(void); 879 880 /* 881 * High level routines for use by the bus drivers 882 */ 883 extern int __must_check device_register(struct device *dev); 884 extern void device_unregister(struct device *dev); 885 extern void device_initialize(struct device *dev); 886 extern int __must_check device_add(struct device *dev); 887 extern void device_del(struct device *dev); 888 extern int device_for_each_child(struct device *dev, void *data, 889 int (*fn)(struct device *dev, void *data)); 890 extern struct device *device_find_child(struct device *dev, void *data, 891 int (*match)(struct device *dev, void *data)); 892 extern int device_rename(struct device *dev, const char *new_name); 893 extern int device_move(struct device *dev, struct device *new_parent, 894 enum dpm_order dpm_order); 895 extern const char *device_get_devnode(struct device *dev, 896 umode_t *mode, kuid_t *uid, kgid_t *gid, 897 const char **tmp); 898 extern void *dev_get_drvdata(const struct device *dev); 899 extern int dev_set_drvdata(struct device *dev, void *data); 900 901 static inline bool device_supports_offline(struct device *dev) 902 { 903 return dev->bus && dev->bus->offline && dev->bus->online; 904 } 905 906 extern void lock_device_hotplug(void); 907 extern void unlock_device_hotplug(void); 908 extern int lock_device_hotplug_sysfs(void); 909 extern int device_offline(struct device *dev); 910 extern int device_online(struct device *dev); 911 /* 912 * Root device objects for grouping under /sys/devices 913 */ 914 extern struct device *__root_device_register(const char *name, 915 struct module *owner); 916 917 /* 918 * This is a macro to avoid include problems with THIS_MODULE, 919 * just as per what is done for device_schedule_callback() above. 920 */ 921 #define root_device_register(name) \ 922 __root_device_register(name, THIS_MODULE) 923 924 extern void root_device_unregister(struct device *root); 925 926 static inline void *dev_get_platdata(const struct device *dev) 927 { 928 return dev->platform_data; 929 } 930 931 /* 932 * Manual binding of a device to driver. See drivers/base/bus.c 933 * for information on use. 934 */ 935 extern int __must_check device_bind_driver(struct device *dev); 936 extern void device_release_driver(struct device *dev); 937 extern int __must_check device_attach(struct device *dev); 938 extern int __must_check driver_attach(struct device_driver *drv); 939 extern int __must_check device_reprobe(struct device *dev); 940 941 /* 942 * Easy functions for dynamically creating devices on the fly 943 */ 944 extern struct device *device_create_vargs(struct class *cls, 945 struct device *parent, 946 dev_t devt, 947 void *drvdata, 948 const char *fmt, 949 va_list vargs); 950 extern __printf(5, 6) 951 struct device *device_create(struct class *cls, struct device *parent, 952 dev_t devt, void *drvdata, 953 const char *fmt, ...); 954 extern __printf(6, 7) 955 struct device *device_create_with_groups(struct class *cls, 956 struct device *parent, dev_t devt, void *drvdata, 957 const struct attribute_group **groups, 958 const char *fmt, ...); 959 extern void device_destroy(struct class *cls, dev_t devt); 960 961 /* 962 * Platform "fixup" functions - allow the platform to have their say 963 * about devices and actions that the general device layer doesn't 964 * know about. 965 */ 966 /* Notify platform of device discovery */ 967 extern int (*platform_notify)(struct device *dev); 968 969 extern int (*platform_notify_remove)(struct device *dev); 970 971 972 /* 973 * get_device - atomically increment the reference count for the device. 974 * 975 */ 976 extern struct device *get_device(struct device *dev); 977 extern void put_device(struct device *dev); 978 979 #ifdef CONFIG_DEVTMPFS 980 extern int devtmpfs_create_node(struct device *dev); 981 extern int devtmpfs_delete_node(struct device *dev); 982 extern int devtmpfs_mount(const char *mntdir); 983 #else 984 static inline int devtmpfs_create_node(struct device *dev) { return 0; } 985 static inline int devtmpfs_delete_node(struct device *dev) { return 0; } 986 static inline int devtmpfs_mount(const char *mountpoint) { return 0; } 987 #endif 988 989 /* drivers/base/power/shutdown.c */ 990 extern void device_shutdown(void); 991 992 /* debugging and troubleshooting/diagnostic helpers. */ 993 extern const char *dev_driver_string(const struct device *dev); 994 995 996 #ifdef CONFIG_PRINTK 997 998 extern __printf(3, 0) 999 int dev_vprintk_emit(int level, const struct device *dev, 1000 const char *fmt, va_list args); 1001 extern __printf(3, 4) 1002 int dev_printk_emit(int level, const struct device *dev, const char *fmt, ...); 1003 1004 extern __printf(3, 4) 1005 int dev_printk(const char *level, const struct device *dev, 1006 const char *fmt, ...); 1007 extern __printf(2, 3) 1008 int dev_emerg(const struct device *dev, const char *fmt, ...); 1009 extern __printf(2, 3) 1010 int dev_alert(const struct device *dev, const char *fmt, ...); 1011 extern __printf(2, 3) 1012 int dev_crit(const struct device *dev, const char *fmt, ...); 1013 extern __printf(2, 3) 1014 int dev_err(const struct device *dev, const char *fmt, ...); 1015 extern __printf(2, 3) 1016 int dev_warn(const struct device *dev, const char *fmt, ...); 1017 extern __printf(2, 3) 1018 int dev_notice(const struct device *dev, const char *fmt, ...); 1019 extern __printf(2, 3) 1020 int _dev_info(const struct device *dev, const char *fmt, ...); 1021 1022 #else 1023 1024 static inline __printf(3, 0) 1025 int dev_vprintk_emit(int level, const struct device *dev, 1026 const char *fmt, va_list args) 1027 { return 0; } 1028 static inline __printf(3, 4) 1029 int dev_printk_emit(int level, const struct device *dev, const char *fmt, ...) 1030 { return 0; } 1031 1032 static inline int __dev_printk(const char *level, const struct device *dev, 1033 struct va_format *vaf) 1034 { return 0; } 1035 static inline __printf(3, 4) 1036 int dev_printk(const char *level, const struct device *dev, 1037 const char *fmt, ...) 1038 { return 0; } 1039 1040 static inline __printf(2, 3) 1041 int dev_emerg(const struct device *dev, const char *fmt, ...) 1042 { return 0; } 1043 static inline __printf(2, 3) 1044 int dev_crit(const struct device *dev, const char *fmt, ...) 1045 { return 0; } 1046 static inline __printf(2, 3) 1047 int dev_alert(const struct device *dev, const char *fmt, ...) 1048 { return 0; } 1049 static inline __printf(2, 3) 1050 int dev_err(const struct device *dev, const char *fmt, ...) 1051 { return 0; } 1052 static inline __printf(2, 3) 1053 int dev_warn(const struct device *dev, const char *fmt, ...) 1054 { return 0; } 1055 static inline __printf(2, 3) 1056 int dev_notice(const struct device *dev, const char *fmt, ...) 1057 { return 0; } 1058 static inline __printf(2, 3) 1059 int _dev_info(const struct device *dev, const char *fmt, ...) 1060 { return 0; } 1061 1062 #endif 1063 1064 /* 1065 * Stupid hackaround for existing uses of non-printk uses dev_info 1066 * 1067 * Note that the definition of dev_info below is actually _dev_info 1068 * and a macro is used to avoid redefining dev_info 1069 */ 1070 1071 #define dev_info(dev, fmt, arg...) _dev_info(dev, fmt, ##arg) 1072 1073 #if defined(CONFIG_DYNAMIC_DEBUG) 1074 #define dev_dbg(dev, format, ...) \ 1075 do { \ 1076 dynamic_dev_dbg(dev, format, ##__VA_ARGS__); \ 1077 } while (0) 1078 #elif defined(DEBUG) 1079 #define dev_dbg(dev, format, arg...) \ 1080 dev_printk(KERN_DEBUG, dev, format, ##arg) 1081 #else 1082 #define dev_dbg(dev, format, arg...) \ 1083 ({ \ 1084 if (0) \ 1085 dev_printk(KERN_DEBUG, dev, format, ##arg); \ 1086 0; \ 1087 }) 1088 #endif 1089 1090 #define dev_level_ratelimited(dev_level, dev, fmt, ...) \ 1091 do { \ 1092 static DEFINE_RATELIMIT_STATE(_rs, \ 1093 DEFAULT_RATELIMIT_INTERVAL, \ 1094 DEFAULT_RATELIMIT_BURST); \ 1095 if (__ratelimit(&_rs)) \ 1096 dev_level(dev, fmt, ##__VA_ARGS__); \ 1097 } while (0) 1098 1099 #define dev_emerg_ratelimited(dev, fmt, ...) \ 1100 dev_level_ratelimited(dev_emerg, dev, fmt, ##__VA_ARGS__) 1101 #define dev_alert_ratelimited(dev, fmt, ...) \ 1102 dev_level_ratelimited(dev_alert, dev, fmt, ##__VA_ARGS__) 1103 #define dev_crit_ratelimited(dev, fmt, ...) \ 1104 dev_level_ratelimited(dev_crit, dev, fmt, ##__VA_ARGS__) 1105 #define dev_err_ratelimited(dev, fmt, ...) \ 1106 dev_level_ratelimited(dev_err, dev, fmt, ##__VA_ARGS__) 1107 #define dev_warn_ratelimited(dev, fmt, ...) \ 1108 dev_level_ratelimited(dev_warn, dev, fmt, ##__VA_ARGS__) 1109 #define dev_notice_ratelimited(dev, fmt, ...) \ 1110 dev_level_ratelimited(dev_notice, dev, fmt, ##__VA_ARGS__) 1111 #define dev_info_ratelimited(dev, fmt, ...) \ 1112 dev_level_ratelimited(dev_info, dev, fmt, ##__VA_ARGS__) 1113 #if defined(CONFIG_DYNAMIC_DEBUG) 1114 /* descriptor check is first to prevent flooding with "callbacks suppressed" */ 1115 #define dev_dbg_ratelimited(dev, fmt, ...) \ 1116 do { \ 1117 static DEFINE_RATELIMIT_STATE(_rs, \ 1118 DEFAULT_RATELIMIT_INTERVAL, \ 1119 DEFAULT_RATELIMIT_BURST); \ 1120 DEFINE_DYNAMIC_DEBUG_METADATA(descriptor, fmt); \ 1121 if (unlikely(descriptor.flags & _DPRINTK_FLAGS_PRINT) && \ 1122 __ratelimit(&_rs)) \ 1123 __dynamic_dev_dbg(&descriptor, dev, fmt, \ 1124 ##__VA_ARGS__); \ 1125 } while (0) 1126 #elif defined(DEBUG) 1127 #define dev_dbg_ratelimited(dev, fmt, ...) \ 1128 do { \ 1129 static DEFINE_RATELIMIT_STATE(_rs, \ 1130 DEFAULT_RATELIMIT_INTERVAL, \ 1131 DEFAULT_RATELIMIT_BURST); \ 1132 if (__ratelimit(&_rs)) \ 1133 dev_printk(KERN_DEBUG, dev, fmt, ##__VA_ARGS__); \ 1134 } while (0) 1135 #else 1136 #define dev_dbg_ratelimited(dev, fmt, ...) \ 1137 no_printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__) 1138 #endif 1139 1140 #ifdef VERBOSE_DEBUG 1141 #define dev_vdbg dev_dbg 1142 #else 1143 #define dev_vdbg(dev, format, arg...) \ 1144 ({ \ 1145 if (0) \ 1146 dev_printk(KERN_DEBUG, dev, format, ##arg); \ 1147 0; \ 1148 }) 1149 #endif 1150 1151 /* 1152 * dev_WARN*() acts like dev_printk(), but with the key difference 1153 * of using a WARN/WARN_ON to get the message out, including the 1154 * file/line information and a backtrace. 1155 */ 1156 #define dev_WARN(dev, format, arg...) \ 1157 WARN(1, "Device: %s\n" format, dev_driver_string(dev), ## arg); 1158 1159 #define dev_WARN_ONCE(dev, condition, format, arg...) \ 1160 WARN_ONCE(condition, "Device %s\n" format, \ 1161 dev_driver_string(dev), ## arg) 1162 1163 /* Create alias, so I can be autoloaded. */ 1164 #define MODULE_ALIAS_CHARDEV(major,minor) \ 1165 MODULE_ALIAS("char-major-" __stringify(major) "-" __stringify(minor)) 1166 #define MODULE_ALIAS_CHARDEV_MAJOR(major) \ 1167 MODULE_ALIAS("char-major-" __stringify(major) "-*") 1168 1169 #ifdef CONFIG_SYSFS_DEPRECATED 1170 extern long sysfs_deprecated; 1171 #else 1172 #define sysfs_deprecated 0 1173 #endif 1174 1175 /** 1176 * module_driver() - Helper macro for drivers that don't do anything 1177 * special in module init/exit. This eliminates a lot of boilerplate. 1178 * Each module may only use this macro once, and calling it replaces 1179 * module_init() and module_exit(). 1180 * 1181 * @__driver: driver name 1182 * @__register: register function for this driver type 1183 * @__unregister: unregister function for this driver type 1184 * @...: Additional arguments to be passed to __register and __unregister. 1185 * 1186 * Use this macro to construct bus specific macros for registering 1187 * drivers, and do not use it on its own. 1188 */ 1189 #define module_driver(__driver, __register, __unregister, ...) \ 1190 static int __init __driver##_init(void) \ 1191 { \ 1192 return __register(&(__driver) , ##__VA_ARGS__); \ 1193 } \ 1194 module_init(__driver##_init); \ 1195 static void __exit __driver##_exit(void) \ 1196 { \ 1197 __unregister(&(__driver) , ##__VA_ARGS__); \ 1198 } \ 1199 module_exit(__driver##_exit); 1200 1201 #endif /* _DEVICE_H_ */ 1202