Explain non-free-firmware vs. hw-detect/apt-setup.

1 files changed, 31 insertions, 8 deletions

diff --git a/en/hardware/hardware-supported.xml b/en/hardware/hardware-supported.xml
index d37c3983f..5b16c20de 100644
--- a/en/hardware/hardware-supported.xml
+++ b/en/hardware/hardware-supported.xml
@@ -365,20 +365,43 @@ the host operating system every time the system boots.
 </para><para>
 
 In most cases firmware is non-free according to the criteria used by the
-&debian-gnu; project and thus cannot be included in the main distribution
-or in the installation system. If the device driver itself is included in
+&debian-gnu; project and thus cannot be included in the main distribution.
+If the device driver itself is included in
 the distribution and if &debian-gnu; legally can distribute the firmware,
 it will often be available as a separate package from the non-free-firmware section
 of the archive (non-free before &debian-gnu; 12.0).
 
 </para><para>
 
-However, this does not mean that such hardware cannot be used during an
-installation. Starting with &debian-gnu; 5.0, &d-i; supports loading
-firmware files or packages containing firmware from a removable medium,
-such as a USB stick.
-See <xref linkend="loading-firmware"/> for detailed information on how to
-load firmware files or packages during the installation.
+However, this does not mean that such hardware cannot be used during
+an installation. Starting with &debian-gnu; 12.0, following the <ulink
+url="https://www.debian.org/vote/2022/vote_003">2022 General
+Resolution about non-free firmware</ulink>, official installation
+images can include non-free firmware packages. By default, &d-i; will
+detect required firmware (based on kernel logs and based on modalias
+information), and install the relevant packages if they are found on
+installation images (e.g. on the netinst). The package manager gets
+automatically configured with the matching components so that those
+packages get security updates. This usually means that the
+non-free-firmware component gets enabled, in addition to main.
+
+</para><para>
+
+Users who wish to disable firmware lookup entirely can do so by
+setting the <userinput>firmware=never</userinput> boot parameter.
+It's an alias for the longer
+<userinput>hw-detect/firmware-lookup=never</userinput> form.
+
+</para><para>
+
+Unless firmware lookup is disabled entirely, &d-i; still supports
+loading firmware files or packages containing firmware from a
+removable medium, such as a USB stick.  See <xref
+linkend="loading-firmware"/> for detailed information on how to load
+firmware files or packages during the installation.
+
+Note that &d-i; is less likely to prompt for firmware files now that
+non-free firmware packages can be included on installation images.
 
 </para><para>