Commit ee430599 authored by Geert Uytterhoeven's avatar Geert Uytterhoeven Committed by Thomas Gleixner

genirq: Update DocBook comments

Fix some parts to match the actual code.

[ tglx: Resolved the FIXMEs Gerd put in ]
Signed-off-by: default avatarGeert Uytterhoeven <geert@linux-m68k.org>
Link: http://lkml.kernel.org/r/%3C1302426113-13808-3-git-send-email-geert%40linux-m68k.org%3ESigned-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Cc: linux-doc@vger.kernel.org
parent 0911f124
...@@ -191,8 +191,8 @@ ...@@ -191,8 +191,8 @@
<para> <para>
Whenever an interrupt triggers, the lowlevel arch code calls into Whenever an interrupt triggers, the lowlevel arch code calls into
the generic interrupt code by calling desc->handle_irq(). the generic interrupt code by calling desc->handle_irq().
This highlevel IRQ handling function only uses desc->chip primitives This highlevel IRQ handling function only uses desc->irq_data.chip
referenced by the assigned chip descriptor structure. primitives referenced by the assigned chip descriptor structure.
</para> </para>
</sect1> </sect1>
<sect1 id="Highlevel_Driver_API"> <sect1 id="Highlevel_Driver_API">
...@@ -206,11 +206,11 @@ ...@@ -206,11 +206,11 @@
<listitem><para>enable_irq()</para></listitem> <listitem><para>enable_irq()</para></listitem>
<listitem><para>disable_irq_nosync() (SMP only)</para></listitem> <listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
<listitem><para>synchronize_irq() (SMP only)</para></listitem> <listitem><para>synchronize_irq() (SMP only)</para></listitem>
<listitem><para>set_irq_type()</para></listitem> <listitem><para>irq_set_irq_type()</para></listitem>
<listitem><para>set_irq_wake()</para></listitem> <listitem><para>irq_set_irq_wake()</para></listitem>
<listitem><para>set_irq_data()</para></listitem> <listitem><para>irq_set_handler_data()</para></listitem>
<listitem><para>set_irq_chip()</para></listitem> <listitem><para>irq_set_chip()</para></listitem>
<listitem><para>set_irq_chip_data()</para></listitem> <listitem><para>irq_set_chip_data()</para></listitem>
</itemizedlist> </itemizedlist>
See the autogenerated function documentation for details. See the autogenerated function documentation for details.
</para> </para>
...@@ -225,6 +225,8 @@ ...@@ -225,6 +225,8 @@
<listitem><para>handle_fasteoi_irq</para></listitem> <listitem><para>handle_fasteoi_irq</para></listitem>
<listitem><para>handle_simple_irq</para></listitem> <listitem><para>handle_simple_irq</para></listitem>
<listitem><para>handle_percpu_irq</para></listitem> <listitem><para>handle_percpu_irq</para></listitem>
<listitem><para>handle_edge_eoi_irq</para></listitem>
<listitem><para>handle_bad_irq</para></listitem>
</itemizedlist> </itemizedlist>
The interrupt flow handlers (either predefined or architecture The interrupt flow handlers (either predefined or architecture
specific) are assigned to specific interrupts by the architecture specific) are assigned to specific interrupts by the architecture
...@@ -241,13 +243,13 @@ ...@@ -241,13 +243,13 @@
<programlisting> <programlisting>
default_enable(struct irq_data *data) default_enable(struct irq_data *data)
{ {
desc->chip->irq_unmask(data); desc->irq_data.chip->irq_unmask(data);
} }
default_disable(struct irq_data *data) default_disable(struct irq_data *data)
{ {
if (!delay_disable(data)) if (!delay_disable(data))
desc->chip->irq_mask(data); desc->irq_data.chip->irq_mask(data);
} }
default_ack(struct irq_data *data) default_ack(struct irq_data *data)
...@@ -284,9 +286,9 @@ noop(struct irq_data *data)) ...@@ -284,9 +286,9 @@ noop(struct irq_data *data))
<para> <para>
The following control flow is implemented (simplified excerpt): The following control flow is implemented (simplified excerpt):
<programlisting> <programlisting>
desc->chip->irq_mask(); desc->irq_data.chip->irq_mask_ack();
handle_IRQ_event(desc->action); handle_irq_event(desc->action);
desc->chip->irq_unmask(); desc->irq_data.chip->irq_unmask();
</programlisting> </programlisting>
</para> </para>
</sect3> </sect3>
...@@ -300,8 +302,8 @@ desc->chip->irq_unmask(); ...@@ -300,8 +302,8 @@ desc->chip->irq_unmask();
<para> <para>
The following control flow is implemented (simplified excerpt): The following control flow is implemented (simplified excerpt):
<programlisting> <programlisting>
handle_IRQ_event(desc->action); handle_irq_event(desc->action);
desc->chip->irq_eoi(); desc->irq_data.chip->irq_eoi();
</programlisting> </programlisting>
</para> </para>
</sect3> </sect3>
...@@ -315,17 +317,17 @@ desc->chip->irq_eoi(); ...@@ -315,17 +317,17 @@ desc->chip->irq_eoi();
The following control flow is implemented (simplified excerpt): The following control flow is implemented (simplified excerpt):
<programlisting> <programlisting>
if (desc->status &amp; running) { if (desc->status &amp; running) {
desc->chip->irq_mask(); desc->irq_data.chip->irq_mask_ack();
desc->status |= pending | masked; desc->status |= pending | masked;
return; return;
} }
desc->chip->irq_ack(); desc->irq_data.chip->irq_ack();
desc->status |= running; desc->status |= running;
do { do {
if (desc->status &amp; masked) if (desc->status &amp; masked)
desc->chip->irq_unmask(); desc->irq_data.chip->irq_unmask();
desc->status &amp;= ~pending; desc->status &amp;= ~pending;
handle_IRQ_event(desc->action); handle_irq_event(desc->action);
} while (status &amp; pending); } while (status &amp; pending);
desc->status &amp;= ~running; desc->status &amp;= ~running;
</programlisting> </programlisting>
...@@ -344,7 +346,7 @@ desc->status &amp;= ~running; ...@@ -344,7 +346,7 @@ desc->status &amp;= ~running;
<para> <para>
The following control flow is implemented (simplified excerpt): The following control flow is implemented (simplified excerpt):
<programlisting> <programlisting>
handle_IRQ_event(desc->action); handle_irq_event(desc->action);
</programlisting> </programlisting>
</para> </para>
</sect3> </sect3>
...@@ -362,12 +364,29 @@ handle_IRQ_event(desc->action); ...@@ -362,12 +364,29 @@ handle_IRQ_event(desc->action);
<para> <para>
The following control flow is implemented (simplified excerpt): The following control flow is implemented (simplified excerpt):
<programlisting> <programlisting>
handle_IRQ_event(desc->action); if (desc->irq_data.chip->irq_ack)
if (desc->chip->irq_eoi) desc->irq_data.chip->irq_ack();
desc->chip->irq_eoi(); handle_irq_event(desc->action);
if (desc->irq_data.chip->irq_eoi)
desc->irq_data.chip->irq_eoi();
</programlisting> </programlisting>
</para> </para>
</sect3> </sect3>
<sect3 id="EOI_Edge_IRQ_flow_handler">
<title>EOI Edge IRQ flow handler</title>
<para>
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.
</para>
</sect3>
<sect3 id="BAD_IRQ_flow_handler">
<title>Bad IRQ flow handler</title>
<para>
handle_bad_irq is used for spurious interrupts which
have no real handler assigned..
</para>
</sect3>
</sect2> </sect2>
<sect2 id="Quirks_and_optimizations"> <sect2 id="Quirks_and_optimizations">
<title>Quirks and optimizations</title> <title>Quirks and optimizations</title>
...@@ -410,6 +429,7 @@ if (desc->chip->irq_eoi) ...@@ -410,6 +429,7 @@ if (desc->chip->irq_eoi)
<listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem> <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem>
<listitem><para>irq_mask()</para></listitem> <listitem><para>irq_mask()</para></listitem>
<listitem><para>irq_unmask()</para></listitem> <listitem><para>irq_unmask()</para></listitem>
<listitem><para>irq_eoi() - Optional, required for eoi flow handlers</para></listitem>
<listitem><para>irq_retrigger() - Optional</para></listitem> <listitem><para>irq_retrigger() - Optional</para></listitem>
<listitem><para>irq_set_type() - Optional</para></listitem> <listitem><para>irq_set_type() - Optional</para></listitem>
<listitem><para>irq_set_wake() - Optional</para></listitem> <listitem><para>irq_set_wake() - Optional</para></listitem>
...@@ -424,32 +444,24 @@ if (desc->chip->irq_eoi) ...@@ -424,32 +444,24 @@ if (desc->chip->irq_eoi)
<chapter id="doirq"> <chapter id="doirq">
<title>__do_IRQ entry point</title> <title>__do_IRQ entry point</title>
<para> <para>
The original implementation __do_IRQ() is an alternative entry The original implementation __do_IRQ() was an alternative entry
point for all types of interrupts. point for all types of interrupts. It not longer exists.
</para> </para>
<para> <para>
This handler turned out to be not suitable for all This handler turned out to be not suitable for all
interrupt hardware and was therefore reimplemented with split interrupt hardware and was therefore reimplemented with split
functionality for egde/level/simple/percpu interrupts. This is not functionality for edge/level/simple/percpu interrupts. This is not
only a functional optimization. It also shortens code paths for only a functional optimization. It also shortens code paths for
interrupts. interrupts.
</para> </para>
<para>
To make use of the split implementation, replace the call to
__do_IRQ by a call to desc->handle_irq() and associate
the appropriate handler function to desc->handle_irq().
In most cases the generic handler implementations should
be sufficient.
</para>
</chapter> </chapter>
<chapter id="locking"> <chapter id="locking">
<title>Locking on SMP</title> <title>Locking on SMP</title>
<para> <para>
The locking of chip registers is up to the architecture that The locking of chip registers is up to the architecture that
defines the chip primitives. There is a chip->lock field that can be used defines the chip primitives. The per-irq structure is
for serialization, but the generic layer does not touch it. The per-irq protected via desc->lock, by the generic layer.
structure is protected via desc->lock, by the generic layer.
</para> </para>
</chapter> </chapter>
<chapter id="structs"> <chapter id="structs">
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment