genirq: doc: add design documentation
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
@@ -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
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
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