About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / driver-model / driver.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:02 EST.

1	
2	Device Drivers
3	
4	See the kerneldoc for the struct device_driver.
5	
6	
7	Allocation
8	~~~~~~~~~~
9	
10	Device drivers are statically allocated structures. Though there may
11	be multiple devices in a system that a driver supports, struct
12	device_driver represents the driver as a whole (not a particular
13	device instance).
14	
15	Initialization
16	~~~~~~~~~~~~~~
17	
18	The driver must initialize at least the name and bus fields. It should
19	also initialize the devclass field (when it arrives), so it may obtain
20	the proper linkage internally. It should also initialize as many of
21	the callbacks as possible, though each is optional.
22	
23	Declaration
24	~~~~~~~~~~~
25	
26	As stated above, struct device_driver objects are statically
27	allocated. Below is an example declaration of the eepro100
28	driver. This declaration is hypothetical only; it relies on the driver
29	being converted completely to the new model. 
30	
31	static struct device_driver eepro100_driver = {
32	       .name		= "eepro100",
33	       .bus		= &pci_bus_type,
34	       
35	       .probe		= eepro100_probe,
36	       .remove		= eepro100_remove,
37	       .suspend		= eepro100_suspend,
38	       .resume		= eepro100_resume,
39	};
40	
41	Most drivers will not be able to be converted completely to the new
42	model because the bus they belong to has a bus-specific structure with
43	bus-specific fields that cannot be generalized. 
44	
45	The most common example of this are device ID structures. A driver
46	typically defines an array of device IDs that it supports. The format
47	of these structures and the semantics for comparing device IDs are
48	completely bus-specific. Defining them as bus-specific entities would
49	sacrifice type-safety, so we keep bus-specific structures around. 
50	
51	Bus-specific drivers should include a generic struct device_driver in
52	the definition of the bus-specific driver. Like this:
53	
54	struct pci_driver {
55	       const struct pci_device_id *id_table;
56	       struct device_driver	  driver;
57	};
58	
59	A definition that included bus-specific fields would look like
60	(using the eepro100 driver again):
61	
62	static struct pci_driver eepro100_driver = {
63	       .id_table       = eepro100_pci_tbl,
64	       .driver	       = {
65			.name		= "eepro100",
66			.bus		= &pci_bus_type,
67			.probe		= eepro100_probe,
68			.remove		= eepro100_remove,
69			.suspend	= eepro100_suspend,
70			.resume		= eepro100_resume,
71	       },
72	};
73	
74	Some may find the syntax of embedded struct initialization awkward or
75	even a bit ugly. So far, it's the best way we've found to do what we want...
76	
77	Registration
78	~~~~~~~~~~~~
79	
80	int driver_register(struct device_driver * drv);
81	
82	The driver registers the structure on startup. For drivers that have
83	no bus-specific fields (i.e. don't have a bus-specific driver
84	structure), they would use driver_register and pass a pointer to their
85	struct device_driver object. 
86	
87	Most drivers, however, will have a bus-specific structure and will
88	need to register with the bus using something like pci_driver_register.
89	
90	It is important that drivers register their driver structure as early as
91	possible. Registration with the core initializes several fields in the
92	struct device_driver object, including the reference count and the
93	lock. These fields are assumed to be valid at all times and may be
94	used by the device model core or the bus driver.
95	
96	
97	Transition Bus Drivers
98	~~~~~~~~~~~~~~~~~~~~~~
99	
100	By defining wrapper functions, the transition to the new model can be
101	made easier. Drivers can ignore the generic structure altogether and
102	let the bus wrapper fill in the fields. For the callbacks, the bus can
103	define generic callbacks that forward the call to the bus-specific
104	callbacks of the drivers. 
105	
106	This solution is intended to be only temporary. In order to get class
107	information in the driver, the drivers must be modified anyway. Since
108	converting drivers to the new model should reduce some infrastructural
109	complexity and code size, it is recommended that they are converted as
110	class information is added.
111	
112	Access
113	~~~~~~
114	
115	Once the object has been registered, it may access the common fields of
116	the object, like the lock and the list of devices. 
117	
118	int driver_for_each_dev(struct device_driver * drv, void * data, 
119			        int (*callback)(struct device * dev, void * data));
120	
121	The devices field is a list of all the devices that have been bound to
122	the driver. The LDM core provides a helper function to operate on all
123	the devices a driver controls. This helper locks the driver on each
124	node access, and does proper reference counting on each device as it
125	accesses it. 
126	
127	
128	sysfs
129	~~~~~
130	
131	When a driver is registered, a sysfs directory is created in its
132	bus's directory. In this directory, the driver can export an interface
133	to userspace to control operation of the driver on a global basis;
134	e.g. toggling debugging output in the driver.
135	
136	A future feature of this directory will be a 'devices' directory. This
137	directory will contain symlinks to the directories of devices it
138	supports.
139	
140	
141	
142	Callbacks
143	~~~~~~~~~
144	
145		int	(*probe)	(struct device * dev);
146	
147	The probe() entry is called in task context, with the bus's rwsem locked
148	and the driver partially bound to the device.  Drivers commonly use
149	container_of() to convert "dev" to a bus-specific type, both in probe()
150	and other routines.  That type often provides device resource data, such
151	as pci_dev.resource[] or platform_device.resources, which is used in
152	addition to dev->platform_data to initialize the driver.
153	
154	This callback holds the driver-specific logic to bind the driver to a
155	given device.  That includes verifying that the device is present, that
156	it's a version the driver can handle, that driver data structures can
157	be allocated and initialized, and that any hardware can be initialized.
158	Drivers often store a pointer to their state with dev_set_drvdata().
159	When the driver has successfully bound itself to that device, then probe()
160	returns zero and the driver model code will finish its part of binding
161	the driver to that device.
162	
163	A driver's probe() may return a negative errno value to indicate that
164	the driver did not bind to this device, in which case it should have
165	released all resources it allocated.
166	
167		int 	(*remove)	(struct device * dev);
168	
169	remove is called to unbind a driver from a device. This may be
170	called if a device is physically removed from the system, if the
171	driver module is being unloaded, during a reboot sequence, or
172	in other cases.
173	
174	It is up to the driver to determine if the device is present or
175	not. It should free any resources allocated specifically for the
176	device; i.e. anything in the device's driver_data field. 
177	
178	If the device is still present, it should quiesce the device and place
179	it into a supported low-power state.
180	
181		int	(*suspend)	(struct device * dev, pm_message_t state);
182	
183	suspend is called to put the device in a low power state.
184	
185		int	(*resume)	(struct device * dev);
186	
187	Resume is used to bring a device back from a low power state.
188	
189	
190	Attributes
191	~~~~~~~~~~
192	struct driver_attribute {
193	        struct attribute        attr;
194	        ssize_t (*show)(struct device_driver *driver, char *buf);
195	        ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
196	};
197	
198	Device drivers can export attributes via their sysfs directories. 
199	Drivers can declare attributes using a DRIVER_ATTR macro that works
200	identically to the DEVICE_ATTR macro. 
201	
202	Example:
203	
204	DRIVER_ATTR(debug,0644,show_debug,store_debug);
205	
206	This is equivalent to declaring:
207	
208	struct driver_attribute driver_attr_debug;
209	
210	This can then be used to add and remove the attribute from the
211	driver's directory using:
212	
213	int driver_create_file(struct device_driver *, const struct driver_attribute *);
214	void driver_remove_file(struct device_driver *, const struct driver_attribute *);
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.