diff --git a/source/guides/clear/stateless.rst b/source/guides/clear/stateless.rst index c80b9d9a..ad283f1e 100644 --- a/source/guides/clear/stateless.rst +++ b/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 diff --git a/source/guides/kernel/firmware.rst b/source/guides/kernel/firmware.rst new file mode 100644 index 00000000..4fa8bc6b --- /dev/null +++ b/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 +`_ 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 `. + + +#. 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 /. /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