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$
   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. Common non-error values are described in the
   93  * DEVICE_PROBE(9) manual page.
   94  *
   95  * If a driver matches the hardware, it should set the device
   96  * description string using device_set_desc() or
   97  * device_set_desc_copy(). This string is used to generate an
   98  * informative message when DEVICE_ATTACH() 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. This should rarely be used.
  103  *
  104  * For example, a probe method for a PCI device driver might look
  105  * like this:
  106  *
  107  * @code
  108  * int
  109  * foo_probe(device_t dev)
  110  * {
  111  *         if (pci_get_vendor(dev) == FOOVENDOR &&
  112  *             pci_get_device(dev) == FOODEVICE) {
  113  *                 device_set_desc(dev, "Foo device");
  114  *                 return (BUS_PROBE_DEFAULT);
  115  *         }
  116  *         return (ENXIO);
  117  * }
  118  * @endcode
  119  *
  120  * To include this method in a device driver, use a line like this
  121  * in the driver's method list:
  122  *
  123  * @code
  124  *      KOBJMETHOD(device_probe, foo_probe)
  125  * @endcode
  126  *
  127  * @param dev           the device to probe
  128  *
  129  * @retval 0            if this is the only possible driver for this
  130  *                      device
  131  * @retval negative     if the driver can match this device - the
  132  *                      least negative value is used to select the
  133  *                      driver
  134  * @retval ENXIO        if the driver does not match the device
  135  * @retval positive     if some kind of error was detected during
  136  *                      the probe, a regular unix error code should
  137  *                      be returned to indicate the type of error
  138  * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
  139  */
  140 METHOD int probe {
  141         device_t dev;
  142 };
  143 
  144 /**
  145  * @brief Allow a device driver to detect devices not otherwise enumerated.
  146  *
  147  * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
  148  * bus driver) to help populate the bus device with a useful set of
  149  * child devices, normally by calling the BUS_ADD_CHILD() method of
  150  * the parent device. For instance, the ISA bus driver uses several
  151  * special drivers, including the isahint driver and the pnp driver to
  152  * create child devices based on configuration hints and PnP bus
  153  * probes respectively.
  154  *
  155  * Many bus drivers which support true plug-and-play do not need to
  156  * use this method at all since child devices can be discovered
  157  * automatically without help from child drivers.
  158  *
  159  * To include this method in a device driver, use a line like this
  160  * in the driver's method list:
  161  *
  162  * @code
  163  *      KOBJMETHOD(device_identify, foo_identify)
  164  * @endcode
  165  *
  166  * @param driver        the driver whose identify method is being called
  167  * @param parent        the parent device to use when adding new children
  168  */
  169 STATICMETHOD void identify {
  170         driver_t *driver;
  171         device_t parent;
  172 };
  173 
  174 /**
  175  * @brief Attach a device to a device driver
  176  *
  177  * Normally only called via device_probe_and_attach(), this is called
  178  * when a driver has succeeded in probing against a device.
  179  * This method should initialise the hardware and allocate other
  180  * system resources (e.g. devfs entries) as required.
  181  *
  182  * To include this method in a device driver, use a line like this
  183  * in the driver's method list:
  184  *
  185  * @code
  186  *      KOBJMETHOD(device_attach, foo_attach)
  187  * @endcode
  188  *
  189  * @param dev           the device to probe
  190  *
  191  * @retval 0            success
  192  * @retval non-zero     if some kind of error was detected during
  193  *                      the attach, a regular unix error code should
  194  *                      be returned to indicate the type of error
  195  * @see DEVICE_PROBE()
  196  */
  197 METHOD int attach {
  198         device_t dev;
  199 };
  200 
  201 /**
  202  * @brief Detach a driver from a device.
  203  *
  204  * This can be called if the user is replacing the
  205  * driver software or if a device is about to be physically removed
  206  * from the system (e.g. for removable hardware such as USB or PCCARD).
  207  *
  208  * To include this method in a device driver, use a line like this
  209  * in the driver's method list:
  210  *
  211  * @code
  212  *      KOBJMETHOD(device_detach, foo_detach)
  213  * @endcode
  214  *
  215  * @param dev           the device to detach
  216  *
  217  * @retval 0            success
  218  * @retval non-zero     the detach could not be performed, e.g. if the
  219  *                      driver does not support detaching.
  220  *
  221  * @see DEVICE_ATTACH()
  222  */
  223 METHOD int detach {
  224         device_t dev;
  225 };
  226 
  227 /**
  228  * @brief Called during system shutdown.
  229  *
  230  * This method allows drivers to detect when the system is being shut down.
  231  * Some drivers need to use this to place their hardware in a consistent
  232  * state before rebooting the computer.
  233  *
  234  * To include this method in a device driver, use a line like this
  235  * in the driver's method list:
  236  *
  237  * @code
  238  *      KOBJMETHOD(device_shutdown, foo_shutdown)
  239  * @endcode
  240  */
  241 METHOD int shutdown {
  242         device_t dev;
  243 } DEFAULT null_shutdown;
  244 
  245 /**
  246  * @brief This is called by the power-management subsystem when a
  247  * suspend has been requested by the user or by some automatic
  248  * mechanism.
  249  *
  250  * This gives drivers a chance to veto the suspend or save their
  251  * configuration before power is removed.
  252  *
  253  * To include this method in a device driver, use a line like this in
  254  * the driver's method list:
  255  *
  256  * @code
  257  *      KOBJMETHOD(device_suspend, foo_suspend)
  258  * @endcode
  259  *
  260  * @param dev           the device being suspended
  261  *
  262  * @retval 0            success
  263  * @retval non-zero     an error occurred while attempting to prepare the
  264  *                      device for suspension
  265  *
  266  * @see DEVICE_RESUME()
  267  */
  268 METHOD int suspend {
  269         device_t dev;
  270 } DEFAULT null_suspend;
  271 
  272 /**
  273  * @brief This is called when the system resumes after a suspend.
  274  *
  275  * To include this method in a device driver, use a line like this
  276  * in the driver's method list:
  277  *
  278  * @code
  279  *      KOBJMETHOD(device_resume, foo_resume)
  280  * @endcode
  281  *
  282  * @param dev           the device being resumed
  283  *
  284  * @retval 0            success
  285  * @retval non-zero     an error occurred while attempting to restore the
  286  *                      device from suspension
  287  *
  288  * @see DEVICE_SUSPEND()
  289  */
  290 METHOD int resume {
  291         device_t dev;
  292 } DEFAULT null_resume;
  293 
  294 /**
  295  * @brief This is called when the driver is asked to quiesce itself.
  296  *
  297  * The driver should arrange for the orderly shutdown of this device.
  298  * All further access to the device should be curtailed.  Soon there
  299  * will be a request to detach, but there won't necessarily be one.
  300  *
  301  * To include this method in a device driver, use a line like this
  302  * in the driver's method list:
  303  *
  304  * @code
  305  *      KOBJMETHOD(device_quiesce, foo_quiesce)
  306  * @endcode
  307  *
  308  * @param dev           the device being quiesced
  309  *
  310  * @retval 0            success
  311  * @retval non-zero     an error occurred while attempting to quiesce the
  312  *                      device
  313  *
  314  * @see DEVICE_DETACH()
  315  */
  316 METHOD int quiesce {
  317         device_t dev;
  318 } DEFAULT null_quiesce;

Cache object: 4c6b95ffe3468c55a968523da834469b


[ 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.