Documentation: x86: convert earlyprintk.txt to reST

.. SPDX-License-Identifier: GPL-2.0

============

Early Printk

============

Mini-HOWTO for using the earlyprintk=dbgp boot option with a

USB2 Debug port key and a debug cable, on x86 systems.

You need two computers, the 'USB debug key' special gadget and

and two USB cables, connected like this:

and two USB cables, connected like this::

  [host/target] <-------> [USB debug key] <-------> [client/console]

1. There are a number of specific hardware requirements:

Hardware requirements

=====================

 a.) Host/target system needs to have USB debug port capability.

  a) Host/target system needs to have USB debug port capability.

     You can check this capability by looking at a 'Debug port' bit in

 the lspci -vvv output:

     the lspci -vvv output::

       # lspci -vvv

       ...

               Kernel modules: ehci-hcd

       ...

( If your system does not list a debug port capability then you probably

  won't be able to use the USB debug key. )

     .. note::

       If your system does not list a debug port capability then you probably

       won't be able to use the USB debug key.

 b.) You also need a NetChip USB debug cable/key:

  b) You also need a NetChip USB debug cable/key:

        http://www.plxtech.com/products/NET2000/NET20DC/default.asp

     This is a small blue plastic connector with two USB connections;

     it draws power from its USB connections.

 c.) You need a second client/console system with a high speed USB 2.0

     port.

  c) You need a second client/console system with a high speed USB 2.0 port.

 d.) The NetChip device must be plugged directly into the physical

  d) The NetChip device must be plugged directly into the physical

     debug port on the "host/target" system. You cannot use a USB hub in

     between the physical debug port and the "host/target" system.

     to the hardware vendor, because there is no reason not to wire

     this port into one of the physically accessible ports.

 e.) It is also important to note, that many versions of the NetChip

  e) It is also important to note, that many versions of the NetChip

     device require the "client/console" system to be plugged into the

     right hand side of the device (with the product logo facing up and

     readable left to right).  The reason being is that the 5 volt

     power supply is taken from only one side of the device and it

     must be the side that does not get rebooted.

2. Software requirements:

Software requirements

=====================

 a.) On the host/target system:

  a) On the host/target system:

    You need to enable the following kernel config option:

    You need to enable the following kernel config option::

      CONFIG_EARLY_PRINTK_DBGP=y

    And you need to add the boot command line: "earlyprintk=dbgp".

    (If you are using Grub, append it to the 'kernel' line in

    .. note::

      If you are using Grub, append it to the 'kernel' line in

      /etc/grub.conf.  If you are using Grub2 on a BIOS firmware system,

      append it to the 'linux' line in /boot/grub2/grub.cfg. If you are

      using Grub2 on an EFI firmware system, append it to the 'linux'

      or 'linuxefi' line in /boot/grub2/grub.cfg or

     /boot/efi/EFI/<distro>/grub.cfg.)

      /boot/efi/EFI/<distro>/grub.cfg.

    On systems with more than one EHCI debug controller you must

    specify the correct EHCI debug controller number.  The ordering

    controller.  To use the second EHCI debug controller, you would

    use the command line: "earlyprintk=dbgp1"

    NOTE: normally earlyprintk console gets turned off once the

    .. note::

      normally earlyprintk console gets turned off once the

      regular console is alive - use "earlyprintk=dbgp,keep" to keep

      this channel open beyond early bootup. This can be useful for

      debugging crashes under Xorg, etc.

 b.) On the client/console system:

  b) On the client/console system:

    You should enable the following kernel config option:

    You should enable the following kernel config option::

      CONFIG_USB_SERIAL_DEBUG=y

    it up to use /dev/ttyUSB0 - or use a raw 'cat /dev/ttyUSBx' to

    see the raw output.

 c.) On Nvidia Southbridge based systems: the kernel will try to probe

  c) On Nvidia Southbridge based systems: the kernel will try to probe

     and find out which port has a debug device connected.

3. Testing that it works fine:

Testing

=======

You can test the output by using earlyprintk=dbgp,keep and provoking

kernel messages on the host/target system. You can provoke a harmless

   kernel message by for example doing:

kernel message by for example doing::

     echo h > /proc/sysrq-trigger

   On the host/target system you should see this help line in "dmesg" output:

On the host/target system you should see this help line in "dmesg" output::

     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)

   On the client/console system do:

On the client/console system do::

       cat /dev/ttyUSB0

   exception-tables

   kernel-stacks

   entry_64

   earlyprintk