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