152 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3============4Early Printk5============6 7Mini-HOWTO for using the earlyprintk=dbgp boot option with a8USB2 Debug port key and a debug cable, on x86 systems.9 10You need two computers, the 'USB debug key' special gadget and11two USB cables, connected like this::12 13 [host/target] <-------> [USB debug key] <-------> [client/console]14 15Hardware requirements16=====================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 in21 the lspci -vvv output::22 23 # lspci -vvv24 ...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 T6127 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: 030 Interrupt: pin D routed to IRQ 1931 Region 0: Memory at fe227000 (32-bit, non-prefetchable) [size=1K]32 Capabilities: [50] Power Management version 233 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=00a036 ^^^^^^^^^^^ <==================== [ HERE ]37 Kernel driver in use: ehci_hcd38 Kernel modules: ehci-hcd39 ...40 41 .. note::42 If your system does not list a debug port capability then you probably43 won't be able to use the USB debug key.44 45 b) You also need a NetChip USB debug cable/key:46 47 http://www.plxtech.com/products/NET2000/NET20DC/default.asp48 49 This is a small blue plastic connector with two USB connections;50 it draws power from its USB connections.51 52 c) You need a second client/console system with a high speed USB 2.0 port.53 54 d) The NetChip device must be plugged directly into the physical55 debug port on the "host/target" system. You cannot use a USB hub in56 between the physical debug port and the "host/target" system.57 58 The EHCI debug controller is bound to a specific physical USB59 port and the NetChip device will only work as an early printk60 device in this port. The EHCI host controllers are electrically61 wired such that the EHCI debug controller is hooked up to the62 first physical port and there is no way to change this via software.63 You can find the physical port through experimentation by trying64 each physical port on the system and rebooting. Or you can try65 and use lsusb or look at the kernel info messages emitted by the66 usb stack when you plug a usb device into various ports on the67 "host/target" system.68 69 Some hardware vendors do not expose the usb debug port with a70 physical connector and if you find such a device send a complaint71 to the hardware vendor, because there is no reason not to wire72 this port into one of the physically accessible ports.73 74 e) It is also important to note, that many versions of the NetChip75 device require the "client/console" system to be plugged into the76 right hand side of the device (with the product logo facing up and77 readable left to right). The reason being is that the 5 volt78 power supply is taken from only one side of the device and it79 must be the side that does not get rebooted.80 81Software requirements82=====================83 84 a) On the host/target system:85 86 You need to enable the following kernel config option::87 88 CONFIG_EARLY_PRINTK_DBGP=y89 90 And you need to add the boot command line: "earlyprintk=dbgp".91 92 .. note::93 If you are using Grub, append it to the 'kernel' line in94 /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 are96 using Grub2 on an EFI firmware system, append it to the 'linux'97 or 'linuxefi' line in /boot/grub2/grub.cfg or98 /boot/efi/EFI/<distro>/grub.cfg.99 100 On systems with more than one EHCI debug controller you must101 specify the correct EHCI debug controller number. The ordering102 comes from the PCI bus enumeration of the EHCI controllers. The103 default with no number argument is "0" or the first EHCI debug104 controller. To use the second EHCI debug controller, you would105 use the command line: "earlyprintk=dbgp1"106 107 .. note::108 normally earlyprintk console gets turned off once the109 regular console is alive - use "earlyprintk=dbgp,keep" to keep110 this channel open beyond early bootup. This can be useful for111 debugging crashes under Xorg, etc.112 113 b) On the client/console system:114 115 You should enable the following kernel config option::116 117 CONFIG_USB_SERIAL_DEBUG=y118 119 On the next bootup with the modified kernel you should120 get a /dev/ttyUSBx device(s).121 122 Now this channel of kernel messages is ready to be used: start123 your favorite terminal emulator (minicom, etc.) and set124 it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to125 see the raw output.126 127 c) On Nvidia Southbridge based systems: the kernel will try to probe128 and find out which port has a debug device connected.129 130Testing131=======132 133You can test the output by using earlyprintk=dbgp,keep and provoking134kernel messages on the host/target system. You can provoke a harmless135kernel message by for example doing::136 137 echo h > /proc/sysrq-trigger138 139On the host/target system you should see this help line in "dmesg" output::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 143On the client/console system do::144 145 cat /dev/ttyUSB0146 147And you should see the help line above displayed shortly after you've148provoked it on the host system.149 150If it does not work then please ask about it on the linux-kernel@vger.kernel.org151mailing list or contact the x86 maintainers.152