Documentation/getting_started: Add a FAQ document

Signed-off-by: Martin Roth <gaumless@gmail.com>
Signed-off-by: Matt DeVillier <matt.devillier@gmail.com>
Change-Id: Ia324e4800bf9dfc7ad86f4f99272c87ac566304e
Reviewed-on: https://review.coreboot.org/c/coreboot/+/79441
Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

2 files changed, 313 insertions, 0 deletions

diff --git a/Documentation/getting_started/faq.md b/Documentation/getting_started/faq.md
new file mode 100644
index 0000000000..a92c5caa6f
--- /dev/null
+++ b/Documentation/getting_started/faq.md
@@ -0,0 +1,312 @@
+# coreboot FAQ
+
+## General coreboot questions
+
+
+### What is coreboot?
+
+coreboot is a free and open software project designed to initialize
+computers and embedded systems in a fast, secure, and auditable fashion.
+The focus is on minimal hardware initialization: to do only what is
+absolutely needed, then pass control to other software (a payload, in
+coreboot parlance) in order to boot the operating system securely.
+
+
+### What is a coreboot payload?
+
+coreboot itself does not deal with boot media such as hard-drives,
+SSDs, or USB flash-drives, beyond initializing the underlying hardware.
+So in order to actually boot an operating system, another piece of
+software which does do those things must be used. coreboot supports
+a large number of diverse payloads; see below for more details.
+
+
+### Is coreboot the same as UEFI?
+
+No. coreboot and UEFI are both system firmware that handle the
+initialization of the hardware, but are otherwise not similar.
+coreboot’s goal is to **just** initialize the hardware and exit.
+This makes coreboot smaller and simpler, leading to faster boot times,
+and making it easier to find and fix bugs. The result is a higher
+overall security.
+
+
+### What's the difference between coreboot and UEFI?
+
+UEFI is actually a firmware specification, not a specific software
+implementation. Intel, along with the rest of the Tianocore project,
+has released an open-source implementation of the overall framework,
+EDK2, but it does not come with hardware support. Most hardware running
+UEFI uses a proprietary implementation built on top of EDK2.
+
+coreboot does not implement the UEFI specification, but it can be used to
+initialize the system, then launch a UEFI payload such as EDK2 in order
+to provide UEFI boot services.
+
+The UEFI specification also defines and allows for many things that are
+outside of coreboot’s scope, including (but not limited to):
+
+* Boot device selection
+* Updating the firmware
+* A CLI shell
+* Network communication
+* An integrated setup menu
+
+
+### Can coreboot boot operating systems that require UEFI?
+
+Yes, but... again, coreboot **just** initializes the hardware. coreboot
+itself doesn’t load operating systems from storage media other than the
+flash chip. Unlike UEFI, coreboot does not, and will not contain a Wi-Fi
+driver or communicate directly with any sort of network. That sort of
+functionality is not related to hardware initialization.
+
+To boot operating systems that require UEFI, coreboot can be compiled with
+EDK2 as the payload. This allows coreboot to perform the hardware init,
+with EDK2 supplying the UEFI boot interface and runtime services to
+the operating system.
+
+
+### What non-UEFI payloads does coreboot support?
+
+* SeaBIOS, behaves like a classic BIOS, allowing you to boot operating
+  systems that rely on the legacy interrupts.
+
+* GRUB can be used as a coreboot payload, and is currently the most
+  common approach to full disk encryption (FDE).
+
+* A Linux kernel and initramfs stored alongside coreboot in the boot
+  ROM can also be used as a payload. In this scenario coreboot
+  initializes hardware, loads Linux from boot ROM into RAM, and
+  executes it. The embedded Linux environment can look for a target OS
+  kernel to load from local storage or over a network and execute it
+  using kexec. This is sometimes called LinuxBoot.
+
+* U-boot, depthcharge, FILO, etc.
+
+There’s [https://doc.coreboot.org/payloads.html](https://doc.coreboot.org/payloads.
+html) with a list, although it’s not complete.
+
+
+### What does coreboot leave in memory after it's done initializing the hardware?
+
+While coreboot tries to remove itself completely from memory after
+finishing, some tables and data need to remain for the OS. coreboot
+reserves an area in memory known as CBMEM, to save this data after it
+has finished booting. This contains things such as the boot log, tables
+that get passed to the payload, SMBIOS, and ACPI tables for the OS.
+
+In addition to CBMEM, on X86 systems, coreboot will typically set up
+SMM, which will remain resident after coreboot exits.
+
+
+## Platforms
+
+### What’s the best coreboot platform for a user?
+
+The choice of the best coreboot platform for a user can vary depending
+on their specific needs, preferences, and use cases.
+
+Typically, people who want a system with a minimum of proprietary
+firmware are restricted to older systems like the Lenovo X220, or more
+expensive, non-x86 solutions like TALOS, from Raptor Engineering.
+
+There are a number of companies selling modern systems, but those all
+require more proprietary binaries in addition to coreboot (e.g., Intel
+FSP). However, unlike the older ThinkPads, many of these newer devices
+use open-source embedded controller (EC) firmware, so there are
+tradeoffs with either option.
+
+The coreboot project mantains a list of companies selling machines
+which use coreboot on the [website](https://coreboot.org/users.html).
+
+
+### What’s the best platform for coreboot development?
+
+Similar to the best platform for users, the best platform for
+developers very much depends on what a developer is trying to do.
+
+* QEMU is generally the easiest platform for coreboot development, just
+  because it’s easy to run anywhere. However, it’s possible for things
+  to work properly in QEMU but fail miserably on actual hardware.
+
+While laptops tend to be harder to develop than desktop platforms, a
+majority of newer platforms on coreboot tend to be laptops. The
+development difficulty is due to a few different factors:
+
+1. The EC (Embedded Controller) is a specialized microcontroller that
+   typically handles keyboard and sometimes mouse input for a laptop.
+   It also controls many power management functions such as fans, USB-C
+   power delivery, etc. ECs run mainboard-specific firmware, which is
+   typically undocumented.
+2. ThinkPads (X230, 30-series, 20-series, T430, T540, T520). Sandy
+   Bridge and Ivy Bridge are well-supported. Some may have
+   difficult-to-reach SPI flash chips. Boards with two flash chips (e.g.
+   30-series ThinkPads) are harder to externally reflash as one needs to
+   make sure the non-targeted flash chip remains disabled at all times.
+   The X230 is notoriously sensitive to external reflashing issues.
+3. Laptops often lack a convenient method to obtain firmware boot logs.
+   One can use EHCI debug on older systems and Chromebook-specific
+   solutions for Chromebooks, but one often has to resort to flashconsole
+   (writing coreboot logs to the flash chip where coreboot resides). On
+   the other hand, several desktop mainboards still have a RS-232 serial
+   port.
+
+Some of the easiest physical systems to use for coreboot development
+are Chromebooks. Newer Chromebooks allow for debug without opening the
+case. Look for SuzyQ Cables or SuzyQables or instructions on how to
+build one. These cables only work on a specific port in a specific
+orientation. Google [supplies
+specifications](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/ccd.md#SuzyQ-SuzyQable)
+for these cables.
+
+
+### What platforms does coreboot support?
+
+The most accurate way to determine what systems coreboot supports is by
+browsing the src/mainboard tree or running “make menuconfig” and going
+through the “Mainboard” submenu. You can also search Gerrit to see if
+there are any unmerged ports for your board.
+
+There is also the board status page
+([https://coreboot.org/status/board-status.html](https://coreboot.org/status/board-status.html)),
+however this does not currently show supported board variants.
+
+
+## coreboot Development
+
+### Can coreboot be ported to [this board]?
+
+The best way to determine if coreboot can be ported to a system is to
+see if the processor and chipset is supported. The next step is to see
+whether the system is locked to the proprietary firmware which comes
+with the board.
+
+Intel Platforms:
+
+* coreboot only supports a few northbridges (back when northbridges
+  were on a separate package), and there's next to no support for
+  "server" platforms (multi-socket and similar things). Here's a list
+  of more recent supported Intel processors:
+    * Alder Lake (2021 - Core Gen 12)
+    * Apollo Lake (2016 - Atom)
+    * Baytrail (2014 - Atom)
+    * Braswell (2016 - Atom)
+    * Broadwell (2014 - Core Gen 5)
+    * Comet Lake (2019 - Core Gen 10)
+    * Cannon Lake (2018 - Core Gen 8/9)
+    * Denverton (2017)
+    * Elkhart lake (2021 - Atom)
+    * Haswell (2013 - Core Gen 4)
+    * Ivy Bridge (2012 - Core Gen 3)
+    * Jasper Lake (2021 - Atom)
+    * Kaby Lake (2016 - Core Gen 7/8)
+    * Meteor Lake (2023 - Gen 1 Ultra-mobile)
+    * Sandy Bridge (2011 - Core Gen 2)
+    * Sky Lake (2015 - Core Gen 6)
+    * Tiger Lake (2020 - Core Gen 11)
+    * Whiskey Lake (2018 - Core Gen 8)
+
+* Intel Boot Guard is a security feature which tries to prevent loading
+  unauthorized firmware by the mainboard. If supported by the platform,
+  and the platform is supported by intelmetool, you should check if Boot
+  Guard is enabled. If it is, then getting coreboot to run will be
+  difficult or impossible even if it is ported. You can run
+  `intelmetool -b` on supported platforms to see if Boot Guard is
+  enabled (although it can fail because it wants to probe the ME
+  beforehand).
+
+AMD Ryzen-based platforms:
+
+* The AMD platforms Ryzen-based platforms unfortunately are currently
+  not well supported outside of the Chromebooks (and AMD reference
+  boards) currently in the tree.
+  The responsible teams are trying to fix this, but currently it's
+  **very** difficult to do a new port. Recent supported SoCs:
+    * Stoney Ridge
+    * Picasso
+    * Cezanne
+    * Mendocino
+    * Phoenix
+
+General notes:
+
+* Check the output of `lspci` to determine what processor/chipset
+  family your system has. Processor/chipset support is the most
+  important to determine if a board can be ported.
+* Check the output of `superiotool` to see if it detects the Super I/O
+  on the system. You can also check board schematics and/or boardviews
+  if you can find them, or physically look at the mainboard for a chip
+  from one of the common superio vendors.
+* Check what EC your system has (mostly applicable to laptops, but some
+  desktops have EC-like chips). You will likely need to refer to the
+  actual board or schematics/boardviews for this. Physical observation
+  is the most accurate identification procedure; software detection can
+  then be used to double-check if the chip is correct, but one should
+  not rely on software detection alone to identify an EC.
+
+
+### How do I port coreboot to [this board]?
+
+A critical piece for anyone attempting to do a board port is to make
+sure that you have a method to recover your system from a failed flash.
+
+We need an updated motherboard porting guide, but currently the guide
+on the [wiki](https://www.coreboot.org/Motherboard_Porting_Guide) looks
+to be the best reference.
+
+At the moment, the best answer to this question is to ask for help on
+one of the [various community
+forums](https://doc.coreboot.org/community/forums.html).
+
+
+### What about the Intel ME?
+
+There seems to be a lot of FUD about what the ME can and can’t do.
+coreboot currently does not have a clear recommendation on how to
+handle the ME. We understand that there are serious concerns about the
+ME, and would like to flatly recommend removing as much as possible,
+however modifying the ME can cause serious stability issues.
+
+Additionally, coreboot and the Intel ME are completely separate entites
+which in many cases simply happen to occupy the same flash chip. It is
+not necessary to run coreboot to modify the ME, and running coreboot
+does not imply anything about the ME's operational state.
+
+
+#### A word of caution about the modifying ME
+
+Messing with the ME firmware can cause issues, and this is outside the
+scope of the coreboot project.
+
+If you do decide to modify the ME firmware, please make sure coreboot
+works **before** messing with it. Even if the vendor boot firmware
+works when the ME isn't operating normally, it's possible that coreboot
+doesn't handle it the same way and something breaks. If someone asks
+for help with coreboot and we think the ME state may be a factor, we'll
+ask them to try reproducing the issue with the ME running normally to
+reduce the number of variables involved. This is especially important
+when flashing coreboot for the first time, as it's best for newbies to
+start with small steps: start by flashing coreboot to the BIOS region
+and leaving the remaining regions untouched, then tinker around with
+coreboot options (e.g. other payloads, bootsplash, RAM overclock...),
+or try messing with the ME firmware **without changing coreboot**.
+
+Most people don't understand the implications of messing with the ME
+firmware, especially the use of `me_cleaner`. We admit that we don't
+know everything about the ME, but we try to understand it as much as
+possible. The ME is designed to operate correctly with the HAP (or
+AltMeDisable) bit set, and it will gracefully enter a debug state (not
+normal, but not an error). However, when using `me_cleaner` to remove
+parts of the ME firmware, the ME will often end up in an error state
+because parts of its FW are missing. It is known that removing some of
+these parts ([`EFFS` and `FCRS` on Cougar Point,
+c.f.](https://review.coreboot.org/c/coreboot/+/27798/6/src/mainboard/asus/p8h61-m_lx/Kconfig#63))
+can cause problems. We do not know whether the state the ME ends up in
+after applying `me_cleaner` is as secure as the state the ME goes to
+when only the HAP bit is set: the removed FW modules could contain
+steps to lock down important settings for security reasons.
+
+To sum up, **we do not recommend messing with the ME firmware**. But if
+you have to, please use `ifdtool` to set the HAP bit initially before
+progressing to `me_cleaner` if necessary.
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index becb6afa72..01dbe8c87a 100644
--- a/Documentation/getting_started/index.md
+++ b/Documentation/getting_started/index.md
@@ -7,3 +7,4 @@
 * [Writing Documentation](writing_documentation.md)
 * [Setting up GPIOs](gpio.md)
 * [Adding devices to a device tree](devicetree.md)
+* [Frequently Asked Questions](faq.md)