convert genericirq.tmpl and kernel-api.tmpl to DocBook
Subsystems (15)
cover convert genericirq.tmpl and kernel-api.tmpl to DocBook
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
Signature · 1 line
2.9.3
PATCH 1/9 scripts/kernel-doc: fix parser for apostrophes
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 <[email protected]>
--- scripts/kernel-doc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)
scripts/kernel-doc +11 -1
@@ -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"],
Signature · 1 line
2.9.3
PATCH 2/9 scripts/kernel-doc: fix handling of parameters with parenthesis
In reply to Mauro Carvalho Chehablib/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 <[email protected]>
--- scripts/kernel-doc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-)
scripts/kernel-doc +3 -4
@@ -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 ".
Signature · 1 line
2.9.3
PATCH 3/9 genericirq.tmpl: convert it to ReST
In reply to Mauro Carvalho ChehabBrainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvt
Copyright information inserted manually.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- 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
Documentation/DocBook/Makefile +1 -1
@@ -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),)
Documentation/DocBook/genericirq.tmpl deleted +0 -520
520 lines not on this page · raw message
Documentation/core-api/genericirq.rst new file +445 -0
445 lines not on this page · raw message
Documentation/core-api/index.rst +1 -0
@@ -16,6 +16,7 @@ Core utilities cpu_hotplug local_ops workqueue + genericirq Interfaces for kernel debugging ===============================
Signature · 1 line
2.9.3
Jonathan Corbet
maintainerRe: [PATCH 3/9] genericirq.tmpl: convert it to ReST
On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
[Reordering things a bit]
Documentation/core-api/genericirq.rst line 8
Quoted 6 lines
+==========================
Documentation/core-api/genericirq.rst new file +5
-0+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).
Quoted 2 lines
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
Quoted 1,014 lines
Copyright information inserted manually.
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- 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.rstDocumentation/DocBook/Makefile +1
-1@@ -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),)Documentation/DocBook/genericirq.tmpl deleted +0
-520@@ -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>[email protected]</email> - </address> - </affiliation> - </author> - <author> - <firstname>Ingo</firstname> - <surname>Molnar</surname> - <affiliation> - <address> - <email>[email protected]</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 & 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; - </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>[email protected]</email></para></listitem> - <listitem><para>Ingo Molnar<email>[email protected]</email></para></listitem> - </orderedlist> - </para> - </chapter> -</book>Documentation/core-api/genericirq.rst new file +445
-0@@ -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 [email protected] + +2. Ingo Molnar [email protected]Documentation/core-api/index.rst +1
-0@@ -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
Quoted 15 lines · Jonathan Corbet
On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab <[email protected]> wrote:[Reordering things a bit]
Documentation/core-api/genericirq.rst line 8
Quoted 6 lines
+==========================
Documentation/core-api/genericirq.rst new file +5
-0+Linux generic IRQ handling +========================== + +:Copyright: |copy| 2005-2010: Thomas Gleixner +:Copyright: |copy| 2005-2006: Ingo MolnarIt seems maybe they should have been CC'd on this one? Adding them now (and leaving the full patch for their amusement).
Quoted 8 lines
Quoted 2 lines
Brainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvtIn 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
In reply to Jonathan CorbetEm Fri, 31 Mar 2017 08:57:11 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 15 lines
On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab <[email protected]> wrote:[Reordering things a bit]
Documentation/core-api/genericirq.rst line 8
Quoted 6 lines
+==========================
Documentation/core-api/genericirq.rst new file +5
-0+Linux generic IRQ handling +========================== + +:Copyright: |copy| 2005-2010: Thomas Gleixner +:Copyright: |copy| 2005-2006: Ingo MolnarIt seems maybe they should have been CC'd on this one? Adding them now (and leaving the full patch for their amusement).
Quoted 8 lines
Quoted 2 lines
Brainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvtIn 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
In reply to Mauro Carvalho ChehabThe 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 <[email protected]>
--- Documentation/core-api/genericirq.rst | 97 +++++++++++++++++------------------ 1 file changed, 46 insertions(+), 51 deletions(-)
Documentation/core-api/genericirq.rst +46 -51
@@ -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 =======
Signature · 1 line
2.9.3
PATCH 5/9 kernel-api.tmpl: convert it to ReST
In reply to Mauro Carvalho ChehabBrainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvt
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- 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
Documentation/DocBook/Makefile +1 -1
@@ -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
Documentation/DocBook/kernel-api.tmpl deleted +0 -331
331 lines not on this page · raw message
Documentation/core-api/index.rst +1 -0
@@ -11,6 +11,7 @@ Core utilities .. toctree:: :maxdepth: 1 + kernel-api assoc_array atomic_ops cpu_hotplug
Documentation/core-api/kernel-api.rst new file +419 -0
419 lines not on this page · raw message
Signature · 1 line
2.9.3
Jonathan Corbet
maintainerRe: [PATCH 5/9] kernel-api.tmpl: convert it to ReST
Quoted 2 lines · On Thu, 30 Mar 2017 17:11:32 -0300 Mauro Carvalho Chehab…
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
Em Fri, 31 Mar 2017 09:05:37 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 11 lines
Quoted 2 lines · On Thu, 30 Mar 2017 17:11:32 -0300 Mauro Carvalho Chehab…
Brainless conversion of genericirq.tmpl book to ReST, via
Documentation/sphinx/tmplcvtThis 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.
Quoted 2 lines
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.
Quoted 2 lines
(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
In reply to Mauro Carvalho ChehabThe 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 <[email protected]>
--- lib/vsprintf.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
lib/vsprintf.c +3 -3
@@ -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
Signature · 1 line
2.9.3
PATCH 7/9 kernel-api.rst: make it handle lib/crc32.c
In reply to Mauro Carvalho ChehabThis file has only "internal" functions:
./lib/crc32.c:1: warning: no structured comments found
Signed-off-by Mauro Carvalho Chehab <[email protected]>
--- Documentation/core-api/kernel-api.rst | 1 - 1 file changed, 1 deletion(-)
Documentation/core-api/kernel-api.rst +0 -1
@@ -80,7 +80,6 @@ CRC Functions :export: .. kernel-doc:: lib/crc32.c - :export: .. kernel-doc:: lib/crc-ccitt.c :export:
Signature · 1 line
2.9.3
PATCH 8/9 kernel-api.rst: fix some complex tags at lib/bitmap.c
In reply to Mauro Carvalho ChehabFix 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 <[email protected]>
--- lib/bitmap.c | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-)
lib/bitmap.c +17 -11
@@ -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
Signature · 1 line
2.9.3
PATCH 9/9 kernel-api.rst: fix a series of errors when parsing C files
In reply to 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 <[email protected]>
--- 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(-)
block/genhd.c +4 -3
@@ -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 */
drivers/pci/irq.c +1 -1
@@ -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)
include/linux/clk.h +2 -2
@@ -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. */
ipc/util.c +7 -5
@@ -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. */
lib/string.c +1 -1
@@ -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.
mm/filemap.c +10 -8
@@ -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
mm/page_alloc.c +2 -1
@@ -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) {
mm/vmalloc.c +1 -1
@@ -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) {
security/security.c +8 -4
@@ -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)
Signature · 1 line
2.9.3
Re: [PATCH 9/9] kernel-api.rst: fix a series of errors when parsing C files
Quoted 16 lines · 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".
Quoted 1 line
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Quoted 13 lines
drivers/pci/irq.c +1
-1@@ -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)
Quoted 6 lines · On Thu, 30 Mar 2017 17:11:27 -0300 Mauro Carvalho Chehab…
This series converts just two documents, adding them to the
core-api.rstbook. 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:
Quoted 4 lines
Applying: docs-rst:
core_api: move driver-specific stuff todrivers_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 todrivers_apiThe 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
Em Sun, 2 Apr 2017 14:34:18 -0600
Jonathan Corbet <[email protected]> escreveu:
Quoted 7 lines
Quoted 4 lines · On Thu, 30 Mar 2017 17:11:27 -0300 Mauro Carvalho Chehab…
This series converts just two documents, adding them to the
core-api.rstbook. It addresses the errors/warnings that popup after the conversion.
Quoted 5 lines
Quoted 2 lines
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!
Quoted 10 lines
For whatever reason, I had a hard time applying a few of these; "git am" would tell me this:
Quoted 4 lines
Applying: docs-rst:
core_api: move driver-specific stuff todrivers_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 todrivers_apiThe copy of the patch that failed is found in: .git/rebase-apply/patchI 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