pci_intr(9) - NetBSD Manual Pages

PCI_INTR(9)            NetBSD Kernel Developer's Manual            PCI_INTR(9)


NAME

     pci_intr, pci_intr_map, pci_intr_string, pci_intr_evcnt,
     pci_intr_establish, pci_intr_establish_xname, pci_intr_disestablish,
     pci_intr_setattr -- PCI bus interrupt manipulation functions


SYNOPSIS

     #include <dev/pci/pcivar.h>

     int
     pci_intr_map(const struct pci_attach_args *pa, pci_intr_handle_t *ih);

     const char *
     pci_intr_string(pci_chipset_tag_t pc, pci_intr_handle_t ih, char *buf,
         size_t len);

     const struct evcnt *
     pci_intr_evcnt(pci_chipset_tag_t pc, pci_intr_handle_t ih);

     void *
     pci_intr_establish(pci_chipset_tag_t pc, pci_intr_handle_t ih, int ipl,
         int (*intrhand)(void *), void *intrarg);

     void *
     pci_intr_establish_xname(pci_chipset_tag_t pc, pci_intr_handle_t ih,
         int ipl, int (*intrhand)(void *), void *intrarg, const char *xname);

     void
     pci_intr_disestablish(pci_chipset_tag_t pc, void *ih);

     int
     pci_intr_setattr(pci_chipset_tag_t pc, pci_intr_handle_t *ih, int attr,
         uint64_t data);


DESCRIPTION

     The pci_intr functions exist to allow device drivers machine-independent
     access to PCI bus interrupts.  The functions described in this page are
     typically declared in a port's <machine/pci_machdep.h> header file; how-
     ever, drivers should generally include <dev/pci/pcivar.h> to get other
     PCI-specific declarations as well.

     Each driver has an attach() function which has a bus-specific attach_args
     structure.  Each driver for a PCI device is passed a pointer to an object
     of type struct pci_attach_args which contains, among other things, infor-
     mation about the location of the device in the PCI bus topology suffi-
     cient to allow interrupts from the device to be handled.

     If a driver wishes to establish an interrupt handler for the device, it
     should pass the struct pci_attach_args * to the pci_intr_map() function,
     which returns zero on success, and nonzero on failure.  The function sets
     the pci_intr_handle_t pointed at by its second argument to a machine-
     dependent value which identifies a particular interrupt source.

     If the driver wishes to refer to the interrupt source in an attach or
     error message, it should use the value returned by pci_intr_string().
     The buffer passed to pci_intr_string() should be at least PCI_INTRSTR_LEN
     bytes.

     Subsequently, when the driver is prepared to receive interrupts, it
     should call pci_intr_establish() to actually establish the handler; when
     the device interrupts, intrhand will be called with a single argument
     intrarg, and will run at the interrupt priority level ipl.

     The return value of pci_intr_establish() may be saved and passed to
     pci_intr_disestablish() to disable the interrupt handler when the driver
     is no longer interested in interrupts from the device.

     pci_intr_establish_xname() is almost the same as pci_intr_establish().
     The difference is only xname which is used by intrctl(8) to show the
     device name(s) of the interrupt id.

     The pci_intr_setattr() function sets an attribute attr of the interrupt
     handler to data.  Currently, only the following attribute is supported:

     PCI_INTR_MPSAFE  If this attribute is set to true, it specifies that the
                      interrupt handler is multiprocessor safe and works its
                      own locking; otherwise the kernel lock will be held for
                      the call to the interrupt handler.  The default is
                      false.

     The pci_intr_setattr() function returns zero on success, and nonzero on
     failure.

     The pci_intr_evcnt() function should return an evcnt structure pointer or
     NULL if there is no evcnt associated with this interrupt.  See evcnt(9)
     for more details.

   PORTING
     A port's implementation of pci_intr_map() may use the following members
     of struct pci_attach_args to determine how the device's interrupts are
     routed.

             pci_chipset_tag_t pa_pc;
             pcitag_t pa_tag;
             pcitag_t pa_intrtag; /* intr. appears to come from here */
             pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */
             pci_intr_line_t pa_intrline; /* intr. routing information */
             pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */

     PCI-PCI bridges swizzle (permute) interrupt wiring.  Depending on imple-
     mentation details, it may be more convenient to use either original or
     the swizzled interrupt parameters.  The original device tag and interrupt
     pin can be found in pa_tag and pa_rawintrpin respectively, while the
     swizzled tag and pin can be found in pa_intrtag and pa_intrpin.

     When a device is attached to a primary bus, both pairs of fields contain
     the same values.  When a device is found behind one or more pci-pci
     bridges, pa_intrpin contains the ``swizzled'' interrupt pin number, while
     pa_rawintrpin contains the original interrupt pin; pa_tag contains the
     PCI tag of the device itself, and pa_intrtag contains the PCI tag of the
     uppermost bridge device.


SEE ALSO

     evcnt(9), pci(9), pci_msi(9)


HISTORY

     pci_intr_establish_xname() was added in NetBSD 8.0 as part of MSI/MSI-X
     support.

NetBSD 10.99                  September 20, 2018                  NetBSD 10.99