From d7fe9f1fc96b83899c1528971d069b23ebcc4250 Mon Sep 17 00:00:00 2001
From: projectmoon <projectmoon@agnos.is>
Date: Tue, 8 Nov 2022 17:16:00 +0100
Subject: [PATCH] Update readme

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 51 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 9ea1922..4d148e9 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,11 @@ Personal Gentoo overlay, focusing mostly on needed tools and
 compatibility for the Librem 14 computer.
 
 Available packages:
- - **dev-util/rust-analyzer-bin**: A properly versioned ebuild of
-   rust-analyzer-bin.
-- **sys-kernel/librem-ec-acpi**: An ebuild packaging the [Librem 14
-   EC ACPI kernel module][ec-acpi], necessary for proper functioning
-   of the laptop's battery charging and function keys.
+ - **sys-kernel/libre-kernel**: A dist-kernel built from the [Linux-libre
+   sources][linux-libre].
+ - **sys-kernel/librem-ec-acpi**: An ebuild packaging the [Librem 14
+    EC ACPI kernel module][ec-acpi], necessary for proper functioning
+	of the laptop's battery charging and function keys.
 
 ## How to Add This Repository
 
@@ -16,6 +16,43 @@ Using eselect-repository:
 # eselect repository add projectmoon git https://git.agnos.is/projectmoon/projectmoon-overlay
 ```
 
+## The Linux-libre dist-kernel
+
+This overlay provides a dist-kernel (based on
+`sys-kernel/vanilla-kernel`) using the Linux-libre kernel sources, and
+an accompanying updated version of `virtual/dist-kernel`. It is
+maintained and tested for my personal use on amd64. The Linux-libre
+kernel removes the ability for the Linux kernel to load firmware that
+is not [Free Software][free-software]. The ebuild follows the current
+stable gentoo-kernel for amd64.
+
+The libre kernel can be installed alongside other dist-kernels, and
+works with the `dist-kernel` and `initramfs` USE flags. The ebuild
+does NOT fail if non-free firmware (i.e. `sys-kernel/linux-firmware`
+with `redistributable` USE flag set) is installed, but it will warn
+you if this is the case. It will also warn you if the `linux-firmware`
+package is not found at all, like normal dist-kernel ebuilds.
+
+The kernel installed by this ebuild has the version suffix
+`-gnu-dist`, making it easy to determine which kernel it is.
+
+To install only the Linux firmware that meets the [Free Software
+Definition][free-software], configure `/etc/portage/package.use` accordingly:
+
+```
+# Install only libre firmware
+sys-kernel/linux-firmware -redistributable -unknown-license
+```
+
+You can also edit `/etc/portage/profile/package.use.mask` to prevent
+the linux-firmware package from ever installing the closed-source
+firmware by adding this line:
+
+```
+# forcibly stop non-free firmware installation
+sys-kernel/linux-firmware redistributable unknown-license
+```
+
 ## Using the Librem EC ACPI kernel module
 
 The Librem EC ACPI kernel module should install and be automatically
@@ -23,7 +60,14 @@ available (via modprobe) after installation, using `emerge
 sys-kernel/librem-ec-acpi`. The module is currently installed to
 `/lib/modules/<kernel>/librem/`.
 
-When upgrading or installing a new kernel, you will need to do `emerge
-@modules-rebuild` to install the module for the new kernel.
+This ebuild supports the `dist-kernel` USE flag, and the module will
+automatically be rebuilt when installing a new dist-kernel if that
+flag is enabled.
 
+If you are not using a dist-kernel, when upgrading or installing a new
+kernel, you will need to do `emerge @modules-rebuild` to install the
+module for the new kernel.
+
+[linux-libre]: https://www.fsfla.org/ikiwiki/selibre/linux-libre/
+[free-software]: https://www.gnu.org/philosophy/free-sw.en.html#fs-definition
 [ec-acpi]: https://source.puri.sm/nicole.faerber/librem-ec-acpi-dkms