sphinx.addnodesdocument)}( rawsource children](translations
LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}(hhparenthuba
attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget0/translations/zh_CN/admin-guide/reporting-issuesmodnameN classnameNrefexplicitutagnamehhhubh)}(hhh]hChinese (Traditional)}(hhhh2ubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/zh_TW/admin-guide/reporting-issuesmodnameN classnameNrefexplicituh1hhhubh)}(hhh]hItalian}(hhhhFubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/it_IT/admin-guide/reporting-issuesmodnameN classnameNrefexplicituh1hhhubh)}(hhh]hJapanese}(hhhhZubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ja_JP/admin-guide/reporting-issuesmodnameN classnameNrefexplicituh1hhhubh)}(hhh]hKorean}(hhhhnubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/ko_KR/admin-guide/reporting-issuesmodnameN classnameNrefexplicituh1hhhubh)}(hhh]hSpanish}(hhhhubah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget0/translations/sp_SP/admin-guide/reporting-issuesmodnameN classnameNrefexplicituh1hhhubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h
hh _documenthsourceNlineNubhcomment)}(h0SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)h]h0SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)}(hhhhubah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhJ/var/lib/git/docbuild/linux/Documentation/admin-guide/reporting-issues.rsthKubh)}(hFSee the bottom of this file for additional redistribution information.h]hFSee the bottom of this file for additional redistribution information.}(hhhhubah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubhsection)}(hhh](htitle)}(hReporting issuesh]hReporting issues}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe short guide (aka TL;DR)h]hThe short guide (aka TL;DR)}(hhhhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhK ubh paragraph)}(hXZ Are you facing a regression with vanilla kernels from the same stable or
longterm series? One still supported? Then search the `LKML
`_ and the `Linux stable mailing list
`_ archives for matching reports to join. If
you don't find any, install `the latest release from that series
`_. If it still shows the issue, report it to the stable
mailing list (stable@vger.kernel.org) and CC the regressions list
(regressions@lists.linux.dev); ideally also CC the maintainer and the mailing
list for the subsystem in question.h](hAre you facing a regression with vanilla kernels from the same stable or
longterm series? One still supported? Then search the }(hAre you facing a regression with vanilla kernels from the same stable or
longterm series? One still supported? Then search the hhhhhNhNubh reference)}(h'`LKML
`_h]hLKML}(hLKMLhhhhhNhNubah}(h]h ]h"]h$]h&]namehrefurihttps://lore.kernel.org/lkml/uh1hhhubhtarget)}(h
h]h}(h]lkmlah ]h"]lkmlah$]h&]refurij uh1j
referencedKhhubh and the }(h and the hhhhhNhNubh)}(h>`Linux stable mailing list
`_h]hLinux stable mailing list}(hLinux stable mailing listhj hhhNhNubah}(h]h ]h"]h$]h&]nameLinux stable mailing listj https://lore.kernel.org/stable/uh1hhhubj )}(h"
h]h}(h]linux-stable-mailing-listah ]h"]linux stable mailing listah$]h&]refurij- uh1j j KhhubhI archives for matching reports to join. If
you don’t find any, install }(hG archives for matching reports to join. If
you don't find any, install hhhhhNhNubh)}(h<`the latest release from that series
`_h]h#the latest release from that series}(h#the latest release from that serieshj@ hhhNhNubah}(h]h ]h"]h$]h&]name#the latest release from that seriesj https://kernel.org/uh1hhhubj )}(h
h]h}(h]#the-latest-release-from-that-seriesah ]h"]#the latest release from that seriesah$]h&]refurijQ uh1j j KhhubhE. If it still shows the issue, report it to the stable
mailing list (}(hE. If it still shows the issue, report it to the stable
mailing list (hhhhhNhNubh)}(hstable@vger.kernel.orgh]hstable@vger.kernel.org}(hhhjd hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:stable@vger.kernel.orguh1hhhubh) and CC the regressions list
(}(h) and CC the regressions list
(hhhhhNhNubh)}(hregressions@lists.linux.devh]hregressions@lists.linux.dev}(hhhjy hhhNhNubah}(h]h ]h"]h$]h&]refuri"mailto:regressions@lists.linux.devuh1hhhubhU); ideally also CC the maintainer and the mailing
list for the subsystem in question.}(hU); ideally also CC the maintainer and the mailing
list for the subsystem in question.hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hX In all other cases try your best guess which kernel part might be causing the
issue. Check the :ref:`MAINTAINERS ` file for how its developers
expect to be told about problems, which most of the time will be by email with a
mailing list in CC. Check the destination's archives for matching reports;
search the `LKML `_ and the web, too. If you
don't find any to join, install `the latest mainline kernel
`_. If the issue is present there, send a report.h](h_In all other cases try your best guess which kernel part might be causing the
issue. Check the }(h_In all other cases try your best guess which kernel part might be causing the
issue. Check the hj hhhNhNubh)}(h :ref:`MAINTAINERS `h]hinline)}(hj h]hMAINTAINERS}(hhhj hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]refdocadmin-guide/reporting-issues refdomainj reftyperefrefexplicitrefwarn reftargetmaintainersuh1hhhhKhj ubh file for how its developers
expect to be told about problems, which most of the time will be by email with a
mailing list in CC. Check the destination’s archives for matching reports;
search the }(h file for how its developers
expect to be told about problems, which most of the time will be by email with a
mailing list in CC. Check the destination's archives for matching reports;
search the hj hhhNhNubh)}(h'`LKML `_h]hLKML}(hLKMLhj hhhNhNubah}(h]h ]h"]h$]h&]namej j https://lore.kernel.org/lkml/uh1hhj ubj )}(h h]h}(h]id1ah ]h"]h$]lkmlah&]refurij uh1j j Khj ubh< and the web, too. If you
don’t find any to join, install }(h: and the web, too. If you
don't find any to join, install hj hhhNhNubh)}(h3`the latest mainline kernel
`_h]hthe latest mainline kernel}(hthe latest mainline kernelhj hhhNhNubah}(h]h ]h"]h$]h&]namethe latest mainline kernelj https://kernel.org/uh1hhj ubj )}(h
h]h}(h]the-latest-mainline-kernelah ]h"]the latest mainline kernelah$]h&]refurij uh1j j Khj ubh/. If the issue is present there, send a report.}(h/. If the issue is present there, send a report.hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXW The issue was fixed there, but you would like to see it resolved in a still
supported stable or longterm series as well? Then install its latest release.
If it shows the problem, search for the change that fixed it in mainline and
check if backporting is in the works or was discarded; if it's neither, ask
those who handled the change for it.h]hXY The issue was fixed there, but you would like to see it resolved in a still
supported stable or longterm series as well? Then install its latest release.
If it shows the problem, search for the change that fixed it in mainline and
check if backporting is in the works or was discarded; if it’s neither, ask
those who handled the change for it.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hX **General remarks**: When installing and testing a kernel as outlined above,
ensure it's vanilla (IOW: not patched and not using add-on modules). Also make
sure it's built and running in a healthy environment and not already tainted
before the issue occurs.h](hstrong)}(h**General remarks**h]hGeneral remarks}(hhhj( hhhNhNubah}(h]h ]h"]h$]h&]uh1j& hj" ubh: When installing and testing a kernel as outlined above,
ensure it’s vanilla (IOW: not patched and not using add-on modules). Also make
sure it’s built and running in a healthy environment and not already tainted
before the issue occurs.}(h: When installing and testing a kernel as outlined above,
ensure it's vanilla (IOW: not patched and not using add-on modules). Also make
sure it's built and running in a healthy environment and not already tainted
before the issue occurs.hj" hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK#hhhhubh)}(hX If you are facing multiple issues with the Linux kernel at once, report each
separately. While writing your report, include all information relevant to the
issue, like the kernel and the distro used. In case of a regression, CC the
regressions mailing list (regressions@lists.linux.dev) to your report. Also try
to pin-point the culprit with a bisection; if you succeed, include its
commit-id and CC everyone in the sign-off-by chain.h](hX If you are facing multiple issues with the Linux kernel at once, report each
separately. While writing your report, include all information relevant to the
issue, like the kernel and the distro used. In case of a regression, CC the
regressions mailing list (}(hX If you are facing multiple issues with the Linux kernel at once, report each
separately. While writing your report, include all information relevant to the
issue, like the kernel and the distro used. In case of a regression, CC the
regressions mailing list (hjA hhhNhNubh)}(hregressions@lists.linux.devh]hregressions@lists.linux.dev}(hhhjJ hhhNhNubah}(h]h ]h"]h$]h&]refuri"mailto:regressions@lists.linux.devuh1hhjA ubh) to your report. Also try
to pin-point the culprit with a bisection; if you succeed, include its
commit-id and CC everyone in the sign-off-by chain.}(h) to your report. Also try
to pin-point the culprit with a bisection; if you succeed, include its
commit-id and CC everyone in the sign-off-by chain.hjA hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK(hhhhubh)}(hOnce the report is out, answer any questions that come up and help where you
can. That includes keeping the ball rolling by occasionally retesting with newer
releases and sending a status update afterwards.h]hOnce the report is out, answer any questions that come up and help where you
can. That includes keeping the ball rolling by occasionally retesting with newer
releases and sending a status update afterwards.}(hjg hje hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hhhhubeh}(h]the-short-guide-aka-tl-drah ]h"]the short guide (aka tl;dr)ah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hAStep-by-step guide how to report issues to the kernel maintainersh]hAStep-by-step guide how to report issues to the kernel maintainers}(hj hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ hhhhhK4ubh)}(hX The above TL;DR outlines roughly how to report issues to the Linux kernel
developers. It might be all that's needed for people already familiar with
reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
everyone else there is this section. It is more detailed and uses a
step-by-step approach. It still tries to be brief for readability and leaves
out a lot of details; those are described below the step-by-step guide in a
reference section, which explains each of the steps in more detail.h]hX The above TL;DR outlines roughly how to report issues to the Linux kernel
developers. It might be all that’s needed for people already familiar with
reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
everyone else there is this section. It is more detailed and uses a
step-by-step approach. It still tries to be brief for readability and leaves
out a lot of details; those are described below the step-by-step guide in a
reference section, which explains each of the steps in more detail.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK6hj{ hhubh)}(hX\ Note: this section covers a few more aspects than the TL;DR and does things in
a slightly different order. That's in your interest, to make sure you notice
early if an issue that looks like a Linux kernel problem is actually caused by
something else. These steps thus help to ensure the time you invest in this
process won't feel wasted in the end:h]hX` Note: this section covers a few more aspects than the TL;DR and does things in
a slightly different order. That’s in your interest, to make sure you notice
early if an issue that looks like a Linux kernel problem is actually caused by
something else. These steps thus help to ensure the time you invest in this
process won’t feel wasted in the end:}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK>hj{ hhubhblock_quote)}(hhh]hbullet_list)}(hhh](h list_item)}(hX` Are you facing an issue with a Linux kernel a hardware or software vendor
provided? Then in almost all cases you are better off to stop reading this
document and reporting the issue to your vendor instead, unless you are
willing to install the latest Linux version yourself. Be aware the latter
will often be needed anyway to hunt down and fix issues.
h]h)}(hX_ Are you facing an issue with a Linux kernel a hardware or software vendor
provided? Then in almost all cases you are better off to stop reading this
document and reporting the issue to your vendor instead, unless you are
willing to install the latest Linux version yourself. Be aware the latter
will often be needed anyway to hunt down and fix issues.h]hX_ Are you facing an issue with a Linux kernel a hardware or software vendor
provided? Then in almost all cases you are better off to stop reading this
document and reporting the issue to your vendor instead, unless you are
willing to install the latest Linux version yourself. Be aware the latter
will often be needed anyway to hunt down and fix issues.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the `Linux Kernel Mailing
List (LKML) `_. If you find matching reports,
join the discussion instead of sending a new one.
h]h)}(hX Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the `Linux Kernel Mailing
List (LKML) `_. If you find matching reports,
join the discussion instead of sending a new one.h](hPerform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the }(hPerform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the hj hhhNhNubh)}(hC`Linux Kernel Mailing
List (LKML) `_h]h Linux Kernel Mailing
List (LKML)}(h Linux Kernel Mailing
List (LKML)hj hhhNhNubah}(h]h ]h"]h$]h&]name Linux Kernel Mailing List (LKML)j https://lore.kernel.org/lkml/uh1hhj ubj )}(h h]h}(h]linux-kernel-mailing-list-lkmlah ]h"] linux kernel mailing list (lkml)ah$]h&]refurij uh1j j Khj ubhQ. If you find matching reports,
join the discussion instead of sending a new one.}(hQ. If you find matching reports,
join the discussion instead of sending a new one.hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKJhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hSee if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.
h]h)}(hSee if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.h]hSee if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are ‘issues of high priority’ that
need special handling in some steps that are about to follow.}(hj hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hRMake sure it's not the kernel's surroundings that are causing the issue
you face.
h]h)}(hQMake sure it's not the kernel's surroundings that are causing the issue
you face.h]hUMake sure it’s not the kernel’s surroundings that are causing the issue
you face.}(hj' hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShj! ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hGCreate a fresh backup and put system repair and restore tools at hand.
h]h)}(hFCreate a fresh backup and put system repair and restore tools at hand.h]hFCreate a fresh backup and put system repair and restore tools at hand.}(hj? hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKVhj9 ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hEnsure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.
h]h)}(hEnsure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.h]hEnsure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.}(hjW hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjQ ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hCheck if your kernel was 'tainted' when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.
h]h)}(hCheck if your kernel was 'tainted' when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.h]hCheck if your kernel was ‘tainted’ when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.}(hjo hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hji ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX? Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That's needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.
h]h)}(hX> Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That's needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.h]hX@ Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That’s needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hIf you are facing a regression within a stable or longterm version line
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
'Dealing with regressions within a stable and longterm kernel line'.
h]h)}(hIf you are facing a regression within a stable or longterm version line
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
'Dealing with regressions within a stable and longterm kernel line'.h]hIf you are facing a regression within a stable or longterm version line
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
‘Dealing with regressions within a stable and longterm kernel line’.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKehj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won't be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.
h]h)}(hX Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won't be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.h]hX Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won’t be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hSearch the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. If you find anything,
join the discussion instead of sending a new report.
h]h)}(hSearch the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. If you find anything,
join the discussion instead of sending a new report.h]hSearch the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. If you find anything,
join the discussion instead of sending a new report.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]bullet*uh1j hhhKDhj ubah}(h]h ]h"]h$]h&]uh1j hj{ hhhNhNubh)}(h8After these preparations you'll now enter the main part:h]h:After these preparations you’ll now enter the main part:}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhj{ hhubj )}(hhh]j )}(hhh](j )}(hX3 Unless you are already running the latest 'mainline' Linux kernel, better
go and install it for the reporting process. Testing and reporting with
the latest 'stable' Linux can be an acceptable alternative in some
situations; during the merge window that actually might be even the best
approach, but in that development phase it can be an even better idea to
suspend your efforts for a few days anyway. Whatever version you choose,
ideally use a 'vanilla' build. Ignoring these advices will dramatically
increase the risk your report will be rejected or ignored.
h]h)}(hX2 Unless you are already running the latest 'mainline' Linux kernel, better
go and install it for the reporting process. Testing and reporting with
the latest 'stable' Linux can be an acceptable alternative in some
situations; during the merge window that actually might be even the best
approach, but in that development phase it can be an even better idea to
suspend your efforts for a few days anyway. Whatever version you choose,
ideally use a 'vanilla' build. Ignoring these advices will dramatically
increase the risk your report will be rejected or ignored.h]hX> Unless you are already running the latest ‘mainline’ Linux kernel, better
go and install it for the reporting process. Testing and reporting with
the latest ‘stable’ Linux can be an acceptable alternative in some
situations; during the merge window that actually might be even the best
approach, but in that development phase it can be an even better idea to
suspend your efforts for a few days anyway. Whatever version you choose,
ideally use a ‘vanilla’ build. Ignoring these advices will dramatically
increase the risk your report will be rejected or ignored.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKthj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hKEnsure the kernel you just installed does not 'taint' itself when
running.
h]h)}(hJEnsure the kernel you just installed does not 'taint' itself when
running.h]hNEnsure the kernel you just installed does not ‘taint’ itself when
running.}(hj! hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hReproduce the issue with the kernel you just installed. If it doesn't show
up there, scroll down to the instructions for issues only happening with
stable and longterm kernels.
h]h)}(hReproduce the issue with the kernel you just installed. If it doesn't show
up there, scroll down to the instructions for issues only happening with
stable and longterm kernels.h]hReproduce the issue with the kernel you just installed. If it doesn’t show
up there, scroll down to the instructions for issues only happening with
stable and longterm kernels.}(hj9 hj7 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3 ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hXl Optimize your notes: try to find and write the most straightforward way to
reproduce your issue. Make sure the end result has all the important
details, and at the same time is easy to read and understand for others
that hear about it for the first time. And if you learned something in this
process, consider searching again for existing reports about the issue.
h]h)}(hXk Optimize your notes: try to find and write the most straightforward way to
reproduce your issue. Make sure the end result has all the important
details, and at the same time is easy to read and understand for others
that hear about it for the first time. And if you learned something in this
process, consider searching again for existing reports about the issue.h]hXk Optimize your notes: try to find and write the most straightforward way to
reproduce your issue. Make sure the end result has all the important
details, and at the same time is easy to read and understand for others
that hear about it for the first time. And if you learned something in this
process, consider searching again for existing reports about the issue.}(hjQ hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjK ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hIf your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
decoding the kernel log to find the line of code that triggered the error.
h]h)}(hIf your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
decoding the kernel log to find the line of code that triggered the error.h]hIf your failure involves a ‘panic’, ‘Oops’, ‘warning’, or ‘BUG’, consider
decoding the kernel log to find the line of code that triggered the error.}(hji hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjc ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hgIf your problem is a regression, try to narrow down when the issue was
introduced as much as possible.
h]h)}(hfIf your problem is a regression, try to narrow down when the issue was
introduced as much as possible.h]hfIf your problem is a regression, try to narrow down when the issue was
introduced as much as possible.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj{ ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel's build configuration
(.config) and the output from ``dmesg`` available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from ``lspci``. Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you're
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those 'issues of high priority': they need
special care which is explained in 'Special handling for high priority
issues' below.
h]h)}(hX Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel's build configuration
(.config) and the output from ``dmesg`` available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from ``lspci``. Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you're
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those 'issues of high priority': they need
special care which is explained in 'Special handling for high priority
issues' below.h](hX? Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel’s build configuration
(.config) and the output from }(hX= Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
for reproducing, the Linux Distribution used, and your notes on how to
reproduce the issue. Ideally, make the kernel's build configuration
(.config) and the output from hj hhhNhNubhliteral)}(h ``dmesg``h]hdmesg}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubh available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from }(h available somewhere on the net and
link to it. Include or upload all other information that might be relevant,
like the output/screenshot of an Oops or the output from hj hhhNhNubj )}(h ``lspci``h]hlspci}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubhX% . Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you’re
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those ‘issues of high priority’: they need
special care which is explained in ‘Special handling for high priority
issues’ below.}(hX . Once
you wrote this main part, insert a normal length paragraph on top of it
outlining the issue and the impact quickly. On top of this add one sentence
that briefly describes the problem and gets people to read on. Now give the
thing a descriptive title or subject that yet again is shorter. Then you're
ready to send or file the report like the MAINTAINERS file told you, unless
you are dealing with one of those 'issues of high priority': they need
special care which is explained in 'Special handling for high priority
issues' below.hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX Wait for reactions and keep the thing rolling until you can accept the
outcome in one way or the other. Thus react publicly and in a timely manner
to any inquiries. Test proposed fixes. Do proactive testing: retest with at
least every first release candidate (RC) of a new mainline version and
report your results. Send friendly reminders if things stall. And try to
help yourself, if you don't get any help or if it's unsatisfying.
h]h)}(hX Wait for reactions and keep the thing rolling until you can accept the
outcome in one way or the other. Thus react publicly and in a timely manner
to any inquiries. Test proposed fixes. Do proactive testing: retest with at
least every first release candidate (RC) of a new mainline version and
report your results. Send friendly reminders if things stall. And try to
help yourself, if you don't get any help or if it's unsatisfying.h]hX Wait for reactions and keep the thing rolling until you can accept the
outcome in one way or the other. Thus react publicly and in a timely manner
to any inquiries. Test proposed fixes. Do proactive testing: retest with at
least every first release candidate (RC) of a new mainline version and
report your results. Send friendly reminders if things stall. And try to
help yourself, if you don’t get any help or if it’s unsatisfying.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKthj ubah}(h]h ]h"]h$]h&]uh1j hj{ hhhNhNubh)}(hhh](h)}(h>Reporting regressions within a stable and longterm kernel lineh]h>Reporting regressions within a stable and longterm kernel line}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hX This subsection is for you, if you followed above process and got sent here at
the point about regression within a stable or longterm kernel version line. You
face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a
switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such
regressions as quickly as possible, hence there is a streamlined process to
report them:h]hX This subsection is for you, if you followed above process and got sent here at
the point about regression within a stable or longterm kernel version line. You
face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a
switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such
regressions as quickly as possible, hence there is a streamlined process to
report them:}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hhh]j )}(hhh](j )}(hCheck if the kernel developers still maintain the Linux kernel version
line you care about: go to the `front page of kernel.org
`_ and make sure it mentions
the latest release of the particular version line without an '[EOL]' tag.
h]h)}(hCheck if the kernel developers still maintain the Linux kernel version
line you care about: go to the `front page of kernel.org
`_ and make sure it mentions
the latest release of the particular version line without an '[EOL]' tag.h](hgCheck if the kernel developers still maintain the Linux kernel version
line you care about: go to the }(hgCheck if the kernel developers still maintain the Linux kernel version
line you care about: go to the hj! hhhNhNubh)}(h1`front page of kernel.org
`_h]hfront page of kernel.org}(hfront page of kernel.orghj* hhhNhNubah}(h]h ]h"]h$]h&]namefront page of kernel.orgj https://kernel.org/uh1hhj! ubj )}(h
h]h}(h]front-page-of-kernel-orgah ]h"]front page of kernel.orgah$]h&]refurij; uh1j j Khj! ubhh and make sure it mentions
the latest release of the particular version line without an ‘[EOL]’ tag.}(hd and make sure it mentions
the latest release of the particular version line without an '[EOL]' tag.hj! hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hoCheck the archives of the `Linux stable mailing list
`_ for existing reports.
h]h)}(hnCheck the archives of the `Linux stable mailing list
`_ for existing reports.h](hCheck the archives of the }(hCheck the archives of the hj^ hhhNhNubh)}(h>`Linux stable mailing list
`_h]hLinux stable mailing list}(hLinux stable mailing listhjg hhhNhNubah}(h]h ]h"]h$]h&]nameLinux stable mailing listj https://lore.kernel.org/stable/uh1hhj^ ubj )}(h"
h]h}(h]id2ah ]h"]h$]linux stable mailing listah&]refurijx uh1j j Khj^ ubh for existing reports.}(h for existing reports.hj^ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjZ ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hXH Install the latest release from the particular version line as a vanilla
kernel. Ensure this kernel is not tainted and still shows the problem, as
the issue might have already been fixed there. If you first noticed the
problem with a vendor kernel, check a vanilla build of the last version
known to work performs fine as well.
h]h)}(hXG Install the latest release from the particular version line as a vanilla
kernel. Ensure this kernel is not tainted and still shows the problem, as
the issue might have already been fixed there. If you first noticed the
problem with a vendor kernel, check a vanilla build of the last version
known to work performs fine as well.h]hXG Install the latest release from the particular version line as a vanilla
kernel. Ensure this kernel is not tainted and still shows the problem, as
the issue might have already been fixed there. If you first noticed the
problem with a vendor kernel, check a vanilla build of the last version
known to work performs fine as well.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX Send a short problem report to the Linux stable mailing list
(stable@vger.kernel.org) and CC the Linux regressions mailing list
(regressions@lists.linux.dev); if you suspect the cause in a particular
subsystem, CC its maintainer and its mailing list. Roughly describe the
issue and ideally explain how to reproduce it. Mention the first version
that shows the problem and the last version that's working fine. Then
wait for further instructions.
h]h)}(hX Send a short problem report to the Linux stable mailing list
(stable@vger.kernel.org) and CC the Linux regressions mailing list
(regressions@lists.linux.dev); if you suspect the cause in a particular
subsystem, CC its maintainer and its mailing list. Roughly describe the
issue and ideally explain how to reproduce it. Mention the first version
that shows the problem and the last version that's working fine. Then
wait for further instructions.h](h>Send a short problem report to the Linux stable mailing list
(}(h>Send a short problem report to the Linux stable mailing list
(hj hhhNhNubh)}(hstable@vger.kernel.orgh]hstable@vger.kernel.org}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:stable@vger.kernel.orguh1hhj ubh-) and CC the Linux regressions mailing list
(}(h-) and CC the Linux regressions mailing list
(hj hhhNhNubh)}(hregressions@lists.linux.devh]hregressions@lists.linux.dev}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]refuri"mailto:regressions@lists.linux.devuh1hhj ubhX# ); if you suspect the cause in a particular
subsystem, CC its maintainer and its mailing list. Roughly describe the
issue and ideally explain how to reproduce it. Mention the first version
that shows the problem and the last version that’s working fine. Then
wait for further instructions.}(hX! ); if you suspect the cause in a particular
subsystem, CC its maintainer and its mailing list. Roughly describe the
issue and ideally explain how to reproduce it. Mention the first version
that shows the problem and the last version that's working fine. Then
wait for further instructions.hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhNhNubh)}(hHThe reference section below explains each of these steps in more detail.h]hHThe reference section below explains each of these steps in more detail.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]>reporting-regressions-within-a-stable-and-longterm-kernel-lineah ]h"]>reporting regressions within a stable and longterm kernel lineah$]h&]uh1hhj{ hhhhhKubh)}(hhh](h)}(h=Reporting issues only occurring in older kernel version linesh]h=Reporting issues only occurring in older kernel version lines}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hX4 This subsection is for you, if you tried the latest mainline kernel as outlined
above, but failed to reproduce your issue there; at the same time you want to
see the issue fixed in a still supported stable or longterm series or vendor
kernels regularly rebased on those. If that the case, follow these steps:h]hX4 This subsection is for you, if you tried the latest mainline kernel as outlined
above, but failed to reproduce your issue there; at the same time you want to
see the issue fixed in a still supported stable or longterm series or vendor
kernels regularly rebased on those. If that the case, follow these steps:}(hj' hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hhh]j )}(hhh](j )}(hPrepare yourself for the possibility that going through the next few steps
might not get the issue solved in older releases: the fix might be too big
or risky to get backported there.
h]h)}(hPrepare yourself for the possibility that going through the next few steps
might not get the issue solved in older releases: the fix might be too big
or risky to get backported there.h]hPrepare yourself for the possibility that going through the next few steps
might not get the issue solved in older releases: the fix might be too big
or risky to get backported there.}(hj? hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj9 ubah}(h]h ]h"]h$]h&]uh1j hj6 ubj )}(hxPerform the first three steps in the section "Dealing with regressions
within a stable and longterm kernel line" above.
h]h)}(hwPerform the first three steps in the section "Dealing with regressions
within a stable and longterm kernel line" above.h]h{Perform the first three steps in the section “Dealing with regressions
within a stable and longterm kernel line” above.}(hjW hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQ ubah}(h]h ]h"]h$]h&]uh1j hj6 ubj )}(hX Search the Linux kernel version control system for the change that fixed
the issue in mainline, as its commit message might tell you if the fix is
scheduled for backporting already. If you don't find anything that way,
search the appropriate mailing lists for posts that discuss such an issue
or peer-review possible fixes; then check the discussions if the fix was
deemed unsuitable for backporting. If backporting was not considered at
all, join the newest discussion, asking if it's in the cards.
h]h)}(hX Search the Linux kernel version control system for the change that fixed
the issue in mainline, as its commit message might tell you if the fix is
scheduled for backporting already. If you don't find anything that way,
search the appropriate mailing lists for posts that discuss such an issue
or peer-review possible fixes; then check the discussions if the fix was
deemed unsuitable for backporting. If backporting was not considered at
all, join the newest discussion, asking if it's in the cards.h]hX Search the Linux kernel version control system for the change that fixed
the issue in mainline, as its commit message might tell you if the fix is
scheduled for backporting already. If you don’t find anything that way,
search the appropriate mailing lists for posts that discuss such an issue
or peer-review possible fixes; then check the discussions if the fix was
deemed unsuitable for backporting. If backporting was not considered at
all, join the newest discussion, asking if it’s in the cards.}(hjo hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhji ubah}(h]h ]h"]h$]h&]uh1j hj6 ubj )}(hOne of the former steps should lead to a solution. If that doesn't work
out, ask the maintainers for the subsystem that seems to be causing the
issue for advice; CC the mailing list for the particular subsystem as well
as the stable mailing list.
h]h)}(hOne of the former steps should lead to a solution. If that doesn't work
out, ask the maintainers for the subsystem that seems to be causing the
issue for advice; CC the mailing list for the particular subsystem as well
as the stable mailing list.h]hOne of the former steps should lead to a solution. If that doesn’t work
out, ask the maintainers for the subsystem that seems to be causing the
issue for advice; CC the mailing list for the particular subsystem as well
as the stable mailing list.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj6 ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKhj3 ubah}(h]h ]h"]h$]h&]uh1j hj hhhNhNubh)}(hHThe reference section below explains each of these steps in more detail.h]hHThe reference section below explains each of these steps in more detail.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]=reporting-issues-only-occurring-in-older-kernel-version-linesah ]h"]=reporting issues only occurring in older kernel version linesah$]h&]uh1hhj{ hhhhhKubeh}(h]Astep-by-step-guide-how-to-report-issues-to-the-kernel-maintainersah ]h"]Astep-by-step guide how to report issues to the kernel maintainersah$]h&]uh1hhhhhhhhK4ubh)}(hhh](h)}(h=Reference section: Reporting issues to the kernel maintainersh]h=Reference section: Reporting issues to the kernel maintainers}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hX The detailed guides above outline all the major steps in brief fashion, which
should be enough for most people. But sometimes there are situations where even
experienced users might wonder how to actually do one of those steps. That's
what this section is for, as it will provide a lot more details on each of the
above steps. Consider this as reference documentation: it's possible to read it
from top to bottom. But it's mainly meant to skim over and a place to look up
details how to actually perform those steps.h]hX
The detailed guides above outline all the major steps in brief fashion, which
should be enough for most people. But sometimes there are situations where even
experienced users might wonder how to actually do one of those steps. That’s
what this section is for, as it will provide a lot more details on each of the
above steps. Consider this as reference documentation: it’s possible to read it
from top to bottom. But it’s mainly meant to skim over and a place to look up
details how to actually perform those steps.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(h>A few words of general advice before digging into the details:h]h>A few words of general advice before digging into the details:}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj )}(hhh]j )}(hhh](j )}(hXT The Linux kernel developers are well aware this process is complicated and
demands more than other FLOSS projects. We'd love to make it simpler. But
that would require work in various places as well as some infrastructure,
which would need constant maintenance; nobody has stepped up to do that
work, so that's just how things are for now.
h]h)}(hXS The Linux kernel developers are well aware this process is complicated and
demands more than other FLOSS projects. We'd love to make it simpler. But
that would require work in various places as well as some infrastructure,
which would need constant maintenance; nobody has stepped up to do that
work, so that's just how things are for now.h]hXW The Linux kernel developers are well aware this process is complicated and
demands more than other FLOSS projects. We’d love to make it simpler. But
that would require work in various places as well as some infrastructure,
which would need constant maintenance; nobody has stepped up to do that
work, so that’s just how things are for now.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX A warranty or support contract with some vendor doesn't entitle you to
request fixes from developers in the upstream Linux kernel community: such
contracts are completely outside the scope of the Linux kernel, its
development community, and this document. That's why you can't demand
anything such a contract guarantees in this context, not even if the
developer handling the issue works for the vendor in question. If you want
to claim your rights, use the vendor's support channel instead. When doing
so, you might want to mention you'd like to see the issue fixed in the
upstream Linux kernel; motivate them by saying it's the only way to ensure
the fix in the end will get incorporated in all Linux distributions.
h]h)}(hX A warranty or support contract with some vendor doesn't entitle you to
request fixes from developers in the upstream Linux kernel community: such
contracts are completely outside the scope of the Linux kernel, its
development community, and this document. That's why you can't demand
anything such a contract guarantees in this context, not even if the
developer handling the issue works for the vendor in question. If you want
to claim your rights, use the vendor's support channel instead. When doing
so, you might want to mention you'd like to see the issue fixed in the
upstream Linux kernel; motivate them by saying it's the only way to ensure
the fix in the end will get incorporated in all Linux distributions.h]hX A warranty or support contract with some vendor doesn’t entitle you to
request fixes from developers in the upstream Linux kernel community: such
contracts are completely outside the scope of the Linux kernel, its
development community, and this document. That’s why you can’t demand
anything such a contract guarantees in this context, not even if the
developer handling the issue works for the vendor in question. If you want
to claim your rights, use the vendor’s support channel instead. When doing
so, you might want to mention you’d like to see the issue fixed in the
upstream Linux kernel; motivate them by saying it’s the only way to ensure
the fix in the end will get incorporated in all Linux distributions.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hXU If you never reported an issue to a FLOSS project before you should consider
reading `How to Report Bugs Effectively
`_, `How To Ask
Questions The Smart Way
`_, and `How to ask good
questions `_.
h]h)}(hXT If you never reported an issue to a FLOSS project before you should consider
reading `How to Report Bugs Effectively
`_, `How To Ask
Questions The Smart Way
`_, and `How to ask good
questions `_.h](hUIf you never reported an issue to a FLOSS project before you should consider
reading }(hUIf you never reported an issue to a FLOSS project before you should consider
reading hj* hhhNhNubh)}(hZ`How to Report Bugs Effectively
`_h]hHow to Report Bugs Effectively}(hHow to Report Bugs Effectivelyhj3 hhhNhNubah}(h]h ]h"]h$]h&]nameHow to Report Bugs Effectivelyj 6https://www.chiark.greenend.org.uk/~sgtatham/bugs.htmluh1hhj* ubj )}(h9
h]h}(h]how-to-report-bugs-effectivelyah ]h"]how to report bugs effectivelyah$]h&]refurijD uh1j j Khj* ubh, }(h, hj* hhhNhNubh)}(hY`How To Ask
Questions The Smart Way
`_h]h"How To Ask
Questions The Smart Way}(h"How To Ask
Questions The Smart WayhjW hhhNhNubah}(h]h ]h"]h$]h&]name"How To Ask Questions The Smart Wayj 1http://www.catb.org/esr/faqs/smart-questions.htmluh1hhj* ubj )}(h4
h]h}(h]"how-to-ask-questions-the-smart-wayah ]h"]"how to ask questions the smart wayah$]h&]refurijh uh1j j Khj* ubh, and }(h, and hj* hhhNhNubh)}(hC`How to ask good
questions `_h]hHow to ask good
questions}(hHow to ask good
questionshj{ hhhNhNubah}(h]h ]h"]h$]h&]nameHow to ask good questionsj $https://jvns.ca/blog/good-questions/uh1hhj* ubj )}(h' h]h}(h]how-to-ask-good-questionsah ]h"]how to ask good questionsah$]h&]refurij uh1j j Khj* ubh.}(h.hj* hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj& ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhKhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhNhNubh)}(hpWith that off the table, find below the details on how to properly report
issues to the Linux kernel developers.h]hpWith that off the table, find below the details on how to properly report
issues to the Linux kernel developers.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hhh](h)}(h0Make sure you're using the upstream Linux kernelh]h2Make sure you’re using the upstream Linux kernel}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubj )}(hhh]h)}(hXa *Are you facing an issue with a Linux kernel a hardware or software vendor
provided? Then in almost all cases you are better off to stop reading this
document and reporting the issue to your vendor instead, unless you are
willing to install the latest Linux version yourself. Be aware the latter
will often be needed anyway to hunt down and fix issues.*h]hemphasis)}(hj h]hX_ Are you facing an issue with a Linux kernel a hardware or software vendor
provided? Then in almost all cases you are better off to stop reading this
document and reporting the issue to your vendor instead, unless you are
willing to install the latest Linux version yourself. Be aware the latter
will often be needed anyway to hunt down and fix issues.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubh)}(hX Like most programmers, Linux kernel developers don't like to spend time dealing
with reports for issues that don't even happen with their current code. It's
just a waste everybody's time, especially yours. Unfortunately such situations
easily happen when it comes to the kernel and often leads to frustration on both
sides. That's because almost all Linux-based kernels pre-installed on devices
(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux
distributors are quite distant from the official Linux kernel as distributed by
kernel.org: these kernels from these vendors are often ancient from the point of
Linux development or heavily modified, often both.h]hX Like most programmers, Linux kernel developers don’t like to spend time dealing
with reports for issues that don’t even happen with their current code. It’s
just a waste everybody’s time, especially yours. Unfortunately such situations
easily happen when it comes to the kernel and often leads to frustration on both
sides. That’s because almost all Linux-based kernels pre-installed on devices
(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux
distributors are quite distant from the official Linux kernel as distributed by
kernel.org: these kernels from these vendors are often ancient from the point of
Linux development or heavily modified, often both.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX Most of these vendor kernels are quite unsuitable for reporting issues to the
Linux kernel developers: an issue you face with one of them might have been
fixed by the Linux kernel developers months or years ago already; additionally,
the modifications and enhancements by the vendor might be causing the issue you
face, even if they look small or totally unrelated. That's why you should report
issues with these kernels to the vendor. Its developers should look into the
report and, in case it turns out to be an upstream issue, fix it directly
upstream or forward the report there. In practice that often does not work out
or might not what you want. You thus might want to consider circumventing the
vendor by installing the very latest Linux kernel core yourself. If that's an
option for you move ahead in this process, as a later step in this guide will
explain how to do that once it rules out other potential causes for your issue.h]hX Most of these vendor kernels are quite unsuitable for reporting issues to the
Linux kernel developers: an issue you face with one of them might have been
fixed by the Linux kernel developers months or years ago already; additionally,
the modifications and enhancements by the vendor might be causing the issue you
face, even if they look small or totally unrelated. That’s why you should report
issues with these kernels to the vendor. Its developers should look into the
report and, in case it turns out to be an upstream issue, fix it directly
upstream or forward the report there. In practice that often does not work out
or might not what you want. You thus might want to consider circumventing the
vendor by installing the very latest Linux kernel core yourself. If that’s an
option for you move ahead in this process, as a later step in this guide will
explain how to do that once it rules out other potential causes for your issue.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hj hhubh)}(hX Note, the previous paragraph is starting with the word 'most', as sometimes
developers in fact are willing to handle reports about issues occurring with
vendor kernels. If they do in the end highly depends on the developers and the
issue in question. Your chances are quite good if the distributor applied only
small modifications to a kernel based on a recent Linux version; that for
example often holds true for the mainline kernels shipped by Debian GNU/Linux
Sid or Fedora Rawhide. Some developers will also accept reports about issues
with kernels from distributions shipping the latest stable kernel, as long as
its only slightly modified; that for example is often the case for Arch Linux,
regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better
want to use a mainline Linux and avoid using a stable kernel for this
process, as outlined in the section 'Install a fresh kernel for testing' in more
detail.h]hX Note, the previous paragraph is starting with the word ‘most’, as sometimes
developers in fact are willing to handle reports about issues occurring with
vendor kernels. If they do in the end highly depends on the developers and the
issue in question. Your chances are quite good if the distributor applied only
small modifications to a kernel based on a recent Linux version; that for
example often holds true for the mainline kernels shipped by Debian GNU/Linux
Sid or Fedora Rawhide. Some developers will also accept reports about issues
with kernels from distributions shipping the latest stable kernel, as long as
its only slightly modified; that for example is often the case for Arch Linux,
regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better
want to use a mainline Linux and avoid using a stable kernel for this
process, as outlined in the section ‘Install a fresh kernel for testing’ in more
detail.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hj hhubh)}(hXu Obviously you are free to ignore all this advice and report problems with an old
or heavily modified vendor kernel to the upstream Linux developers. But note,
those often get rejected or ignored, so consider yourself warned. But it's still
better than not reporting the issue at all: sometimes such reports directly or
indirectly will help to get the issue fixed over time.h]hXw Obviously you are free to ignore all this advice and report problems with an old
or heavily modified vendor kernel to the upstream Linux developers. But note,
those often get rejected or ignored, so consider yourself warned. But it’s still
better than not reporting the issue at all: sometimes such reports directly or
indirectly will help to get the issue fixed over time.}(hj$ hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj hhubeh}(h]0make-sure-you-re-using-the-upstream-linux-kernelah ]h"]0make sure you're using the upstream linux kernelah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(h&Search for existing reports, first runh]h&Search for existing reports, first run}(hj= hj; hhhNhNubah }(h]h ]h"]h$]h&]uh1hhj8 hhhhhMIubj )}(hhh]h)}(h*Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the Linux Kernel Mailing
List (LKML). If you find matching reports, join the discussion instead of
sending a new one.*h]j )}(hjN h]hPerform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the Linux Kernel Mailing
List (LKML). If you find matching reports, join the discussion instead of
sending a new one.}(hhhjP hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjL ubah}(h]h ]h"]h$]h&]uh1hhhhMKhjI ubah}(h]h ]h"]h$]h&]uh1j hj8 hhhhhNubh)}(hX Reporting an issue that someone else already brought forward is often a waste of
time for everyone involved, especially you as the reporter. So it's in your own
interest to thoroughly check if somebody reported the issue already. At this
step of the process it's okay to just perform a rough search: a later step will
tell you to perform a more detailed search once you know where your issue needs
to be reported to. Nevertheless, do not hurry with this step of the reporting
process, it can save you time and trouble.h]hX
Reporting an issue that someone else already brought forward is often a waste of
time for everyone involved, especially you as the reporter. So it’s in your own
interest to thoroughly check if somebody reported the issue already. At this
step of the process it’s okay to just perform a rough search: a later step will
tell you to perform a more detailed search once you know where your issue needs
to be reported to. Nevertheless, do not hurry with this step of the reporting
process, it can save you time and trouble.}(hjk hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhj8 hhubh)}(hSimply search the internet with your favorite search engine first. Afterwards,
search the `Linux Kernel Mailing List (LKML) archives
`_.h](hZSimply search the internet with your favorite search engine first. Afterwards,
search the }(hZSimply search the internet with your favorite search engine first. Afterwards,
search the hjw hhhNhNubh)}(hL`Linux Kernel Mailing List (LKML) archives
`_h]h)Linux Kernel Mailing List (LKML) archives}(h)Linux Kernel Mailing List (LKML) archiveshj hhhNhNubah}(h]h ]h"]h$]h&]name)Linux Kernel Mailing List (LKML) archivesj https://lore.kernel.org/lkml/uh1hhjw ubj )}(h
h]h}(h]'linux-kernel-mailing-list-lkml-archivesah ]h"])linux kernel mailing list (lkml) archivesah$]h&]refurij uh1j j Khjw ubh.}(hj hjw hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMXhj8 hhubh)}(hXM If you get flooded with results consider telling your search engine to limit
search timeframe to the past month or year. And wherever you search, make sure
to use good search terms; vary them a few times, too. While doing so try to
look at the issue from the perspective of someone else: that will help you to
come up with other words to use as search terms. Also make sure not to use too
many search terms at once. Remember to search with and without information like
the name of the kernel driver or the name of the affected hardware component.
But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC')
often is not much helpful, as it is too specific. Instead try search terms like
the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip
('Navi' or 'Navi10') with and without its manufacturer ('AMD').h]hX] If you get flooded with results consider telling your search engine to limit
search timeframe to the past month or year. And wherever you search, make sure
to use good search terms; vary them a few times, too. While doing so try to
look at the issue from the perspective of someone else: that will help you to
come up with other words to use as search terms. Also make sure not to use too
many search terms at once. Remember to search with and without information like
the name of the kernel driver or the name of the affected hardware component.
But its exact brand name (say ‘ASUS Red Devil Radeon RX 5700 XT Gaming OC’)
often is not much helpful, as it is too specific. Instead try search terms like
the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip
(‘Navi’ or ‘Navi10’) with and without its manufacturer (‘AMD’).}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM\hj8 hhubh)}(hX In case you find an existing report about your issue, join the discussion, as
you might be able to provide valuable additional information. That can be
important even when a fix is prepared or in its final stages already, as
developers might look for people that can provide additional information or
test a proposed fix. Jump to the section 'Duties after the report went out' for
details on how to get properly involved.h]hX In case you find an existing report about your issue, join the discussion, as
you might be able to provide valuable additional information. That can be
important even when a fix is prepared or in its final stages already, as
developers might look for people that can provide additional information or
test a proposed fix. Jump to the section ‘Duties after the report went out’ for
details on how to get properly involved.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhj8 hhubh)}(hX/ Note, searching `bugzilla.kernel.org `_ might also
be a good idea, as that might provide valuable insights or turn up matching
reports. If you find the latter, just keep in mind: most subsystems expect
reports in different places, as described below in the section "Check where you
need to report your issue". The developers that should take care of the issue
thus might not even be aware of the bugzilla ticket. Hence, check the ticket if
the issue already got reported as outlined in this document and if not consider
doing so.h](hNote, searching }(hNote, searching hj hhhNhNubh)}(h5`bugzilla.kernel.org `_h]hbugzilla.kernel.org}(hbugzilla.kernel.orghj hhhNhNubah}(h]h ]h"]h$]h&]namej j https://bugzilla.kernel.org/uh1hhj ubj )}(h h]h}(h]bugzilla-kernel-orgah ]h"]bugzilla.kernel.orgah$]h&]refurij uh1j j Khj ubhX might also
be a good idea, as that might provide valuable insights or turn up matching
reports. If you find the latter, just keep in mind: most subsystems expect
reports in different places, as described below in the section “Check where you
need to report your issue”. The developers that should take care of the issue
thus might not even be aware of the bugzilla ticket. Hence, check the ticket if
the issue already got reported as outlined in this document and if not consider
doing so.}(hX might also
be a good idea, as that might provide valuable insights or turn up matching
reports. If you find the latter, just keep in mind: most subsystems expect
reports in different places, as described below in the section "Check where you
need to report your issue". The developers that should take care of the issue
thus might not even be aware of the bugzilla ticket. Hence, check the ticket if
the issue already got reported as outlined in this document and if not consider
doing so.hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMohj8 hhubeh}(h]%search-for-existing-reports-first-runah ]h"]&search for existing reports, first runah$]h&]uh1hhj hhhhhMIubh)}(hhh](h)}(hIssue of high priority?h]hIssue of high priority?}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMzubj )}(hhh]h)}(h*See if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.*h]j )}(hj h]hSee if the issue you are dealing with qualifies as regression, security
issue, or a really severe problem: those are ‘issues of high priority’ that
need special handling in some steps that are about to follow.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhM|hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubh)}(hX* Linus Torvalds and the leading Linux kernel developers want to see some issues
fixed as soon as possible, hence there are 'issues of high priority' that get
handled slightly differently in the reporting process. Three type of cases
qualify: regressions, security issues, and really severe problems.h]hX. Linus Torvalds and the leading Linux kernel developers want to see some issues
fixed as soon as possible, hence there are ‘issues of high priority’ that get
handled slightly differently in the reporting process. Three type of cases
qualify: regressions, security issues, and really severe problems.}(hj2 hj0 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX You deal with a regression if some application or practical use case running
fine with one Linux kernel works worse or not at all with a newer version
compiled using a similar configuration. The document
Documentation/admin-guide/reporting-regressions.rst explains this in more
detail. It also provides a good deal of other information about regressions you
might want to be aware of; it for example explains how to add your issue to the
list of tracked regressions, to ensure it won't fall through the cracks.h]hX You deal with a regression if some application or practical use case running
fine with one Linux kernel works worse or not at all with a newer version
compiled using a similar configuration. The document
Documentation/admin-guide/reporting-regressions.rst explains this in more
detail. It also provides a good deal of other information about regressions you
might want to be aware of; it for example explains how to add your issue to the
list of tracked regressions, to ensure it won’t fall through the cracks.}(hj@ hj> hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hWhat qualifies as security issue is left to your judgment. Consider reading
Documentation/process/security-bugs.rst before proceeding, as it
provides additional details how to best handle security issues.h]hWhat qualifies as security issue is left to your judgment. Consider reading
Documentation/process/security-bugs.rst before proceeding, as it
provides additional details how to best handle security issues.}(hjN hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX An issue is a 'really severe problem' when something totally unacceptably bad
happens. That's for example the case when a Linux kernel corrupts the data it's
handling or damages hardware it's running on. You're also dealing with a severe
issue when the kernel suddenly stops working with an error message ('kernel
panic') or without any farewell note at all. Note: do not confuse a 'panic' (a
fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
as the kernel remains running after the latter.h]hX An issue is a ‘really severe problem’ when something totally unacceptably bad
happens. That’s for example the case when a Linux kernel corrupts the data it’s
handling or damages hardware it’s running on. You’re also dealing with a severe
issue when the kernel suddenly stops working with an error message (‘kernel
panic’) or without any farewell note at all. Note: do not confuse a ‘panic’ (a
fatal error where the kernel stop itself) with a ‘Oops’ (a recoverable error),
as the kernel remains running after the latter.}(hj\ hjZ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]issue-of-high-priorityah ]h"]issue of high priority?ah$]h&]uh1hhj hhhhhMzubh)}(hhh](h)}(hEnsure a healthy environmenth]hEnsure a healthy environment}(hju hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjp hhhhhMubj )}(hhh]h)}(hS*Make sure it's not the kernel's surroundings that are causing the issue
you face.*h]j )}(hj h]hUMake sure it’s not the kernel’s surroundings that are causing the issue
you face.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hjp hhhhhNubh)}(hProblems that look a lot like a kernel issue are sometimes caused by build or
runtime environment. It's hard to rule out that problem completely, but you
should minimize it:h]hProblems that look a lot like a kernel issue are sometimes caused by build or
runtime environment. It’s hard to rule out that problem completely, but you
should minimize it:}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjp hhubj )}(hhh]j )}(hhh](j )}(hUse proven tools when building your kernel, as bugs in the compiler or the
binutils can cause the resulting kernel to misbehave.
h]h)}(hUse proven tools when building your kernel, as bugs in the compiler or the
binutils can cause the resulting kernel to misbehave.h]hUse proven tools when building your kernel, as bugs in the compiler or the
binutils can cause the resulting kernel to misbehave.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hEnsure your computer components run within their design specifications;
that's especially important for the main processor, the main memory, and the
motherboard. Therefore, stop undervolting or overclocking when facing a
potential kernel issue.
h]h)}(hEnsure your computer components run within their design specifications;
that's especially important for the main processor, the main memory, and the
motherboard. Therefore, stop undervolting or overclocking when facing a
potential kernel issue.h]hEnsure your computer components run within their design specifications;
that’s especially important for the main processor, the main memory, and the
motherboard. Therefore, stop undervolting or overclocking when facing a
potential kernel issue.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hTry to make sure it's not faulty hardware that is causing your issue. Bad
main memory for example can result in a multitude of issues that will
manifest itself in problems looking like kernel issues.
h]h)}(hTry to make sure it's not faulty hardware that is causing your issue. Bad
main memory for example can result in a multitude of issues that will
manifest itself in problems looking like kernel issues.h]hTry to make sure it’s not faulty hardware that is causing your issue. Bad
main memory for example can result in a multitude of issues that will
manifest itself in problems looking like kernel issues.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hIf you're dealing with a filesystem issue, you might want to check the file
system in question with ``fsck``, as it might be damaged in a way that leads
to unexpected kernel behavior.
h]h)}(hIf you're dealing with a filesystem issue, you might want to check the file
system in question with ``fsck``, as it might be damaged in a way that leads
to unexpected kernel behavior.h](hfIf you’re dealing with a filesystem issue, you might want to check the file
system in question with }(hdIf you're dealing with a filesystem issue, you might want to check the file
system in question with hj
hhhNhNubj )}(h``fsck``h]hfsck}(hhhj
hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj
ubhK, as it might be damaged in a way that leads
to unexpected kernel behavior.}(hK, as it might be damaged in a way that leads
to unexpected kernel behavior.hj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hX When dealing with a regression, make sure it's not something else that
changed in parallel to updating the kernel. The problem for example might be
caused by other software that was updated at the same time. It can also
happen that a hardware component coincidentally just broke when you rebooted
into a new kernel for the first time. Updating the systems BIOS or changing
something in the BIOS Setup can also lead to problems that on look a lot
like a kernel regression.
h]h)}(hX When dealing with a regression, make sure it's not something else that
changed in parallel to updating the kernel. The problem for example might be
caused by other software that was updated at the same time. It can also
happen that a hardware component coincidentally just broke when you rebooted
into a new kernel for the first time. Updating the systems BIOS or changing
something in the BIOS Setup can also lead to problems that on look a lot
like a kernel regression.h]hX When dealing with a regression, make sure it’s not something else that
changed in parallel to updating the kernel. The problem for example might be
caused by other software that was updated at the same time. It can also
happen that a hardware component coincidentally just broke when you rebooted
into a new kernel for the first time. Updating the systems BIOS or changing
something in the BIOS Setup can also lead to problems that on look a lot
like a kernel regression.}(hj/
hj-
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj)
ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]j j uh1j hhhMhj ubah}(h]h ]h"]h$]h&]uh1j hjp hhhNhNubeh}(h]ensure-a-healthy-environmentah ]h"]ensure a healthy environmentah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(hPrepare for emergenciesh]hPrepare for emergencies}(hjZ
hjX
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjU
hhhhhMubj )}(hhh]h)}(hH*Create a fresh backup and put system repair and restore tools at hand.*h]j )}(hjk
h]hFCreate a fresh backup and put system repair and restore tools at hand.}(hhhjm
hhhNhNubah}(h]h ]h"]h$]h&]uh1j hji
ubah}(h]h ]h"]h$]h&]uh1hhhhMhjf
ubah}(h]h ]h"]h$]h&]uh1j hjU
hhhhhNubh)}(hX Reminder, you are dealing with computers, which sometimes do unexpected things,
especially if you fiddle with crucial parts like the kernel of its operating
system. That's what you are about to do in this process. Thus, make sure to
create a fresh backup; also ensure you have all tools at hand to repair or
reinstall the operating system as well as everything you need to restore the
backup.h]hX Reminder, you are dealing with computers, which sometimes do unexpected things,
especially if you fiddle with crucial parts like the kernel of its operating
system. That’s what you are about to do in this process. Thus, make sure to
create a fresh backup; also ensure you have all tools at hand to repair or
reinstall the operating system as well as everything you need to restore the
backup.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjU
hhubeh}(h]prepare-for-emergenciesah ]h"]prepare for emergenciesah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(h*Make sure your kernel doesn't get enhancedh]h,Make sure your kernel doesn’t get enhanced}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj
hhhhhMubj )}(hhh]h)}(h*Ensure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.*h]j )}(hj
h]hEnsure your system does not enhance its kernels by building additional
kernel modules on-the-fly, which solutions like DKMS might be doing locally
without your knowledge.}(hhhj
hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj
ubah}(h]h ]h"]h$]h&]uh1hhhhMhj
ubah}(h]h ]h"]h$]h&]uh1j hj
hhhhhNubh)}(hX The risk your issue report gets ignored or rejected dramatically increases if
your kernel gets enhanced in any way. That's why you should remove or disable
mechanisms like akmods and DKMS: those build add-on kernel modules
automatically, for example when you install a new Linux kernel or boot it for
the first time. Also remove any modules they might have installed. Then reboot
before proceeding.h]hX The risk your issue report gets ignored or rejected dramatically increases if
your kernel gets enhanced in any way. That’s why you should remove or disable
mechanisms like akmods and DKMS: those build add-on kernel modules
automatically, for example when you install a new Linux kernel or boot it for
the first time. Also remove any modules they might have installed. Then reboot
before proceeding.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hX| Note, you might not be aware that your system is using one of these solutions:
they often get set up silently when you install Nvidia's proprietary graphics
driver, VirtualBox, or other software that requires a some support from a
module not part of the Linux kernel. That why your might need to uninstall the
packages with such software to get rid of any 3rd party kernel module.h]hX~ Note, you might not be aware that your system is using one of these solutions:
they often get set up silently when you install Nvidia’s proprietary graphics
driver, VirtualBox, or other software that requires a some support from a
module not part of the Linux kernel. That why your might need to uninstall the
packages with such software to get rid of any 3rd party kernel module.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubeh}(h]*make-sure-your-kernel-doesn-t-get-enhancedah ]h"]*make sure your kernel doesn't get enhancedah$]h&]uh1hhj hhhhhMubh)}(hhh](h)}(hCheck 'taint' flagh]hCheck ‘taint’ flag}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj
hhhhhMubj )}(hhh]h)}(h*Check if your kernel was 'tainted' when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.*h]j )}(hj h]hCheck if your kernel was ‘tainted’ when the issue occurred, as the event
that made the kernel set this flag might be causing the issue you face.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hj
hhhhhNubh)}(hX& The kernel marks itself with a 'taint' flag when something happens that might
lead to follow-up errors that look totally unrelated. The issue you face might
be such an error if your kernel is tainted. That's why it's in your interest to
rule this out early before investing more time into this process. This is the
only reason why this step is here, as this process later will tell you to
install the latest mainline kernel; you will need to check the taint flag again
then, as that's when it matters because it's the kernel the report will focus
on.h]hX2 The kernel marks itself with a ‘taint’ flag when something happens that might
lead to follow-up errors that look totally unrelated. The issue you face might
be such an error if your kernel is tainted. That’s why it’s in your interest to
rule this out early before investing more time into this process. This is the
only reason why this step is here, as this process later will tell you to
install the latest mainline kernel; you will need to check the taint flag again
then, as that’s when it matters because it’s the kernel the report will focus
on.}(hj$ hj" hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hX On a running system is easy to check if the kernel tainted itself: if ``cat
/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and
everything is fine. Checking that file is impossible in some situations; that's
why the kernel also mentions the taint status when it reports an internal
problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a
non-recoverable error before halting operation (a 'kernel panic'). Look near
the top of the error messages printed when one of these occurs and search for a
line starting with 'CPU:'. It should end with 'Not tainted' if the kernel was
not tainted when it noticed the problem; it was tainted if you see 'Tainted:'
followed by a few spaces and some letters.h](hFOn a running system is easy to check if the kernel tainted itself: if }(hFOn a running system is easy to check if the kernel tainted itself: if hj0 hhhNhNubj )}(h ``cat
/proc/sys/kernel/tainted``h]hcat
/proc/sys/kernel/tainted}(hhhj9 hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj0 ubhX returns ‘0’ then the kernel is not tainted and
everything is fine. Checking that file is impossible in some situations; that’s
why the kernel also mentions the taint status when it reports an internal
problem (a ‘kernel bug’), a recoverable error (a ‘kernel Oops’) or a
non-recoverable error before halting operation (a ‘kernel panic’). Look near
the top of the error messages printed when one of these occurs and search for a
line starting with ‘CPU:’. It should end with ‘Not tainted’ if the kernel was
not tainted when it noticed the problem; it was tainted if you see ‘Tainted:’
followed by a few spaces and some letters.}(hXr returns '0' then the kernel is not tainted and
everything is fine. Checking that file is impossible in some situations; that's
why the kernel also mentions the taint status when it reports an internal
problem (a 'kernel bug'), a recoverable error (a 'kernel Oops') or a
non-recoverable error before halting operation (a 'kernel panic'). Look near
the top of the error messages printed when one of these occurs and search for a
line starting with 'CPU:'. It should end with 'Not tainted' if the kernel was
not tainted when it noticed the problem; it was tainted if you see 'Tainted:'
followed by a few spaces and some letters.hj0 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubh)}(hIf your kernel is tainted, study Documentation/admin-guide/tainted-kernels.rst
to find out why. Try to eliminate the reason. Often it's caused by one these
three things:h]hIf your kernel is tainted, study Documentation/admin-guide/tainted-kernels.rst
to find out why. Try to eliminate the reason. Often it’s caused by one these
three things:}(hjT hjR hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj
hhubj )}(hhh]henumerated_list)}(hhh](j )}(hX A recoverable error (a 'kernel Oops') occurred and the kernel tainted
itself, as the kernel knows it might misbehave in strange ways after that
point. In that case check your kernel or system log and look for a section
that starts with this::
Oops: 0000 [#1] SMP
That's the first Oops since boot-up, as the '#1' between the brackets shows.
Every Oops and any other problem that happens after that point might be a
follow-up problem to that first Oops, even if both look totally unrelated.
Rule this out by getting rid of the cause for the first Oops and reproducing
the issue afterwards. Sometimes simply restarting will be enough, sometimes
a change to the configuration followed by a reboot can eliminate the Oops.
But don't invest too much time into this at this point of the process, as
the cause for the Oops might already be fixed in the newer Linux kernel
version you are going to install later in this process.
h](h)}(hA recoverable error (a 'kernel Oops') occurred and the kernel tainted
itself, as the kernel knows it might misbehave in strange ways after that
point. In that case check your kernel or system log and look for a section
that starts with this::h]hA recoverable error (a ‘kernel Oops’) occurred and the kernel tainted
itself, as the kernel knows it might misbehave in strange ways after that
point. In that case check your kernel or system log and look for a section
that starts with this:}(hA recoverable error (a 'kernel Oops') occurred and the kernel tainted
itself, as the kernel knows it might misbehave in strange ways after that
point. In that case check your kernel or system log and look for a section
that starts with this:hjl hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjh ubh
literal_block)}(hOops: 0000 [#1] SMPh]hOops: 0000 [#1] SMP}(hhhj} ubah}(h]h ]h"]h$]h&]hhuh1j{ hhhMhjh ubh)}(hX That's the first Oops since boot-up, as the '#1' between the brackets shows.
Every Oops and any other problem that happens after that point might be a
follow-up problem to that first Oops, even if both look totally unrelated.
Rule this out by getting rid of the cause for the first Oops and reproducing
the issue afterwards. Sometimes simply restarting will be enough, sometimes
a change to the configuration followed by a reboot can eliminate the Oops.
But don't invest too much time into this at this point of the process, as
the cause for the Oops might already be fixed in the newer Linux kernel
version you are going to install later in this process.h]hX That’s the first Oops since boot-up, as the ‘#1’ between the brackets shows.
Every Oops and any other problem that happens after that point might be a
follow-up problem to that first Oops, even if both look totally unrelated.
Rule this out by getting rid of the cause for the first Oops and reproducing
the issue afterwards. Sometimes simply restarting will be enough, sometimes
a change to the configuration followed by a reboot can eliminate the Oops.
But don’t invest too much time into this at this point of the process, as
the cause for the Oops might already be fixed in the newer Linux kernel
version you are going to install later in this process.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjh ubeh}(h]h ]h"]h$]h&]uh1j hje ubj )}(hXa Your system uses a software that installs its own kernel modules, for
example Nvidia's proprietary graphics driver or VirtualBox. The kernel
taints itself when it loads such module from external sources (even if
they are Open Source): they sometimes cause errors in unrelated kernel
areas and thus might be causing the issue you face. You therefore have to
prevent those modules from loading when you want to report an issue to the
Linux kernel developers. Most of the time the easiest way to do that is:
temporarily uninstall such software including any modules they might have
installed. Afterwards reboot.
h]h)}(hX` Your system uses a software that installs its own kernel modules, for
example Nvidia's proprietary graphics driver or VirtualBox. The kernel
taints itself when it loads such module from external sources (even if
they are Open Source): they sometimes cause errors in unrelated kernel
areas and thus might be causing the issue you face. You therefore have to
prevent those modules from loading when you want to report an issue to the
Linux kernel developers. Most of the time the easiest way to do that is:
temporarily uninstall such software including any modules they might have
installed. Afterwards reboot.h]hXb Your system uses a software that installs its own kernel modules, for
example Nvidia’s proprietary graphics driver or VirtualBox. The kernel
taints itself when it loads such module from external sources (even if
they are Open Source): they sometimes cause errors in unrelated kernel
areas and thus might be causing the issue you face. You therefore have to
prevent those modules from loading when you want to report an issue to the
Linux kernel developers. Most of the time the easiest way to do that is:
temporarily uninstall such software including any modules they might have
installed. Afterwards reboot.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hje ubj )}(hXa The kernel also taints itself when it's loading a module that resides in
the staging tree of the Linux kernel source. That's a special area for
code (mostly drivers) that does not yet fulfill the normal Linux kernel
quality standards. When you report an issue with such a module it's
obviously okay if the kernel is tainted; just make sure the module in
question is the only reason for the taint. If the issue happens in an
unrelated area reboot and temporarily block the module from being loaded
by specifying ``foo.blacklist=1`` as kernel parameter (replace 'foo' with
the name of the module in question).
h]h)}(hX_ The kernel also taints itself when it's loading a module that resides in
the staging tree of the Linux kernel source. That's a special area for
code (mostly drivers) that does not yet fulfill the normal Linux kernel
quality standards. When you report an issue with such a module it's
obviously okay if the kernel is tainted; just make sure the module in
question is the only reason for the taint. If the issue happens in an
unrelated area reboot and temporarily block the module from being loaded
by specifying ``foo.blacklist=1`` as kernel parameter (replace 'foo' with
the name of the module in question).h](hX The kernel also taints itself when it’s loading a module that resides in
the staging tree of the Linux kernel source. That’s a special area for
code (mostly drivers) that does not yet fulfill the normal Linux kernel
quality standards. When you report an issue with such a module it’s
obviously okay if the kernel is tainted; just make sure the module in
question is the only reason for the taint. If the issue happens in an
unrelated area reboot and temporarily block the module from being loaded
by specifying }(hX The kernel also taints itself when it's loading a module that resides in
the staging tree of the Linux kernel source. That's a special area for
code (mostly drivers) that does not yet fulfill the normal Linux kernel
quality standards. When you report an issue with such a module it's
obviously okay if the kernel is tainted; just make sure the module in
question is the only reason for the taint. If the issue happens in an
unrelated area reboot and temporarily block the module from being loaded
by specifying hj hhhNhNubj )}(h``foo.blacklist=1``h]hfoo.blacklist=1}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubhQ as kernel parameter (replace ‘foo’ with
the name of the module in question).}(hM as kernel parameter (replace 'foo' with
the name of the module in question).hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j hje ubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffixj uh1jc hj` ubah}(h]h ]h"]h$]h&]uh1j hj
hhhNhNubeh}(h]check-taint-flagah ]h"]h$]check 'taint' flagah&]uh1hhj hhhhhMj Kubh)}(hhh](h)}(hDocument how to reproduce issueh]hDocument how to reproduce issue}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM$ubj )}(hhh]h)}(hX@ *Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That's needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.*h]j )}(hj h]hX@ Write down coarsely how to reproduce the issue. If you deal with multiple
issues at once, create separate notes for each of them and make sure they
work independently on a freshly booted system. That’s needed, as each issue
needs to get reported to the kernel developers separately, unless they are
strongly entangled.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhM&hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubh)}(hX; If you deal with multiple issues at once, you'll have to report each of them
separately, as they might be handled by different developers. Describing
various issues in one report also makes it quite difficult for others to tear
it apart. Hence, only combine issues in one report if they are very strongly
entangled.h]hX= If you deal with multiple issues at once, you’ll have to report each of them
separately, as they might be handled by different developers. Describing
various issues in one report also makes it quite difficult for others to tear
it apart. Hence, only combine issues in one report if they are very strongly
entangled.}(hj. hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj hhubh)}(hAdditionally, during the reporting process you will have to test if the issue
happens with other kernel versions. Therefore, it will make your work easier if
you know exactly how to reproduce an issue quickly on a freshly booted system.h]hAdditionally, during the reporting process you will have to test if the issue
happens with other kernel versions. Therefore, it will make your work easier if
you know exactly how to reproduce an issue quickly on a freshly booted system.}(hj< hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hj hhubh)}(hX Note: it's often fruitless to report issues that only happened once, as they
might be caused by a bit flip due to cosmic radiation. That's why you should
try to rule that out by reproducing the issue before going further. Feel free
to ignore this advice if you are experienced enough to tell a one-time error
due to faulty hardware apart from a kernel issue that rarely happens and thus
is hard to reproduce.h]hX Note: it’s often fruitless to report issues that only happened once, as they
might be caused by a bit flip due to cosmic radiation. That’s why you should
try to rule that out by reproducing the issue before going further. Feel free
to ignore this advice if you are experienced enough to tell a one-time error
due to faulty hardware apart from a kernel issue that rarely happens and thus
is hard to reproduce.}(hjJ hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj hhubeh}(h]document-how-to-reproduce-issueah ]h"]document how to reproduce issueah$]h&]uh1hhj hhhhhM$ubh)}(hhh](h)}(h(Regression in stable or longterm kernel?h]h(Regression in stable or longterm kernel?}(hjc hja hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ hhhhhM?ubj )}(hhh]h)}(h*If you are facing a regression within a stable or longterm version line
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
'Dealing with regressions within a stable and longterm kernel line'.*h]j )}(hjt h]hIf you are facing a regression within a stable or longterm version line
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
‘Dealing with regressions within a stable and longterm kernel line’.}(hhhjv hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjr ubah}(h]h ]h"]h$]h&]uh1hhhhMAhjo ubah}(h]h ]h"]h$]h&]uh1j hj^ hhhhhNubh)}(hX Regression within a stable and longterm kernel version line are something the
Linux developers want to fix badly, as such issues are even more unwanted than
regression in the main development branch, as they can quickly affect a lot of
people. The developers thus want to learn about such issues as quickly as
possible, hence there is a streamlined process to report them. Note,
regressions with newer kernel version line (say something broke when switching
from 5.9.15 to 5.10.5) do not qualify.h]hX Regression within a stable and longterm kernel version line are something the
Linux developers want to fix badly, as such issues are even more unwanted than
regression in the main development branch, as they can quickly affect a lot of
people. The developers thus want to learn about such issues as quickly as
possible, hence there is a streamlined process to report them. Note,
regressions with newer kernel version line (say something broke when switching
from 5.9.15 to 5.10.5) do not qualify.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj^ hhubeh}(h]'regression-in-stable-or-longterm-kernelah ]h"](regression in stable or longterm kernel?ah$]h&]uh1hhj hhhhhM?ubh)}(hhh](h)}(h)Check where you need to report your issueh]h)Check where you need to report your issue}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMOubj )}(hhh]h)}(hX *Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won't be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.*h]j )}(hj h]hX Locate the driver or kernel subsystem that seems to be causing the issue.
Find out how and where its developers expect reports. Note: most of the
time this won’t be bugzilla.kernel.org, as issues typically need to be sent
by mail to a maintainer and a public mailing list.}(hhhj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]uh1hhhhMQhj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubh)}(hX It's crucial to send your report to the right people, as the Linux kernel is a
big project and most of its developers are only familiar with a small subset of
it. Quite a few programmers for example only care for just one driver, for
example one for a WiFi chip; its developer likely will only have small or no
knowledge about the internals of remote or unrelated "subsystems", like the TCP
stack, the PCIe/PCI subsystem, memory management or file systems.h]hX It’s crucial to send your report to the right people, as the Linux kernel is a
big project and most of its developers are only familiar with a small subset of
it. Quite a few programmers for example only care for just one driver, for
example one for a WiFi chip; its developer likely will only have small or no
knowledge about the internals of remote or unrelated “subsystems”, like the TCP
stack, the PCIe/PCI subsystem, memory management or file systems.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMVhj hhubh)}(hX Problem is: the Linux kernel lacks a central bug tracker where you can simply
file your issue and make it reach the developers that need to know about it.
That's why you have to find the right place and way to report issues yourself.
You can do that with the help of a script (see below), but it mainly targets
kernel developers and experts. For everybody else the MAINTAINERS file is the
better place.h]hX Problem is: the Linux kernel lacks a central bug tracker where you can simply
file your issue and make it reach the developers that need to know about it.
That’s why you have to find the right place and way to report issues yourself.
You can do that with the help of a script (see below), but it mainly targets
kernel developers and experts. For everybody else the MAINTAINERS file is the
better place.}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hj hhubh)}(hhh](h)}(h How to read the MAINTAINERS fileh]h How to read the MAINTAINERS file}(hj hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMeubh)}(hX To illustrate how to use the :ref:`MAINTAINERS ` file, lets assume
the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
case it's likely an issue in the WiFi driver. Obviously it could also be some
code it builds upon, but unless you suspect something like that stick to the
driver. If it's really something else, the driver's developers will get the
right people involved.h](hTo illustrate how to use the }(hTo illustrate how to use the hj
hhhNhNubh)}(h :ref:`MAINTAINERS `h]j )}(hj
h]hMAINTAINERS}(hhhj
hhhNhNubah}(h]h ](j stdstd-refeh"]h$]h&]uh1j hj
ubah}(h]h ]h"]h$]h&]refdocj refdomainj
reftyperefrefexplicitrefwarnj maintainersuh1hhhhMfhj
ubhXe file, lets assume
the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
case it’s likely an issue in the WiFi driver. Obviously it could also be some
code it builds upon, but unless you suspect something like that stick to the
driver. If it’s really something else, the driver’s developers will get the
right people involved.}(hX_ file, lets assume
the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
case it's likely an issue in the WiFi driver. Obviously it could also be some
code it builds upon, but unless you suspect something like that stick to the
driver. If it's really something else, the driver's developers will get the
right people involved.hj
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMfhj hhubh)}(hvSadly, there is no way to check which code is driving a particular hardware
component that is both universal and easy.h]hvSadly, there is no way to check which code is driving a particular hardware
component that is both universal and easy.}(hj9
hj7
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhj hhubh)}(hIn case of a problem with the WiFi driver you for example might want to look at
the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and the
kernel module driving it::h](h^In case of a problem with the WiFi driver you for example might want to look at
the output of }(h^In case of a problem with the WiFi driver you for example might want to look at
the output of hjE
hhhNhNubj )}(h``lspci -k``h]hlspci -k}(hhhjN
hhhNhNubah}(h]h ]h"]h$]h&]uh1j hjE
ubhK, as it lists devices on the PCI/PCIe bus and the
kernel module driving it:}(hK, as it lists devices on the PCI/PCIe bus and the
kernel module driving it:hjE
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMphj hhubj| )}(h[user@something ~]$ lspci -k
[...]
3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
Subsystem: Bigfoot Networks, Inc. Device 1535
Kernel driver in use: ath10k_pci
Kernel modules: ath10k_pci
[...]h]h[user@something ~]$ lspci -k
[...]
3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
Subsystem: Bigfoot Networks, Inc. Device 1535
Kernel driver in use: ath10k_pci
Kernel modules: ath10k_pci
[...]}(hhhjg
ubah}(h]h ]h"]h$]h&]hhuh1j{ hhhMthj hhubh)}(hXX But this approach won't work if your WiFi chip is connected over USB or some
other internal bus. In those cases you might want to check your WiFi manager or
the output of ``ip link``. Look for the name of the problematic network
interface, which might be something like 'wlp58s0'. This name can be used like
this to find the module driving it::h](hBut this approach won’t work if your WiFi chip is connected over USB or some
other internal bus. In those cases you might want to check your WiFi manager or
the output of }(hBut this approach won't work if your WiFi chip is connected over USB or some
other internal bus. In those cases you might want to check your WiFi manager or
the output of hju
hhhNhNubj )}(h``ip link``h]hip link}(hhhj~
hhhNhNubah}(h]h ]h"]h$]h&]uh1j hju
ubh. Look for the name of the problematic network
interface, which might be something like ‘wlp58s0’. This name can be used like
this to find the module driving it:}(h. Look for the name of the problematic network
interface, which might be something like 'wlp58s0'. This name can be used like
this to find the module driving it:hju
hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM|hj hhubj| )}(hn[user@something ~]$ realpath --relative-to=/sys/module/ /sys/class/net/wlp58s0/device/driver/module
ath10k_pcih]hn[user@something ~]$ realpath --relative-to=/sys/module/ /sys/class/net/wlp58s0/device/driver/module
ath10k_pci}(hhhj
ubah}(h]h ]h"]h$]h&]hhuh1j{ hhhMhj hhubh)}(hIn case tricks like these don't bring you any further, try to search the
internet on how to narrow down the driver or subsystem in question. And if you
are unsure which it is: just try your best guess, somebody will help you if you
guessed poorly.h]hIn case tricks like these don’t bring you any further, try to search the
internet on how to narrow down the driver or subsystem in question. And if you
are unsure which it is: just try your best guess, somebody will help you if you
guessed poorly.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hXq Once you know the driver or subsystem, you want to search for it in the
MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as the
name is too specific. Sometimes you will need to search on the net for help;
but before doing so, try a somewhat shorted or modified name when searching the
MAINTAINERS file, as then you might find something like this::h]hXv Once you know the driver or subsystem, you want to search for it in the
MAINTAINERS file. In the case of ‘ath10k_pci’ you won’t find anything, as the
name is too specific. Sometimes you will need to search on the net for help;
but before doing so, try a somewhat shorted or modified name when searching the
MAINTAINERS file, as then you might find something like this:}(hXp Once you know the driver or subsystem, you want to search for it in the
MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as the
name is too specific. Sometimes you will need to search on the net for help;
but before doing so, try a somewhat shorted or modified name when searching the
MAINTAINERS file, as then you might find something like this:hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj| )}(hXc QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
Mail: A. Some Human
Mailing list: ath10k@lists.infradead.org
Status: Supported
Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
Files: drivers/net/wireless/ath/ath10k/h]hXc QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
Mail: A. Some Human
Mailing list: ath10k@lists.infradead.org
Status: Supported
Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
Files: drivers/net/wireless/ath/ath10k/}(hhhj
ubah}(h]h ]h"]h$]h&]hhuh1j{ hhhMhj hhubh)}(hX* Note: the line description will be abbreviations, if you read the plain
MAINTAINERS file found in the root of the Linux source tree. 'Mail:' for
example will be 'M:', 'Mailing list:' will be 'L', and 'Status:' will be 'S:'.
A section near the top of the file explains these and other abbreviations.h]hXB Note: the line description will be abbreviations, if you read the plain
MAINTAINERS file found in the root of the Linux source tree. ‘Mail:’ for
example will be ‘M:’, ‘Mailing list:’ will be ‘L’, and ‘Status:’ will be ‘S:’.
A section near the top of the file explains these and other abbreviations.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX First look at the line 'Status'. Ideally it should be 'Supported' or
'Maintained'. If it states 'Obsolete' then you are using some outdated approach
that was replaced by a newer solution you need to switch to. Sometimes the code
only has someone who provides 'Odd Fixes' when feeling motivated. And with
'Orphan' you are totally out of luck, as nobody takes care of the code anymore.
That only leaves these options: arrange yourself to live with the issue, fix it
yourself, or find a programmer somewhere willing to fix it.h]hX# First look at the line ‘Status’. Ideally it should be ‘Supported’ or
‘Maintained’. If it states ‘Obsolete’ then you are using some outdated approach
that was replaced by a newer solution you need to switch to. Sometimes the code
only has someone who provides ‘Odd Fixes’ when feeling motivated. And with
‘Orphan’ you are totally out of luck, as nobody takes care of the code anymore.
That only leaves these options: arrange yourself to live with the issue, fix it
yourself, or find a programmer somewhere willing to fix it.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX{ After checking the status, look for a line starting with 'bugs:': it will tell
you where to find a subsystem specific bug tracker to file your issue. The
example above does not have such a line. That is the case for most sections, as
Linux kernel development is completely driven by mail. Very few subsystems use
a bug tracker, and only some of those rely on bugzilla.kernel.org.h]hX After checking the status, look for a line starting with ‘bugs:’: it will tell
you where to find a subsystem specific bug tracker to file your issue. The
example above does not have such a line. That is the case for most sections, as
Linux kernel development is completely driven by mail. Very few subsystems use
a bug tracker, and only some of those rely on bugzilla.kernel.org.}(hj
hj
hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hX In this and many other cases you thus have to look for lines starting with
'Mail:' instead. Those mention the name and the email addresses for the
maintainers of the particular code. Also look for a line starting with 'Mailing
list:', which tells you the public mailing list where the code is developed.
Your report later needs to go by mail to those addresses. Additionally, for all
issue reports sent by email, make sure to add the Linux Kernel Mailing List
(LKML) to CC. Don't omit either of the mailing
lists when sending your issue report by mail later! Maintainers are busy people
and might leave some work for other developers on the subsystem specific list;
and LKML is important to have one place where all issue reports can be found.h](hX In this and many other cases you thus have to look for lines starting with
‘Mail:’ instead. Those mention the name and the email addresses for the
maintainers of the particular code. Also look for a line starting with ‘Mailing
list:’, which tells you the public mailing list where the code is developed.
Your report later needs to go by mail to those addresses. Additionally, for all
issue reports sent by email, make sure to add the Linux Kernel Mailing List
(LKML) <}(hX In this and many other cases you thus have to look for lines starting with
'Mail:' instead. Those mention the name and the email addresses for the
maintainers of the particular code. Also look for a line starting with 'Mailing
list:', which tells you the public mailing list where the code is developed.
Your report later needs to go by mail to those addresses. Additionally, for all
issue reports sent by email, make sure to add the Linux Kernel Mailing List
(LKML)