Re: [PATCH 07/27] Documentation: x86: convert earlyprintk.txt to reST

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

Em Fri, 26 Apr 2019 23:31:30 +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/{earlyprintk.txt => earlyprintk.rst}  | 103 ++++++++++--------
>  Documentation/x86/index.rst                   |   1 +
>  2 files changed, 57 insertions(+), 47 deletions(-)
>  rename Documentation/x86/{earlyprintk.txt => earlyprintk.rst} (59%)
> 
> diff --git a/Documentation/x86/earlyprintk.txt b/Documentation/x86/earlyprintk.rst
> similarity index 59%
> rename from Documentation/x86/earlyprintk.txt
> rename to Documentation/x86/earlyprintk.rst
> index 46933e06c972..7714e32501ec 100644
> --- a/Documentation/x86/earlyprintk.txt
> +++ b/Documentation/x86/earlyprintk.rst
> @@ -1,52 +1,58 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============
> +Early Printk
> +============
>  
>  Mini-HOWTO for using the earlyprintk=dbgp boot option with a
>  USB2 Debug port key and a debug cable, on x86 systems.
>  
>  You need two computers, the 'USB debug key' special gadget and
> -and two USB cables, connected like this:
> +and two USB cables, connected like this::
>  
>    [host/target] <-------> [USB debug key] <-------> [client/console]
>  
> -1. There are a number of specific hardware requirements:
> -
> - a.) Host/target system needs to have USB debug port capability.
> -
> - You can check this capability by looking at a 'Debug port' bit in
> - the lspci -vvv output:
> -
> - # lspci -vvv
> - ...
> - 00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI])
> -         Subsystem: Lenovo ThinkPad T61
> -         Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx-
> -         Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
> -         Latency: 0
> -         Interrupt: pin D routed to IRQ 19
> -         Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K]
> -         Capabilities: [50] Power Management version 2
> -                 Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+)
> -                 Status: D0 PME-Enable- DSel=0 DScale=0 PME+
> -         Capabilities: [58] Debug port: BAR=1 offset=00a0
> +Hardware requirements
> +=====================
> +
> +  a) Host/target system needs to have USB debug port capability.
> +
> +     You can check this capability by looking at a 'Debug port' bit in
> +     the lspci -vvv output::
> +
> +       # lspci -vvv
> +       ...
> +       00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI])
> +               Subsystem: Lenovo ThinkPad T61
> +               Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx-
> +               Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
> +               Latency: 0
> +               Interrupt: pin D routed to IRQ 19
> +               Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K]
> +               Capabilities: [50] Power Management version 2
> +                       Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+)
> +                       Status: D0 PME-Enable- DSel=0 DScale=0 PME+
> +               Capabilities: [58] Debug port: BAR=1 offset=00a0
>                              ^^^^^^^^^^^ <==================== [ HERE ]
> -	 Kernel driver in use: ehci_hcd
> -         Kernel modules: ehci-hcd
> - ...
> +               Kernel driver in use: ehci_hcd
> +               Kernel modules: ehci-hcd
> +       ...
>  
> -( If your system does not list a debug port capability then you probably
> -  won't be able to use the USB debug key. )
> +     .. note::
> +       If your system does not list a debug port capability then you probably
> +       won't be able to use the USB debug key. )

You should remove the close parenthesis on the above line.

>  
> - b.) You also need a NetChip USB debug cable/key:
> +  b) You also need a NetChip USB debug cable/key:
>  
>          http://www.plxtech.com/products/NET2000/NET20DC/default.asp
>  
>       This is a small blue plastic connector with two USB connections;
>       it draws power from its USB connections.
>  
> - c.) You need a second client/console system with a high speed USB 2.0
> -     port.
> +  c) You need a second client/console system with a high speed USB 2.0 port.
>  
> - d.) The NetChip device must be plugged directly into the physical
> -     debug port on the "host/target" system.  You cannot use a USB hub in
> +  d) The NetChip device must be plugged directly into the physical
> +     debug port on the "host/target" system. You cannot use a USB hub in
>       between the physical debug port and the "host/target" system.
>  
>       The EHCI debug controller is bound to a specific physical USB
> @@ -65,24 +71,26 @@ and two USB cables, connected like this:
>       to the hardware vendor, because there is no reason not to wire
>       this port into one of the physically accessible ports.
>  
> - e.) It is also important to note, that many versions of the NetChip
> +  e) It is also important to note, that many versions of the NetChip
>       device require the "client/console" system to be plugged into the
>       right hand side of the device (with the product logo facing up and
>       readable left to right).  The reason being is that the 5 volt
>       power supply is taken from only one side of the device and it
>       must be the side that does not get rebooted.
>  
> -2. Software requirements:
> +Software requirements
> +=====================
>  
> - a.) On the host/target system:
> +  a) On the host/target system:
>  
> -    You need to enable the following kernel config option:
> +    You need to enable the following kernel config option::
>  
>        CONFIG_EARLY_PRINTK_DBGP=y
>  
>      And you need to add the boot command line: "earlyprintk=dbgp".
>  
> -    (If you are using Grub, append it to the 'kernel' line in
> +    .. note::
> +     If you are using Grub, append it to the 'kernel' line in
>      /etc/grub.conf.  If you are using Grub2 on a BIOS firmware system,
>      append it to the 'linux' line in /boot/grub2/grub.cfg. If you are
>      using Grub2 on an EFI firmware system, append it to the 'linux'
>      or 'linuxefi' line in /boot/grub2/grub.cfg or
>      /boot/efi/EFI/<distro>/grub.cfg.)

Same here: You should remove the close parenthesis on the above line.


>       /etc/grub.conf.  If you are using Grub2 on a BIOS firmware system,
>       append it to the 'linux' line in /boot/grub2/grub.cfg. If you are
>       using Grub2 on an EFI firmware system, append it to the 'linux'

Hmm... there is another note here:

     NOTE: normally earlyprintk console gets turned off once the
     regular console is alive - use "earlyprintk=dbgp,keep" to keep
     this channel open beyond early bootup. This can be useful for
     debugging crashes under Xorg, etc.

Why are you keeping it untouched?

After fixing the above:

Reviewed-by: 

> @@ -101,9 +109,9 @@ and two USB cables, connected like this:
>      this channel open beyond early bootup. This can be useful for
>      debugging crashes under Xorg, etc.
>  
> - b.) On the client/console system:
> +  b) On the client/console system:
>  
> -    You should enable the following kernel config option:
> +    You should enable the following kernel config option::
>  
>        CONFIG_USB_SERIAL_DEBUG=y
>  
> @@ -115,27 +123,28 @@ and two USB cables, connected like this:
>      it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to
>      see the raw output.
>  
> - c.) On Nvidia Southbridge based systems: the kernel will try to probe
> +  c) On Nvidia Southbridge based systems: the kernel will try to probe
>       and find out which port has a debug device connected.
>  
> -3. Testing that it works fine:
> +Testing
> +=======
>  
> -   You can test the output by using earlyprintk=dbgp,keep and provoking
> -   kernel messages on the host/target system. You can provoke a harmless
> -   kernel message by for example doing:
> +You can test the output by using earlyprintk=dbgp,keep and provoking
> +kernel messages on the host/target system. You can provoke a harmless
> +kernel message by for example doing::
>  
>       echo h > /proc/sysrq-trigger
>  
> -   On the host/target system you should see this help line in "dmesg" output:
> +On the host/target system you should see this help line in "dmesg" output::
>  
>       SysRq : HELP : loglevel(0-9) reBoot Crashdump terminate-all-tasks(E) memory-full-oom-kill(F) kill-all-tasks(I) saK show-backtrace-all-active-cpus(L) show-memory-usage(M) nice-all-RT-tasks(N) powerOff show-registers(P) show-all-timers(Q) unRaw Sync show-task-states(T) Unmount show-blocked-tasks(W) dump-ftrace-buffer(Z)
>  
> -   On the client/console system do:
> +On the client/console system do::
>  
>         cat /dev/ttyUSB0
>  
> -   And you should see the help line above displayed shortly after you've
> -   provoked it on the host system.
> +And you should see the help line above displayed shortly after you've
> +provoked it on the host system.
>  
>  If it does not work then please ask about it on the linux-kernel@vger.kernel.org
>  mailing list or contact the x86 maintainers.
> diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
> index 8a666c5abc85..7b8388ebd43d 100644
> --- a/Documentation/x86/index.rst
> +++ b/Documentation/x86/index.rst
> @@ -13,3 +13,4 @@ Linux x86 Support
>     exception-tables
>     kernel-stacks
>     entry_64
> +   earlyprintk



Thanks,
Mauro