linux/Documentation/driver-model/class.txt
<<
>>
Prefs
   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
  27typedef int (*devclass_add)(struct device *);
  28typedef void (*devclass_remove)(struct device *);
  29
  30See the kerneldoc for the struct class.
  31
  32A typical device class definition would look like: 
  33
  34struct 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
  45int devclass_register(struct device_class * cls);
  46void 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~~~~~~~~~~~~~~~~~~~~
 114struct devclass_attribute {
 115        struct attribute        attr;
 116        ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
 117        ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
 118};
 119
 120Class drivers can export attributes using the DEVCLASS_ATTR macro that works
 121similarly to the DEVICE_ATTR macro for devices. For example, a definition 
 122like this:
 123
 124static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
 125
 126is equivalent to declaring:
 127
 128static devclass_attribute devclass_attr_debug;
 129
 130The bus driver can add and remove the attribute from the class's
 131sysfs directory using:
 132
 133int devclass_create_file(struct device_class *, struct devclass_attribute *);
 134void devclass_remove_file(struct device_class *, struct devclass_attribute *);
 135
 136In the example above, the file will be named 'debug' in placed in the
 137class's directory in sysfs. 
 138
 139
 140Interfaces
 141~~~~~~~~~~
 142There may exist multiple mechanisms for accessing the same device of a
 143particular class type. Device interfaces describe these mechanisms. 
 144
 145When a device is added to a device class, the core attempts to add it
 146to every interface that is registered with the device class.
 147
 148
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.