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/bus_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/types.h>
   30 #include <sys/systm.h>
   31 #include <sys/bus.h>
   32 
   33 /**
   34  * @defgroup BUS bus - KObj methods for drivers of devices with children
   35  * @brief A set of methods required device drivers that support
   36  * child devices.
   37  * @{
   38  */
   39 INTERFACE bus;
   40 
   41 #
   42 # Default implementations of some methods.
   43 #
   44 CODE {
   45         static struct resource *
   46         null_alloc_resource(device_t dev, device_t child,
   47             int type, int *rid, u_long start, u_long end,
   48             u_long count, u_int flags)
   49         {
   50             return (0);
   51         }
   52 
   53         static device_t
   54         null_add_child(device_t bus, int order, const char *name,
   55             int unit)
   56         {
   57 
   58                 panic("bus_add_child is not implemented");
   59         }
   60 };
   61 
   62 /**
   63  * @brief Print a description of a child device
   64  *
   65  * This is called from system code which prints out a description of a
   66  * device. It should describe the attachment that the child has with
   67  * the parent. For instance the TurboLaser bus prints which node the
   68  * device is attached to. See bus_generic_print_child() for more 
   69  * information.
   70  *
   71  * @param _dev          the device whose child is being printed
   72  * @param _child        the child device to describe
   73  *
   74  * @returns             the number of characters output.
   75  */
   76 METHOD int print_child {
   77         device_t _dev;
   78         device_t _child;
   79 } DEFAULT bus_generic_print_child;
   80 
   81 /**
   82  * @brief Print a notification about an unprobed child device.
   83  *
   84  * Called for each child device that did not succeed in probing for a
   85  * driver.
   86  *
   87  * @param _dev          the device whose child was being probed
   88  * @param _child        the child device which failed to probe
   89  */   
   90 METHOD void probe_nomatch {
   91         device_t _dev;
   92         device_t _child;
   93 };
   94 
   95 /**
   96  * @brief Read the value of a bus-specific attribute of a device
   97  *
   98  * This method, along with BUS_WRITE_IVAR() manages a bus-specific set
   99  * of instance variables of a child device.  The intention is that
  100  * each different type of bus defines a set of appropriate instance
  101  * variables (such as ports and irqs for ISA bus etc.)
  102  *
  103  * This information could be given to the child device as a struct but
  104  * that makes it hard for a bus to add or remove variables without
  105  * forcing an edit and recompile for all drivers which may not be
  106  * possible for vendor supplied binary drivers.
  107  *
  108  * This method copies the value of an instance variable to the
  109  * location specified by @p *_result.
  110  * 
  111  * @param _dev          the device whose child was being examined
  112  * @param _child        the child device whose instance variable is
  113  *                      being read
  114  * @param _index        the instance variable to read
  115  * @param _result       a loction to recieve the instance variable
  116  *                      value
  117  * 
  118  * @retval 0            success
  119  * @retval ENOENT       no such instance variable is supported by @p
  120  *                      _dev 
  121  */
  122 METHOD int read_ivar {
  123         device_t _dev;
  124         device_t _child;
  125         int _index;
  126         uintptr_t *_result;
  127 };
  128 
  129 /**
  130  * @brief Write the value of a bus-specific attribute of a device
  131  * 
  132  * This method sets the value of an instance variable to @p _value.
  133  * 
  134  * @param _dev          the device whose child was being updated
  135  * @param _child        the child device whose instance variable is
  136  *                      being written
  137  * @param _index        the instance variable to write
  138  * @param _value        the value to write to that instance variable
  139  * 
  140  * @retval 0            success
  141  * @retval ENOENT       no such instance variable is supported by @p
  142  *                      _dev 
  143  * @retval EINVAL       the instance variable was recognised but
  144  *                      contains a read-only value
  145  */
  146 METHOD int write_ivar {
  147         device_t _dev;
  148         device_t _child;
  149         int _indx;
  150         uintptr_t _value;
  151 };
  152 
  153 /**
  154  * @brief Notify a bus that a child was detached
  155  *
  156  * Called after the child's DEVICE_DETACH() method to allow the parent
  157  * to reclaim any resources allocated on behalf of the child.
  158  * 
  159  * @param _dev          the device whose child changed state
  160  * @param _child        the child device which changed state
  161  */
  162 METHOD void child_detached {
  163         device_t _dev;
  164         device_t _child;
  165 };
  166 
  167 /**
  168  * @brief Notify a bus that a new driver was added
  169  * 
  170  * Called when a new driver is added to the devclass which owns this
  171  * bus. The generic implementation of this method attempts to probe and
  172  * attach any un-matched children of the bus.
  173  * 
  174  * @param _dev          the device whose devclass had a new driver
  175  *                      added to it
  176  * @param _driver       the new driver which was added
  177  */
  178 METHOD void driver_added {
  179         device_t _dev;
  180         driver_t *_driver;
  181 } DEFAULT bus_generic_driver_added;
  182 
  183 /**
  184  * @brief Create a new child device
  185  *
  186  * For busses which use use drivers supporting DEVICE_IDENTIFY() to
  187  * enumerate their devices, this method is used to create new
  188  * device instances. The new device will be added after the last
  189  * existing child with the same order.
  190  * 
  191  * @param _dev          the bus device which will be the parent of the
  192  *                      new child device
  193  * @param _order        a value which is used to partially sort the
  194  *                      children of @p _dev - devices created using
  195  *                      lower values of @p _order appear first in @p
  196  *                      _dev's list of children
  197  * @param _name         devclass name for new device or @c NULL if not
  198  *                      specified
  199  * @param _unit         unit number for new device or @c -1 if not
  200  *                      specified
  201  */
  202 METHOD device_t add_child {
  203         device_t _dev;
  204         u_int _order;
  205         const char *_name;
  206         int _unit;
  207 } DEFAULT null_add_child;
  208 
  209 /**
  210  * @brief Allocate a system resource
  211  *
  212  * This method is called by child devices of a bus to allocate resources.
  213  * The types are defined in <machine/resource.h>; the meaning of the
  214  * resource-ID field varies from bus to bus (but @p *rid == 0 is always
  215  * valid if the resource type is). If a resource was allocated and the
  216  * caller did not use the RF_ACTIVE to specify that it should be
  217  * activated immediately, the caller is responsible for calling
  218  * BUS_ACTIVATE_RESOURCE() when it actually uses the resource.
  219  *
  220  * @param _dev          the parent device of @p _child
  221  * @param _child        the device which is requesting an allocation
  222  * @param _type         the type of resource to allocate
  223  * @param _rid          a pointer to the resource identifier
  224  * @param _start        hint at the start of the resource range - pass
  225  *                      @c 0UL for any start address
  226  * @param _end          hint at the end of the resource range - pass
  227  *                      @c ~0UL for any end address
  228  * @param _count        hint at the size of range required - pass @c 1
  229  *                      for any size
  230  * @param _flags        any extra flags to control the resource
  231  *                      allocation - see @c RF_XXX flags in
  232  *                      <sys/rman.h> for details
  233  * 
  234  * @returns             the resource which was allocated or @c NULL if no
  235  *                      resource could be allocated
  236  */
  237 METHOD struct resource * alloc_resource {
  238         device_t        _dev;
  239         device_t        _child;
  240         int             _type;
  241         int            *_rid;
  242         u_long          _start;
  243         u_long          _end;
  244         u_long          _count;
  245         u_int           _flags;
  246 } DEFAULT null_alloc_resource;
  247 
  248 /**
  249  * @brief Activate a resource
  250  *
  251  * Activate a resource previously allocated with
  252  * BUS_ALLOC_RESOURCE(). This may for instance map a memory region
  253  * into the kernel's virtual address space.
  254  *
  255  * @param _dev          the parent device of @p _child
  256  * @param _child        the device which allocated the resource
  257  * @param _type         the type of resource
  258  * @param _rid          the resource identifier
  259  * @param _r            the resource to activate
  260  */
  261 METHOD int activate_resource {
  262         device_t        _dev;
  263         device_t        _child;
  264         int             _type;
  265         int             _rid;
  266         struct resource *_r;
  267 };
  268 
  269 /**
  270  * @brief Deactivate a resource
  271  *
  272  * Deactivate a resource previously allocated with
  273  * BUS_ALLOC_RESOURCE(). This may for instance unmap a memory region
  274  * from the kernel's virtual address space.
  275  *
  276  * @param _dev          the parent device of @p _child
  277  * @param _child        the device which allocated the resource
  278  * @param _type         the type of resource
  279  * @param _rid          the resource identifier
  280  * @param _r            the resource to deactivate
  281  */
  282 METHOD int deactivate_resource {
  283         device_t        _dev;
  284         device_t        _child;
  285         int             _type;
  286         int             _rid;
  287         struct resource *_r;
  288 };
  289 
  290 /**
  291  * @brief Release a resource
  292  *
  293  * Free a resource allocated by the BUS_ALLOC_RESOURCE.  The @p _rid
  294  * value must be the same as the one returned by BUS_ALLOC_RESOURCE()
  295  * (which is not necessarily the same as the one the client passed).
  296  *
  297  * @param _dev          the parent device of @p _child
  298  * @param _child        the device which allocated the resource
  299  * @param _type         the type of resource
  300  * @param _rid          the resource identifier
  301  * @param _r            the resource to release
  302  */
  303 METHOD int release_resource {
  304         device_t        _dev;
  305         device_t        _child;
  306         int             _type;
  307         int             _rid;
  308         struct resource *_res;
  309 };
  310 
  311 /**
  312  * @brief Install an interrupt handler
  313  *
  314  * This method is used to associate an interrupt handler function with
  315  * an irq resource. When the interrupt triggers, the function @p _intr
  316  * will be called with the value of @p _arg as its single
  317  * argument. The value returned in @p *_cookiep is used to cancel the
  318  * interrupt handler - the caller should save this value to use in a
  319  * future call to BUS_TEARDOWN_INTR().
  320  * 
  321  * @param _dev          the parent device of @p _child
  322  * @param _child        the device which allocated the resource
  323  * @param _irq          the resource representing the interrupt
  324  * @param _flags        a set of bits from enum intr_type specifying
  325  *                      the class of interrupt
  326  * @param _intr         the function to call when the interrupt
  327  *                      triggers
  328  * @param _arg          a value to use as the single argument in calls
  329  *                      to @p _intr
  330  * @param _cookiep      a pointer to a location to recieve a cookie
  331  *                      value that may be used to remove the interrupt
  332  *                      handler
  333  */
  334 METHOD int setup_intr {
  335         device_t        _dev;
  336         device_t        _child;
  337         struct resource *_irq;
  338         int             _flags;
  339         driver_filter_t *_filter;
  340         driver_intr_t   *_intr;
  341         void            *_arg;
  342         void            **_cookiep;
  343 };
  344 
  345 /**
  346  * @brief Uninstall an interrupt handler
  347  *
  348  * This method is used to disassociate an interrupt handler function
  349  * with an irq resource. The value of @p _cookie must be the value
  350  * returned from a previous call to BUS_SETUP_INTR().
  351  * 
  352  * @param _dev          the parent device of @p _child
  353  * @param _child        the device which allocated the resource
  354  * @param _irq          the resource representing the interrupt
  355  * @param _cookie       the cookie value returned when the interrupt
  356  *                      was originally registered
  357  */
  358 METHOD int teardown_intr {
  359         device_t        _dev;
  360         device_t        _child;
  361         struct resource *_irq;
  362         void            *_cookie;
  363 };
  364 
  365 /**
  366  * @brief Define a resource which can be allocated with
  367  * BUS_ALLOC_RESOURCE().
  368  *
  369  * This method is used by some busses (typically ISA) to allow a
  370  * driver to describe a resource range that it would like to
  371  * allocate. The resource defined by @p _type and @p _rid is defined
  372  * to start at @p _start and to include @p _count indices in its
  373  * range.
  374  * 
  375  * @param _dev          the parent device of @p _child
  376  * @param _child        the device which owns the resource
  377  * @param _type         the type of resource
  378  * @param _rid          the resource identifier
  379  * @param _start        the start of the resource range
  380  * @param _count        the size of the resource range
  381  */
  382 METHOD int set_resource {
  383         device_t        _dev;
  384         device_t        _child;
  385         int             _type;
  386         int             _rid;
  387         u_long          _start;
  388         u_long          _count;
  389 };
  390 
  391 /**
  392  * @brief Describe a resource
  393  *
  394  * This method allows a driver to examine the range used for a given
  395  * resource without actually allocating it.
  396  * 
  397  * @param _dev          the parent device of @p _child
  398  * @param _child        the device which owns the resource
  399  * @param _type         the type of resource
  400  * @param _rid          the resource identifier
  401  * @param _start        the address of a location to recieve the start
  402  *                      index of the resource range
  403  * @param _count        the address of a location to recieve the size
  404  *                      of the resource range
  405  */
  406 METHOD int get_resource {
  407         device_t        _dev;
  408         device_t        _child;
  409         int             _type;
  410         int             _rid;
  411         u_long          *_startp;
  412         u_long          *_countp;
  413 };
  414 
  415 /**
  416  * @brief Delete a resource.
  417  * 
  418  * Use this to delete a resource (possibly one previously added with
  419  * BUS_SET_RESOURCE()).
  420  * 
  421  * @param _dev          the parent device of @p _child
  422  * @param _child        the device which owns the resource
  423  * @param _type         the type of resource
  424  * @param _rid          the resource identifier
  425  */
  426 METHOD void delete_resource {
  427         device_t        _dev;
  428         device_t        _child;
  429         int             _type;
  430         int             _rid;
  431 };
  432 
  433 /**
  434  * @brief Return a struct resource_list.
  435  *
  436  * Used by drivers which use bus_generic_rl_alloc_resource() etc. to
  437  * implement their resource handling. It should return the resource
  438  * list of the given child device.
  439  * 
  440  * @param _dev          the parent device of @p _child
  441  * @param _child        the device which owns the resource list
  442  */
  443 METHOD struct resource_list * get_resource_list {
  444         device_t        _dev;
  445         device_t        _child;
  446 } DEFAULT bus_generic_get_resource_list;
  447 
  448 /**
  449  * @brief Is the hardware described by @p _child still attached to the
  450  * system?
  451  *
  452  * This method should return 0 if the device is not present.  It
  453  * should return -1 if it is present.  Any errors in determining
  454  * should be returned as a normal errno value.  Client drivers are to
  455  * assume that the device is present, even if there is an error
  456  * determining if it is there.  Busses are to try to avoid returning
  457  * errors, but newcard will return an error if the device fails to
  458  * implement this method.
  459  * 
  460  * @param _dev          the parent device of @p _child
  461  * @param _child        the device which is being examined
  462  */
  463 METHOD int child_present {
  464         device_t        _dev;
  465         device_t        _child;
  466 } DEFAULT bus_generic_child_present;
  467 
  468 /**
  469  * @brief Returns the pnp info for this device.
  470  *
  471  * Return it as a string.  If the string is insufficient for the
  472  * storage, then return EOVERFLOW.
  473  * 
  474  * @param _dev          the parent device of @p _child
  475  * @param _child        the device which is being examined
  476  * @param _buf          the address of a buffer to receive the pnp
  477  *                      string
  478  * @param _buflen       the size of the buffer pointed to by @p _buf
  479  */
  480 METHOD int child_pnpinfo_str {
  481         device_t        _dev;
  482         device_t        _child;
  483         char            *_buf;
  484         size_t          _buflen;
  485 };
  486 
  487 /**
  488  * @brief Returns the location for this device.
  489  *
  490  * Return it as a string.  If the string is insufficient for the
  491  * storage, then return EOVERFLOW.
  492  * 
  493  * @param _dev          the parent device of @p _child
  494  * @param _child        the device which is being examined
  495  * @param _buf          the address of a buffer to receive the location
  496  *                      string
  497  * @param _buflen       the size of the buffer pointed to by @p _buf
  498  */
  499 METHOD int child_location_str {
  500         device_t        _dev;
  501         device_t        _child;
  502         char            *_buf;
  503         size_t          _buflen;
  504 };
  505 
  506 /**
  507  * @brief Allow drivers to request that an interrupt be bound to a specific
  508  * CPU.
  509  * 
  510  * @param _dev          the parent device of @p _child
  511  * @param _child        the device which allocated the resource
  512  * @param _irq          the resource representing the interrupt
  513  * @param _cpu          the CPU to bind the interrupt to
  514  */
  515 METHOD int bind_intr {
  516         device_t        _dev;
  517         device_t        _child;
  518         struct resource *_irq;
  519         int             _cpu;
  520 } DEFAULT bus_generic_bind_intr;
  521 
  522 /**
  523  * @brief Allow (bus) drivers to specify the trigger mode and polarity
  524  * of the specified interrupt.
  525  * 
  526  * @param _dev          the bus device
  527  * @param _irq          the interrupt number to modify
  528  * @param _trig         the trigger mode required
  529  * @param _pol          the interrupt polarity required
  530  */
  531 METHOD int config_intr {
  532         device_t        _dev;
  533         int             _irq;
  534         enum intr_trigger _trig;
  535         enum intr_polarity _pol;
  536 } DEFAULT bus_generic_config_intr;
  537 
  538 /**
  539  * @brief Allow drivers to associate a description with an active
  540  * interrupt handler.
  541  *
  542  * @param _dev          the parent device of @p _child
  543  * @param _child        the device which allocated the resource
  544  * @param _irq          the resource representing the interrupt
  545  * @param _cookie       the cookie value returned when the interrupt
  546  *                      was originally registered
  547  * @param _descr        the description to associate with the interrupt
  548  */
  549 METHOD int describe_intr {
  550         device_t        _dev;
  551         device_t        _child;
  552         struct resource *_irq;
  553         void            *_cookie;
  554         const char      *_descr;
  555 } DEFAULT bus_generic_describe_intr;
  556 
  557 /**
  558  * @brief Notify a (bus) driver about a child that the hints mechanism
  559  * believes it has discovered.
  560  *
  561  * The bus is responsible for then adding the child in the right order
  562  * and discovering other things about the child.  The bus driver is
  563  * free to ignore this hint, to do special things, etc.  It is all up
  564  * to the bus driver to interpret.
  565  *
  566  * This method is only called in response to the parent bus asking for
  567  * hinted devices to be enumerated.
  568  *
  569  * @param _dev          the bus device
  570  * @param _dname        the name of the device w/o unit numbers
  571  * @param _dunit        the unit number of the device
  572  */
  573 METHOD void hinted_child {
  574         device_t        _dev;
  575         const char *    _dname;
  576         int             _dunit;
  577 };
  578 
  579 /**
  580  * @brief Returns bus_dma_tag_t for use w/ devices on the bus.
  581  *
  582  * @param _dev          the parent device of @p _child
  583  * @param _child        the device to which the tag will belong
  584  */
  585 METHOD bus_dma_tag_t get_dma_tag {
  586         device_t        _dev;
  587         device_t        _child;
  588 } DEFAULT bus_generic_get_dma_tag;

Cache object: 9c8f009ea6efa16dbd3c5a160bca3709


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