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 | ||
30 | struct 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 | ||
47 | A typical device class definition would look like: | |
48 | ||
49 | struct device_class input_devclass = { | |
50 | .name = "input", | |
51 | .add_device = input_add_device, | |
52 | .remove_device = input_remove_device, | |
53 | }; | |
54 | ||
55 | Each device class structure should be exported in a header file so it | |
56 | can be used by drivers, extensions and interfaces. | |
57 | ||
58 | Device classes are registered and unregistered with the core using: | |
59 | ||
60 | int devclass_register(struct device_class * cls); | |
61 | void devclass_unregister(struct device_class * cls); | |
62 | ||
63 | ||
64 | Devices | |
65 | ~~~~~~~ | |
66 | As devices are bound to drivers, they are added to the device class | |
67 | that the driver belongs to. Before the driver model core, this would | |
68 | typically happen during the driver's probe() callback, once the device | |
69 | has been initialized. It now happens after the probe() callback | |
70 | finishes from the core. | |
71 | ||
72 | The device is enumerated in the class. Each time a device is added to | |
73 | the class, the class's devnum field is incremented and assigned to the | |
74 | device. The field is never decremented, so if the device is removed | |
75 | from the class and re-added, it will receive a different enumerated | |
76 | value. | |
77 | ||
78 | The class is allowed to create a class-specific structure for the | |
79 | device and store it in the device's class_data pointer. | |
80 | ||
81 | There is no list of devices in the device class. Each driver has a | |
82 | list of devices that it supports. The device class has a list of | |
83 | drivers of that particular class. To access all of the devices in the | |
84 | class, iterate over the device lists of each driver in the class. | |
85 | ||
86 | ||
87 | Device Drivers | |
88 | ~~~~~~~~~~~~~~ | |
89 | Device drivers are added to device classes when they are registered | |
90 | with the core. A driver specifies the class it belongs to by setting | |
91 | the struct device_driver::devclass field. | |
92 | ||
93 | ||
94 | sysfs directory structure | |
95 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
96 | There is a top-level sysfs directory named 'class'. | |
97 | ||
98 | Each class gets a directory in the class directory, along with two | |
99 | default subdirectories: | |
100 | ||
101 | class/ | |
102 | `-- input | |
103 | |-- devices | |
104 | `-- drivers | |
105 | ||
106 | ||
107 | Drivers registered with the class get a symlink in the drivers/ directory | |
108 | that 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 | ||
117 | Each device gets a symlink in the devices/ directory that points to the | |
118 | device'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 | ||
127 | Exporting Attributes | |
128 | ~~~~~~~~~~~~~~~~~~~~ | |
129 | struct 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 | ||
135 | Class drivers can export attributes using the DEVCLASS_ATTR macro that works | |
136 | similarly to the DEVICE_ATTR macro for devices. For example, a definition | |
137 | like this: | |
138 | ||
139 | static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); | |
140 | ||
141 | is equivalent to declaring: | |
142 | ||
143 | static devclass_attribute devclass_attr_debug; | |
144 | ||
145 | The bus driver can add and remove the attribute from the class's | |
146 | sysfs directory using: | |
147 | ||
148 | int devclass_create_file(struct device_class *, struct devclass_attribute *); | |
149 | void devclass_remove_file(struct device_class *, struct devclass_attribute *); | |
150 | ||
151 | In the example above, the file will be named 'debug' in placed in the | |
152 | class's directory in sysfs. | |
153 | ||
154 | ||
155 | Interfaces | |
156 | ~~~~~~~~~~ | |
157 | There may exist multiple mechanisms for accessing the same device of a | |
158 | particular class type. Device interfaces describe these mechanisms. | |
159 | ||
160 | When a device is added to a device class, the core attempts to add it | |
161 | to every interface that is registered with the device class. | |
162 |