Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Device Classes | |
3 | ||
4 | ||
5 | Introduction | |
6 | ~~~~~~~~~~~~ | |
7 | A device class describes a type of device, like an audio or network | |
8 | device. The following device classes have been identified: | |
9 | ||
10 | <Insert List of Device Classes Here> | |
11 | ||
12 | ||
13 | Each device class defines a set of semantics and a programming interface | |
14 | that devices of that class adhere to. Device drivers are the | |
2fe0ae78 | 15 | implementation of that programming interface for a particular device on |
1da177e4 LT |
16 | a particular bus. |
17 | ||
18 | Device classes are agnostic with respect to what bus a device resides | |
19 | on. | |
20 | ||
21 | ||
22 | Programming Interface | |
23 | ~~~~~~~~~~~~~~~~~~~~~ | |
24 | The device class structure looks like: | |
25 | ||
26 | ||
27 | typedef int (*devclass_add)(struct device *); | |
28 | typedef void (*devclass_remove)(struct device *); | |
29 | ||
63dc355a | 30 | See the kerneldoc for the struct class. |
1da177e4 LT |
31 | |
32 | A 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 | ||
40 | Each device class structure should be exported in a header file so it | |
41 | can be used by drivers, extensions and interfaces. | |
42 | ||
43 | Device 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 | ||
49 | Devices | |
50 | ~~~~~~~ | |
51 | As devices are bound to drivers, they are added to the device class | |
52 | that the driver belongs to. Before the driver model core, this would | |
53 | typically happen during the driver's probe() callback, once the device | |
54 | has been initialized. It now happens after the probe() callback | |
55 | finishes from the core. | |
56 | ||
57 | The device is enumerated in the class. Each time a device is added to | |
58 | the class, the class's devnum field is incremented and assigned to the | |
59 | device. The field is never decremented, so if the device is removed | |
60 | from the class and re-added, it will receive a different enumerated | |
61 | value. | |
62 | ||
63 | The class is allowed to create a class-specific structure for the | |
64 | device and store it in the device's class_data pointer. | |
65 | ||
66 | There is no list of devices in the device class. Each driver has a | |
67 | list of devices that it supports. The device class has a list of | |
68 | drivers of that particular class. To access all of the devices in the | |
69 | class, iterate over the device lists of each driver in the class. | |
70 | ||
71 | ||
72 | Device Drivers | |
73 | ~~~~~~~~~~~~~~ | |
74 | Device drivers are added to device classes when they are registered | |
75 | with the core. A driver specifies the class it belongs to by setting | |
76 | the struct device_driver::devclass field. | |
77 | ||
78 | ||
79 | sysfs directory structure | |
80 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
81 | There is a top-level sysfs directory named 'class'. | |
82 | ||
83 | Each class gets a directory in the class directory, along with two | |
84 | default subdirectories: | |
85 | ||
86 | class/ | |
87 | `-- input | |
88 | |-- devices | |
89 | `-- drivers | |
90 | ||
91 | ||
92 | Drivers registered with the class get a symlink in the drivers/ directory | |
93 | that 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 | ||
102 | Each device gets a symlink in the devices/ directory that points to the | |
103 | device'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 | ||
112 | Exporting Attributes | |
113 | ~~~~~~~~~~~~~~~~~~~~ | |
114 | struct 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 | ||
120 | Class drivers can export attributes using the DEVCLASS_ATTR macro that works | |
121 | similarly to the DEVICE_ATTR macro for devices. For example, a definition | |
122 | like this: | |
123 | ||
124 | static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); | |
125 | ||
126 | is equivalent to declaring: | |
127 | ||
128 | static devclass_attribute devclass_attr_debug; | |
129 | ||
130 | The bus driver can add and remove the attribute from the class's | |
131 | sysfs directory using: | |
132 | ||
133 | int devclass_create_file(struct device_class *, struct devclass_attribute *); | |
134 | void devclass_remove_file(struct device_class *, struct devclass_attribute *); | |
135 | ||
136 | In the example above, the file will be named 'debug' in placed in the | |
137 | class's directory in sysfs. | |
138 | ||
139 | ||
140 | Interfaces | |
141 | ~~~~~~~~~~ | |
142 | There may exist multiple mechanisms for accessing the same device of a | |
143 | particular class type. Device interfaces describe these mechanisms. | |
144 | ||
145 | When a device is added to a device class, the core attempts to add it | |
146 | to every interface that is registered with the device class. | |
147 |