device_if.m revision 133588
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: head/sys/kern/device_if.m 133588 2004-08-12 17:26:22Z imp $ 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 */ 40INTERFACE device; 41 42# 43# Default implementations of some methods. 44# 45CODE { 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 */ 133METHOD 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 */ 162STATICMETHOD 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 */ 190METHOD 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 */ 216METHOD 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 */ 234METHOD 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 */ 261METHOD 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 */ 283METHOD int resume { 284 device_t dev; 285} DEFAULT null_resume; 286