Merge branch 'merge-requests/23'

5 files changed, 58 insertions, 81 deletions

diff --git a/en/appendix/preseed.xml b/en/appendix/preseed.xml
index 0a4582149..189d7c76b 100644
--- a/en/appendix/preseed.xml
+++ b/en/appendix/preseed.xml
@@ -957,6 +957,10 @@ d-i netcfg/wireless_wep string
 # The wacky dhcp hostname that some ISPs use as a password of sorts.
 #d-i netcfg/dhcp_hostname string radish
 
+# If you want to completely disable firmware lookup (i.e. not use firmware
+# files or packages that might be available on installation images):
+#d-i hw-detect/firmware-lookup string never
+
 # If non-free firmware is needed for the network or other hardware, you can
 # configure the installer to always try to load it, without prompting. Or
 # change to false to disable asking.
@@ -1427,6 +1431,8 @@ earlier questions. You can optionally add other (local) repositories.
 # Choose, if you want to scan additional installation media
 # (default: false).
 d-i apt-setup/cdrom/set-first boolean false
+# You can choose to install non-free firmware.
+#d-i apt-setup/non-free-firmware boolean true
 # You can choose to install non-free and contrib software.
 #d-i apt-setup/non-free boolean true
 #d-i apt-setup/contrib boolean true
diff --git a/en/hardware/hardware-supported.xml b/en/hardware/hardware-supported.xml
index f1dddcc5e..fb135e6c9 100644
--- a/en/hardware/hardware-supported.xml
+++ b/en/hardware/hardware-supported.xml
@@ -349,11 +349,6 @@ With many graphics cards, basic functionality is available without
 additional firmware, but the use of advanced features requires an
 appropriate firmware file to be installed in the system.
 
-In some cases, a successful installation can still end up in a black
-screen or garbled display when rebooting into the installed system. If
-that happens, some workarounds can be tried to log in anyway (see
-<xref linkend="completing-installed-system"/>).
-
 </para><para>
 
 On many older devices which require firmware to work, the firmware file was
@@ -365,20 +360,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 section
-of the archive.
+it will often be available as a separate package from the non-free-firmware section
+of the archive (prior to &debian-gnu; 12.0: from the non-free section).
+
+</para><para>
+
+However, this does not mean that such hardware cannot be used during
+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 modalias
+information), and install the relevant packages if they are found on
+an installation medium (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>
 
-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.
+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>
 
diff --git a/en/post-install/orientation.xml b/en/post-install/orientation.xml
index 2f6d09bde..98f772da9 100644
--- a/en/post-install/orientation.xml
+++ b/en/post-install/orientation.xml
@@ -63,7 +63,7 @@ line version of <command>apt</command> as well as tools like
 <application>aptitude</application> or <application>synaptic</application>
 (which are just graphical frontends for <command>apt</command>).
 Note that apt will also let you merge
-main, contrib, and non-free so you can have restricted packages
+main, contrib, non-free, and non-free-firmware so you can have restricted packages
 (strictly speaking not belonging to &debian;) as well as packages from
 &debian-gnu; at the same time.
 
diff --git a/en/using-d-i/loading-firmware.xml b/en/using-d-i/loading-firmware.xml
index 958615397..5b96cf802 100644
--- a/en/using-d-i/loading-firmware.xml
+++ b/en/using-d-i/loading-firmware.xml
@@ -13,6 +13,17 @@ additional features.
 
 </para><para>
 
+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 (like netinst) can include non-free firmware packages.
+
+Even with those firmware packages available, some firmware files might
+still be missing. Or one might be using netboot files, which don't
+include firmware packages.
+
+</para><para>
+
 If a device driver requests firmware that is not available, &d-i; will
 display a dialog offering to load the missing firmware. If this option
 is selected, &d-i; will scan available devices for either loose firmware
@@ -37,27 +48,14 @@ Note that it is possible to skip loading the firmware if you know the
 device will also function without it, or if the device is not needed during
 the installation.
 
-</para><para>
-
-&d-i; only prompts for firmware needed by kernel modules loaded during
-the installation. Not all drivers are included in &d-i;, in particular
-radeon is not, so this implies that the capabilities of some devices may
-be no different at the end of the installation from what they were at
-the beginning. Consequently, some of your hardware may not be being used
-to its full potential. If you suspect this is the case, or are just
-curious, it is not a bad idea to check the output of the
-<command>dmesg</command> command on the newly booted system and search
-for <quote>firmware</quote>. 
-
 </para>
 
   <sect2><title>Preparing a medium</title>
 <para>
 
-Official installation images do not include non-free firmware. The most common
+The most common
 method to load such firmware is from some removable medium such as a USB
-stick. Alternatively, unofficial installation images containing non-free firmware
-can be found at <ulink url="&url-firmware-cds;"/>.
+stick.
 
 To prepare a USB stick (or other medium like a hard drive partition),
 the firmware files or packages must be placed in either the root directory
@@ -67,8 +65,9 @@ certain to be supported during the early stages of the installation.
 
 </para><para>
 
-Tarballs and zip files containing current packages for the most common firmware are
-available from:
+Tarballs and zip files containing current packages for the most common
+firmware, and the associated metadata to ensure a proper detection by
+the installer (<filename>dep11</filename> directory), are available from:
 
 <itemizedlist>
 <listitem><para>
@@ -81,20 +80,6 @@ the file system on the medium.
 
 </para><para>
 
-If the firmware you need is not included in the tarball, you can also
-download specific firmware packages from the (non-free section of the)
-archive. The following overview should list most available firmware
-packages but is not guaranteed to be complete and may also contain
-non-firmware packages:
-
-<itemizedlist>
-<listitem><para>
-<ulink url="&url-firmware-packages;"/>
-</para></listitem>
-</itemizedlist>
-
-</para><para>
-
 It is also possible to copy individual firmware files to the medium. Loose
 firmware could be obtained for example from an already installed system or
 from a hardware vendor.
@@ -115,7 +100,7 @@ the firmware cannot be loaded due to version skew.
 </para><para>
 
 If the firmware was loaded from a firmware package, &d-i; will also install
-this package for the installed system and will automatically add the non-free
+this package for the installed system and will automatically add the non-free-firmware
 section of the package archive in APT's <filename>sources.list</filename>.
 This has the advantage that the firmware should be updated automatically if
 a new version becomes available.
@@ -161,37 +146,5 @@ system. When that happens, the following workarounds can be tried:
   key combination to switch to VT2, which might offer a functional
   login prompt.</para></listitem>
 </itemizedlist>
-
-<para>
-
-Once logged in into the installed system, it is possible to automate
-the detection of missing firmware, and to perform the required steps to
-enable them following this procedure:
-
-</para><orderedlist>
-  <listitem><para>Install the <classname>isenkram-cli</classname>
-  package.</para></listitem>
-
-  <listitem><para>Run the
-  <command>isenkram-autoinstall-firmware</command> command as the
-  <quote>root</quote> user.</para></listitem>
-</orderedlist><para>
-
-Usually, rebooting is the simplest way to make sure all kernel modules
-are properly initialized; that's particularly important when one has
-booted the system with the <code>nomodeset</code> option as an
-interim measure.
-
-</para><note><para>
-
-Installing firmware packages is very likely to require enabling the
-non-free section of the package archive. As of &debian-gnu; 11.0,
-running the <command>isenkram-autoinstall-firmware</command> command
-will do that automatically by creating a dedicated file
-(<filename>/etc/apt/sources.list.d/isenkram-autoinstall-firmware.list</filename>),
-pointing at a generic mirror.
-
-</para></note>
-
   </sect2>
  </sect1>
diff --git a/en/using-d-i/modules/apt-setup.xml b/en/using-d-i/modules/apt-setup.xml
index 37484594b..4d77b204c 100644
--- a/en/using-d-i/modules/apt-setup.xml
+++ b/en/using-d-i/modules/apt-setup.xml
@@ -48,7 +48,7 @@ mirror and, if you are installing the stable distribution, a mirror for the
 If you are installing at a lower priority (e.g. in expert mode), you will
 be able to make more decisions yourself. You can choose whether or not to
 use the security and/or stable-updates services, and you can choose to
-add packages from the <quote>contrib</quote> and <quote>non-free</quote>
+add packages from the <quote>contrib</quote>, <quote>non-free</quote>, and <quote>non-free-firmware</quote>
 sections of the archive.
 
 </para>