EHCI Debugging

EHCI Debugging can be used on mainboards without a serial console.

Identifying the Mainboard EHCI Debug port

• Download ehci_port_scanner.sh
• Run ehci_port_scanner.sh as root with a flash drive connected to the port you want to test
• If the script lists your flash drive under an available debugging port, you can use that USB port

Turning on the EHCI Debug console in coreboot

in make menuconfig:

Generic Drivers -> USB 2.0 EHCI debug dongle support (enabled)
Generic Drivers -> Index for EHCI controller to use with usbdebug (0) # Use 0 for the first available EHCI controller
Generic Drivers -> Default USB port to use as Debug Port (0) # Use 0 to auto-find the debugger
Generic Drivers -> Type of dongle (USB gadget driver or Net20DC)
Console -> USB dongle console output

Raspberry Pi Zero W

The Raspberry Pi Zero W can be used as a EHCI debugger. The required equipment for this tutorial is:

• Raspberry Pi Zero W with a MicroSD card
• A WPA2 WiFi Network
• A Micro-USB cable for power, connected to PWR-IN (RPI) and a power source (5V 2A)
• A Micro-USB cable for debugging, connected to USB (RPI) and a mainboard EHCI debugging port

Setup the RPI

• Image 2024-10-22-raspios-bullseye-armhf-lite.img onto the MicroSD card
• Before attaching the MicroSD card to the RPI, mount /boot and add/edit the following files:

/boot/config.txt: append the following

dtoverlay=dwc2

/boot/ssh: empty file, activates sshd

/boot/wpa_supplicant.conf: edit to match your country/wifi

country=us
update_config=1
ctrl_interface=/var/run/wpa_supplicant

network={
 scan_ssid=1
 ssid="WIFI_NAME"
 psk="WIFI_PASSWORD"
}

/boot/userconf: create a default user (debug:debug)

debug:$6$bPlhEkH1cqka0J4L$heiwAMdszLhD4rbfOeNfApYapuS/D6HzJR4Lmk6hZxzvnRTNgu3XeBlG4t73n4mNyrdLCM4Cn8knhscJ9/0nD0

• Attach the MicroSD card into the RPI and power on the device. You should now be able to SSH the device once it boots
• SSH to the RPI (ssh debug@raspberrypi, password: debug)
  • Nmap can be used to find the IP of the RPI if you do not have local DNS (nmap -p 22 192.168.1.1/24)
• Setup the RPI as a EHCI USB Debugger Gadget

# Install dependencies
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git bc libncurses5-dev flex bison libssl-dev

# Prepare to build
git clone --depth=1 https://github.com/raspberrypi/linux # tested on commit 763693bb98ba47d2b21e4128cf761dd9ceb74041
cd linux
KERNEL=kernel
make bcmrpi_defconfig

# Device Drivers -> USB support -> USB Gadget Support -> USB Gadget precomposed configurations
# Enable EHCI Debug Device Gadget
# Set EHCI Debug Device mode to serial
# Save and Exit
make menuconfig

# Build using 4 threads - this will take 10+ hours - if you need it to be faster, consider cross-compiling (see below)
make -j4 zImage modules dtbs

# Apply patches
wget https://15h.org/images/6/62/Debug_patches.tar.xz
tar -xJf Debug_patches.tar.xz
patch -p0 < dbgp.patch
patch -p0 < gadget.patch
patch -p0 < u_serial.patch

# Rebuild the affected files
make -j4 zImage modules dtbs

# Install the build kernel on the system and reboot
sudo make modules_install
sudo cp arch/arm/boot/dts/broadcom/*.dtb /boot/
sudo cp arch/arm/boot/dts/overlays/*.dtb* /boot/overlays/
sudo cp arch/arm/boot/dts/overlays/README /boot/overlays/
sudo cp arch/arm/boot/zImage /boot/kernel.img
reboot

Cross-Compilation

The above setup instructions work, and are the simplest way to set up a Raspberry Pi Zero W for EHCI debugging. However, compiling the kernel (make -j4 zImage modules dtbs) is extremely slow - it is likely to take upwards of 10 hours on the original Raspberry Pi Zero's single-core CPU. If you wish to compile your kernel on a separate, faster system, set up your Pi's SD card as described above, then do the following:

# On your build host, install dependencies including the armhf toolchain
sudo apt install git bc libncurses5-dev flex bison libssl-dev crossbuild-essential-armhf

# Prepare to build
git clone --depth=1 https://github.com/raspberrypi/linux
cd linux/
KERNEL=kernel

# ensure all of your make commands on the build host include ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcmrpi_defconfig

# Device Drivers -> USB support -> USB Gadget Support -> USB Gadget precomposed configurations
# Enable EHCI Debug Device Gadget
# Set EHCI Debug Device mode to serial
# Save and Exit
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

# Build using 32 threads
make -j32 ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs

# Apply patches
wget https://15h.org/images/6/62/Debug_patches.tar.xz
tar -xJf Debug_patches.tar.xz
patch -p0 < dbgp.patch
patch -p0 < gadget.patch
patch -p0 < u_serial.patch

# Rebuild the affected files
make -j32 ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs

# Copy the entire tree to the Raspberry Pi over the network (do not make install these binaries on your non-RPi build system!)
cd ..
rsync -avzP linux pi@[your RPi's hostname/IP]:~/

# Connect to the Pi
ssh pi@[your RPi's hostname/IP]
cd linux/

# On the RPi, install the built kernel on your Pi and reboot
sudo make modules_install
sudo cp arch/arm/boot/dts/broadcom/*.dtb /boot/
sudo cp arch/arm/boot/dts/overlays/*.dtb* /boot/overlays/
sudo cp arch/arm/boot/dts/overlays/README /boot/overlays/
sudo cp arch/arm/boot/zImage /boot/kernel.img
reboot

Start Debugging

• Connect the RPI to the mainboard

sudo modprobe g_dbgp
screen -L -Logfile default.log /dev/ttyGS0 115200

• Turn on the mainboard

Precautions

While EHCI debugging, disconnecting the USB cable from the Raspberry Pi to the system under test may cause the Pi to crash. Avoid disconnecting the cable if possible.