From bb1e8d89b5083400b7a0e5635285d6c25114762d Mon Sep 17 00:00:00 2001 From: opdecirkel Date: Thu, 09 Apr 2015 04:37:55 -0400 Subject: docs/install/bbb_setup.html: EHCI Debug logging setup guide --- diff --git a/docs/install/bbb_setup.html b/docs/install/bbb_setup.html index a7d2879..19a8989 100644 --- a/docs/install/bbb_setup.html +++ b/docs/install/bbb_setup.html @@ -384,49 +384,440 @@ Note: flashrom can never write if the flash chip isn't found automatically.
-

EHCI debugging

- -

- Some libreboot systems lack serial ports, so you have to use the debug port (USB) instead. - The BeagleBone can be configured for this. It may involve compiling a patched kernel. -

- -

- Work is in progress to implement this, and document it in libreboot. These are just some preliminary notes. -

- -

- http://www.coreboot.org/EHCI_Debug_Port - http://www.coreboot.org/EHCI_Gadget_Debug -

- +
    +
  1. Find + USB port on the target that supports EHCI debug
    2. +
  2. Initial + setup of BBB to act as EHCI debug dongle
    3. +
  3. Patch + BBB's g_dbgp module (optional, but highly recommended)
    4. +
  4. Configure + libreboot with EHCI debug +
      +
    1. Selecting + HCD Index and USB Debug port
      2. +
    5. +
  5. How to get the debug + logs
    6. +
  6. Eneble + EHCI Debug on the target's kernel (optional, recommended)
    7. +
  7. References
    8. +
+

If your computer does not boot after installing libreboot, it is + very useful to get debug logs from it, from the payload (grub) and/or + the kernel (if gets to there). All of them stream debug logs on the + available serial (RS-232) by default. However, most of todays laptops + lack RS-232 port. The other option is to stream the logs to USB EHCI + debug port.

+

This section explains step-by-step how to setup BBB as a + “USB EHCI debug dongle” and configure libreboot and the + linux kernel to stream logs to it (TODO: grub).

+

I will refer to three computers:

+ +

Find USB port + on the target that supports EHCI debug

+

+ Not all USB controllers support EHCI debug (see: EHCI + Debug Port ). Even more, if a USB controller supports EHCI debug, it + is available only on a single port that might or might + not be exposed externally. +

+ + +
    +
  1. Plug the usb stick in the first available usb port
    2. +
  2. Run the script, you will get output similar to following:
    3. +
    The following PCI devices support a USB debug port (says lspci): 0000:00:1a.0 0000:00:1d.0
+The following PCI devices support a USB debug port (says the kernel): 0000:00:1a.0 0000:00:1d.0
+*PCI device 0000:00:1a.0, USB bus 3, USB physical port 1*
+*PCI device 0000:00:1d.0, USB bus 4, USB physical port 2*
+Currently connected high-speed devices:
+/:  Bus 04.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M
+	|__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/8p, 480M
+		|__ Port 7: Dev 14, If 0, Class=Hub, Driver=hub/4p, 480M
+			|__ Port 1: Dev 15, If 0, Class=Hub, Driver=hub/4p, 480M
+			|__ Port 3: Dev 17, If 0, Class=Hub, Driver=hub/2p, 480M
+			|__ Port 4: Dev 18, If 0, Class=Hub, Driver=hub/4p, 480M
+/:  Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M
+	|__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/6p, 480M
+/:  *Bus 01*.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/4p, 480M
+	|__ *Port 3: Dev 31, If 0, Class=Mass Storage, Driver=usb-storage, 480M*
+
    +
  3. The buses the support debug are Bus 3 (0000:00:1a.0) on Port 1 + and Bus 4 (0000:00:1d.0) on port 2. Your usb stick is plugged on Bus + 1, Port 3
    4. +
  4. Repeat the steps, plugging the USB stick in the next available + port
    5. +
  5. Go through all available ports and remember(write down) those + for which bus/port of the usb stick matches one of the bus/port that + support debug (bold).
    6. +
+

Remember (write down) for each port (external plug) you found + that supports debug: PCI device id, the bus id, the port number, and + the physical location of the usb plug.

+

If you do not find a match, you can not get debug over EHCI. + Sorry.

+

+ 1 The guys from coreboot were talking about including the + script in coreboot distribution (check the status). +

+

Initial setup of + BBB to act as EHCI debug dongle

+

BBB must be powered with a barrel power connector since the + mini-B USB plug will be used for the EHCI debug stream. So you will + need:

+ +

+ (On BBB) The linux kernel includes module (g_dbgp that enables one of the usb ports on a computer to behave as EHCI + debug dongle. Make sure you have this module available on your BBB + (Debian 7.8 that comes with BBB should have it), if not, you should + compile it yourself (see next section): +

+
ls /lib/modules/3.8.13-bone70/kernel/drivers/usb/gadget/g_dbgp.ko
+

+ Unload all other + g_* + modules: +

+
# lsmod
+# rmmod g_multi
+...
+
+

+ Then load + g_dbgp + : +

+
# modprobe g_dbgp
+# lsmod # should show that g_dbgp is loaded, and no other g_*
+
+

+ Plug the mini-B side of the USB cable in your BBB and the A side in + your target. Then one of the usb devices on your target (with + lsusb + ) should be: +

+
Bus 001 Device 024: ID 0525:c0de Netchip Technology, Inc.
+

If you see the device on the target, you are good to continue to + the next step.

+

+ Patch BBB’s + g_dbgp + module (optional, but highly recommended) +

+

+ For the reasons why you need this, see: EHCI Gadget Debug.
Make + sure that you have cross compiling environment for + arm-linux-gnueabihf + setup on your host. +

+ +
$ cd $work_dir
+$ git clone https://github.com/beagleboard/kernel.git
+$ cd kernel
+$ git checkout $mav (see above)
+$ ./patch.sh
+$ wget http://arago-project.org/git/projects/?p=am33x-cm3.git\;a=blob_plain\;f=bin/am335x-pm-firmware.bin\;hb=HEAD -O kernel/firmware/am335x-pm-firmware.bin
+$ cp configs/beaglebone kernel/arch/arm/configs/beaglebone_defconfig
+
+ 
-from #coreboot
-<tty0_> stefanct,  1) plug the the BBB to a running system first and make sure you see it as "Netchip" (with lsusb).  if that is correct (i.e you have BBB > ver1 ) , you have to rebuild coreboot/libreboot with Net20DB instead of BBB as debug dongle
-<stefanct> tty0_: the coreboot config is clear to me... it fails to show up in lsusb already
-<tty0_> on BBB, unload all the modules, then modprobe g_dbgp
-<tty0_> ... and when i siad lsusb, you do that on the target system, not on BBB
-
-<tty0_> fchmmr, the kernel should be compiled with: CONFIG_EARLY_PRINTK_DBGP=y to output on EHCI debug: https://wiki.ubuntu.com/Kernel/Debugging/USBearlyprintk
-
-<tty0_> stefanct, carldani: Note that the script has small bug in the last for loop:  for dev in "$debug_dmesg_devs"; do ...
-<stefanct> tty0_: had ;)
-<stefanct> carldani: ok that's what i was expecting, thanks
-* ob-sed has quit (Ping timeout: 248 seconds)
-<tty0_> On the wiki there are links to two scripts, the updated one has bug
-<tty0_> $debug_dmesg_devs should not be quoted
-<tty0_> ... if there are multiple controllers with debug, $dev will be assgined <controller1 controller2> instead of iterating throug each of them
-<stefanct> i have seen your conversation with mtjm earlier
-<stefanct> that's the reason why i was working on usb debug today at all :)
-<stefanct> idwer: ping
-<carldani> tty0_: indeed, this was a bug.
-<stefanct> carldani: the most annoying thing about lsusb... the debug device is actually missing from lsusb -t as i have found out today
-<tty0_> It shows only ports that have something attached to them, because of that you have to go with usb stick through all the ports and run the script each time
-<stefanct> tty0_: lsusb without the -t shows the debug device... but doesnt print the port number
-
+git apply ../usbdebug-gadget/v3.8-debug-gadget/0001-usb-dbgp-gadget-Fix-re-connecting-after-USB-disconne.patch
+git apply ../usbdebug-gadget/v3.8-debug-gadget/0002-usb-serial-gadget-no-TTY-hangup-on-USB-disconnect-WI.patch
+;
+make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- beaglebone_defconfig -j4@
- + +
+$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j4 (is it possoble to build only the gadget modules)
+$ mkdir ../tmp && make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- INSTALL_MOD_PATH=../tmp modules_install
+
+ +

Configure libreboot with + EHCI debug

+

+ Libreboot(coreboot) should be configured with debug turned on and to + push debug messages to the EHCI debug port.
If you’ve + downloaded the binary distribution, you can check if it is properly + configured in the following way: +

+ +
+./cbfstool/i686/cbfstool $img_path extract -n config -f ./my_config
+
+ +
+CONFIG_USBDEBUG=y (Generic Drivers -> USB 2.0 EHCI debug dongle support)
+CONFIG_USBDEBUG_IN_ROMSTAGE=y (Generic Drivers -> Enable early (pre-RAM) usbdebug)
+CONFIG_USBDEBUG_HCD_INDEX=<HCD Index of usb controller - see below> (Generic Drivers -> Index for EHCI controller to use with usbdebug)
+CONFIG_USBDEBUG_DEFAULT_PORT=<USB Debug port - see below> (Generic Drivers -> Default USB port to use as Debug Port)
+
+

+ The following three are behind radio button in the menu. Only the first + one2 should be = y +

+
+USBDEBUG_DONGLE_STD=y                       (Generic Drivers -> Type of dongle (Net20DC or compatible) -> Net20DC or compatible)
+CONFIG_USBDEBUG_DONGLE_BEAGLEBONE=n         (Generic Drivers -> Type of dongle (Net20DC or compatible) -> BeagleBone)
+CONFIG_USBDEBUG_DONGLE_BEAGLEBONE_BLACK=n   (Generic Drivers -> Type of dongle (Net20DC or compatible) -> BeagleBone Black)
+
+

+ 2 The g_dbgp module on BeagleBone Black (Rev. C) reports it self as Net20DC, the + other options are for older BB(B) - ver1. This is documented here + (also tested/verified). +

+

+ Then:
+

+CONFIG_CONSOLE_USB=y (Console -> USB dongle console output)
+
+

+

+ Also + Debugging ---> Output verbose XYZ + ) (FIXME somebody verify these): +

+
+CONFIG_DEBUG_CBFS=y (Output verbose CBFS debug messages )
+CONFIG_HAVE_DEBUG_RAM_SETUP=y (??? What/where is this)
+CONFIG_DEBUG_RAM_SETUP=y (Output verbose RAM init debug messages)
+CONFIG_DEBUG_SMI=y      (Output verbose SMI debug messages)
+CONFIG_DEBUG_ACPI=y     (Output verbose ACPI debug messages )
+CONFIG_DEBUG_USBDEBUG=y (Output verbose USB 2.0 EHCI debug dongle messages)
+
+

If some of the above mentioned configuration options are not as + specified, you have to configure and compile libreboot yourself. Please + refer to the doc(FIXME: link about compiling libreboot.

+

+ Selecting + HCD Index + and + USB Debug port +

+

+ This applies (and works) only if the USB controller that supports debug + (found in the first section) is from Intel.
If the PCI ID of the + port you found in the first section is + 0000:00:1a.0 + or + 0000:00:1d.0 + , you are ok. Otherwise you have to try without guarantee that will + work. +

+

+ If the externally exposed port is on a bus with + PCI ID == 0000:00:1a.0 + then for + CONFIG_USBDEBUG_HCD_INDEX + choose 2, otherwise choose 0 + . +

+

+ For + CONFIG_USBDEBUG_DEFAULT_PORT + choose the port from the first section that correspond to the + PCI ID +

+

+ Notes:
The above is based on the implementation of + coreboot/src/southbridge/intel/common/usb_debug.c : pci_ehci_dbg_dev() + .
This is enough as it applies for the supported GM45/G45 + Thinkpads. coreboot support some other contollers too, but they are + irellevent for libreboot (for now). +

+ +

How to get the debug logs

+ +
+stty -icrnl -inlcr -F /dev/ttyGS0
+cat /dev/ttyGS0
+
+ +

+ Note that this is not permanent on BBB, if you reboot it, you have to + rmmod g_* + and + modprobe g_dbgp +

+

Eneble + EHCI Debug on the target’s kernel (optional, recommended)

+

You have to know how to compile kernel for your target.

+
    +
  1. Check if early debugging is already enabled: grep + CONFIG_EARLY_PRINTK_DBGP /boot/config-<ver>
    2. +
  2. If enabled, you do not have to compile the kernel (skip this + step). Otherwise, prepare kernel source for your distribution and + select (Kernel hacking -> Early printk via EHCI debug + port). Compile and install the new kernel. +
    3. +
  3. Edit your grub configuration and add following to the kenel + parameters2021: earlyprintk=dbgp,keep. + Also, try: earlyprintk=dbgp<N>,keep where N + is the debug port id if the first does not work. +
    4. +
+

References

+

+ 10 EHCI + Debug Port +

+

+ 11 coreboot + EHCI debug gadget demonstration +

+

+ 12 EHCI + Gadget Debug +

+

+ 13 Ehci-debug-gadget-patches.tar.gz +

+

+ 14 Compiling + the BeagleBone Black Kernel +

+

+ 15 + http://dumb-looks-free.blogspot.ca/2014/06/beaglebone-black-bbb-compile-kernel.html +

+

+ 16 + http://dumb-looks-free.blogspot.fr/2014/06/beaglebone-black-bbb-kernal-headers.html +

+

+ 17 Building + BBB Kernel +

+

+ 18 + http://komposter.com.ua/documents/USB-2.0-Debug-Port%28John-Keys%29.pdf +

+

+ 19 Exploring + USB at the Hardware/Software Interface +

+

+ 20 + https://www.kernel.org/doc/Documentation/x86/earlyprintk.txt +

+

+ 21 https://wiki.ubuntu.com/Kernel/Debugging/USBearlyprintk +

+

+ TODO: +

+
    +
  1. grub does not send messages to EHCI debug. Investigate.
    2. +
  2. The section “Configure libreboot with EHCI debug” + can be skipped/simplified if a common configuration works for all + relevant targets is selected as defualt
    3. +
  3. Patch and compule g_dbgp on BBB instead cross-compile
    4. +
  4. Find a simple way to send debug messages from targets userland
    5. +
@@ -434,6 +825,7 @@ from #coreboot

Copyright © 2014, 2015 Francis Rowe <info@gluglug.org.uk>
Copyright © 2015 Patrick "P. J." McDermott <pj@pehjota.net>
+ Copyright © 2015 Pi Van Den Cirkel This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. A copy of the license can be found at ../license.txt.

-- cgit v0.9.1