2 # Copyright (c) 1998-2004 Doug Rabson
5 # Redistribution and use in source and binary forms, with or without
6 # modification, are permitted provided that the following conditions
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.
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
31 * @defgroup DEVICE device - KObj methods for all device drivers
32 * @brief A basic set of methods required for all device drivers.
34 * The device interface is used to match devices to drivers during
35 * autoconfiguration and provides methods to allow drivers to handle
36 * system-wide events such as suspend, resume or shutdown.
41 # Needed for timestamping device probe/attach calls
43 #include <sys/tslog.h>
47 # Default implementations of some methods.
50 static int null_shutdown(device_t dev)
55 static int null_suspend(device_t dev)
60 static int null_resume(device_t dev)
65 static int null_quiesce(device_t dev)
70 static void * null_register(device_t dev)
77 * @brief Probe to see if a device matches a driver.
79 * Users should not call this method directly. Normally, this
80 * is called via device_probe_and_attach() to select a driver
81 * calling the DEVICE_PROBE() of all candidate drivers and attach
82 * the winning driver (if any) to the device.
84 * This function is used to match devices to device drivers.
85 * Typically, the driver will examine the device to see if
86 * it is suitable for this driver. This might include checking
87 * the values of various device instance variables or reading
90 * In some cases, there may be more than one driver available
91 * which can be used for a device (for instance there might
92 * be a generic driver which works for a set of many types of
93 * device and a more specific driver which works for a subset
94 * of devices). Because of this, a driver should not assume
95 * that it will be the driver that attaches to the device even
96 * if it returns a success status from DEVICE_PROBE(). In particular,
97 * a driver must free any resources which it allocated during
98 * the probe before returning. The return value of DEVICE_PROBE()
99 * is used to elect which driver is used - the driver which returns
100 * the largest non-error value wins the election and attaches to
101 * the device. Common non-error values are described in the
102 * DEVICE_PROBE(9) manual page.
104 * If a driver matches the hardware, it should set the device
105 * description string using device_set_desc() or
106 * device_set_desc_copy(). This string is used to generate an
107 * informative message when DEVICE_ATTACH() is called.
109 * As a special case, if a driver returns zero, the driver election
110 * is cut short and that driver will attach to the device
111 * immediately. This should rarely be used.
113 * For example, a probe method for a PCI device driver might look
118 * foo_probe(device_t dev)
120 * if (pci_get_vendor(dev) == FOOVENDOR &&
121 * pci_get_device(dev) == FOODEVICE) {
122 * device_set_desc(dev, "Foo device");
123 * return (BUS_PROBE_DEFAULT);
129 * To include this method in a device driver, use a line like this
130 * in the driver's method list:
133 * KOBJMETHOD(device_probe, foo_probe)
136 * @param dev the device to probe
138 * @retval 0 if this is the only possible driver for this
140 * @retval negative if the driver can match this device - the
141 * least negative value is used to select the
143 * @retval ENXIO if the driver does not match the device
144 * @retval positive if some kind of error was detected during
145 * the probe, a regular unix error code should
146 * be returned to indicate the type of error
147 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
150 TSENTER2(device_get_name(dev));
153 TSEXIT2(device_get_name(dev));
160 * @brief Allow a device driver to detect devices not otherwise enumerated.
162 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
163 * bus driver) to help populate the bus device with a useful set of
164 * child devices, normally by calling the BUS_ADD_CHILD() method of
165 * the parent device. For instance, the ISA bus driver uses several
166 * special drivers, including the isahint driver and the pnp driver to
167 * create child devices based on configuration hints and PnP bus
168 * probes respectively.
170 * Many bus drivers which support true plug-and-play do not need to
171 * use this method at all since child devices can be discovered
172 * automatically without help from child drivers.
174 * To include this method in a device driver, use a line like this
175 * in the driver's method list:
178 * KOBJMETHOD(device_identify, foo_identify)
181 * @param driver the driver whose identify method is being called
182 * @param parent the parent device to use when adding new children
184 STATICMETHOD void identify {
190 * @brief Attach a device to a device driver
192 * Normally only called via device_probe_and_attach(), this is called
193 * when a driver has succeeded in probing against a device.
194 * This method should initialise the hardware and allocate other
195 * system resources (e.g. devfs entries) as required.
197 * To include this method in a device driver, use a line like this
198 * in the driver's method list:
201 * KOBJMETHOD(device_attach, foo_attach)
204 * @param dev the device to probe
207 * @retval non-zero if some kind of error was detected during
208 * the attach, a regular unix error code should
209 * be returned to indicate the type of error
210 * @see DEVICE_PROBE()
213 TSENTER2(device_get_name(dev));
216 TSEXIT2(device_get_name(dev));
223 * @brief Detach a driver from a device.
225 * This can be called if the user is replacing the
226 * driver software or if a device is about to be physically removed
227 * from the system (e.g. for removable hardware such as USB or PCCARD).
229 * To include this method in a device driver, use a line like this
230 * in the driver's method list:
233 * KOBJMETHOD(device_detach, foo_detach)
236 * @param dev the device to detach
239 * @retval non-zero the detach could not be performed, e.g. if the
240 * driver does not support detaching.
242 * @see DEVICE_ATTACH()
249 * @brief Called during system shutdown.
251 * This method allows drivers to detect when the system is being shut down.
252 * Some drivers need to use this to place their hardware in a consistent
253 * state before rebooting the computer.
255 * To include this method in a device driver, use a line like this
256 * in the driver's method list:
259 * KOBJMETHOD(device_shutdown, foo_shutdown)
262 METHOD int shutdown {
264 } DEFAULT null_shutdown;
267 * @brief This is called by the power-management subsystem when a
268 * suspend has been requested by the user or by some automatic
271 * This gives drivers a chance to veto the suspend or save their
272 * configuration before power is removed.
274 * To include this method in a device driver, use a line like this in
275 * the driver's method list:
278 * KOBJMETHOD(device_suspend, foo_suspend)
281 * @param dev the device being suspended
284 * @retval non-zero an error occurred while attempting to prepare the
285 * device for suspension
287 * @see DEVICE_RESUME()
291 } DEFAULT null_suspend;
294 * @brief This is called when the system resumes after a suspend.
296 * To include this method in a device driver, use a line like this
297 * in the driver's method list:
300 * KOBJMETHOD(device_resume, foo_resume)
303 * @param dev the device being resumed
306 * @retval non-zero an error occurred while attempting to restore the
307 * device from suspension
309 * @see DEVICE_SUSPEND()
313 } DEFAULT null_resume;
316 * @brief This is called when the driver is asked to quiesce itself.
318 * The driver should arrange for the orderly shutdown of this device.
319 * All further access to the device should be curtailed. Soon there
320 * will be a request to detach, but there won't necessarily be one.
322 * To include this method in a device driver, use a line like this
323 * in the driver's method list:
326 * KOBJMETHOD(device_quiesce, foo_quiesce)
329 * @param dev the device being quiesced
332 * @retval non-zero an error occurred while attempting to quiesce the
335 * @see DEVICE_DETACH()
339 } DEFAULT null_quiesce;
342 * @brief This is called when the driver is asked to register handlers.
345 * To include this method in a device driver, use a line like this
346 * in the driver's method list:
349 * KOBJMETHOD(device_register, foo_register)
352 * @param dev the device for which handlers are being registered
354 * @retval NULL method not implemented
355 * @retval non-NULL a pointer to implementation specific static driver state
358 METHOD void * register {
360 } DEFAULT null_register;