Merge branch 'pu/firmware-v2'

3 files changed, 71 insertions, 5 deletions

diff --git a/README b/README
index a5335133c..dd371cbdb 100644
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
-Here is the new manual. It is in Docbook XML format, which is
-becoming the new standard for documentation. The advantages include
+This is the Debian Installer documentation for end users. It is in
+Docbook XML format, which is a standard for documentation. The advantages include
 more precise tagging, figure and table support, and a very strongly
 supported toolchain. There is a fairly brief cheatsheet.xml here which
 will probably tell you all you need to know, especially if you've
@@ -7,7 +7,7 @@ worked with debiandoc before. The Definitive Guide to DocBook by Norm
 Walsh is indispensable for figuring out why your tags don't work the
 way you think they should:
 
-http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html
+https://www.oreilly.com/catalog/docbook/chapter/book/docbook.html
 
 The sources can be found at
 https://salsa.debian.org/installer-team/installation-guide
@@ -15,7 +15,7 @@ Checkout with:
 git clone git@salsa.debian.org:installer-team/installation-guide.git
 
 For more information about the manual, see:
-http://d-i.debian.org/manual/
+https://d-i.debian.org/manual/
 
 See also the various files in the subdirectory doc.
 
@@ -23,7 +23,7 @@ All help is welcome! Send suggestions to the debian-boot list. Patches
 can be submitted against the package installation-guide.
 
 Patches should normally be submitted against the 'master' branch of
-the manual, so they will be included in the next stable release.
+the manual, so they will be included in the next upload.
 However there are some cases where it is appropriate to update the
 stable release also: such patches should be made against the branch
 for the relevant stable release codename.
diff --git a/en/hardware/hardware-supported.xml b/en/hardware/hardware-supported.xml
index bd2193046..04411b800 100644
--- a/en/hardware/hardware-supported.xml
+++ b/en/hardware/hardware-supported.xml
@@ -401,10 +401,18 @@ so-called <firstterm>firmware</firstterm> or <firstterm>microcode</firstterm>
 to be loaded into the device before it can become operational. This is most
 common for network interface cards (especially wireless NICs), but for example
 some USB devices and even some hard disk controllers also require firmware.
+
+</para><para>
+
 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
diff --git a/en/using-d-i/loading-firmware.xml b/en/using-d-i/loading-firmware.xml
index 4e60aa9d5..a07a72ac5 100644
--- a/en/using-d-i/loading-firmware.xml
+++ b/en/using-d-i/loading-firmware.xml
@@ -136,4 +136,62 @@ the installation is completed.
 
 </para></note>
   </sect2>
+
+  <sect2 id="completing-installed-system"><title>Completing the Installed System</title>
+<para>
+
+Depending on how the installation was performed, it might be that the
+need for some firmware was not detected during installation, that the
+relevant firmware was not available, or that one chose not to install
+some firmware at that time.
+
+In some cases, a successful installation can still end up in a black
+screen or a garbled display when rebooting into the installed
+system. When that happens, the following workarounds can be tried:
+
+</para>
+
+<itemizedlist>
+  <listitem><para>Pass the <code>nomodeset</code> option on the kernel
+  command line. This might help boot into a <quote>fallback
+  graphics</quote> mode.</para></listitem>
+
+  <listitem><para>Use the
+  <keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F2</keycap></keycombo>
+  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>