441 lines
13 KiB
ReStructuredText
441 lines
13 KiB
ReStructuredText
.. include:: <isonum.txt>
|
|
|
|
==========================
|
|
Linux generic IRQ handling
|
|
==========================
|
|
|
|
:Copyright: |copy| 2005-2010: Thomas Gleixner
|
|
:Copyright: |copy| 2005-2006: Ingo Molnar
|
|
|
|
Introduction
|
|
============
|
|
|
|
The generic interrupt handling layer is designed to provide a complete
|
|
abstraction of interrupt handling for device drivers. It is able to
|
|
handle all the different types of interrupt controller hardware. Device
|
|
drivers use generic API functions to request, enable, disable and free
|
|
interrupts. The drivers do not have to know anything about interrupt
|
|
hardware details, so they can be used on different platforms without
|
|
code changes.
|
|
|
|
This documentation is provided to developers who want to implement an
|
|
interrupt subsystem based for their architecture, with the help of the
|
|
generic IRQ handling layer.
|
|
|
|
Rationale
|
|
=========
|
|
|
|
The original implementation of interrupt handling in Linux uses the
|
|
:c:func:`__do_IRQ` super-handler, which is able to deal with every type of
|
|
interrupt logic.
|
|
|
|
Originally, Russell King identified different types of handlers to build
|
|
a quite universal set for the ARM interrupt handler implementation in
|
|
Linux 2.5/2.6. He distinguished between:
|
|
|
|
- Level type
|
|
|
|
- Edge type
|
|
|
|
- Simple type
|
|
|
|
During the implementation we identified another type:
|
|
|
|
- Fast EOI type
|
|
|
|
In the SMP world of the :c:func:`__do_IRQ` super-handler another type was
|
|
identified:
|
|
|
|
- Per CPU type
|
|
|
|
This split implementation of high-level IRQ handlers allows us to
|
|
optimize the flow of the interrupt handling for each specific interrupt
|
|
type. This reduces complexity in that particular code path and allows
|
|
the optimized handling of a given type.
|
|
|
|
The original general IRQ implementation used hw_interrupt_type
|
|
structures and their ``->ack``, ``->end`` [etc.] callbacks to differentiate
|
|
the flow control in the super-handler. This leads to a mix of flow logic
|
|
and low-level hardware logic, and it also leads to unnecessary code
|
|
duplication: for example in i386, there is an ``ioapic_level_irq`` and an
|
|
``ioapic_edge_irq`` IRQ-type which share many of the low-level details but
|
|
have different flow handling.
|
|
|
|
A more natural abstraction is the clean separation of the 'irq flow' and
|
|
the 'chip details'.
|
|
|
|
Analysing a couple of architecture's IRQ subsystem implementations
|
|
reveals that most of them can use a generic set of 'irq flow' methods
|
|
and only need to add the chip-level specific code. The separation is
|
|
also valuable for (sub)architectures which need specific quirks in the
|
|
IRQ flow itself but not in the chip details - and thus provides a more
|
|
transparent IRQ subsystem design.
|
|
|
|
Each interrupt descriptor is assigned its own high-level flow handler,
|
|
which is normally one of the generic implementations. (This high-level
|
|
flow handler implementation also makes it simple to provide
|
|
demultiplexing handlers which can be found in embedded platforms on
|
|
various architectures.)
|
|
|
|
The separation makes the generic interrupt handling layer more flexible
|
|
and extensible. For example, an (sub)architecture can use a generic
|
|
IRQ-flow implementation for 'level type' interrupts and add a
|
|
(sub)architecture specific 'edge type' implementation.
|
|
|
|
To make the transition to the new model easier and prevent the breakage
|
|
of existing implementations, the :c:func:`__do_IRQ` super-handler is still
|
|
available. This leads to a kind of duality for the time being. Over time
|
|
the new model should be used in more and more architectures, as it
|
|
enables smaller and cleaner IRQ subsystems. It's deprecated for three
|
|
years now and about to be removed.
|
|
|
|
Known Bugs And Assumptions
|
|
==========================
|
|
|
|
None (knock on wood).
|
|
|
|
Abstraction layers
|
|
==================
|
|
|
|
There are three main levels of abstraction in the interrupt code:
|
|
|
|
1. High-level driver API
|
|
|
|
2. High-level IRQ flow handlers
|
|
|
|
3. Chip-level hardware encapsulation
|
|
|
|
Interrupt control flow
|
|
----------------------
|
|
|
|
Each interrupt is described by an interrupt descriptor structure
|
|
irq_desc. The interrupt is referenced by an 'unsigned int' numeric
|
|
value which selects the corresponding interrupt description structure in
|
|
the descriptor structures array. The descriptor structure contains
|
|
status information and pointers to the interrupt flow method and the
|
|
interrupt chip structure which are assigned to this interrupt.
|
|
|
|
Whenever an interrupt triggers, the low-level architecture code calls
|
|
into the generic interrupt code by calling :c:func:`desc->handle_irq`. This
|
|
high-level IRQ handling function only uses desc->irq_data.chip
|
|
primitives referenced by the assigned chip descriptor structure.
|
|
|
|
High-level Driver API
|
|
---------------------
|
|
|
|
The high-level Driver API consists of following functions:
|
|
|
|
- :c:func:`request_irq`
|
|
|
|
- :c:func:`free_irq`
|
|
|
|
- :c:func:`disable_irq`
|
|
|
|
- :c:func:`enable_irq`
|
|
|
|
- :c:func:`disable_irq_nosync` (SMP only)
|
|
|
|
- :c:func:`synchronize_irq` (SMP only)
|
|
|
|
- :c:func:`irq_set_irq_type`
|
|
|
|
- :c:func:`irq_set_irq_wake`
|
|
|
|
- :c:func:`irq_set_handler_data`
|
|
|
|
- :c:func:`irq_set_chip`
|
|
|
|
- :c:func:`irq_set_chip_data`
|
|
|
|
See the autogenerated function documentation for details.
|
|
|
|
High-level IRQ flow handlers
|
|
----------------------------
|
|
|
|
The generic layer provides a set of pre-defined irq-flow methods:
|
|
|
|
- :c:func:`handle_level_irq`
|
|
|
|
- :c:func:`handle_edge_irq`
|
|
|
|
- :c:func:`handle_fasteoi_irq`
|
|
|
|
- :c:func:`handle_simple_irq`
|
|
|
|
- :c:func:`handle_percpu_irq`
|
|
|
|
- :c:func:`handle_edge_eoi_irq`
|
|
|
|
- :c:func:`handle_bad_irq`
|
|
|
|
The interrupt flow handlers (either pre-defined or architecture
|
|
specific) are assigned to specific interrupts by the architecture either
|
|
during bootup or during device initialization.
|
|
|
|
Default flow implementations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Helper functions
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
The helper functions call the chip primitives and are used by the
|
|
default flow implementations. The following helper functions are
|
|
implemented (simplified excerpt)::
|
|
|
|
default_enable(struct irq_data *data)
|
|
{
|
|
desc->irq_data.chip->irq_unmask(data);
|
|
}
|
|
|
|
default_disable(struct irq_data *data)
|
|
{
|
|
if (!delay_disable(data))
|
|
desc->irq_data.chip->irq_mask(data);
|
|
}
|
|
|
|
default_ack(struct irq_data *data)
|
|
{
|
|
chip->irq_ack(data);
|
|
}
|
|
|
|
default_mask_ack(struct irq_data *data)
|
|
{
|
|
if (chip->irq_mask_ack) {
|
|
chip->irq_mask_ack(data);
|
|
} else {
|
|
chip->irq_mask(data);
|
|
chip->irq_ack(data);
|
|
}
|
|
}
|
|
|
|
noop(struct irq_data *data))
|
|
{
|
|
}
|
|
|
|
|
|
|
|
Default flow handler implementations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Default Level IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_level_irq provides a generic implementation for level-triggered
|
|
interrupts.
|
|
|
|
The following control flow is implemented (simplified excerpt)::
|
|
|
|
desc->irq_data.chip->irq_mask_ack();
|
|
handle_irq_event(desc->action);
|
|
desc->irq_data.chip->irq_unmask();
|
|
|
|
|
|
Default Fast EOI IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_fasteoi_irq provides a generic implementation for interrupts,
|
|
which only need an EOI at the end of the handler.
|
|
|
|
The following control flow is implemented (simplified excerpt)::
|
|
|
|
handle_irq_event(desc->action);
|
|
desc->irq_data.chip->irq_eoi();
|
|
|
|
|
|
Default Edge IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_edge_irq provides a generic implementation for edge-triggered
|
|
interrupts.
|
|
|
|
The following control flow is implemented (simplified excerpt)::
|
|
|
|
if (desc->status & running) {
|
|
desc->irq_data.chip->irq_mask_ack();
|
|
desc->status |= pending | masked;
|
|
return;
|
|
}
|
|
desc->irq_data.chip->irq_ack();
|
|
desc->status |= running;
|
|
do {
|
|
if (desc->status & masked)
|
|
desc->irq_data.chip->irq_unmask();
|
|
desc->status &= ~pending;
|
|
handle_irq_event(desc->action);
|
|
} while (status & pending);
|
|
desc->status &= ~running;
|
|
|
|
|
|
Default simple IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_simple_irq provides a generic implementation for simple
|
|
interrupts.
|
|
|
|
.. note::
|
|
|
|
The simple flow handler does not call any handler/chip primitives.
|
|
|
|
The following control flow is implemented (simplified excerpt)::
|
|
|
|
handle_irq_event(desc->action);
|
|
|
|
|
|
Default per CPU flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_percpu_irq provides a generic implementation for per CPU
|
|
interrupts.
|
|
|
|
Per CPU interrupts are only available on SMP and the handler provides a
|
|
simplified version without locking.
|
|
|
|
The following control flow is implemented (simplified excerpt)::
|
|
|
|
if (desc->irq_data.chip->irq_ack)
|
|
desc->irq_data.chip->irq_ack();
|
|
handle_irq_event(desc->action);
|
|
if (desc->irq_data.chip->irq_eoi)
|
|
desc->irq_data.chip->irq_eoi();
|
|
|
|
|
|
EOI Edge IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_edge_eoi_irq provides an abnomination of the edge handler
|
|
which is solely used to tame a badly wreckaged irq controller on
|
|
powerpc/cell.
|
|
|
|
Bad IRQ flow handler
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
handle_bad_irq is used for spurious interrupts which have no real
|
|
handler assigned..
|
|
|
|
Quirks and optimizations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The generic functions are intended for 'clean' architectures and chips,
|
|
which have no platform-specific IRQ handling quirks. If an architecture
|
|
needs to implement quirks on the 'flow' level then it can do so by
|
|
overriding the high-level irq-flow handler.
|
|
|
|
Delayed interrupt disable
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This per interrupt selectable feature, which was introduced by Russell
|
|
King in the ARM interrupt implementation, does not mask an interrupt at
|
|
the hardware level when :c:func:`disable_irq` is called. The interrupt is kept
|
|
enabled and is masked in the flow handler when an interrupt event
|
|
happens. This prevents losing edge interrupts on hardware which does not
|
|
store an edge interrupt event while the interrupt is disabled at the
|
|
hardware level. When an interrupt arrives while the IRQ_DISABLED flag
|
|
is set, then the interrupt is masked at the hardware level and the
|
|
IRQ_PENDING bit is set. When the interrupt is re-enabled by
|
|
:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt
|
|
is resent either via hardware or by a software resend mechanism. (It's
|
|
necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
|
|
the delayed interrupt disable feature and your hardware is not capable
|
|
of retriggering an interrupt.) The delayed interrupt disable is not
|
|
configurable.
|
|
|
|
Chip-level hardware encapsulation
|
|
---------------------------------
|
|
|
|
The chip-level hardware descriptor structure :c:type:`irq_chip` contains all
|
|
the direct chip relevant functions, which can be utilized by the irq flow
|
|
implementations.
|
|
|
|
- ``irq_ack``
|
|
|
|
- ``irq_mask_ack`` - Optional, recommended for performance
|
|
|
|
- ``irq_mask``
|
|
|
|
- ``irq_unmask``
|
|
|
|
- ``irq_eoi`` - Optional, required for EOI flow handlers
|
|
|
|
- ``irq_retrigger`` - Optional
|
|
|
|
- ``irq_set_type`` - Optional
|
|
|
|
- ``irq_set_wake`` - Optional
|
|
|
|
These primitives are strictly intended to mean what they say: ack means
|
|
ACK, masking means masking of an IRQ line, etc. It is up to the flow
|
|
handler(s) to use these basic units of low-level functionality.
|
|
|
|
__do_IRQ entry point
|
|
====================
|
|
|
|
The original implementation :c:func:`__do_IRQ` was an alternative entry point
|
|
for all types of interrupts. It no longer exists.
|
|
|
|
This handler turned out to be not suitable for all interrupt hardware
|
|
and was therefore reimplemented with split functionality for
|
|
edge/level/simple/percpu interrupts. This is not only a functional
|
|
optimization. It also shortens code paths for interrupts.
|
|
|
|
Locking on SMP
|
|
==============
|
|
|
|
The locking of chip registers is up to the architecture that defines the
|
|
chip primitives. The per-irq structure is protected via desc->lock, by
|
|
the generic layer.
|
|
|
|
Generic interrupt chip
|
|
======================
|
|
|
|
To avoid copies of identical implementations of IRQ chips the core
|
|
provides a configurable generic interrupt chip implementation.
|
|
Developers should check carefully whether the generic chip fits their
|
|
needs before implementing the same functionality slightly differently
|
|
themselves.
|
|
|
|
.. kernel-doc:: kernel/irq/generic-chip.c
|
|
:export:
|
|
|
|
Structures
|
|
==========
|
|
|
|
This chapter contains the autogenerated documentation of the structures
|
|
which are used in the generic IRQ layer.
|
|
|
|
.. kernel-doc:: include/linux/irq.h
|
|
:internal:
|
|
|
|
.. kernel-doc:: include/linux/interrupt.h
|
|
:internal:
|
|
|
|
Public Functions Provided
|
|
=========================
|
|
|
|
This chapter contains the autogenerated documentation of the kernel API
|
|
functions which are exported.
|
|
|
|
.. kernel-doc:: kernel/irq/manage.c
|
|
|
|
.. kernel-doc:: kernel/irq/chip.c
|
|
|
|
Internal Functions Provided
|
|
===========================
|
|
|
|
This chapter contains the autogenerated documentation of the internal
|
|
functions.
|
|
|
|
.. kernel-doc:: kernel/irq/irqdesc.c
|
|
|
|
.. kernel-doc:: kernel/irq/handle.c
|
|
|
|
.. kernel-doc:: kernel/irq/chip.c
|
|
|
|
Credits
|
|
=======
|
|
|
|
The following people have contributed to this document:
|
|
|
|
1. Thomas Gleixner tglx@linutronix.de
|
|
|
|
2. Ingo Molnar mingo@elte.hu
|