About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / driver-model / class.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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
15	implementation of that programming interface for a particular device on
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	See the kerneldoc for the struct class.
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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog