Debugging

This guide covers collecting diagnostic information for firmware-related issues. For OS-specific problems (drivers, functionality under Linux/Windows), please use the Chrultrabook Forums.

Before You Begin

When reporting firmware issues, always include:

• Device board name (HWID) - not manufacturer model name
• Firmware version - found in firmware menu or sudo dmidecode -t bios
• What you're trying to do - detailed description
• What's happening instead - error messages, unexpected behavior
• Relevant log files - see sections below for how to collect

Quick Reference: What Logs to Collect

Collecting Firmware Logs (cbmem)

The cbmem utility captures coreboot's boot log, which is essential for diagnosing firmware issues.

When to Use cbmem

• Device boots but has hardware detection issues
• Investigating boot time delays
• Debugging display initialization problems
• Any firmware-related errors or warnings

Collecting cbmem Logs

Step 1: Download cbmem utility

wget https://mrchromebox.tech/files/util/cbmem.tar.gz

Step 2: Extract and make executable

tar -xf cbmem.tar.gz
rm cbmem.tar.gz
chmod +x cbmem

Step 3: Run cbmem and save output

sudo ./cbmem -1 > cbmem.log

Step 4: Share the log file

Attach cbmem.log to your issue report on:

• Firmware Issue Tracker
• Chrultrabook Forums
• Email to MrChromebox (if requested)

Understanding cbmem Output

The cbmem log contains:

• Hardware initialization - CPU, RAM, chipset setup
• Device enumeration - PCI devices, USB controllers, storage
• Display initialization - Graphics setup and mode setting
• Boot timestamps - Helps identify slow boot stages
• Error messages - Look for "ERROR", "WARN", or "FAIL" lines

Common issues revealed by cbmem:

• Missing or misconfigured hardware
• RAM training failures
• Display initialization problems
• Storage device detection issues

Advanced: SuzyQable Debug Cable

The SuzyQable (also called SuzyQ, CCD cable) is a specialized USB-C debug cable that provides serial console access to various components of ChromeOS devices with CR50/Ti50 security chips.

When You Need a SuzyQable

• Severe boot failures - device doesn't POST, completely dead
• Firmware development - real-time debugging during boot
• Bricked device recovery - see Unbricking with SuzyQable
• Advanced firmware debugging - kernel crashes, early boot issues

SuzyQable Serial Ports

The SuzyQable provides three serial console ports (UARTs):

Port 1: CR50/Ti50 Console (/dev/ttyUSB0)

minicom -D /dev/ttyUSB0

• Google Security Chip console
• Used to open CCD, disable WP (wp disable / atboot), and set AllowUnverifiedRo
• Required for Ti50 device recovery if ChromeOS gsctool is gone

Port 2: CPU Console (/dev/ttyUSB1)

minicom -D /dev/ttyUSB1

• Main coreboot/edk2 console output
• Shows boot process in real-time
• Requires firmware compiled with serial console support (see below)

Port 3: EC Console (/dev/ttyUSB2)

minicom -D /dev/ttyUSB2

• Embedded Controller console
• Useful for debugging keyboard, battery, power issues
• EC-specific commands available

Enabling Serial Console Output

Standard MrChromebox firmware does not include serial console output by default. To enable:

For coreboot/firmware debugging:

Build with the --debug flag on the UEFI build script (replace redrix with your board name):

./build-uefi.sh --debug redrix

Or set these options yourself if you are building by hand:

CONFIG_CONSOLE_SERIAL=y
CONFIG_EDK2_SERIAL_SUPPORT=y

--debug turns those two options on.

See Compiling Firmware for build instructions.

For Linux kernel debugging:

Add to kernel command line (in GRUB or bootloader config):

loglevel=15 console=ttyS4,115200n8

Terminal Emulator Setup

Using minicom:

sudo apt install minicom
minicom -D /dev/ttyUSB1 -b 115200

Using picocom:

sudo apt install picocom
picocom -b 115200 /dev/ttyUSB1

Using screen:

screen /dev/ttyUSB1 115200

To exit: CTRL+A then K (minicom), CTRL+A then CTRL+X (picocom), CTRL+A then \ (screen)

Where to Get a SuzyQable

• Fyra Labs SuzyQ Board
• Search online for "SuzyQable" or "CCD cable"
• Not all USB-C debug cables work - must be SuzyQable-compatible

Comprehensive Debug Bundle (Linux)

For complex issues involving hardware detection, ACPI, or driver problems, use the chrultrabook debugging script to collect a complete diagnostic bundle.

When to Use the Debug Script

• Hardware not working under Linux (audio, touchpad, etc.)
• ACPI errors or warnings in dmesg
• Device not detected or enumerated incorrectly
• Suspend/resume issues
• Any hardware-related Linux kernel problems

Collecting Complete Debug Information

Step 1: Download the script

cd ~/Desktop
wget https://raw.githubusercontent.com/chrultrabook/linux-tools/main/debugging.sh

Step 2: Make executable and run

chmod +x debugging.sh
./debugging.sh

The script automatically collects:

• ACPI tables - System hardware description from firmware
• DMI information - System/board identification (dmidecode)
• cbmem log - coreboot firmware boot log
• dmesg - Linux kernel messages and errors
• lspci -vvnn - Detailed PCI device information
• lsusb -vv - Detailed USB device information
• Audio configuration - Sound card setup and driver info

Step 3: Find the output

All logs are packaged into debug-logs.tar.gz on your Desktop.

Step 4: Upload and share

Upload this archive when requesting help on:

• Chrultrabook Forums
• Firmware Issue Tracker (if firmware-related)

Manual Log Collection

If the script doesn't work, manually collect key logs:

System information:

sudo dmidecode > dmidecode.txt
sudo lspci -vvnn > lspci.txt
lsusb -vv > lsusb.txt

Firmware and kernel logs:

sudo cbmem -1 > cbmem.log
dmesg > dmesg.txt

ACPI tables:

sudo cat /sys/firmware/acpi/tables/DSDT > dsdt.dat
sudo acpidump > acpi-tables.txt

Google Security Chip Tools (gsctool)

The gsctool utility communicates with the Google Security Chip (GSC — CR50 or Ti50) and is primarily used for CCD (Closed Case Debugging) operations from ChromeOS.

What is CCD?

CCD (Closed Case Debugging) is a GSC feature. Opening it (gsctool -a -o) lets you change CCD capabilities and, on a SuzyQable, talk to the GSC console.

Using gsctool (ChromeOS only)

Check CCD status and capabilities:

sudo gsctool -a -I

Check hardware WP state:

sudo gsctool -a -w

Open CCD (not "unlock" — that is gsctool -a -u, a weaker state):

sudo gsctool -a -o

This initiates a multi-step process:

1. You'll be prompted to press the power button several times over up to about five minutes. Press when it says Press PP button now!; wait when it says Another press will be required!
2. After the last press, the device reboots into Verified Boot Mode (Developer Mode is off)
3. Re-enable Developer Mode. CCD is then Open, which allows SuzyQable access and (on Ti50) gsctool WP / AllowUnverifiedRo commands

Important CCD notes:

• Only works from ChromeOS (not Linux, and not after flashing UEFI firmware)
• Requires physical presence (power button presses)
• On Ti50, after CCD is Open you still need AllowUnverifiedRo:always and gsctool -a -w disable before flashing Full ROM
• Once UEFI firmware is flashed, CCD state is preserved on the GSC but the ChromeOS gsctool binary is gone

Alternative: Physical Write-Protect Methods

These apply to no-GSC and CR50 boards, not Ti50:

• Remove WP screw
• Disconnect battery
• Bridge a jumper
• SuzyQable — after CCD is Open, GSC console wp disable

See Disabling Write Protection for the actual procedures.

Additional Resources

• Firmware Issue Tracker - Report firmware bugs
• Chrultrabook Forums - Get help with debugging
• Unbricking Guide - Recover from failed flashes
• Compiling Firmware - Build custom firmware with debug options
• Write Protection - Understanding and disabling WP