1==============
  2Device Classes
  3==============
  4
  5Introduction
  6~~~~~~~~~~~~
  7A device class describes a type of device, like an audio or network
  8device. The following device classes have been identified:
  9
 10<Insert List of Device Classes Here>
 11
 12
 13Each device class defines a set of semantics and a programming interface
 14that devices of that class adhere to. Device drivers are the
 15implementation of that programming interface for a particular device on
 16a particular bus.
 17
 18Device classes are agnostic with respect to what bus a device resides
 19on.
 20
 21
 22Programming Interface
 23~~~~~~~~~~~~~~~~~~~~~
 24The device class structure looks like::
 25
 26
 27  typedef int (*devclass_add)(struct device *);
 28  typedef void (*devclass_remove)(struct device *);
 29
 30See the kerneldoc for the struct class.
 31
 32A typical device class definition would look like::
 33
 34  struct device_class input_devclass = {
 35        .name		= "input",
 36        .add_device	= input_add_device,
 37	.remove_device	= input_remove_device,
 38  };
 39
 40Each device class structure should be exported in a header file so it
 41can be used by drivers, extensions and interfaces.
 42
 43Device classes are registered and unregistered with the core using::
 44
 45  int devclass_register(struct device_class * cls);
 46  void devclass_unregister(struct device_class * cls);
 47
 48
 49Devices
 50~~~~~~~
 51As devices are bound to drivers, they are added to the device class
 52that the driver belongs to. Before the driver model core, this would
 53typically happen during the driver's probe() callback, once the device
 54has been initialized. It now happens after the probe() callback
 55finishes from the core.
 56
 57The device is enumerated in the class. Each time a device is added to
 58the class, the class's devnum field is incremented and assigned to the
 59device. The field is never decremented, so if the device is removed
 60from the class and re-added, it will receive a different enumerated
 61value.
 62
 63The class is allowed to create a class-specific structure for the
 64device and store it in the device's class_data pointer.
 65
 66There is no list of devices in the device class. Each driver has a
 67list of devices that it supports. The device class has a list of
 68drivers of that particular class. To access all of the devices in the
 69class, iterate over the device lists of each driver in the class.
 70
 71
 72Device Drivers
 73~~~~~~~~~~~~~~
 74Device drivers are added to device classes when they are registered
 75with the core. A driver specifies the class it belongs to by setting
 76the struct device_driver::devclass field.
 77
 78
 79sysfs directory structure
 80~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 81There is a top-level sysfs directory named 'class'.
 82
 83Each class gets a directory in the class directory, along with two
 84default subdirectories::
 85
 86        class/
 87        `-- input
 88            |-- devices
 89            `-- drivers
 90
 91
 92Drivers registered with the class get a symlink in the drivers/ directory
 93that points to the driver's directory (under its bus directory)::
 94
 95   class/
 96   `-- input
 97       |-- devices
 98       `-- drivers
 99           `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
100
101
102Each device gets a symlink in the devices/ directory that points to the
103device's directory in the physical hierarchy::
104
105   class/
106   `-- input
107       |-- devices
108       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
109       `-- drivers
110
111
112Exporting Attributes
113~~~~~~~~~~~~~~~~~~~~
114
115::
116
117  struct devclass_attribute {
118        struct attribute        attr;
119        ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
120        ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
121  };
122
123Class drivers can export attributes using the DEVCLASS_ATTR macro that works
124similarly to the DEVICE_ATTR macro for devices. For example, a definition
125like this::
126
127  static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
128
129is equivalent to declaring::
130
131  static devclass_attribute devclass_attr_debug;
132
133The bus driver can add and remove the attribute from the class's
134sysfs directory using::
135
136  int devclass_create_file(struct device_class *, struct devclass_attribute *);
137  void devclass_remove_file(struct device_class *, struct devclass_attribute *);
138
139In the example above, the file will be named 'debug' in placed in the
140class's directory in sysfs.
141
142
143Interfaces
144~~~~~~~~~~
145There may exist multiple mechanisms for accessing the same device of a
146particular class type. Device interfaces describe these mechanisms.
147
148When a device is added to a device class, the core attempts to add it
149to every interface that is registered with the device class.