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/11.1/sys/kern/device_if.m 300113 2016-05-18 04:35:58Z scottl $
   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 0;
   64         }
   65 
   66         static void * null_register(device_t dev)
   67         {
   68                 return NULL;
   69         }
   70 };
   71         
   72 /**
   73  * @brief Probe to see if a device matches a driver.
   74  *
   75  * Users should not call this method directly. Normally, this
   76  * is called via device_probe_and_attach() to select a driver
   77  * calling the DEVICE_PROBE() of all candidate drivers and attach
   78  * the winning driver (if any) to the device.
   79  *
   80  * This function is used to match devices to device drivers.
   81  * Typically, the driver will examine the device to see if
   82  * it is suitable for this driver. This might include checking
   83  * the values of various device instance variables or reading
   84  * hardware registers.
   85  *  
   86  * In some cases, there may be more than one driver available
   87  * which can be used for a device (for instance there might
   88  * be a generic driver which works for a set of many types of
   89  * device and a more specific driver which works for a subset
   90  * of devices). Because of this, a driver should not assume
   91  * that it will be the driver that attaches to the device even
   92  * if it returns a success status from DEVICE_PROBE(). In particular,
   93  * a driver must free any resources which it allocated during
   94  * the probe before returning. The return value of DEVICE_PROBE()
   95  * is used to elect which driver is used - the driver which returns
   96  * the largest non-error value wins the election and attaches to
   97  * the device. Common non-error values are described in the
   98  * DEVICE_PROBE(9) manual page.
   99  *
  100  * If a driver matches the hardware, it should set the device
  101  * description string using device_set_desc() or
  102  * device_set_desc_copy(). This string is used to generate an
  103  * informative message when DEVICE_ATTACH() is called.
  104  * 
  105  * As a special case, if a driver returns zero, the driver election
  106  * is cut short and that driver will attach to the device
  107  * immediately. This should rarely be used.
  108  *
  109  * For example, a probe method for a PCI device driver might look
  110  * like this:
  111  *
  112  * @code
  113  * int
  114  * foo_probe(device_t dev)
  115  * {
  116  *         if (pci_get_vendor(dev) == FOOVENDOR &&
  117  *             pci_get_device(dev) == FOODEVICE) {
  118  *                 device_set_desc(dev, "Foo device");
  119  *                 return (BUS_PROBE_DEFAULT);
  120  *         }
  121  *         return (ENXIO);
  122  * }
  123  * @endcode
  124  *
  125  * To include this method in a device driver, use a line like this
  126  * in the driver's method list:
  127  *
  128  * @code
  129  *      KOBJMETHOD(device_probe, foo_probe)
  130  * @endcode
  131  *
  132  * @param dev           the device to probe
  133  *
  134  * @retval 0            if this is the only possible driver for this
  135  *                      device
  136  * @retval negative     if the driver can match this device - the
  137  *                      least negative value is used to select the
  138  *                      driver
  139  * @retval ENXIO        if the driver does not match the device
  140  * @retval positive     if some kind of error was detected during
  141  *                      the probe, a regular unix error code should
  142  *                      be returned to indicate the type of error
  143  * @see DEVICE_ATTACH(), pci_get_vendor(), pci_get_device()
  144  */
  145 METHOD int probe {
  146         device_t dev;
  147 };
  148 
  149 /**
  150  * @brief Allow a device driver to detect devices not otherwise enumerated.
  151  *
  152  * The DEVICE_IDENTIFY() method is used by some drivers (e.g. the ISA
  153  * bus driver) to help populate the bus device with a useful set of
  154  * child devices, normally by calling the BUS_ADD_CHILD() method of
  155  * the parent device. For instance, the ISA bus driver uses several
  156  * special drivers, including the isahint driver and the pnp driver to
  157  * create child devices based on configuration hints and PnP bus
  158  * probes respectively.
  159  *
  160  * Many bus drivers which support true plug-and-play do not need to
  161  * use this method at all since child devices can be discovered
  162  * automatically without help from child drivers.
  163  *
  164  * To include this method in a device driver, use a line like this
  165  * in the driver's method list:
  166  *
  167  * @code
  168  *      KOBJMETHOD(device_identify, foo_identify)
  169  * @endcode
  170  *
  171  * @param driver        the driver whose identify method is being called
  172  * @param parent        the parent device to use when adding new children
  173  */
  174 STATICMETHOD void identify {
  175         driver_t *driver;
  176         device_t parent;
  177 };
  178 
  179 /**
  180  * @brief Attach a device to a device driver
  181  *
  182  * Normally only called via device_probe_and_attach(), this is called
  183  * when a driver has succeeded in probing against a device.
  184  * This method should initialise the hardware and allocate other
  185  * system resources (e.g. devfs entries) as required.
  186  *
  187  * To include this method in a device driver, use a line like this
  188  * in the driver's method list:
  189  *
  190  * @code
  191  *      KOBJMETHOD(device_attach, foo_attach)
  192  * @endcode
  193  *
  194  * @param dev           the device to probe
  195  *
  196  * @retval 0            success
  197  * @retval non-zero     if some kind of error was detected during
  198  *                      the attach, a regular unix error code should
  199  *                      be returned to indicate the type of error
  200  * @see DEVICE_PROBE()
  201  */
  202 METHOD int attach {
  203         device_t dev;
  204 };
  205 
  206 /**
  207  * @brief Detach a driver from a device.
  208  *
  209  * This can be called if the user is replacing the
  210  * driver software or if a device is about to be physically removed
  211  * from the system (e.g. for removable hardware such as USB or PCCARD).
  212  *
  213  * To include this method in a device driver, use a line like this
  214  * in the driver's method list:
  215  *
  216  * @code
  217  *      KOBJMETHOD(device_detach, foo_detach)
  218  * @endcode
  219  *
  220  * @param dev           the device to detach
  221  *
  222  * @retval 0            success
  223  * @retval non-zero     the detach could not be performed, e.g. if the
  224  *                      driver does not support detaching.
  225  *
  226  * @see DEVICE_ATTACH()
  227  */
  228 METHOD int detach {
  229         device_t dev;
  230 };
  231 
  232 /**
  233  * @brief Called during system shutdown.
  234  *
  235  * This method allows drivers to detect when the system is being shut down.
  236  * Some drivers need to use this to place their hardware in a consistent
  237  * state before rebooting the computer.
  238  *
  239  * To include this method in a device driver, use a line like this
  240  * in the driver's method list:
  241  *
  242  * @code
  243  *      KOBJMETHOD(device_shutdown, foo_shutdown)
  244  * @endcode
  245  */
  246 METHOD int shutdown {
  247         device_t dev;
  248 } DEFAULT null_shutdown;
  249 
  250 /**
  251  * @brief This is called by the power-management subsystem when a
  252  * suspend has been requested by the user or by some automatic
  253  * mechanism.
  254  *
  255  * This gives drivers a chance to veto the suspend or save their
  256  * configuration before power is removed.
  257  *
  258  * To include this method in a device driver, use a line like this in
  259  * the driver's method list:
  260  *
  261  * @code
  262  *      KOBJMETHOD(device_suspend, foo_suspend)
  263  * @endcode
  264  *
  265  * @param dev           the device being suspended
  266  *
  267  * @retval 0            success
  268  * @retval non-zero     an error occurred while attempting to prepare the
  269  *                      device for suspension
  270  *
  271  * @see DEVICE_RESUME()
  272  */
  273 METHOD int suspend {
  274         device_t dev;
  275 } DEFAULT null_suspend;
  276 
  277 /**
  278  * @brief This is called when the system resumes after a suspend.
  279  *
  280  * To include this method in a device driver, use a line like this
  281  * in the driver's method list:
  282  *
  283  * @code
  284  *      KOBJMETHOD(device_resume, foo_resume)
  285  * @endcode
  286  *
  287  * @param dev           the device being resumed
  288  *
  289  * @retval 0            success
  290  * @retval non-zero     an error occurred while attempting to restore the
  291  *                      device from suspension
  292  *
  293  * @see DEVICE_SUSPEND()
  294  */
  295 METHOD int resume {
  296         device_t dev;
  297 } DEFAULT null_resume;
  298 
  299 /**
  300  * @brief This is called when the driver is asked to quiesce itself.
  301  *
  302  * The driver should arrange for the orderly shutdown of this device.
  303  * All further access to the device should be curtailed.  Soon there
  304  * will be a request to detach, but there won't necessarily be one.
  305  *
  306  * To include this method in a device driver, use a line like this
  307  * in the driver's method list:
  308  *
  309  * @code
  310  *      KOBJMETHOD(device_quiesce, foo_quiesce)
  311  * @endcode
  312  *
  313  * @param dev           the device being quiesced
  314  *
  315  * @retval 0            success
  316  * @retval non-zero     an error occurred while attempting to quiesce the
  317  *                      device
  318  *
  319  * @see DEVICE_DETACH()
  320  */
  321 METHOD int quiesce {
  322         device_t dev;
  323 } DEFAULT null_quiesce;
  324 
  325 /**
  326  * @brief This is called when the driver is asked to register handlers.
  327  *
  328  *
  329  * To include this method in a device driver, use a line like this
  330  * in the driver's method list:
  331  *
  332  * @code
  333  *      KOBJMETHOD(device_register, foo_register)
  334  * @endcode
  335  *
  336  * @param dev           the device for which handlers are being registered
  337  *
  338  * @retval NULL     method not implemented
  339  * @retval non-NULL     a pointer to implementation specific static driver state
  340  *
  341  */
  342 METHOD void * register {
  343         device_t dev;
  344 } DEFAULT null_register;

Cache object: 0fb67d3169a41a0d5fc2efc3801dc206


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