Bug#991627: installation-guide: expand firmware-related documentation
Source: installation-guide
Severity: important
X-Debbugs-Cc: debian-release@lists.debian.org, isenkram@packages.debian.org
[ RT and isenkram maintainers in the loop for information ]
Hi,
This bug report is about the first part of the proposal outlined in this
other bug report:
https://bugs.debian.org/989863
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.
→ https://www.debian.org/releases/bullseye/amd64/ch02s01#gfx
- 2.2, which pretends graphics cards should work at least minimally
(which tends not to be true), and which also points at 6.4.
→ https://www.debian.org/releases/bullseye/amd64/ch02s02
- 6.4, which documents a number of things.
→ https://www.debian.org/releases/bullseye/amd64/ch06s04
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);
→ https://salsa.debian.org/installer-team/installation-guide/-/commit/09375ab4dfd366560d86bda554cd8d89c8920294
- 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
missing firmware.
→ https://salsa.debian.org/installer-team/installation-guide/-/commit/ed2ec80f30e4a024ed5d061e03251af5f7a28e00
For now, both commits are in a pu/firmware-v0 branch in the installation
guide repository.
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
required!
Some remarks:
- 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
point).
- 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
unreasonable though.
Cheers,
--
Cyril Brulebois (kibi@debian.org) <https://debamax.com/>
D-I release manager989863 -- Release team member -- Freelance Consultant
Reply to: