Debugging

GDB Interface

GDB Wait

Coreboot has an easy to use interface to the GNU debugger gdb. To enable it, select the CONFIG_GDB_STUB and the CONFIG_GDB_WAIT options in the Debugging menu of coreboot's configuration:

[*] GDB debugging support
[*]   Wait for a GDB connection

Then Coreboot will stop and wait for a GDB connection.

To connect to the remote coreboot instance over serial do:

$ gdb
GNU gdb (Ubuntu/Linaro 7.3-0ubuntu2) 7.3-2011.08
Copyright (C) 2011 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
For bug reporting instructions, please see:
<http://bugs.launchpad.net/gdb-linaro/>.
(gdb) file ./build/cbfs/fallback/coreboot_ram.debug
Reading symbols from /home/gnutoo/Coreboot/coreboot/build/cbfs/fallback/coreboot_ram.debug...done.
(gdb) set remotebaud 115200
(gdb) target remote /dev/ttyUSB0
Remote debugging using /dev/ttyUSB0
_text () at src/arch/x86/lib/c_start.S:85
85		call	hardwaremain
(gdb) 

Exceptions with GDB

Else if you just enable CONFIG_GDB_STUB option in the Debugging menu of coreboot's configuration you will still get some benefit.

[*] GDB debugging support

For instance you will not get exceptions like this:

Unexpected Exception: 0 @ 10:0012724b - Halting
Code: 0 eflags: 00010046
eax: 00000001 ebx: 00000061 ecx: 00000004 edx: 00000000
edi: 00000000 esi: 00000061 ebp: 00163abc esp: 00163a98

But instead you will be able to connect to the machine using gdb over a serial line in case of an exception:

(gdb) file coreboot/build/cbfs/fallback/coreboot_ram.debug
Reading symbols from coreboot/build/cbfs/fallback/coreboot_ram.debug...done.
(gdb) set remotebaud 115200
(gdb) target remote /dev/ttyUSB0
Remote debugging using /dev/ttyUSB0
0x0012824b in __udivdi3 (n=17082841390, d=0) at ...
...
(gdb) bt
#0  0x0012824b in __udivdi3 (n=17082841390, d=0)
    at /usr/lib/gcc/gcc- 4.3.2/libgcc/../gcc/libgcc2.c:899 
#1  0x0011efa2 in handle_port_61h ()
#2  0x0011fbc3 in my_inb ()
#3  0x001189f5 in x86emuOp_in_byte_AL_IMM ()
#4  0x001092f1 in X86EMU_exec ()
#5  0x0010a06f in biosemu ()
#6  0x0011fcfb in run_bios ()
#7  0x0010cbcb in pci_dev_init ()
#8  0x00103d9b in dev_initialize ()
#9  0x0010f8b5 in hardwaremain ()
#10 0x00100099 in _text ()

Windows 7 USB

This is documentation on how to setup Windows 7 on USB, so it can be used with a USB debug device and WinDbg to track down Windows errors that are otherwise hard to debug (eg. black screen, Stop codes, ACPI issues).

Prepare Windows Media

Step 1: Get media

I used Windows 7 Ultimate 64bit English, ISO image has SHA1: 36AE90DEFBAD9D9539E649B193AE573B77A71C83

I also tried Windows 8 Consumer Preview 64bit English, ISO image has SHA1: 1288519C5035BCAC83CBFA23A33038CCF5522749

Step 2: Prepare disk

Use some sufficiently large USB media (4GB+), and format it as NTFS.

Windows 7 might work on FAT, but Windows 8 definitely won’t, as the main file archive is >4GB, which even FAT32 doesn't like.

For reference, I called the volume “WININST”, but I doubt that matters.

Step 3: Copy the entire disk content to disk

I started out from an ISO image (as obtained from digitalriver), and extracted it using 7-zip to the media. After that I had a directory that looks like this:

E:\>dir
Datenträger in Laufwerk E: ist WININST
Volumeseriennummer: 86DF-6846

Verzeichnis von E:\

12.04.2011  11:38               122 autorun.inf
03.05.2012  18:54    <DIR>          boot
12.04.2011  11:38           383.786 bootmgr
12.04.2011  11:38           669.568 bootmgr.efi
03.05.2012  18:54    <DIR>          efi
12.04.2011  11:38           106.768 setup.exe
03.05.2012  18:56    <DIR>          sources
03.05.2012  18:56    <DIR>          support
03.05.2012  18:56    <DIR>          upgrade
              4 Datei(en),      1.160.244 Bytes
              5 Verzeichnis(se),  4.976.803.840 Bytes frei

Step 4: Install boot sector

For this, you need to run a Windows Console prompt as Administrator. It’s not enough to run as the admin user, but you need to go through the “run as administrator” + UAC motions.

On Windows 7, the fastest way is to open the start menu, type “cmd” in the search field, wait for cmd to appear (with that black window + C:\ icon), right click it, and select “run as administrator”. On Windows 8, there's an Admin Command Line in the Win+X menu.

Move to the drive with the install data (E:\ in my case), enter boot\, and run bootsect like this:

C:\Windows\System32>e:

E:\>cd boot

E:\boot>bootsect /nt60 e: /force /mbr
Target volumes will be updated with BOOTMGR compatible bootcode.

E: (\\?\Volume{39f55ea8-3ea1-11e1-afe7-005056c00008})

    Forced dismount complete, open handles to this volume are now invalid.

    Successfully updated NTFS filesystem bootcode.

\??\PhysicalDrive2

    Successfully updated disk bootcode.

Bootcode was successfully updated on all targeted volumes.

Step 5: Prepare installer for USB debug device

In the same Console prompt (and same directory), run:

bcdedit /store bcd /dbgsettings usb targetname:TargetSystem
bcdedit /store bcd /set {default} debug yes

If you have access to the legacy serial port, you can use that to run a kernel debugger session without usb debug device (and its setup, which can be complicated in the presence of Rate Matching Hubs).

In such a setup, instead of the first command use

bcdedit /store bcd /dbgsettings serial debugport:1 baudrate:115200

Step 6: Install

Start your coreboot + seabios system, and make it boot from your USB device. If everything is well, dance and jump with joy! If not, you have a chance to improve coreboot!

Step 7: Boot Windows

Once installation is done, boot the new system. That’s another source of trouble, since this is a slightly different Windows than the one driving the installer. And there was no chance to setup debug mode for it yet! (TBD)

Setup Debugging Environment

Configuring WinDbg

First, install WinDbg. You can find in the Debugging Utilities for Windows. Set up the symbol file path, so it can resolve the addresses it gets from the target:

• Create a directory somewhere (C:\Symbols is the default).
• Create an empty "index2.txt" in there.
• Start Windbg
• File, Symbol File Path
• Enter "SRV*C:\Symbols*http://msdl.microsoft.com/download/symbols" (fill in your path instead of C:\Symbols)

With this configuration, WinDbg will fetch symbol files from the Microsoft server.

Start debug operation

Select the communication channel in File, Kernel Debug (USB 2.0 or serial).

For USB, fill in the name (TargetSystem in the example above), for serial, configure the port. Press OK.

WinDbg will wait for the target to break into the kernel debugger now. It might take a while on the first runs as it has to download the symbol files. Eventually it will print the error and location.