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

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git bc libncurses5-dev flex bison libsssl-dev
git clone --depth=1 https://github.com/raspberrypi/linux # tested on commit 763693bb98ba47d2b21e4128cf761dd9ceb74041
cd linux
KERNEL=kernel
make bcmrpi_defconfig
make menuconfig
# 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 -j4 zImage modules dtbs
# This make may take hours
wget https://johnlewis.ie/debug_patches.tar.xz
tar -xJf debug_patches.tar.xz
patch -p0 < dbgp.patch
patch -p0 < gadget.patch
patch -p0 < u_serial.patch
make -j4 zImage modules dtbs
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