sys/kern/device_if.m

   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  */
  40 INTERFACE device;
  41
  42 # Needed for timestamping device probe/attach calls
  43 HEADER {
  44         #include <sys/tslog.h>
  45 }
  46
  47 #
  48 # Default implementations of some methods.
  49 #
  50 CODE {
  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  */
 150 PROLOG {
 151         TSENTER2(device_get_name(dev));
 152 }
 153 EPILOG {
 154         TSEXIT2(device_get_name(dev));
 155 }
 156 METHOD 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  */
 185 STATICMETHOD 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  */
 213 PROLOG {
 214         TSENTER2(device_get_name(dev));
 215 }
 216 EPILOG {
 217         TSEXIT2(device_get_name(dev));
 218 }
 219 METHOD 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  */
 245 METHOD 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  */
 263 METHOD 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  */
 290 METHOD 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  */
 312 METHOD 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  */
 338 METHOD 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  */
 359 METHOD void * register {
 360         device_t dev;
 361 } DEFAULT null_register;