Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
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 in the beginning of the ramstage.
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)
Note that agent-proxy is capable of multiplexing GBD and the serial console.
./agent-proxy 5550^5551 0 /dev/ttyUSB0,115200
telnet localhost 5550
$ gdb GNU gdb (GDB) 7.6.1 Copyright (C) 2013 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 "i686-pc-linux-gnu". For bug reporting instructions, please see: <http://www.gnu.org/software/gdb/bugs/>. (gdb) file ./build/cbfs/normal/coreboot_ram.debug Reading symbols from /home/gnutoo/x86/coreboot-X60/build/cbfs/normal/coreboot_ram.debug...done. (gdb) target remote localhost:5551 Remote debugging using localhost:5551 _text () at src/arch/x86/lib/c_start.S:89 89 call main (gdb) b set_boot_successful Breakpoint 1 at 0x10a7b3: file src/arch/x86/include/arch/io.h, line 63. (gdb) c Continuing.
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 ()
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).
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
Use some sufficiently large USB media (4GB+), and format it as NTFS.
Windows 7 might work on FAT, but Windows 8 definitely wont, 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.
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
For this, you need to run a Windows Console prompt as Administrator. Its 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.
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
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!
Once installation is done, boot the new system. Thats 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)
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:
"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.
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.