update documentation

2026-07-23 22:01:03 +02:00
parent e0fad8e6ed
commit 40b6cd8bb5
6 changed files with 190 additions and 2 deletions
@@ -0,0 +1,60 @@
+.docname {Firmware Udpates}
+.include {docs}
+
+## Missing Firmware
+
+During the initramfs generation with command `mkinitcpio -P` you might see warnings about potentially
+missing firmware.
+
+Some of the warnings can be fixed by installing additional software packages. Others can be ignored.
+
+Run `mkinitcpio -P` to see the current list of warnings. Then install missing firmware if available.
+
+- missing `xhci_pie`: Install `yay -S upd72020x-fw` from the AUR
+- missing `qat_6xxx`: This is a Intel Encryption Accelerator firmware. Its use is possible on
+  Linux, but is discouraged because it is buggy and slow[^1].
+
+## Firmware Updates
+
+`fwupd` is a daemon to simply update firmware of your device - if it is supported by the vendor of
+the firmware and hardware.
+
+Install `sudo pacman -S fwupd udisks2`. Enable and start the `udisk` service with
+`systemctl enable --now udisks2`. Then restart `fwupd` with `systemctl restart fwupd`.
+
+Run the following commands for firmware upgrades
+
+- `sudo fwupdmgr get-devices`: list all devices detected by the firmware update tool
+- `sudo fwupdmgr refresh`: download the latest metadata available from the Linux Vendor firmware service
+- `sudo fwupdmgr get-updates`: list available updates for your system
+- `sudo fwupdmgr update`: perform the update
+
+> Important: If you use secure boot, follow the next section before running `sudo fwupdmgr update`
+
+### Secure Boot
+
+`fwupd` relies on shim to chainload the `fwupd` EFI binary on systems with Secure Boot enabled.
+Since we do not use shim for Secure Boot, this will not work on our system. We need to sign the
+firmware update binaries with our own keys.
+
+List binaries for UEFI firmware updates with `ls /usr/lib/fwupd/efi/fwupdx64.efi`.
+Then sign it and store it at `/usr/lib/fwupd/efi/fwupdx64.efi.signed`:
+
+```sh
+sbctl sign /usr/lib/fwupd/efi/fwupdx64.efi -o /usr/lib/fwupd/efi/fwupdx64.efi.signed -s
+```
+
+Once this is done, it will be automatically executed when there are future updates thanks to a `sbctl`
+hook in pacman.
+
+Finally disable the unushed shim mechanism. Create or modify `/etc/fwupd/fwupd.conf`
+
+```ini
+[uefi_capsule]
+DisableShimForSecureBoot=true
+```
+
+Restart `systemctl restart fwupd.service`.
+You can now run `fwupdmgr update` to update firmware on your device.
+
+[^1]: <https://www.phoronix.com/news/Intel-QAT-FSCRYPT-Linux-6.17>