[PATCH 0/2] Improvements to the genericirq documentation

[PATCH 0/2] Improvements to the genericirq documentation

[Jonathan Corbet]

Initially I started out just getting rid of :c:func: clutter, but then
noticed that request_irq() wasn't documented - I am guessing that got left
behind when request_threaded_irq() came in.  The second patch fixes that up
as well.

Happy to carry this up or let it go through the IRQ tree, whichever is
preferable.

Jonathan Corbet (2):
  docs: remove :c:func: from genericirq.rst
  docs: Add request_irq() documentation

 Documentation/core-api/genericirq.rst | 52 ++++++++++++++-------------
 include/linux/interrupt.h             | 13 +++++++
 2 files changed, 40 insertions(+), 25 deletions(-)

-- 
2.21.0

[PATCH 1/2] docs: remove :c:func: from genericirq.rst

[Jonathan Corbet]

As of 5.3, the automarkup extension will do the right thing with function()
notation, so we don't need to clutter the text with :c:func: invocations.
So remove them.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/genericirq.rst | 50 +++++++++++++--------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
index 4da67b65cecf..2e6c99e3ce3b 100644
--- a/Documentation/core-api/genericirq.rst
+++ b/Documentation/core-api/genericirq.rst
@@ -26,7 +26,7 @@ Rationale
 =========
 
 The original implementation of interrupt handling in Linux uses the
-:c:func:`__do_IRQ` super-handler, which is able to deal with every type of
+__do_IRQ() super-handler, which is able to deal with every type of
 interrupt logic.
 
 Originally, Russell King identified different types of handlers to build
@@ -43,7 +43,7 @@ During the implementation we identified another type:
 
 -  Fast EOI type
 
-In the SMP world of the :c:func:`__do_IRQ` super-handler another type was
+In the SMP world of the __do_IRQ() super-handler another type was
 identified:
 
 -  Per CPU type
@@ -83,7 +83,7 @@ IRQ-flow implementation for 'level type' interrupts and add a
 (sub)architecture specific 'edge type' implementation.
 
 To make the transition to the new model easier and prevent the breakage
-of existing implementations, the :c:func:`__do_IRQ` super-handler is still
+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 be used in more and more architectures, as it
 enables smaller and cleaner IRQ subsystems. It's deprecated for three
@@ -116,7 +116,7 @@ status information and pointers to the interrupt flow method and the
 interrupt chip structure which are assigned to this interrupt.
 
 Whenever an interrupt triggers, the low-level architecture code calls
-into the generic interrupt code by calling :c:func:`desc->handle_irq`. This
+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.
 
@@ -125,27 +125,27 @@ High-level Driver API
 
 The high-level Driver API consists of following functions:
 
--  :c:func:`request_irq`
+-  request_irq()
 
--  :c:func:`free_irq`
+-  free_irq()
 
--  :c:func:`disable_irq`
+-  disable_irq()
 
--  :c:func:`enable_irq`
+-  enable_irq()
 
--  :c:func:`disable_irq_nosync` (SMP only)
+-  disable_irq_nosync() (SMP only)
 
--  :c:func:`synchronize_irq` (SMP only)
+-  synchronize_irq() (SMP only)
 
--  :c:func:`irq_set_irq_type`
+-  irq_set_irq_type()
 
--  :c:func:`irq_set_irq_wake`
+-  irq_set_irq_wake()
 
--  :c:func:`irq_set_handler_data`
+-  irq_set_handler_data()
 
--  :c:func:`irq_set_chip`
+-  irq_set_chip()
 
--  :c:func:`irq_set_chip_data`
+-  irq_set_chip_data()
 
 See the autogenerated function documentation for details.
 
@@ -154,19 +154,19 @@ High-level IRQ flow handlers
 
 The generic layer provides a set of pre-defined irq-flow methods:
 
--  :c:func:`handle_level_irq`
+-  handle_level_irq()
 
--  :c:func:`handle_edge_irq`
+-  handle_edge_irq()
 
--  :c:func:`handle_fasteoi_irq`
+-  handle_fasteoi_irq()
 
--  :c:func:`handle_simple_irq`
+-  handle_simple_irq()
 
--  :c:func:`handle_percpu_irq`
+-  handle_percpu_irq()
 
--  :c:func:`handle_edge_eoi_irq`
+-  handle_edge_eoi_irq()
 
--  :c:func:`handle_bad_irq`
+-  handle_bad_irq()
 
 The interrupt flow handlers (either pre-defined or architecture
 specific) are assigned to specific interrupts by the architecture either
@@ -325,14 +325,14 @@ Delayed interrupt disable
 
 This per interrupt selectable feature, which was introduced by Russell
 King in the ARM interrupt implementation, does not mask an interrupt at
-the hardware level when :c:func:`disable_irq` is called. The interrupt is kept
+the hardware level when disable_irq() is called. The interrupt is kept
 enabled and is masked in the flow handler when an interrupt event
 happens. This prevents losing edge interrupts on hardware which does not
 store an edge interrupt event while the interrupt is disabled at the
 hardware level. When an interrupt arrives while the IRQ_DISABLED flag
 is set, then the interrupt is masked at the hardware level and the
 IRQ_PENDING bit is set. When the interrupt is re-enabled by
-:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt
+enable_irq() the pending bit is checked and if it is set, the interrupt
 is resent either via hardware or by a software resend mechanism. (It's
 necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use
 the delayed interrupt disable feature and your hardware is not capable
@@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality.
 __do_IRQ entry point
 ====================
 
-The original implementation :c:func:`__do_IRQ` was an alternative entry point
+The original implementation __do_IRQ() was an alternative entry point
 for all types of interrupts. It no longer exists.
 
 This handler turned out to be not suitable for all interrupt hardware
-- 
2.21.0

[PATCH 2/2] docs: Add request_irq() documentation

[Jonathan Corbet]

While checking the results of the :c:func: removal, I noticed that there
was no documentation for request_irq(), and request_threaded_irq() was not
mentioned at all.  Add a kerneldoc comment for request_irq() and add
request_threaded_irq() to the list of functions.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 Documentation/core-api/genericirq.rst |  2 ++
 include/linux/interrupt.h             | 13 +++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
index 2e6c99e3ce3b..8f06d885c310 100644
--- a/Documentation/core-api/genericirq.rst
+++ b/Documentation/core-api/genericirq.rst
@@ -127,6 +127,8 @@ The high-level Driver API consists of following functions:
 
 -  request_irq()
 
+-  request_threaded_irq()
+
 -  free_irq()
 
 -  disable_irq()
diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h
index 89fc59dab57d..ba873ec7e09d 100644
--- a/include/linux/interrupt.h
+++ b/include/linux/interrupt.h
@@ -140,6 +140,19 @@ request_threaded_irq(unsigned int irq, irq_handler_t handler,
 		     irq_handler_t thread_fn,
 		     unsigned long flags, const char *name, void *dev);
 
+/**
+ * request_irq - Add a handler for an interrupt line
+ * @irq:	The interrupt line to allocate
+ * @handler:	Function to be called when the IRQ occurs.
+ *		Primary handler for threaded interrupts
+ *		If NULL, the default primary handler is installed
+ * @flags:	Handling flags
+ * @name:	Name of the device generating this interrupt
+ * @dev:	A cookie passed to the handler function
+ *
+ * This call allocates an interrupt and establishes a handler; see
+ * the documentation for request_threaded_irq() for details.
+ */
 static inline int __must_check
 request_irq(unsigned int irq, irq_handler_t handler, unsigned long flags,
 	    const char *name, void *dev)
-- 
2.21.0

Re: [PATCH 1/2] docs: remove :c:func: from genericirq.rst

[Matthew Wilcox]

On Fri, Oct 04, 2019 at 10:39:54AM -0600, Jonathan Corbet wrote:
>  To make the transition to the new model easier and prevent the breakage
> -of existing implementations, the :c:func:`__do_IRQ` super-handler is still
> +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 be used in more and more architectures, as it
>  enables smaller and cleaner IRQ subsystems. It's deprecated for three

...

> @@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality.
>  __do_IRQ entry point
>  ====================
>  
> -The original implementation :c:func:`__do_IRQ` was an alternative entry point
> +The original implementation __do_IRQ() was an alternative entry point
>  for all types of interrupts. It no longer exists.

I think someone needs to rationalise these two paragraphs ;-)

__do_IRQ indeed no longer exists (since 2011).  It should probably be
removed from the documentation too.

Re: [PATCH 2/2] docs: Add request_irq() documentation

[Thomas Gleixner]

On Fri, 4 Oct 2019, Jonathan Corbet wrote:

> While checking the results of the :c:func: removal, I noticed that there
> was no documentation for request_irq(), and request_threaded_irq() was not
> mentioned at all.  Add a kerneldoc comment for request_irq() and add
> request_threaded_irq() to the list of functions.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Thomas Gleixner <tglx@linutronix.de>

Which reminds me that this documentation really needs some thorough
rewrite ...

Re: [PATCH 2/2] docs: Add request_irq() documentation

[Jonathan Corbet]

On Fri, 15 Nov 2019 19:23:29 +0100 (CET)
Thomas Gleixner <tglx@linutronix.de> wrote:

> On Fri, 4 Oct 2019, Jonathan Corbet wrote:
> 
> > While checking the results of the :c:func: removal, I noticed that there
> > was no documentation for request_irq(), and request_threaded_irq() was not
> > mentioned at all.  Add a kerneldoc comment for request_irq() and add
> > request_threaded_irq() to the list of functions.
> > 
> > Signed-off-by: Jonathan Corbet <corbet@lwn.net>  

Heh...I'd forgotten about this one...

> Reviewed-by: Thomas Gleixner <tglx@linutronix.de>

Thanks, I'll go ahead and apply it.

jon