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