The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/kern/device_if.m

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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/6.3/sys/kern/device_if.m 173886 2007-11-24 19:45:58Z cvs2svn $
   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;

Cache object: 7d1a442f1196fa9da8c523416d23d462


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.