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# 27 28#include <sys/bus.h> 29 30/** 31 * @defgroup DEVICE device - KObj methods for all device drivers 32 * @brief A basic set of methods required for all device drivers. 33 * 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. 37 * @{ 38 */ 39INTERFACE device; 40 41# Needed for timestamping device probe/attach calls 42HEADER { 43 #include <sys/tslog.h> 44} 45 46# 47# Default implementations of some methods. 48# 49CODE { 50 static int null_shutdown(device_t dev) 51 { 52 return 0; 53 } 54 55 static int null_suspend(device_t dev) 56 { 57 return 0; 58 } 59 60 static int null_resume(device_t dev) 61 { 62 return 0; 63 } 64 65 static int null_quiesce(device_t dev) 66 { 67 return 0; 68 } 69 70 static void * null_register(device_t dev) 71 { 72 return NULL; 73 } 74}; 75 76/** 77 * @brief Probe to see if a device matches a driver. 78 * 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. 83 * 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 88 * hardware registers. 89 * 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. 103 * 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. 108 * 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. 112 * 113 * For example, a probe method for a PCI device driver might look 114 * like this: 115 * 116 * @code 117 * int 118 * foo_probe(device_t dev) 119 * { 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); 124 * } 125 * return (ENXIO); 126 * } 127 * @endcode 128 * 129 * To include this method in a device driver, use a line like this 130 * in the driver's method list: 131 * 132 * @code 133 * KOBJMETHOD(device_probe, foo_probe) 134 * @endcode 135 * 136 * @param dev the device to probe 137 * 138 * @retval 0 if this is the only possible driver for this 139 * device 140 * @retval negative if the driver can match this device - the 141 * least negative value is used to select the 142 * driver 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() 148 */ 149PROLOG { 150 TSENTER2(device_get_name(dev)); 151} 152EPILOG { 153 TSEXIT2(device_get_name(dev)); 154} 155METHOD int probe { 156 device_t dev; 157}; 158 159/** 160 * @brief Allow a device driver to detect devices not otherwise enumerated. 161 * 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. 169 * 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. 173 * 174 * To include this method in a device driver, use a line like this 175 * in the driver's method list: 176 * 177 * @code 178 * KOBJMETHOD(device_identify, foo_identify) 179 * @endcode 180 * 181 * @param driver the driver whose identify method is being called 182 * @param parent the parent device to use when adding new children 183 */ 184STATICMETHOD void identify { 185 driver_t *driver; 186 device_t parent; 187}; 188 189/** 190 * @brief Attach a device to a device driver 191 * 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. 196 * 197 * To include this method in a device driver, use a line like this 198 * in the driver's method list: 199 * 200 * @code 201 * KOBJMETHOD(device_attach, foo_attach) 202 * @endcode 203 * 204 * @param dev the device to probe 205 * 206 * @retval 0 success 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() 211 */ 212PROLOG { 213 TSENTER2(device_get_name(dev)); 214} 215EPILOG { 216 TSEXIT2(device_get_name(dev)); 217} 218METHOD int attach { 219 device_t dev; 220}; 221 222/** 223 * @brief Detach a driver from a device. 224 * 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). 228 * 229 * To include this method in a device driver, use a line like this 230 * in the driver's method list: 231 * 232 * @code 233 * KOBJMETHOD(device_detach, foo_detach) 234 * @endcode 235 * 236 * @param dev the device to detach 237 * 238 * @retval 0 success 239 * @retval non-zero the detach could not be performed, e.g. if the 240 * driver does not support detaching. 241 * 242 * @see DEVICE_ATTACH() 243 */ 244METHOD int detach { 245 device_t dev; 246}; 247 248/** 249 * @brief Called during system shutdown. 250 * 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. 254 * 255 * To include this method in a device driver, use a line like this 256 * in the driver's method list: 257 * 258 * @code 259 * KOBJMETHOD(device_shutdown, foo_shutdown) 260 * @endcode 261 */ 262METHOD int shutdown { 263 device_t dev; 264} DEFAULT null_shutdown; 265 266/** 267 * @brief This is called by the power-management subsystem when a 268 * suspend has been requested by the user or by some automatic 269 * mechanism. 270 * 271 * This gives drivers a chance to veto the suspend or save their 272 * configuration before power is removed. 273 * 274 * To include this method in a device driver, use a line like this in 275 * the driver's method list: 276 * 277 * @code 278 * KOBJMETHOD(device_suspend, foo_suspend) 279 * @endcode 280 * 281 * @param dev the device being suspended 282 * 283 * @retval 0 success 284 * @retval non-zero an error occurred while attempting to prepare the 285 * device for suspension 286 * 287 * @see DEVICE_RESUME() 288 */ 289METHOD int suspend { 290 device_t dev; 291} DEFAULT null_suspend; 292 293/** 294 * @brief This is called when the system resumes after a suspend. 295 * 296 * To include this method in a device driver, use a line like this 297 * in the driver's method list: 298 * 299 * @code 300 * KOBJMETHOD(device_resume, foo_resume) 301 * @endcode 302 * 303 * @param dev the device being resumed 304 * 305 * @retval 0 success 306 * @retval non-zero an error occurred while attempting to restore the 307 * device from suspension 308 * 309 * @see DEVICE_SUSPEND() 310 */ 311METHOD int resume { 312 device_t dev; 313} DEFAULT null_resume; 314 315/** 316 * @brief This is called when the driver is asked to quiesce itself. 317 * 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. 321 * 322 * To include this method in a device driver, use a line like this 323 * in the driver's method list: 324 * 325 * @code 326 * KOBJMETHOD(device_quiesce, foo_quiesce) 327 * @endcode 328 * 329 * @param dev the device being quiesced 330 * 331 * @retval 0 success 332 * @retval non-zero an error occurred while attempting to quiesce the 333 * device 334 * 335 * @see DEVICE_DETACH() 336 */ 337METHOD int quiesce { 338 device_t dev; 339} DEFAULT null_quiesce; 340 341/** 342 * @brief This is called when the driver is asked to register handlers. 343 * 344 * 345 * To include this method in a device driver, use a line like this 346 * in the driver's method list: 347 * 348 * @code 349 * KOBJMETHOD(device_register, foo_register) 350 * @endcode 351 * 352 * @param dev the device for which handlers are being registered 353 * 354 * @retval NULL method not implemented 355 * @retval non-NULL a pointer to implementation specific static driver state 356 * 357 */ 358METHOD void * register { 359 device_t dev; 360} DEFAULT null_register; 361