[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Libreboot-dev] Document EHCI debug setup with BBB

From: Pi Van Den Cirkel
Subject: [Libreboot-dev] Document EHCI debug setup with BBB
Date: Thu, 9 Apr 2015 04:55:15 -0400

diff --git a/docs/install/bbb_setup.html b/docs/install/bbb_setup.html
index a7d2879..38d583e 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.

     <div class="section">
         <h1>EHCI debugging</h1>
-            <p>
-                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.
-            </p>
-            <p>
-                Work is in progress to implement this, and document
it in libreboot. These are just some preliminary notes.
-            </p>
-            <p>
-                <a
-                <a
-            </p>
+        <ol class="toc">
+            <li><a href="#FindUSBportonthetargetthatsupportsEHCIdebug">Find
+                    USB port on the target that supports EHCI debug</a></li>
+            <li><a href="#InitialsetupofBBBtoactasEHCIdebugdongle">Initial
+                    setup of BBB to act as EHCI debug dongle</a></li>
+            <li><a
+                    BBB's <tt>g_dbgp</tt> module (optional, but
highly recommended)</a></li>
+            <li><a href="#ConfigurelibrebootwithEHCIdebug">Configure
+                    libreboot with EHCI debug</a>
+                <ol>
+                    <li><a href="#SelectingHCDIndexandUSBDebugport">Selecting
+                            <tt>HCD Index</tt> and <tt>USB Debug
+                </ol></li>
+            <li><a href="#Howtogetthedebuglogs">How to get the debug
+                    logs</a></li>
+            <li><a
+                    EHCI Debug on the target's kernel (optional,
+            <li><a href="#References">References</a></li>
+        </ol>
+        <p>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
+            debug port.</p>
+        <p>This section explains step-by-step how to setup BBB as a
+            &#8220;USB EHCI debug dongle&#8221; and configure libreboot and the
+            linux kernel to stream logs to it (TODO: grub).</p>
+        <p>I will refer to three computers:</p>
+        <ul>
+            <li><b>host</b> - this is the computer you use, have
+                tools, compiler, Internet, etc</li>
+            <li><b>BBB</b> - Beaglebone Black (rev. B or higher, i
+                use rev. C)</li>
+            <li><b>target</b> - the computer you are trying to
+                install liberboot</li>
+        </ul>
+        <h3 id="FindUSBportonthetargetthatsupportsEHCIdebug">Find USB port
+            on the target that supports EHCI debug</h3>
+        <p>
+            Not all USB controllers support EHCI debug (see: <a
+                Debug Port</a> ). Even more, if a USB controller
supports EHCI debug, it
+            is available only <b>on a single port</b> that might or might
+            not be exposed externally.
+        </p>
+        <ul>
+            <li>You need running OS (GNU/Linux) on your target for this step
+                (If you&#8217;ve flashed libreboot and it does not
boot, you have to
+                flush back the stock bios)</li>
+            <li>You need USB memory stick (the data on it will not be
+                touched).</li>
+            <li>The EHCI debugging can not be done through external hub, BBB
+                must be connected directly to the debug port of the
controller (so, no
+                hubs)</li>
+        </ul>
+        <ul>
+            <li>Download<sup class="footnote"><a href="#___fn1">1</a></sup> <a
+                shell script.
+            </li>
+        </ul>
+        <ol>
+            <li>Plug the usb stick in the first available usb port</li>
+            <li>Run the script, you will get output similar to following:</li>
+<pre>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*
+            <li>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</li>
+            <li>Repeat the steps, plugging the USB stick in the next available
+                port</li>
+            <li>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).</li>
+        </ol>
+        <p>Remember (write down) for each port (external plug) you found
+            that supports debug: <b>PCI device id, the bus id, the
port number, and
+            the physical location of the usb plug.</b></p>
+        <p>If you do not find a match, you can not get debug over EHCI.
+            Sorry.</p>
+        <p id="___fn1" class="footnote">
+            <sup>1</sup> The guys from coreboot were talking about
including the
+            script in coreboot distribution (check the status).
+        </p>
+        <h3 id="InitialsetupofBBBtoactasEHCIdebugdongle">Initial setup of
+            BBB to act as EHCI debug dongle</h3>
+        <p>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:</p>
+        <ul>
+            <li>power supply (5V, 2A(10W) is sufficient).</li>
+            <li>an extra usb cable: A to mini-B</li>
+        </ul>
+        <p>
+            (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):
+        </p>
+<pre>ls /lib/modules/3.8.13-bone70/kernel/drivers/usb/gadget/g_dbgp.ko</pre>
+    <p>
+        Unload all other
+        g_*
+        modules:
+    </p>
+<pre># lsmod
+# rmmod g_multi
+        <p>
+            Then load
+            g_dbgp
+            :
+        </p>
+<pre># modprobe g_dbgp
+# lsmod # should show that g_dbgp is loaded, and no other g_*
+        <p>
+            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:
+        </p>
+<pre>Bus 001 Device 024: ID 0525:c0de Netchip Technology, Inc.</pre>
+        <p>If you see the device on the target, you are good to continue to
+            the next step.</p>
+        <h3 id="PatchBBBsgdbgpmoduleoptionalbuthighlyrecommended">
+            Patch BBB&#8217;s
+            g_dbgp
+            module (optional, but highly recommended)
+        </h3>
+        <p>
+            For the reasons why you need this, see: <a
+                href="";>EHCI
Gadget Debug</a>.<br />Make
+            sure that you have cross compiling environment for
+            arm-linux-gnueabihf
+            setup on your <em>host</em>.
+        </p>
+        <ul>
+            <li>On BBB: uname -r - this will give you version
+                number like 3.8.13-bone70 (I will refer to this as:
+                where mav=3.8, miv=13, lv=bone70
+            </li>
+            <li>Get the BBB kernel ready on your host for cross-compiling:</li>
+        </ul>
+<pre>$ cd $work_dir
+$ git clone
+$ cd kernel
+$ git checkout $mav (see above)
+$ ./
+$ wget\;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
+        <ul>
+            <li>Download the patch from <a
+            <li>tar -xf Ehci-debug-gadget-patches.tar.gz (will
+                create dir: usbdebug-gadget)</li>
+            <li>Note that there are two patches (patch_1 and patch_2) for each
+                of the two different version of the kernel (3.8 and
3.10). I will use
+                3.8. (If using kernel 3.12 patch_1 is not needed)</li>
+            <li>cd kernel (note that this is one more level: you
+                should be in $work_dir/kernel/kernel)</li>
+            <li>Apply the patches:</li>
+        </ul>
-from #coreboot
-&lt;tty0_&gt; 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
-&lt;stefanct&gt; tty0_: the coreboot config is clear to me... it
fails to show up in lsusb already
-&lt;tty0_&gt; on BBB, unload all the modules, then modprobe g_dbgp
-&lt;tty0_&gt; ... and when i siad lsusb, you do that on the target
system, not on BBB
-&lt;tty0_&gt; fchmmr, the kernel should be compiled with:
CONFIG_EARLY_PRINTK_DBGP=y to output on EHCI debug:
-&lt;tty0_&gt; stefanct, carldani: Note that the script has small bug
in the last for loop:  for dev in &quot;$debug_dmesg_devs&quot;; do
-&lt;stefanct&gt; tty0_: had ;)
-&lt;stefanct&gt; carldani: ok that's what i was expecting, thanks
-* ob-sed has quit (Ping timeout: 248 seconds)
-&lt;tty0_&gt; On the wiki there are links to two scripts, the updated
one has bug
-&lt;tty0_&gt; $debug_dmesg_devs should not be quoted
-&lt;tty0_&gt; ... if there are multiple controllers with debug, $dev
will be assgined &lt;controller1 controller2&gt; instead of iterating
throug each of them
-&lt;stefanct&gt; i have seen your conversation with mtjm earlier
-&lt;stefanct&gt; that's the reason why i was working on usb debug
today at all :)
-&lt;stefanct&gt; idwer: ping
-&lt;carldani&gt; tty0_: indeed, this was a bug.
-&lt;stefanct&gt; carldani: the most annoying thing about lsusb... the
debug device is actually missing from lsusb -t as i have found out
-&lt;tty0_&gt; 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
-&lt;stefanct&gt; tty0_: lsusb without the -t shows the debug
device... but doesnt print the port number
+git apply 
+git apply 
+make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- beaglebone_defconfig -j4@
+        <ul>
+            <li>Get your current BBB kernel config (from:
+                and copy it to your host as
+make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- oldconfig - all
default answers</pre>
+            <li>Set proper version number:
+                <ul>
+                    <li>On your host, edit $work_dir/kernel/kernel/.config
+                        (the one you&#8217;ve just copied from BBB),
find the line CONFIG_LOCALVERSION="&lt;something
+                            or empty&gt;" and change it to
+                        so it will look something like:
+                </ul>
+            </li>
+            <li>Also, make sure that: CONFIG_USB_G_DBGP=m (If
+                not, make menuconfig, and set @Device Drivers-&gt; USB
+                    Support -&gt; USB Gadget Support -&gt; EHCI Debug
Device Gadget=m</li>
+            <li>Build the module:</li>
+        </ul>
+$ make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j4 (is it
possoble to build only the gadget modules)
+$ mkdir ../tmp &amp;&amp; make ARCH=arm
CROSS_COMPILE=arm-linux-gnueabihf- INSTALL_MOD_PATH=../tmp
+        <ul>
+            <li>on BBB, backup
+                (i.e. mv
+                    /lib/modules/3.8.13-bone70/kernel/drivers/usb/gadget $HOME)
+            </li>
+            <li>copy the freshly compiled usb/gadget dir to
+            <li>restart BBB</li>
+            <li>Remove all g_* modules (rmmod
+                    g_&lt;&gt;)
+            </li>
+            <li>modprobpe g_dbgp</li>
+        </ul>
+        <h3 id="ConfigurelibrebootwithEHCIdebug">Configure libreboot with
+            EHCI debug</h3>
+        <p>
+            Libreboot(coreboot) should be configured with debug
turned on and to
+            push debug messages to the EHCI debug port.<br />If you&#8217;ve
+            downloaded the binary distribution, you can check if it is properly
+            configured in the following way:
+        </p>
+        <ul>
+            <li>Go to the libreboot dist root directory cd
+                    $libreboot_bin</li>
+            <li>Locate the rom image for your target (I will call it:
+            </li>
+            <li>Running the following command will extract the config in a
+                file ./my_config:
+            </li>
+        </ul>
+./cbfstool/i686/cbfstool $img_path extract -n config -f ./my_config
+        <ul>
+            <li>Make sure that the following params in the config are set as
+                following:</li>
+        </ul>
+CONFIG_USBDEBUG=y (Generic Drivers -&gt; USB 2.0 EHCI debug dongle support)
+CONFIG_USBDEBUG_IN_ROMSTAGE=y (Generic Drivers -&gt; Enable early
(pre-RAM) usbdebug)
+CONFIG_USBDEBUG_HCD_INDEX=&lt;HCD Index of usb controller - see
below&gt; (Generic Drivers -&gt; Index for EHCI controller to use with
+CONFIG_USBDEBUG_DEFAULT_PORT=&lt;USB Debug port - see below&gt;
(Generic Drivers -&gt; Default USB port to use as Debug Port)
+        <p>
+            The following three are behind radio button in the menu.
Only the first
+            one<sup class="footnote"><a href="#___fn2">2</a></sup>
should be =    y
+        </p>
+USBDEBUG_DONGLE_STD=y                       (Generic Drivers -&gt;
Type of dongle (Net20DC or compatible) -&gt; Net20DC or compatible)
+CONFIG_USBDEBUG_DONGLE_BEAGLEBONE=n         (Generic Drivers -&gt;
Type of dongle (Net20DC or compatible) -&gt; BeagleBone)
Type of dongle (Net20DC or compatible) -&gt; BeagleBone Black)
+        <p id="___fn2" class="footnote">
+            <sup>2</sup> 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 <a
+            (also tested/verified).
+        </p>
+        <p>
+            Then:<br />
+CONFIG_CONSOLE_USB=y (Console -&gt; USB dongle console output)
+        </p>
+        <p>
+            Also
+            Debugging ---&gt; Output verbose XYZ
+            ) (<b>FIXME</b> somebody verify these):
+        </p>
+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)
+        <p>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(<b>FIXME: link</b> about compiling libreboot.</p>
+        <h4 id="SelectingHCDIndexandUSBDebugport">
+            Selecting
+            HCD Index
+            and
+            USB Debug port
+        </h4>
+        <p>
+            This applies (and works) only if the USB controller that
supports debug
+            (found in the first section) is from Intel.<br />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.
+        </p>
+        <p>
+            If the externally exposed port is on a bus with
+            PCI ID == 0000:00:1a.0
+            then for
+            choose 2, otherwise choose 0
+            .
+        </p>
+        <p>
+            For
+            choose the port from the first section that correspond to the
+            PCI ID
+        </p>
+        <p>
+            Notes:<br />The above is based on the implementation of
+            coreboot/src/southbridge/intel/common/usb_debug.c :
+            .<br />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).
+        </p>
+        <ul>
+            <li>On T500 (with switchable GPU) the debug ports for both intel
+                controllers is exposed.</li>
+            <li>On x200t the debug ports for both intel controllers is
+                exposed.</li>
+        </ul>
+        <h3 id="Howtogetthedebuglogs">How to get the debug logs</h3>
+        <ul>
+            <li>Plug the USB cable in the target&#8217;s debug port (the one
+                you found in step 1) and BBB&#8217;s mini-B USB</li>
+            <li>Make sure no other then g_dbgp of the g_*
+                modules is loaded on your BBB
+            </li>
+            <li>On the BBB:</li>
+        </ul>
+stty -icrnl -inlcr -F /dev/ttyGS0
+cat /dev/ttyGS0
+        <ul>
+            <li>Power on the target with libreboot</li>
+            <li>You should see debug logs comming on your BBB console</li>
+        </ul>
+        <p>
+            Note that this is not permanent on BBB, if you reboot it,
you have to
+            rmmod g_*
+            and
+            modprobe g_dbgp
+        </p>
+        <h3 id="EnebleEHCIDebugonthetargetskerneloptionalrecommended">Eneble
+            EHCI Debug on the target&#8217;s kernel (optional,
+        <p>You have to know how to compile kernel for your target.</p>
+        <ol>
+            <li>Check if early debugging is already enabled: grep
+                    CONFIG_EARLY_PRINTK_DBGP /boot/config-&lt;ver&gt;</li>
+            <li>If enabled, you do not have to compile the kernel (skip this
+                step). Otherwise, prepare kernel source for your
distribution and
+                select (Kernel hacking -&gt; Early printk via EHCI debug
+                    port). Compile and install the new kernel.
+            </li>
+            <li>Edit your grub configuration and add following to the kenel
+                parameters<sup class="footnote"><a
+                class="footnote"><a href="#___fn21">21</a></sup>:
+                Also, try: earlyprintk=dbgp&lt;N&gt;,keep where N
+                is the debug port id if the first does not work.
+            </li>
+        </ol>
+        <h3 id="References">References</h3>
+        <p id="___fn10" class="footnote">
+            <sup>10</sup> <a
+                Debug Port</a>
+        </p>
+        <p id="___fn11" class="footnote">
+            <sup>11</sup> <a
+                EHCI debug gadget demonstration</a>
+        </p>
+        <p id="___fn12" class="footnote">
+            <sup>12</sup> <a
+                Gadget Debug</a>
+        </p>
+        <p id="___fn13" class="footnote">
+            <sup>13</sup> <a
+        </p>
+        <p id="___fn14" class="footnote">
+            <sup>14</sup> <a
+                the BeagleBone Black Kernel</a>
+        </p>
+        <p id="___fn15" class="footnote">
+            <sup>15</sup>
+        </p>
+        <p id="___fn16" class="footnote">
+            <sup>16</sup>
+        </p>
+        <p id="___fn17" class="footnote">
+            <sup>17</sup> <a
+                BBB Kernel</a>
+        </p>
+        <p id="___fn18" class="footnote">
+            <sup>18</sup>
+        </p>
+        <p id="___fn19" class="footnote">
+            <sup>19</sup> <a
+                USB at the Hardware/Software Interface</a>
+        </p>
+        <p id="___fn20" class="footnote">
+            <sup>20</sup>
+        </p>
+        <p id="___fn21" class="footnote">
+            <sup>21</sup>
+        </p>
+        <p>
+            <b>TODO</b>:
+        </p>
+        <ol>
+            <li>grub does not send messages to EHCI debug. Investigate.</li>
+            <li>The section &#8220;Configure libreboot with EHCI debug&#8221;
+                can be skipped/simplified if a common configuration
works for all
+                relevant targets is selected as defualt</li>
+            <li>Patch and compule g_dbgp on BBB instead cross-compile</li>
+            <li>Find a simple way to send debug messages from targets
+        </ol>

     <div class="section">

reply via email to

[Prev in Thread] Current Thread [Next in Thread]