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

From: Changbin Du
Date: Wed May 08 2019 - 11:23:50 EST

Next message: Changbin Du: "[PATCH v4 08/27] Documentation: x86: convert zero-page.txt to reST"
Previous message: Steven Rostedt: "Re: [RFC PATCH v6 4/6] tracing/probe: Support user-space dereference"
In reply to: Changbin Du: "[PATCH v4 06/27] Documentation: x86: convert entry_64.txt to reST"
Next in thread: Changbin Du: "[PATCH v4 08/27] Documentation: x86: convert zero-page.txt to reST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
---
.../x86/{earlyprintk.txt => earlyprintk.rst} | 122 ++++++++++--------
Documentation/x86/index.rst | 1 +
2 files changed, 67 insertions(+), 56 deletions(-)
rename Documentation/x86/{earlyprintk.txt => earlyprintk.rst} (51%)

diff --git a/Documentation/x86/earlyprintk.txt b/Documentation/x86/earlyprintk.rst
similarity index 51%
rename from Documentation/x86/earlyprintk.txt
rename to Documentation/x86/earlyprintk.rst
index 46933e06c972..11307378acf0 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.

- 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,29 +71,31 @@ 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
- /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.)
+ .. 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.

On systems with more than one EHCI debug controller you must
specify the correct EHCI debug controller number. The ordering
@@ -96,14 +104,15 @@ and two USB cables, connected like this:
controller. To use the second EHCI debug controller, you would
use the command line: "earlyprintk=dbgp1"

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

- 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 +124,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 0e3e73458738..d9ccc0f39279 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -13,3 +13,4 @@ x86-specific Documentation
exception-tables
kernel-stacks
entry_64
+ earlyprintk
--
2.20.1

Next message: Changbin Du: "[PATCH v4 08/27] Documentation: x86: convert zero-page.txt to reST"
Previous message: Steven Rostedt: "Re: [RFC PATCH v6 4/6] tracing/probe: Support user-space dereference"
In reply to: Changbin Du: "[PATCH v4 06/27] Documentation: x86: convert entry_64.txt to reST"
Next in thread: Changbin Du: "[PATCH v4 08/27] Documentation: x86: convert zero-page.txt to reST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]