pcibr_rrb(D3)

NAME
     pcibr_rrb_check - query RRB allocation
     pcibr_rrb_alloc - allocate RRBs for this slot
     pcibr_alloc_all_rrbs - allocate RRBs for slot group
     pcibr_set_rrb_callback - set up allocation callback

SYNOPSIS
     #include <sys/PCI/pcibr.h>

     int
     pcibr_rrb_alloc(
               vertex_hdl_t pconn_vhdl,
               int *count_vchan0,
               int *count_vchan1)

     int
     pcibr_rrb_check(vertex_hdl_t pconn_vhdl,
               int *count_vchan0,
               int *count_vchan1,
               int *count_reserved,
               int *count_pool)

     int
     pcibr_alloc_all_rrbs(
               vertex_hdl_t xconn_vhdl,
               int even_odd,
               int dev_1_rrbs, int virt1,
               int dev_2_rrbs, int virt2,
               int dev_3_rrbs, int virt3,
               int dev_4_rrbs, int virt4)

     void
     pcibr_set_rrb_callback(
               vertex_hdl_t xconn_vhdl,
               rrb_alloc_funct_t rrb_alloc_funct)



   Arguments
     pconn_vhdl
             is an appropriate PCI connection point.

     xconn_vhdl
             is an appropriate XIO connection point.

     count_vchan0, count_vchan1
             is where to get and where to return RRB counts for the primary
             and alternate virtual DMA channels.

     even_odd
             specifies whether pcibr_alloc_all_rrbs() is operating on the RRB
             allocatios for the even numbered or the odd numbered PCI DMA
             REQ/GNT pairs.  Zero specifies the even pairs, One specifies the
             odd pairs.

     dev_N_rrbs
             specifies the total RRBs to be allocated for both virtual
             channels for the corresponding REQ/GNT pair.

     virtN   specifies whether alternate virtual channel accesses will be made
             using the corresponding REQ/GNT pair.

DESCRIPTION
     Drivers are not normally expected to need to call any of these functions;
     they exist for the use of drivers that service devices that actually
     contain the SGI XIO-PCI Bridge ASIC.

     pcibr_rrb_alloc() is used to adjust the allocation for a specific PCI DMA
     REQ/GNT pair, when the automatic allocation is insufficient, without
     modifying the RRB allocations for other REQ/GNT pairs.

     pcibr_rrb_check() can be used to observe the current RRB allocation state
     for a REQ/GNT pair without changing it.  Note that the pool value
     returned may change as other device drivers within the same RRB pool
     allocate RRBs.

     pcibr_alloc_all_rrbs() can be used to efficiently set up the allocation
     for all four devices in the RRB pool.

     The most common time to modify RRBs is from a NIC callback based on
     recognizing the XIO part number.  However, some drivers may want to do
     further RRB adjustment after the infrastructure hsa probed the contents
     of the PCI bus.  pcibr_set_rrb_callback() can be used to specify a
     function to be called when pcibr has finished taking inventory on the
     bus; it is passed the XIO connection point and an array containing the
     VENDOR_ID values from the eight PCI slots.

   Automatic RRB Management
     During the booting process, the pcibr module observes the RRB allocations
     that may have been made by the boot prom.  Any RRBs assigned to REQ/GNT
     pairs corresponding to IDSEL pins on which there is no response (and
     which are not noted specially as secondary REQ/GNT pairs using the pcibr
     hint mechanism are unassigned.

     Based on the number of unassigned RRBs in each group, the number of
     active PCI DMA REQ/GNT pairs and the preallocation of RRBs, some
     unassigned RRBs will be reserved for each active REQ/GNT pair so that
     each pair can have up to three RRBs.  The reservation level may be
     decreased to avoid overbooking the RRBs.

     When DMA related requests are received by pcibr from pciio, a check is
     made that at least one RRB is actually assigned to that REQ/GNT pair and
     virtual channel; if not, one is assigned, either from that pair's
     reservation pool or from the free pool.  If the DMA is marked as
     PREFETCH, an attempt is made to allocate a second RRB.

     In nearly all cases, the above algorithm provides sufficient RRB
     resources for optimum DMA performance.

NOTES
     Failure to automatically allocate an RRB does not currently cause a
     failure to map the DMA, but if no RRBs are assigned and the device
     attempts to do a read it will stall forever on the PCI bus.

SEE ALSO
     nic_vmc(D3), pcibr_hints(D3), pciio(D3)

DIAGNOSTICS
     All functions return zero if all went well, or negative if there was a
     problem.