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# Needed for timestamping device probe/attach calls 43HEADER { 44 #include <sys/tslog.h> 45} 46 47# 48# Default implementations of some methods. 49# 50CODE { 51 static int null_shutdown(device_t dev) 52 { 53 return 0; 54 } 55 56 static int null_suspend(device_t dev) 57 { 58 return 0; 59 } 60 61 static int null_resume(device_t dev) 62 { 63 return 0; 64 } 65 66 static int null_quiesce(device_t dev) 67 { 68 return 0; 69 } 70 71 static void * null_register(device_t dev) 72 { 73 return NULL; 74 } 75}; 76 77/** 78 * @brief Probe to see if a device matches a driver. 79 * 80 * Users should not call this method directly. Normally, this 81 * is called via device_probe_and_attach() to select a driver 82 * calling the DEVICE_PROBE() of all candidate drivers and attach 83 * the winning driver (if any) to the device. 84 * 85 * This function is used to match devices to device drivers. 86 * Typically, the driver will examine the device to see if 87 * it is suitable for this driver. This might include checking 88 * the values of various device instance variables or reading 89 * hardware registers. 90 * 91 * In some cases, there may be more than one driver available 92 * which can be used for a device (for instance there might 93 * be a generic driver which works for a set of many types of 94 * device and a more specific driver which works for a subset 95 * of devices). Because of this, a driver should not assume 96 * that it will be the driver that attaches to the device even 97 * if it returns a success status from DEVICE_PROBE(). In particular, 98 * a driver must free any resources which it allocated during 99 * the probe before returning. The return value of DEVICE_PROBE() 100 * is used to elect which driver is used - the driver which returns 101 * the largest non-error value wins the election and attaches to 102 * the device. Common non-error values are described in the 103 * DEVICE_PROBE(9) manual page. 104 * 105 * If a driver matches the hardware, it should set the device 106 * description string using device_set_desc() or 107 * device_set_desc_copy(). This string is used to generate an 108 * informative message when DEVICE_ATTACH() is called. 109 * 110 * As a special case, if a driver returns zero, the driver election 111 * is cut short and that driver will attach to the device 112 * immediately. This should rarely be used. 113 * 114 * For example, a probe method for a PCI device driver might look 115 * like this: 116 * 117 * @code 118 * int 119 * foo_probe(device_t dev) 120 * { 121 * if (pci_get_vendor(dev) == FOOVENDOR && 122 * pci_get_device(dev) == FOODEVICE) { 123 * device_set_desc(dev, "Foo device"); 124 * return (BUS_PROBE_DEFAULT); 125 * } 126 * return (ENXIO); 127 * } 128 * @endcode 129 * 130 * To include this method in a device driver, use a line like this 131 * in the driver's method list: 132 * 133 * @code 134 * KOBJMETHOD(device_probe, foo_probe) 135 * @endcode 136 * 137 * @param dev the device to probe 138 * 139 * @retval 0 if this is the only possible driver for this 140 * device 141 * @retval negative if the driver can match this device - the 142 * least negative value is used to select the 143 * driver 144 * @retval ENXIO if the driver does not match the device 145 * @retval positive if some kind of error was detected during 146 * the probe, a regular unix error code should 147 * be returned to indicate the type of error 148 * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device() 149 */ 150PROLOG { 151 TSENTER2(device_get_name(dev)); 152} 153EPILOG { 154 TSEXIT2(device_get_name(dev)); 155} 156METHOD int probe { 157 device_t dev; 158}; 159 160/** 161 * @brief Allow a device driver to detect devices not otherwise enumerated. 162 * 163 * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA 164 * bus driver) to help populate the bus device with a useful set of 165 * child devices, normally by calling the BUS_ADD_CHILD() method of 166 * the parent device. For instance, the ISA bus driver uses several 167 * special drivers, including the isahint driver and the pnp driver to 168 * create child devices based on configuration hints and PnP bus 169 * probes respectively. 170 * 171 * Many bus drivers which support true plug-and-play do not need to 172 * use this method at all since child devices can be discovered 173 * automatically without help from child drivers. 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_identify, foo_identify) 180 * @endcode 181 * 182 * @param driver the driver whose identify method is being called 183 * @param parent the parent device to use when adding new children 184 */ 185STATICMETHOD void identify { 186 driver_t *driver; 187 device_t parent; 188}; 189 190/** 191 * @brief Attach a device to a device driver 192 * 193 * Normally only called via device_probe_and_attach(), this is called 194 * when a driver has succeeded in probing against a device. 195 * This method should initialise the hardware and allocate other 196 * system resources (e.g. devfs entries) as required. 197 * 198 * To include this method in a device driver, use a line like this 199 * in the driver's method list: 200 * 201 * @code 202 * KOBJMETHOD(device_attach, foo_attach) 203 * @endcode 204 * 205 * @param dev the device to probe 206 * 207 * @retval 0 success 208 * @retval non-zero if some kind of error was detected during 209 * the attach, a regular unix error code should 210 * be returned to indicate the type of error 211 * @see DEVICE_PROBE() 212 */ 213PROLOG { 214 TSENTER2(device_get_name(dev)); 215} 216EPILOG { 217 TSEXIT2(device_get_name(dev)); 218} 219METHOD int attach { 220 device_t dev; 221}; 222 223/** 224 * @brief Detach a driver from a device. 225 * 226 * This can be called if the user is replacing the 227 * driver software or if a device is about to be physically removed 228 * from the system (e.g. for removable hardware such as USB or PCCARD). 229 * 230 * To include this method in a device driver, use a line like this 231 * in the driver's method list: 232 * 233 * @code 234 * KOBJMETHOD(device_detach, foo_detach) 235 * @endcode 236 * 237 * @param dev the device to detach 238 * 239 * @retval 0 success 240 * @retval non-zero the detach could not be performed, e.g. if the 241 * driver does not support detaching. 242 * 243 * @see DEVICE_ATTACH() 244 */ 245METHOD int detach { 246 device_t dev; 247}; 248 249/** 250 * @brief Called during system shutdown. 251 * 252 * This method allows drivers to detect when the system is being shut down. 253 * Some drivers need to use this to place their hardware in a consistent 254 * state before rebooting the computer. 255 * 256 * To include this method in a device driver, use a line like this 257 * in the driver's method list: 258 * 259 * @code 260 * KOBJMETHOD(device_shutdown, foo_shutdown) 261 * @endcode 262 */ 263METHOD int shutdown { 264 device_t dev; 265} DEFAULT null_shutdown; 266 267/** 268 * @brief This is called by the power-management subsystem when a 269 * suspend has been requested by the user or by some automatic 270 * mechanism. 271 * 272 * This gives drivers a chance to veto the suspend or save their 273 * configuration before power is removed. 274 * 275 * To include this method in a device driver, use a line like this in 276 * the driver's method list: 277 * 278 * @code 279 * KOBJMETHOD(device_suspend, foo_suspend) 280 * @endcode 281 * 282 * @param dev the device being suspended 283 * 284 * @retval 0 success 285 * @retval non-zero an error occurred while attempting to prepare the 286 * device for suspension 287 * 288 * @see DEVICE_RESUME() 289 */ 290METHOD int suspend { 291 device_t dev; 292} DEFAULT null_suspend; 293 294/** 295 * @brief This is called when the system resumes after a suspend. 296 * 297 * To include this method in a device driver, use a line like this 298 * in the driver's method list: 299 * 300 * @code 301 * KOBJMETHOD(device_resume, foo_resume) 302 * @endcode 303 * 304 * @param dev the device being resumed 305 * 306 * @retval 0 success 307 * @retval non-zero an error occurred while attempting to restore the 308 * device from suspension 309 * 310 * @see DEVICE_SUSPEND() 311 */ 312METHOD int resume { 313 device_t dev; 314} DEFAULT null_resume; 315 316/** 317 * @brief This is called when the driver is asked to quiesce itself. 318 * 319 * The driver should arrange for the orderly shutdown of this device. 320 * All further access to the device should be curtailed. Soon there 321 * will be a request to detach, but there won't necessarily be one. 322 * 323 * To include this method in a device driver, use a line like this 324 * in the driver's method list: 325 * 326 * @code 327 * KOBJMETHOD(device_quiesce, foo_quiesce) 328 * @endcode 329 * 330 * @param dev the device being quiesced 331 * 332 * @retval 0 success 333 * @retval non-zero an error occurred while attempting to quiesce the 334 * device 335 * 336 * @see DEVICE_DETACH() 337 */ 338METHOD int quiesce { 339 device_t dev; 340} DEFAULT null_quiesce; 341 342/** 343 * @brief This is called when the driver is asked to register handlers. 344 * 345 * 346 * To include this method in a device driver, use a line like this 347 * in the driver's method list: 348 * 349 * @code 350 * KOBJMETHOD(device_register, foo_register) 351 * @endcode 352 * 353 * @param dev the device for which handlers are being registered 354 * 355 * @retval NULL method not implemented 356 * @retval non-NULL a pointer to implementation specific static driver state 357 * 358 */ 359METHOD void * register { 360 device_t dev; 361} DEFAULT null_register; 362