iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation: x86: convert earlyprintk.txt to reST

Browse Source 
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>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Changbin Du 2019-05-08 23:21:21 +08:00 committed by Jonathan Corbet
parent c2dea5cda0
commit 4b13576002
2 changed files with 64 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
Documentation/x86/earlyprintk.txt → Documentation/x86/earlyprintk.rst
View File

@ -1,52 +1,58 @@
.. SPDX-License-Identifier: GPL-2.0
============
Early Printk
============
Mini-HOWTO for using the earlyprintk=dbgp boot option with a Mini-HOWTO for using the earlyprintk=dbgp boot option with a
USB2 Debug port key and a debug cable, on x86 systems. USB2 Debug port key and a debug cable, on x86 systems.
You need two computers, the 'USB debug key' special gadget and 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] [host/target] <-------> [USB debug key] <-------> [client/console]
1. There are a number of specific hardware requirements: Hardware requirements
=====================
a.) Host/target system needs to have USB debug port capability. a) Host/target system needs to have USB debug port capability.
You can check this capability by looking at a 'Debug port' bit in You can check this capability by looking at a 'Debug port' bit in
the lspci -vvv output: the lspci -vvv output::
# lspci -vvv # lspci -vvv
... ...
00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI]) 00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI])
Subsystem: Lenovo ThinkPad T61 Subsystem: Lenovo ThinkPad T61
Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx- 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- Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
Latency: 0 Latency: 0
Interrupt: pin D routed to IRQ 19 Interrupt: pin D routed to IRQ 19
Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K] Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K]
Capabilities: [50] Power Management version 2 Capabilities: [50] Power Management version 2
Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+) Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+)
Status: D0 PME-Enable- DSel=0 DScale=0 PME+ Status: D0 PME-Enable- DSel=0 DScale=0 PME+
Capabilities: [58] Debug port: BAR=1 offset=00a0 Capabilities: [58] Debug port: BAR=1 offset=00a0
^^^^^^^^^^^ <==================== [ HERE ] ^^^^^^^^^^^ <==================== [ HERE ]
Kernel driver in use: ehci_hcd Kernel driver in use: ehci_hcd
Kernel modules: ehci-hcd Kernel modules: ehci-hcd
... ...
( If your system does not list a debug port capability then you probably .. note::
won't be able to use the USB debug key. ) 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 http://www.plxtech.com/products/NET2000/NET20DC/default.asp
This is a small blue plastic connector with two USB connections; This is a small blue plastic connector with two USB connections;
it draws power from its USB connections. it draws power from its USB connections.
c.) You need a second client/console system with a high speed USB 2.0 c) You need a second client/console system with a high speed USB 2.0 port.
port.
d.) The NetChip device must be plugged directly into the physical 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 debug port on the "host/target" system. You cannot use a USB hub in
between the physical debug port and the "host/target" system. between the physical debug port and the "host/target" system.
The EHCI debug controller is bound to a specific physical USB 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 to the hardware vendor, because there is no reason not to wire
this port into one of the physically accessible ports. 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 device require the "client/console" system to be plugged into the
right hand side of the device (with the product logo facing up and 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 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 power supply is taken from only one side of the device and it
must be the side that does not get rebooted. 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 CONFIG_EARLY_PRINTK_DBGP=y
And you need to add the boot command line: "earlyprintk=dbgp". And you need to add the boot command line: "earlyprintk=dbgp".
(If you are using Grub, append it to the 'kernel' line in .. note::
/etc/grub.conf. If you are using Grub2 on a BIOS firmware system, If you are using Grub, append it to the 'kernel' line in
append it to the 'linux' line in /boot/grub2/grub.cfg. If you are /etc/grub.conf. If you are using Grub2 on a BIOS firmware system,
using Grub2 on an EFI firmware system, append it to the 'linux' append it to the 'linux' line in /boot/grub2/grub.cfg. If you are
or 'linuxefi' line in /boot/grub2/grub.cfg or using Grub2 on an EFI firmware system, append it to the 'linux'
/boot/efi/EFI/<distro>/grub.cfg.) 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 On systems with more than one EHCI debug controller you must
specify the correct EHCI debug controller number. The ordering 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 controller. To use the second EHCI debug controller, you would
use the command line: "earlyprintk=dbgp1" use the command line: "earlyprintk=dbgp1"
NOTE: normally earlyprintk console gets turned off once the .. note::
regular console is alive - use "earlyprintk=dbgp,keep" to keep normally earlyprintk console gets turned off once the
this channel open beyond early bootup. This can be useful for regular console is alive - use "earlyprintk=dbgp,keep" to keep
debugging crashes under Xorg, etc. 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 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 it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to
see the raw output. 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. 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 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 messages on the host/target system. You can provoke a harmless
kernel message by for example doing: kernel message by for example doing::
echo h > /proc/sysrq-trigger 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) 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 cat /dev/ttyUSB0
And you should see the help line above displayed shortly after you've And you should see the help line above displayed shortly after you've
provoked it on the host system. provoked it on the host system.
If it does not work then please ask about it on the linux-kernel@vger.kernel.org If it does not work then please ask about it on the linux-kernel@vger.kernel.org
mailing list or contact the x86 maintainers. mailing list or contact the x86 maintainers.

1
Documentation/x86/index.rst
View File

@ -13,3 +13,4 @@ x86-specific Documentation
exception-tables exception-tables
kernel-stacks kernel-stacks
entry_64 entry_64
earlyprintk