SOURCES (LINUX_2_6): patch-2.6.14-rt1 (NEW) - snap.
pluto
pluto at pld-linux.org
Sun Oct 30 15:41:55 CET 2005
Author: pluto Date: Sun Oct 30 14:41:55 2005 GMT
Module: SOURCES Tag: LINUX_2_6
---- Log message:
- snap.
---- Files affected:
SOURCES:
patch-2.6.14-rt1 (NONE -> 1.1.2.1) (NEW)
---- Diffs:
================================================================
Index: SOURCES/patch-2.6.14-rt1
diff -u /dev/null SOURCES/patch-2.6.14-rt1:1.1.2.1
--- /dev/null Sun Oct 30 15:41:55 2005
+++ SOURCES/patch-2.6.14-rt1 Sun Oct 30 15:41:50 2005
@@ -0,0 +1,56078 @@
+Index: linux/Documentation/DocBook/Makefile
+===================================================================
+--- linux.orig/Documentation/DocBook/Makefile
++++ linux/Documentation/DocBook/Makefile
+@@ -10,7 +10,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mc
+ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
+ procfs-guide.xml writing_usb_driver.xml \
+ sis900.xml kernel-api.xml journal-api.xml lsm.xml usb.xml \
+- gadget.xml libata.xml mtdnand.xml librs.xml
++ gadget.xml libata.xml mtdnand.xml librs.xml genericirq.xml
+
+ ###
+ # The build process is as follows (targets):
+Index: linux/Documentation/DocBook/genericirq.tmpl
+===================================================================
+--- /dev/null
++++ linux/Documentation/DocBook/genericirq.tmpl
+@@ -0,0 +1,560 @@
++<?xml version="1.0" encoding="UTF-8"?>
++<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
++ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
++
++<book id="Generic-IRQ-Guide">
++ <bookinfo>
++ <title>Linux generic IRQ handling</title>
++
++ <authorgroup>
++ <author>
++ <firstname>Thomas</firstname>
++ <surname>Gleixner</surname>
++ <affiliation>
++ <address>
++ <email>tglx at linutronix.de</email>
++ </address>
++ </affiliation>
++ </author>
++ <author>
++ <firstname>Ingo</firstname>
++ <surname>Molnar</surname>
++ <affiliation>
++ <address>
++ <email>mingo at elte.hu</email>
++ </address>
++ </affiliation>
++ </author>
++ </authorgroup>
++
++ <copyright>
++ <year>2005</year>
++ <holder>Thomas Gleixner</holder>
++ </copyright>
++ <copyright>
++ <year>2005</year>
++ <holder>Ingo Molnar</holder>
++ </copyright>
++
++ <legalnotice>
++ <para>
++ This documentation is free software; you can redistribute
++ it and/or modify it under the terms of the GNU General Public
++ License version 2 as published by the Free Software Foundation.
++ </para>
++
++ <para>
++ This program is distributed in the hope that it will be
++ useful, but WITHOUT ANY WARRANTY; without even the implied
++ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
++ See the GNU General Public License for more details.
++ </para>
++
++ <para>
++ You should have received a copy of the GNU General Public
++ License along with this program; if not, write to the Free
++ Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
++ MA 02111-1307 USA
++ </para>
++
++ <para>
++ For more details see the file COPYING in the source
++ distribution of Linux.
++ </para>
++ </legalnotice>
++ </bookinfo>
++
++<toc></toc>
++
++ <chapter id="intro">
++ <title>Introduction</title>
++ <para>
++ The generic interrupt handling layer is designed to provide a
++ complete abstraction of interrupt handling for device drivers
++ and is able to handle all different types of interrupt controller
++ hardware. Device drivers use generic API function to request, enable,
++ disable and free interrupts. The drivers do not have to know anything
++ about interrupt hardware, so they can be used on different hardware
++ platforms without code changes.
++ </para>
++ <para>
++ This documentation is provided for developers who want to implement
++ architecture interrupt support based on the Generic IRQ handling layer.
++ </para>
++ </chapter>
++
++ <chapter id="rationale">
++ <title>Rationale</title>
++ <para>
++ The original implementation of interrupt handling in Linux is using
++ the __do_IRQ() super-handler, which must be able to deal with every
++ type of interrupt logic. This is achieved by an 'interrupt type'
++ structure and runtime flags to handle special cases.
++ Furthermore the superhandler assumed a certain type of interrupt
++ handling hardware and turned out to be not capable of handling all
++ kind of interrupt controller hardware which can be found through
++ the architectures. The all in one approach also adds unnecessary
++ complexity for every user.
++ </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:
++ <itemizedlist>
++ <listitem><para>Level type</para></listitem>
++ <listitem><para>Edge type</para></listitem>
++ <listitem><para>Simple type</para></listitem>
++ </itemizedlist>
++ In the SMP world of the __do_IRQ() super-handler another type
++ was identified:
++ <itemizedlist>
++ <listitem><para>Per CPU type</para></listitem>
++ </itemizedlist>
++ </para>
++ <para>
++ This split implementation of handlers allows to optimize the flow
++ of the interrupt handling for each specific interrupt type.
++ This reduces complexitiy in that particular code path and allows
++ the optimized handling of a given type.
++ </para>
++ <para>
++ The original general implementation uses interrupt_type structures
++ to differentiate the flow control in the super-handler. This
++ leads to a mix of flow logic and code related to hardware details.
++ Russell Kings ARM implementation which replaced the type by a chip
++ abstraction did the mix the other way around.
++ </para>
++ <para>
++ The natural conclusion was a clean seperation of the 'type flow'
++ and the 'chip'. Analysing a couple of architecture implementations
++ reveals that many of them can use a generic set of 'type flow'
++ implementations and only need to add the chip level specific code.
++ The seperation is also valuable for the (sub)architectures,
++ which need specific quirks in the type flow itself, because it
++ provides a more transparent design.
++ </para>
++ <para>
++ Each interrupt type implementation has assigned its own flow
++ handler, which should be normally one of the generic
++ implementations. The flow handler implementation makes it
++ simple to provide demultiplexing handlers which can be found in
++ embedded platforms on various architectures.
++ </para>
++ <para>
++ The seperation makes the generic interrupt handling more flexible
++ and extensible. An (sub)architecture can use a generic type flow
++ implementation for e.g. '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
++ is still available. This leads to a kind of duality for the time
++ being. Over time the new model should achieve a homogeneous
++ implementation scheme over all architectures with enhanced
++ maintainability and cleanliness.
++ </para>
++ </chapter>
++ <chapter id="bugs">
++ <title>Known Bugs And Assumptions</title>
++ <para>
++ None (hopefully).
++ </para>
++ </chapter>
++
++ <chapter id="Abstraction">
++ <title>Abstraction layers</title>
++ <para>
++ There are three main levels of abstraction in the interrupt code:
++ <orderedlist>
++ <listitem><para>Highlevel driver API</para></listitem>
++ <listitem><para>Abstract interrupt type</para></listitem>
++ <listitem><para>Chiplevel hardware encapsulation</para></listitem>
++ </orderedlist>
++ </para>
++ <para>
++ The seperation of interrupt type and chip level functionality
++ provides the most flexible design. This implementation can handle
++ all kinds of interrupt hardware and the necessary workarounds for
++ the interrupt types without the need of redundant implementations.
++ The seperation handles also edge and level type interrupts
++ on the same hardware chip.
++ </para>
++ <sect1>
++ <title>Interrupt control flow</title>
++ <para>
++ Each interrupt is described by an interrupt description structure
++ irq_desc. The interrupt is referenced by an 'unsigned int' numeric
++ value which selects the corresponding interrupt decription structure
++ in the description structures array.
++ The description structure contains status information and pointers
++ to the interrupt type structure and the interrupt chip structure
++ which are assigned to this interrupt.
++ </para>
++ <para>
++ Whenever an interrupt triggers, the lowlevel arch code calls into
++ the generic interrupt code by calling desc->handler->handle_irq().
++ This highlevel IRQ handling function only uses other
++ desc->handler primitives which describe the control flow operation
++ necessary for the interrupt type. These operations are calling
++ the chip primitives referenced by the assigned chip description
++ structure.
++ </para>
++ </sect1>
++ <sect1>
++ <title>Highlevel Driver API</title>
++ <para>
++ The highlevel Driver API consists of following functions:
++ <itemizedlist>
++ <listitem><para>request_irq()</para></listitem>
++ <listitem><para>free_irq()</para></listitem>
++ <listitem><para>disable_irq()</para></listitem>
++ <listitem><para>enable_irq()</para></listitem>
++ <listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
++ <listitem><para>synchronize_irq() (SMP only)</para></listitem>
++ <listitem><para>set_irq_type()</para></listitem>
++ <listitem><para>set_irq_wake()</para></listitem>
++ <listitem><para>set_irq_data()</para></listitem>
++ <listitem><para>set_irq_chip()</para></listitem>
++ <listitem><para>set_irq_chip_data()</para></listitem>
++ </itemizedlist>
++ See the autogenerated function documentation for details.
++ </para>
++ </sect1>
++ <sect1>
++ <title>Abstract interrupt type</title>
++ <para>
++ The 'interrupt type' (struct irq_type) abstraction mainly consists of
++ methods which implement the 'interrupt handling flow'. The generic
++ layer provides a set of pre-defined types:
++ <itemizedlist>
++ <listitem><para>default_level_type</para></listitem>
++ <listitem><para>default_edge_type</para></listitem>
++ <listitem><para>default_simple_type</para></listitem>
++ <listitem><para>default_percpu_type</para></listitem>
++ </itemizedlist>
++ The default type implementations use the generic type handlers.
++ <itemizedlist>
++ <listitem><para>handle_level_type</para></listitem>
++ <listitem><para>handle_edge_type</para></listitem>
++ <listitem><para>handle_simple_type</para></listitem>
++ <listitem><para>handle_percpu_type</para></listitem>
++ </itemizedlist>
++ The interrupt types (either predefined or architecture specific) are
++ assigned to specific interrupts by the architecture either during
++ bootup or during device initialization.
++ </para>
++ <sect2>
++ <title>Default type implementations</title>
++ <sect3>
++ <title>Helper functions</title>
++ <para>
++ The helper functions call the chip primitives and
++ are used by the default type implementations.
++ Following helper functions are implemented (simplified excerpt):
++ <programlisting>
++default_enable(irq)
++{
++ desc->chip->unmask(irq);
++}
++
++default_disable(irq)
++{
++ desc->chip->mask(irq);
++}
++
++default_ack(irq)
++{
++ chip->ack(irq);
++}
++
++default_mask_ack(irq)
++{
++ if (chip->mask_ack) {
++ chip->mask_ack(irq);
++ } else {
++ chip->mask(irq);
++ chip->ack(irq);
++ }
++}
++
++noop(irq)
++{
++}
++
++default_set_type(irq, type)
++{
++ if (desc->chip->set_type) {
++ if (desc->chip->set_type(irq, type))
++ return NULL;
++ }
++
++ return default_handler for type;
++}
++ </programlisting>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default Level IRQ type</title>
++ <para>
++ The default Level IRQ type implements the functions
++ <simplelist type="horiz" columns="2">
++ <member>enable</member><member>default_enable</member>
++ <member>disable</member><member>default_disable</member>
++ <member>start</member><member>default_mask_ack</member>
++ <member>end</member><member>default_enable</member>
++ <member>handle_irq</member><member>handle_level_irq</member>
++ <member>set_type</member><member>default_set_type</member>
++ </simplelist>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default Edge IRQ type</title>
++ <para>
++ The default Edge IRQ type implements the functions
++ <simplelist type="horiz" columns="2">
++ <member>enable</member><member>default_enable</member>
++ <member>disable</member><member>default_disable</member>
++ <member>start</member><member>default_ack</member>
++ <member>hold</member><member>default_mask_ack</member>
++ <member>end</member><member>noop</member>
++ <member>handle_irq</member><member>handle_edge_irq</member>
++ <member>set_type</member><member>default_set_type</member>
++ </simplelist>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default simple IRQ type</title>
++ <para>
++ The default simple IRQ type implements the functions
++ <simplelist type="horiz" columns="2">
++ <member>enable</member><member>noop</member>
++ <member>disable</member><member>noop</member>
++ <member>handle_irq</member><member>handle_simple_irq</member>
++ </simplelist>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default per CPU IRQ type</title>
++ <para>
++ The default per CPU IRQ type implements the functions
++ <simplelist type="horiz" columns="2">
++ <member>enable</member><member>default_enable</member>
++ <member>disable</member><member>default_disable</member>
++ <member>start</member><member>default_ack</member>
++ <member>end</member><member>default_enable</member>
++ <member>handle_irq</member><member>handle_percpu_irq</member>
++ </simplelist>
++ </para>
++ </sect3>
++ </sect2>
++ <sect2>
++ <title>Default type handler implementations</title>
++ <sect3>
++ <title>Default Level IRQ type handler</title>
++ <para>
++ handle_level_type provides a generic implementation
++ for level type interrupts.
++ </para>
++ <para>
++ Following control flow is implemented (simplified excerpt):
++ <programlisting>
++desc->handler->start();
++handle_IRQ_event(desc->action);
++desc->handler->end();
++ </programlisting>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default Edge IRQ type handler</title>
++ <para>
++ handle_edge_type provides a generic implementation
++ for edge type interrupts.
++ </para>
++ <para>
++ Following control flow is implemented (simplified excerpt):
++ <programlisting>
++if (desc->status & running) {
++ desc->handler->hold();
++ desc->status |= pending | masked;
++ return;
++}
++desc->handler->start();
++desc->status |= running;
++do {
++ if (desc->status & masked)
++ desc->handler->enable();
++ desc-status &= ~pending;
++ handle_IRQ_event(desc->action);
++} while (status & pending);
++desc-status &= ~running;
++desc->handler->end();
++ </programlisting>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default simple IRQ type handler</title>
++ <para>
++ handle_simple_type provides a generic implementation
++ for simple type interrupts.
++ </para>
++ <para>
++ Note: The simple type handler does not call any
++ handler/chip primitives.
++ </para>
++ <para>
++ Following control flow is implemented (simplified excerpt):
++ <programlisting>
++handle_IRQ_event(desc->action);
++ </programlisting>
++ </para>
++ </sect3>
++ <sect3>
++ <title>Default per CPU type handler</title>
++ <para>
++ handle_percpu_type provides a generic implementation
++ for per CPU type interrupts.
++ </para>
++ <para>
++ Per CPU interrupts are only available on SMP and
++ the handler provides a simplified version without
++ locking.
++ </para>
++ <para>
++ Following control flow is implemented (simplified excerpt):
++ <programlisting>
++desc->handler->start();
++handle_IRQ_event(desc->action);
++desc->handler->end();
++ </programlisting>
++ </para>
++ </sect3>
++ </sect2>
++ <sect2>
++ <title>Architecture specific type implementation</title>
++ <para>
++ If an architecture needs to implement its own type structures, then
++ the following primitives have to be implemented:
++ <itemizedlist>
++ <listitem><para>handle_irq() - The handle_irq function pointer should preferably point to
++ one of the generic type handler functions</para></listitem>
++ <listitem><para>startup() - Optional</para></listitem>
++ <listitem><para>shutdown() - Optional</para></listitem>
++ <listitem><para>enable()</para></listitem>
++ <listitem><para>disable()</para></listitem>
++ <listitem><para>start()</para></listitem>
++ <listitem><para>hold() - For edge type interupts only</para></listitem>
++ <listitem><para>end()</para></listitem>
++ <listitem><para>set_type - Optional</para></listitem>
++ <listitem><para>set_affinity - SMP only</para></listitem>
++ </itemizedlist>
++ </para>
++ </sect2>
++ <sect2>
++ <title>Quirks and optimizations</title>
++ <para>
++ 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 irqtype. This is also done for compatibility reasons, as
++ most architectures use irqtypes only at the moment.
++ </para>
++ <para>
++ An architecture could implement all of its IRQ logic via pushing
++ chip handling details into the irqtype's ->start()/->end()/->hold()
++ functions. This is only recommended when the underlying primitives
++ are pure chip primitives without additional quirks. The direct pointer
++ to the chip functions reduces the indirection level by one.
++ </para>
++ </sect2>
++ </sect1>
++ <sect1>
++ <title>Chiplevel hardware encapsulation</title>
++ <para>
++ The chip level hardware description structure irq_chip
++ contains all the direct chip relevant functions, which
++ can be utilized by the irq_type implementations.
++ <itemizedlist>
++ <listitem><para>ack()</para></listitem>
++ <listitem><para>mask_ack() - Optional, recommended for performance</para></listitem>
++ <listitem><para>mask()</para></listitem>
++ <listitem><para>unmask()</para></listitem>
++ <listitem><para>retrigger() - Optional</para></listitem>
++ <listitem><para>set_type() - Optional</para></listitem>
++ <listitem><para>set_wake() - Optional</para></listitem>
++ </itemizedlist>
++ 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 lowlevel functionality.
++ </para>
++ </sect1>
++ </chapter>
++
++ <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
++ functionality for egde/level/simple/percpu interrupts. This is not
++ only a functional optimization. It also shortenes code pathes for
++ interrupts.
++ </para>
++ <para>
++ To make use of the split implementation, replace the call to
++ __do_IRQ by a call to desc->handler->handle_irq() and associate
++ the appropriate handler function to desc->handler->handle_irq().
++ In most cases the generic type and handler implementations should
++ be sufficient.
++ </para>
++ </chapter>
++
++ <chapter id="locking">
++ <title>Locking on SMP</title>
++ <para>
++ 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
++ for serialization, but the generic layer does not touch it. The per-irq
++ structure is protected via desc->lock, by the generic layer.
++ </para>
++ </chapter>
++ <chapter id="structs">
++ <title>Structures</title>
++ <para>
++ This chapter contains the autogenerated documentation of the structures which are
++ used in the generic IRQ layer.
++ </para>
++!Iinclude/linux/irq.h
++ </chapter>
++
++ <chapter id="pubfunctions">
++ <title>Public Functions Provided</title>
++ <para>
++ This chapter contains the autogenerated documentation of the kernel API functions
++ which are exported.
++ </para>
++!Ekernel/irq/manage.c
++ </chapter>
++
++ <chapter id="intfunctions">
++ <title>Internal Functions Provided</title>
++ <para>
++ This chapter contains the autogenerated documentation of the internal functions.
++ </para>
++!Ikernel/irq/handle.c
++ </chapter>
++
++ <chapter id="credits">
++ <title>Credits</title>
++ <para>
++ The following people have contributed to this document:
++ <orderedlist>
++ <listitem><para>Thomas Gleixner<email>tglx at linutronix.de</email></para></listitem>
++ <listitem><para>Ingo Molnar<email>mingo at elte.hu</email></para></listitem>
++ </orderedlist>
++ </para>
++ </chapter>
++</book>
+Index: linux/Documentation/DocBook/kernel-api.tmpl
+===================================================================
+--- linux.orig/Documentation/DocBook/kernel-api.tmpl
++++ linux/Documentation/DocBook/kernel-api.tmpl
+@@ -54,6 +54,11 @@
+ !Ekernel/sched.c
+ !Ekernel/timer.c
+ </sect1>
++ <sect1><title>High-precision timers</title>
++!Iinclude/linux/ktime.h
++!Iinclude/linux/ktimer.h
++!Ekernel/ktimers.c
++ </sect1>
<<Diff was trimmed, longer than 597 lines>>
More information about the pld-cvs-commit
mailing list