Merge tag 'omap-for-v3.13/fixes-for-merge-window-take2' of...

E: dipankar@in.ibm.com

D: RCU

N: Yoshinori Sato

E: ysato@users.sourceforge.jp

D: uClinux for Renesas H8/300 (H8300)

D: http://uclinux-h8.sourceforge.jp/

N: Hannu Savolainen

E: hannu@opensound.com

D: Maintainer of the sound drivers until 2.1.x days.

!Ekernel/printk/printk.c

!Ekernel/panic.c

!Ekernel/sys.c

!Ekernel/rcupdate.c

!Ekernel/rcu/srcu.c

!Ekernel/rcu/tree.c

!Ekernel/rcu/tree_plugin.h

!Ekernel/rcu/update.c

     </sect1>

     <sect1><title>Device Resource Management</title>

  <chapter id="rationale">

    <title>Rationale</title>

	<para>

	The original implementation of interrupt handling in Linux is using

	The original implementation of interrupt handling in Linux uses

	the __do_IRQ() super-handler, which is able to deal with every

	type of interrupt logic.

	</para>

	</itemizedlist>

	</para>

	<para>

	This split implementation of highlevel IRQ handlers allows us to

	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 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.

	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.

	</para>

	<para>

	A more natural abstraction is the clean separation of the

	<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.

	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

	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 is assigned its own highlevel flow

	Each interrupt descriptor is assigned its own high-level flow

	handler, which is normally one of the generic

	implementations. (This highlevel flow handler implementation also

	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.)

	</para>

	<para>

	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

	use a generic IRQ-flow implementation for 'level type' interrupts

	and add a (sub)architecture specific 'edge type' implementation.

	</para>

	<para>

    <para>

	There are three main levels of abstraction in the interrupt code:

	<orderedlist>

	  <listitem><para>Highlevel driver API</para></listitem>

	  <listitem><para>Highlevel IRQ flow handlers</para></listitem>

	  <listitem><para>Chiplevel hardware encapsulation</para></listitem>

	  <listitem><para>High-level driver API</para></listitem>

	  <listitem><para>High-level IRQ flow handlers</para></listitem>

	  <listitem><para>Chip-level hardware encapsulation</para></listitem>

	</orderedlist>

    </para>

    <sect1 id="Interrupt_control_flow">

	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->handle_irq().

	This highlevel IRQ handling function only uses desc->irq_data.chip

	Whenever an interrupt triggers, the low-level architecture code calls

	into the generic interrupt code by calling desc->handle_irq().

	This high-level IRQ handling function only uses desc->irq_data.chip

	primitives referenced by the assigned chip descriptor structure.

	</para>

    </sect1>

    <sect1 id="Highlevel_Driver_API">

	<title>Highlevel Driver API</title>

	<title>High-level Driver API</title>

	<para>

	  The highlevel Driver API consists of following functions:

	  The high-level Driver API consists of following functions:

	  <itemizedlist>

	  <listitem><para>request_irq()</para></listitem>

	  <listitem><para>free_irq()</para></listitem>

	</para>

    </sect1>

    <sect1 id="Highlevel_IRQ_flow_handlers">

	<title>Highlevel IRQ flow handlers</title>

	<title>High-level IRQ flow handlers</title>

	<para>

	  The generic layer provides a set of pre-defined irq-flow methods:

	  <itemizedlist>

	  <listitem><para>handle_edge_eoi_irq</para></listitem>

	  <listitem><para>handle_bad_irq</para></listitem>

	  </itemizedlist>

	  The interrupt flow handlers (either predefined or architecture

	  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.

	</para>

		<para>

		handle_fasteoi_irq provides a generic implementation

		for interrupts, which only need an EOI at the end of

		the handler

		the handler.

		</para>

		<para>

		The following control flow is implemented (simplified excerpt):

	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 highlevel irq-flow handler.

	overriding the high-level irq-flow handler.

	</para>

	</sect2>

	<sect2 id="Delayed_interrupt_disable">

	</sect2>

    </sect1>

    <sect1 id="Chiplevel_hardware_encapsulation">

	<title>Chiplevel hardware encapsulation</title>

	<title>Chip-level hardware encapsulation</title>

	<para>

	The chip level hardware descriptor structure irq_chip

	The chip-level hardware descriptor structure irq_chip

	contains all the direct chip relevant functions, which

	can be utilized by the irq flow implementations.

	  <itemizedlist>

	  <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem>

	  <listitem><para>irq_mask()</para></listitem>

	  <listitem><para>irq_unmask()</para></listitem>

	  <listitem><para>irq_eoi() - Optional, required for eoi flow handlers</para></listitem>

	  <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem>

	  <listitem><para>irq_retrigger() - Optional</para></listitem>

	  <listitem><para>irq_set_type() - Optional</para></listitem>

	  <listitem><para>irq_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.

	handler(s) to use these basic units of low-level functionality.

	</para>

    </sect1>

  </chapter>

     <title>__do_IRQ entry point</title>

     <para>

	The original implementation __do_IRQ() was an alternative entry

	point for all types of interrupts. It not longer exists.

	point for all types of interrupts. It no longer exists.

     </para>

     <para>

	This handler turned out to be not suitable for all

  <chapter id="genericchip">

     <title>Generic interrupt chip</title>

     <para>

       To avoid copies of identical implementations of irq chips the

       To avoid copies of identical implementations of IRQ chips the

       core provides a configurable generic interrupt chip

       implementation. Developers should check carefuly whether the

       generic chip fits their needs before implementing the same

       functionality slightly different themself.

       functionality slightly differently themselves.

     </para>

!Ekernel/irq/generic-chip.c

  </chapter>

	updater uses call_rcu_sched() or synchronize_sched(), then

	the corresponding readers must disable preemption, possibly

	by calling rcu_read_lock_sched() and rcu_read_unlock_sched().

	If the updater uses synchronize_srcu() or call_srcu(),

	the the corresponding readers must use srcu_read_lock() and

	If the updater uses synchronize_srcu() or call_srcu(), then

	the corresponding readers must use srcu_read_lock() and

	srcu_read_unlock(), and with the same srcu_struct.  The rules for

	the expedited primitives are the same as for their non-expedited

	counterparts.  Mixing things up will result in confusion and

	This kernel configuration parameter defines the period of time

	that RCU will wait from the beginning of a grace period until it

	issues an RCU CPU stall warning.  This time period is normally

	sixty seconds.

	21 seconds.

	This configuration parameter may be changed at runtime via the

	/sys/module/rcutree/parameters/rcu_cpu_stall_timeout, however

	this parameter is checked only at the beginning of a cycle.

	So if you are 30 seconds into a 70-second stall, setting this

	So if you are 10 seconds into a 40-second stall, setting this

	sysfs parameter to (say) five will shorten the timeout for the

	-next- stall, or the following warning for the current stall

	(assuming the stall lasts long enough).  It will not affect the

	also dump the stacks of any tasks that are blocking the current

	RCU-preempt grace period.

RCU_CPU_STALL_INFO

CONFIG_RCU_CPU_STALL_INFO

	This kernel configuration parameter causes the stall warning to

	print out additional per-CPU diagnostic information, including

	Although the lockdep facility is extremely useful, it does add

	some overhead.  Therefore, under CONFIG_PROVE_RCU, the

	RCU_STALL_DELAY_DELTA macro allows five extra seconds before

	giving an RCU CPU stall warning message.

	giving an RCU CPU stall warning message.  (This is a cpp

	macro, not a kernel configuration parameter.)

RCU_STALL_RAT_DELAY

	However, if the offending CPU does not detect its own stall in

	the number of jiffies specified by RCU_STALL_RAT_DELAY, then

	some other CPU will complain.  This delay is normally set to

	two jiffies.

	two jiffies.  (This is a cpp macro, not a kernel configuration

	parameter.)

When a CPU detects that it is stalling, it will print a message similar

to the following:

INFO: rcu_bh_state detected stalls on CPUs/tasks: { } (detected by 4, 2502 jiffies)

This is rare, but does happen from time to time in real life.

This is rare, but does happen from time to time in real life.  It is also

possible for a zero-jiffy stall to be flagged in this case, depending

on how the stall warning and the grace-period initialization happen to

interact.  Please note that it is not possible to entirely eliminate this

sort of false positive without resorting to things like stop_machine(),

which is overkill for this sort of problem.

If the CONFIG_RCU_CPU_STALL_INFO kernel configuration parameter is set,

more information is printed with the stall-warning message, for example:

If you can reliably trigger the stall, ftrace can be quite helpful.

RCU bugs can often be debugged with the help of CONFIG_RCU_TRACE

and with RCU's event tracing.

and with RCU's event tracing.  For information on RCU's event tracing,

see include/trace/events/rcu.h.