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