Interrupt handlers have a return value for a couple of reasons.
- Interrupt vectors can be shared between multiple devices. By returning IRQ_NONE/IRQ_HANDLED, an interrupt handler can indicate that the interrupt was/was not from the device it is specifically interested in. If IRQ_NONE is returned, the next handler in the list should be called.
- Even if the IRQ is not shared, an interrupt handler can indicate to the interrupt subsystem that there were problems handling the interrupt and that it should be disabled to prevent system hangs from an irq loop.
Interrupt handlers have a return value for a couple of reasons.
- Interrupt vectors can be shared between multiple devices. By returning IRQ_NONE/IRQ_HANDLED, an interrupt handler can indicate that the interrupt was/was not from the device it is specifically interested in. If IRQ_NONE is returned, the next handler in the list should be called.
- Even if the IRQ is not shared, an interrupt handler can indicate to the interrupt subsystem that there were problems handling the interrupt and that it should be disabled to prevent system hangs from an irq loop.
Interrupt handlers are not interrupt vector. Interrupt vector is the code the processor jumps to when an interrupt is triggered. This is a gross simplification, but here is how it looks :
interrupt_vector {
num = check_interrupt_number()
f = get_interrupt_handler_func(num);
d = get_interrupt_handler_data(num);
/* call interrupt handler */
ret = f(d);
}
So handler and data are registered together, and the interrupt vector code call the registererd handler, passing the registered data, and checks the return value. Of course, here we have a single level of handler, but you can have several, with for example one handler for all PCI Irq, that in turns checks for registered handler for a specific PCI irq and eventually calls itn passing registered data etc...
Of course, real code tends to be much more complicated. You can try this lxr link to navigate through the linux kernel sources
This is covered in chapter 10 of Linux Device Drivers, 3rd edition, by Corbet et al. It is available for free online, or you may toss some shekels O'Reilly's way for dead tree or ebook forms. The part relevant to your question begins on page 278 in the first link.
For what it's worth, here is my attempt to paraphrase those three pages, plus other bits I've Googled up:
When you register a shared IRQ handler, the kernel checks that either:
a. no other handler exists for that interrupt, or
b. all of those previously registered also requested interrupt sharing
If either case applies, it then checks that your dev_id parameter is unique, so that the kernel can differentiate the multiple handlers, e.g. during handler removal.
- When a PCI¹ hardware device raises the IRQ line, the kernel's low-level interrupt handler is called, and it in turn calls all of the registered interrupt handlers, passing each back the
dev_idyou used to register the handler viarequest_irq().
The dev_id value needs to be machine-unique. The common way to do that is to pass a pointer to the per-device struct your driver uses to manage that device. Since this pointer must be within your driver's memory space for it to be useful to the driver, it is ipso facto unique to that driver.²
If there are multiple drivers registered for a given interrupt, they will all be called when any of the devices raises that shared interrupt line. If it wasn't your driver's device that did this, your driver's interrupt handler needs to detect this and return IRQ_NONE promptly.
Another case is that your driver is managing multiple devices. The driver's interrupt handler should use dev_id to decide which device to poll.
The example Corbet et al. give is that of a PC parallel port. When it asserts the interrupt line, it also sets the top bit in its first device register. (That is, inb(0x378) & 0x80 == true, assuming standard I/O port numbering.) When your handler detects this, it is supposed to do its work, then clear the IRQ by writing the value read from the I/O port back to the port with the top bit cleared.
I don't see any reason that particular mechanism is special. A different hardware device could choose a different mechanism. The only important thing is that for a device to allow shared interrupts, it has to have some way for the driver to read the interrupt status of the device, and some way to clear the interrupt. You'll have to read your device's datasheet or programming manual to find out what mechanism your particular device uses.
- When your interrupt handler tells the kernel it handled the interrupt, that doesn't stop the kernel from continuing to call any other handlers registered for that same interrupt. This is unavoidable if you are to share an interrupt line when using level-triggered interrupts.
Imagine two devices assert the same interrupt line at the same time. (Or at least, so close in time that the kernel doesn't have time to call an interrupt handler to clear the line and thereby see the second assertion as separate.) The kernel must call all handlers for that interrupt line, to give each a chance to query its associated hardware to see if it needs attention. It is quite possible for two different drivers to successfully handle an interrupt within the same pass through the handler list for a given interrupt.
Because of this, it is imperative that your driver tell the device it is managing to clear its interrupt assertion sometime before the interrupt handler returns. It's not clear to me what happens otherwise. The continuously-asserted interrupt line will either result in the kernel continuously calling the shared interrupt handlers, or it will mask the kernel's ability to see new interrupts so the handlers are never called. Either way, disaster.
Footnotes:
I specified PCI above because all of the above assumes level-triggered interrupts, as used in the original PCI spec. ISA used edge-triggered interrupts, which made sharing tricky at best, and possible even then only when supported by the hardware. PCIe uses message-signalled interrupts; the interrupt message contains a unique value the kernel can use to avoid the round-robin guessing game required with PCI interrupt sharing. PCIe may eliminate the very need for interrupt sharing. (I don't know if it actually does, just that it has the potential to.)
Linux kernel drivers all share the same memory space, but an unrelated driver isn't supposed to be mucking around in another's memory space. Unless you pass that pointer around, you can be pretty sure another driver isn't going to come up with that same value accidentally on its own.
When a driver requests a shared IRQ, it passes a pointer to the kernel to a reference to a device specific structure within the driver's memory space.
According to LDD3:
Whenever two or more drivers are sharing an interrupt line and the hardware interrupts the processor on that line, the kernel invokes every handler registered for that interrupt, passing each its own dev_id.
Upon checking several drivers' IRQ handlers, it appears they probe the hardware itself in order to determine whether or not it should handle the interrupt or return IRQ_NONE.
Examples
UHCI-HCD Driver status = inw(uhci->io_addr + USBSTS);
if (!(status & ~USBSTS_HCH)) /* shared interrupt, not mine */
return IRQ_NONE;
In the code above, the driver is reading the USBSTS register to determine if there is an interrupt to service.
intmask = sdhci_readl(host, SDHCI_INT_STATUS);
if (!intmask || intmask == 0xffffffff) {
result = IRQ_NONE;
goto out;
}
Just as in the previous example, the driver is checking a status register, SDHCI_INT_STATUS to determine whether it needs to service an interrupt.
struct ath5k_softc *sc = dev_id;
struct ath5k_hw *ah = sc->ah;
enum ath5k_int status;
unsigned int counter = 1000;
if (unlikely(test_bit(ATH_STAT_INVALID, sc->status) ||
!ath5k_hw_is_intr_pending(ah)))
return IRQ_NONE;
Just one more example.
The actual flags passed into request_irq() are defined in a comment in :
/*
* These flags used only by the kernel as part of the
* irq handling routines.
*
* IRQF_DISABLED - keep irqs disabled when calling the action handler.
* DEPRECATED. This flag is a NOOP and scheduled to be removed
* IRQF_SAMPLE_RANDOM - irq is used to feed the random generator
* IRQF_SHARED - allow sharing the irq among several devices
* IRQF_PROBE_SHARED - set by callers when they expect sharing mismatches to occur
* IRQF_TIMER - Flag to mark this interrupt as timer interrupt
* IRQF_PERCPU - Interrupt is per cpu
* IRQF_NOBALANCING - Flag to exclude this interrupt from irq balancing
* IRQF_IRQPOLL - Interrupt is used for polling (only the interrupt that is
* registered first in an shared interrupt is considered for
* performance reasons)
* IRQF_ONESHOT - Interrupt is not reenabled after the hardirq handler finished.
* Used by threaded interrupts which need to keep the
* irq line disabled until the threaded handler has been run.
* IRQF_NO_SUSPEND - Do not disable this IRQ during suspend
* IRQF_FORCE_RESUME - Force enable it on resume even if IRQF_NO_SUSPEND is set
* IRQF_NO_THREAD - Interrupt cannot be threaded
* IRQF_EARLY_RESUME - Resume IRQ early during syscore instead of at device
* resume time.
*/
These are bits, so a logical OR (ie |) of a subset of these can be passed in; and if none apply, then the empty set is perfectly fine -- ie a value 0 for the flags parameter.
Since IRQF_TRIGGER_NONE is 0, passing 0 into request_irq() just says leave the triggering configuration of the IRQ alone -- ie however the hardware/firmware configured it.
IRQ_NONE is in a different namespace; it is one of the possible return values of an interrupt handler (the function passed into request_irq()), and it means that the interrupt handler did not handle an interrupt.
IRQ_NONE is a constant for the return values of IRQ handlers. It is still available in include/linux/irqreturn.h.
IRQ_TRIGGER_NONE is a specifier for the behaviour of the interrupt line.
So they are not equivalent.