Skip to contentSkip to conversation

genirq: doc: add design documentation

PATCH In review Ingo Molnar 2 participants 3 messages May 17, 2006 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 15/50 genirq: doc: add design documentation

From: Thomas Gleixner <[email protected]>

Add docbook file - includes API documentation.

---
 Documentation/DocBook/Makefile        |    3 
 Documentation/DocBook/genericirq.tmpl |  453 ++++++++++++++++++++++++++++++++++
 2 files changed, 455 insertions(+), 1 deletion(-)
Documentation/DocBook/Makefile +2 -1
Index: linux-genirq.q/Documentation/DocBook/Makefile
===================================================================
@@ -10,7 +10,8 @@ DOCBOOKS := wanbook.xml z8530book.xml mc
 	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
 	    procfs-guide.xml writing_usb_driver.xml \
 	    kernel-api.xml journal-api.xml lsm.xml usb.xml \
-	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml
+	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
+	    genericirq.xml
 
 ###
 # The build process is as follows (targets):
Documentation/DocBook/genericirq.tmpl new file +453 -0

453 lines not on this page · raw message

#1 lore raw
Quoted 3 lines · On Wed, 17 May 2006 02:16:23 +0200 Ingo Molnar wrote:

From: Thomas Gleixner <[email protected]>

Add docbook file - includes API documentation.

Thanks. :)

Quoted 7 lines

Index: linux-genirq.q/Documentation/DocBook/genericirq.tmpl
===================================================================

Documentation/DocBook/genericirq.tmpl new file +1 -0
@@ -0,0 +1,453 @@
 
+  <chapter id="rationale">

Documentation/DocBook/genericirq.tmpl line 97

Quoted 10 lines
Documentation/DocBook/genericirq.tmpl new file +10 -0
+    <title>Rationale</title>
+	<para>
+	The original implementation of interrupt handling in Linux is using
+	the __do_IRQ() super-handler, which is able to deal with every
+	type of interrupt logic.
+	</para>
+	<para>
+	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 distiguished between:

distinguished

Documentation/DocBook/genericirq.tmpl line 125

Quoted 11 lines
Documentation/DocBook/genericirq.tmpl new file +11 -0
+	<para>
+	The original general IRQ implementation used hw_interrupt_type
+	structures and their ->ack(), ->end() [etc.] callbcks to
+	differentiate the flow control in the super-handler. This leads to
+	a mix of flow logic and lowlevel hardware logic, and it also leads
+	to unnecessary code duplication: for example in i386, there is a
+	ioapic_level_irq and a ioapic_edge_irq irq-type which share many
+	of the lowlevel details but have different flow handling.
+	</para>
+	<para>
+	A more natural abstraction is the clean seperation of the

separation (multiple locations)
(or as my wife says, "there's 'a rat' in separate.")

Documentation/DocBook/genericirq.tmpl line 138

Quoted 13 lines
Documentation/DocBook/genericirq.tmpl new file +13 -0
+	'irq flow' and the 'chip details'.
+	</para>
+	<para>
+	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 seperation 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.
+	</para>
+	<para>
+	Each interrupt descriptor has assigned its own highlevel flow

s/has/is/

Quoted 4 lines
Documentation/DocBook/genericirq.tmpl new file +4 -0
+	handler, which is normally one of the generic
+	implementations. (This highlevel flow handler implementation also
+	makes it simple to provide demultiplexing handlers which can be
+	found in embedded platforms on various architectures.)

Documentation/DocBook/genericirq.tmpl line 152

Quoted 10 lines
Documentation/DocBook/genericirq.tmpl new file +10 -0
+	</para>
+	<para>
+	The seperation 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.
+	</para>
+	<para>
+	To make the transition to the new model easier and prevent the
+	breakage of existing implementations the __do_IRQ() super-handler

add comma after "implementations"

Quoted 11 lines
Documentation/DocBook/genericirq.tmpl new file +11 -0
+	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.
+	</para>
+  </chapter>
+  <chapter id="bugs">
+    <title>Known Bugs And Assumptions</title>
+    <para>
+	None (knock on wood).
+    </para>
+  </chapter>

Documentation/DocBook/genericirq.tmpl

Quoted 10 lines
Documentation/DocBook/genericirq.tmpl new file +9 -0
+
 
+	<sect2>
+	<title>Default flow implementations</title>
+	    <sect3>
+	 	<title>Helper functions</title>
+		<para>
+		The helper functions call the chip primitives and
+		are used by the default flow implementations.
+		Following helper functions are implemented (simplified excerpt):

The following ... (multiple locations)

Documentation/DocBook/genericirq.tmpl line 293

Quoted 5 lines
Documentation/DocBook/genericirq.tmpl new file +5 -0
+	    <sect3>
+	 	<title>Default Edge IRQ flow handler</title>
+		<para>
+		handle_edge_irq provides a generic implementation
+		for edge interrupts.

edge-triggered interrupts. (IMO)

Documentation/DocBook/genericirq.tmpl line 394

Quoted 9 lines
Documentation/DocBook/genericirq.tmpl new file +9 -0
+  <chapter id="doirq">
+     <title>__do_IRQ entry point</title>
+     <para>
+ 	The original implementation __do_IRQ() is an alternative entry
+	point for all types of interrupts.
+     </para>
+     <para>
+	This handler turned out to be not suitable for all
+	interrupt hardware and was therefor reimplemented with split

therefore

Documentation/DocBook/genericirq.tmpl line 396

Quoted 2 lines
Documentation/DocBook/genericirq.tmpl new file +2 -0
+	functionality for egde/level/simple/percpu interrupts. This is not
+	only a functional optimization. It also shortenes code pathes for

shortens code paths

Documentation/DocBook/genericirq.tmpl line 397

Quoted 1 line
Documentation/DocBook/genericirq.tmpl new file +1 -0
+	interrupts.

HTH.
---
~Randy

#2 lore raw
Quoted 3 lines · Randy.Dunlap
Quoted 1 line

Index: linux-genirq.q/Documentation/DocBook/genericirq.tmpl

[tons of fixes]

i've added all of them, they'll be in -V4. Thanks!

Ingo