FreeBSD/Linux Kernel Cross Reference
sys/kern/device_if.m
1 #-
2 # Copyright (c) 1998-2004 Doug Rabson
3 # All rights reserved.
4 #
5 # Redistribution and use in source and binary forms, with or without
6 # modification, are permitted provided that the following conditions
7 # are met:
8 # 1. Redistributions of source code must retain the above copyright
9 # notice, this list of conditions and the following disclaimer.
10 # 2. Redistributions in binary form must reproduce the above copyright
11 # notice, this list of conditions and the following disclaimer in the
12 # documentation and/or other materials provided with the distribution.
13 #
14 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 # SUCH DAMAGE.
25 #
26 # $FreeBSD: releng/11.1/sys/kern/device_if.m 300113 2016-05-18 04:35:58Z scottl $
27 #
28
29 #include <sys/bus.h>
30
31 /**
32 * @defgroup DEVICE device - KObj methods for all device drivers
33 * @brief A basic set of methods required for all device drivers.
34 *
35 * The device interface is used to match devices to drivers during
36 * autoconfiguration and provides methods to allow drivers to handle
37 * system-wide events such as suspend, resume or shutdown.
38 * @{
39 */
40 INTERFACE device;
41
42 #
43 # Default implementations of some methods.
44 #
45 CODE {
46 static int null_shutdown(device_t dev)
47 {
48 return 0;
49 }
50
51 static int null_suspend(device_t dev)
52 {
53 return 0;
54 }
55
56 static int null_resume(device_t dev)
57 {
58 return 0;
59 }
60
61 static int null_quiesce(device_t dev)
62 {
63 return 0;
64 }
65
66 static void * null_register(device_t dev)
67 {
68 return NULL;
69 }
70 };
71
72 /**
73 * @brief Probe to see if a device matches a driver.
74 *
75 * Users should not call this method directly. Normally, this
76 * is called via device_probe_and_attach() to select a driver
77 * calling the DEVICE_PROBE() of all candidate drivers and attach
78 * the winning driver (if any) to the device.
79 *
80 * This function is used to match devices to device drivers.
81 * Typically, the driver will examine the device to see if
82 * it is suitable for this driver. This might include checking
83 * the values of various device instance variables or reading
84 * hardware registers.
85 *
86 * In some cases, there may be more than one driver available
87 * which can be used for a device (for instance there might
88 * be a generic driver which works for a set of many types of
89 * device and a more specific driver which works for a subset
90 * of devices). Because of this, a driver should not assume
91 * that it will be the driver that attaches to the device even
92 * if it returns a success status from DEVICE_PROBE(). In particular,
93 * a driver must free any resources which it allocated during
94 * the probe before returning. The return value of DEVICE_PROBE()
95 * is used to elect which driver is used - the driver which returns
96 * the largest non-error value wins the election and attaches to
97 * the device. Common non-error values are described in the
98 * DEVICE_PROBE(9) manual page.
99 *
100 * If a driver matches the hardware, it should set the device
101 * description string using device_set_desc() or
102 * device_set_desc_copy(). This string is used to generate an
103 * informative message when DEVICE_ATTACH() is called.
104 *
105 * As a special case, if a driver returns zero, the driver election
106 * is cut short and that driver will attach to the device
107 * immediately. This should rarely be used.
108 *
109 * For example, a probe method for a PCI device driver might look
110 * like this:
111 *
112 * @code
113 * int
114 * foo_probe(device_t dev)
115 * {
116 * if (pci_get_vendor(dev) == FOOVENDOR &&
117 * pci_get_device(dev) == FOODEVICE) {
118 * device_set_desc(dev, "Foo device");
119 * return (BUS_PROBE_DEFAULT);
120 * }
121 * return (ENXIO);
122 * }
123 * @endcode
124 *
125 * To include this method in a device driver, use a line like this
126 * in the driver's method list:
127 *
128 * @code
129 * KOBJMETHOD(device_probe, foo_probe)
130 * @endcode
131 *
132 * @param dev the device to probe
133 *
134 * @retval 0 if this is the only possible driver for this
135 * device
136 * @retval negative if the driver can match this device - the
137 * least negative value is used to select the
138 * driver
139 * @retval ENXIO if the driver does not match the device
140 * @retval positive if some kind of error was detected during
141 * the probe, a regular unix error code should
142 * be returned to indicate the type of error
143 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
144 */
145 METHOD int probe {
146 device_t dev;
147 };
148
149 /**
150 * @brief Allow a device driver to detect devices not otherwise enumerated.
151 *
152 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
153 * bus driver) to help populate the bus device with a useful set of
154 * child devices, normally by calling the BUS_ADD_CHILD() method of
155 * the parent device. For instance, the ISA bus driver uses several
156 * special drivers, including the isahint driver and the pnp driver to
157 * create child devices based on configuration hints and PnP bus
158 * probes respectively.
159 *
160 * Many bus drivers which support true plug-and-play do not need to
161 * use this method at all since child devices can be discovered
162 * automatically without help from child drivers.
163 *
164 * To include this method in a device driver, use a line like this
165 * in the driver's method list:
166 *
167 * @code
168 * KOBJMETHOD(device_identify, foo_identify)
169 * @endcode
170 *
171 * @param driver the driver whose identify method is being called
172 * @param parent the parent device to use when adding new children
173 */
174 STATICMETHOD void identify {
175 driver_t *driver;
176 device_t parent;
177 };
178
179 /**
180 * @brief Attach a device to a device driver
181 *
182 * Normally only called via device_probe_and_attach(), this is called
183 * when a driver has succeeded in probing against a device.
184 * This method should initialise the hardware and allocate other
185 * system resources (e.g. devfs entries) as required.
186 *
187 * To include this method in a device driver, use a line like this
188 * in the driver's method list:
189 *
190 * @code
191 * KOBJMETHOD(device_attach, foo_attach)
192 * @endcode
193 *
194 * @param dev the device to probe
195 *
196 * @retval 0 success
197 * @retval non-zero if some kind of error was detected during
198 * the attach, a regular unix error code should
199 * be returned to indicate the type of error
200 * @see DEVICE_PROBE()
201 */
202 METHOD int attach {
203 device_t dev;
204 };
205
206 /**
207 * @brief Detach a driver from a device.
208 *
209 * This can be called if the user is replacing the
210 * driver software or if a device is about to be physically removed
211 * from the system (e.g. for removable hardware such as USB or PCCARD).
212 *
213 * To include this method in a device driver, use a line like this
214 * in the driver's method list:
215 *
216 * @code
217 * KOBJMETHOD(device_detach, foo_detach)
218 * @endcode
219 *
220 * @param dev the device to detach
221 *
222 * @retval 0 success
223 * @retval non-zero the detach could not be performed, e.g. if the
224 * driver does not support detaching.
225 *
226 * @see DEVICE_ATTACH()
227 */
228 METHOD int detach {
229 device_t dev;
230 };
231
232 /**
233 * @brief Called during system shutdown.
234 *
235 * This method allows drivers to detect when the system is being shut down.
236 * Some drivers need to use this to place their hardware in a consistent
237 * state before rebooting the computer.
238 *
239 * To include this method in a device driver, use a line like this
240 * in the driver's method list:
241 *
242 * @code
243 * KOBJMETHOD(device_shutdown, foo_shutdown)
244 * @endcode
245 */
246 METHOD int shutdown {
247 device_t dev;
248 } DEFAULT null_shutdown;
249
250 /**
251 * @brief This is called by the power-management subsystem when a
252 * suspend has been requested by the user or by some automatic
253 * mechanism.
254 *
255 * This gives drivers a chance to veto the suspend or save their
256 * configuration before power is removed.
257 *
258 * To include this method in a device driver, use a line like this in
259 * the driver's method list:
260 *
261 * @code
262 * KOBJMETHOD(device_suspend, foo_suspend)
263 * @endcode
264 *
265 * @param dev the device being suspended
266 *
267 * @retval 0 success
268 * @retval non-zero an error occurred while attempting to prepare the
269 * device for suspension
270 *
271 * @see DEVICE_RESUME()
272 */
273 METHOD int suspend {
274 device_t dev;
275 } DEFAULT null_suspend;
276
277 /**
278 * @brief This is called when the system resumes after a suspend.
279 *
280 * To include this method in a device driver, use a line like this
281 * in the driver's method list:
282 *
283 * @code
284 * KOBJMETHOD(device_resume, foo_resume)
285 * @endcode
286 *
287 * @param dev the device being resumed
288 *
289 * @retval 0 success
290 * @retval non-zero an error occurred while attempting to restore the
291 * device from suspension
292 *
293 * @see DEVICE_SUSPEND()
294 */
295 METHOD int resume {
296 device_t dev;
297 } DEFAULT null_resume;
298
299 /**
300 * @brief This is called when the driver is asked to quiesce itself.
301 *
302 * The driver should arrange for the orderly shutdown of this device.
303 * All further access to the device should be curtailed. Soon there
304 * will be a request to detach, but there won't necessarily be one.
305 *
306 * To include this method in a device driver, use a line like this
307 * in the driver's method list:
308 *
309 * @code
310 * KOBJMETHOD(device_quiesce, foo_quiesce)
311 * @endcode
312 *
313 * @param dev the device being quiesced
314 *
315 * @retval 0 success
316 * @retval non-zero an error occurred while attempting to quiesce the
317 * device
318 *
319 * @see DEVICE_DETACH()
320 */
321 METHOD int quiesce {
322 device_t dev;
323 } DEFAULT null_quiesce;
324
325 /**
326 * @brief This is called when the driver is asked to register handlers.
327 *
328 *
329 * To include this method in a device driver, use a line like this
330 * in the driver's method list:
331 *
332 * @code
333 * KOBJMETHOD(device_register, foo_register)
334 * @endcode
335 *
336 * @param dev the device for which handlers are being registered
337 *
338 * @retval NULL method not implemented
339 * @retval non-NULL a pointer to implementation specific static driver state
340 *
341 */
342 METHOD void * register {
343 device_t dev;
344 } DEFAULT null_register;
Cache object: 0fb67d3169a41a0d5fc2efc3801dc206
|