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 # 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;

Cache object: 60169c37de8623a25ebf5f94abd85b0f


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