Lines Matching full:you
3 If you want to distribute this text under CC-BY-4.0 only, please use 'The
20 Are you facing a regression with vanilla kernels from the same stable or
24 you don't find any, install `the latest release from that series
34 search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you
38 The issue was fixed there, but you would like to see it resolved in a still
49 If you are facing multiple issues with the Linux kernel at once, report each
53 to pin-point the culprit with a bisection; if you succeed, include its
56 Once the report is out, answer any questions that come up and help where you
72 a slightly different order. That's in your interest, to make sure you notice
74 something else. These steps thus help to ensure the time you invest in this
77 * Are you facing an issue with a Linux kernel a hardware or software vendor
78 provided? Then in almost all cases you are better off to stop reading this
79 document and reporting the issue to your vendor instead, unless you are
85 List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports,
88 * See if the issue you are dealing with qualifies as regression, security
93 you face.
102 that made the kernel set this flag might be causing the issue you face.
104 * Write down coarsely how to reproduce the issue. If you deal with multiple
110 * If you are facing a regression within a stable or longterm version line
120 thoroughly for reports that might match your issue. If you find anything,
123 After these preparations you'll now enter the main part:
125 * Unless you are already running the latest 'mainline' Linux kernel, better
130 suspend your efforts for a few days anyway. Whatever version you choose,
134 * Ensure the kernel you just installed does not 'taint' itself when
137 * Reproduce the issue with the kernel you just installed. If it doesn't show
144 that hear about it for the first time. And if you learned something in this
154 issue. Always mention a few things: the latest kernel version you installed
160 you wrote this main part, insert a normal length paragraph on top of it
163 thing a descriptive title or subject that yet again is shorter. Then you're
164 ready to send or file the report like the MAINTAINERS file told you, unless
165 you are dealing with one of those 'issues of high priority': they need
169 * Wait for reactions and keep the thing rolling until you can accept the
174 help yourself, if you don't get any help or if it's unsatisfying.
180 This subsection is for you, if you followed above process and got sent here at
181 the point about regression within a stable or longterm kernel version line. You
188 line you care about: go to the `front page of kernel.org
197 the issue might have already been fixed there. If you first noticed the
203 (regressions@lists.linux.dev); if you suspect the cause in a particular
215 This subsection is for you, if you tried the latest mainline kernel as outlined
216 above, but failed to reproduce your issue there; at the same time you want to
228 the issue in mainline, as its commit message might tell you if the fix is
229 scheduled for backporting already. If you don't find anything that way,
262 * A warranty or support contract with some vendor doesn't entitle you to
265 development community, and this document. That's why you can't demand
267 developer handling the issue works for the vendor in question. If you want
269 so, you might want to mention you'd like to see the issue fixed in the
273 * If you never reported an issue to a FLOSS project before you should consider
284 Make sure you're using the upstream Linux kernel
287 *Are you facing an issue with a Linux kernel a hardware or software vendor
288 provided? Then in almost all cases you are better off to stop reading this
289 document and reporting the issue to your vendor instead, unless you are
304 Linux kernel developers: an issue you face with one of them might have been
306 the modifications and enhancements by the vendor might be causing the issue you
307 face, even if they look small or totally unrelated. That's why you should report
311 or might not what you want. You thus might want to consider circumventing the
313 option for you move ahead in this process, as a later step in this guide will
325 regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better
330 Obviously you are free to ignore all this advice and report problems with an old
342 List (LKML). If you find matching reports, join the discussion instead of
346 time for everyone involved, especially you as the reporter. So it's in your own
349 tell you to perform a more detailed search once you know where your issue needs
351 process, it can save you time and trouble.
357 If you get flooded with results consider telling your search engine to limit
358 search timeframe to the past month or year. And wherever you search, make sure
360 look at the issue from the perspective of someone else: that will help you to
369 In case you find an existing report about your issue, join the discussion, as
370 you might be able to provide valuable additional information. That can be
378 reports. If you find the latter, just keep in mind: most subsystems expect
379 reports in different places, as described below in the section "Check where you
389 *See if the issue you are dealing with qualifies as regression, security
398 You deal with a 'regression' if something that worked with an older version of
418 handling or damages hardware it's running on. You're also dealing with a severe
429 you face.*
432 runtime environment. It's hard to rule out that problem completely, but you
447 * If you're dealing with a filesystem issue, you might want to check the file
454 happen that a hardware component coincidentally just broke when you rebooted
465 Reminder, you are dealing with computers, which sometimes do unexpected things,
466 especially if you fiddle with crucial parts like the kernel of its operating
467 system. That's what you are about to do in this process. Thus, make sure to
468 create a fresh backup; also ensure you have all tools at hand to repair or
469 reinstall the operating system as well as everything you need to restore the
481 your kernel gets enhanced in any way. That's why you should remove or disable
483 automatically, for example when you install a new Linux kernel or boot it for
487 Note, you might not be aware that your system is using one of these solutions:
488 they often get set up silently when you install Nvidia's proprietary graphics
498 that made the kernel set this flag might be causing the issue you face.*
501 lead to follow-up errors that look totally unrelated. The issue you face might
504 only reason why this step is here, as this process later will tell you to
505 install the latest mainline kernel; you will need to check the taint flag again
517 not tainted when it noticed the problem; it was tainted if you see 'Tainted:'
539 version you are going to install later in this process.
545 areas and thus might be causing the issue you face. You therefore have to
546 prevent those modules from loading when you want to report an issue to the
554 quality standards. When you report an issue with such a module it's
565 *Write down coarsely how to reproduce the issue. If you deal with multiple
571 If you deal with multiple issues at once, you'll have to report each of them
577 Additionally, during the reporting process you will have to test if the issue
579 you know exactly how to reproduce an issue quickly on a freshly booted system.
582 might be caused by a bit flip due to cosmic radiation. That's why you should
584 to ignore this advice if you are experienced enough to tell a one-time error
592 *If you are facing a regression within a stable or longterm version line
605 Check where you need to report your issue
620 Problem is: the Linux kernel lacks a central bug tracker where you can simply
622 That's why you have to find the right place and way to report issues yourself.
623 You can do that with the help of a script (see below), but it mainly targets
632 code it builds upon, but unless you suspect something like that stick to the
639 In case of a problem with the WiFi driver you for example might want to look at
652 other internal bus. In those cases you might want to check your WiFi manager or
660 In case tricks like these don't bring you any further, try to search the
661 internet on how to narrow down the driver or subsystem in question. And if you
662 are unsure which it is: just try your best guess, somebody will help you if you
665 Once you know the driver or subsystem, you want to search for it in the
666 MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as the
667 name is too specific. Sometimes you will need to search on the net for help;
669 MAINTAINERS file, as then you might find something like this::
679 Note: the line description will be abbreviations, if you read the plain
685 'Maintained'. If it states 'Obsolete' then you are using some outdated approach
686 that was replaced by a newer solution you need to switch to. Sometimes the code
688 'Orphan' you are totally out of luck, as nobody takes care of the code anymore.
693 you where to find a subsystem specific bug tracker to file your issue. The
698 In this and many other cases you thus have to look for lines starting with
701 list:', which tells you the public mailing list where the code is developed.
734 the code as well as the Linux Kernel Mailing List (LKML). In this case you thus
738 Note: in case you cloned the Linux sources with git you might want to call
742 can easily send you in a wrong direction. That for example happens quickly in
752 thoroughly for reports that might match your issue. If you find anything,
756 brought forward is often a waste of time for everyone involved, especially you
757 as the reporter. That's why you should search for existing report again, now
758 that you know where they need to be reported to. If it's mailing list, you will
762 the ath10k WiFi driver used as example in the previous step. But you'll often
764 ath10k@lists.infradead.org' for example will lead you to the `Info page for the
774 at this point. If your report needs to be filed in a bug tracker, you may want
778 For details how to search and what to do if you find matching reports see
782 or even more time can save you and others quite a lot of time and trouble.
788 *Unless you are already running the latest 'mainline' Linux kernel, better
793 suspend your efforts for a few days anyway. Whatever version you choose,
801 interest that you confirm the issue still exists with the latest upstream code
802 before reporting it. You are free to ignore this advice, but as outlined
821 Head over to `kernel.org <https://kernel.org/>`_ to find out which version you
823 and look a little lower at the table. At its top you'll see a line starting with
825 number like '5.8-rc2'. If that's the case, you'll want to use this mainline
827 that 'rc' scare you, these 'development kernels' are pretty reliable — and you
828 made a backup, as you were instructed above, didn't you?
830 In about two out of every nine to ten weeks, mainline might point you to a
839 window fixes the issue you face; that's why you soon would have to retest with
844 to that if you're dealing with something that shouldn't wait. In that case
847 case mainline for some reason does currently not work for you. An in general:
853 kernel is so important: any issue you want to see fixed in older version lines
855 take a few days or weeks. Another reason: the fix you hope for might be too
862 further: if the issue doesn't occur with mainline it will guide you how to get
869 way for testing — especially is you are unfamiliar with the Linux kernel. The
873 you face or influence it somehow.
875 But you are in luck if you are using a popular Linux distribution: for quite a
876 few of them you'll find repositories on the net that contain packages with the
884 Please note that you might need to build your own kernel manually later: that's
888 BUG occurs; if you plan to decode those, you might be better off compiling a
905 the necessary steps already. If you are new to it, consider following one of
911 Note: If you are dealing with a panic, Oops, warning, or BUG from the kernel,
914 latter is the relevant one of those two, but can only be reached if you enable
917 you later to pinpoint the exact line of code that triggers your issue. The
928 *Ensure the kernel you just installed does not 'taint' itself when
933 unrelated. That's why you need to check if the kernel you just installed does
934 not set this flag. And if it does, you in almost all the cases needs to
935 eliminate the reason for it before you reporting issues that occur with it. See
942 *Reproduce the issue with the kernel you just installed. If it doesn't show
946 Check if the issue occurs with the fresh Linux kernel version you just
951 those). If you prefer to use one of those or just want to help their users,
962 that hear about it for the first time. And if you learned something in this
970 In this in the previous steps you likely have learned a thing or two about the
971 issue you face. Use this knowledge and search again for existing reports
972 instead you can join.
984 works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring
985 your kernel. If you did so, consider to decode the information from the
990 Decoding can be done with a script you find in the Linux source tree. If you
991 are running a kernel you compiled yourself earlier, call it like this::
995 If you are running a packaged vanilla kernel, you will likely have to install
996 the corresponding packages with debug symbols. Then call the script (which you
1021 Note, if you can't get this to work, simply skip this step and mention the
1022 reason for it in the report. If you're lucky, it might not be needed. And if it
1023 is, someone might help you to get things going. Also be aware this is just one
1026 needed in your case, developers will tell you what to do.
1047 will often require you to build about ten to twenty kernel images, trying to
1050 Thanks to a 'binary search' this will lead you to the one commit in the source
1051 code management system that's causing the regression. Once you find it, search
1053 (the first 12 characters of the commit id). This will lead you to existing
1058 highly recommended performing a bisection yourself. If you really can't or
1062 5.7 and 5.8) to check when it first showed up. Unless you're trying to find a
1065 interpret, which might render your testing useless. Once you found the major
1070 be unable to help unless you perform a bisection.
1072 When dealing with regressions make sure the issue you face is really caused by
1078 kernel freshly to each newer kernel version you try. Afterwards run ``make
1086 issue. Always mention a few things: the latest kernel version you installed
1092 you wrote this main part, insert a normal length paragraph on top of it
1095 thing a descriptive title or subject that yet again is shorter. Then you're
1096 ready to send or file the report like the MAINTAINERS file told you, unless
1097 you are dealing with one of those 'issues of high priority': they need
1101 Now that you have prepared everything it's time to write your report. How to do
1111 will look into it and help you. And that is why you should ignore them for now
1117 Describe in detail how your issue happens with the fresh vanilla kernel you
1118 installed. Try to include the step-by-step instructions you wrote and optimized
1119 earlier that outline how you and ideally others can reproduce the issue; in
1120 those rare cases where that's impossible try to describe what you did to
1125 but there are some things you should include always:
1135 * if you are dealing with a regression and performed a bisection, mention the
1143 * the kernel's messages that you get from ``dmesg`` written to a file. Make
1148 ``journalctl -b 0 -k``; alternatively you can also reboot, reproduce the
1152 your report. If you are filing the issue in a bug tracker then attach them to
1153 the ticket. If you report the issue by mail do not attach them, as that makes
1164 * Put the files aside and mention you will send them later in individual
1171 Depending on the issue you might need to add more background data. Here are a
1174 * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
1175 include it. If you can't copy'n'paste it, try to capture a netconsole trace
1179 of system you use. If you for example have problems with your graphics card,
1190 * Mention the relevant software in use. If you have problems with loading
1191 modules, you want to mention the versions of kmod, systemd, and udev in use.
1192 If one of the DRM drivers misbehaves, you want to state the versions of
1194 its driver. If you have a filesystem issue, mention the version of
1199 hardware you use. If you have a problem with hardware you even might want to
1209 attach, but you have to think yourself what will be helpful for others to know.
1218 Now that you have the detailed part of the report prepared let's get to the
1220 something like 'The detailed description:' before the part you just wrote and
1223 crucial parts readers need to know to understand what this is all about; if you
1226 Once you did that insert two more lines at the top and write a one sentence
1227 summary that explains quickly what the report is about. After that you have to
1230 Now that you have written this part take some time to optimize it, as it is the
1235 you, unless it's one of those 'issues of high priority' outlined earlier: in
1249 In case you performed a successful bisection, use the title of the change that
1260 Also add a short note at the top where you mention the URL to the ticket.
1264 chain, which you find at the end of its commit message.
1269 For issues that bear such a risk you will need to adjust the reporting process
1272 * If the MAINTAINERS file instructed you to report the issue by mail, do not
1275 * If you were supposed to file the issue in a bug tracker make sure to mark
1282 them when sending the report by mail. If you filed it in a bug tracker, forward
1284 you mention that you filed it with a link to the ticket.
1292 *Wait for reactions and keep the thing rolling until you can accept the
1297 help yourself, if you don't get any help or if it's unsatisfying.*
1299 If your report was good and you are really lucky then one of the developers
1303 all you need to do is reply with a 'Thank you very much' and switch to a version
1307 once you got the report out. What you'll have to do depends on the situations,
1309 details, here are a few important things you need to keep in mind for this part
1316 **Always reply in public**: When you filed the issue in a bug tracker, always
1319 you receive. That includes mails with any additional data you might want to add
1329 * Someone tells you to send something privately.
1331 * You were told to send something, but noticed it contains sensitive
1334 mail that you did that, so everyone else knows you honored the request.
1337 process someone might tell you to do something that requires a skill you might
1338 not have mastered yet. For example, you might be asked to use some test tools
1339 you never have heard of yet; or you might be asked to apply a patch to the
1344 about it to a chatroom or forum you normally hang out.
1346 **Be patient**: If you are really lucky you might get a reply to your report
1357 here: maintainers should address them as soon as possible; that's why you
1373 mail you sent as reply to your report (make sure it has all those in the CC
1375 commitment and that you are willing to help. It also tells developers if the
1378 idea, but only report your results if something relevant changed or if you are
1387 Here are your duties in case you got replies to your report:
1389 **Check who you deal with**: Most of the time it will be the maintainer or a
1392 including people that want to help, but in the end might guide you totally off
1394 many reasons why it's wise to quickly run an internet search to see who you're
1395 interacting with. By doing this you also get aware if your report was heard by
1400 **Inquiries for data**: Often you will be asked to test something or provide
1401 additional details. Try to provide the requested information soon, as you have
1402 the attention of someone that might help and risk losing it the longer you
1403 wait; that outcome is even likely if you do not provide the information within
1406 **Requests for testing**: When you are asked to test a diagnostic patch or a
1432 After the reminder wait three more weeks for replies. If you still don't get a
1433 proper reaction, you first should reconsider your approach. Did you maybe try
1439 review it before you send it out. Such an approach is totally fine; just
1443 If the report was proper you can send a second reminder; in it ask for advice
1446 version got published, as you should retest and provide a status update at that
1455 'issues of high priority' outlined earlier. So don't be too devastating if you
1467 Don't get devastated if you don't find any help or if the issue in the end does
1468 not get solved: the Linux kernel is FLOSS and thus you can still help yourself.
1469 You for example could try to find others that are affected and team up with
1471 together that mentions how many you are and why this is something that in your
1472 option should get fixed. Maybe together you can also narrow down the root cause
1481 This subsection provides details for the steps you need to perform if you face
1488 line you care about: go to the front page of kernel.org and make sure it
1494 chosen and gets supported for at least two years (often six). That's why you
1495 need to check if the kernel developers still support the version line you care
1498 Note, if kernel.org lists two stable version lines on the front page, you
1510 Maybe the issue you face is already known and was fixed or is about to. Hence,
1513 you find any matches, consider joining the discussion, unless the fix is
1521 the issue might have already been fixed there. If you first noticed the
1525 Before investing any more time in this process you want to check if the issue
1526 was already fixed in the latest release of version line you're interested in.
1531 Did you first notice the regression with a vendor kernel? Then changes the
1532 vendor applied might be interfering. You need to rule that out by performing
1533 a recheck. Say something broke when you updated from 5.10.4-vendor.42 to
1537 regression and you need switch back to the main step-by-step guide to report
1545 (regressions@lists.linux.dev); if you suspect the cause in a particular
1554 stable and regressions mailing list is all it takes; but in case you suspect
1558 And note, it helps developers a great deal if you can specify the exact version
1576 the recipients; also CC everyone in the signed-off-by chain, which you find at
1583 This section provides details for the steps you need to take if you could not
1602 fix you are hoping for might be one of those that won't be backported to the
1603 version line your care about. In that case you'll have no other choice then to
1604 live with the issue or switch to a newer Linux version, unless you want to
1613 You need to carry out a few steps already described in another section of this
1614 guide. Those steps will let you:
1617 you care about.
1628 the issue in mainline, as its commit message might tell you if the fix is
1629 scheduled for backporting already. If you don't find anything that way,
1635 In a lot of cases the issue you deal with will have happened with mainline, but
1637 to get the issue solved. That's why you want to search for it or any
1641 sources. You can do this with the web interfaces `on kernel.org
1643 or its mirror `on GitHub <https://github.com/torvalds/linux>`_; if you have
1644 a local clone you alternatively can search on the command line with ``git
1647 If you find the fix, look if the commit message near the end contains a
1656 * If the commit doesn't tell you anything or if you can't find the fix, look
1662 list archive might have the answer you are looking for.
1664 * If you see a proposed fix, search for it in the version control system as
1665 outlined above, as the commit might tell you if a backport can be expected.
1668 backported to the version line you care about. If that's the case you have
1673 join the discussion: mention the version where you face the issue and that
1674 you would like to see it fixed, if suitable.
1685 If the previous three steps didn't get you closer to a solution there is only
1686 one option left: ask for advice. Do that in a mail you sent to the maintainers
1716 old that it's something you don't find much outside of computer museums
1759 This text is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If you
1761 fix it. You are free to do the same in a mostly informal way if you want