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