GNU Linux-libre 4.19.211-gnu1
[releases.git] / Documentation / x86 / earlyprintk.txt
1
2 Mini-HOWTO for using the earlyprintk=dbgp boot option with a
3 USB2 Debug port key and a debug cable, on x86 systems.
4
5 You need two computers, the 'USB debug key' special gadget and
6 and two USB cables, connected like this:
7
8   [host/target] <-------> [USB debug key] <-------> [client/console]
9
10 1. There are a number of specific hardware requirements:
11
12  a.) Host/target system needs to have USB debug port capability.
13
14  You can check this capability by looking at a 'Debug port' bit in
15  the lspci -vvv output:
16
17  # lspci -vvv
18  ...
19  00:1d.7 USB Controller: Intel Corporation 82801H (ICH8 Family) USB2 EHCI Controller #1 (rev 03) (prog-if 20 [EHCI])
20          Subsystem: Lenovo ThinkPad T61
21          Control: I/O- Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- DisINTx-
22          Status: Cap+ 66MHz- UDF- FastB2B+ ParErr- DEVSEL=medium >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx-
23          Latency: 0
24          Interrupt: pin D routed to IRQ 19
25          Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K]
26          Capabilities: [50] Power Management version 2
27                  Flags: PMEClk- DSI- D1- D2- AuxCurrent=375mA PME(D0+,D1-,D2-,D3hot+,D3cold+)
28                  Status: D0 PME-Enable- DSel=0 DScale=0 PME+
29          Capabilities: [58] Debug port: BAR=1 offset=00a0
30                             ^^^^^^^^^^^ <==================== [ HERE ]
31          Kernel driver in use: ehci_hcd
32          Kernel modules: ehci-hcd
33  ...
34
35 ( If your system does not list a debug port capability then you probably
36   won't be able to use the USB debug key. )
37
38  b.) You also need a NetChip USB debug cable/key:
39
40         http://www.plxtech.com/products/NET2000/NET20DC/default.asp
41
42      This is a small blue plastic connector with two USB connections;
43      it draws power from its USB connections.
44
45  c.) You need a second client/console system with a high speed USB 2.0
46      port.
47
48  d.) The NetChip device must be plugged directly into the physical
49      debug port on the "host/target" system.  You cannot use a USB hub in
50      between the physical debug port and the "host/target" system.
51
52      The EHCI debug controller is bound to a specific physical USB
53      port and the NetChip device will only work as an early printk
54      device in this port.  The EHCI host controllers are electrically
55      wired such that the EHCI debug controller is hooked up to the
56      first physical port and there is no way to change this via software.
57      You can find the physical port through experimentation by trying
58      each physical port on the system and rebooting.  Or you can try
59      and use lsusb or look at the kernel info messages emitted by the
60      usb stack when you plug a usb device into various ports on the
61      "host/target" system.
62
63      Some hardware vendors do not expose the usb debug port with a
64      physical connector and if you find such a device send a complaint
65      to the hardware vendor, because there is no reason not to wire
66      this port into one of the physically accessible ports.
67
68  e.) It is also important to note, that many versions of the NetChip
69      device require the "client/console" system to be plugged into the
70      right hand side of the device (with the product logo facing up and
71      readable left to right).  The reason being is that the 5 volt
72      power supply is taken from only one side of the device and it
73      must be the side that does not get rebooted.
74
75 2. Software requirements:
76
77  a.) On the host/target system:
78
79     You need to enable the following kernel config option:
80
81       CONFIG_EARLY_PRINTK_DBGP=y
82
83     And you need to add the boot command line: "earlyprintk=dbgp".
84
85     (If you are using Grub, append it to the 'kernel' line in
86      /etc/grub.conf.  If you are using Grub2 on a BIOS firmware system,
87      append it to the 'linux' line in /boot/grub2/grub.cfg. If you are
88      using Grub2 on an EFI firmware system, append it to the 'linux'
89      or 'linuxefi' line in /boot/grub2/grub.cfg or
90      /boot/efi/EFI/<distro>/grub.cfg.)
91
92     On systems with more than one EHCI debug controller you must
93     specify the correct EHCI debug controller number.  The ordering
94     comes from the PCI bus enumeration of the EHCI controllers.  The
95     default with no number argument is "0" or the first EHCI debug
96     controller.  To use the second EHCI debug controller, you would
97     use the command line: "earlyprintk=dbgp1"
98
99     NOTE: normally earlyprintk console gets turned off once the
100     regular console is alive - use "earlyprintk=dbgp,keep" to keep
101     this channel open beyond early bootup. This can be useful for
102     debugging crashes under Xorg, etc.
103
104  b.) On the client/console system:
105
106     You should enable the following kernel config option:
107
108       CONFIG_USB_SERIAL_DEBUG=y
109
110     On the next bootup with the modified kernel you should
111     get a /dev/ttyUSBx device(s).
112
113     Now this channel of kernel messages is ready to be used: start
114     your favorite terminal emulator (minicom, etc.) and set
115     it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to
116     see the raw output.
117
118  c.) On Nvidia Southbridge based systems: the kernel will try to probe
119      and find out which port has a debug device connected.
120
121 3. Testing that it works fine:
122
123    You can test the output by using earlyprintk=dbgp,keep and provoking
124    kernel messages on the host/target system. You can provoke a harmless
125    kernel message by for example doing:
126
127      echo h > /proc/sysrq-trigger
128
129    On the host/target system you should see this help line in "dmesg" output:
130
131      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)
132
133    On the client/console system do:
134
135        cat /dev/ttyUSB0
136
137    And you should see the help line above displayed shortly after you've
138    provoked it on the host system.
139
140 If it does not work then please ask about it on the linux-kernel@vger.kernel.org
141 mailing list or contact the x86 maintainers.