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 #
  43 # Default implementations of some methods.
  44 #
  45 CODE {
  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  */
 138 METHOD 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  */
 167 STATICMETHOD 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  */
 195 METHOD 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  */
 221 METHOD 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  */
 239 METHOD 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  */
 266 METHOD 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  */
 288 METHOD 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  */
 314 METHOD int quiesce {
 315         device_t dev;
 316 } DEFAULT null_quiesce;