[PATCH 10/12] irq: add comment about overall design of lost/spurious IRQ handling

[Tejun Heo <tj@kernel.org>]

Give a general overview of the facility at the top of file and add
copyright notice.

Signed-off-by: Tejun Heo <tj@kernel.org>
---
 kernel/irq/spurious.c |   74 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 73 insertions(+), 1 deletions(-)

diff --git a/kernel/irq/spurious.c b/kernel/irq/spurious.c
index 2d92113..329555f 100644
--- a/kernel/irq/spurious.c
+++ b/kernel/irq/spurious.c
@@ -2,8 +2,66 @@
  * linux/kernel/irq/spurious.c
  *
  * Copyright (C) 1992, 1998-2004 Linus Torvalds, Ingo Molnar
+ * Copyright (C) 2010            SUSE Linux Products GmbH
+ * Copyright (C) 2010            Tejun Heo <tj@kernel.org>
  *
- * This file contains spurious interrupt handling.
+ * There are two ways interrupt handling can go wrong - too few or too
+ * many.  Due to misrouting or other issues, sometimes IRQs don't
+ * reach the driver while at other times an interrupt line gets stuck
+ * and a continuous spurious interrupts are generated.
+ *
+ * This file implements workaround for both cases.  Lost interrupts
+ * are handled by IRQ expecting and watching, and spurious interrupts
+ * by spurious polling.  All mechanisms need IRQF_SHARED to be set on
+ * the irqaction in question.
+ *
+ * Both lost interrupt workarounds require cooperation from drivers
+ * and can be chosen depending on how much information the driver can
+ * provide.
+ *
+ * - IRQ expecting
+ *
+ *   IRQ expecting is useful when the driver can tell when IRQs can be
+ *   expected; in other words, when IRQs are used to signal completion
+ *   of host initiated operations.  This is the surest way to work
+ *   around lost interrupts.
+ *
+ *   When the controller is expected to raise an IRQ, the driver
+ *   should call expect_irq() and, when the expected event happens or
+ *   times out, unexpect_irq().  IRQ subsystem polls the interrupt
+ *   inbetween.
+ *
+ *   As interrupts tend to keep working if it works at the beginning,
+ *   IRQ expecting implements "verified state".  After certain number
+ *   of successful IRQ deliveries, the irqaction becomes verified and
+ *   much longer polling interval is used.
+ *
+ * - IRQ watching
+ *
+ *   This can be used when the driver doesn't know when to exactly
+ *   expect and unexpect IRQs.  Once watch_irq() is called, the
+ *   irqaction is slowly polled for certain amount of time (1min).  If
+ *   IRQs are missed during that time, the irqaction is marked and
+ *   actively polled; otherwise, the watching is stopped.
+ *
+ *   In the most basic case, drivers can call this right after
+ *   registering an irqaction to verify IRQ delivery.  In many cases,
+ *   if IRQ works at the beginning, it keeps working, so just calling
+ *   watch_irq() once can provide decent protection against misrouted
+ *   IRQs.  It would also be a good idea to call watch_irq() when
+ *   timeouts are detected.
+ *
+ * - Spurious IRQ handling
+ *
+ *   All IRQs are continuously monitored and spurious IRQ handling
+ *   kicks in if there are too many spurious IRQs.  The IRQ is
+ *   disabled and the registered irqactions are polled.  The IRQ is
+ *   given another shot after certain number IRQs are handled or an
+ *   irqaction is added or removed.
+ *
+ * All of the above three mechanisms can be used together.  Spurious
+ * IRQ handling is enabled by default and drivers are free to expect
+ * and watch IRQs as they see fit.
  */
 
 #include <linux/jiffies.h>
@@ -17,6 +75,20 @@
 
 #include "internals.h"
 
+/*
+ * I spent quite some time thinking about each parameter but they
+ * still are just numbers pulled out of my ass.  If you think your ass
+ * is prettier than mine, please go ahead and suggest better ones.
+ *
+ * Most parameters are intentionally fixed constants and not
+ * adjustable through API.  The nature of IRQ delivery failures isn't
+ * usually dependent on specific drivers and the timing parameters are
+ * more about human perceivable latencies rather than any specific
+ * controller timing details, so figuring out constant values which
+ * can work for most cases shouldn't be too hard.  This allows tighter
+ * control over polling behaviors, eases future changes and makes the
+ * interface easy for drivers.
+ */
 enum {
 	/* irqfixup levels */
 	IRQFIXUP_SPURIOUS		= 0,		/* spurious storm detection */
-- 
1.6.4.2