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$
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 # Needed for timestamping device probe/attach calls
43 HEADER {
44 #include <sys/tslog.h>
45 }
46
47 #
48 # Default implementations of some methods.
49 #
50 CODE {
51 static int null_shutdown(device_t dev)
52 {
53 return 0;
54 }
55
56 static int null_suspend(device_t dev)
57 {
58 return 0;
59 }
60
61 static int null_resume(device_t dev)
62 {
63 return 0;
64 }
65
66 static int null_quiesce(device_t dev)
67 {
68 return 0;
69 }
70
71 static void * null_register(device_t dev)
72 {
73 return NULL;
74 }
75 };
76
77 /**
78 * @brief Probe to see if a device matches a driver.
79 *
80 * Users should not call this method directly. Normally, this
81 * is called via device_probe_and_attach() to select a driver
82 * calling the DEVICE_PROBE() of all candidate drivers and attach
83 * the winning driver (if any) to the device.
84 *
85 * This function is used to match devices to device drivers.
86 * Typically, the driver will examine the device to see if
87 * it is suitable for this driver. This might include checking
88 * the values of various device instance variables or reading
89 * hardware registers.
90 *
91 * In some cases, there may be more than one driver available
92 * which can be used for a device (for instance there might
93 * be a generic driver which works for a set of many types of
94 * device and a more specific driver which works for a subset
95 * of devices). Because of this, a driver should not assume
96 * that it will be the driver that attaches to the device even
97 * if it returns a success status from DEVICE_PROBE(). In particular,
98 * a driver must free any resources which it allocated during
99 * the probe before returning. The return value of DEVICE_PROBE()
100 * is used to elect which driver is used - the driver which returns
101 * the largest non-error value wins the election and attaches to
102 * the device. Common non-error values are described in the
103 * DEVICE_PROBE(9) manual page.
104 *
105 * If a driver matches the hardware, it should set the device
106 * description string using device_set_desc() or
107 * device_set_desc_copy(). This string is used to generate an
108 * informative message when DEVICE_ATTACH() is called.
109 *
110 * As a special case, if a driver returns zero, the driver election
111 * is cut short and that driver will attach to the device
112 * immediately. This should rarely be used.
113 *
114 * For example, a probe method for a PCI device driver might look
115 * like this:
116 *
117 * @code
118 * int
119 * foo_probe(device_t dev)
120 * {
121 * if (pci_get_vendor(dev) == FOOVENDOR &&
122 * pci_get_device(dev) == FOODEVICE) {
123 * device_set_desc(dev, "Foo device");
124 * return (BUS_PROBE_DEFAULT);
125 * }
126 * return (ENXIO);
127 * }
128 * @endcode
129 *
130 * To include this method in a device driver, use a line like this
131 * in the driver's method list:
132 *
133 * @code
134 * KOBJMETHOD(device_probe, foo_probe)
135 * @endcode
136 *
137 * @param dev the device to probe
138 *
139 * @retval 0 if this is the only possible driver for this
140 * device
141 * @retval negative if the driver can match this device - the
142 * least negative value is used to select the
143 * driver
144 * @retval ENXIO if the driver does not match the device
145 * @retval positive if some kind of error was detected during
146 * the probe, a regular unix error code should
147 * be returned to indicate the type of error
148 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
149 */
150 PROLOG {
151 TSENTER2(device_get_name(dev));
152 }
153 EPILOG {
154 TSEXIT2(device_get_name(dev));
155 }
156 METHOD int probe {
157 device_t dev;
158 };
159
160 /**
161 * @brief Allow a device driver to detect devices not otherwise enumerated.
162 *
163 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
164 * bus driver) to help populate the bus device with a useful set of
165 * child devices, normally by calling the BUS_ADD_CHILD() method of
166 * the parent device. For instance, the ISA bus driver uses several
167 * special drivers, including the isahint driver and the pnp driver to
168 * create child devices based on configuration hints and PnP bus
169 * probes respectively.
170 *
171 * Many bus drivers which support true plug-and-play do not need to
172 * use this method at all since child devices can be discovered
173 * automatically without help from child drivers.
174 *
175 * To include this method in a device driver, use a line like this
176 * in the driver's method list:
177 *
178 * @code
179 * KOBJMETHOD(device_identify, foo_identify)
180 * @endcode
181 *
182 * @param driver the driver whose identify method is being called
183 * @param parent the parent device to use when adding new children
184 */
185 STATICMETHOD void identify {
186 driver_t *driver;
187 device_t parent;
188 };
189
190 /**
191 * @brief Attach a device to a device driver
192 *
193 * Normally only called via device_probe_and_attach(), this is called
194 * when a driver has succeeded in probing against a device.
195 * This method should initialise the hardware and allocate other
196 * system resources (e.g. devfs entries) as required.
197 *
198 * To include this method in a device driver, use a line like this
199 * in the driver's method list:
200 *
201 * @code
202 * KOBJMETHOD(device_attach, foo_attach)
203 * @endcode
204 *
205 * @param dev the device to probe
206 *
207 * @retval 0 success
208 * @retval non-zero if some kind of error was detected during
209 * the attach, a regular unix error code should
210 * be returned to indicate the type of error
211 * @see DEVICE_PROBE()
212 */
213 PROLOG {
214 TSENTER2(device_get_name(dev));
215 }
216 EPILOG {
217 TSEXIT2(device_get_name(dev));
218 }
219 METHOD int attach {
220 device_t dev;
221 };
222
223 /**
224 * @brief Detach a driver from a device.
225 *
226 * This can be called if the user is replacing the
227 * driver software or if a device is about to be physically removed
228 * from the system (e.g. for removable hardware such as USB or PCCARD).
229 *
230 * To include this method in a device driver, use a line like this
231 * in the driver's method list:
232 *
233 * @code
234 * KOBJMETHOD(device_detach, foo_detach)
235 * @endcode
236 *
237 * @param dev the device to detach
238 *
239 * @retval 0 success
240 * @retval non-zero the detach could not be performed, e.g. if the
241 * driver does not support detaching.
242 *
243 * @see DEVICE_ATTACH()
244 */
245 METHOD int detach {
246 device_t dev;
247 };
248
249 /**
250 * @brief Called during system shutdown.
251 *
252 * This method allows drivers to detect when the system is being shut down.
253 * Some drivers need to use this to place their hardware in a consistent
254 * state before rebooting the computer.
255 *
256 * To include this method in a device driver, use a line like this
257 * in the driver's method list:
258 *
259 * @code
260 * KOBJMETHOD(device_shutdown, foo_shutdown)
261 * @endcode
262 */
263 METHOD int shutdown {
264 device_t dev;
265 } DEFAULT null_shutdown;
266
267 /**
268 * @brief This is called by the power-management subsystem when a
269 * suspend has been requested by the user or by some automatic
270 * mechanism.
271 *
272 * This gives drivers a chance to veto the suspend or save their
273 * configuration before power is removed.
274 *
275 * To include this method in a device driver, use a line like this in
276 * the driver's method list:
277 *
278 * @code
279 * KOBJMETHOD(device_suspend, foo_suspend)
280 * @endcode
281 *
282 * @param dev the device being suspended
283 *
284 * @retval 0 success
285 * @retval non-zero an error occurred while attempting to prepare the
286 * device for suspension
287 *
288 * @see DEVICE_RESUME()
289 */
290 METHOD int suspend {
291 device_t dev;
292 } DEFAULT null_suspend;
293
294 /**
295 * @brief This is called when the system resumes after a suspend.
296 *
297 * To include this method in a device driver, use a line like this
298 * in the driver's method list:
299 *
300 * @code
301 * KOBJMETHOD(device_resume, foo_resume)
302 * @endcode
303 *
304 * @param dev the device being resumed
305 *
306 * @retval 0 success
307 * @retval non-zero an error occurred while attempting to restore the
308 * device from suspension
309 *
310 * @see DEVICE_SUSPEND()
311 */
312 METHOD int resume {
313 device_t dev;
314 } DEFAULT null_resume;
315
316 /**
317 * @brief This is called when the driver is asked to quiesce itself.
318 *
319 * The driver should arrange for the orderly shutdown of this device.
320 * All further access to the device should be curtailed. Soon there
321 * will be a request to detach, but there won't necessarily be one.
322 *
323 * To include this method in a device driver, use a line like this
324 * in the driver's method list:
325 *
326 * @code
327 * KOBJMETHOD(device_quiesce, foo_quiesce)
328 * @endcode
329 *
330 * @param dev the device being quiesced
331 *
332 * @retval 0 success
333 * @retval non-zero an error occurred while attempting to quiesce the
334 * device
335 *
336 * @see DEVICE_DETACH()
337 */
338 METHOD int quiesce {
339 device_t dev;
340 } DEFAULT null_quiesce;
341
342 /**
343 * @brief This is called when the driver is asked to register handlers.
344 *
345 *
346 * To include this method in a device driver, use a line like this
347 * in the driver's method list:
348 *
349 * @code
350 * KOBJMETHOD(device_register, foo_register)
351 * @endcode
352 *
353 * @param dev the device for which handlers are being registered
354 *
355 * @retval NULL method not implemented
356 * @retval non-NULL a pointer to implementation specific static driver state
357 *
358 */
359 METHOD void * register {
360 device_t dev;
361 } DEFAULT null_register;
Cache object: c5bb0f56026207b51cf9322bdb28d581
|