From b3242efba691e394f273e56e6a2f34881082913c Mon Sep 17 00:00:00 2001
From: Tim Crawford <tcrawford@system76.com>
Date: Mon, 28 Feb 2022 15:51:17 -0700
Subject: [PATCH] docs: Add info for enabling debug logging

Signed-off-by: Tim Crawford <tcrawford@system76.com>
---
 README.md         |  2 +-
 docs/debugging.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 docs/debugging.md

diff --git a/README.md b/README.md
index db217b0..3e8856c 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ are the model folders in `models/`. For example, to build for QEMU:
 Once built, the firmware must be flashed to use. Several scripts are available
 to flash the new firmware, depending on how it is going to be written.
 
-- `scripts/qemu.sh`: Run the firmware in QEMU (specific to the QEMU model)
+- `scripts/qemu.sh`: [Run the firmware in QEMU](./docs/debugging.md#using-qemu) (specific to the QEMU model)
 - `scripts/flash.sh`: Flash using the internal flasher
 - `scripts/ch341a-flash.sh`: Flash using a CH341A programmer
 - `scripts/spipi-flash.sh`: Flash using a Raspberry Pi
diff --git a/docs/debugging.md b/docs/debugging.md
new file mode 100644
index 0000000..99085fc
--- /dev/null
+++ b/docs/debugging.md
@@ -0,0 +1,97 @@
+# Debugging
+
+## Component
+
+### coreboot
+
+coreboot debug logging is enabled by default at the level of `Debug`. This can
+be changed using `nvramtool` to set the CMOS option `debug_level`.
+
+```
+sudo nvramtool -w debug_level=<level>
+```
+
+Available log levels are:
+
+- Emergency
+- Alert
+- Critical
+- Error
+- Warning
+- Notice
+- Info
+- Debug
+- Spew
+
+### edk2
+
+Modify `./scripts/_build/edk2.sh` so `BUILD_TYPE` is set to `DEBUG` instead of
+`RELEASE`.
+
+```sh
+#BUILD_TYPE=RELEASE
+BUILD_TYPE=DEBUG
+```
+
+The default PCD values are used, so a lot of ouput will be generated. This can
+have a significant impact on the boot time.
+
+This also unconditionally enables asserts, so any failures will result in edk2
+hanging and require a reflash to fix.
+
+### Rust UEFI apps
+
+Debug logging can be enabled in the Rust UEFI apps (e.g., `firmware-setup`) by
+selecting the `debug` feature in `Cargo.toml`.
+
+## Method
+
+A couple of methods can be used to get debug logging.
+
+### Parallel port
+
+This method requires no soldering of board components.
+
+See [Debugging the EC firmware](./ec/doc/debugging.md) for details on setting
+up EC debugging over the parallel port.
+
+cbmem output can be passed through the EC by enabling the driver in coreboot.
+Uncomment the config in `models/<model>/coreboot.config` to enable logging the
+cbmem console through the EC.
+
+```
+CONFIG_CONSOLE_SYSTEM76_EC=y
+```
+
+edk2 output can be passed through as well by enabling the driver in edk2.
+This causes boot to be *very* slow, as edk2 generates a lot of output.
+Uncomment the config in `models/<model>/edk2.config` to enable the driver.
+
+```
+SYSTEM76_EC_LOGGING=TRUE
+```
+
+### Using QEMU
+
+A `qemu` target is provided to allow development and debugging in a VM.
+
+```
+./scripts/build.sh qemu
+```
+
+Install QEMU:
+
+```sh
+# Arch
+sudo pacman -S qemu
+# Fedora
+sudo dnf install qemu-system-x86
+# Ubuntu
+sudo apt install qemu-system-x86
+```
+
+And run the image in a VM:
+
+```
+./scripts/qemu.sh
+```