Add document on firmware (#824)

Adds a new document on firmware laoding and a reference to it from the stateless document.

source/guides/clear/stateless.rst

@@ -133,6 +133,7 @@ Additional information
 **********************
 
 * `stateless man page`_
+* :ref:`firmware`
 
 .. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst
 

source/guides/kernel/firmware.rst

@@ -0,0 +1,96 @@
+.. _firmware:
+
+Firmware
+########
+
+This guide shows how |CL-ATTR| handles firmware and microcode loading.
+
+.. contents::
+   :local:
+   :depth: 1
+
+Overview 
+********
+
+Many devices and system components require firmware or microcode, software
+that runs directly on the device, to function correctly. Because firmware
+loading requires privileged hardware access, the kernel is involved in the
+process.
+
+Firmware does not typically come with source code. Instead, firmware is
+provided as binary blobs which are licensed for free or non-free use.
+
+In |CL| firmware is loaded during device initialization which typically
+happens at boot time. 
+
+
+Included firmware
+*****************
+
+The Linux kernel project contains a repository for firmware binaries that are
+licensed to allow free redistribution. |CL| packages these firmware binaries
+in the `linux-firmware bundles
+<https://clearlinux.org/software?search_api_fulltext=linux-firmware>`_ and
+automatically includes them with the kernel.
+
+The Linux kernel's firmware repository can be found here:
+https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
+
+If the firmware for your device is included upstream, no action is required
+for it to be automatically detected and loaded. 
+
+
+Additional firmware loading
+***************************
+
+Some device hardware manufacturers have a license that limits redistribution
+of firmware. This means |CL| is unable to distribute those firmware and you
+must manually obtain them from the manufacturer or another source.
+
+You can place additional firmware in :file:`/etc/firmware`. |CL| reads this
+directory for additional firmware files in conjunction with the typical
+:file:`/lib/firmware` path to provide a :ref:`stateless design <stateless>`.
+
+
+#. Create the :file:`/etc/firmware` directory
+
+   .. code-block:: bash
+
+      sudo mkdir -p /etc/firmware
+
+#. Obtain the additional firmware binary from a trusted source.
+
+#. Copy the firmware files including any subdirectories to
+   :file:`/etc/firmware`. It is important to place the firmware files in
+   expected path for proper loading. 
+
+   .. code-block:: bash
+
+      sudo cp -Rv <directory>/<filename>.<fw|bin> /etc/firmware 
+
+
+CPU microcode loading
+*********************
+
+Microcode is low level code for processors loaded during the boot process that
+contain stability and security updates. 
+
+Microcode updates can be updated by motherboard firmware however this is not
+always feasible or does not happen in a timely fashion. The `Linux microcode
+loader`_ included in the Linux kernel allows for more flexibility and more
+frequent updates.
+
+|CL| uses the *early loading* mechanism described in the `Linux microcode
+loader`_ documented by which the CPU microcode is loaded as early as possible
+in the boot process by using an initial RAM disk (initrd). 
+
+
+Troubleshooting
+***************
+
+Look at the output of :command:`sudo dmesg` to see device initialization and
+expected firmware paths
+
+
+
+.. _`Linux microcode loader`: https://www.kernel.org/doc/Documentation/x86/microcode.txt