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@xxxxxxxxx> 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@xxxxxxxxx>
> > ---
> > .../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@xxxxxxxxxxxxxxx
> > 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
