linux/Documentation/x86/earlyprintk.rst
<<
>>
Prefs
   1.. SPDX-License-Identifier: GPL-2.0
   2
   3============
   4Early Printk
   5============
   6
   7Mini-HOWTO for using the earlyprintk=dbgp boot option with a
   8USB2 Debug port key and a debug cable, on x86 systems.
   9
  10You need two computers, the 'USB debug key' special gadget and
  11two USB cables, connected like this::
  12
  13  [host/target] <-------> [USB debug key] <-------> [client/console]
  14
  15Hardware 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
  36                            ^^^^^^^^^^^ <==================== [ HERE ]
  37               Kernel driver in use: ehci_hcd
  38               Kernel modules: ehci-hcd
  39       ...
  40
  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.
  44
  45  b) You also need a NetChip USB debug cable/key:
  46
  47        http://www.plxtech.com/products/NET2000/NET20DC/default.asp
  48
  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 physical
  55     debug port on the "host/target" system. You cannot use a USB hub in
  56     between the physical debug port and the "host/target" system.
  57
  58     The EHCI debug controller is bound to a specific physical USB
  59     port and the NetChip device will only work as an early printk
  60     device in this port.  The EHCI host controllers are electrically
  61     wired such that the EHCI debug controller is hooked up to the
  62     first physical port and there is no way to change this via software.
  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
  74  e) It is also important to note, that many versions of the NetChip
  75     device require the "client/console" system to be plugged into the
  76     right hand side of the device (with the product logo facing up and
  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.
  80
  81Software requirements
  82=====================
  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=y
  89
  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 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.
  99
 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
 103    default with no number argument is "0" or the first EHCI debug
 104    controller.  To use the second EHCI debug controller, you would
 105    use the command line: "earlyprintk=dbgp1"
 106
 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.
 112
 113  b) On the client/console system:
 114
 115    You should enable the following kernel config option::
 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
 127  c) On Nvidia Southbridge based systems: the kernel will try to probe
 128     and find out which port has a debug device connected.
 129
 130Testing
 131=======
 132
 133You can test the output by using earlyprintk=dbgp,keep and provoking
 134kernel messages on the host/target system. You can provoke a harmless
 135kernel message by for example doing::
 136
 137     echo h > /proc/sysrq-trigger
 138
 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/ttyUSB0
 146
 147And you should see the help line above displayed shortly after you've
 148provoked it on the host system.
 149
 150If it does not work then please ask about it on the linux-kernel@vger.kernel.org
 151mailing list or contact the x86 maintainers.
 152