[gentoo-dev] [PATCH 0/7] Changes to dracut kernel module/microcode handling

[Andrew Nowa Ammerlaan <andrewammerlaan@gentoo.org>]

Hi all,

This patch series essential moves the dist-kernel initramfs/UKI 
rebuilding out off zfs-kmod.ebuild and into linux-mod-r1.eclass.

In the process we fix several issues:
- zfs-kmod.ebuild binpkgs no longer rebuild currently running kernel, 
but uses instead the kernel version that matches the version the modules 
were built for (Bug 931213, commit 1,2,3,6,7).
- zfs.ebuild binpkgs no longer rebuild currently running kernel, but use 
the eselected kernel instead (commit 6,7). In most "normal" cases the 
eselected kernel version will match the kernel version zfs-kmod modules 
were built for due to the slot operator on the virtual/dist-kernel 
dependency in both ebuilds, and the automatic adjustments of the 
/usr/src/linux symlink when dist-kernels are used. (TODO: consider 
merging the zfs and zfs-kmod ebuilds to make this 100% robust).
- Which modules are and which ones are not included in the Dracut 
generated initramfs is now properly defined and won't change after 
random dist-kernel reinstallations (commit 1,2).
- As a result of the above, Dracut's "--reproducible" setting actually 
makes something that is reproducible (apart from package upgrades and 
configuration changes of course).
- It is now super easy for kernel module package maintainers to define 
that a module can be included in the initramfs, USE flags and 
(initramfs/UKI) rebuilds are taken care off by the eclass (commits 1,2)
- We mirror the changes to the kernel modules in the packages that 
install CPU microcode (linux-firmware and intel-microcode) by 
introducing the "dist-kernel" flag there which alters the behaviour of 
the "initramfs" flag to instead configure Dracut to include the 
microcode and then rebuild the Dracut initramfs/UKI. This ensures that 
microcode updates are always propagated into the initramfs. (commits 4,5)

Most users will not have to do anything, we are only setting defaults in 
/usr/lib/dracut/dracut.conf.d, the (existing) user configuration in 
/etc/dracut.conf.d takes precedence. Nonetheless, I wrote a news item to 
accompany these changes, users should ensure that they do not 
unintentionally overwrite USE=initramfs, and they may also want to get 
rid of custom configuration/workarounds they have set in /etc/dracut.conf.

Best regards,
Andrew


Title: Changes to dracut kernel module/microcode handling
Author: Andrew Ammerlaan <andrewammerlaan@gentoo.org>
Posted: 2024-05-10
Revision: 1
News-Item-Format: 2.0
Display-If-Installed: sys-kernel/dracut
Display-If-Installed: virtual/dist-kernel
Display-If-Installed: sys-kernel/linux-firmware
Display-If-Installed: sys-firmware/intel-microcode


Impact
====================

Several changes were made regarding out-of-tree kernel modules, CPU
microcode, and how these are handled in initial RAM file systems
(initramfs) generated by sys-kernel/dracut for distribution kernels.
Depending on the local Dracut and USE flag configuration, some
configuration adjustments may be required as a result of these changes.

Background (the problem)
====================

Previously Dracut implicitly included all out-of-tree kernel modules
it could find. This leads to several problems:
- It unnecessarily increases the size of the initramfs
- It creates a bit of a mess when using distribution kernels, consider
	the following:
		1) Distribution kernel is upgraded
		2) Initramfs for the new kernel is generated, it does not include
			any out-of-tree kernel modules.
		3) Portage triggers rebuild of the out-of-tree kernel modules
		4) If zfs is installed, its rebuild will trigger an initramfs
			re-installation. Otherwise no rebuild is triggered.
	Problem: What is and is not included in the initramfs is now
	ambiguous. It depends on the emerge order of the kernel modules
	when zfs is used. And will completely change if at some later stage
	regeneration of the initramfs is triggered manually via e.g.:
		emerge --config sys-kernel/gentoo-kernel
	As a result, Dracut's "--reproducible" setting is not working. And
	the functionality of the initramfs may change (seemingly) at random.

Background (the fix)
====================

Several things have been changed:
- Out-of-tree kernel modules installed by portage are explicitly omitted
	from the initramfs generated by Dracut by default.
- Packages that install a kernel module for which it might make sense to
	have it in the initramfs, have gained the "initramfs" USE flag. When
	this flag is enabled, Dracut is instructed to include the installed
	kernel modules. Packages for which it is essential that its kernel
	modules are included in the initramfs have this new flag enabled
	by default.
- When distribution kernels are used (USE=dist-kernel), and a module
	that should be in the initramfs is installed (USE=initramfs) the
	initramfs is always re-generated.
- The packages installing CPU microcode (sys-kernel/linux-firmware
	and sys-firmware/intel-microcode) have been adjusted to mirror the
	above changes for out-of-tree kernel modules. Both packages
	have gained the "dist-kernel" USE flag, and the "initramfs" flag is
	now enabled by default. When both flags are enabled, Dracut is
	configured to include the installed microcode in the initramfs, and
	then the initramfs is regenerated. When the "dist-kernel" flag is
	disabled, the "initramfs" flag behaves as it previously did.

User Action Required
====================

Users should double check two things:
1) Please ensure that you are *not* globally enabling or disabling
	the "initramfs" USE flag. Enabling it globally might result in an
	unnecessarily large initramfs. Disabling it globally might result
	in missing functionality in the initramfs. Which could lead to boot
	failure if, for example, the zfs module is missing while the root
	partition is a zfs.
2) Any add_drivers, or omit_drivers lines in /etc/dracut.conf or
	/etc/dracut.conf.d/* may override the Dracut configuration snippets
	installed by the kernel module packages in
	/usr/lib/dracut/dracut.conf.d.  Please review your Dracut
	configuration files to ensure that you are not unintentionally
	overriding the settings set by Portage.

Frequently Asked Questions
====================

A package installing a kernel module I would like in my initramfs has
not gained the "initramfs" USE flag. How do I proceed?

	Please report a new bug on bugs.gentoo.org, requesting that the
	package maintainer consider adding support to the package for
	including the modules in the initramfs. In the meantime you can
	locally override the configuration provided by the package (see
	below). Note though that when distribution kernels are used,
	regeneration of the initramfs must be triggered manually via e.g.:
		emerge --config sys-kernel/gentoo-kernel

How do I override the provided Dracut configuration snippets to
include/exclude a custom list of modules?

	To override the provided configuration snippet, create a new file
	/etc/dracut.conf.d/10-PACKAGENAME.conf, replacing PACKAGENAME with
	the name of the package providing the module. Add to this file:
		omit_drivers+=" my list of drivers to omit "
	and/or
		add_drivers+=" my list of drivers to include "