Document how to update system firmware

This is a very important task, but it is often not done due to bad
tools.  Also correct some outdated information on the "how to update
software" page.

user/how-to-guides/how-to-update.md

@@ -17,6 +17,7 @@ Fully updating your Qubes OS system means updating:
 - [dom0](/doc/glossary/#dom0)
 - [templates](/doc/glossary/#template)
 - [standalones](/doc/glossary/#standalone) (if you have any)
+- [firmware](/doc/glossary/#firmware)
 
 ## Security updates
 
@@ -63,15 +64,19 @@ If you use [Anti Evil Maid (AEM)](/doc/anti-evil-maid/), you'll have to "reseal"
 
 <div class="alert alert-danger" role="alert">
   <i class="fa fa-exclamation-triangle"></i>
-  <b>Warning:</b> Updating with direct commands such as <code>qubes-dom0-update</code>, <code>dnf update</code>, and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
+  <b>Warning:</b> Updating with direct commands such as <code>dnf update</code> and <code>apt update</code> is <b>not</b> recommended, since these bypass built-in Qubes OS update security measures. Instead, we strongly recommend using the <b>Qubes Update</b> tool or its command-line equivalents, as described below. (By contrast, <a href="/doc/how-to-install-software/">installing</a> packages using direct package manager commands is fine.)
 </div>
 
-Advanced users may wish to perform updates via the command-line interface. The recommended way to do this is by applying the following two Salt states. **Applying these two Salt states is the same as updating via the Qubes Update tool.**
+Advanced users may wish to perform updates via the command-line interface. There are two ways to do this:
+
+- If you are using Salt, one can use the following two Salt states.
 
  - [update.qubes-dom0](/doc/salt/#updatequbes-dom0)
  - [update.qubes-vm](/doc/salt/#updatequbes-vm)
 
-In your update qube, a terminal window opens that displays the progress of operations and output as it is logged. At the end of the process, logs are sent back to dom0. You answer any yes/no prompts in your dom0 terminal window.
+- Alternatively, use `qubes-dom0-update` to update dom0, and use `qubes-vm-update` to update domUs.
+
+Using either of these methods has the same effect as updating via the Qubes Update tool.
 
 Advanced users may also be interested in learning [how to enable the testing repos](/doc/testing/).
 
@@ -86,3 +91,61 @@ In the case of Qubes OS itself, we will make an [announcement](/news/categories/
 Periodic upgrades are also important for templates. For example, you might be using a [Fedora template](/doc/templates/fedora/). The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project. They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL. You can always find out when an OS reaches EOL from the upstream project that maintains it. We also pass along any EOL notices we receive for official template OSes as a convenience to Qubes users (see the [supported template releases](/doc/supported-releases/#templates)).
 
 The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-releases/#note-on-dom0-and-eol).
+
+## Microcode Updates
+
+x86\_64 CPUs contain special low-level software called **microcode**, which
+is used to implement certain instructions and runs on various processors that
+are outside of Qubes OS's control.  Most microcode is in an on-CPU ROM, but
+CPU vendors provide patches that modify small parts of this microcode.  These
+patches can be loaded from the BIOS or by the OS.
+
+The fixes for some QSBs require a microcode update to work. Furthermore,
+microcode updates will sometimes fix vulnerabilities "silently". This means
+that the vulnerability impacts the security of Qubes OS, but the Qubes OS
+Security Team is not informed that a vulnerability exists, so no QSB is ever
+issued. Therefore, it is critical to update microcode.
+
+Intel provides microcode updates for all of their CPUs in a public Git
+repository, and allows OS vendors (such as Qubes OS) to distribute the updates
+free of charge.  AMD, however, only provides microcode for server CPUs.
+AMD client CPUs can only receive microcode updates via a system firmware
+update.  Worse, there is often a significant delay between when a vulnerability
+becomes public and when firmware that includes updated microcode is available
+to Qubes OS users.  This is why Qubes OS recommends Intel CPUs instead of
+AMD CPUs.
+
+## Firmware updates
+
+Modern computers have many processors other than those that run Qubes OS.
+Furthermore, the main processor cores also run firmware, which is used to
+boot the system and often provides some services at runtime.  Both kinds
+of firmware can have bugs and vulnerabilities, so it is critical to keep
+them updated.
+
+Some firmware is loaded by the OS at runtime.
+Such firmware is provided by the `linux-firmware` package and can be updated the usual way.
+Other devices have persistent firmware that must be updated manually.
+
+Qubes OS supports updating system firmware in three different ways.
+Which one to use depends on the device whose firmware is being updated.
+
+- If a device is attached to a domU, it should be updated using **fwupd**.
+  fwupd is included in both Debian and Fedora repositories.
+  It requires Internet access to use, but you can use the updates proxy if you
+  need to update firmware from an offline VM.  You can use either the
+  command-line `fwupdmgr` tool or any of the graphical interfaces to fwupd.
+
+- If a device is attached to dom0, use the `qubes-fwupdmgr` command-line tool.
+  This tool uses fwupd internally, but it fetches firmware and metadata over
+  qrexec from the dom0 UpdateVM, rather than fetching them from the Internet.
+  Unfortunately, their is no graphical interface for this tool yet.
+
+- System76 systems use a special update tool which is simpler than fwupd.
+  Support for this tool is currently in progress.  Once it is finished,
+  users will be able to use the **system76-firmware-cli** command-line
+  tool to update the firmware.
+
+Firmware updates are important on all systems, but they are especially
+important on AMD client systems.  These doesn't support loading microcode from
+the OS, so firmware updates are the **only** way to obtain microcode updates.

user/reference/glossary.md

@@ -88,6 +88,13 @@ domUs lack direct hardware access.
 * Sometimes the term [VM](#vm) is used as a synonym for domU. This is
   technically inaccurate, as [dom0](#dom0) is also a VM in Xen.
 
+## firmware
+
+Software that runs outside the control of the operating system.
+Some firmware executes on the same CPU cores as Qubes OS does, but
+all computers have many additional processors that the operating system
+does not run on, and these computers also run firmware.
+
 ## HVM
 
 Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted,