Document support in the installer for loading missing firmware

1 files changed, 133 insertions, 0 deletions

diff --git a/en/using-d-i/loading-firmware.xml b/en/using-d-i/loading-firmware.xml
new file mode 100644
index 000000000..dad39ebda
--- /dev/null
+++ b/en/using-d-i/loading-firmware.xml
@@ -0,0 +1,133 @@
+<!-- retain these comments for translator revision tracking -->
+<!-- $Id$ -->
+
+ <sect1 id="loading-firmware" arch="not-s390">
+ <title>Loading Missing Firmware</title>
+<para>
+
+As described in <xref linkend="hardware-firmware"/>, some devices require
+firmware to be loaded. In most cases the device will not work at all
+if the firmware is not available; sometimes basic functionality is not
+impaired if it is missing and the firmware is only needed to enable
+additional features.
+
+</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
+files or packages containing firmware. If found, the firmware will be
+copied to the correct location (<filename>/lib/firmware</filename>) and
+the driver module will be reloaded.
+
+</para>
+<note><para>
+
+Which devices are scanned and which file systems are supported depends on
+the architecture, the installation method and the stage of the installation.
+Especially during the early stages of the installation, loading the firmware
+is most likely to succeed from a FAT-formatted floppy disk or USB stick.
+<phrase arch="x86">On i386 and amd64 firmware can also be loaded from an
+MMC or SD card.</phrase>
+
+</para></note>
+<para>
+
+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>
+<warning><para>
+
+Support for loading firmware is still relatively basic and is likely to
+be improved in future releases of the installer. Currently &d-i; will
+for example not display any warning if you choose to load missing firmware,
+but the requested firmware is not found.
+Please <xref linkend="submit-bug">report</xref> any issues you encounter.
+
+</para></warning>
+
+  <sect2><title>Preparing a medium</title>
+<para>
+
+Although in some cases the firmware can also be loaded from a partition on
+a hard disk, the most common method to load firmware will be from some
+removable medium such as a floppy disk or a USB stick.
+The firmware files or packages must be placed in either the root directory
+or a directory named <filename>/firmware</filename> of the file system on
+the medium. The recommended file system to use is FAT as that is most
+certain to be supported during the early stages of the installation.
+
+</para><para>
+
+Tarballs containing current packages for the most common firmware are
+available from:
+
+<itemizedlist>
+<listitem><para>
+<ulink url="&url-firmware-tarballs;"/>
+</para></listitem>
+</itemizedlist>
+
+Just download the tarball for the correct release and unpack it to 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.
+
+</para>
+  </sect2>
+
+  <sect2><title>Firmware and the Installed System</title>
+<para>
+
+Any firmware loaded during the installation will be copied automatically
+to the installed system. In most cases this will ensure that the device
+that requires the firmware will also work correctly after the system is
+rebooted into the installed system. However, if the installed system runs
+a different kernel version from the installer there is a slight chance that
+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
+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.
+
+</para><para>
+
+If loading the firmware was skipped during the installation, the relevant
+device will probably not work with the installed system until the firmware
+(package) is installed manually.
+
+</para>
+<note><para>
+
+If the firmware was loaded from loose firmware files, the firmware copied to
+the installed system will <emphasis>not</emphasis> be automatically updated
+unless the corresponding firmware package (if available) is installed after
+the installation is completed.
+
+</para></note>
+  </sect2>
+ </sect1>