Document the isenkram-based procedure (See: #989863, #991627).

Start by mentioning a few workarounds that might help log in into the
installed system: nomodeset & Ctrl-Alt-F2.

Document how to use isenkram-cli to automate firmware installation (and
mention what happens so that users are taken by surprise).

Finally, set an `id` for this new subsection so that it can be linked to
directly.

v2: Apply suggestions by Holger Wansing, thanks!

1 files changed, 58 insertions, 0 deletions

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>