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 #
  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  */
  39 INTERFACE device;
  40
  41 # Needed for timestamping device probe/attach calls
  42 HEADER {
  43         #include <sys/tslog.h>
  44 }
  45
  46 #
  47 # Default implementations of some methods.
  48 #
  49 CODE {
  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  */
 149 PROLOG {
 150         TSENTER2(device_get_name(dev));
 151 }
 152 EPILOG {
 153         TSEXIT2(device_get_name(dev));
 154 }
 155 METHOD 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  */
 184 STATICMETHOD 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  */
 212 PROLOG {
 213         TSENTER2(device_get_name(dev));
 214 }
 215 EPILOG {
 216         TSEXIT2(device_get_name(dev));
 217 }
 218 METHOD 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  */
 244 METHOD 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  */
 262 METHOD 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  */
 289 METHOD 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  */
 311 METHOD 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  */
 337 METHOD 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  */
 358 METHOD void * register {
 359         device_t dev;
 360 } DEFAULT null_register;