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