Change in coreboot[master]: Documentation: Add proposal to allow enabling serial console with a flag

[Patrick Georgi (Code Review)]

Patrick Georgi has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/54385 )

Change subject: Documentation: Add proposal to allow enabling serial console with a flag
......................................................................

Documentation: Add proposal to allow enabling serial console with a flag

BUG=b:172341184, b:151780766

Change-Id: If1b0efc55880095f9d5d6d6e448f2c8677d57ff5
Signed-off-by: Patrick Georgi 
---
A Documentation/technotes/2021-05-selectable-serial-console.md
M Documentation/technotes/index.md
2 files changed, 137 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/85/54385/1

diff --git a/Documentation/technotes/2021-05-selectable-serial-console.md b/Documentation/technotes/2021-05-selectable-serial-console.md
new file mode 100644
index 0000000..361be00
--- /dev/null
+++ b/Documentation/technotes/2021-05-selectable-serial-console.md
@@ -0,0 +1,136 @@
+# Selectable serial console
+
+## Problem statement
+
+The primary mechanism to provide visibility into what coreboot is doing is
+its "console", providing insight at configurable verbosity levels to multiple
+potential outputs.
+
+The main two outputs are cbmem, a buffer in RAM that can be read out from the
+payload or operating system, and the serial console, sending the log to an
+external system through UART controllers. There are a few other options, e.g.
+EHCI Debug and even a few esoteric options like modulating the output onto
+the PC speaker output.
+
+While writing the log into RAM costs only a negligible amount of time,
+others are more expensive: To write a character to UART, the driver needs
+to wait for the hardware FIFOs to be ready, so enabling serial output can
+add a significant amount of time (10 seconds aren't unusual) to the boot time.
+
+For this reason shipping coreboot images usually come without serial console
+support compiled in, but sometimes it would be desirable to get additional
+visibility into the behavior of a given configuration with little effort
+and as little behavior change as possible.
+
+Regarding behavioral changes, adding serial console output to arbitrary
+parts of the code flow obviously _does_ induce differences, e.g. by messing
+up timings.  However, those differences are inherent to the change - there
+are others that can be avoided, e.g. changes that come from differences in
+code size or layout.
+
+To facilitate this, this document discusses options on how to selectively
+enable serial output in a given binary image and a few related approaches.
+
+## Approaches considered
+
+### Have separate images with serial support compiled in or not
+
+This is how the problem is usually approached at the time of writing this doc:
+Take a configuration for normal boot and if there's a need to dig in deeper,
+rebuild the same configuration but with serial enabled.
+
+This strategy is simple but comes with downsides: First, even though that
+seems to happen less often recently, differences in code size, even as benign
+as compiling serial console support in or not, can lead to behavioral changes.
+
+Switching images wholesale can come at a major increase in complexity in the
+environment. For example, there are plans to use serial output as a signal
+for some (but not all) automated tests in Chrome OS but the way firmware
+images are delivered in that environment doesn't allow keeping serial-enabled
+images around right now.
+
+While that specific testing infrastructure could be extended, similar issues
+would have to be solved individually for all affected coreboot users, making
+users reinvent the wheel.
+
+### Add a configuration flag (CMOS nvram)
+
+The CMOS nvram would be an obvious place to put such a flag but sadly it's
+an x86-specific solution: None of the other platforms provide something like
+this and even on x86 this is supposed to be on the way out (although vendors
+have already been saying that decades ago.)
+
+### Add a configuration flag (VPD)
+
+While VPD isn't universal, it's used in more than just Chrome OS contexts
+these days. Due to its key/value design, adding more flags is simple.
+
+The downside is that VPD isn't guaranteed to be available in the bootblock
+(since it doesn't use it yet) and there have been concerns that adding
+support for that significantly increases the overhead on platforms without
+memory mapped SPI flash.
+
+### Add a configuration flag (GBB)
+
+GBB also isn't universal, and the way it allows adding flags is much more
+static than with VPD. It should bring less complexity though, avoiding all
+the string parsing, but the bootblock might still not be able to access it.
+
+### Add a configuration flag (into the bootblock binary)
+
+It would be feasible to put a global variable into the bootblock, read out
+the offset to that byte to the bootblock's memory map and store it somewhere.
+That way the serial console could be enabled or disabled by flipping a byte
+in the bootblock.
+
+However this requires updating signatures on platforms with a signed bootblock
+(Intel Boot Guard) and it likely isn't feasible to keep the signing key
+around on arbitrary testing machines. This wouldn't affect Chrome OS but
+given that there's lots of activity on building such a "trusted" boot path
+in other coreboot based projects, using this approach guarantees that such
+efforts would have to build their own flag of this kind if they need it,
+instead of reusing this work.
+
+### Add a configuration flag in flash but ignore the bootblock
+
+By forgoing the bootblock, visibility into the very earliest parts of the
+boot process is limited (unless always enabled, which might be an option
+since even with slow serial ports there isn't much for the console to do:
+At some point we didn't have serial output in the bootblock _at all_!)
+
+On the upside, by the next stage (romstage or verstage) enough infrastructure
+is present to access flash for various purposes that reading a flag shouldn't
+add a significant amount of complexity even when using VPD.
+
+## Proposal
+
+Forgo the bootblock in these considerations (and default to the serial
+console being enabled there if it's compiled in). Allow overriding that
+default through Kconfig, so that serial is compiled in but not used even in
+the bootblock. In verstage or romstage (if there is no verstage), read out
+a VPD flag (the most portable and flexible mechanism in this evaluation)
+and change the default to whatever is found there.
+
+## Discussion
+
+### How widely is VPD used?
+
+It originates with Chrome OS devices and all of them use it.  The default fmap
+layout for x86 (`util/cbfstool/default-x86.fmd`) adds a VPD if the support
+code is compiled in. Various other devices (e.g. across our lenovo ports)
+have a VPD region in their vboot-enabled FMAPs.
+
+The main issue might be to support non-Chrome OS non-x86 devices, but right
+now these are underserved anyway.
+
+### Messing up secured boot processes?
+
+On vboot-enabled designs, the VPD region is put in the RO part of the flash.
+This means that enabling the serial console through this mechanism is already
+a privileged operation: People who could mess up the boot flow (e.g. through
+timing) can also mess up the boot flow by writing their own image.
+
+Platforms merely enforcing boot trust through a signature scheme (e.g. Boot
+Guard) need to treat the VPD variable (like all other configuration options)
+as untrusted input and evaluate if this capability should be enabled in
+their builds.
diff --git a/Documentation/technotes/index.md b/Documentation/technotes/index.md
index a9320fb..7463edf 100644
--- a/Documentation/technotes/index.md
+++ b/Documentation/technotes/index.md
@@ -3,4 +3,5 @@
 * [Dealing with Untrusted Input in SMM](2017-02-dealing-with-untrusted-input-in-smm.md)
 * [Rebuilding coreboot image generation](2015-11-rebuilding-coreboot-image-generation.md)
 * [Unit testing coreboot](2020-03-unit-testing-coreboot.md)
+* [Selectable serial console](2021-05-selectable-serial-console.md)
 * [Address Sanitizer](asan.md)