[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Jani proposed to batch-convert the remaining DocBooks for us
to get rid of it.

Well, I tried ;) 

The conversion itself can easily done, but the problem is that
it hits several errors/warnings when parsing kernel-doc tags.

It ends that it takes some time to fix those.

Also, it seems that the "!I" and "!E" tags at the DocBook
template are not quite right. So, despite being properly
converted to the corresponding kernel-doc tags at ReST, they
didn't produce all that it was needed. I manually fixed a
few, but I guess there are more to be fixed there. Anyway,
this is something that the subsystem maintainers can fix later,
as they understand better what functions they want exported at
the public API documentation, and what functions they want to
hide.

This series converts just two documents, adding them to the
core-api.rst book. It addresses the errors/warnings that popup
after the conversion.

I had to add two fixes to scripts/kernel-doc, in order to solve
some of the issues.

If I have some time during this weekend, I may try to convert
some additional documents to DocBook.


Mauro Carvalho Chehab (9):
  scripts/kernel-doc: fix parser for apostrophes
  scripts/kernel-doc: fix handling of parameters with parenthesis
  genericirq.tmpl: convert it to ReST
  genericirq.rst: add cross-reference links and use monospaced fonts
  kernel-api.tmpl: convert it to ReST
  kernel-api.rst: fix output of the vsnprintf() documentation
  kernel-api.rst: make it handle lib/crc32.c
  kernel-api.rst: fix some complex tags at lib/bitmap.c
  kernel-api.rst: fix a series of errors when parsing C files

 Documentation/DocBook/Makefile        |   4 +-
 Documentation/DocBook/genericirq.tmpl | 520 ----------------------------------
 Documentation/DocBook/kernel-api.tmpl | 331 ----------------------
 Documentation/core-api/genericirq.rst | 440 ++++++++++++++++++++++++++++
 Documentation/core-api/index.rst      |   2 +
 Documentation/core-api/kernel-api.rst | 418 +++++++++++++++++++++++++++
 block/genhd.c                         |   7 +-
 drivers/pci/irq.c                     |   2 +-
 include/linux/clk.h                   |   4 +-
 ipc/util.c                            |  12 +-
 lib/bitmap.c                          |  28 +-
 lib/string.c                          |   2 +-
 lib/vsprintf.c                        |   6 +-
 mm/filemap.c                          |  18 +-
 mm/page_alloc.c                       |   3 +-
 mm/vmalloc.c                          |   2 +-
 scripts/kernel-doc                    |  19 +-
 security/security.c                   |  12 +-
 18 files changed, 932 insertions(+), 898 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst
 create mode 100644 Documentation/core-api/kernel-api.rst

-- 
2.9.3

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Jani proposed to batch-convert the remaining DocBooks for us
to get rid of it.

Well, I tried ;) 

The conversion itself can easily done, but the problem is that
it hits several errors/warnings when parsing kernel-doc tags.

It ends that it takes some time to fix those.

Also, it seems that the "!I" and "!E" tags at the DocBook
template are not quite right. So, despite being properly
converted to the corresponding kernel-doc tags at ReST, they
didn't produce all that it was needed. I manually fixed a
few, but I guess there are more to be fixed there. Anyway,
this is something that the subsystem maintainers can fix later,
as they understand better what functions they want exported at
the public API documentation, and what functions they want to
hide.

This series converts just two documents, adding them to the
core-api.rst book. It addresses the errors/warnings that popup
after the conversion.

I had to add two fixes to scripts/kernel-doc, in order to solve
some of the issues.

If I have some time during this weekend, I may try to convert
some additional documents to DocBook.


Mauro Carvalho Chehab (9):
  scripts/kernel-doc: fix parser for apostrophes
  scripts/kernel-doc: fix handling of parameters with parenthesis
  genericirq.tmpl: convert it to ReST
  genericirq.rst: add cross-reference links and use monospaced fonts
  kernel-api.tmpl: convert it to ReST
  kernel-api.rst: fix output of the vsnprintf() documentation
  kernel-api.rst: make it handle lib/crc32.c
  kernel-api.rst: fix some complex tags at lib/bitmap.c
  kernel-api.rst: fix a series of errors when parsing C files

 Documentation/DocBook/Makefile        |   4 +-
 Documentation/DocBook/genericirq.tmpl | 520 ----------------------------------
 Documentation/DocBook/kernel-api.tmpl | 331 ----------------------
 Documentation/core-api/genericirq.rst | 440 ++++++++++++++++++++++++++++
 Documentation/core-api/index.rst      |   2 +
 Documentation/core-api/kernel-api.rst | 418 +++++++++++++++++++++++++++
 block/genhd.c                         |   7 +-
 drivers/pci/irq.c                     |   2 +-
 include/linux/clk.h                   |   4 +-
 ipc/util.c                            |  12 +-
 lib/bitmap.c                          |  28 +-
 lib/string.c                          |   2 +-
 lib/vsprintf.c                        |   6 +-
 mm/filemap.c                          |  18 +-
 mm/page_alloc.c                       |   3 +-
 mm/vmalloc.c                          |   2 +-
 scripts/kernel-doc                    |  19 +-
 security/security.c                   |  12 +-
 18 files changed, 932 insertions(+), 898 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst
 create mode 100644 Documentation/core-api/kernel-api.rst

-- 
2.9.3


--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Jani proposed to batch-convert the remaining DocBooks for us
to get rid of it.

Well, I tried ;) 

The conversion itself can easily done, but the problem is that
it hits several errors/warnings when parsing kernel-doc tags.

It ends that it takes some time to fix those.

Also, it seems that the "!I" and "!E" tags at the DocBook
template are not quite right. So, despite being properly
converted to the corresponding kernel-doc tags at ReST, they
didn't produce all that it was needed. I manually fixed a
few, but I guess there are more to be fixed there. Anyway,
this is something that the subsystem maintainers can fix later,
as they understand better what functions they want exported at
the public API documentation, and what functions they want to
hide.

This series converts just two documents, adding them to the
core-api.rst book. It addresses the errors/warnings that popup
after the conversion.

I had to add two fixes to scripts/kernel-doc, in order to solve
some of the issues.

If I have some time during this weekend, I may try to convert
some additional documents to DocBook.


Mauro Carvalho Chehab (9):
  scripts/kernel-doc: fix parser for apostrophes
  scripts/kernel-doc: fix handling of parameters with parenthesis
  genericirq.tmpl: convert it to ReST
  genericirq.rst: add cross-reference links and use monospaced fonts
  kernel-api.tmpl: convert it to ReST
  kernel-api.rst: fix output of the vsnprintf() documentation
  kernel-api.rst: make it handle lib/crc32.c
  kernel-api.rst: fix some complex tags at lib/bitmap.c
  kernel-api.rst: fix a series of errors when parsing C files

 Documentation/DocBook/Makefile        |   4 +-
 Documentation/DocBook/genericirq.tmpl | 520 ----------------------------------
 Documentation/DocBook/kernel-api.tmpl | 331 ----------------------
 Documentation/core-api/genericirq.rst | 440 ++++++++++++++++++++++++++++
 Documentation/core-api/index.rst      |   2 +
 Documentation/core-api/kernel-api.rst | 418 +++++++++++++++++++++++++++
 block/genhd.c                         |   7 +-
 drivers/pci/irq.c                     |   2 +-
 include/linux/clk.h                   |   4 +-
 ipc/util.c                            |  12 +-
 lib/bitmap.c                          |  28 +-
 lib/string.c                          |   2 +-
 lib/vsprintf.c                        |   6 +-
 mm/filemap.c                          |  18 +-
 mm/page_alloc.c                       |   3 +-
 mm/vmalloc.c                          |   2 +-
 scripts/kernel-doc                    |  19 +-
 security/security.c                   |  12 +-
 18 files changed, 932 insertions(+), 898 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst
 create mode 100644 Documentation/core-api/kernel-api.rst

-- 
2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/9] scripts/kernel-doc: fix parser for apostrophes

[Mauro Carvalho Chehab]

On ReST, adding a text like ``literal`` is valid. However,
the kernel-doc script won't handle it fine.

We really need this feature, in order to escape things like
%ph, with is found on some C files.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 33c85dfdfce9..a4e5cc3b38e8 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -202,6 +202,7 @@ EOF
 # '&struct_name.member' - name of a structure member
 # '@parameter' - name of a parameter
 # '%CONST' - name of a constant.
+# '``LITERAL``' - literal string without any spaces on it.
 
 ## init lots of data
 
@@ -210,7 +211,8 @@ my $warnings = 0;
 my $anon_struct_union = 0;
 
 # match expressions used to find embedded type information
-my $type_constant = '\%([-_\w]+)';
+my $type_constant = '\b``([^\`]+)``\b';
+my $type_constant2 = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w+(\.\.\.)?)';
 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
@@ -235,6 +237,7 @@ my $type_member_func = $type_member . '\(\)';
 # these work fairly well
 my @highlights_html = (
                        [$type_constant, "<i>\$1</i>"],
+                       [$type_constant2, "<i>\$1</i>"],
                        [$type_func, "<b>\$1</b>"],
                        [$type_enum_xml, "<i>\$1</i>"],
                        [$type_struct_xml, "<i>\$1</i>"],
@@ -252,6 +255,7 @@ my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
 # html version 5
 my @highlights_html5 = (
                         [$type_constant, "<span class=\"const\">\$1</span>"],
+                        [$type_constant2, "<span class=\"const\">\$1</span>"],
                         [$type_func, "<span class=\"func\">\$1</span>"],
                         [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
@@ -268,6 +272,7 @@ my $blankline_html5 = $local_lt . "br /" . $local_gt;
 my @highlights_xml = (
                       ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
                       [$type_constant, "<constant>\$1</constant>"],
+                      [$type_constant2, "<constant>\$1</constant>"],
                       [$type_enum_xml, "<type>\$1</type>"],
                       [$type_struct_xml, "<structname>\$1</structname>"],
                       [$type_typedef_xml, "<type>\$1</type>"],
@@ -283,6 +288,7 @@ my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $loca
 # gnome, docbook format
 my @highlights_gnome = (
                         [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
+                        [$type_constant2, "<replaceable class=\"option\">\$1</replaceable>"],
                         [$type_func, "<function>\$1</function>"],
                         [$type_enum, "<type>\$1</type>"],
                         [$type_struct, "<structname>\$1</structname>"],
@@ -298,6 +304,7 @@ my $blankline_gnome = "</para><para>\n";
 # these are pretty rough
 my @highlights_man = (
                       [$type_constant, "\$1"],
+                      [$type_constant2, "\$1"],
                       [$type_func, "\\\\fB\$1\\\\fP"],
                       [$type_enum, "\\\\fI\$1\\\\fP"],
                       [$type_struct, "\\\\fI\$1\\\\fP"],
@@ -312,6 +319,7 @@ my $blankline_man = "";
 # text-mode
 my @highlights_text = (
                        [$type_constant, "\$1"],
+                       [$type_constant2, "\$1"],
                        [$type_func, "\$1"],
                        [$type_enum, "\$1"],
                        [$type_struct, "\$1"],
@@ -326,6 +334,7 @@ my $blankline_text = "";
 # rst-mode
 my @highlights_rst = (
                        [$type_constant, "``\$1``"],
+                       [$type_constant2, "``\$1``"],
                        # Note: need to escape () to avoid func matching later
                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
@@ -344,6 +353,7 @@ my $blankline_rst = "\n";
 # list mode
 my @highlights_list = (
                        [$type_constant, "\$1"],
+                       [$type_constant2, "\$1"],
                        [$type_func, "\$1"],
                        [$type_enum, "\$1"],
                        [$type_struct, "\$1"],
-- 
2.9.3

[PATCH 2/9] scripts/kernel-doc: fix handling of parameters with parenthesis

[Mauro Carvalho Chehab]

lib/crc32c defines one parameter as:
	const u32 (*tab)[256]

Better handle parenthesis, to avoid those warnings:

./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic'
./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic'

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a4e5cc3b38e8..a26a5f2dce39 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2402,8 +2402,7 @@ sub push_parameter($$$) {
 	}
 
 	$anon_struct_union = 0;
-	my $param_name = $param;
-	$param_name =~ s/\[.*//;
+	$param =~ s/[\[\)].*//;
 
 	if ($type eq "" && $param =~ /\.\.\.$/)
 	{
@@ -2434,9 +2433,9 @@ sub push_parameter($$$) {
 	# but inline preprocessor statements);
 	# also ignore unnamed structs/unions;
 	if (!$anon_struct_union) {
-	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
+	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
 
-	    $parameterdescs{$param_name} = $undescribed;
+	    $parameterdescs{$param} = $undescribed;
 
 	    if (($type eq 'function') || ($type eq 'enum')) {
 		print STDERR "${file}:$.: warning: Function parameter ".
-- 
2.9.3

[PATCH 3/9] genericirq.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt

Copyright information inserted manually.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/DocBook/Makefile        |   2 +-
 Documentation/DocBook/genericirq.tmpl | 520 ----------------------------------
 Documentation/core-api/genericirq.rst | 445 +++++++++++++++++++++++++++++
 Documentation/core-api/index.rst      |   1 +
 4 files changed, 447 insertions(+), 521 deletions(-)
 delete mode 100644 Documentation/DocBook/genericirq.tmpl
 create mode 100644 Documentation/core-api/genericirq.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 7d94db2b53cd..e0c13655f770 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -11,7 +11,7 @@ DOCBOOKS := z8530book.xml  \
 	    networking.xml \
 	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \
-	    genericirq.xml s390-drivers.xml scsi.xml \
+	    s390-drivers.xml scsi.xml \
 	    sh.xml w1.xml
 
 ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl
deleted file mode 100644
index 59fb5c077541..000000000000
--- a/Documentation/DocBook/genericirq.tmpl
+++ /dev/null
@@ -1,520 +0,0 @@
-<?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@linutronix.de</email>
-     </address>
-    </affiliation>
-   </author>
-   <author>
-    <firstname>Ingo</firstname>
-    <surname>Molnar</surname>
-    <affiliation>
-     <address>
-      <email>mingo@elte.hu</email>
-     </address>
-    </affiliation>
-   </author>
-  </authorgroup>
-
-  <copyright>
-   <year>2005-2010</year>
-   <holder>Thomas Gleixner</holder>
-  </copyright>
-  <copyright>
-   <year>2005-2006</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.
-	It is able to handle all the different types of interrupt controller
-	hardware. Device drivers use generic API functions to request, enable,
-	disable and free interrupts. The drivers do not have to know anything
-	about interrupt hardware details, so they can be used on different
-	platforms without code changes.
-    </para>
-    <para>
-  	This documentation is provided to developers who want to implement
-	an interrupt subsystem based for their architecture, with the help
-	of the generic IRQ handling layer.
-    </para>
-  </chapter>
-
-  <chapter id="rationale">
-    <title>Rationale</title>
-	<para>
-	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>
-	<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 distinguished between:
-	<itemizedlist>
-	  <listitem><para>Level type</para></listitem>
-	  <listitem><para>Edge type</para></listitem>
-	  <listitem><para>Simple type</para></listitem>
-	</itemizedlist>
-	During the implementation we identified another type:
-	<itemizedlist>
-	  <listitem><para>Fast EOI 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 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.
-	</para>
-	<para>
-	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 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
-	'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 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
-	design.
-	</para>
-	<para>
-	Each interrupt descriptor is assigned its own high-level flow
-	handler, which is normally one of the generic
-	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
-	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 be used in more and more
-	architectures, as it enables smaller and cleaner IRQ subsystems.
-	It's deprecated for three years now and about to be removed.
-	</para>
-  </chapter>
-  <chapter id="bugs">
-    <title>Known Bugs And Assumptions</title>
-    <para>
-	None (knock on wood).
-    </para>
-  </chapter>
-
-  <chapter id="Abstraction">
-    <title>Abstraction layers</title>
-    <para>
-	There are three main levels of abstraction in the interrupt code:
-	<orderedlist>
-	  <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">
-	<title>Interrupt control flow</title>
-	<para>
-	Each interrupt is described by an interrupt descriptor structure
-	irq_desc. The interrupt is referenced by an 'unsigned int' numeric
-	value which selects the corresponding interrupt description structure
-	in the descriptor structures array.
-	The descriptor structure contains status information and pointers
-	to the interrupt flow method and the interrupt chip structure
-	which are assigned to this interrupt.
-	</para>
-	<para>
-	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>High-level Driver API</title>
-	<para>
-	  The high-level 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>irq_set_irq_type()</para></listitem>
-	  <listitem><para>irq_set_irq_wake()</para></listitem>
-	  <listitem><para>irq_set_handler_data()</para></listitem>
-	  <listitem><para>irq_set_chip()</para></listitem>
-	  <listitem><para>irq_set_chip_data()</para></listitem>
-          </itemizedlist>
-	  See the autogenerated function documentation for details.
-	</para>
-    </sect1>
-    <sect1 id="Highlevel_IRQ_flow_handlers">
-	<title>High-level IRQ flow handlers</title>
-	<para>
-	  The generic layer provides a set of pre-defined irq-flow methods:
-	  <itemizedlist>
-	  <listitem><para>handle_level_irq</para></listitem>
-	  <listitem><para>handle_edge_irq</para></listitem>
-	  <listitem><para>handle_fasteoi_irq</para></listitem>
-	  <listitem><para>handle_simple_irq</para></listitem>
-	  <listitem><para>handle_percpu_irq</para></listitem>
-	  <listitem><para>handle_edge_eoi_irq</para></listitem>
-	  <listitem><para>handle_bad_irq</para></listitem>
-	  </itemizedlist>
-	  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>
-	<sect2 id="Default_flow_implementations">
-	<title>Default flow implementations</title>
-	    <sect3 id="Helper_functions">
-	 	<title>Helper functions</title>
-		<para>
-		The helper functions call the chip primitives and
-		are used by the default flow implementations.
-		The following helper functions are implemented (simplified excerpt):
-		<programlisting>
-default_enable(struct irq_data *data)
-{
-	desc->irq_data.chip->irq_unmask(data);
-}
-
-default_disable(struct irq_data *data)
-{
-	if (!delay_disable(data))
-		desc->irq_data.chip->irq_mask(data);
-}
-
-default_ack(struct irq_data *data)
-{
-	chip->irq_ack(data);
-}
-
-default_mask_ack(struct irq_data *data)
-{
-	if (chip->irq_mask_ack) {
-		chip->irq_mask_ack(data);
-	} else {
-		chip->irq_mask(data);
-		chip->irq_ack(data);
-	}
-}
-
-noop(struct irq_data *data))
-{
-}
-
-		</programlisting>
-	        </para>
-	    </sect3>
-	</sect2>
-	<sect2 id="Default_flow_handler_implementations">
-	<title>Default flow handler implementations</title>
-	    <sect3 id="Default_Level_IRQ_flow_handler">
-	 	<title>Default Level IRQ flow handler</title>
-		<para>
-		handle_level_irq provides a generic implementation
-		for level-triggered interrupts.
-		</para>
-		<para>
-		The following control flow is implemented (simplified excerpt):
-		<programlisting>
-desc->irq_data.chip->irq_mask_ack();
-handle_irq_event(desc->action);
-desc->irq_data.chip->irq_unmask();
-		</programlisting>
-		</para>
-	    </sect3>
-	    <sect3 id="Default_FASTEOI_IRQ_flow_handler">
-		<title>Default Fast EOI IRQ flow handler</title>
-		<para>
-		handle_fasteoi_irq provides a generic implementation
-		for interrupts, which only need an EOI at the end of
-		the handler.
-		</para>
-		<para>
-		The following control flow is implemented (simplified excerpt):
-		<programlisting>
-handle_irq_event(desc->action);
-desc->irq_data.chip->irq_eoi();
-		</programlisting>
-		</para>
-	    </sect3>
-	    <sect3 id="Default_Edge_IRQ_flow_handler">
-	 	<title>Default Edge IRQ flow handler</title>
-		<para>
-		handle_edge_irq provides a generic implementation
-		for edge-triggered interrupts.
-		</para>
-		<para>
-		The following control flow is implemented (simplified excerpt):
-		<programlisting>
-if (desc->status &amp; running) {
-	desc->irq_data.chip->irq_mask_ack();
-	desc->status |= pending | masked;
-	return;
-}
-desc->irq_data.chip->irq_ack();
-desc->status |= running;
-do {
-	if (desc->status &amp; masked)
-		desc->irq_data.chip->irq_unmask();
-	desc->status &amp;= ~pending;
-	handle_irq_event(desc->action);
-} while (status &amp; pending);
-desc->status &amp;= ~running;
-		</programlisting>
-		</para>
-   	    </sect3>
-	    <sect3 id="Default_simple_IRQ_flow_handler">
-	 	<title>Default simple IRQ flow handler</title>
-		<para>
-		handle_simple_irq provides a generic implementation
-		for simple interrupts.
-		</para>
-		<para>
-		Note: The simple flow handler does not call any
-		handler/chip primitives.
-		</para>
-		<para>
-		The following control flow is implemented (simplified excerpt):
-		<programlisting>
-handle_irq_event(desc->action);
-		</programlisting>
-		</para>
-   	    </sect3>
-	    <sect3 id="Default_per_CPU_flow_handler">
-	 	<title>Default per CPU flow handler</title>
-		<para>
-		handle_percpu_irq provides a generic implementation
-		for per CPU interrupts.
-		</para>
-		<para>
-		Per CPU interrupts are only available on SMP and
-		the handler provides a simplified version without
-		locking.
-		</para>
-		<para>
-		The following control flow is implemented (simplified excerpt):
-		<programlisting>
-if (desc->irq_data.chip->irq_ack)
-	desc->irq_data.chip->irq_ack();
-handle_irq_event(desc->action);
-if (desc->irq_data.chip->irq_eoi)
-        desc->irq_data.chip->irq_eoi();
-		</programlisting>
-		</para>
-   	    </sect3>
-	    <sect3 id="EOI_Edge_IRQ_flow_handler">
-	 	<title>EOI Edge IRQ flow handler</title>
-		<para>
-		handle_edge_eoi_irq provides an abnomination of the edge
-		handler which is solely used to tame a badly wreckaged
-		irq controller on powerpc/cell.
-		</para>
-   	    </sect3>
-	    <sect3 id="BAD_IRQ_flow_handler">
-	 	<title>Bad IRQ flow handler</title>
-		<para>
-		handle_bad_irq is used for spurious interrupts which
-		have no real handler assigned..
-		</para>
-   	    </sect3>
-	</sect2>
-	<sect2 id="Quirks_and_optimizations">
-	<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 high-level irq-flow handler.
-	</para>
-	</sect2>
-	<sect2 id="Delayed_interrupt_disable">
-	<title>Delayed interrupt disable</title>
-	<para>
-	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 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
-	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 of retriggering	an interrupt.)
-	The delayed interrupt disable is not configurable.
-	</para>
-	</sect2>
-    </sect1>
-    <sect1 id="Chiplevel_hardware_encapsulation">
-	<title>Chip-level hardware encapsulation</title>
-	<para>
-	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_ack()</para></listitem>
-	  <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_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 low-level functionality.
-	</para>
-    </sect1>
-  </chapter>
-
-  <chapter id="doirq">
-     <title>__do_IRQ entry point</title>
-     <para>
-	The original implementation __do_IRQ() was an alternative entry
-	point for all types of interrupts. It no longer exists.
-     </para>
-     <para>
-	This handler turned out to be not suitable for all
-	interrupt hardware and was therefore reimplemented with split
-	functionality for edge/level/simple/percpu interrupts. This is not
-	only a functional optimization. It also shortens code paths for
-	interrupts.
-      </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. The per-irq structure is
-	protected via desc->lock, by the generic layer.
-     </para>
-  </chapter>
-
-  <chapter id="genericchip">
-     <title>Generic interrupt chip</title>
-     <para>
-       To avoid copies of identical implementations of IRQ chips the
-       core provides a configurable generic interrupt chip
-       implementation. Developers should check carefully whether the
-       generic chip fits their needs before implementing the same
-       functionality slightly differently themselves.
-     </para>
-!Ekernel/irq/generic-chip.c
-  </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
-!Iinclude/linux/interrupt.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
-!Ekernel/irq/chip.c
-  </chapter>
-
-  <chapter id="intfunctions">
-     <title>Internal Functions Provided</title>
-     <para>
-     This chapter contains the autogenerated documentation of the internal functions.
-     </para>
-!Ikernel/irq/irqdesc.c
-!Ikernel/irq/handle.c
-!Ikernel/irq/chip.c
-  </chapter>
-
-  <chapter id="credits">
-     <title>Credits</title>
-	<para>
-		The following people have contributed to this document:
-		<orderedlist>
-			<listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
-			<listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
-		</orderedlist>
-	</para>
-  </chapter>
-</book>
diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
new file mode 100644
index 000000000000..65d023b26864
--- /dev/null
+++ b/Documentation/core-api/genericirq.rst
@@ -0,0 +1,445 @@
+.. include:: <isonum.txt>
+
+==========================
+Linux generic IRQ handling
+==========================
+
+:Copyright: |copy| 2005-2010: Thomas Gleixner
+:Copyright: |copy| 2005-2006:  Ingo Molnar
+
+Introduction
+============
+
+The generic interrupt handling layer is designed to provide a complete
+abstraction of interrupt handling for device drivers. It is able to
+handle all the different types of interrupt controller hardware. Device
+drivers use generic API functions to request, enable, disable and free
+interrupts. The drivers do not have to know anything about interrupt
+hardware details, so they can be used on different platforms without
+code changes.
+
+This documentation is provided to developers who want to implement an
+interrupt subsystem based for their architecture, with the help of the
+generic IRQ handling layer.
+
+Rationale
+=========
+
+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.
+
+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 distinguished between:
+
+-  Level type
+
+-  Edge type
+
+-  Simple type
+
+During the implementation we identified another type:
+
+-  Fast EOI type
+
+In the SMP world of the __do_IRQ() super-handler another type was
+identified:
+
+-  Per CPU type
+
+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 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.
+
+A more natural abstraction is the clean separation of the 'irq flow' and
+the 'chip details'.
+
+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 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 design.
+
+Each interrupt descriptor is assigned its own high-level flow handler,
+which is normally one of the generic 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.)
+
+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 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 __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
+years now and about to be removed.
+
+Known Bugs And Assumptions
+==========================
+
+None (knock on wood).
+
+Abstraction layers
+==================
+
+There are three main levels of abstraction in the interrupt code:
+
+1. High-level driver API
+
+2. High-level IRQ flow handlers
+
+3. Chip-level hardware encapsulation
+
+Interrupt control flow
+----------------------
+
+Each interrupt is described by an interrupt descriptor structure
+irq_desc. The interrupt is referenced by an 'unsigned int' numeric
+value which selects the corresponding interrupt description structure in
+the descriptor structures array. The descriptor structure contains
+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 desc->handle_irq(). This
+high-level IRQ handling function only uses desc->irq_data.chip
+primitives referenced by the assigned chip descriptor structure.
+
+High-level Driver API
+---------------------
+
+The high-level Driver API consists of following functions:
+
+-  request_irq()
+
+-  free_irq()
+
+-  disable_irq()
+
+-  enable_irq()
+
+-  disable_irq_nosync() (SMP only)
+
+-  synchronize_irq() (SMP only)
+
+-  irq_set_irq_type()
+
+-  irq_set_irq_wake()
+
+-  irq_set_handler_data()
+
+-  irq_set_chip()
+
+-  irq_set_chip_data()
+
+See the autogenerated function documentation for details.
+
+High-level IRQ flow handlers
+----------------------------
+
+The generic layer provides a set of pre-defined irq-flow methods:
+
+-  handle_level_irq
+
+-  handle_edge_irq
+
+-  handle_fasteoi_irq
+
+-  handle_simple_irq
+
+-  handle_percpu_irq
+
+-  handle_edge_eoi_irq
+
+-  handle_bad_irq
+
+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.
+
+Default flow implementations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Helper functions
+^^^^^^^^^^^^^^^^
+
+The helper functions call the chip primitives and are used by the
+default flow implementations. The following helper functions are
+implemented (simplified excerpt)::
+
+    default_enable(struct irq_data *data)
+    {
+        desc->irq_data.chip->irq_unmask(data);
+    }
+
+    default_disable(struct irq_data *data)
+    {
+        if (!delay_disable(data))
+            desc->irq_data.chip->irq_mask(data);
+    }
+
+    default_ack(struct irq_data *data)
+    {
+        chip->irq_ack(data);
+    }
+
+    default_mask_ack(struct irq_data *data)
+    {
+        if (chip->irq_mask_ack) {
+            chip->irq_mask_ack(data);
+        } else {
+            chip->irq_mask(data);
+            chip->irq_ack(data);
+        }
+    }
+
+    noop(struct irq_data *data))
+    {
+    }
+
+
+
+Default flow handler implementations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Default Level IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_level_irq provides a generic implementation for level-triggered
+interrupts.
+
+The following control flow is implemented (simplified excerpt)::
+
+    desc->irq_data.chip->irq_mask_ack();
+    handle_irq_event(desc->action);
+    desc->irq_data.chip->irq_unmask();
+
+
+Default Fast EOI IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_fasteoi_irq provides a generic implementation for interrupts,
+which only need an EOI at the end of the handler.
+
+The following control flow is implemented (simplified excerpt)::
+
+    handle_irq_event(desc->action);
+    desc->irq_data.chip->irq_eoi();
+
+
+Default Edge IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_edge_irq provides a generic implementation for edge-triggered
+interrupts.
+
+The following control flow is implemented (simplified excerpt)::
+
+    if (desc->status & running) {
+        desc->irq_data.chip->irq_mask_ack();
+        desc->status |= pending | masked;
+        return;
+    }
+    desc->irq_data.chip->irq_ack();
+    desc->status |= running;
+    do {
+        if (desc->status & masked)
+            desc->irq_data.chip->irq_unmask();
+        desc->status &= ~pending;
+        handle_irq_event(desc->action);
+    } while (status & pending);
+    desc->status &= ~running;
+
+
+Default simple IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_simple_irq provides a generic implementation for simple
+interrupts.
+
+.. note::
+
+   The simple flow handler does not call any handler/chip primitives.
+
+The following control flow is implemented (simplified excerpt)::
+
+    handle_irq_event(desc->action);
+
+
+Default per CPU flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_percpu_irq provides a generic implementation for per CPU
+interrupts.
+
+Per CPU interrupts are only available on SMP and the handler provides a
+simplified version without locking.
+
+The following control flow is implemented (simplified excerpt)::
+
+    if (desc->irq_data.chip->irq_ack)
+        desc->irq_data.chip->irq_ack();
+    handle_irq_event(desc->action);
+    if (desc->irq_data.chip->irq_eoi)
+            desc->irq_data.chip->irq_eoi();
+
+
+EOI Edge IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+handle_edge_eoi_irq provides an abnomination of the edge handler
+which is solely used to tame a badly wreckaged irq controller on
+powerpc/cell.
+
+Bad IRQ flow handler
+^^^^^^^^^^^^^^^^^^^^
+
+handle_bad_irq is used for spurious interrupts which have no real
+handler assigned..
+
+Quirks and optimizations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 high-level irq-flow handler.
+
+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 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
+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
+of retriggering an interrupt.) The delayed interrupt disable is not
+configurable.
+
+Chip-level hardware encapsulation
+---------------------------------
+
+The chip-level hardware descriptor structure irq_chip contains all the
+direct chip relevant functions, which can be utilized by the irq flow
+implementations.
+
+-  irq_ack()
+
+-  irq_mask_ack() - Optional, recommended for performance
+
+-  irq_mask()
+
+-  irq_unmask()
+
+-  irq_eoi() - Optional, required for EOI flow handlers
+
+-  irq_retrigger() - Optional
+
+-  irq_set_type() - Optional
+
+-  irq_set_wake() - Optional
+
+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 low-level functionality.
+
+__do_IRQ 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
+and was therefore reimplemented with split functionality for
+edge/level/simple/percpu interrupts. This is not only a functional
+optimization. It also shortens code paths for interrupts.
+
+Locking on SMP
+==============
+
+The locking of chip registers is up to the architecture that defines the
+chip primitives. The per-irq structure is protected via desc->lock, by
+the generic layer.
+
+Generic interrupt chip
+======================
+
+To avoid copies of identical implementations of IRQ chips the core
+provides a configurable generic interrupt chip implementation.
+Developers should check carefully whether the generic chip fits their
+needs before implementing the same functionality slightly differently
+themselves.
+
+.. kernel-doc:: kernel/irq/generic-chip.c
+   :export:
+
+Structures
+==========
+
+This chapter contains the autogenerated documentation of the structures
+which are used in the generic IRQ layer.
+
+.. kernel-doc:: include/linux/irq.h
+   :internal:
+
+.. kernel-doc:: include/linux/interrupt.h
+   :internal:
+
+Public Functions Provided
+=========================
+
+This chapter contains the autogenerated documentation of the kernel API
+functions which are exported.
+
+.. kernel-doc:: kernel/irq/manage.c
+   :export:
+
+.. kernel-doc:: kernel/irq/chip.c
+   :export:
+
+Internal Functions Provided
+===========================
+
+This chapter contains the autogenerated documentation of the internal
+functions.
+
+.. kernel-doc:: kernel/irq/irqdesc.c
+   :internal:
+
+.. kernel-doc:: kernel/irq/handle.c
+   :internal:
+
+.. kernel-doc:: kernel/irq/chip.c
+   :internal:
+
+Credits
+=======
+
+The following people have contributed to this document:
+
+1. Thomas Gleixner tglx@linutronix.de
+
+2. Ingo Molnar mingo@elte.hu
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 0d93d8089136..c058febbd991 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -16,6 +16,7 @@ Core utilities
    cpu_hotplug
    local_ops
    workqueue
+   genericirq
 
 Interfaces for kernel debugging
 ===============================
-- 
2.9.3

Re: [PATCH 3/9] genericirq.tmpl: convert it to ReST

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

[Reordering things a bit]

> +==========================
> +Linux generic IRQ handling
> +==========================
> +
> +:Copyright: |copy| 2005-2010: Thomas Gleixner
> +:Copyright: |copy| 2005-2006:  Ingo Molnar

It seems maybe they should have been CC'd on this one?  Adding them now
(and leaving the full patch for their amusement).

> Brainless conversion of genericirq.tmpl book to ReST, via
> 	Documentation/sphinx/tmplcvt

In general this seems good, but I have to wonder how current this material
is at this point?  The last substantive change was in 2013 (3.11), and I've
seen a certain amount of IRQ work going by since then.  I'm not opposed to
this move at all, but perhaps if it's outdated we should add a note to that
effect?

Thanks,

jon

> Copyright information inserted manually.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/DocBook/Makefile        |   2 +-
>  Documentation/DocBook/genericirq.tmpl | 520 ----------------------------------
>  Documentation/core-api/genericirq.rst | 445 +++++++++++++++++++++++++++++
>  Documentation/core-api/index.rst      |   1 +
>  4 files changed, 447 insertions(+), 521 deletions(-)
>  delete mode 100644 Documentation/DocBook/genericirq.tmpl
>  create mode 100644 Documentation/core-api/genericirq.rst
> 
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index 7d94db2b53cd..e0c13655f770 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -11,7 +11,7 @@ DOCBOOKS := z8530book.xml  \
>  	    networking.xml \
>  	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
>  	    libata.xml mtdnand.xml librs.xml rapidio.xml \
> -	    genericirq.xml s390-drivers.xml scsi.xml \
> +	    s390-drivers.xml scsi.xml \
>  	    sh.xml w1.xml
>  
>  ifeq ($(DOCBOOKS),)
> diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl
> deleted file mode 100644
> index 59fb5c077541..000000000000
> --- a/Documentation/DocBook/genericirq.tmpl
> +++ /dev/null
> @@ -1,520 +0,0 @@
> -<?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@linutronix.de</email>
> -     </address>
> -    </affiliation>
> -   </author>
> -   <author>
> -    <firstname>Ingo</firstname>
> -    <surname>Molnar</surname>
> -    <affiliation>
> -     <address>
> -      <email>mingo@elte.hu</email>
> -     </address>
> -    </affiliation>
> -   </author>
> -  </authorgroup>
> -
> -  <copyright>
> -   <year>2005-2010</year>
> -   <holder>Thomas Gleixner</holder>
> -  </copyright>
> -  <copyright>
> -   <year>2005-2006</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.
> -	It is able to handle all the different types of interrupt controller
> -	hardware. Device drivers use generic API functions to request, enable,
> -	disable and free interrupts. The drivers do not have to know anything
> -	about interrupt hardware details, so they can be used on different
> -	platforms without code changes.
> -    </para>
> -    <para>
> -  	This documentation is provided to developers who want to implement
> -	an interrupt subsystem based for their architecture, with the help
> -	of the generic IRQ handling layer.
> -    </para>
> -  </chapter>
> -
> -  <chapter id="rationale">
> -    <title>Rationale</title>
> -	<para>
> -	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>
> -	<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 distinguished between:
> -	<itemizedlist>
> -	  <listitem><para>Level type</para></listitem>
> -	  <listitem><para>Edge type</para></listitem>
> -	  <listitem><para>Simple type</para></listitem>
> -	</itemizedlist>
> -	During the implementation we identified another type:
> -	<itemizedlist>
> -	  <listitem><para>Fast EOI 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 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.
> -	</para>
> -	<para>
> -	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 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
> -	'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 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
> -	design.
> -	</para>
> -	<para>
> -	Each interrupt descriptor is assigned its own high-level flow
> -	handler, which is normally one of the generic
> -	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
> -	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 be used in more and more
> -	architectures, as it enables smaller and cleaner IRQ subsystems.
> -	It's deprecated for three years now and about to be removed.
> -	</para>
> -  </chapter>
> -  <chapter id="bugs">
> -    <title>Known Bugs And Assumptions</title>
> -    <para>
> -	None (knock on wood).
> -    </para>
> -  </chapter>
> -
> -  <chapter id="Abstraction">
> -    <title>Abstraction layers</title>
> -    <para>
> -	There are three main levels of abstraction in the interrupt code:
> -	<orderedlist>
> -	  <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">
> -	<title>Interrupt control flow</title>
> -	<para>
> -	Each interrupt is described by an interrupt descriptor structure
> -	irq_desc. The interrupt is referenced by an 'unsigned int' numeric
> -	value which selects the corresponding interrupt description structure
> -	in the descriptor structures array.
> -	The descriptor structure contains status information and pointers
> -	to the interrupt flow method and the interrupt chip structure
> -	which are assigned to this interrupt.
> -	</para>
> -	<para>
> -	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>High-level Driver API</title>
> -	<para>
> -	  The high-level 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>irq_set_irq_type()</para></listitem>
> -	  <listitem><para>irq_set_irq_wake()</para></listitem>
> -	  <listitem><para>irq_set_handler_data()</para></listitem>
> -	  <listitem><para>irq_set_chip()</para></listitem>
> -	  <listitem><para>irq_set_chip_data()</para></listitem>
> -          </itemizedlist>
> -	  See the autogenerated function documentation for details.
> -	</para>
> -    </sect1>
> -    <sect1 id="Highlevel_IRQ_flow_handlers">
> -	<title>High-level IRQ flow handlers</title>
> -	<para>
> -	  The generic layer provides a set of pre-defined irq-flow methods:
> -	  <itemizedlist>
> -	  <listitem><para>handle_level_irq</para></listitem>
> -	  <listitem><para>handle_edge_irq</para></listitem>
> -	  <listitem><para>handle_fasteoi_irq</para></listitem>
> -	  <listitem><para>handle_simple_irq</para></listitem>
> -	  <listitem><para>handle_percpu_irq</para></listitem>
> -	  <listitem><para>handle_edge_eoi_irq</para></listitem>
> -	  <listitem><para>handle_bad_irq</para></listitem>
> -	  </itemizedlist>
> -	  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>
> -	<sect2 id="Default_flow_implementations">
> -	<title>Default flow implementations</title>
> -	    <sect3 id="Helper_functions">
> -	 	<title>Helper functions</title>
> -		<para>
> -		The helper functions call the chip primitives and
> -		are used by the default flow implementations.
> -		The following helper functions are implemented (simplified excerpt):
> -		<programlisting>
> -default_enable(struct irq_data *data)
> -{
> -	desc->irq_data.chip->irq_unmask(data);
> -}
> -
> -default_disable(struct irq_data *data)
> -{
> -	if (!delay_disable(data))
> -		desc->irq_data.chip->irq_mask(data);
> -}
> -
> -default_ack(struct irq_data *data)
> -{
> -	chip->irq_ack(data);
> -}
> -
> -default_mask_ack(struct irq_data *data)
> -{
> -	if (chip->irq_mask_ack) {
> -		chip->irq_mask_ack(data);
> -	} else {
> -		chip->irq_mask(data);
> -		chip->irq_ack(data);
> -	}
> -}
> -
> -noop(struct irq_data *data))
> -{
> -}
> -
> -		</programlisting>
> -	        </para>
> -	    </sect3>
> -	</sect2>
> -	<sect2 id="Default_flow_handler_implementations">
> -	<title>Default flow handler implementations</title>
> -	    <sect3 id="Default_Level_IRQ_flow_handler">
> -	 	<title>Default Level IRQ flow handler</title>
> -		<para>
> -		handle_level_irq provides a generic implementation
> -		for level-triggered interrupts.
> -		</para>
> -		<para>
> -		The following control flow is implemented (simplified excerpt):
> -		<programlisting>
> -desc->irq_data.chip->irq_mask_ack();
> -handle_irq_event(desc->action);
> -desc->irq_data.chip->irq_unmask();
> -		</programlisting>
> -		</para>
> -	    </sect3>
> -	    <sect3 id="Default_FASTEOI_IRQ_flow_handler">
> -		<title>Default Fast EOI IRQ flow handler</title>
> -		<para>
> -		handle_fasteoi_irq provides a generic implementation
> -		for interrupts, which only need an EOI at the end of
> -		the handler.
> -		</para>
> -		<para>
> -		The following control flow is implemented (simplified excerpt):
> -		<programlisting>
> -handle_irq_event(desc->action);
> -desc->irq_data.chip->irq_eoi();
> -		</programlisting>
> -		</para>
> -	    </sect3>
> -	    <sect3 id="Default_Edge_IRQ_flow_handler">
> -	 	<title>Default Edge IRQ flow handler</title>
> -		<para>
> -		handle_edge_irq provides a generic implementation
> -		for edge-triggered interrupts.
> -		</para>
> -		<para>
> -		The following control flow is implemented (simplified excerpt):
> -		<programlisting>
> -if (desc->status &amp; running) {
> -	desc->irq_data.chip->irq_mask_ack();
> -	desc->status |= pending | masked;
> -	return;
> -}
> -desc->irq_data.chip->irq_ack();
> -desc->status |= running;
> -do {
> -	if (desc->status &amp; masked)
> -		desc->irq_data.chip->irq_unmask();
> -	desc->status &amp;= ~pending;
> -	handle_irq_event(desc->action);
> -} while (status &amp; pending);
> -desc->status &amp;= ~running;
> -		</programlisting>
> -		</para>
> -   	    </sect3>
> -	    <sect3 id="Default_simple_IRQ_flow_handler">
> -	 	<title>Default simple IRQ flow handler</title>
> -		<para>
> -		handle_simple_irq provides a generic implementation
> -		for simple interrupts.
> -		</para>
> -		<para>
> -		Note: The simple flow handler does not call any
> -		handler/chip primitives.
> -		</para>
> -		<para>
> -		The following control flow is implemented (simplified excerpt):
> -		<programlisting>
> -handle_irq_event(desc->action);
> -		</programlisting>
> -		</para>
> -   	    </sect3>
> -	    <sect3 id="Default_per_CPU_flow_handler">
> -	 	<title>Default per CPU flow handler</title>
> -		<para>
> -		handle_percpu_irq provides a generic implementation
> -		for per CPU interrupts.
> -		</para>
> -		<para>
> -		Per CPU interrupts are only available on SMP and
> -		the handler provides a simplified version without
> -		locking.
> -		</para>
> -		<para>
> -		The following control flow is implemented (simplified excerpt):
> -		<programlisting>
> -if (desc->irq_data.chip->irq_ack)
> -	desc->irq_data.chip->irq_ack();
> -handle_irq_event(desc->action);
> -if (desc->irq_data.chip->irq_eoi)
> -        desc->irq_data.chip->irq_eoi();
> -		</programlisting>
> -		</para>
> -   	    </sect3>
> -	    <sect3 id="EOI_Edge_IRQ_flow_handler">
> -	 	<title>EOI Edge IRQ flow handler</title>
> -		<para>
> -		handle_edge_eoi_irq provides an abnomination of the edge
> -		handler which is solely used to tame a badly wreckaged
> -		irq controller on powerpc/cell.
> -		</para>
> -   	    </sect3>
> -	    <sect3 id="BAD_IRQ_flow_handler">
> -	 	<title>Bad IRQ flow handler</title>
> -		<para>
> -		handle_bad_irq is used for spurious interrupts which
> -		have no real handler assigned..
> -		</para>
> -   	    </sect3>
> -	</sect2>
> -	<sect2 id="Quirks_and_optimizations">
> -	<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 high-level irq-flow handler.
> -	</para>
> -	</sect2>
> -	<sect2 id="Delayed_interrupt_disable">
> -	<title>Delayed interrupt disable</title>
> -	<para>
> -	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 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
> -	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 of retriggering	an interrupt.)
> -	The delayed interrupt disable is not configurable.
> -	</para>
> -	</sect2>
> -    </sect1>
> -    <sect1 id="Chiplevel_hardware_encapsulation">
> -	<title>Chip-level hardware encapsulation</title>
> -	<para>
> -	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_ack()</para></listitem>
> -	  <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_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 low-level functionality.
> -	</para>
> -    </sect1>
> -  </chapter>
> -
> -  <chapter id="doirq">
> -     <title>__do_IRQ entry point</title>
> -     <para>
> -	The original implementation __do_IRQ() was an alternative entry
> -	point for all types of interrupts. It no longer exists.
> -     </para>
> -     <para>
> -	This handler turned out to be not suitable for all
> -	interrupt hardware and was therefore reimplemented with split
> -	functionality for edge/level/simple/percpu interrupts. This is not
> -	only a functional optimization. It also shortens code paths for
> -	interrupts.
> -      </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. The per-irq structure is
> -	protected via desc->lock, by the generic layer.
> -     </para>
> -  </chapter>
> -
> -  <chapter id="genericchip">
> -     <title>Generic interrupt chip</title>
> -     <para>
> -       To avoid copies of identical implementations of IRQ chips the
> -       core provides a configurable generic interrupt chip
> -       implementation. Developers should check carefully whether the
> -       generic chip fits their needs before implementing the same
> -       functionality slightly differently themselves.
> -     </para>
> -!Ekernel/irq/generic-chip.c
> -  </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
> -!Iinclude/linux/interrupt.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
> -!Ekernel/irq/chip.c
> -  </chapter>
> -
> -  <chapter id="intfunctions">
> -     <title>Internal Functions Provided</title>
> -     <para>
> -     This chapter contains the autogenerated documentation of the internal functions.
> -     </para>
> -!Ikernel/irq/irqdesc.c
> -!Ikernel/irq/handle.c
> -!Ikernel/irq/chip.c
> -  </chapter>
> -
> -  <chapter id="credits">
> -     <title>Credits</title>
> -	<para>
> -		The following people have contributed to this document:
> -		<orderedlist>
> -			<listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
> -			<listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
> -		</orderedlist>
> -	</para>
> -  </chapter>
> -</book>
> diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
> new file mode 100644
> index 000000000000..65d023b26864
> --- /dev/null
> +++ b/Documentation/core-api/genericirq.rst
> @@ -0,0 +1,445 @@
> +.. include:: <isonum.txt>
> +
> +==========================
> +Linux generic IRQ handling
> +==========================
> +
> +:Copyright: |copy| 2005-2010: Thomas Gleixner
> +:Copyright: |copy| 2005-2006:  Ingo Molnar
> +
> +Introduction
> +============
> +
> +The generic interrupt handling layer is designed to provide a complete
> +abstraction of interrupt handling for device drivers. It is able to
> +handle all the different types of interrupt controller hardware. Device
> +drivers use generic API functions to request, enable, disable and free
> +interrupts. The drivers do not have to know anything about interrupt
> +hardware details, so they can be used on different platforms without
> +code changes.
> +
> +This documentation is provided to developers who want to implement an
> +interrupt subsystem based for their architecture, with the help of the
> +generic IRQ handling layer.
> +
> +Rationale
> +=========
> +
> +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.
> +
> +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 distinguished between:
> +
> +-  Level type
> +
> +-  Edge type
> +
> +-  Simple type
> +
> +During the implementation we identified another type:
> +
> +-  Fast EOI type
> +
> +In the SMP world of the __do_IRQ() super-handler another type was
> +identified:
> +
> +-  Per CPU type
> +
> +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 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.
> +
> +A more natural abstraction is the clean separation of the 'irq flow' and
> +the 'chip details'.
> +
> +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 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 design.
> +
> +Each interrupt descriptor is assigned its own high-level flow handler,
> +which is normally one of the generic 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.)
> +
> +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 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 __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
> +years now and about to be removed.
> +
> +Known Bugs And Assumptions
> +==========================
> +
> +None (knock on wood).
> +
> +Abstraction layers
> +==================
> +
> +There are three main levels of abstraction in the interrupt code:
> +
> +1. High-level driver API
> +
> +2. High-level IRQ flow handlers
> +
> +3. Chip-level hardware encapsulation
> +
> +Interrupt control flow
> +----------------------
> +
> +Each interrupt is described by an interrupt descriptor structure
> +irq_desc. The interrupt is referenced by an 'unsigned int' numeric
> +value which selects the corresponding interrupt description structure in
> +the descriptor structures array. The descriptor structure contains
> +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 desc->handle_irq(). This
> +high-level IRQ handling function only uses desc->irq_data.chip
> +primitives referenced by the assigned chip descriptor structure.
> +
> +High-level Driver API
> +---------------------
> +
> +The high-level Driver API consists of following functions:
> +
> +-  request_irq()
> +
> +-  free_irq()
> +
> +-  disable_irq()
> +
> +-  enable_irq()
> +
> +-  disable_irq_nosync() (SMP only)
> +
> +-  synchronize_irq() (SMP only)
> +
> +-  irq_set_irq_type()
> +
> +-  irq_set_irq_wake()
> +
> +-  irq_set_handler_data()
> +
> +-  irq_set_chip()
> +
> +-  irq_set_chip_data()
> +
> +See the autogenerated function documentation for details.
> +
> +High-level IRQ flow handlers
> +----------------------------
> +
> +The generic layer provides a set of pre-defined irq-flow methods:
> +
> +-  handle_level_irq
> +
> +-  handle_edge_irq
> +
> +-  handle_fasteoi_irq
> +
> +-  handle_simple_irq
> +
> +-  handle_percpu_irq
> +
> +-  handle_edge_eoi_irq
> +
> +-  handle_bad_irq
> +
> +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.
> +
> +Default flow implementations
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Helper functions
> +^^^^^^^^^^^^^^^^
> +
> +The helper functions call the chip primitives and are used by the
> +default flow implementations. The following helper functions are
> +implemented (simplified excerpt)::
> +
> +    default_enable(struct irq_data *data)
> +    {
> +        desc->irq_data.chip->irq_unmask(data);
> +    }
> +
> +    default_disable(struct irq_data *data)
> +    {
> +        if (!delay_disable(data))
> +            desc->irq_data.chip->irq_mask(data);
> +    }
> +
> +    default_ack(struct irq_data *data)
> +    {
> +        chip->irq_ack(data);
> +    }
> +
> +    default_mask_ack(struct irq_data *data)
> +    {
> +        if (chip->irq_mask_ack) {
> +            chip->irq_mask_ack(data);
> +        } else {
> +            chip->irq_mask(data);
> +            chip->irq_ack(data);
> +        }
> +    }
> +
> +    noop(struct irq_data *data))
> +    {
> +    }
> +
> +
> +
> +Default flow handler implementations
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Default Level IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_level_irq provides a generic implementation for level-triggered
> +interrupts.
> +
> +The following control flow is implemented (simplified excerpt)::
> +
> +    desc->irq_data.chip->irq_mask_ack();
> +    handle_irq_event(desc->action);
> +    desc->irq_data.chip->irq_unmask();
> +
> +
> +Default Fast EOI IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_fasteoi_irq provides a generic implementation for interrupts,
> +which only need an EOI at the end of the handler.
> +
> +The following control flow is implemented (simplified excerpt)::
> +
> +    handle_irq_event(desc->action);
> +    desc->irq_data.chip->irq_eoi();
> +
> +
> +Default Edge IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_edge_irq provides a generic implementation for edge-triggered
> +interrupts.
> +
> +The following control flow is implemented (simplified excerpt)::
> +
> +    if (desc->status & running) {
> +        desc->irq_data.chip->irq_mask_ack();
> +        desc->status |= pending | masked;
> +        return;
> +    }
> +    desc->irq_data.chip->irq_ack();
> +    desc->status |= running;
> +    do {
> +        if (desc->status & masked)
> +            desc->irq_data.chip->irq_unmask();
> +        desc->status &= ~pending;
> +        handle_irq_event(desc->action);
> +    } while (status & pending);
> +    desc->status &= ~running;
> +
> +
> +Default simple IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_simple_irq provides a generic implementation for simple
> +interrupts.
> +
> +.. note::
> +
> +   The simple flow handler does not call any handler/chip primitives.
> +
> +The following control flow is implemented (simplified excerpt)::
> +
> +    handle_irq_event(desc->action);
> +
> +
> +Default per CPU flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_percpu_irq provides a generic implementation for per CPU
> +interrupts.
> +
> +Per CPU interrupts are only available on SMP and the handler provides a
> +simplified version without locking.
> +
> +The following control flow is implemented (simplified excerpt)::
> +
> +    if (desc->irq_data.chip->irq_ack)
> +        desc->irq_data.chip->irq_ack();
> +    handle_irq_event(desc->action);
> +    if (desc->irq_data.chip->irq_eoi)
> +            desc->irq_data.chip->irq_eoi();
> +
> +
> +EOI Edge IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +handle_edge_eoi_irq provides an abnomination of the edge handler
> +which is solely used to tame a badly wreckaged irq controller on
> +powerpc/cell.
> +
> +Bad IRQ flow handler
> +^^^^^^^^^^^^^^^^^^^^
> +
> +handle_bad_irq is used for spurious interrupts which have no real
> +handler assigned..
> +
> +Quirks and optimizations
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +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 high-level irq-flow handler.
> +
> +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 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
> +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
> +of retriggering an interrupt.) The delayed interrupt disable is not
> +configurable.
> +
> +Chip-level hardware encapsulation
> +---------------------------------
> +
> +The chip-level hardware descriptor structure irq_chip contains all the
> +direct chip relevant functions, which can be utilized by the irq flow
> +implementations.
> +
> +-  irq_ack()
> +
> +-  irq_mask_ack() - Optional, recommended for performance
> +
> +-  irq_mask()
> +
> +-  irq_unmask()
> +
> +-  irq_eoi() - Optional, required for EOI flow handlers
> +
> +-  irq_retrigger() - Optional
> +
> +-  irq_set_type() - Optional
> +
> +-  irq_set_wake() - Optional
> +
> +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 low-level functionality.
> +
> +__do_IRQ 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
> +and was therefore reimplemented with split functionality for
> +edge/level/simple/percpu interrupts. This is not only a functional
> +optimization. It also shortens code paths for interrupts.
> +
> +Locking on SMP
> +==============
> +
> +The locking of chip registers is up to the architecture that defines the
> +chip primitives. The per-irq structure is protected via desc->lock, by
> +the generic layer.
> +
> +Generic interrupt chip
> +======================
> +
> +To avoid copies of identical implementations of IRQ chips the core
> +provides a configurable generic interrupt chip implementation.
> +Developers should check carefully whether the generic chip fits their
> +needs before implementing the same functionality slightly differently
> +themselves.
> +
> +.. kernel-doc:: kernel/irq/generic-chip.c
> +   :export:
> +
> +Structures
> +==========
> +
> +This chapter contains the autogenerated documentation of the structures
> +which are used in the generic IRQ layer.
> +
> +.. kernel-doc:: include/linux/irq.h
> +   :internal:
> +
> +.. kernel-doc:: include/linux/interrupt.h
> +   :internal:
> +
> +Public Functions Provided
> +=========================
> +
> +This chapter contains the autogenerated documentation of the kernel API
> +functions which are exported.
> +
> +.. kernel-doc:: kernel/irq/manage.c
> +   :export:
> +
> +.. kernel-doc:: kernel/irq/chip.c
> +   :export:
> +
> +Internal Functions Provided
> +===========================
> +
> +This chapter contains the autogenerated documentation of the internal
> +functions.
> +
> +.. kernel-doc:: kernel/irq/irqdesc.c
> +   :internal:
> +
> +.. kernel-doc:: kernel/irq/handle.c
> +   :internal:
> +
> +.. kernel-doc:: kernel/irq/chip.c
> +   :internal:
> +
> +Credits
> +=======
> +
> +The following people have contributed to this document:
> +
> +1. Thomas Gleixner tglx@linutronix.de
> +
> +2. Ingo Molnar mingo@elte.hu
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index 0d93d8089136..c058febbd991 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -16,6 +16,7 @@ Core utilities
>     cpu_hotplug
>     local_ops
>     workqueue
> +   genericirq
>  
>  Interfaces for kernel debugging
>  ===============================

Re: [PATCH 3/9] genericirq.tmpl: convert it to ReST

[Thomas Gleixner]

On Fri, 31 Mar 2017, Jonathan Corbet wrote:
> On Thu, 30 Mar 2017 17:11:30 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> [Reordering things a bit]
> 
> > +==========================
> > +Linux generic IRQ handling
> > +==========================
> > +
> > +:Copyright: |copy| 2005-2010: Thomas Gleixner
> > +:Copyright: |copy| 2005-2006:  Ingo Molnar
> 
> It seems maybe they should have been CC'd on this one?  Adding them now
> (and leaving the full patch for their amusement).
> 
> > Brainless conversion of genericirq.tmpl book to ReST, via
> > 	Documentation/sphinx/tmplcvt
> 
> In general this seems good, but I have to wonder how current this material
> is at this point?  The last substantive change was in 2013 (3.11), and I've
> seen a certain amount of IRQ work going by since then.  I'm not opposed to
> this move at all, but perhaps if it's outdated we should add a note to that
> effect?

We should take the opportunity and rewrite it proper. I might have an
intern available in the next couple of weeks, but I need to check with the
folks who are tasked to entertain him :)

Thanks,

	tglx

Re: [PATCH 3/9] genericirq.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Em Fri, 31 Mar 2017 08:57:11 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 30 Mar 2017 17:11:30 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> [Reordering things a bit]
> 
> > +==========================
> > +Linux generic IRQ handling
> > +==========================
> > +
> > +:Copyright: |copy| 2005-2010: Thomas Gleixner
> > +:Copyright: |copy| 2005-2006:  Ingo Molnar  
> 
> It seems maybe they should have been CC'd on this one?  Adding them now
> (and leaving the full patch for their amusement).
> 
> > Brainless conversion of genericirq.tmpl book to ReST, via
> > 	Documentation/sphinx/tmplcvt  
> 
> In general this seems good, but I have to wonder how current this material
> is at this point?  The last substantive change was in 2013 (3.11), and I've
> seen a certain amount of IRQ work going by since then.  I'm not opposed to
> this move at all, but perhaps if it's outdated we should add a note to that
> effect?

Looking on the amount of c:func: references that got solved:
	http://www.infradead.org/~mchehab/kernel_docs/core-api/genericirq.html

I'd say that it doesn't seem outdated.

It mentions a __do_IRQ() function, with I was unable to found, but
I was able to find arch-dependent do_IRQ() functions, with seems to
match the concepts explained at the doc. I almost did a
	s/__do_IRQ/do_IRQ/
but, as I wasn't 100% sure, I opted to keep it as-is for others to touch.

It also mentions a request_irq() function, with is there, just without
kernel-doc markups.

Finally, it includes several core-api files with kernel-doc markups.

So, IMHO, it is worth merging it. Yet, it would be great if the ones
working on that part of the core could review and update it.

Regards,
Mauro

[PATCH 4/9] genericirq.rst: add cross-reference links and use monospaced fonts

[Mauro Carvalho Chehab]

The document describes several functions that are documented
there via kernel doc macros. Add cross-references to them.

In order to be consistend with other documents, use monospaced
fonts for fields.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/core-api/genericirq.rst | 97 +++++++++++++++++------------------
 1 file changed, 46 insertions(+), 51 deletions(-)

diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst
index 65d023b26864..0054bd48be84 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
-__do_IRQ() super-handler, which is able to deal with every type of
+:c:func:`__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 __do_IRQ() super-handler another type was
+In the SMP world of the :c:func:`__do_IRQ` super-handler another type was
 identified:
 
 -  Per CPU type
@@ -54,11 +54,11 @@ 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
+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 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
+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.
 
 A more natural abstraction is the clean separation of the 'irq flow' and
@@ -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 __do_IRQ() super-handler is still
+of existing implementations, the :c:func:`__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 desc->handle_irq(). This
+into the generic interrupt code by calling :c:func:`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:
 
--  request_irq()
+-  :c:func:`request_irq`
 
--  free_irq()
+-  :c:func:`free_irq`
 
--  disable_irq()
+-  :c:func:`disable_irq`
 
--  enable_irq()
+-  :c:func:`enable_irq`
 
--  disable_irq_nosync() (SMP only)
+-  :c:func:`disable_irq_nosync` (SMP only)
 
--  synchronize_irq() (SMP only)
+-  :c:func:`synchronize_irq` (SMP only)
 
--  irq_set_irq_type()
+-  :c:func:`irq_set_irq_type`
 
--  irq_set_irq_wake()
+-  :c:func:`irq_set_irq_wake`
 
--  irq_set_handler_data()
+-  :c:func:`irq_set_handler_data`
 
--  irq_set_chip()
+-  :c:func:`irq_set_chip`
 
--  irq_set_chip_data()
+-  :c:func:`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:
 
--  handle_level_irq
+-  :c:func:`handle_level_irq`
 
--  handle_edge_irq
+-  :c:func:`handle_edge_irq`
 
--  handle_fasteoi_irq
+-  :c:func:`handle_fasteoi_irq`
 
--  handle_simple_irq
+-  :c:func:`handle_simple_irq`
 
--  handle_percpu_irq
+-  :c:func:`handle_percpu_irq`
 
--  handle_edge_eoi_irq
+-  :c:func:`handle_edge_eoi_irq`
 
--  handle_bad_irq
+-  :c:func:`handle_bad_irq`
 
 The interrupt flow handlers (either pre-defined or architecture
 specific) are assigned to specific interrupts by the architecture either
@@ -225,9 +225,9 @@ interrupts.
 
 The following control flow is implemented (simplified excerpt)::
 
-    desc->irq_data.chip->irq_mask_ack();
+    :c:func:`desc->irq_data.chip->irq_mask_ack`;
     handle_irq_event(desc->action);
-    desc->irq_data.chip->irq_unmask();
+    :c:func:`desc->irq_data.chip->irq_unmask`;
 
 
 Default Fast EOI IRQ flow handler
@@ -239,7 +239,7 @@ which only need an EOI at the end of the handler.
 The following control flow is implemented (simplified excerpt)::
 
     handle_irq_event(desc->action);
-    desc->irq_data.chip->irq_eoi();
+    :c:func:`desc->irq_data.chip->irq_eoi`;
 
 
 Default Edge IRQ flow handler
@@ -251,15 +251,15 @@ interrupts.
 The following control flow is implemented (simplified excerpt)::
 
     if (desc->status & running) {
-        desc->irq_data.chip->irq_mask_ack();
+        :c:func:`desc->irq_data.chip->irq_mask_ack`;
         desc->status |= pending | masked;
         return;
     }
-    desc->irq_data.chip->irq_ack();
+    :c:func:`desc->irq_data.chip->irq_ack`;
     desc->status |= running;
     do {
         if (desc->status & masked)
-            desc->irq_data.chip->irq_unmask();
+            :c:func:`desc->irq_data.chip->irq_unmask`;
         desc->status &= ~pending;
         handle_irq_event(desc->action);
     } while (status & pending);
@@ -293,10 +293,10 @@ simplified version without locking.
 The following control flow is implemented (simplified excerpt)::
 
     if (desc->irq_data.chip->irq_ack)
-        desc->irq_data.chip->irq_ack();
+        :c:func:`desc->irq_data.chip->irq_ack`;
     handle_irq_event(desc->action);
     if (desc->irq_data.chip->irq_eoi)
-            desc->irq_data.chip->irq_eoi();
+            :c:func:`desc->irq_data.chip->irq_eoi`;
 
 
 EOI Edge IRQ flow handler
@@ -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 disable_irq() is called. The interrupt is kept
+the hardware level when :c:func:`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
-enable_irq() the pending bit is checked and if it is set, the interrupt
+:c:func:`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
@@ -342,25 +342,25 @@ configurable.
 Chip-level hardware encapsulation
 ---------------------------------
 
-The chip-level hardware descriptor structure irq_chip contains all the
-direct chip relevant functions, which can be utilized by the irq flow
+The chip-level hardware descriptor structure :c:type:`irq_chip` contains all
+the direct chip relevant functions, which can be utilized by the irq flow
 implementations.
 
--  irq_ack()
+-  ``irq_ack``
 
--  irq_mask_ack() - Optional, recommended for performance
+-  ``irq_mask_ack`` - Optional, recommended for performance
 
--  irq_mask()
+-  ``irq_mask``
 
--  irq_unmask()
+-  ``irq_unmask``
 
--  irq_eoi() - Optional, required for EOI flow handlers
+-  ``irq_eoi`` - Optional, required for EOI flow handlers
 
--  irq_retrigger() - Optional
+-  ``irq_retrigger`` - Optional
 
--  irq_set_type() - Optional
+-  ``irq_set_type`` - Optional
 
--  irq_set_wake() - Optional
+-  ``irq_set_wake`` - Optional
 
 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
@@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality.
 __do_IRQ entry point
 ====================
 
-The original implementation __do_IRQ() was an alternative entry point
+The original implementation :c:func:`__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
@@ -415,10 +415,8 @@ This chapter contains the autogenerated documentation of the kernel API
 functions which are exported.
 
 .. kernel-doc:: kernel/irq/manage.c
-   :export:
 
 .. kernel-doc:: kernel/irq/chip.c
-   :export:
 
 Internal Functions Provided
 ===========================
@@ -427,13 +425,10 @@ This chapter contains the autogenerated documentation of the internal
 functions.
 
 .. kernel-doc:: kernel/irq/irqdesc.c
-   :internal:
 
 .. kernel-doc:: kernel/irq/handle.c
-   :internal:
 
 .. kernel-doc:: kernel/irq/chip.c
-   :internal:
 
 Credits
 =======
-- 
2.9.3

[PATCH 5/9] kernel-api.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Brainless conversion of genericirq.tmpl book to ReST, via
	Documentation/sphinx/tmplcvt

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/DocBook/Makefile        |   2 +-
 Documentation/DocBook/kernel-api.tmpl | 331 ---------------------------
 Documentation/core-api/index.rst      |   1 +
 Documentation/core-api/kernel-api.rst | 419 ++++++++++++++++++++++++++++++++++
 4 files changed, 421 insertions(+), 332 deletions(-)
 delete mode 100644 Documentation/DocBook/kernel-api.tmpl
 create mode 100644 Documentation/core-api/kernel-api.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index e0c13655f770..13056d40e11b 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -9,7 +9,7 @@
 DOCBOOKS := z8530book.xml  \
 	    kernel-hacking.xml kernel-locking.xml \
 	    networking.xml \
-	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
+	    filesystems.xml lsm.xml kgdb.xml \
 	    libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    s390-drivers.xml scsi.xml \
 	    sh.xml w1.xml
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
deleted file mode 100644
index ecfd0ea40661..000000000000
--- a/Documentation/DocBook/kernel-api.tmpl
+++ /dev/null
@@ -1,331 +0,0 @@
-<?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="LinuxKernelAPI">
- <bookinfo>
-  <title>The Linux Kernel API</title>
-  
-  <legalnotice>
-   <para>
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License as published by the Free Software Foundation; either
-     version 2 of the License, or (at your option) any later
-     version.
-   </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="adt">
-     <title>Data Types</title>
-     <sect1><title>Doubly Linked Lists</title>
-!Iinclude/linux/list.h
-     </sect1>
-  </chapter>
-
-  <chapter id="libc">
-     <title>Basic C Library Functions</title>
-
-     <para>
-       When writing drivers, you cannot in general use routines which are
-       from the C Library.  Some of the functions have been found generally
-       useful and they are listed below.  The behaviour of these functions
-       may vary slightly from those defined by ANSI, and these deviations
-       are noted in the text.
-     </para>
-
-     <sect1><title>String Conversions</title>
-!Elib/vsprintf.c
-!Finclude/linux/kernel.h kstrtol
-!Finclude/linux/kernel.h kstrtoul
-!Elib/kstrtox.c
-     </sect1>
-     <sect1><title>String Manipulation</title>
-<!-- All functions are exported at now
-X!Ilib/string.c
- -->
-!Elib/string.c
-     </sect1>
-     <sect1><title>Bit Operations</title>
-!Iarch/x86/include/asm/bitops.h
-     </sect1>
-  </chapter>
-
-  <chapter id="kernel-lib">
-     <title>Basic Kernel Library Functions</title>
-
-     <para>
-       The Linux kernel provides more basic utility functions.
-     </para>
-
-     <sect1><title>Bitmap Operations</title>
-!Elib/bitmap.c
-!Ilib/bitmap.c
-     </sect1>
-
-     <sect1><title>Command-line Parsing</title>
-!Elib/cmdline.c
-     </sect1>
-
-     <sect1 id="crc"><title>CRC Functions</title>
-!Elib/crc7.c
-!Elib/crc16.c
-!Elib/crc-itu-t.c
-!Elib/crc32.c
-!Elib/crc-ccitt.c
-     </sect1>
-
-     <sect1 id="idr"><title>idr/ida Functions</title>
-!Pinclude/linux/idr.h idr sync
-!Plib/idr.c IDA description
-!Elib/idr.c
-     </sect1>
-  </chapter>
-
-  <chapter id="mm">
-     <title>Memory Management in Linux</title>
-     <sect1><title>The Slab Cache</title>
-!Iinclude/linux/slab.h
-!Emm/slab.c
-!Emm/util.c
-     </sect1>
-     <sect1><title>User Space Memory Access</title>
-!Iarch/x86/include/asm/uaccess_32.h
-!Earch/x86/lib/usercopy_32.c
-     </sect1>
-     <sect1><title>More Memory Management Functions</title>
-!Emm/readahead.c
-!Emm/filemap.c
-!Emm/memory.c
-!Emm/vmalloc.c
-!Imm/page_alloc.c
-!Emm/mempool.c
-!Emm/dmapool.c
-!Emm/page-writeback.c
-!Emm/truncate.c
-     </sect1>
-  </chapter>
-
-
-  <chapter id="ipc">
-     <title>Kernel IPC facilities</title>
-
-     <sect1><title>IPC utilities</title>
-!Iipc/util.c
-     </sect1>
-  </chapter>
-
-  <chapter id="kfifo">
-     <title>FIFO Buffer</title>
-     <sect1><title>kfifo interface</title>
-!Iinclude/linux/kfifo.h
-     </sect1>
-  </chapter>
-
-  <chapter id="relayfs">
-     <title>relay interface support</title>
-
-     <para>
-	Relay interface support
-	is designed to provide an efficient mechanism for tools and
-	facilities to relay large amounts of data from kernel space to
-	user space.
-     </para>
-
-     <sect1><title>relay interface</title>
-!Ekernel/relay.c
-!Ikernel/relay.c
-     </sect1>
-  </chapter>
-
-  <chapter id="modload">
-     <title>Module Support</title>
-     <sect1><title>Module Loading</title>
-!Ekernel/kmod.c
-     </sect1>
-     <sect1><title>Inter Module support</title>
-        <para>
-           Refer to the file kernel/module.c for more information.
-        </para>
-<!-- FIXME: Removed for now since no structured comments in source
-X!Ekernel/module.c
--->
-     </sect1>
-  </chapter>
-
-  <chapter id="hardware">
-     <title>Hardware Interfaces</title>
-     <sect1><title>Interrupt Handling</title>
-!Ekernel/irq/manage.c
-     </sect1>
-
-     <sect1><title>DMA Channels</title>
-!Ekernel/dma.c
-     </sect1>
-
-     <sect1><title>Resources Management</title>
-!Ikernel/resource.c
-!Ekernel/resource.c
-     </sect1>
-
-     <sect1><title>MTRR Handling</title>
-!Earch/x86/kernel/cpu/mtrr/main.c
-     </sect1>
-
-     <sect1><title>PCI Support Library</title>
-!Edrivers/pci/pci.c
-!Edrivers/pci/pci-driver.c
-!Edrivers/pci/remove.c
-!Edrivers/pci/search.c
-!Edrivers/pci/msi.c
-!Edrivers/pci/bus.c
-!Edrivers/pci/access.c
-!Edrivers/pci/irq.c
-!Edrivers/pci/htirq.c
-<!-- FIXME: Removed for now since no structured comments in source
-X!Edrivers/pci/hotplug.c
--->
-!Edrivers/pci/probe.c
-!Edrivers/pci/slot.c
-!Edrivers/pci/rom.c
-!Edrivers/pci/iov.c
-!Idrivers/pci/pci-sysfs.c
-     </sect1>
-     <sect1><title>PCI Hotplug Support Library</title>
-!Edrivers/pci/hotplug/pci_hotplug_core.c
-     </sect1>
-  </chapter>
-
-  <chapter id="firmware">
-     <title>Firmware Interfaces</title>
-     <sect1><title>DMI Interfaces</title>
-!Edrivers/firmware/dmi_scan.c
-     </sect1>
-     <sect1><title>EDD Interfaces</title>
-!Idrivers/firmware/edd.c
-     </sect1>
-  </chapter>
-
-  <chapter id="security">
-     <title>Security Framework</title>
-!Isecurity/security.c
-!Esecurity/inode.c
-  </chapter>
-
-  <chapter id="audit">
-     <title>Audit Interfaces</title>
-!Ekernel/audit.c
-!Ikernel/auditsc.c
-!Ikernel/auditfilter.c
-  </chapter>
-
-  <chapter id="accounting">
-     <title>Accounting Framework</title>
-!Ikernel/acct.c
-  </chapter>
-
-  <chapter id="blkdev">
-     <title>Block Devices</title>
-!Eblock/blk-core.c
-!Iblock/blk-core.c
-!Eblock/blk-map.c
-!Iblock/blk-sysfs.c
-!Eblock/blk-settings.c
-!Eblock/blk-exec.c
-!Eblock/blk-flush.c
-!Eblock/blk-lib.c
-!Eblock/blk-tag.c
-!Iblock/blk-tag.c
-!Eblock/blk-integrity.c
-!Ikernel/trace/blktrace.c
-!Iblock/genhd.c
-!Eblock/genhd.c
-  </chapter>
-
-  <chapter id="chrdev">
-	<title>Char devices</title>
-!Efs/char_dev.c
-  </chapter>
-
-  <chapter id="miscdev">
-     <title>Miscellaneous Devices</title>
-!Edrivers/char/misc.c
-  </chapter>
-
-  <chapter id="clk">
-     <title>Clock Framework</title>
-
-     <para>
-	The clock framework defines programming interfaces to support
-	software management of the system clock tree.
-	This framework is widely used with System-On-Chip (SOC) platforms
-	to support power management and various devices which may need
-	custom clock rates.
-	Note that these "clocks" don't relate to timekeeping or real
-	time clocks (RTCs), each of which have separate frameworks.
-	These <structname>struct clk</structname> instances may be used
-	to manage for example a 96 MHz signal that is used to shift bits
-	into and out of peripherals or busses, or otherwise trigger
-	synchronous state machine transitions in system hardware.
-     </para>
-
-     <para>
-	Power management is supported by explicit software clock gating:
-	unused clocks are disabled, so the system doesn't waste power
-	changing the state of transistors that aren't in active use.
-	On some systems this may be backed by hardware clock gating,
-	where clocks are gated without being disabled in software.
-	Sections of chips that are powered but not clocked may be able
-	to retain their last state.
-	This low power state is often called a <emphasis>retention
-	mode</emphasis>.
-	This mode still incurs leakage currents, especially with finer
-	circuit geometries, but for CMOS circuits power is mostly used
-	by clocked state changes.
-     </para>
-
-     <para>
-	Power-aware drivers only enable their clocks when the device
-	they manage is in active use.  Also, system sleep states often
-	differ according to which clock domains are active:  while a
-	"standby" state may allow wakeup from several active domains, a
-	"mem" (suspend-to-RAM) state may require a more wholesale shutdown
-	of clocks derived from higher speed PLLs and oscillators, limiting
-	the number of possible wakeup event sources.  A driver's suspend
-	method may need to be aware of system-specific clock constraints
-	on the target sleep state.
-     </para>
-
-     <para>
-        Some platforms support programmable clock generators.  These
-	can be used by external chips of various kinds, such as other
-	CPUs, multimedia codecs, and devices with strict requirements
-	for interface clocking.
-     </para>
-
-!Iinclude/linux/clk.h
-  </chapter>
-
-</book>
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index c058febbd991..da64e2e7ddfd 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -11,6 +11,7 @@ Core utilities
 .. toctree::
    :maxdepth: 1
 
+   kernel-api
    assoc_array
    atomic_ops
    cpu_hotplug
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
new file mode 100644
index 000000000000..e820247e90d3
--- /dev/null
+++ b/Documentation/core-api/kernel-api.rst
@@ -0,0 +1,419 @@
+====================
+The Linux Kernel API
+====================
+
+Data Types
+==========
+
+Doubly Linked Lists
+-------------------
+
+.. kernel-doc:: include/linux/list.h
+   :internal:
+
+Basic C Library Functions
+=========================
+
+When writing drivers, you cannot in general use routines which are from
+the C Library. Some of the functions have been found generally useful
+and they are listed below. The behaviour of these functions may vary
+slightly from those defined by ANSI, and these deviations are noted in
+the text.
+
+String Conversions
+------------------
+
+.. kernel-doc:: lib/vsprintf.c
+   :export:
+
+.. kernel-doc:: include/linux/kernel.h
+   :functions: kstrtol
+
+.. kernel-doc:: include/linux/kernel.h
+   :functions: kstrtoul
+
+.. kernel-doc:: lib/kstrtox.c
+   :export:
+
+String Manipulation
+-------------------
+
+.. kernel-doc:: lib/string.c
+   :export:
+
+Bit Operations
+--------------
+
+.. kernel-doc:: arch/x86/include/asm/bitops.h
+   :internal:
+
+Basic Kernel Library Functions
+==============================
+
+The Linux kernel provides more basic utility functions.
+
+Bitmap Operations
+-----------------
+
+.. kernel-doc:: lib/bitmap.c
+   :export:
+
+.. kernel-doc:: lib/bitmap.c
+   :internal:
+
+Command-line Parsing
+--------------------
+
+.. kernel-doc:: lib/cmdline.c
+   :export:
+
+CRC Functions
+-------------
+
+.. kernel-doc:: lib/crc7.c
+   :export:
+
+.. kernel-doc:: lib/crc16.c
+   :export:
+
+.. kernel-doc:: lib/crc-itu-t.c
+   :export:
+
+.. kernel-doc:: lib/crc32.c
+   :export:
+
+.. kernel-doc:: lib/crc-ccitt.c
+   :export:
+
+idr/ida Functions
+-----------------
+
+.. kernel-doc:: include/linux/idr.h
+   :doc: idr sync
+
+.. kernel-doc:: lib/idr.c
+   :doc: IDA description
+
+.. kernel-doc:: lib/idr.c
+   :export:
+
+Memory Management in Linux
+==========================
+
+The Slab Cache
+--------------
+
+.. kernel-doc:: include/linux/slab.h
+   :internal:
+
+.. kernel-doc:: mm/slab.c
+   :export:
+
+.. kernel-doc:: mm/util.c
+   :export:
+
+User Space Memory Access
+------------------------
+
+.. kernel-doc:: arch/x86/include/asm/uaccess_32.h
+   :internal:
+
+.. kernel-doc:: arch/x86/lib/usercopy_32.c
+   :export:
+
+More Memory Management Functions
+--------------------------------
+
+.. kernel-doc:: mm/readahead.c
+   :export:
+
+.. kernel-doc:: mm/filemap.c
+   :export:
+
+.. kernel-doc:: mm/memory.c
+   :export:
+
+.. kernel-doc:: mm/vmalloc.c
+   :export:
+
+.. kernel-doc:: mm/page_alloc.c
+   :internal:
+
+.. kernel-doc:: mm/mempool.c
+   :export:
+
+.. kernel-doc:: mm/dmapool.c
+   :export:
+
+.. kernel-doc:: mm/page-writeback.c
+   :export:
+
+.. kernel-doc:: mm/truncate.c
+   :export:
+
+Kernel IPC facilities
+=====================
+
+IPC utilities
+-------------
+
+.. kernel-doc:: ipc/util.c
+   :internal:
+
+FIFO Buffer
+===========
+
+kfifo interface
+---------------
+
+.. kernel-doc:: include/linux/kfifo.h
+   :internal:
+
+relay interface support
+=======================
+
+Relay interface support is designed to provide an efficient mechanism
+for tools and facilities to relay large amounts of data from kernel
+space to user space.
+
+relay interface
+---------------
+
+.. kernel-doc:: kernel/relay.c
+   :export:
+
+.. kernel-doc:: kernel/relay.c
+   :internal:
+
+Module Support
+==============
+
+Module Loading
+--------------
+
+.. kernel-doc:: kernel/kmod.c
+   :export:
+
+Inter Module support
+--------------------
+
+Refer to the file kernel/module.c for more information.
+
+Hardware Interfaces
+===================
+
+Interrupt Handling
+------------------
+
+.. kernel-doc:: kernel/irq/manage.c
+   :export:
+
+DMA Channels
+------------
+
+.. kernel-doc:: kernel/dma.c
+   :export:
+
+Resources Management
+--------------------
+
+.. kernel-doc:: kernel/resource.c
+   :internal:
+
+.. kernel-doc:: kernel/resource.c
+   :export:
+
+MTRR Handling
+-------------
+
+.. kernel-doc:: arch/x86/kernel/cpu/mtrr/main.c
+   :export:
+
+PCI Support Library
+-------------------
+
+.. kernel-doc:: drivers/pci/pci.c
+   :export:
+
+.. kernel-doc:: drivers/pci/pci-driver.c
+   :export:
+
+.. kernel-doc:: drivers/pci/remove.c
+   :export:
+
+.. kernel-doc:: drivers/pci/search.c
+   :export:
+
+.. kernel-doc:: drivers/pci/msi.c
+   :export:
+
+.. kernel-doc:: drivers/pci/bus.c
+   :export:
+
+.. kernel-doc:: drivers/pci/access.c
+   :export:
+
+.. kernel-doc:: drivers/pci/irq.c
+   :export:
+
+.. kernel-doc:: drivers/pci/htirq.c
+   :export:
+
+.. kernel-doc:: drivers/pci/probe.c
+   :export:
+
+.. kernel-doc:: drivers/pci/slot.c
+   :export:
+
+.. kernel-doc:: drivers/pci/rom.c
+   :export:
+
+.. kernel-doc:: drivers/pci/iov.c
+   :export:
+
+.. kernel-doc:: drivers/pci/pci-sysfs.c
+   :internal:
+
+PCI Hotplug Support Library
+---------------------------
+
+.. kernel-doc:: drivers/pci/hotplug/pci_hotplug_core.c
+   :export:
+
+Firmware Interfaces
+===================
+
+DMI Interfaces
+--------------
+
+.. kernel-doc:: drivers/firmware/dmi_scan.c
+   :export:
+
+EDD Interfaces
+--------------
+
+.. kernel-doc:: drivers/firmware/edd.c
+   :internal:
+
+Security Framework
+==================
+
+.. kernel-doc:: security/security.c
+   :internal:
+
+.. kernel-doc:: security/inode.c
+   :export:
+
+Audit Interfaces
+================
+
+.. kernel-doc:: kernel/audit.c
+   :export:
+
+.. kernel-doc:: kernel/auditsc.c
+   :internal:
+
+.. kernel-doc:: kernel/auditfilter.c
+   :internal:
+
+Accounting Framework
+====================
+
+.. kernel-doc:: kernel/acct.c
+   :internal:
+
+Block Devices
+=============
+
+.. kernel-doc:: block/blk-core.c
+   :export:
+
+.. kernel-doc:: block/blk-core.c
+   :internal:
+
+.. kernel-doc:: block/blk-map.c
+   :export:
+
+.. kernel-doc:: block/blk-sysfs.c
+   :internal:
+
+.. kernel-doc:: block/blk-settings.c
+   :export:
+
+.. kernel-doc:: block/blk-exec.c
+   :export:
+
+.. kernel-doc:: block/blk-flush.c
+   :export:
+
+.. kernel-doc:: block/blk-lib.c
+   :export:
+
+.. kernel-doc:: block/blk-tag.c
+   :export:
+
+.. kernel-doc:: block/blk-tag.c
+   :internal:
+
+.. kernel-doc:: block/blk-integrity.c
+   :export:
+
+.. kernel-doc:: kernel/trace/blktrace.c
+   :internal:
+
+.. kernel-doc:: block/genhd.c
+   :internal:
+
+.. kernel-doc:: block/genhd.c
+   :export:
+
+Char devices
+============
+
+.. kernel-doc:: fs/char_dev.c
+   :export:
+
+Miscellaneous Devices
+=====================
+
+.. kernel-doc:: drivers/char/misc.c
+   :export:
+
+Clock Framework
+===============
+
+The clock framework defines programming interfaces to support software
+management of the system clock tree. This framework is widely used with
+System-On-Chip (SOC) platforms to support power management and various
+devices which may need custom clock rates. Note that these "clocks"
+don't relate to timekeeping or real time clocks (RTCs), each of which
+have separate frameworks. These :c:type:`struct clk <clk>`
+instances may be used to manage for example a 96 MHz signal that is used
+to shift bits into and out of peripherals or busses, or otherwise
+trigger synchronous state machine transitions in system hardware.
+
+Power management is supported by explicit software clock gating: unused
+clocks are disabled, so the system doesn't waste power changing the
+state of transistors that aren't in active use. On some systems this may
+be backed by hardware clock gating, where clocks are gated without being
+disabled in software. Sections of chips that are powered but not clocked
+may be able to retain their last state. This low power state is often
+called a *retention mode*. This mode still incurs leakage currents,
+especially with finer circuit geometries, but for CMOS circuits power is
+mostly used by clocked state changes.
+
+Power-aware drivers only enable their clocks when the device they manage
+is in active use. Also, system sleep states often differ according to
+which clock domains are active: while a "standby" state may allow wakeup
+from several active domains, a "mem" (suspend-to-RAM) state may require
+a more wholesale shutdown of clocks derived from higher speed PLLs and
+oscillators, limiting the number of possible wakeup event sources. A
+driver's suspend method may need to be aware of system-specific clock
+constraints on the target sleep state.
+
+Some platforms support programmable clock generators. These can be used
+by external chips of various kinds, such as other CPUs, multimedia
+codecs, and devices with strict requirements for interface clocking.
+
+.. kernel-doc:: include/linux/clk.h
+   :internal:
-- 
2.9.3

Re: [PATCH 5/9] kernel-api.tmpl: convert it to ReST

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:32 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> Brainless conversion of genericirq.tmpl book to ReST, via
> 	Documentation/sphinx/tmplcvt

This one kind of showcases why I'm nervous about bulk conversions.  It's
a bit of a dumping-ground document, with a bit of everything, and I think
we can do better.  And, in particular, this one contains a bunch of stuff
that belongs in the driver-api manual instead.  So, at a minimum, I would
really like to see this template split across those two manuals.

If you promise me a followup patch doing that, maybe I can go ahead and
merge this series now :)

(That's mildly complicated by the fact that you didn't send me parts 6,
8, and 9; I really would rather get the whole series in cases like this.)

Thanks,

jon

Re: [PATCH 5/9] kernel-api.tmpl: convert it to ReST

[Mauro Carvalho Chehab]

Em Fri, 31 Mar 2017 09:05:37 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 30 Mar 2017 17:11:32 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > Brainless conversion of genericirq.tmpl book to ReST, via
> > 	Documentation/sphinx/tmplcvt  
> 
> This one kind of showcases why I'm nervous about bulk conversions.  It's
> a bit of a dumping-ground document, with a bit of everything, and I think
> we can do better.  And, in particular, this one contains a bunch of stuff
> that belongs in the driver-api manual instead.  So, at a minimum, I would
> really like to see this template split across those two manuals.

Yeah, I was in doubt if it should be either at driver-api or core-api
manuals.

> If you promise me a followup patch doing that, maybe I can go ahead and
> merge this series now :)

Surely I can do a patch moving things around.

> (That's mildly complicated by the fact that you didn't send me parts 6,
> 8, and 9; I really would rather get the whole series in cases like this.)

Sorry. Just forwarded those missing parts to your e-mail.

They basically fix some kernel-doc headers that are not properly
parsed by Sphinx.

Thanks,
Mauro

[PATCH 6/9] kernel-api.rst: fix output of the vsnprintf() documentation

[Mauro Carvalho Chehab]

The vsnprintf() kernel-doc comment uses % character with a special
meaning other than escaping a constant. As ReST already defines
``literal`` as an escape sequence, let's make kernel-doc handle it,
and use it at lib/vsprintf.c.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 lib/vsprintf.c | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/vsprintf.c b/lib/vsprintf.c
index e3bf4e0f10b5..176641cc549d 100644
--- a/lib/vsprintf.c
+++ b/lib/vsprintf.c
@@ -1954,13 +1954,13 @@ set_precision(struct printf_spec *spec, int prec)
  * This function generally follows C99 vsnprintf, but has some
  * extensions and a few limitations:
  *
- * %n is unsupported
- * %p* is handled by pointer()
+ *  - ``%n`` is unsupported
+ *  - ``%p*`` is handled by pointer()
  *
  * See pointer() or Documentation/printk-formats.txt for more
  * extensive description.
  *
- * ** Please update the documentation in both places when making changes **
+ * **Please update the documentation in both places when making changes**
  *
  * The return value is the number of characters which would
  * be generated for the given input, excluding the trailing
-- 
2.9.3

[PATCH 7/9] kernel-api.rst: make it handle lib/crc32.c

[Mauro Carvalho Chehab]

This file has only "internal" functions:
	./lib/crc32.c:1: warning: no structured comments found

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/core-api/kernel-api.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index e820247e90d3..9a3d3597a6b7 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -80,7 +80,6 @@ CRC Functions
    :export:
 
 .. kernel-doc:: lib/crc32.c
-   :export:
 
 .. kernel-doc:: lib/crc-ccitt.c
    :export:
-- 
2.9.3

[PATCH 8/9] kernel-api.rst: fix some complex tags at lib/bitmap.c

[Mauro Carvalho Chehab]

Fix the following issues:

./lib/bitmap.c:869: WARNING: Definition list ends without a blank line; unexpected unindent.
./lib/bitmap.c:876: WARNING: Inline emphasis start-string without end-string.
./lib/bitmap.c:508: ERROR: Unexpected indentation.

And make sure that a table and a footnote will use the right tags.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 lib/bitmap.c | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/lib/bitmap.c b/lib/bitmap.c
index 0b66f0e5eb6b..08c6ef3a2b6f 100644
--- a/lib/bitmap.c
+++ b/lib/bitmap.c
@@ -502,11 +502,11 @@ EXPORT_SYMBOL(bitmap_print_to_pagebuf);
  * Syntax: range:used_size/group_size
  * Example: 0-1023:2/256 ==> 0,1,256,257,512,513,768,769
  *
- * Returns 0 on success, -errno on invalid input strings.
- * Error values:
- *    %-EINVAL: second number in range smaller than first
- *    %-EINVAL: invalid character in string
- *    %-ERANGE: bit number specified too large for mask
+ * Returns: 0 on success, -errno on invalid input strings. Error values:
+ *
+ *   - ``-EINVAL``: second number in range smaller than first
+ *   - ``-EINVAL``: invalid character in string
+ *   - ``-ERANGE``: bit number specified too large for mask
  */
 static int __bitmap_parselist(const char *buf, unsigned int buflen,
 		int is_user, unsigned long *maskp,
@@ -864,14 +864,16 @@ EXPORT_SYMBOL(bitmap_bitremap);
  *  11 was set in @orig had no affect on @dst.
  *
  * Example [2] for bitmap_fold() + bitmap_onto():
- *  Let's say @relmap has these ten bits set:
+ *  Let's say @relmap has these ten bits set::
+ *
  *		40 41 42 43 45 48 53 61 74 95
+ *
  *  (for the curious, that's 40 plus the first ten terms of the
  *  Fibonacci sequence.)
  *
  *  Further lets say we use the following code, invoking
  *  bitmap_fold() then bitmap_onto, as suggested above to
- *  avoid the possibility of an empty @dst result:
+ *  avoid the possibility of an empty @dst result::
  *
  *	unsigned long *tmp;	// a temporary bitmap's bits
  *
@@ -882,22 +884,26 @@ EXPORT_SYMBOL(bitmap_bitremap);
  *  various @orig's.  I list the zero-based positions of each set bit.
  *  The tmp column shows the intermediate result, as computed by
  *  using bitmap_fold() to fold the @orig bitmap modulo ten
- *  (the weight of @relmap).
+ *  (the weight of @relmap):
  *
+ *      =============== ============== =================
  *      @orig           tmp            @dst
  *      0                0             40
  *      1                1             41
  *      9                9             95
- *      10               0             40 (*)
+ *      10               0             40 [#f1]_
  *      1 3 5 7          1 3 5 7       41 43 48 61
  *      0 1 2 3 4        0 1 2 3 4     40 41 42 43 45
  *      0 9 18 27        0 9 8 7       40 61 74 95
  *      0 10 20 30       0             40
  *      0 11 22 33       0 1 2 3       40 41 42 43
  *      0 12 24 36       0 2 4 6       40 42 45 53
- *      78 102 211       1 2 8         41 42 74 (*)
+ *      78 102 211       1 2 8         41 42 74 [#f1]_
+ *      =============== ============== =================
  *
- * (*) For these marked lines, if we hadn't first done bitmap_fold()
+ * .. [#f1]
+ *
+ *     For these marked lines, if we hadn't first done bitmap_fold()
  *     into tmp, then the @dst result would have been empty.
  *
  * If either of @orig or @relmap is empty (no set bits), then @dst
-- 
2.9.3

[PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Mauro Carvalho Chehab]

./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/filemap.c:1283: ERROR: Unexpected indentation.
./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
./ipc/util.c:676: ERROR: Unexpected indentation.
./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
./security/security.c:109: ERROR: Unexpected indentation.
./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./ipc/util.c:477: ERROR: Unknown target name: "s".

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 block/genhd.c       |  7 ++++---
 drivers/pci/irq.c   |  2 +-
 include/linux/clk.h |  4 ++--
 ipc/util.c          | 12 +++++++-----
 lib/string.c        |  2 +-
 mm/filemap.c        | 18 ++++++++++--------
 mm/page_alloc.c     |  3 ++-
 mm/vmalloc.c        |  2 +-
 security/security.c | 12 ++++++++----
 9 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/block/genhd.c b/block/genhd.c
index b26a5ea115d0..a53bfd19a0ec 100644
--- a/block/genhd.c
+++ b/block/genhd.c
@@ -271,16 +271,17 @@ void blkdev_show(struct seq_file *seqf, off_t offset)
 /**
  * register_blkdev - register a new block device
  *
- * @major: the requested major device number [1..255]. If @major=0, try to
+ * @major: the requested major device number [1..255]. If @major = 0, try to
  *         allocate any unused major number.
  * @name: the name of the new block device as a zero terminated string
  *
  * The @name must be unique within the system.
  *
- * The return value depends on the @major input parameter.
+ * The return value depends on the @major input parameter:
+ *
  *  - if a major device number was requested in range [1..255] then the
  *    function returns zero on success, or a negative error code
- *  - if any unused major number was requested with @major=0 parameter
+ *  - if any unused major number was requested with @major = 0 parameter
  *    then the return value is the allocated major number in range
  *    [1..255] or a negative error code otherwise
  */
diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
index 6684f153ab57..f9f2a0324ecc 100644
--- a/drivers/pci/irq.c
+++ b/drivers/pci/irq.c
@@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
  * driver).
  *
  * Returns:
- *  a suggestion for fixing it (although the driver is not required to
+ * a suggestion for fixing it (although the driver is not required to
  * act on this).
  */
 enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
diff --git a/include/linux/clk.h b/include/linux/clk.h
index e9d36b3e49de..024cd07870d0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -132,8 +132,8 @@ int clk_get_phase(struct clk *clk);
  * @q: clk compared against p
  *
  * Returns true if the two struct clk pointers both point to the same hardware
- * clock node. Put differently, returns true if struct clk *p and struct clk *q
- * share the same struct clk_core object.
+ * clock node. Put differently, returns true if @p and @q
+ * share the same &struct clk_core object.
  *
  * Returns false otherwise. Note that two NULL clks are treated as matching.
  */
diff --git a/ipc/util.c b/ipc/util.c
index 798cad18dd87..3459a16a9df9 100644
--- a/ipc/util.c
+++ b/ipc/util.c
@@ -474,7 +474,7 @@ void ipc_rcu_free(struct rcu_head *head)
  * Check user, group, other permissions for access
  * to ipc resources. return 0 if allowed
  *
- * @flag will most probably be 0 or S_...UGO from <linux/stat.h>
+ * @flag will most probably be 0 or ``S_...UGO`` from <linux/stat.h>
  */
 int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 {
@@ -672,10 +672,12 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
  *
  * This function does some common audit and permissions check for some IPC_XXX
  * cmd and is called from semctl_down, shmctl_down and msgctl_down.
- * It must be called without any lock held and
- *  - retrieves the ipc with the given id in the given table.
- *  - performs some audit and permission check, depending on the given cmd
- *  - returns a pointer to the ipc object or otherwise, the corresponding error.
+ * It must be called without any lock held and:
+ *
+ *   - retrieves the ipc with the given id in the given table.
+ *   - performs some audit and permission check, depending on the given cmd
+ *   - returns a pointer to the ipc object or otherwise, the corresponding
+ *     error.
  *
  * Call holding the both the rwsem and the rcu read lock.
  */
diff --git a/lib/string.c b/lib/string.c
index ed83562a53ae..b5c9a1168d3a 100644
--- a/lib/string.c
+++ b/lib/string.c
@@ -131,7 +131,7 @@ EXPORT_SYMBOL(strncpy);
  * @src: Where to copy the string from
  * @size: size of destination buffer
  *
- * Compatible with *BSD: the result is always a valid
+ * Compatible with ``*BSD``: the result is always a valid
  * NUL-terminated string that fits in the buffer (unless,
  * of course, the buffer size is zero). It does not pad
  * out the result like strncpy() does.
diff --git a/mm/filemap.c b/mm/filemap.c
index 1694623a6289..c5808b7a5fb1 100644
--- a/mm/filemap.c
+++ b/mm/filemap.c
@@ -519,7 +519,7 @@ EXPORT_SYMBOL(filemap_write_and_wait);
  *
  * Write out and wait upon file offsets lstart->lend, inclusive.
  *
- * Note that `lend' is inclusive (describes the last byte to be written) so
+ * Note that @lend is inclusive (describes the last byte to be written) so
  * that this function can be used to write to the very end-of-file (end = -1).
  */
 int filemap_write_and_wait_range(struct address_space *mapping,
@@ -1277,12 +1277,14 @@ EXPORT_SYMBOL(find_lock_entry);
  *
  * PCG flags modify how the page is returned.
  *
- * FGP_ACCESSED: the page will be marked accessed
- * FGP_LOCK: Page is return locked
- * FGP_CREAT: If page is not present then a new page is allocated using
- *		@gfp_mask and added to the page cache and the VM's LRU
- *		list. The page is returned locked and with an increased
- *		refcount. Otherwise, %NULL is returned.
+ * @fgp_flags can be:
+ *
+ * - FGP_ACCESSED: the page will be marked accessed
+ * - FGP_LOCK: Page is return locked
+ * - FGP_CREAT: If page is not present then a new page is allocated using
+ *   @gfp_mask and added to the page cache and the VM's LRU
+ *   list. The page is returned locked and with an increased
+ *   refcount. Otherwise, NULL is returned.
  *
  * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even
  * if the GFP flags specified for FGP_CREAT are atomic.
@@ -3001,7 +3003,7 @@ EXPORT_SYMBOL(generic_file_write_iter);
  * @gfp_mask: memory allocation flags (and I/O mode)
  *
  * The address_space is to try to release any data against the page
- * (presumably at page->private).  If the release was successful, return `1'.
+ * (presumably at page->private).  If the release was successful, return '1'.
  * Otherwise return zero.
  *
  * This may also be called if PG_fscache is set on a page, indicating that the
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index eaa64d2ffdc5..c1b68edaf106 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -4242,7 +4242,8 @@ EXPORT_SYMBOL(free_pages_exact);
  * nr_free_zone_pages() counts the number of counts pages which are beyond the
  * high watermark within all zones at or below a given zone index.  For each
  * zone, the number of pages is calculated as:
- *     managed_pages - high_pages
+ *
+ *     nr_free_zone_pages = managed_pages - high_pages
  */
 static unsigned long nr_free_zone_pages(int offset)
 {
diff --git a/mm/vmalloc.c b/mm/vmalloc.c
index b4024d688f38..c24db06f15c4 100644
--- a/mm/vmalloc.c
+++ b/mm/vmalloc.c
@@ -1540,7 +1540,7 @@ void vfree_atomic(const void *addr)
  *	have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling
  *	conventions for vfree() arch-depenedent would be a really bad idea)
  *
- *	NOTE: assumes that the object at *addr has a size >= sizeof(llist_node)
+ *	NOTE: assumes that the object at @addr has a size >= sizeof(llist_node)
  */
 void vfree(const void *addr)
 {
diff --git a/security/security.c b/security/security.c
index d0e07f269b2d..23555c5504f6 100644
--- a/security/security.c
+++ b/security/security.c
@@ -103,10 +103,14 @@ static int lsm_append(char *new, char **result)
  * to avoid security registration races. This method may also be used
  * to check if your LSM is currently loaded during kernel initialization.
  *
- * Return true if:
- *	-The passed LSM is the one chosen by user at boot time,
- *	-or the passed LSM is configured as the default and the user did not
- *	 choose an alternate LSM at boot time.
+ * Returns:
+ *
+ * true if:
+ *
+ * - The passed LSM is the one chosen by user at boot time,
+ * - or the passed LSM is configured as the default and the user did not
+ *   choose an alternate LSM at boot time.
+ *
  * Otherwise, return false.
  */
 int __init security_module_enable(const char *module)
-- 
2.9.3

[PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Mauro Carvalho Chehab]

./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/filemap.c:1283: ERROR: Unexpected indentation.
./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
./ipc/util.c:676: ERROR: Unexpected indentation.
./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
./security/security.c:109: ERROR: Unexpected indentation.
./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./ipc/util.c:477: ERROR: Unknown target name: "s".

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 block/genhd.c       |  7 ++++---
 drivers/pci/irq.c   |  2 +-
 include/linux/clk.h |  4 ++--
 ipc/util.c          | 12 +++++++-----
 lib/string.c        |  2 +-
 mm/filemap.c        | 18 ++++++++++--------
 mm/page_alloc.c     |  3 ++-
 mm/vmalloc.c        |  2 +-
 security/security.c | 12 ++++++++----
 9 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/block/genhd.c b/block/genhd.c
index b26a5ea115d0..a53bfd19a0ec 100644
--- a/block/genhd.c
+++ b/block/genhd.c
@@ -271,16 +271,17 @@ void blkdev_show(struct seq_file *seqf, off_t offset)
 /**
  * register_blkdev - register a new block device
  *
- * @major: the requested major device number [1..255]. If @major=0, try to
+ * @major: the requested major device number [1..255]. If @major = 0, try to
  *         allocate any unused major number.
  * @name: the name of the new block device as a zero terminated string
  *
  * The @name must be unique within the system.
  *
- * The return value depends on the @major input parameter.
+ * The return value depends on the @major input parameter:
+ *
  *  - if a major device number was requested in range [1..255] then the
  *    function returns zero on success, or a negative error code
- *  - if any unused major number was requested with @major=0 parameter
+ *  - if any unused major number was requested with @major = 0 parameter
  *    then the return value is the allocated major number in range
  *    [1..255] or a negative error code otherwise
  */
diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
index 6684f153ab57..f9f2a0324ecc 100644
--- a/drivers/pci/irq.c
+++ b/drivers/pci/irq.c
@@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
  * driver).
  *
  * Returns:
- *  a suggestion for fixing it (although the driver is not required to
+ * a suggestion for fixing it (although the driver is not required to
  * act on this).
  */
 enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
diff --git a/include/linux/clk.h b/include/linux/clk.h
index e9d36b3e49de..024cd07870d0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -132,8 +132,8 @@ int clk_get_phase(struct clk *clk);
  * @q: clk compared against p
  *
  * Returns true if the two struct clk pointers both point to the same hardware
- * clock node. Put differently, returns true if struct clk *p and struct clk *q
- * share the same struct clk_core object.
+ * clock node. Put differently, returns true if @p and @q
+ * share the same &struct clk_core object.
  *
  * Returns false otherwise. Note that two NULL clks are treated as matching.
  */
diff --git a/ipc/util.c b/ipc/util.c
index 798cad18dd87..3459a16a9df9 100644
--- a/ipc/util.c
+++ b/ipc/util.c
@@ -474,7 +474,7 @@ void ipc_rcu_free(struct rcu_head *head)
  * Check user, group, other permissions for access
  * to ipc resources. return 0 if allowed
  *
- * @flag will most probably be 0 or S_...UGO from <linux/stat.h>
+ * @flag will most probably be 0 or ``S_...UGO`` from <linux/stat.h>
  */
 int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 {
@@ -672,10 +672,12 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
  *
  * This function does some common audit and permissions check for some IPC_XXX
  * cmd and is called from semctl_down, shmctl_down and msgctl_down.
- * It must be called without any lock held and
- *  - retrieves the ipc with the given id in the given table.
- *  - performs some audit and permission check, depending on the given cmd
- *  - returns a pointer to the ipc object or otherwise, the corresponding error.
+ * It must be called without any lock held and:
+ *
+ *   - retrieves the ipc with the given id in the given table.
+ *   - performs some audit and permission check, depending on the given cmd
+ *   - returns a pointer to the ipc object or otherwise, the corresponding
+ *     error.
  *
  * Call holding the both the rwsem and the rcu read lock.
  */
diff --git a/lib/string.c b/lib/string.c
index ed83562a53ae..b5c9a1168d3a 100644
--- a/lib/string.c
+++ b/lib/string.c
@@ -131,7 +131,7 @@ EXPORT_SYMBOL(strncpy);
  * @src: Where to copy the string from
  * @size: size of destination buffer
  *
- * Compatible with *BSD: the result is always a valid
+ * Compatible with ``*BSD``: the result is always a valid
  * NUL-terminated string that fits in the buffer (unless,
  * of course, the buffer size is zero). It does not pad
  * out the result like strncpy() does.
diff --git a/mm/filemap.c b/mm/filemap.c
index 1694623a6289..c5808b7a5fb1 100644
--- a/mm/filemap.c
+++ b/mm/filemap.c
@@ -519,7 +519,7 @@ EXPORT_SYMBOL(filemap_write_and_wait);
  *
  * Write out and wait upon file offsets lstart->lend, inclusive.
  *
- * Note that `lend' is inclusive (describes the last byte to be written) so
+ * Note that @lend is inclusive (describes the last byte to be written) so
  * that this function can be used to write to the very end-of-file (end = -1).
  */
 int filemap_write_and_wait_range(struct address_space *mapping,
@@ -1277,12 +1277,14 @@ EXPORT_SYMBOL(find_lock_entry);
  *
  * PCG flags modify how the page is returned.
  *
- * FGP_ACCESSED: the page will be marked accessed
- * FGP_LOCK: Page is return locked
- * FGP_CREAT: If page is not present then a new page is allocated using
- *		@gfp_mask and added to the page cache and the VM's LRU
- *		list. The page is returned locked and with an increased
- *		refcount. Otherwise, %NULL is returned.
+ * @fgp_flags can be:
+ *
+ * - FGP_ACCESSED: the page will be marked accessed
+ * - FGP_LOCK: Page is return locked
+ * - FGP_CREAT: If page is not present then a new page is allocated using
+ *   @gfp_mask and added to the page cache and the VM's LRU
+ *   list. The page is returned locked and with an increased
+ *   refcount. Otherwise, NULL is returned.
  *
  * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even
  * if the GFP flags specified for FGP_CREAT are atomic.
@@ -3001,7 +3003,7 @@ EXPORT_SYMBOL(generic_file_write_iter);
  * @gfp_mask: memory allocation flags (and I/O mode)
  *
  * The address_space is to try to release any data against the page
- * (presumably at page->private).  If the release was successful, return `1'.
+ * (presumably at page->private).  If the release was successful, return '1'.
  * Otherwise return zero.
  *
  * This may also be called if PG_fscache is set on a page, indicating that the
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index eaa64d2ffdc5..c1b68edaf106 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -4242,7 +4242,8 @@ EXPORT_SYMBOL(free_pages_exact);
  * nr_free_zone_pages() counts the number of counts pages which are beyond the
  * high watermark within all zones at or below a given zone index.  For each
  * zone, the number of pages is calculated as:
- *     managed_pages - high_pages
+ *
+ *     nr_free_zone_pages = managed_pages - high_pages
  */
 static unsigned long nr_free_zone_pages(int offset)
 {
diff --git a/mm/vmalloc.c b/mm/vmalloc.c
index b4024d688f38..c24db06f15c4 100644
--- a/mm/vmalloc.c
+++ b/mm/vmalloc.c
@@ -1540,7 +1540,7 @@ void vfree_atomic(const void *addr)
  *	have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling
  *	conventions for vfree() arch-depenedent would be a really bad idea)
  *
- *	NOTE: assumes that the object at *addr has a size >= sizeof(llist_node)
+ *	NOTE: assumes that the object at @addr has a size >= sizeof(llist_node)
  */
 void vfree(const void *addr)
 {
diff --git a/security/security.c b/security/security.c
index d0e07f269b2d..23555c5504f6 100644
--- a/security/security.c
+++ b/security/security.c
@@ -103,10 +103,14 @@ static int lsm_append(char *new, char **result)
  * to avoid security registration races. This method may also be used
  * to check if your LSM is currently loaded during kernel initialization.
  *
- * Return true if:
- *	-The passed LSM is the one chosen by user at boot time,
- *	-or the passed LSM is configured as the default and the user did not
- *	 choose an alternate LSM at boot time.
+ * Returns:
+ *
+ * true if:
+ *
+ * - The passed LSM is the one chosen by user at boot time,
+ * - or the passed LSM is configured as the default and the user did not
+ *   choose an alternate LSM at boot time.
+ *
  * Otherwise, return false.
  */
 int __init security_module_enable(const char *module)
-- 
2.9.3


--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

[PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Mauro Carvalho Chehab]

./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/filemap.c:1283: ERROR: Unexpected indentation.
./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
./ipc/util.c:676: ERROR: Unexpected indentation.
./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
./security/security.c:109: ERROR: Unexpected indentation.
./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
./ipc/util.c:477: ERROR: Unknown target name: "s".

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 block/genhd.c       |  7 ++++---
 drivers/pci/irq.c   |  2 +-
 include/linux/clk.h |  4 ++--
 ipc/util.c          | 12 +++++++-----
 lib/string.c        |  2 +-
 mm/filemap.c        | 18 ++++++++++--------
 mm/page_alloc.c     |  3 ++-
 mm/vmalloc.c        |  2 +-
 security/security.c | 12 ++++++++----
 9 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/block/genhd.c b/block/genhd.c
index b26a5ea115d0..a53bfd19a0ec 100644
--- a/block/genhd.c
+++ b/block/genhd.c
@@ -271,16 +271,17 @@ void blkdev_show(struct seq_file *seqf, off_t offset)
 /**
  * register_blkdev - register a new block device
  *
- * @major: the requested major device number [1..255]. If @major=0, try to
+ * @major: the requested major device number [1..255]. If @major = 0, try to
  *         allocate any unused major number.
  * @name: the name of the new block device as a zero terminated string
  *
  * The @name must be unique within the system.
  *
- * The return value depends on the @major input parameter.
+ * The return value depends on the @major input parameter:
+ *
  *  - if a major device number was requested in range [1..255] then the
  *    function returns zero on success, or a negative error code
- *  - if any unused major number was requested with @major=0 parameter
+ *  - if any unused major number was requested with @major = 0 parameter
  *    then the return value is the allocated major number in range
  *    [1..255] or a negative error code otherwise
  */
diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
index 6684f153ab57..f9f2a0324ecc 100644
--- a/drivers/pci/irq.c
+++ b/drivers/pci/irq.c
@@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
  * driver).
  *
  * Returns:
- *  a suggestion for fixing it (although the driver is not required to
+ * a suggestion for fixing it (although the driver is not required to
  * act on this).
  */
 enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
diff --git a/include/linux/clk.h b/include/linux/clk.h
index e9d36b3e49de..024cd07870d0 100644
--- a/include/linux/clk.h
+++ b/include/linux/clk.h
@@ -132,8 +132,8 @@ int clk_get_phase(struct clk *clk);
  * @q: clk compared against p
  *
  * Returns true if the two struct clk pointers both point to the same hardware
- * clock node. Put differently, returns true if struct clk *p and struct clk *q
- * share the same struct clk_core object.
+ * clock node. Put differently, returns true if @p and @q
+ * share the same &struct clk_core object.
  *
  * Returns false otherwise. Note that two NULL clks are treated as matching.
  */
diff --git a/ipc/util.c b/ipc/util.c
index 798cad18dd87..3459a16a9df9 100644
--- a/ipc/util.c
+++ b/ipc/util.c
@@ -474,7 +474,7 @@ void ipc_rcu_free(struct rcu_head *head)
  * Check user, group, other permissions for access
  * to ipc resources. return 0 if allowed
  *
- * @flag will most probably be 0 or S_...UGO from <linux/stat.h>
+ * @flag will most probably be 0 or ``S_...UGO`` from <linux/stat.h>
  */
 int ipcperms(struct ipc_namespace *ns, struct kern_ipc_perm *ipcp, short flag)
 {
@@ -672,10 +672,12 @@ int ipc_update_perm(struct ipc64_perm *in, struct kern_ipc_perm *out)
  *
  * This function does some common audit and permissions check for some IPC_XXX
  * cmd and is called from semctl_down, shmctl_down and msgctl_down.
- * It must be called without any lock held and
- *  - retrieves the ipc with the given id in the given table.
- *  - performs some audit and permission check, depending on the given cmd
- *  - returns a pointer to the ipc object or otherwise, the corresponding error.
+ * It must be called without any lock held and:
+ *
+ *   - retrieves the ipc with the given id in the given table.
+ *   - performs some audit and permission check, depending on the given cmd
+ *   - returns a pointer to the ipc object or otherwise, the corresponding
+ *     error.
  *
  * Call holding the both the rwsem and the rcu read lock.
  */
diff --git a/lib/string.c b/lib/string.c
index ed83562a53ae..b5c9a1168d3a 100644
--- a/lib/string.c
+++ b/lib/string.c
@@ -131,7 +131,7 @@ EXPORT_SYMBOL(strncpy);
  * @src: Where to copy the string from
  * @size: size of destination buffer
  *
- * Compatible with *BSD: the result is always a valid
+ * Compatible with ``*BSD``: the result is always a valid
  * NUL-terminated string that fits in the buffer (unless,
  * of course, the buffer size is zero). It does not pad
  * out the result like strncpy() does.
diff --git a/mm/filemap.c b/mm/filemap.c
index 1694623a6289..c5808b7a5fb1 100644
--- a/mm/filemap.c
+++ b/mm/filemap.c
@@ -519,7 +519,7 @@ EXPORT_SYMBOL(filemap_write_and_wait);
  *
  * Write out and wait upon file offsets lstart->lend, inclusive.
  *
- * Note that `lend' is inclusive (describes the last byte to be written) so
+ * Note that @lend is inclusive (describes the last byte to be written) so
  * that this function can be used to write to the very end-of-file (end = -1).
  */
 int filemap_write_and_wait_range(struct address_space *mapping,
@@ -1277,12 +1277,14 @@ EXPORT_SYMBOL(find_lock_entry);
  *
  * PCG flags modify how the page is returned.
  *
- * FGP_ACCESSED: the page will be marked accessed
- * FGP_LOCK: Page is return locked
- * FGP_CREAT: If page is not present then a new page is allocated using
- *		@gfp_mask and added to the page cache and the VM's LRU
- *		list. The page is returned locked and with an increased
- *		refcount. Otherwise, %NULL is returned.
+ * @fgp_flags can be:
+ *
+ * - FGP_ACCESSED: the page will be marked accessed
+ * - FGP_LOCK: Page is return locked
+ * - FGP_CREAT: If page is not present then a new page is allocated using
+ *   @gfp_mask and added to the page cache and the VM's LRU
+ *   list. The page is returned locked and with an increased
+ *   refcount. Otherwise, NULL is returned.
  *
  * If FGP_LOCK or FGP_CREAT are specified then the function may sleep even
  * if the GFP flags specified for FGP_CREAT are atomic.
@@ -3001,7 +3003,7 @@ EXPORT_SYMBOL(generic_file_write_iter);
  * @gfp_mask: memory allocation flags (and I/O mode)
  *
  * The address_space is to try to release any data against the page
- * (presumably at page->private).  If the release was successful, return `1'.
+ * (presumably at page->private).  If the release was successful, return '1'.
  * Otherwise return zero.
  *
  * This may also be called if PG_fscache is set on a page, indicating that the
diff --git a/mm/page_alloc.c b/mm/page_alloc.c
index eaa64d2ffdc5..c1b68edaf106 100644
--- a/mm/page_alloc.c
+++ b/mm/page_alloc.c
@@ -4242,7 +4242,8 @@ EXPORT_SYMBOL(free_pages_exact);
  * nr_free_zone_pages() counts the number of counts pages which are beyond the
  * high watermark within all zones at or below a given zone index.  For each
  * zone, the number of pages is calculated as:
- *     managed_pages - high_pages
+ *
+ *     nr_free_zone_pages = managed_pages - high_pages
  */
 static unsigned long nr_free_zone_pages(int offset)
 {
diff --git a/mm/vmalloc.c b/mm/vmalloc.c
index b4024d688f38..c24db06f15c4 100644
--- a/mm/vmalloc.c
+++ b/mm/vmalloc.c
@@ -1540,7 +1540,7 @@ void vfree_atomic(const void *addr)
  *	have CONFIG_ARCH_HAVE_NMI_SAFE_CMPXCHG, but making the calling
  *	conventions for vfree() arch-depenedent would be a really bad idea)
  *
- *	NOTE: assumes that the object at *addr has a size >= sizeof(llist_node)
+ *	NOTE: assumes that the object at @addr has a size >= sizeof(llist_node)
  */
 void vfree(const void *addr)
 {
diff --git a/security/security.c b/security/security.c
index d0e07f269b2d..23555c5504f6 100644
--- a/security/security.c
+++ b/security/security.c
@@ -103,10 +103,14 @@ static int lsm_append(char *new, char **result)
  * to avoid security registration races. This method may also be used
  * to check if your LSM is currently loaded during kernel initialization.
  *
- * Return true if:
- *	-The passed LSM is the one chosen by user at boot time,
- *	-or the passed LSM is configured as the default and the user did not
- *	 choose an alternate LSM at boot time.
+ * Returns:
+ *
+ * true if:
+ *
+ * - The passed LSM is the one chosen by user at boot time,
+ * - or the passed LSM is configured as the default and the user did not
+ *   choose an alternate LSM at boot time.
+ *
  * Otherwise, return false.
  */
 int __init security_module_enable(const char *module)
-- 
2.9.3


--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Bjorn Helgaas]

On Thu, Mar 30, 2017 at 05:11:36PM -0300, Mauro Carvalho Chehab wrote:
> ./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
> ./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/filemap.c:1283: ERROR: Unexpected indentation.
> ./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
> ./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
> ./ipc/util.c:676: ERROR: Unexpected indentation.
> ./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./security/security.c:109: ERROR: Unexpected indentation.
> ./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
> ./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
> ./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./ipc/util.c:477: ERROR: Unknown target name: "s".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>	# for drivers/pci/irq.c

> diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
> index 6684f153ab57..f9f2a0324ecc 100644
> --- a/drivers/pci/irq.c
> +++ b/drivers/pci/irq.c
> @@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
>   * driver).
>   *
>   * Returns:
> - *  a suggestion for fixing it (although the driver is not required to
> + * a suggestion for fixing it (although the driver is not required to
>   * act on this).
>   */
>  enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)

Re: [PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Bjorn Helgaas]

On Thu, Mar 30, 2017 at 05:11:36PM -0300, Mauro Carvalho Chehab wrote:
> ./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
> ./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/filemap.c:1283: ERROR: Unexpected indentation.
> ./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
> ./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
> ./ipc/util.c:676: ERROR: Unexpected indentation.
> ./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./security/security.c:109: ERROR: Unexpected indentation.
> ./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
> ./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
> ./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./ipc/util.c:477: ERROR: Unknown target name: "s".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>	# for drivers/pci/irq.c

> diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
> index 6684f153ab57..f9f2a0324ecc 100644
> --- a/drivers/pci/irq.c
> +++ b/drivers/pci/irq.c
> @@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
>   * driver).
>   *
>   * Returns:
> - *  a suggestion for fixing it (although the driver is not required to
> + * a suggestion for fixing it (although the driver is not required to
>   * act on this).
>   */
>  enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

[PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files

[Bjorn Helgaas]

On Thu, Mar 30, 2017 at 05:11:36PM -0300, Mauro Carvalho Chehab wrote:
> ./lib/string.c:134: WARNING: Inline emphasis start-string without end-string.
> ./mm/filemap.c:522: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/filemap.c:1283: ERROR: Unexpected indentation.
> ./mm/filemap.c:3003: WARNING: Inline interpreted text or phrase reference start-string without end-string.
> ./mm/vmalloc.c:1544: WARNING: Inline emphasis start-string without end-string.
> ./mm/page_alloc.c:4245: ERROR: Unexpected indentation.
> ./ipc/util.c:676: ERROR: Unexpected indentation.
> ./drivers/pci/irq.c:35: WARNING: Block quote ends without a blank line; unexpected unindent.
> ./security/security.c:109: ERROR: Unexpected indentation.
> ./security/security.c:110: WARNING: Definition list ends without a blank line; unexpected unindent.
> ./block/genhd.c:275: WARNING: Inline strong start-string without end-string.
> ./block/genhd.c:283: WARNING: Inline strong start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./include/linux/clk.h:134: WARNING: Inline emphasis start-string without end-string.
> ./ipc/util.c:477: ERROR: Unknown target name: "s".
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Bjorn Helgaas <bhelgaas@google.com>	# for drivers/pci/irq.c

> diff --git a/drivers/pci/irq.c b/drivers/pci/irq.c
> index 6684f153ab57..f9f2a0324ecc 100644
> --- a/drivers/pci/irq.c
> +++ b/drivers/pci/irq.c
> @@ -31,7 +31,7 @@ static void pci_note_irq_problem(struct pci_dev *pdev, const char *reason)
>   * driver).
>   *
>   * Returns:
> - *  a suggestion for fixing it (although the driver is not required to
> + * a suggestion for fixing it (although the driver is not required to
>   * act on this).
>   */
>  enum pci_lost_interrupt_reason pci_lost_interrupt(struct pci_dev *pdev)
--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:27 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> This series converts just two documents, adding them to the
> core-api.rst book. It addresses the errors/warnings that popup
> after the conversion.
> 
> I had to add two fixes to scripts/kernel-doc, in order to solve
> some of the issues.

I've applied the set, including the add-on to move some stuff to
driver-api - thanks.

For whatever reason, I had a hard time applying a few of these; "git am"
would tell me this:

> Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> The copy of the patch that failed is found in: .git/rebase-apply/patch

I was able to get around this, but it took some hand work.  How are you
generating these?

Thanks,

jon

Re: [PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:27 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> This series converts just two documents, adding them to the
> core-api.rst book. It addresses the errors/warnings that popup
> after the conversion.
> 
> I had to add two fixes to scripts/kernel-doc, in order to solve
> some of the issues.

I've applied the set, including the add-on to move some stuff to
driver-api - thanks.

For whatever reason, I had a hard time applying a few of these; "git am"
would tell me this:

> Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> The copy of the patch that failed is found in: .git/rebase-apply/patch

I was able to get around this, but it took some hand work.  How are you
generating these?

Thanks,

jon

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:27 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> This series converts just two documents, adding them to the
> core-api.rst book. It addresses the errors/warnings that popup
> after the conversion.
> 
> I had to add two fixes to scripts/kernel-doc, in order to solve
> some of the issues.

I've applied the set, including the add-on to move some stuff to
driver-api - thanks.

For whatever reason, I had a hard time applying a few of these; "git am"
would tell me this:

> Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> The copy of the patch that failed is found in: .git/rebase-apply/patch

I was able to get around this, but it took some hand work.  How are you
generating these?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Em Sun, 2 Apr 2017 14:34:18 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 30 Mar 2017 17:11:27 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > This series converts just two documents, adding them to the
> > core-api.rst book. It addresses the errors/warnings that popup
> > after the conversion.
> > 
> > I had to add two fixes to scripts/kernel-doc, in order to solve
> > some of the issues.  
> 
> I've applied the set, including the add-on to move some stuff to
> driver-api - thanks.

Thanks!

> For whatever reason, I had a hard time applying a few of these; "git am"
> would tell me this:
> 
> > Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> > fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> > Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> > The copy of the patch that failed is found in: .git/rebase-apply/patch  
> 
> I was able to get around this, but it took some hand work.  How are you
> generating these?

That's weird. I'm using this to generate the patches:

	git format-patch -o $tmp_dir --stat --summary --patience --signoff --thread=shallow

plus some scripting that runs scripts/get_maintainers.

After that, I run:

	git send-email $tmp_dir

Then, exim sends the patches to a smart SMTP server (currently,
infradead.org, but I'm switching to s-opensource.org, as I'm getting
some troubles because the IP doesn't match the From: line).

Thanks,
Mauro

Re: [PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Em Sun, 2 Apr 2017 14:34:18 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 30 Mar 2017 17:11:27 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > This series converts just two documents, adding them to the
> > core-api.rst book. It addresses the errors/warnings that popup
> > after the conversion.
> > 
> > I had to add two fixes to scripts/kernel-doc, in order to solve
> > some of the issues.  
> 
> I've applied the set, including the add-on to move some stuff to
> driver-api - thanks.

Thanks!

> For whatever reason, I had a hard time applying a few of these; "git am"
> would tell me this:
> 
> > Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> > fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> > Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> > The copy of the patch that failed is found in: .git/rebase-apply/patch  
> 
> I was able to get around this, but it took some hand work.  How are you
> generating these?

That's weird. I'm using this to generate the patches:

	git format-patch -o $tmp_dir --stat --summary --patience --signoff --thread=shallow

plus some scripting that runs scripts/get_maintainers.

After that, I run:

	git send-email $tmp_dir

Then, exim sends the patches to a smart SMTP server (currently,
infradead.org, but I'm switching to s-opensource.org, as I'm getting
some troubles because the IP doesn't match the From: line).

Thanks,
Mauro

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>

[PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Mauro Carvalho Chehab]

Em Sun, 2 Apr 2017 14:34:18 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 30 Mar 2017 17:11:27 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > This series converts just two documents, adding them to the
> > core-api.rst book. It addresses the errors/warnings that popup
> > after the conversion.
> > 
> > I had to add two fixes to scripts/kernel-doc, in order to solve
> > some of the issues.  
> 
> I've applied the set, including the add-on to move some stuff to
> driver-api - thanks.

Thanks!

> For whatever reason, I had a hard time applying a few of these; "git am"
> would tell me this:
> 
> > Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> > fatal: sha1 information is lacking or useless (Documentation/driver-api/index.rst).
> > Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to drivers_api
> > The copy of the patch that failed is found in: .git/rebase-apply/patch  
> 
> I was able to get around this, but it took some hand work.  How are you
> generating these?

That's weird. I'm using this to generate the patches:

	git format-patch -o $tmp_dir --stat --summary --patience --signoff --thread=shallow

plus some scripting that runs scripts/get_maintainers.

After that, I run:

	git send-email $tmp_dir

Then, exim sends the patches to a smart SMTP server (currently,
infradead.org, but I'm switching to s-opensource.org, as I'm getting
some troubles because the IP doesn't match the From: line).

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-security-module" in
the body of a message to majordomo at vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html