pci_intr(9) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
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. Currenty, 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 9.1 September 20, 2018 NetBSD 9.1
Powered by man-cgi (2024-03-20). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.