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

[Mauro Carvalho Chehab]

Em Fri, 31 Mar 2017 08:57:11 -0600
Jonathan Corbet  escreveu:

> On Thu, 30 Mar 2017 17:11:30 -0300
> Mauro Carvalho Chehab  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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

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


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

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

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab  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 
> ---
>  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..
> --- a/Documentation/DocBook/genericirq.tmpl
> +++ /dev/null
> @@ -1,520 +0,0 @@
> -
> - - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd; []>
> -
> -
> - 
> -  Linux generic IRQ handling
> -
> -  
> -   
> -Thomas
> -Gleixner
> -
> - 
> -  t...@linutronix.de
> - 
> -
> -   
> -   
> -Ingo
> -Molnar
> -
> - 
> -  mi...@elte.hu
> - 
> -
> -   
> -  
> -
> -  
> -   2005-2010
> -   Thomas Gleixner
> -  
> -  
> -   2005-2006
> -   Ingo Molnar
> -  
> -
> -  
> -   
> - 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.
> -   
> -
> -   
> - 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.
> -   
> -
> -   
> - 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
> -   
> -
> -   
> - For more details see the file COPYING in the source
> - distribution of Linux.
> -   
> -  
> - 
> -
> -
> -
> -  
> -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: