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

[Changbin Du <changbin.du@gmail.com>]

On Sat, Apr 27, 2019 at 02:17:39PM -0300, Mauro Carvalho Chehab wrote:
> 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.
>
Fixed.

> >  
> > - 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?
>
I missed this block. Now fixed.

> 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

-- 
Cheers,
Changbin Du