Nicholas Chin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/85913?usp=email )
Change subject: [WIP] Docs: Add information about various debugging methods ......................................................................
[WIP] Docs: Add information about various debugging methods
Add information about the different methods to debug coreboot, such as the various consoles and the tools required to use them.
Signed-off-by: Nicholas Chin nic.c3.14@gmail.com Change-Id: I0b407fc05678a944567479a6430b7d47175b4072 --- M 3rdparty/amd_blobs M 3rdparty/fsp A Documentation/debugging/cbmem.md A Documentation/debugging/ehci.md A Documentation/debugging/em100.md A Documentation/debugging/flashconsole.md A Documentation/debugging/gdb.md A Documentation/debugging/index.md A Documentation/debugging/ne2000.md A Documentation/debugging/post_codes.md A Documentation/debugging/serial.md A Documentation/debugging/spkmodem.md M Documentation/index.md 13 files changed, 163 insertions(+), 2 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/13/85913/1
diff --git a/3rdparty/amd_blobs b/3rdparty/amd_blobs index 26c5729..6a1e145 160000 --- a/3rdparty/amd_blobs +++ b/3rdparty/amd_blobs @@ -1 +1 @@ -Subproject commit 26c572974bcf7255930b0e9a51da3144ed0104b5 +Subproject commit 6a1e1457afddf49e53bfa4f422e7fd42f9db6e49 diff --git a/3rdparty/fsp b/3rdparty/fsp index 909cf43..3beceb0 160000 --- a/3rdparty/fsp +++ b/3rdparty/fsp @@ -1 +1 @@ -Subproject commit 909cf43ad6ccebb6adee482bc0a4f098c32c9a6d +Subproject commit 3beceb01f90dbdbe7781c7fa43ecc928cd68d2f0 diff --git a/Documentation/debugging/cbmem.md b/Documentation/debugging/cbmem.md new file mode 100644 index 0000000..c1a0bca --- /dev/null +++ b/Documentation/debugging/cbmem.md @@ -0,0 +1,34 @@ +# CBMEM console +As this can only be accessed once the system has reached the payload, +this cannot be used to debug issues that cause coreboot to lock up or +reboot in earlier stages. + +As cbmem is a core part of coreboot, this should be available on all +boards coreboot supports. + +## Enabling + +## Viewing the console +### Linux +#### cbmem utility +These require th +To view all logs in cbmem: + + sudo cbmem -c + +To view only the console log for the last boot: + + sudo cbmem -1 + +#### Linux driver +If your kernel was built with the `GOOGLE_MEMCONSOLE_COREBOOT` config, +then the console should be available under `/sys/firmware/log` + +### Payloads +#### GRUB +The GRUB2 payload provides a cbmem driver, which can be used to view the +cbmem console: + +#### coreinfo +The coreinfo secondary payload can be used to view the cbmem console, by +pressing `F2` (Firmware), and then `C` (Bootlog) diff --git a/Documentation/debugging/ehci.md b/Documentation/debugging/ehci.md new file mode 100644 index 0000000..e92ef6e --- /dev/null +++ b/Documentation/debugging/ehci.md @@ -0,0 +1,55 @@ +# EHCI debug console + +EHCI (USB 2.0) controllers may optionally implement a feature which +provides a simpler, register based interface to communicate over USB, +eliminating the need for a full USB stack that requires memory. Newer +boards will not have this feature as EHCI controllers have largely been +replaced with the xHCI (USB 3.0) controllers, which do not provide a +similar interface. + +To use this as a coreboot console output you will need both a board with +EHCI debug capability and an accessible debug port, as well as a +supported debug device. + +## Supported chips with EHCI debug capability +- ICH9 +- ICH10 +- ibex peak +- bd82x6x +- lynxpoint + +## Supported debug devices +### USB to UART adapters +- FTDI FT232H/2232H/4232H + - Must not be configured for a specific mode through an attached EEPROM +- WCH CH347T + - Supports UART 1 in modes 0, 1, and 3 + +### USB debug gadget +On some single board computers, USB ports can be used as a gadget +device, where the port acts as a USB device with functionality defined +by software. +- Raspberry Pi Zero +- Beaglebone Black + +## Finding the EHCI debug port +To determine if there is an EHCI debug capable USB controller in your +system and locate the physical USB port the debug port is routed to, you +can use the `util/find_usbdebug/find_usbdebug.sh` script. The script +requires lspci and lsusb, which can included in the pciutils and +usbutils packages. + +First, start the script with root privileges. It will report whether or not your +board has an EHCI controller with debug capabilities, and will list the +port(s) on the controller which are designated as the debug port. Then, +insert a high speed (USB 2.0 device into any USB port and press `enter`. If the +device was connected to the physical port which the debug port is routed +to, the device will show up in the output of the script. Repeat the +process of inserting the device into an untested port and pressing +`enter` until either you find the debug port or you have exhausted all +possible ports. If possible also check any unused USB 2.0 headers on +your mainboard. + +If you are unlucky the debug port on the EHCI controller may not be +physically routed to any available USB port or header, in which case you +will need to resort to alternative debugging methods. diff --git a/Documentation/debugging/em100.md b/Documentation/debugging/em100.md new file mode 100644 index 0000000..427a73c --- /dev/null +++ b/Documentation/debugging/em100.md @@ -0,0 +1,3 @@ +# Dediprog EM100 console + +I diff --git a/Documentation/debugging/flashconsole.md b/Documentation/debugging/flashconsole.md new file mode 100644 index 0000000..d2361a7 --- /dev/null +++ b/Documentation/debugging/flashconsole.md @@ -0,0 +1,13 @@ +# Flash console + +The SPI flash console offers a way + +## Usage + +## Known issues +The SPI flash console has been known to cause issues later in the boot +process (usually after romstage), and should be considered as a method +of last resort to debug early boot issues. + +- On Haswell, the flash console causes coreboot to freeze during the + jump to postcar after romstage diff --git a/Documentation/debugging/gdb.md b/Documentation/debugging/gdb.md new file mode 100644 index 0000000..aa42f24 --- /dev/null +++ b/Documentation/debugging/gdb.md @@ -0,0 +1 @@ +# GDB Stub diff --git a/Documentation/debugging/index.md b/Documentation/debugging/index.md new file mode 100644 index 0000000..25ca7ad --- /dev/null +++ b/Documentation/debugging/index.md @@ -0,0 +1,19 @@ +# Debugging + +This section describes various methods of debugging coreboot. + +## Debug Method Specific Documentation + +```{toctree} +:maxdepth: 1 + +Serial console <serial.md> +EHCI Debug console <ehci.md> +CBMEM console <cbmem.md> +SPI flash console <flashconsole.md> +NE2000 network console <ne2000.md> +Spkmodem console <spkmodem.md> +Dediprog EM100 console <em100.md> +POST codes <post_codes.md> +GDB <gdb_stub.md> +``` diff --git a/Documentation/debugging/ne2000.md b/Documentation/debugging/ne2000.md new file mode 100644 index 0000000..2bf0c5e --- /dev/null +++ b/Documentation/debugging/ne2000.md @@ -0,0 +1 @@ +# NE2000 Network Console diff --git a/Documentation/debugging/post_codes.md b/Documentation/debugging/post_codes.md new file mode 100644 index 0000000..97ee032 --- /dev/null +++ b/Documentation/debugging/post_codes.md @@ -0,0 +1,7 @@ +# POST Codes + +POST codes provide a basic way to determine overall progress of the +coreboot boot process, serving as "checkpoints" indicating a point in +the code that coreboot has passed. + +Some boards may have integrated displays diff --git a/Documentation/debugging/serial.md b/Documentation/debugging/serial.md new file mode 100644 index 0000000..b119e04 --- /dev/null +++ b/Documentation/debugging/serial.md @@ -0,0 +1 @@ +# Serial console diff --git a/Documentation/debugging/spkmodem.md b/Documentation/debugging/spkmodem.md new file mode 100644 index 0000000..905506e --- /dev/null +++ b/Documentation/debugging/spkmodem.md @@ -0,0 +1,26 @@ +# Spkmodem console +Spkmodem uses tones played over the PC speaker in order to encode the +console output, which can be received by another system and decoded. +Note that it is extremely slow (about baud), and will make the boot +process significantly slower. + +The protocol and decode utility originated from the GRUB2 project. + +## Availability +As this uses the legacy 8254 Programmable Interval Timer, this is only +supported on x86. Furthermore, the output pin on the chipset for the +speaker needs to be connected to an audio output, such as a piezo beeper +on the mainboard or routed to the audio codec. In the case that it is +routed to the codec, initialization verbs may need to be sent to do +things like unmute the speakers, route the beep signal to an output, and +set the gain. These can be specified in the `pc_beep_verbs` array in a +board's `hda_verb.c`. This also currently limits spkmodem functionality +to ramstage if the beep signal goes to a codec which requires +initialization, as the verbs are not run until ramstage. + +## Usage +On the target board, enable CONFIG_SPKMODEM (Console > spkmodem (console +on speaker) console output). + +## Protocol + diff --git a/Documentation/index.md b/Documentation/index.md index 7ba88f3..8aaf9d5 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -233,6 +233,7 @@ Security <security/index.md> SuperIO <superio/index.md> Vendorcode <vendorcode/index.md> +Debugging <debugging/index.md> Utilities <util.md> Software Bill of Materials <sbom/sbom.md> Project infrastructure & services <infrastructure/index.md>