Re: [PATCH 20/27] Documentation: x86: convert i386/IO-APIC.txt to reST

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Fri, 26 Apr 2019 23:31:43 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  .../x86/i386/{IO-APIC.txt => IO-APIC.rst}     | 26 ++++++++++++-------
>  Documentation/x86/i386/index.rst              | 10 +++++++
>  Documentation/x86/index.rst                   |  1 +
>  3 files changed, 27 insertions(+), 10 deletions(-)
>  rename Documentation/x86/i386/{IO-APIC.txt => IO-APIC.rst} (93%)
>  create mode 100644 Documentation/x86/i386/index.rst
> 
> diff --git a/Documentation/x86/i386/IO-APIC.txt b/Documentation/x86/i386/IO-APIC.rst
> similarity index 93%
> rename from Documentation/x86/i386/IO-APIC.txt
> rename to Documentation/x86/i386/IO-APIC.rst
> index 15f5baf7e1b6..aec98f742763 100644
> --- a/Documentation/x86/i386/IO-APIC.txt
> +++ b/Documentation/x86/i386/IO-APIC.rst
> @@ -1,3 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======
> +IO-APIC
> +=======
> +
> +:Author: Ingo Molnar <mingo@kernel.org>
> +
>  Most (all) Intel-MP compliant SMP boards have the so-called 'IO-APIC',
>  which is an enhanced interrupt controller. It enables us to route
>  hardware interrupts to multiple CPUs, or to CPU groups. Without an
> @@ -13,7 +21,7 @@ usually worked around by the kernel. If your MP-compliant SMP board does
>  not boot Linux, then consult the linux-smp mailing list archives first.
>  
>  If your box boots fine with enabled IO-APIC IRQs, then your
> -/proc/interrupts will look like this one:
> +/proc/interrupts will look like this one::
>  
>     ---------------------------->
...
     <----------------------------

I would remove those lines, as they sounds like a way used by the
doc author to "escape" a literal block.

Either way:

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>


>    hell:~> cat /proc/interrupts  
> @@ -37,14 +45,14 @@ none of those IRQ sources is performance-critical.
>  In the unlikely case that your board does not create a working mp-table,
>  you can use the pirq= boot parameter to 'hand-construct' IRQ entries. This
>  is non-trivial though and cannot be automated. One sample /etc/lilo.conf
> -entry:
> +entry::
>  
>  	append="pirq=15,11,10"
>  
>  The actual numbers depend on your system, on your PCI cards and on their
>  PCI slot position. Usually PCI slots are 'daisy chained' before they are
>  connected to the PCI chipset IRQ routing facility (the incoming PIRQ1-4
> -lines):
> +lines)::
>  
>                 ,-.        ,-.        ,-.        ,-.        ,-.
>       PIRQ4 ----| |-.    ,-| |-.    ,-| |-.    ,-| |--------| |
> @@ -56,7 +64,7 @@ lines):
>       PIRQ1 ----| |-  `----| |-  `----| |-  `----| |--------| |
>                 `-'        `-'        `-'        `-'        `-'
>  
> -Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD:
> +Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD::
>  
>                                 ,-.
>                           INTD--| |
> @@ -78,19 +86,19 @@ to have non shared interrupts). Slot5 should be used for videocards, they
>  do not use interrupts normally, thus they are not daisy chained either.
>  
>  so if you have your SCSI card (IRQ11) in Slot1, Tulip card (IRQ9) in
> -Slot2, then you'll have to specify this pirq= line:
> +Slot2, then you'll have to specify this pirq= line::
>  
>  	append="pirq=11,9"
>  
>  the following script tries to figure out such a default pirq= line from
> -your PCI configuration:
> +your PCI configuration::
>  
>  	echo -n pirq=; echo `scanpci | grep T_L | cut -c56-` | sed 's/ /,/g'
>  
>  note that this script won't work if you have skipped a few slots or if your
>  board does not do default daisy-chaining. (or the IO-APIC has the PIRQ pins
>  connected in some strange way). E.g. if in the above case you have your SCSI
> -card (IRQ11) in Slot3, and have Slot1 empty:
> +card (IRQ11) in Slot3, and have Slot1 empty::
>  
>  	append="pirq=0,9,11"
>  
> @@ -105,7 +113,7 @@ won't function properly (e.g. if it's inserted as a module).
>  If you have 2 PCI buses, then you can use up to 8 pirq values, although such
>  boards tend to have a good configuration.
>  
> -Be prepared that it might happen that you need some strange pirq line:
> +Be prepared that it might happen that you need some strange pirq line::
>  
>  	append="pirq=0,0,0,0,0,0,9,11"
>  
> @@ -115,5 +123,3 @@ Good luck and mail to linux-smp@vger.kernel.org or
>  linux-kernel@vger.kernel.org if you have any problems that are not covered
>  by this document.
>  
> --- mingo
> -
> diff --git a/Documentation/x86/i386/index.rst b/Documentation/x86/i386/index.rst
> new file mode 100644
> index 000000000000..8747cf5bbd49
> --- /dev/null
> +++ b/Documentation/x86/i386/index.rst
> @@ -0,0 +1,10 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============
> +i386 Support
> +============
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   IO-APIC
> diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
> index 526f7a008b8e..19323c5b89ce 100644
> --- a/Documentation/x86/index.rst
> +++ b/Documentation/x86/index.rst
> @@ -26,3 +26,4 @@ Linux x86 Support
>     microcode
>     resctrl_ui
>     usb-legacy-support
> +   i386/index



Thanks,
Mauro