Bug#991627: installation-guide: expand firmware-related documentation
X-Debbugs-Cc: email@example.com, firstname.lastname@example.org
[ RT and isenkram maintainers in the loop for information ]
This bug report is about the first part of the proposal outlined in this
other bug report:
which is trying to be a bit more helpful regarding firmware problems.
Looking at the amd64 documentation, there are several places where
firmware is mentioned:
- 2.1.5, which basically points at 2.2.
- 2.2, which pretends graphics cards should work at least minimally
(which tends not to be true), and which also points at 6.4.
- 6.4, which documents a number of things.
At first glance, I'm proposing:
- not to change 2.1.5;
- to amend 2.2, mentioning graphics cards might be problematic, and
mentioning nomodeset as a possible workaround (plus another pointer
at 6.4 right after that);
- to extend 6.4, mentioning nomodeset again (for people who haven't
seen 2.2 first), as well as an automated way to detect and install
For now, both commits are in a pu/firmware-v0 branch in the installation
I'm not very used to best practices when it comes to end-user doc in
general and to the installation-guide package in general, so I'd be
happy for other to build on those suggested changes, and amend/reword as
- There's a copy-paste for the “nomodeset” option, which I suppose
could be avoided with some include logic. This might avoid duplicate
works on the l10n front (which might be important due to the next
- This is a *possible* workaround, as I have not been able to test it
(I couldn't reproduce the black screen issue with test hardware). I
plan to have some kind of survey organized to see if people affected
by this issue can confirm.
- 6.4.1 points at `unofficial/non-free/firmware/` which have been made
to work out of the box (as much as possible) as detailed in #989863,
but “the archive (tar or zip) on a separate support” use case wasn't
tackled yet (in particular detecting graphics firmware might be
required, even if the installer didn't spot that on its own due to
using generic drivers). I don't think it makes sense to document that
separately, as we might improve this in a point release, and the
“nomodeset workaround” + “isenkram procedure” combination should be
enough to fix things up from the installed system.
- I documented in a note what happens with that “isenkram procedure”
since mentioning non-free seemed to be the bare minimum. We might
skip mentioning contrib though (see earlier note in 6.4.2; the logic
is exactly the same though — same code!).
- Documenting what isenkram-autoinstall-firmware does means we should
check what happens for each major release, to keep up with the
current implementation. Doing that once every two years doesn't seem
Cyril Brulebois (email@example.com) <https://debamax.com/>
D-I release manager989863 -- Release team member -- Freelance Consultant