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