aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/driver-model/class.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/driver-model/class.txt')
-rw-r--r--Documentation/driver-model/class.txt162
1 files changed, 162 insertions, 0 deletions
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.txt
new file mode 100644
index 000000000000..2d1d893a5e5d
--- /dev/null
+++ b/Documentation/driver-model/class.txt
@@ -0,0 +1,162 @@
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
15implemention 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
30struct device_class {
31 char * name;
32 rwlock_t lock;
33 u32 devnum;
34 struct list_head node;
35
36 struct list_head drivers;
37 struct list_head intf_list;
38
39 struct driver_dir_entry dir;
40 struct driver_dir_entry device_dir;
41 struct driver_dir_entry driver_dir;
42
43 devclass_add add_device;
44 devclass_remove remove_device;
45};
46
47A typical device class definition would look like:
48
49struct device_class input_devclass = {
50 .name = "input",
51 .add_device = input_add_device,
52 .remove_device = input_remove_device,
53};
54
55Each device class structure should be exported in a header file so it
56can be used by drivers, extensions and interfaces.
57
58Device classes are registered and unregistered with the core using:
59
60int devclass_register(struct device_class * cls);
61void devclass_unregister(struct device_class * cls);
62
63
64Devices
65~~~~~~~
66As devices are bound to drivers, they are added to the device class
67that the driver belongs to. Before the driver model core, this would
68typically happen during the driver's probe() callback, once the device
69has been initialized. It now happens after the probe() callback
70finishes from the core.
71
72The device is enumerated in the class. Each time a device is added to
73the class, the class's devnum field is incremented and assigned to the
74device. The field is never decremented, so if the device is removed
75from the class and re-added, it will receive a different enumerated
76value.
77
78The class is allowed to create a class-specific structure for the
79device and store it in the device's class_data pointer.
80
81There is no list of devices in the device class. Each driver has a
82list of devices that it supports. The device class has a list of
83drivers of that particular class. To access all of the devices in the
84class, iterate over the device lists of each driver in the class.
85
86
87Device Drivers
88~~~~~~~~~~~~~~
89Device drivers are added to device classes when they are registered
90with the core. A driver specifies the class it belongs to by setting
91the struct device_driver::devclass field.
92
93
94sysfs directory structure
95~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96There is a top-level sysfs directory named 'class'.
97
98Each class gets a directory in the class directory, along with two
99default subdirectories:
100
101 class/
102 `-- input
103 |-- devices
104 `-- drivers
105
106
107Drivers registered with the class get a symlink in the drivers/ directory
108that points to the driver's directory (under its bus directory):
109
110 class/
111 `-- input
112 |-- devices
113 `-- drivers
114 `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
115
116
117Each device gets a symlink in the devices/ directory that points to the
118device's directory in the physical hierarchy:
119
120 class/
121 `-- input
122 |-- devices
123 | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
124 `-- drivers
125
126
127Exporting Attributes
128~~~~~~~~~~~~~~~~~~~~
129struct devclass_attribute {
130 struct attribute attr;
131 ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
132 ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
133};
134
135Class drivers can export attributes using the DEVCLASS_ATTR macro that works
136similarly to the DEVICE_ATTR macro for devices. For example, a definition
137like this:
138
139static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
140
141is equivalent to declaring:
142
143static devclass_attribute devclass_attr_debug;
144
145The bus driver can add and remove the attribute from the class's
146sysfs directory using:
147
148int devclass_create_file(struct device_class *, struct devclass_attribute *);
149void devclass_remove_file(struct device_class *, struct devclass_attribute *);
150
151In the example above, the file will be named 'debug' in placed in the
152class's directory in sysfs.
153
154
155Interfaces
156~~~~~~~~~~
157There may exist multiple mechanisms for accessing the same device of a
158particular class type. Device interfaces describe these mechanisms.
159
160When a device is added to a device class, the core attempts to add it
161to every interface that is registered with the device class.
162