Documentation/admin-guide/reporting-issues.rst

27 <https://kernel.org/>`_. If the issue is present there, send a report.
32 check if backporting is in the works or was discarded; if it's neither, ask
47 Once the report is out, answer any questions that come up and help where you
57 everyone else there is this section. It is more detailed and uses a
64 early if an issue that looks like a Linux kernel problem is actually caused by
119    situations; during the merge window that actually might be even the best
134    details, and at the same time is easy to read and understand for others
141  * If your problem is a regression, try to narrow down when the issue was
154    thing a descriptive title or subject that yet again is shorter. Then you're
157    special care which is explained in 'Special handling for high priority
171 This subsection is for you, if you followed above process and got sent here at
175 regressions as quickly as possible, hence there is a streamlined process to
187    kernel. Ensure this kernel is not tainted and still shows the problem, as
206 This subsection is for you, if you tried the latest mainline kernel as outlined
219    the issue in mainline, as its commit message might tell you if the fix is
240 what this section is for, as it will provide a lot more details on each of the
247  * The Linux kernel developers are well aware this process is complicated and
288 sides. That's because almost all Linux-based kernels pre-installed on devices
307 Note, the previous paragraph is starting with the word 'most', as sometimes
315 its only slightly modified; that for example is often the case for Arch Linux,
336 Reporting an issue that someone else already brought forward is often a waste of
356 often is not much helpful, as it is too specific. Instead try search terms like
362 important even when a fix is prepared or in its final stages already, as
397 What qualifies as security issue is left to your judgment. Consider reading
401 An issue is a 'really severe problem' when something totally unacceptably bad
428  * Try to make sure it's not faulty hardware that is causing your issue. Bad
472 Note, you might not be aware that your system is using one of these solutions:
487 be such an error if your kernel is tainted. That's why it's in your interest to
488 rule this out early before investing more time into this process. This is the
489 only reason why this step is here, as this process later will tell you to
494 On a running system is easy to check if the kernel tainted itself: if ``cat
495 /proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and
496 everything is fine. Checking that file is impossible in some situations; that's
505 If your kernel is tainted, study Documentation/admin-guide/tainted-kernels.rst
532     Linux kernel developers. Most of the time the easiest way to do that is:
540     obviously okay if the kernel is tainted; just make sure the module in
541     question is the only reason for the taint. If the issue happens in an
571 is hard to reproduce.
585 possible, hence there is a streamlined process to report them. Note,
598 It's crucial to send your report to the right people, as the Linux kernel is a
605 Problem is: the Linux kernel lacks a central bug tracker where you can simply
609 kernel developers and experts. For everybody else the MAINTAINERS file is the
621 Sadly, there is no way to check which code is driving a particular hardware
622 component that is both universal and easy.
636 But this approach won't work if your WiFi chip is connected over USB or some
647 are unsure which it is: just try your best guess, somebody will help you if you
652 name is too specific. Sometimes you will need to search on the net for help;
679 example above does not have such a line. That is the case for most sections, as
680 Linux kernel development is completely driven by mail. Very few subsystems use
686 list:', which tells you the public mailing list where the code is developed.
692 and LKML is important to have one place where all issue reports can be found.
698 For people that have the Linux sources at hand there is a second option to find
728 areas rarely changed (like old or unmaintained drivers): sometimes such code is
741 brought forward is often a waste of time for everyone involved, especially you
746 But some list are hosted in different places. That for example is the case for
776     situations; during the merge window that actually might be even the best
794    most of the time is better avoided. Longterm kernels (sometimes called 'LTS
799    It also outlines that using a pre-compiled kernel are fine, but better are
809 mainline, which most of the time will point to a pre-release with a version
817 suspending the reporting process until the first pre-release of the next
819 cycle then is in its two-week long 'merge window'. The bulk of the changes and
823 also quite possible that one of the many changes applied during the merge
828 That's why it might make sense to wait till the merge window is over. But don't
831 latest stable version offered on kernel.org. Using that is also acceptable in
833 using it for reproducing the issue is also better than not reporting it issue
836 Better avoid using the latest stable kernel outside merge windows, as all fixes
838 kernel is so important: any issue you want to see fixed in older version lines
841 hard or risky for backporting; reporting the issue again hence is unlikely to
853 **Using a pre-compiled kernel**: This is often the quickest, easiest, and safest
854 way for testing — especially is you are unfamiliar with the Linux kernel. The
871 document. Also be aware that pre-compiled kernels might lack debug symbols that
881 Those are likely a bit ahead of the latest mainline pre-release. Don't worry
882 about it: they are as reliable as a proper pre-release, unless the kernel's
883 development cycle is currently in the middle of a merge window. But even then
889 How to actually build a kernel is not described here, as many websites explain
899 latter is the relevant one of those two, but can only be reached if you enable
905 But keep in mind: Always keep a record of the issue encountered in case it is
906 hard to reproduce. Sending an undecoded report is better than not reporting
946     details, and at the same time is easy to read and understand for others
1008 is, someone might help you to get things going. Also be aware this is just one
1017     *If your problem is a regression, try to narrow down when the issue was
1024 way. Reporting a regression is thus a bit like playing a kind of trump card to
1030 To find the change there is a process called 'bisection' which the document
1042 bit of effort, which not everyone is willing to invest. Nevertheless, it's
1057 When dealing with regressions make sure the issue you face is really caused by
1081     thing a descriptive title or subject that yet again is shorter. Then you're
1084     special care which is explained in 'Special handling for high priority
1088 that is partly explained by the three documents linked to in the preface above.
1092 There is one thing that fits both categories: the most crucial parts of your
1097 will look into it and help you. And that is why you should ignore them for now
1116  * the Linux distribution the machine is running (``hostnamectl | grep
1122    subject and the commit-id of the change that is causing it.
1158 few suggestions what often is good to provide:
1166    mention its manufacturer, the card's model, and what chip is uses. If it's a
1168    for example is not, because it might be the one from 2012; that one looks
1191    information. One such tool is ``alsa-info.sh`` `which the audio/sound
1209 crucial parts readers need to know to understand what this is all about; if you
1213 summary that explains quickly what the report is about. After that you have to
1216 Now that you have written this part take some time to optimize it, as it is the
1218 they decide if reading the rest is time well spent.
1289 all you need to do is reply with a 'Thank you very much' and switch to a version
1292 But this ideal scenario rarely happens. That's why the job is only starting
1309 also keeps the mail thread intact, which among others is really important for
1313 is unsuitable:
1338 reports. Sometimes it will take longer, as they might be busy with the merge
1356 **Proactive testing**: Every time the first pre-release (the 'rc1') of a new
1357 mainline kernel version gets released, go and check if the issue is fixed there
1389 wait; that outcome is even likely if you do not provide the information within
1395 of confusion for everyone involved. A common mistake for example is thinking a
1410 writing the reminder, kindly ask if anything else from your side is needed to
1412 first lines of a mail that is a reply to your initial mail (see above) which
1414 situations where such a 'TOFU' (Text Over, Fullquote Under) is the right
1425 review it before you send it out. Such an approach is totally fine; just
1426 mention that this is the second and improved report on the issue and include a
1431 mail is shortly after the first pre-release (the 'rc1') of a new Linux kernel
1448 a fix. Such situations can be devastating, but is within the cards when it
1454 not get solved: the Linux kernel is FLOSS and thus you can still help yourself.
1457 together that mentions how many you are and why this is something that in your
1479 maintaining them longer is quite a lot of work. Hence, only one per year is
1486 support for it is likely to be abandoned soon. Then it will get a "end-of-life"
1496 Maybe the issue you face is already known and was fixed or is about to. Hence,
1499 you find any matches, consider joining the discussion, unless the fix is
1506     kernel. Ensure this kernel is not tainted and still shows the problem, as
1538 line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for
1540 stable and regressions mailing list is all it takes; but in case you suspect
1553 is still broken.
1555 What the previous paragraph outlines is basically a rough manual 'bisection'.
1556 Once your report is out your might get asked to do a proper one, as it allows to
1614     the issue in mainline, as its commit message might tell you if the fix is
1671 If the previous three steps didn't get you closer to a solution there is only
1687 This is best explained with kernel developers that contribute to the Linux
1701 Maybe their test hardware broke, got replaced by something more fancy, or is so
1705 nobody is willing to take over the job as maintainer – and nobody can be forced
1706 to, as contributing to the Linux kernel is done on a voluntary basis. Abandoned
1710 The situation is not that different with developers that are paid for their
1723 quite often are forced to set those, as time to work on Linux is limited.
1726 get overwhelmed with reports, even if a driver is working nearly perfectly. To
1740 it is for now. The main author of this text hopes documenting the state of the
1747    This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
1755    This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
1762    is available under CC-BY-4.0, as versions of this text that were processed