* [PATCH v1 26/30] docs: reporting-issues: improve text on second search
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Fine-tune the instructions about searching lore again while dropping the
text on optimizing the write-up how to reproduce the issue: this is left
to a later step now.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 38 ++++++++++---------
1 file changed, 20 insertions(+), 18 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index a78060098c59f0..aad98ccb49add8 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -257,11 +257,17 @@ following the others is usually in your own interest.
[:ref:`details <verify_repiref>`]
- * 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.
+.. _checkloretwo_repisbs:
+
+* If you performed a bisection or learned anything new about the bug while
+ following this guide so far, search once more for earlier reports
+ and fixes. In the bisection case, you want to search
+ `lore <https://lore.kernel.org/all/>`_ for the culprit's mainline commit-id
+ abbreviated to seven characters immediately followed by an asterisk (e.g.,
+ '`1f2e3d4 <https://lore.kernel.org/all/?q=1f2e3d4*>`_'); if that does not
+ produce any valuable insights, search for the commit's title, too.
+
+ [:ref:`details <checkloretwo_repiref>`]
* If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
decoding the kernel log to find the line of code that triggered the error.
@@ -988,23 +994,19 @@ more detailed instructions, follow Documentation/admin-guide/verify-bugs-and-bis
[:ref:`back to step-by-step guide <verify_repisbs>`]
-Optimize description to reproduce issue
----------------------------------------
+.. _checkloretwo_repiref:
- *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.*
+Search again
+------------
-An unnecessarily complex report will make it hard for others to understand your
-report. Thus try to find a reproducer that's straight forward to describe and
-thus easy to understand in written form. Include all important details, but at
-the same time try to keep it as short as possible.
+ *If you performed a bisection or learned anything new about the bug
+ while following this guide so far, search once more* [:ref:`... <checkloretwo_repisbs>`]
-In this in the previous steps you likely have learned a thing or two about the
+During the previous step you likely have learned a thing or two about the
issue you face. Use this knowledge and search again for existing reports
-instead you can join.
+and potential fixes.
+
+[:ref:`back to step-by-step guide <checkloretwo_repisbs>`]
Decode failure messages
--
2.51.0
^ permalink raw reply related
* [PATCH v1 13/30] docs: reporting-issues: improve environment check
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Fine-tune the instructions regarding the environment check.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 74 ++++++++++++-------
1 file changed, 46 insertions(+), 28 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 861237aaf94126..439ec52f270167 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -92,9 +92,17 @@ following the others is usually in your own interest.
[:ref:`details <taintone_repiref>`]
+.. _checkenv_repisbs:
+
+* Evaluate briefly if some glitch in your kernel's environment might make it
+ misbehave -- like a hardware defect, an updated system firmware, a
+ misconfigured BIOS, an overclocked component, a kernel parameter enabling
+ something unsupported, a broken initramfs, an inconsistent file system,
+ changes to the linux-firmware files, or some malfunction/misconfiguration in
+ your Linux distribution.
+
+ [:ref:`details <checkenv_repiref>`]
- * Make sure it's not the kernel's surroundings that are causing the issue
- you face.
* Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the `Linux Kernel Mailing
@@ -481,39 +489,49 @@ These are the most frequent reasons why the kernel set the flag:
[:ref:`back to step-by-step guide <taintone_repisbs>`]
-Ensure a healthy environment
-----------------------------
+.. _checkenv_repiref:
+
+Ensure there is nothing wrong with the kernel's surroundings
+------------------------------------------------------------
+
+ *Evaluate briefly if some glitch in your kernel's environment might make it
+ misbehave -- like a* [:ref:`... <checkenv_repisbs>`]
+
+Problems that look like a kernel issue are sometimes caused by its
+surroundings. It is impossible to detect sometimes -- but it is wise to rule
+out a few common causes before wasting time on a meaningless bug report:
+
+* When dealing with a regression (e.g., something stopped working or works worse
+ after updating the kernel), make sure it is not something else that changed
+ in parallel. That could be something else you updated at the same time, like
+ the BIOS, the boot loader, Mesa, the linux-firmware package, or something
+ else close to the kernel; but it could also be some change you performed in
+ the BIOS setup or your Linux distribution's configuration.
+
+* Try to make sure the hardware is healthy, as problems with it can result in a
+ multitude of issues that look like kernel bugs.
- *Make sure it's not the kernel's surroundings that are causing the issue
- you face.*
+ Ideally try to rule out faulty RAM or a dying device causes the problem.
-Problems 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:
+ Also ensure your computer components run within their design specifications;
+ that is especially important for the main processor, the RAM, and the
+ motherboard. Therefore, stop undervolting or overclocking when facing a
+ potential kernel issue.
- * Use proven tools when building your kernel, as bugs in the compiler or the
- binutils can cause the resulting kernel to misbehave.
+* Temporarily remove any optional kernel parameters you use, as they might
+ enable unsupported or experimental features.
- * Ensure 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.
+* In case of any problems related to booting, check if the initramfs was
+ generated correctly.
- * Try 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.
+* When dealing with a file system issue, check the file
+ system in question with ``fsck``, as it might be damaged in a way that leads
+ to unexpected kernel behavior.
- * If 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.
+* Use proven tools when building your kernel, as bugs in the compiler or the
+ linker can cause the resulting kernel to misbehave.
- * 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.
+[:ref:`back to step-by-step guide <checkenv_repisbs>`]
Search for existing reports, first run
--
2.51.0
^ permalink raw reply related
* [PATCH v1 14/30] docs: reporting-issues: improve text about checking for existing issues
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Fine-tune the instructions with regards to checking for existing issues
-- and tell readers straight in the step-by-step guide what to do in
slightly more detail.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 166 ++++++++++++------
1 file changed, 115 insertions(+), 51 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 439ec52f270167..623feb55caae97 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -103,11 +103,31 @@ following the others is usually in your own interest.
[:ref:`details <checkenv_repiref>`]
+.. _checkloreone_repisbs:
+
+* Search `lore <https://lore.kernel.org/all/>`_ for similar reports and
+ potential fixes; afterwards the wider internet, too.
+
+ If you find a matching report, check it carefully:
+
+ * If it is less than a month old and without a single doubt about the same
+ issue, consider replying to tell involved people that you are affected as
+ well.
+
+ * If it just looks quite a lot like the same issue, send a reply briefly
+ describing your problem and ask if it might be the same issue; if you do
+ receive a negative reply or none at all, report the problem anew separately.
+
+ * In all other cases, prepare a separate report by following this guide
+ further and linking to any possibly related reports in yours.
+
+ When you find fixes, consider trying them. If they work and are not yet
+ committed, write a short reply to let the developers know. If they don't work
+ while fixing the issue for other people, you most likely face a different
+ problem you have to report independently while linking to the earlier report.
+
+ [:ref:`details <checkloreone_repiref>`]
- * Perform a rough search for existing reports with your favorite internet
- search engine; additionally, check the archives of the `Linux Kernel Mailing
- List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports,
- join the discussion instead of sending a new one.
* 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
@@ -534,53 +554,97 @@ out a few common causes before wasting time on a meaningless bug report:
[:ref:`back to step-by-step guide <checkenv_repisbs>`]
-Search for existing reports, first run
---------------------------------------
-
- *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.*
-
-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.
-
-Simply search the internet with your favorite search engine first. Afterwards,
-search the `Linux Kernel Mailing List (LKML) archives
-<https://lore.kernel.org/lkml/>`_.
-
-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').
-
-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.
-
-Note, searching `bugzilla.kernel.org <https://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.
+.. _checkloreone_repiref:
+
+Search for existing reports and fixes
+-------------------------------------
+
+ *Search lore.kernel.org for similar reports and potential fixes; afterwards
+ the wider internet, too.* [:ref:`... <checkloreone_repisbs>`]
+
+You don't want to waste your time reporting an issue anew someone already
+brought forward or resolved already. So it is in your own interest to check for
+existing reports and fixes.
+
+Searching for fixes and existing reports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your search on `lore <https://lore.kernel.org/all/>`_ and the web results in
+a flood of results, consider limiting the search timeframe. In lore you can do
+so by adding something like 'rt:3.months.ago..' or 'rt:1.years.ago..' to your
+query.
+
+Wherever you search, make sure to use good terms; vary them a few times, too.
+
+Start with something specific and become broader if there are no or too few
+results. Also try to look at the issue from the perspective of someone else:
+that might help you to come up with other terms to use in your search.
+
+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 way 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 the
+manufacturer of the main chip's name ('AMD') or the product's series
+('Radeon').
+
+Try fixes and evaluate matching reports closely
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you find a potential fix, give it a try; if it is still under discussion and
+helps, let the developers know through a short reply.
+
+You found matching reports or a fix that does not help? Then evaluate them
+closely, as they might be about a different issue with similar symptoms. Your
+next steps depend on the outcome:
+
+* Is the report or fix still discussed and without any doubt about an issue like
+ yours? Then join the exchange, as you might be able to provide valuable
+ additional information or test results.
+
+* If the report or fix seems to be about a different issue, ignore it and
+ proceed with this guide, but briefly mention and link the earlier report or
+ fix in your report later. After reporting, it might also be wise to send a
+ short reply to the earlier report with a text along the lines of 'To whom it
+ may concern, I ran into a similar, but from my understanding slightly
+ different problem', coupled with a link to the report.
+
+* When unsure if it is the same or a different problem, send a short reply to
+ the earlier report or fix; in it, very briefly outline the problem while
+ asking if that seems to be the same problem or a different one better
+ reported separately.
+
+While doing so, keep in mind:
+
+* Chaos and confusion easily ensue when an issue is reported in a bug tracker
+ ticket or mailing list thread that looks related, but, in fact, is about a
+ different issue. Try hard to avoid such an outcome, as then it can quickly
+ happen that none of the problems will be addressed in the end. The best
+ strategy to avoid that: Whenever there is a slight chance that your issue
+ might be different, report it in a new ticket or thread, but mention the
+ earlier reports you found; afterwards send a short reply to the earlier
+ ticket/thread with a text along the lines of 'I have a similar problem which
+ might or might not be related' coupled with a link to your report.
+
+* Never report an issue in a bug tracker ticket or a mailing list thread that
+ looks related, but is considered resolved. Always report in a new thread
+ instead; afterwards send a short reply to the earlier ticket/thread with a
+ text along the lines of 'I have a similar problem which might or might not be
+ related' coupled with a link to your report.
+
+* When spotting matching reports on `bugzilla.kernel.org
+ <https://bugzilla.kernel.org/>`_, keep in mind that the appropriate
+ developers to handle the issue might not even be aware of the report. That is
+ because Bugzilla might not have forwarded the report to them: It lacks the
+ necessary information to do so for many of the kernel's subsystems, as their
+ developers expect reports in different places -- ':ref:`Check how to report
+ your issue <maintainers_repiref>`' describes this in more detail. If in
+ doubt, add a comment to the Bugzilla report; if no reassuring answer is
+ forthcoming, report the issue briefly through the proper channel while
+ mentioning the Bugzilla report; afterwards add a comment to the latter
+ pointing to your report.
+
+[:ref:`back to step-by-step guide <checkloreone_repisbs>`]
Issue of high priority?
--
2.51.0
^ permalink raw reply related
* [PATCH v1 27/30] docs: reporting-issues: make collecting files a separate step
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Make collecting files a separate step and tone down the need to decode
stack traces somewhat.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 158 +++++++++---------
1 file changed, 79 insertions(+), 79 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index aad98ccb49add8..5c991163039f82 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -269,8 +269,34 @@ following the others is usually in your own interest.
[:ref:`details <checkloretwo_repiref>`]
- * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
- decoding the kernel log to find the line of code that triggered the error.
+.. _attachments_repisbs:
+
+* Collect relevant files to supply with the report.
+
+ It almost always is wise to store the log messages (``journalctl -k``) from
+ the kernel used for the verification to a file. In case of a regression,
+ create a file with log messages from a working kernel, too.
+
+ What else is appropriate to supply depends on your problem. In case of build
+ errors, the build configuration (the '.config' file) used for the verification
+ is important to provide. Other times it is wise to include separate files
+ with the output from commands such as ``lsblk``, ``lspci -nn``, ``lsusb.py``,
+ ``alsa-info.sh``, or ``grep -s '' /sys/class/dmi/id/*``; occasionally the
+ output of ``lscpu``, ``lsirq``, ``lsmod``, ``sudo lspci -vvv``, or ``lsscsi``
+ makes sense, too.
+
+ Only compress files larger than a megabyte. Do not use an archiver to package
+ multiple files together.
+
+ If you later have to file the report in a bug tracker, attach the files. If
+ you have to email it, attach them when they in total are smaller than 250
+ KByte; if they are bigger, attach only the most relevant and send the rest in
+ a reply-to-all to your own report. Alternatively, create a ticket in
+ `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ with a brief note that
+ the ticket is only meant to store files used in a mailed report; attach the
+ files there and later link to them in your report.
+
+ [:ref:`details <attachments_repiref>`]
* Start to compile the report by writing a detailed description about the
issue. Always mention a few things: the latest kernel version you installed
@@ -1009,58 +1035,77 @@ and potential fixes.
[:ref:`back to step-by-step guide <checkloretwo_repisbs>`]
+.. _attachments_repiref:
+
+Collect files to provide
+------------------------
+
+ *Collect relevant files to supply with the report.* [:ref:`... <attachments_repisbs>`]
+
+The developers will usually ask for files with details about your system, as
+what is needed highly depends on the nature of the problem. But it is often
+wise to provide at least the kernel log and maybe a few things along with the
+report, as outlined in the step-by-step guide.
+
+When collecting the kernel's log messages with ``dmesg``, make sure they start
+with a line like 'Linux version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1,
+GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020'. The kernel discarded
+messages from the first boot phase already if it is missing. In that case,
+instead consider using ``journalctl -k``; alternatively, reboot and reproduce
+the issue, before calling ``dmesg`` right afterwards.
+
+In case the kernel's log messages contain a 'panic', 'Oops', 'warning', or
+'BUG', you might want to decode them as described below if that is easy for you
+-- but that is optional, as many bugs can be solved without this.
+
+On many Linux distributions the tools mentioned by the guide are installed by
+default, except maybe ``alsa-info.sh``, which `the sound subsystem developers
+provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
+
+
Decode failure messages
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
- *If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
- decoding the kernel log to find the line of code that triggered the error.*
+A 'panic', 'Oops', 'warning', or 'BUG' includes a stack trace, which contains
+addresses that allow pinpointing the exact path to the line in your kernel's
+source code that triggered the issue. Many bugs can be resolved without
+decoding these addresses, but for some it is helpful or required.
-When the kernel detects an internal problem, it will log some information about
-the executed code. This makes it possible to pinpoint the exact line in the
-source code that triggered the issue and shows how it was called. But that only
-works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring
-your kernel. If you did so, consider to decode the information from the
-kernel's log. That will make it a lot easier to understand what lead to the
-'panic', 'Oops', 'warning', or 'BUG', which increases the chances that someone
-can provide a fix.
+That is why it is fine to report problems without bothering about this, but
+when asked for this, try to decode the stack trace. Note: This requires a
+kernel build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled.
-Decoding can be done with a script you find in the Linux source tree. If you
-are running a kernel you compiled yourself earlier, call it like this::
+Usually you want to decode using a script shipped in the Linux sources. If you
+are running a kernel you compiled yourself, call it like this::
- [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux
+ [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux
-If you are running a packaged vanilla kernel, you will likely have to install
-the corresponding packages with debug symbols. Then call the script (which you
-might need to get from the Linux sources if your distro does not package it)
-like this::
+If you are running a packaged kernel, you will likely have to install packages
+with the corresponding debug symbols. Then call the script (which you might need
+to fetch from the Linux sources if your distro does not package it) like this::
- [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \
- /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/
+ [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \
+ /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/debug/kernel-5.10.10-4.1.x86_64/
The script will work on log lines like the following, which show the address of
the code the kernel was executing when the error occurred::
- [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module]
+ [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module]
Once decoded, these lines will look like this::
- [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module
+ [ 68.387301] RIP: 0010:test_module_init (/home/user/linux-5.10.5/test-module/test-module.c:16) test_module
In this case the executed code was built from the file
-'~/linux-5.10.5/test-module/test-module.c' and the error occurred by the
+'~/linux-5.10.5/test-module/test-module.c' and the error occurred during the
instructions found in line '16'.
The script will similarly decode the addresses mentioned in the section
-starting with 'Call trace', which show the path to the function where the
-problem occurred. Additionally, the script will show the assembler output for
-the code section the kernel was executing.
+starting with 'Call trace', which shows the path to the function where the
+problem occurred. The script, furthermore, will show the assembler output for
+the code section the kernel was executing at that time.
-Note, if you can't get this to work, simply skip this step and mention the
-reason for it in the report. If you're lucky, it might not be needed. And if it
-is, someone might help you to get things going. Also be aware this is just one
-of several ways to decode kernel stack traces. Sometimes different steps will
-be required to retrieve the relevant details. Don't worry about that, if that's
-needed in your case, developers will tell you what to do.
+[:ref:`back to step-by-step guide <attachments_repisbs>`]
Write and send the report
@@ -1119,46 +1164,12 @@ but there are some things you should include always:
* if you are dealing with a regression and performed a bisection, mention the
subject and the commit-id of the change that is causing it.
-In a lot of cases it's also wise to make two more things available to those
-that read your report:
-
- * the configuration used for building your Linux kernel (the '.config' file)
-
- * the kernel's messages that you get from ``dmesg`` written to a file. Make
- sure that it starts with a line like 'Linux version 5.8-1
- (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version 2.34) #1 SMP Mon Aug
- 3 14:54:37 UTC 2020' If it's missing, then important messages from the first
- boot phase already got discarded. In this case instead consider using
- ``journalctl -b 0 -k``; alternatively you can also reboot, reproduce the
- issue and call ``dmesg`` right afterwards.
-
-These two files are big, that's why it's a bad idea to put them directly into
-your report. If you are filing the issue in a bug tracker then attach them to
-the ticket. If you report the issue by mail do not attach them, as that makes
-the mail too large; instead do one of these things:
-
- * Upload the files somewhere public (your website, a public file paste
- service, a ticket created just for this purpose on `bugzilla.kernel.org
- <https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
- report. Ideally use something where the files stay available for years, as
- they could be useful to someone many years from now; this for example can
- happen if five or ten years from now a developer works on some code that was
- changed just to fix your issue.
-
- * Put the files aside and mention you will send them later in individual
- replies to your own mail. Just remember to actually do that once the report
- went out. ;-)
-
Things that might be wise to provide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Depending on the issue you might need to add more background data. Here are a
few suggestions what often is good to provide:
- * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
- include it. If you can't copy'n'paste it, try to capture a netconsole trace
- or at least take a picture of the screen.
-
* If the issue might be related to your computer hardware, mention what kind
of system you use. If you for example have problems with your graphics card,
mention its manufacturer, the card's model, and what chip is uses. If it's a
@@ -1178,17 +1189,6 @@ few suggestions what often is good to provide:
its driver. If you have a filesystem issue, mention the version of
corresponding filesystem utilities (e2fsprogs, btrfs-progs, xfsprogs, ...).
- * Gather additional information from the kernel that might be of interest. The
- output from ``lspci -nn`` will for example help others to identify what
- hardware you use. If you have a problem with hardware you even might want to
- make the output from ``sudo lspci -vvv`` available, as that provides
- insights how the components were configured. For some issues it might be
- good to include the contents of files like ``/proc/cpuinfo``,
- ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
- ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
- information. One such tool is ``alsa-info.sh`` `which the audio/sound
- subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
-
Those examples should give your some ideas of what data might be wise to
attach, but you have to think yourself what will be helpful for others to know.
Don't worry too much about forgetting something, as developers will ask for
--
2.51.0
^ permalink raw reply related
* [PATCH v1 12/30] docs: reporting-issues: move 'check environment' upwards
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Move text around to improve diffability of an follow-up patch.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 76 +++++++++----------
1 file changed, 38 insertions(+), 38 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 452733669debf5..861237aaf94126 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -93,6 +93,9 @@ following the others is usually in your own interest.
[:ref:`details <taintone_repiref>`]
+ * Make sure it's not the kernel's surroundings that are causing the issue
+ you face.
+
* Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the `Linux Kernel Mailing
List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports,
@@ -102,9 +105,6 @@ following the others is usually in your own interest.
issue, or a really severe problem: those are 'issues of high priority' that
need special handling in some steps that are about to follow.
- * Make sure it's not the kernel's surroundings that are causing the issue
- you face.
-
* Create a fresh backup and put system repair and restore tools at hand.
* Ensure your system does not enhance its kernels by building additional
@@ -481,6 +481,41 @@ These are the most frequent reasons why the kernel set the flag:
[:ref:`back to step-by-step guide <taintone_repisbs>`]
+Ensure a healthy environment
+----------------------------
+
+ *Make sure it's not the kernel's surroundings that are causing the issue
+ you face.*
+
+Problems 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:
+
+ * Use proven tools when building your kernel, as bugs in the compiler or the
+ binutils can cause the resulting kernel to misbehave.
+
+ * Ensure 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.
+
+ * Try 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.
+
+ * If 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.
+
+ * 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.
+
+
Search for existing reports, first run
--------------------------------------
@@ -563,41 +598,6 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
as the kernel remains running after the latter.
-Ensure a healthy environment
-----------------------------
-
- *Make sure it's not the kernel's surroundings that are causing the issue
- you face.*
-
-Problems 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:
-
- * Use proven tools when building your kernel, as bugs in the compiler or the
- binutils can cause the resulting kernel to misbehave.
-
- * Ensure 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.
-
- * Try 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.
-
- * If 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.
-
- * 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.
-
-
Prepare for emergencies
-----------------------
--
2.51.0
^ permalink raw reply related
* [PATCH v1 28/30] docs: reporting-issues: separate steps for optimizing and submitting reports
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Make optimizing and submitting reports separate steps. The latter now
needs to cover regressions as well, which earlier was handled by a
separate section.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 341 ++++++++++--------
1 file changed, 199 insertions(+), 142 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 5c991163039f82..c147191a7d0987 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -298,21 +298,79 @@ following the others is usually in your own interest.
[:ref:`details <attachments_repiref>`]
- * 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.
+.. _compile_repisbs:
+
+* Prepare and optimize the report.
+
+ Start by writing a text describing the problem. Ensure it contains all the
+ important bits directly so that readers do not have to open attachments or
+ follow links to understand roughly what the report is about -- you thus might
+ want to copy error messages and similarly important parts from supplied files
+ into the text.
+
+ Early on in the text, mention the distribution and kernel version used for the
+ bug verification.
+
+ In case of a regression, start the subject with '[REGRESSION]'. Furthermore,
+ specify early in the text the latest working versions and all known to be
+ broken; if you performed a bisection, mention the culprit's commit-id, title,
+ and authors instead.
+
+ Mention the Linux distribution used and other aspects of your environment
+ that might be relevant, like the machine's model name, the hardware
+ components involved, or the version of related userspace drivers.
+
+ Make sure to not overload the report with a long problem description, too
+ many details, or many attachments: Developers will ask for additional
+ information when needed.
+
+ Now write a subject, which is the only thing most people will read -- hence
+ try hard to make it as descriptive as possible without making it overly long,
+ as that is your best chance to grab people's attention. Your second best
+ chance is the first paragraph. If your problem description is longer than two
+ or three paragraphs, you thus want to create a small intro paragraph
+ describing the gist of the problem; if it is shorter, optimize the early
+ sentences.
+
+ At the end, review and optimize the report once more to make it as
+ straightforward as possible while ensuring the problem is easy to grasp for
+ people new to it.
+
+ [:ref:`details <compile_repiref>`]
+
+.. _submit_repisbs:
+
+* Submit your report in the appropriate way, which depends on the outcome of
+ the verification and the MAINTAINERS entry.
+
+ * Are you facing a regression within a stable or longterm kernel series you
+ were unable to reproduce with a fresh mainline kernel? Then report it by
+ email to the stable team while CCing the regressions list (To: Greg
+ Kroah-Hartman <gregkh@linuxfoundation.org>, Sasha Levin <sashal@kernel.org>;
+ CC: stable@vger.kernel.org, regressions@lists.linux.dev); if you performed a
+ bisection, CC everyone in the culprit's 'Signed-off-by' chain, too.
+
+ * In all other cases, submit the report as specified in MAINTAINERS while
+ keeping Documentation/process/security-bugs.rst in mind in case you deal
+ with a security issue:
+
+ * If that means reporting by email, CC linux-kernel@vger.kernel.org. In case
+ of a regression, CC regressions@lists.linux.dev, too -- and when the
+ culprit is known, also everyone in its 'Signed-off-by' chain, while
+ addressing the email to the culprit's author.
+
+ * If that means submitting a regression to a bug tracker, perform
+ one more thing afterwards: Write a short heads-up email with a link to the
+ report to regressions@lists.linux.dev -- and if the culprit is known, CC
+ everyone that signed it off, while addressing the email to the culprit's
+ author.
+
+ Whichever way it is, in case you sent the brief inquiry mentioned initially
+ to the regressions list, try to keep that discussion involved: Either send
+ your report as a reply to the earlier inquiry while adding relevant parties
+ or send a quick reply-to-self with a link to the proper report.
+
+ [:ref:`details <submit_repiref>`]
* 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
@@ -1108,166 +1166,165 @@ the code section the kernel was executing at that time.
[:ref:`back to step-by-step guide <attachments_repisbs>`]
-Write and send the report
--------------------------
-
- *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.*
-
-Now that you have prepared everything it's time to write your report. How to do
-that is partly explained by the three documents linked to in the preface above.
-That's why this text will only mention a few of the essentials as well as
-things specific to the Linux kernel.
-
-There is one thing that fits both categories: the most crucial parts of your
-report are the title/subject, the first sentence, and the first paragraph.
-Developers often get quite a lot of mail. They thus often just take a few
-seconds to skim a mail before deciding to move on or look closer. Thus: the
-better the top section of your report, the higher are the chances that someone
-will look into it and help you. And that is why you should ignore them for now
-and write the detailed report first. ;-)
+.. _compile_repiref:
+
+Prepare and optimize the report
+-------------------------------
+
+ *Prepare and optimize the report.* [:ref:`... <compile_repisbs>`]
+
+Most developers just take a few seconds to skim a report before deciding
+between taking a closer look or moving on, as they receive a ton of messages.
+That is why the title/subject, the first sentence, and the three or four
+following it are crucial.
+
+People will also stop reading if the report's text is long or hard to follow;
+the same is true if crucial information is not at hand. So be sure to describe
+things as short, straightforward, and simple as possible while providing
+everything important.
+
+How to do that is partly explained by the three documents linked to in the
+reference section's intro. The next few subsections thus will only mention a
+few essentials as well as things specific to the Linux kernel.
+
Things each report should mention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Describe in detail how your issue happens with the fresh vanilla kernel you
-installed. Try to include the step-by-step instructions you wrote and optimized
-earlier that outline how you and ideally others can reproduce the issue; in
-those rare cases where that's impossible try to describe what you did to
-trigger it.
+Describe the problem while mentioning all the important details about the
+environment others might need to fully understand the issue.:
+
+* The output from ``uname -r`` from the Linux kernel used for the verification.
-Also include all the relevant information others might need to understand the
-issue and its environment. What's actually needed depends a lot on the issue,
-but there are some things you should include always:
+* The Linux distribution used (``hostnamectl | grep 'Operating System'``)
- * the output from ``cat /proc/version``, which contains the Linux kernel
- version number and the compiler it was built with.
+* The nature of the issue and when it occurs.
- * the Linux distribution the machine is running (``hostnamectl | grep
- "Operating System"``)
+* If you are dealing with a regression and performed a bisection, mention
+ The author, subject, and commit-id of the culprit change.
- * the architecture of the CPU and the operating system (``uname -mi``)
+* If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
+ include it. If you can't copy and paste it, take a picture of the screen.
- * if you are dealing with a regression and performed a bisection, mention the
- subject and the commit-id of the change that is causing it.
-Things that might be wise to provide
+Things that might be good to provide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Depending on the issue you might need to add more background data. Here are a
-few suggestions what often is good to provide:
-
- * If the issue might be related to your computer hardware, mention what kind
- of system you use. If you for example have problems with your graphics card,
- mention its manufacturer, the card's model, and what chip is uses. If it's a
- laptop mention its name, but try to make sure it's meaningful. 'Dell XPS 13'
- for example is not, because it might be the one from 2012; that one looks
- not that different from the one sold today, but apart from that the two have
- nothing in common. Hence, in such cases add the exact model number, which
- for example are '9380' or '7390' for XPS 13 models introduced during 2019.
- Names like 'Lenovo Thinkpad T590' are also somewhat ambiguous: there are
- variants of this laptop with and without a dedicated graphics chip, so try
- to find the exact model name or specify the main components.
-
- * Mention the relevant software in use. If you have problems with loading
- modules, you want to mention the versions of kmod, systemd, and udev in use.
- If one of the DRM drivers misbehaves, you want to state the versions of
- libdrm and Mesa; also specify your Wayland compositor or the X-Server and
- its driver. If you have a filesystem issue, mention the version of
- corresponding filesystem utilities (e2fsprogs, btrfs-progs, xfsprogs, ...).
-
-Those examples should give your some ideas of what data might be wise to
-attach, but you have to think yourself what will be helpful for others to know.
+In some cases it is wise to provide additional details:
+
+* The processor architecture used (``uname -mi``).
+
+* The relevant software in use. If you have problems with loading
+ modules, you want to mention the versions of kmod, systemd, and udev in use.
+ If one of the DRM drivers misbehaves, you want to state the versions of
+ libdrm and Mesa; also specify your Wayland compositor or the X-Server and
+ its driver.
+
+* If the issue might be related to your hardware, mention what kind
+ of system you use. If you, for example, have problems with your graphics card,
+ mention its manufacturer, the card's model, and what chip it uses. If it is a
+ laptop, specify its name, but try to make sure it is meaningful. 'Dell XPS
+ 13', for example, is not, because that might be the one from 2012 or 2020;
+ the latter might not look that different, but apart from that it shares
+ nothing with the former. In such cases add the exact model number, like '9380'
+ or '7390' for XPS 13 models introduced during 2019. Names like 'Lenovo
+ Thinkpad T590' are also somewhat ambiguous: There are variants of this laptop
+ with and without a dedicated graphics chip, so try to find the exact model
+ name or specify the main components.
+
+Those examples should give you some ideas of what data might be wise to
+specify, but you have to think through yourself what will be helpful for others
+to know.
+
Don't worry too much about forgetting something, as developers will ask for
additional details they need. But making everything important available from
the start increases the chance someone will take a closer look.
+Special handling for high-priority issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The important part: the head of your report
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Reports for high-priority issues need special handling:
-Now that you have the detailed part of the report prepared let's get to the
-most important section: the first few sentences. Thus go to the top, add
-something like 'The detailed description:' before the part you just wrote and
-insert two newlines at the top. Now write one normal length paragraph that
-describes the issue roughly. Leave out all boring details and focus on the
-crucial parts readers need to know to understand what this is all about; if you
-think this bug affects a lot of users, mention this to get people interested.
+* Regressions: Make the report's subject start with '[REGRESSION]'.
-Once you did that insert two more lines at the top and write a one sentence
-summary that explains quickly what the report is about. After that you have to
-get even more abstract and write an even shorter subject/title for the report.
+ In case you performed a successful bisection, use the title of the change that
+ introduced the regression as the second part of your subject. Make the report
+ also mention the commit-id of the culprit. In case of an unsuccessful
+ bisection, make your report mention the latest tested version that is working
+ fine (say 5.7) and the oldest where the issue occurs (say 5.8-rc1).
-Now that you have written this part take some time to optimize it, as it is the
-most important parts of your report: a lot of people will only read this before
-they decide if reading the rest is time well spent.
+ When sending the report by email, CC the Linux regressions mailing list
+ (regressions@lists.linux.dev). In case the report needs to be filed to some
+ web tracker, proceed to do so. Once filed, forward the report by email to the
+ regressions list; CC the maintainer and the mailing list for the subsystem in
+ question. Make sure to inline the forwarded report and do not attach it.
+ Also add a short note at the top where you mention the URL to the ticket.
-Now send or file the report like the :ref:`MAINTAINERS <maintainers>` file told
-you, unless it's one of those 'issues of high priority' outlined earlier: in
-that case please read the next subsection first before sending the report on
-its way.
+ When mailing or forwarding the report, in case of a successful bisection, add
+ the author of the culprit to the recipients; also CC everyone in the
+ signed-off-by chain, which you find at the end of its commit message.
-Special handling for high priority issues
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Security issues: For these issues you will have to evaluate if a
+ short-term risk to other users would arise if details were publicly disclosed.
+ If that is not the case, simply proceed with reporting the issue as described.
+ For issues that bear such a risk, you will need to adjust the reporting
+ process slightly:
-Reports for high priority issues need special handling.
+ * If the MAINTAINERS file instructed you to report the issue by email, do not
+ CC any public mailing lists.
-**Severe issues**: make sure the subject or ticket title as well as the first
-paragraph makes the severeness obvious.
+ * If you were supposed to file the issue in a bug tracker, make sure to mark
+ the ticket as 'private' or 'security issue'. If the bug tracker does not
+ offer a way to keep reports private, forget about it and send your report as
+ a private email to the maintainers instead.
-**Regressions**: make the report's subject start with '[REGRESSION]'.
+ In both cases, make sure to also email your report to the addresses the
+ MAINTAINERS file lists in the section 'security contact'. Ideally, directly CC
+ them when sending the report by email. If you filed it in a bug tracker, forward
+ the report's text to these addresses; but on top of it, put a small note where
+ you mention that you filed it with a link to the ticket.
-In case you performed a successful bisection, use the title of the change that
-introduced the regression as the second part of your subject. Make the report
-also mention the commit id of the culprit. In case of an unsuccessful bisection,
-make your report mention the latest tested version that's working fine (say 5.7)
-and the oldest where the issue occurs (say 5.8-rc1).
+ See Documentation/process/security-bugs.rst for more information.
-When sending the report by mail, CC the Linux regressions mailing list
-(regressions@lists.linux.dev). In case the report needs to be filed to some web
-tracker, proceed to do so. Once filed, forward the report by mail to the
-regressions list; CC the maintainer and the mailing list for the subsystem in
-question. Make sure to inline the forwarded report, hence do not attach it.
-Also add a short note at the top where you mention the URL to the ticket.
+Optimize the report and especially its head section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When mailing or forwarding the report, in case of a successful bisection add the
-author of the culprit to the recipients; also CC everyone in the signed-off-by
-chain, which you find at the end of its commit message.
+Once you have everything covered in your report, it is wise to optimize the
+most important section: The first few sentences.
-**Security issues**: for these issues your will have to evaluate if a
-short-term risk to other users would arise if details were publicly disclosed.
-If that's not the case simply proceed with reporting the issue as described.
-For issues that bear such a risk you will need to adjust the reporting process
-slightly:
+If the report is long, it is usually a good idea to go to the top, add
+something like 'The detailed description:' before the part you just wrote, and
+insert two newlines at the top. Now write one normal length paragraph that
+describes the issue roughly. Leave out all boring details and focus on the
+crucial parts readers need to know to understand what this is all about.
+
+Whenever you have or do not have such a paragraph with a gist, ideally start the
+report with one sentence that explains quickly what the report is about.
+
+Now try to write an even shorter subject/title for the report.
- * If the MAINTAINERS file instructed you to report the issue by mail, do not
- CC any public mailing lists.
+Spending time on these things is time well spent, as a lot of people will only
+read the subject and maybe the first sentence or two before they decide if
+reading the rest is worth it for them.
+
+Now send or file the report like the :ref:`MAINTAINERS <maintainers>` file told
+you, unless it is one of those 'issues of high-priority' outlined earlier: In
+that case, please read the next subsection first before sending the report on
+its way.
+
+[:ref:`back to step-by-step guide <compile_repisbs>`]
+
+
+.. _submit_repiref:
+
+Submit the report
+-----------------
- * If you were supposed to file the issue in a bug tracker make sure to mark
- the ticket as 'private' or 'security issue'. If the bug tracker does not
- offer a way to keep reports private, forget about it and send your report as
- a private mail to the maintainers instead.
+ *Submit your report in the appropriate way, which depends on the outcome* [:ref:`... <submit_repisbs>`]
-In both cases make sure to also mail your report to the addresses the
-MAINTAINERS file lists in the section 'security contact'. Ideally directly CC
-them when sending the report by mail. If you filed it in a bug tracker, forward
-the report's text to these addresses; but on top of it put a small note where
-you mention that you filed it with a link to the ticket.
+The step-by-step guide covers all the important details already.
-See Documentation/process/security-bugs.rst for more information.
+[:ref:`back to step-by-step guide <submit_repisbs>`]
Duties after the report went out
--
2.51.0
^ permalink raw reply related
* [PATCH v1 29/30] docs: reporting-issues: separate steps for follow-up tasks
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Create three separate steps that cover things that are important for bug
reporters to keep an eye on after submitting the report.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 347 +++++++++---------
1 file changed, 175 insertions(+), 172 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index c147191a7d0987..d81d558c245953 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -372,12 +372,41 @@ following the others is usually in your own interest.
[:ref:`details <submit_repiref>`]
- * 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.
+.. _keeprolling_repisbs:
+
+* Wait for reactions and keep the ball rolling until you can accept the outcome
+ in one way or the other. Hence react publicly and in a timely manner to any
+ inquiries and requests for testing patches.
+
+ [:ref:`details <keeprolling_repiref>`]
+
+.. _retest_repisbs:
+
+* Retest at least every first release candidate (e.g., -rc1) of a new mainline
+ version released and report your findings in a reply to your report.
+
+ [:ref:`details <retest_repiref>`]
+
+.. _reminder_repisbs:
+
+* If things stall for more than three weeks, evaluate why. It can happen due to
+ good or bad reasons -- like an inadequate report or because you
+ missed a request for further details or testing. If it is unlikely to be
+ something like that, send a friendly inquiry as a reply-to-self, as it might
+ be a mundane reason like an over-eager spam filter or a developer being on
+ vacation.
+
+ [:ref:`details <reminder_repiref>`]
+
+.. _yourself_repisbs:
+
+* Be aware that nobody is obliged to help you, unless it is a recent regression,
+ a security issue, or an extremely severe problem. Hence, try to help yourself
+ if you don't receive any or only unsatisfying help.
+
+ [:ref:`details <yourself_repiref>`]
+
+.. _readysolved_repisubs:
Handling non-regressions only occurring in stable or longterm kernels
@@ -1327,193 +1356,167 @@ The step-by-step guide covers all the important details already.
[:ref:`back to step-by-step guide <submit_repisbs>`]
-Duties after the report went out
---------------------------------
+.. _keeprolling_repiref:
+
+Things to do after the report went out
+--------------------------------------
- *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.*
+ *Wait for reactions and keep the ball rolling until you can accept the outcome* [:ref:`... <keeprolling_repisbs>`]
-If your report was good and you are really lucky then one of the developers
-might immediately spot what's causing the issue; they then might write a patch
-to fix it, test it, and send it straight for integration in mainline while
-tagging it for later backport to stable and longterm kernels that need it. Then
-all you need to do is reply with a 'Thank you very much' and switch to a version
-with the fix once it gets released.
+If your report was good and you are lucky, some developers might immediately
+spot what is causing the issue. They then might provide a fix for you to test,
+which you should do in a timely manner; afterwards they then send it out for
+integration into the mainline kernel while tagging it for backporting to
+affected stable and longterm kernels if appropriate.
-But this ideal scenario rarely happens. That's why the job is only starting
-once you got the report out. What you'll have to do depends on the situations,
-but often it will be the things listed below. But before digging into the
-details, here are a few important things you need to keep in mind for this part
-of the process.
+But frequently it is a little less straightforward. That is why the job often
+is only starting once you send a report. What you'll have to do depends on the
+situation. Here are a few tips:
+**Check who you deal with**: Most of the time a
+developer for the particular area of code will respond. But as
+issues are usually reported in public, it could be anyone --
+including people that want to help but in the end send you off
+track. That is why it might be wise to run a quick search on `lore <https://lore.kernel.org/all/>`_
+to see who you are interacting with.
-General advice for further interactions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Inquiries for data**: Often you will be asked to test something or provide
+additional details. Try to supply the requested information soon, as you have
+the attention of someone willing to help and risk losing it the longer you
+wait; that outcome is even likely if you do not provide the information within
+a few business days.
-**Always reply in public**: When you filed the issue in a bug tracker, always
-reply there and do not contact any of the developers privately about it. For
-mailed reports always use the 'Reply-all' function when replying to any mails
-you receive. That includes mails with any additional data you might want to add
-to your report: go to your mail applications 'Sent' folder and use 'reply-all'
-on your mail with the report. This approach will make sure the public mailing
-list(s) and everyone else that gets involved over time stays in the loop; it
-also keeps the mail thread intact, which among others is really important for
-mailing lists to group all related mails together.
+**Always reply in public!** When you submitted the issue in a bug tracker,
+always reply there and do not contact any of the developers privately; for
+mailed reports, always use the 'Reply-all' function when replying to any emails
+you receive. That includes emails with any additional data you might want to add
+to your report: Go to your email application's 'Sent' folder and use 'reply-all'
+on your email with the report. This approach will make sure the public mailing
+lists and everyone else who becomes involved later can access everything; it
+also keeps the email thread intact, which, among others, is really important for
+others that later run into the same problem and check the thread for a solution.
There are just two situations where a comment in a bug tracker or a 'Reply-all'
is unsuitable:
- * Someone tells you to send something privately.
+* Someone tells you to send something privately.
+
+* You were told to supply something containing
+ information that should not be exposed to the public. In that case, it is okay
+ to send it in private to the person who asked for it. But note in the ticket
+ or an email that you did so to keep the public record straight.
- * You were told to send something, but noticed it contains sensitive
- information that needs to be kept private. In that case it's okay to send it
- in private to the developer that asked for it. But note in the ticket or a
- mail that you did that, so everyone else knows you honored the request.
+**Requests for testing**: When you are asked to test a diagnostic patch or a
+possible fix, try to test it in a timely manner, too. But do it thoroughly and
+do not rush it: Mixing things up can happen easily and leads to a lot of
+confusion. A common mistake, for example, is thinking a proposed fix was applied
+when building a test kernel, when in fact it was not.
-**Do research before asking for clarifications or help**: In this part of the
+**Try to help yourself** before asking for help: During this part of the
process someone might tell you to do something that requires a skill you might
not have mastered yet. For example, you might be asked to use some test tools
-you never have heard of yet; or you might be asked to apply a patch to the
-Linux kernel sources to test if it helps. In some cases it will be fine sending
-a reply asking for instructions how to do that. But before going that route try
-to find the answer own your own by searching the internet; alternatively
-consider asking in other places for advice. For example ask a friend or post
-about it to a chatroom or forum you normally hang out.
-
-**Be patient**: If you are really lucky you might get a reply to your report
-within a few hours. But most of the time it will take longer, as maintainers
-are scattered around the globe and thus might be in a different time zone – one
-where they already enjoy their night away from keyboard.
-
-In general, kernel developers will take one to five business days to respond to
-reports. Sometimes it will take longer, as they might be busy with the merge
-windows, other work, visiting developer conferences, or simply enjoying a long
-summer holiday.
-
-The 'issues of high priority' (see above for an explanation) are an exception
-here: maintainers should address them as soon as possible; that's why you
-should wait a week at maximum (or just two days if it's something urgent)
-before sending a friendly reminder.
-
-Sometimes the maintainer might not be responding in a timely manner; other
-times there might be disagreements, for example if an issue qualifies as
-regression or not. In such cases raise your concerns on the mailing list and
-ask others for public or private replies how to move on. If that fails, it
-might be appropriate to get a higher authority involved. In case of a WiFi
-driver that would be the wireless maintainers; if there are no higher level
-maintainers or all else fails, it might be one of those rare situations where
-it's okay to get Linus Torvalds involved.
-
-**Proactive testing**: Every time the first pre-release (the 'rc1') of a new
-mainline kernel version gets released, go and check if the issue is fixed there
-or if anything of importance changed. Mention the outcome in the ticket or in a
-mail you sent as reply to your report (make sure it has all those in the CC
-that up to that point participated in the discussion). This will show your
-commitment and that you are willing to help. It also tells developers if the
-issue persists and makes sure they do not forget about it. A few other
-occasional retests (for example with rc3, rc5 and the final) are also a good
-idea, but only report your results if something relevant changed or if you are
-writing something anyway.
-
-With all these general things off the table let's get into the details of how
-to help to get issues resolved once they were reported.
-
-Inquires and testing request
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Here are your duties in case you got replies to your report:
-
-**Check who you deal with**: Most of the time it will be the maintainer or a
-developer of the particular code area that will respond to your report. But as
-issues are normally reported in public it could be anyone that's replying —
-including people that want to help, but in the end might guide you totally off
-track with their questions or requests. That rarely happens, but it's one of
-many reasons why it's wise to quickly run an internet search to see who you're
-interacting with. By doing this you also get aware if your report was heard by
-the right people, as a reminder to the maintainer (see below) might be in order
-later if discussion fades out without leading to a satisfying solution for the
-issue.
+you have never heard of yet; or you are asked to apply a patch to the
+Linux kernel sources to test. It usually will be fine replying asking for
+instructions on how to do that. But before going that route, try to find the
+answer on your own by searching the internet; alternatively,
+consider asking elsewhere for advice. For example, ask a friend or post
+your question to a chat room or forum you normally hang out in.
-**Inquiries for data**: Often you will be asked to test something or provide
-additional details. Try to provide the requested information soon, as you have
-the attention of someone that might help and risk losing it the longer you
-wait; that outcome is even likely if you do not provide the information within
-a few business days.
+**Be patient**: If you are really lucky, you might receive a reply to your
+report within a few hours. But most of the time it will take longer, as
+maintainers might be in a different time zone -- one where people currently
+take a few days off or already enjoy their night away from the keyboard. They
+might also simply be busy with other work, on a trip to a conference, or simply
+enjoying a long holiday.
-**Requests for testing**: When you are asked to test a diagnostic patch or a
-possible fix, try to test it in timely manner, too. But do it properly and make
-sure to not rush it: mixing things up can happen easily and can lead to a lot
-of confusion for everyone involved. A common mistake for example is thinking a
-proposed patch with a fix was applied, but in fact wasn't. Things like that
-happen even to experienced testers occasionally, but they most of the time will
-notice when the kernel with the fix behaves just as one without it.
+[:ref:`back to step-by-step guide <keeprolling_repisbs>`]
+
+
+.. _retest_repiref:
+
+Regularly check if the bug is still present
+-------------------------------------------
+
+ *Retest at least every first release candidate (e.g., -rc1) of a new mainline
+ version released and* [:ref:`... <retest_repisbs>`]
+
+Every time the first pre-release of a new mainline kernel version is released
+(the 'rc1'), go and check if the issue is fixed there or if anything of
+importance has changed. Mention the outcome in the ticket or in a mailed reply
+to your report (make sure to CCs everyone that up to that point participated in
+the discussion). This will show your commitment. It also tells developers the
+issue persists and acts as an implicit reminder.
+
+An occasional retest at another time (for example, with -rc4 or -rc7) is also
+wise, but only report your results if something relevant changed or if you are
+writing anyway.
+
+[:ref:`back to step-by-step guide <retest_repisbs>`]
+
+
+.. _reminder_repiref:
What to do when nothing of substance happens
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Some reports will not get any reaction from the responsible Linux kernel
-developers; or a discussion around the issue evolved, but faded out with
-nothing of substance coming out of it.
-
-In these cases wait two (better: three) weeks before sending a friendly
-reminder: maybe the maintainer was just away from keyboard for a while when
-your report arrived or had something more important to take care of. When
-writing the reminder, kindly ask if anything else from your side is needed to
-get the ball running somehow. If the report got out by mail, do that in the
-first lines of a mail that is a reply to your initial mail (see above) which
-includes a full quote of the original report below: that's on of those few
-situations where such a 'TOFU' (Text Over, Fullquote Under) is the right
-approach, as then all the recipients will have the details at hand immediately
-in the proper order.
-
-After the reminder wait three more weeks for replies. If you still don't get a
-proper reaction, you first should reconsider your approach. Did you maybe try
-to reach out to the wrong people? Was the report maybe offensive or so
-confusing that people decided to completely stay away from it? The best way to
-rule out such factors: show the report to one or two people familiar with FLOSS
-issue reporting and ask for their opinion. Also ask them for their advice how
-to move forward. That might mean: prepare a better report and make those people
-review it before you send it out. Such an approach is totally fine; just
+--------------------------------------------
+
+ *If things stall for more than two to three weeks, evaluate why. It can
+ happen due to good or bad reasons, like* [:ref:`... <reminder_repisbs>`]
+
+Sometimes you will not receive any reaction from the responsible
+developers; or a discussion around the issue evolves but ends fruitlessly.
+
+In these cases, wait two to three weeks before sending a friendly
+reminder: Maybe the right developers were just away from their keyboards when
+you sent your report or had something more important to take care of.
+
+When writing the reminder, kindly ask if there was anything wrong with the
+report or if anything from your side is needed to get the ball rolling. If the
+report was submitted by email, send a reply inserting your query after quoting
+the intro while including a full quote of the original report below: Then all
+the recipients will have both the gist of the problem and the details at hand
+immediately in convenient order.
+
+After sending a reminder, wait three more weeks for replies. If you still don't
+receive a proper reaction, reconsider your approach. Did you maybe try
+to reach out to the wrong people? Was the report possibly offensive or so
+confusing that people decided to stay away from it?
+
+The best way to
+rule out such factors: Show the report to one or two people familiar with FLOSS
+issue reporting and ask for their opinion. Also ask them for their advice on how
+to move forward. That might mean preparing a better report and making those
+people review it before sending it out. Such an approach is totally fine; just
mention that this is the second and improved report on the issue and include a
link to the first report.
-If the report was proper you can send a second reminder; in it ask for advice
-why the report did not get any replies. A good moment for this second reminder
-mail is shortly after the first pre-release (the 'rc1') of a new Linux kernel
-version got published, as you should retest and provide a status update at that
-point anyway (see above).
-
-If the second reminder again results in no reaction within a week, try to
-contact a higher-level maintainer asking for advice: even busy maintainers by
-then should at least have sent some kind of acknowledgment.
-
-Remember to prepare yourself for a disappointment: maintainers ideally should
-react somehow to every issue report, but they are only obliged to fix those
-'issues of high priority' outlined earlier. So don't be too devastating if you
-get a reply along the lines of 'thanks for the report, I have more important
-issues to deal with currently and won't have time to look into this for the
-foreseeable future'.
-
-It's also possible that after some discussion in the bug tracker or on a list
-nothing happens anymore and reminders don't help to motivate anyone to work out
-a fix. Such situations can be devastating, but is within the cards when it
-comes to Linux kernel development. This and several other reasons for not
-getting help are explained in 'Why some issues won't get any reaction or remain
-unfixed after being reported' near the end of this document.
-
-Don't get devastated if you don't find any help or if the issue in the end does
-not get solved: the Linux kernel is FLOSS and thus you can still help yourself.
-You for example could try to find others that are affected and team up with
-them to get the issue resolved. Such a team could prepare a fresh report
-together that mentions how many you are and why this is something that in your
-option should get fixed. Maybe together you can also narrow down the root cause
-or the change that introduced a regression, which often makes developing a fix
-easier. And with a bit of luck there might be someone in the team that knows a
-bit about programming and might be able to write a fix.
+If the report was proper, you can send a second reminder; in it, ask for advice
+on why the report did not receive any replies. An ideal moment for this is
+shortly after retesting with the first pre-release of a new mainline release
+(the 'rc1'), as you should retest and provide a status update at that point
+anyway (see above).
+
+[:ref:`back to step-by-step guide <reminder_repisbs>`]
+
+
+.. _yourself_repiref:
+
+In most cases nobody is obliged to help
+---------------------------------------
+
+*Be aware that nobody is obliged to help you, unless it is* [:ref:`... <yourself_repisbs>`]
+
+Developers ideally should react somehow to every issue report, but sometimes do
+not reply or, in the end, do not address problems. This is due to reasons
+[:ref:`Why some bugs remain unfixed and some reports are ignored <unfixedbugs_repiapdx>`]
+explains in more detail, which also explains why some code does not even have
+maintainers.
+
+Try to help yourself in that case.
+You, for example, could team up with others affected to then create a better
+report or narrow down the root cause of a problem. With a bit of luck, someone
+on the team might even know a bit about programming and provide a fix.
+
+[:ref:`back to step-by-step guide <yourself_repisbs>`]
Appendix: additional background information
--
2.51.0
^ permalink raw reply related
* [PATCH v1 16/30] docs: reporting-issues: add fast-track for regressions
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Some regressions are reported multiple times within a short time frame,
so it's worth asking on the regressions mailing list: subscribers might
already known about them and might safe the reporter a lot of trouble,
as reporting it again is unlikely to do much of a difference.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 29 +++++++++++++++++++
1 file changed, 29 insertions(+)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index be0e49046ec913..f040ca7c0a2f59 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -136,6 +136,19 @@ following the others is usually in your own interest.
[:ref:`details <specialtreat_repiref>`]
+.. _reginquiry_repisbs:
+
+* Do you face a regression? One still occurring in a kernel version less than
+ two (ideally: one) weeks old? A kernel that is vanilla or close to it? If
+ you answered all three questions with 'yes', feel free to send a brief email
+ to the public 'Linux regressions mailing list <regressions@lists.linux.dev>'
+ asking if the problem is known. If someone confirms this to be the case,
+ there most likely is no need to follow this guide further; but do so in case
+ there is no reply with a pointer to a matching report within two or three
+ weekdays. You are also free to immediately continue if you feel like it.
+
+ [:ref:`details <reginquiry_repiref>`]
+
* Create a fresh backup and put system repair and restore tools at hand.
* Ensure your system does not enhance its kernels by building additional
@@ -676,6 +689,22 @@ development process:
[:ref:`back to step-by-step guide <specialtreat_repisbs>`]
+.. _reginquiry_repiref:
+
+Fast track for regressions
+--------------------------
+
+ *Do you face a regression? One still occurring in a kernel version less than
+ two (ideally: one) weeks old? A kernel that is vanilla or close to it? If you
+ answered* [:ref:`... <reginquiry_repisbs>`]
+
+This is an optional fast track that might relieve you from further work on
+reporting in case the issue is already known. Note: It are volunteers that
+answer these emails on a best-effort basis.
+
+[:ref:`back to step-by-step guide <reginquiry_repisbs>`]
+
+
Prepare for emergencies
-----------------------
--
2.51.0
^ permalink raw reply related
* [PATCH v1 15/30] docs: reporting-issues: improve text on classifying the bug
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Fine-tune the instructions about classifying the bug.
This drops support for "really severe problems", this is a rare special
case not woth spending much thought on.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 62 +++++++++----------
1 file changed, 29 insertions(+), 33 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 623feb55caae97..be0e49046ec913 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -128,10 +128,13 @@ following the others is usually in your own interest.
[:ref:`details <checkloreone_repiref>`]
+.. _specialtreat_repisbs:
- * 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.
+* Evaluate if the issue you are dealing with qualifies as a regression or
+ security issue, as those receive special treatment in some of the following
+ steps.
+
+ [:ref:`details <specialtreat_repiref>`]
* Create a fresh backup and put system repair and restore tools at hand.
@@ -647,37 +650,30 @@ While doing so, keep in mind:
[:ref:`back to step-by-step guide <checkloreone_repisbs>`]
-Issue of high priority?
------------------------
+.. _specialtreat_repiref:
+
+Issues receiving special treatment
+----------------------------------
+
+ *Evaluate if the issue you are dealing with qualifies as a regression or
+ security issue, as those* [:ref:`... <specialtreat_repisbs>`]
+
+Check if you face an issue that receives special treatment in the Linux
+development process:
+
+* You deal with a regression, if some application or practical use case running
+ fine with one Linux kernel version works worse or not at all with a newer
+ version compiled using a similar configuration; the 'no regression' rule
+ forbids that. The document
+ Documentation/admin-guide/reporting-regressions.rst explains these and
+ additional aspects in more detail, but everything important is covered in
+ this document.
+
+* What qualifies as a security issue is left to your judgment. Consider reading
+ Documentation/process/security-bugs.rst before proceeding, which
+ provides instructions on handling security issues.
- *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.*
-
-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.
-
-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.
-
-What 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.
-
-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.
+[:ref:`back to step-by-step guide <specialtreat_repisbs>`]
Prepare for emergencies
--
2.51.0
^ permalink raw reply related
* [PATCH v1 30/30] docs: reporting-issues: fix a few line breaks
From: Thorsten Leemhuis @ 2025-10-26 12:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Rewrap a few paragraphs that have odd line breaks to keep the diff
clearer in preceding changes. Apart from that no text changes.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 230 +++++++++---------
1 file changed, 111 insertions(+), 119 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index d81d558c245953..3b1519fe80511f 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -615,29 +615,29 @@ Check 'taint' flag
*Check if the kernel was already 'tainted' when the issue first occurred* [:ref:`... <taintone_repisbs>`]
The kernel marks itself with a 'taint' flag when something happens that might
-lead to follow-up errors looking totally unrelated. Your issue might
-be such an error, in which case there is nothing to report. That is why it is
-in your interest to check the taint status early in the reporting process. This
-is the main reason why this step is here in the guide, as you most likely will
-have to install a different kernel for reporting later -- and then need to
-recheck the flag, as that is when it matters.
+lead to follow-up errors looking totally unrelated. Your issue might be such an
+error, in which case there is nothing to report. That is why it is in your
+interest to check the taint status early in the reporting process. This is the
+main reason why this step is here in the guide, as you most likely will have to
+install a different kernel for reporting later -- and then need to recheck the
+flag, as that is when it matters.
To check the tainted flag, execute ``cat /proc/sys/kernel/tainted``: If it
returns '0' everything is fine; if it contains a higher number, it is tainted.
-In some situations it is impossible to check that file. That is
-why the kernel also mentions the taint status when it reports small (a
-'warning' or a 'bug') or big (an 'Oops' or a 'panic') problems. In such cases,
-search for a line starting with 'CPU:' near the top of the error messages
-printed on the screen or in the log. If the kernel at that point considered
-itself to be fine, it will end with 'Not tainted'; if not, you will see
-'Tainted:' followed by a few spaces and some letters.
+In some situations it is impossible to check that file. That is why the kernel
+also mentions the taint status when it reports small (a 'warning' or a 'bug') or
+big (an 'Oops' or a 'panic') problems. In such cases, search for a line starting
+with 'CPU:' near the top of the error messages printed on the screen or in the
+log. If the kernel at that point considered itself to be fine, it will end with
+'Not tainted'; if not, you will see 'Tainted:' followed by a few spaces and some
+letters.
If your kernel is tainted, check Documentation/admin-guide/tainted-kernels.rst
-to find out why. Note: It is quite possible that the problem you ran into
-caused the kernel to taint itself, in which case you are free to ignore the
-flag. But if the kernel was tainted beforehand, you might have to eliminate the
-cause or rule out that it is an influence.
+to find out why. Note: It is quite possible that the problem you ran into caused
+the kernel to taint itself, in which case you are free to ignore the flag. But
+if the kernel was tainted beforehand, you might have to eliminate the cause or
+rule out that it is an influence.
These are the most frequent reasons why the kernel set the flag:
@@ -649,18 +649,17 @@ These are the most frequent reasons why the kernel set the flag:
Oops: 0000 [#1] SMP
That is the first Oops since boot-up, as the '#1' between the brackets shows.
- Every later Oops and any other problem that happens afterwards might be
- a follow-up issue
- that would never have happened otherwise, even if both look totally unrelated.
- Rule this out by eliminating the cause for the first Oops and reproducing
- the issue afterwards. Sometimes simply restarting will be enough; other times
- a change to the configuration followed by a reboot can eliminate the Oops.
+ Every later Oops and any other problem that happens afterwards might be a
+ follow-up issue that would never have happened otherwise, even if both look
+ totally unrelated. Rule this out by eliminating the cause for the first Oops
+ and reproducing the issue afterwards. Sometimes simply restarting will be
+ enough; other times a change to the configuration followed by a reboot can
+ eliminate the Oops.
Note: Do not invest too much time into this while you are still on an
- outdated or vendor kernel: The cause for the Oops might already be fixed in
- a newer Linux kernel
- version you most likely will have to install for reporting while following
- this guide.
+ outdated or vendor kernel: The cause for the Oops might already be fixed in a
+ newer Linux kernel version you most likely will have to install for reporting
+ while following this guide.
2. Your system uses software that installs externally developed kernel modules,
for example, kernel modules from Nvidia, OpenZFS, VirtualBox, or VMware. The
@@ -838,10 +837,9 @@ development process:
* You deal with a regression, if some application or practical use case running
fine with one Linux kernel version works worse or not at all with a newer
version compiled using a similar configuration; the 'no regression' rule
- forbids that. The document
- Documentation/admin-guide/reporting-regressions.rst explains these and
- additional aspects in more detail, but everything important is covered in
- this document.
+ forbids that. The document Documentation/admin-guide/reporting-regressions.rst
+ explains these and additional aspects in more detail, but everything important
+ is covered in this document.
* What qualifies as a security issue is left to your judgment. Consider reading
Documentation/process/security-bugs.rst before proceeding, which
@@ -892,12 +890,10 @@ How to read the MAINTAINERS file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, let's assume
-the WiFi in your Laptop misbehaves. In that
-case it is likely an issue in the WiFi driver. Obviously it could also be some
-underlying code from other subsystems, but unless something hints at that,
-stick to the driver; if it is really something else, the driver's developers
-will involve the
-right people.
+the WiFi in your Laptop misbehaves. In that case it is likely an issue in the
+WiFi driver. Obviously it could also be some underlying code from other
+subsystems, but unless something hints at that, stick to the driver; if it is
+really something else, the driver's developers will involve the right people.
Sadly, there is no way to check which code is driving a particular hardware
component that is both universal and easy.
@@ -953,9 +949,8 @@ only has someone who provides 'Odd Fixes' when feeling motivated. And with
That only leaves these options: Arrange yourself to live with the issue, fix it
yourself, or find a programmer somewhere willing to fix it.
-After checking the status, look for a line starting with 'bugs:' ('B:'): It
-will tell you where to find a subsystem-specific bug tracker to file your
-issue. The
+After checking the status, look for a line starting with 'bugs:' ('B:'): 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 email: Very few subsystems use
a bug tracker, and only some of those rely on bugzilla.kernel.org.
@@ -1158,9 +1153,9 @@ addresses that allow pinpointing the exact path to the line in your kernel's
source code that triggered the issue. Many bugs can be resolved without
decoding these addresses, but for some it is helpful or required.
-That is why it is fine to report problems without bothering about this, but
-when asked for this, try to decode the stack trace. Note: This requires a
-kernel build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled.
+That is why it is fine to report problems without bothering about this, but when
+asked for this, try to decode the stack trace. Note: This requires a kernel
+build with CONFIG_DEBUG_INFO and CONFIG_KALLSYMS enabled.
Usually you want to decode using a script shipped in the Linux sources. If you
are running a kernel you compiled yourself, call it like this::
@@ -1187,10 +1182,10 @@ In this case the executed code was built from the file
'~/linux-5.10.5/test-module/test-module.c' and the error occurred during the
instructions found in line '16'.
-The script will similarly decode the addresses mentioned in the section
-starting with 'Call trace', which shows the path to the function where the
-problem occurred. The script, furthermore, will show the assembler output for
-the code section the kernel was executing at that time.
+The script will similarly decode the addresses mentioned in the section starting
+with 'Call trace', which shows the path to the function where the problem
+occurred. The script, furthermore, will show the assembler output for the code
+section the kernel was executing at that time.
[:ref:`back to step-by-step guide <attachments_repisbs>`]
@@ -1202,10 +1197,10 @@ Prepare and optimize the report
*Prepare and optimize the report.* [:ref:`... <compile_repisbs>`]
-Most developers just take a few seconds to skim a report before deciding
-between taking a closer look or moving on, as they receive a ton of messages.
-That is why the title/subject, the first sentence, and the three or four
-following it are crucial.
+Most developers just take a few seconds to skim a report before deciding between
+taking a closer look or moving on, as they receive a ton of messages. That is
+why the title/subject, the first sentence, and the three or four following it
+are crucial.
People will also stop reading if the report's text is long or hard to follow;
the same is true if crucial information is not at hand. So be sure to describe
@@ -1373,12 +1368,11 @@ But frequently it is a little less straightforward. That is why the job often
is only starting once you send a report. What you'll have to do depends on the
situation. Here are a few tips:
-**Check who you deal with**: Most of the time a
-developer for the particular area of code will respond. But as
-issues are usually reported in public, it could be anyone --
-including people that want to help but in the end send you off
-track. That is why it might be wise to run a quick search on `lore <https://lore.kernel.org/all/>`_
-to see who you are interacting with.
+**Check who you deal with**: Most of the time a developer for the particular
+area of code will respond. But as issues are usually reported in public, it
+could be anyone -- including people that want to help but in the end send you
+off track. That is why it might be wise to run a quick search on `lore
+<https://lore.kernel.org/all/>`_ to see who you are interacting with.
**Inquiries for data**: Often you will be asked to test something or provide
additional details. Try to supply the requested information soon, as you have
@@ -1412,21 +1406,21 @@ do not rush it: Mixing things up can happen easily and leads to a lot of
confusion. A common mistake, for example, is thinking a proposed fix was applied
when building a test kernel, when in fact it was not.
-**Try to help yourself** before asking for help: During this part of the
-process someone might tell you to do something that requires a skill you might
-not have mastered yet. For example, you might be asked to use some test tools
-you have never heard of yet; or you are asked to apply a patch to the
-Linux kernel sources to test. It usually will be fine replying asking for
-instructions on how to do that. But before going that route, try to find the
-answer on your own by searching the internet; alternatively,
-consider asking elsewhere for advice. For example, ask a friend or post
-your question to a chat room or forum you normally hang out in.
+**Try to help yourself** before asking for help: During this part of the process
+someone might tell you to do something that requires a skill you might not have
+mastered yet. For example, you might be asked to use some test tools you have
+never heard of yet; or you are asked to apply a patch to the Linux kernel
+sources to test. It usually will be fine replying asking for instructions on how
+to do that. But before going that route, try to find the answer on your own by
+searching the internet; alternatively, consider asking elsewhere for advice. For
+example, ask a friend or post your question to a chat room or forum you normally
+hang out in.
**Be patient**: If you are really lucky, you might receive a reply to your
report within a few hours. But most of the time it will take longer, as
-maintainers might be in a different time zone -- one where people currently
-take a few days off or already enjoy their night away from the keyboard. They
-might also simply be busy with other work, on a trip to a conference, or simply
+maintainers might be in a different time zone -- one where people currently take
+a few days off or already enjoy their night away from the keyboard. They might
+also simply be busy with other work, on a trip to a conference, or simply
enjoying a long holiday.
[:ref:`back to step-by-step guide <keeprolling_repisbs>`]
@@ -1462,12 +1456,12 @@ What to do when nothing of substance happens
*If things stall for more than two to three weeks, evaluate why. It can
happen due to good or bad reasons, like* [:ref:`... <reminder_repisbs>`]
-Sometimes you will not receive any reaction from the responsible
-developers; or a discussion around the issue evolves but ends fruitlessly.
+Sometimes you will not receive any reaction from the responsible developers; or
+a discussion around the issue evolves but ends fruitlessly.
-In these cases, wait two to three weeks before sending a friendly
-reminder: Maybe the right developers were just away from their keyboards when
-you sent your report or had something more important to take care of.
+In these cases, wait two to three weeks before sending a friendly reminder:
+Maybe the right developers were just away from their keyboards when you sent
+your report or had something more important to take care of.
When writing the reminder, kindly ask if there was anything wrong with the
report or if anything from your side is needed to get the ball rolling. If the
@@ -1477,17 +1471,16 @@ the recipients will have both the gist of the problem and the details at hand
immediately in convenient order.
After sending a reminder, wait three more weeks for replies. If you still don't
-receive a proper reaction, reconsider your approach. Did you maybe try
-to reach out to the wrong people? Was the report possibly offensive or so
-confusing that people decided to stay away from it?
-
-The best way to
-rule out such factors: Show the report to one or two people familiar with FLOSS
-issue reporting and ask for their opinion. Also ask them for their advice on how
-to move forward. That might mean preparing a better report and making those
-people review it before sending it out. Such an approach is totally fine; just
-mention that this is the second and improved report on the issue and include a
-link to the first report.
+receive a proper reaction, reconsider your approach. Did you maybe try to reach
+out to the wrong people? Was the report possibly offensive or so confusing that
+people decided to stay away from it?
+
+The best way to rule out such factors: Show the report to one or two people
+familiar with FLOSS issue reporting and ask for their opinion. Also ask them for
+their advice on how to move forward. That might mean preparing a better report
+and making those people review it before sending it out. Such an approach is
+totally fine; just mention that this is the second and improved report on the
+issue and include a link to the first report.
If the report was proper, you can send a second reminder; in it, ask for advice
on why the report did not receive any replies. An ideal moment for this is
@@ -1507,14 +1500,14 @@ In most cases nobody is obliged to help
Developers ideally should react somehow to every issue report, but sometimes do
not reply or, in the end, do not address problems. This is due to reasons
-[:ref:`Why some bugs remain unfixed and some reports are ignored <unfixedbugs_repiapdx>`]
-explains in more detail, which also explains why some code does not even have
-maintainers.
+[:ref:`Why some bugs remain unfixed and some reports are ignored
+<unfixedbugs_repiapdx>`] explains in more detail, which also explains why some
+code does not even have maintainers.
-Try to help yourself in that case.
-You, for example, could team up with others affected to then create a better
-report or narrow down the root cause of a problem. With a bit of luck, someone
-on the team might even know a bit about programming and provide a fix.
+Try to help yourself in that case. You, for example, could team up with others
+affected to then create a better report or narrow down the root cause of a
+problem. With a bit of luck, someone on the team might even know a bit about
+programming and provide a fix.
[:ref:`back to step-by-step guide <yourself_repisbs>`]
@@ -1548,35 +1541,34 @@ test. The former can happen when the publicly available docs are superficial or
when a driver was written with the help of reverse engineering.
Sooner or later, spare-time developers usually stop caring for the driver.
-Maybe their test hardware broke, was replaced by something more fancy, or
-became so old that it is something you don't find much outside of computer
-museums anymore. Other times developers also stop caring when
-something different in life becomes more important to them. Then sometimes
-nobody is willing to take over the job as maintainer -- and nobody else can be
-forced to, as contributing is voluntary. The code nevertheless often stays
-around, as it is useful for people; removing it would also cause a regression,
-which is not allowed in Linux.
-
-The situation is not that different with developers that are paid for their
-work on the upstream Linux kernel. Those contribute the most changes these days.
-But their employers set the priorities. And those sooner or later stop caring
-for some code or make their
-employees focus on other things. Hardware vendors, for example, earn their money
-mainly by selling new hardware -- they thus often are not much interested in
-investing much time and energy in maintaining a Linux kernel driver for a chip
-they stopped selling years ago. Enterprise Linux distributors often care for a
-longer time period, but in new versions might set support for old and rare
-hardware aside to limit the scope, too. Often spare-time contributors take over
-once employed developers orphan some code, but as mentioned earlier: Sooner or
-later they will usually leave the code behind, too.
-
-Priorities are another reason why some issues are not fixed, as developers
-quite often are forced to set those: The spare-time of volunteers or the time
+Maybe their test hardware broke, was replaced by something more fancy, or became
+so old that it is something you don't find much outside of computer museums
+anymore. Other times developers also stop caring when something different in
+life becomes more important to them. Then sometimes nobody is willing to take
+over the job as maintainer -- and nobody else can be forced to, as contributing
+is voluntary. The code nevertheless often stays around, as it is useful for
+people; removing it would also cause a regression, which is not allowed in
+Linux.
+
+The situation is not that different with developers that are paid for their work
+on the upstream Linux kernel. Those contribute the most changes these days. But
+their employers set the priorities. And those sooner or later stop caring for
+some code or make their employees focus on other things. Hardware vendors, for
+example, earn their money mainly by selling new hardware -- they thus often are
+not much interested in investing much time and energy in maintaining a Linux
+kernel driver for a chip they stopped selling years ago. Enterprise Linux
+distributors often care for a longer time period, but in new versions might set
+support for old and rare hardware aside to limit the scope, too. Often
+spare-time contributors take over once employed developers orphan some code, but
+as mentioned earlier: Sooner or later they will usually leave the code behind,
+too.
+
+Priorities are another reason why some issues are not fixed, as developers quite
+often are forced to set those: The spare-time of volunteers or the time
employers allot for upstream Linux kernel work is often limited. Sometimes
developers are also flooded with good and bad reports, even if a driver is
-working well. To
-not get completely stuck, the programmers might have no other choice than
-to prioritize bug reports and ignore some.
+working well. To not get completely stuck, the programmers might have no other
+choice than to prioritize bug reports and ignore some.
But do not worry too much about all of this, a lot of drivers have active
maintainers who are quite interested in fixing as many issues as possible.
--
2.51.0
^ permalink raw reply related
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: Dan Carpenter @ 2025-10-27 5:27 UTC (permalink / raw)
To: ally heev
Cc: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft, workflows, linux-doc, linux-kernel, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <81e6af8eea5b0399d1685797d0ea6a6ebc273270.camel@gmail.com>
On Sat, Oct 25, 2025 at 11:53:56AM +0530, ally heev wrote:
> On Fri, 2025-10-24 at 21:08 +0300, Dan Carpenter wrote:
> > On Fri, Oct 24, 2025 at 10:59:16PM +0530, Ally Heev wrote:
> > > pointers with __free attribute initialized to NULL
> > > pose potential cleanup issues [1] when a function uses
> > > interdependent variables with cleanup attributes
> > >
> > > Link: https://docs.kernel.org/core-api/cleanup.html [1]
> > > Link: https://lore.kernel.org/all/68f7b830ec21a_10e910070@dwillia2-mobl4.notmuch/
> > > Suggested-by: Dan Williams <dan.j.williams@intel.com>
> > > Signed-off-by: Ally Heev <allyheev@gmail.com>
> > > ---
> >
> > I don't think this patch is a good idea... There are two issues to
> > consider 1) The absolute number over warnings. 500+ is too high.
> > 2) The ratio of bugs to false positives and we don't have any data on
> > that but I bet it's low. It needs to be at least 5%. For anything
> > lower than that, you're better off just reviewing code at random
> > instead of looking through warnings.
> >
> > regards,
> > dan carpenter
>
> makes sense
>
> General question about the process for my understanding:
> Is checkpatch run on full tree by CI or someone and results reported
> regularly ?
Newbies run it regularly. Otherwise it gets run on subsystem CIs and
the zero-day bot runs it on new patches but it will report the old
warnings as well under the "Old warnings" section.
> My understanding was that we would run it only on patches
> before submitting them Or we just run it on full tree before adding
> new checks to understand if they are catching real issues
Eventually someone will look at all the warnings. And probably it's
going to be a newbie and so we need to be careful with warning where
newbies might introduce bugs with their changes.
regards,
dan carpenter
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: ally heev @ 2025-10-27 8:34 UTC (permalink / raw)
To: Dan Carpenter
Cc: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft, workflows, linux-doc, linux-kernel, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <aP8CxkXYAitKB3vx@stanley.mountain>
On Mon, Oct 27, 2025 at 10:57 AM Dan Carpenter <dan.carpenter@linaro.org> wrote:
> > General question about the process for my understanding:
> > Is checkpatch run on full tree by CI or someone and results reported
> > regularly ?
>
> Newbies run it regularly. Otherwise it gets run on subsystem CIs and
> the zero-day bot runs it on new patches but it will report the old
> warnings as well under the "Old warnings" section.
>
> > My understanding was that we would run it only on patches
> > before submitting them Or we just run it on full tree before adding
> > new checks to understand if they are catching real issues
>
> Eventually someone will look at all the warnings. And probably it's
> going to be a newbie and so we need to be careful with warning where
> newbies might introduce bugs with their changes.
>
> regards,
> dan carpenter
>
Makes sense. Thanks!!
---
aheev
^ permalink raw reply
* Re: [PATCH 21/21] Docs: add Functions parameters order section
From: Jani Nikula @ 2025-10-27 9:02 UTC (permalink / raw)
To: Yury Norov (NVIDIA), Linus Walleij, Lee Jones, linux-arm-kernel,
linux-kernel, Jonathan Corbet, workflows, linux-doc
Cc: Yury Norov (NVIDIA)
In-Reply-To: <20251025163305.306787-14-yury.norov@gmail.com>
On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" <yury.norov@gmail.com> wrote:
> Standardize parameters ordering in some typical cases to minimize
> confusion.
>
> Signed-off-by: Yury Norov (NVIDIA) <yury.norov@gmail.com>
> ---
> Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++
> 1 file changed, 48 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index d1a8e5465ed9..dde24148305c 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -523,6 +523,54 @@ below, compared to the **declaration** example above)::
> ...
> }
>
> +6.2) Function parameters order
> +------------------------------
> +
> +The order of parameters is important both for code generation and readability.
> +Passing parameters in an unusual order is a common source of bugs. Listing
> +them in standard widely adopted order helps to avoid confusion.
> +
> +Many ABIs put first function parameter and return value in R0. If your
> +function returns one of its parameters, passing it at the very beginning
> +would lead to a better code generation. For example::
> +
> + void *memset64(uint64_t *s, uint64_t v, size_t count);
> + void *memcpy(void *dest, const void *src, size_t count);
> +
> +If your function doesn't propagate a parameter, but has a meaning of copying
> +and/or processing data, the best practice is following the traditional order:
> +destination, source, options, flags.
> +
> +for_each()-like iterators should take an enumerator the first. For example::
> +
> + for_each_set_bit(bit, mask, nbits);
> + do_something(bit);
> +
> + list_for_each_entry(pos, head, member);
> + do_something(pos);
> +
> +If function operates on a range or ranges of data, corresponding parameters
> +may be described as ``start - end`` or ``start - size`` pairs. In both cases,
> +the parameters should follow each other. For example::
> +
> + int
> + check_range(unsigned long vstart, unsigned long vend,
> + unsigned long kstart, unsigned long kend);
> +
> + static inline void flush_icache_range(unsigned long start, unsigned long end);
> +
> + static inline void flush_icache_user_page(struct vm_area_struct *vma,
> + struct page *page,
> + unsigned long addr, int len);
> +
> +Both ``start`` and ``end`` of the interval are inclusive.
> +
> +Describing intervals in order ``end - start`` is unfavorable. One notable
> +example is the ``GENMASK(high, low)`` macro. While such a notation is popular
> +in hardware context, particularly to describe registers structure, in context
> +of software development it looks counter intuitive and confusing. Please switch
> +to an equivalent ``BITS(low, high)`` version.
> +
GENMASK when used for defining hardware registers is completely fine,
and *much* easier to deal with when you cross check against the specs
that almost invariably define high:low.
Which other parts of coding style take on specific interfaces and tell
you to switch? Weird. I for one don't want to encourage an influx of
trivial patches doing GENMASK to BITS conversions, and then keep
rejecting them. It's just a huge collective waste of time.
Anyway, that's a lot of text on "function parameter order" to justify
BITS(), but completely skips more important principles such as "context
parameter first", or "destination first".
BR,
Jani.
> 7) Centralized exiting of functions
> -----------------------------------
--
Jani Nikula, Intel
^ permalink raw reply
* Re: [PATCH 21/21] Docs: add Functions parameters order section
From: Jeff Johnson @ 2025-10-27 16:08 UTC (permalink / raw)
To: Jani Nikula, Yury Norov (NVIDIA), Linus Walleij, Lee Jones,
linux-arm-kernel, linux-kernel, Jonathan Corbet, workflows,
linux-doc
In-Reply-To: <723c936f92352352c3b1a84b858d684f5b7a0834@intel.com>
On 10/27/2025 2:02 AM, Jani Nikula wrote:
> On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" <yury.norov@gmail.com> wrote:
>> Standardize parameters ordering in some typical cases to minimize
>> confusion.
>>
>> Signed-off-by: Yury Norov (NVIDIA) <yury.norov@gmail.com>
>> ---
>> Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++
>> 1 file changed, 48 insertions(+)
>>
>> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
>> index d1a8e5465ed9..dde24148305c 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -523,6 +523,54 @@ below, compared to the **declaration** example above)::
>> ...
>> }
>>
>> +6.2) Function parameters order
>> +------------------------------
>> +
>> +The order of parameters is important both for code generation and readability.
>> +Passing parameters in an unusual order is a common source of bugs. Listing
>> +them in standard widely adopted order helps to avoid confusion.
>> +
>> +Many ABIs put first function parameter and return value in R0. If your
>> +function returns one of its parameters, passing it at the very beginning
>> +would lead to a better code generation. For example::
>> +
>> + void *memset64(uint64_t *s, uint64_t v, size_t count);
>> + void *memcpy(void *dest, const void *src, size_t count);
>> +
>> +If your function doesn't propagate a parameter, but has a meaning of copying
>> +and/or processing data, the best practice is following the traditional order:
>> +destination, source, options, flags.
>> +
>> +for_each()-like iterators should take an enumerator the first. For example::
>> +
>> + for_each_set_bit(bit, mask, nbits);
>> + do_something(bit);
>> +
>> + list_for_each_entry(pos, head, member);
>> + do_something(pos);
>> +
>> +If function operates on a range or ranges of data, corresponding parameters
>> +may be described as ``start - end`` or ``start - size`` pairs. In both cases,
>> +the parameters should follow each other. For example::
>> +
>> + int
>> + check_range(unsigned long vstart, unsigned long vend,
>> + unsigned long kstart, unsigned long kend);
>> +
>> + static inline void flush_icache_range(unsigned long start, unsigned long end);
>> +
>> + static inline void flush_icache_user_page(struct vm_area_struct *vma,
>> + struct page *page,
>> + unsigned long addr, int len);
>> +
>> +Both ``start`` and ``end`` of the interval are inclusive.
>> +
>> +Describing intervals in order ``end - start`` is unfavorable. One notable
>> +example is the ``GENMASK(high, low)`` macro. While such a notation is popular
>> +in hardware context, particularly to describe registers structure, in context
>> +of software development it looks counter intuitive and confusing. Please switch
>> +to an equivalent ``BITS(low, high)`` version.
>> +
>
> GENMASK when used for defining hardware registers is completely fine,
> and *much* easier to deal with when you cross check against the specs
> that almost invariably define high:low.
Not only that, there is no common definition of BITS
Defined in 7 files as a macro:
arch/arc/include/asm/disasm.h, line 32 (as a macro)
drivers/mfd/db8500-prcmu-regs.h, line 15 (as a macro)
drivers/net/wireless/intel/iwlwifi/fw/api/coex.h, line 14 (as a macro)
fs/select.c, line 415 (as a macro)
lib/zlib_inflate/inflate.c, line 232 (as a macro)
sound/core/oss/rate.c, line 28 (as a macro)
tools/perf/dlfilters/dlfilter-show-cycles.c, line 22 (as a macro)
Most of these do NOT have a (low, high) signature.
And GENMASK will throw a compile error if you swap the high and low:
#define GENMASK_INPUT_CHECK(h, l) BUILD_BUG_ON_ZERO(const_true((l) > (h)))
IMO the real confusion with GENMASK(), which would be the same with the
proposed BITS(), is that without knowledge of the implementation, when looking
at an instance of usage you can't tell if the parameters are two bit numbers
or a start bit and number of bits.
/jeff
^ permalink raw reply
* Re: [PATCH v1 00/30] docs: reporting-issues: rework
From: Jonathan Corbet @ 2025-10-27 17:16 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> I worked on-and-off on this for maybe two years and the problem is:
> what started as fine tuning in various places piled up. That together
> with the newly added links & anchors and some text movements makes the
> patchset huge. When you ignore those two aspects and look at individual
> patches using a word diff algorithm it looks a lot less scary, but it
> remains big – and thus sadly puts some load on reviewers and
> translators. Sorry. I think it's worth it and tried to split things up
> to facilitate handling.
It is indeed a lot, it's going to be hard to get people (including me)
to look at it all. I think you should really consider breaking this
into smaller sets and getting them through one at a time...
I'll look at a few of these, but certainly won't get through the whole
set today.
Thanks,
jon
P.S. Grumbling aside, it's good to have you back...
^ permalink raw reply
* Re: [PATCH v1 01/30] docs: reporting-issues: mention text is best viewed rendered
From: Jonathan Corbet @ 2025-10-27 17:18 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <4f7e2de2a2336c52e55cc49dcda627a4e86b8793.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Add a comment before the step-by-step guide explaining that the document
> is best viewed in the rendered form, as there the internal links will
> work that later patches will add.
>
> While at it change the double quotes in the license hint at the end of
> the document into single quotes, which is the preferred style.
That is the classic marker of an independent change, of course. But
more significantly ... "preferred" by who? Double quotes are the normal
English style that folks like me learned many years ago...
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> Documentation/admin-guide/reporting-issues.rst | 18 ++++++++++++++----
> 1 file changed, 14 insertions(+), 4 deletions(-)
Otherwise seems OK.
jon
^ permalink raw reply
* Re: [PATCH v1 02/30] docs: reporting-issues: tweak the reference section intro
From: Jonathan Corbet @ 2025-10-27 17:27 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <d94aa32d4a1ed5ef9d0f768d05e64987f4a1ae69.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Small improvements to the intro of the reference section.
That's a bit uninformative ... what is the purpose of these
improvements? That information would be especially helpful in a patch
that simply replaces that section altogether.
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> .../admin-guide/reporting-issues.rst | 67 +++++++++----------
> 1 file changed, 31 insertions(+), 36 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 3bc47afaf85ea0..90b50c27c0d2b6 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -244,42 +244,37 @@ The reference section below explains each of these steps in more detail.
[...]
> +The step-by-step guide above outlines all the major steps in brief fashion,
> +which usually covers everything required. But even experienced users will
> +sometimes wonder how to actually realize some of those steps or why they are
> +needed; there are also corner cases the guide ignores for readability. That is
> +what the entries in this reference section are for, which provide additional
> +information for each of the steps in the detailed guide.
> +
> +A few words of general advice:
> +
> +* The Linux kernel developers are well aware that reporting bugs to them is
> + more complicated and demanding than in other FLOSS projects. Quite a few
> + would love to make it simpler. But that would require convincing a lot of
> + developers to change their habits; it, furthermore, would require improvements
> + on several technical fronts and people that constantly take care of various
> + things. Nobody has stepped up to do or fund that work.
This paragraph ... essentially says "we're making it hard on you because
kernel developers can't be bothered to work on GitHub". But a lot of
the complexity, as reflected in this guide, has to do with properly
gathering the information that is needed to have a hope at tracking a
problem down. I'm not sure this paragraph is needed at all but, if
you're going to keep it, have it at least reflect that the complexity of
problem reporting has a lot to do with the complexity of the problem
domain rather than developers who are stuck in their habits.
Otherwise seems OK.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1 03/30] docs: reporting-issues: add conclusion to the step-by-step guide
From: Jonathan Corbet @ 2025-10-27 17:29 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <9a8d7b58f482cf0669bc5028dd0e01301f7f526e.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Idea and text comes from
> Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> Documentation/admin-guide/reporting-issues.rst | 14 ++++++++++++++
> 1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 90b50c27c0d2b6..9676ba85e1b73c 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -241,6 +241,20 @@ kernels regularly rebased on those. If that is the case, follow these steps:
> The reference section below explains each of these steps in more detail.
>
>
> +Conclusion of the step-by-step guide
> +------------------------------------
> +
> +Did you run into trouble following the step-by-step guide not cleared up by the
> +reference section below? Did you spot errors? Or do you have ideas on how to
> +improve the guide?
> +
> +If any of that applies, please take a moment and let the primary author of this
> +text, Thorsten Leemhuis <linux@leemhuis.info>, know by email while ideally CCing
> +the public Linux docs mailing list <linux-doc@vger.kernel.org>. Such feedback is
> +vital to improve this text further, which is in everybody's interest, as it will
> +enable more people to master the task described here.
> +
Consider also soliciting patches to improve it - one can always hope we
can bring in some help...
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1 04/30] docs: reporting-issues: add proper appendix
From: Jonathan Corbet @ 2025-10-27 17:38 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <c3d92d4e74557bfff3627d8ceb6a9911612af52a.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Turn the "Why some bugs remain unfixed and some report are ignored"
> section into a proper appendix while improving it slightly.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> .../admin-guide/reporting-issues.rst | 102 +++++++++---------
> 1 file changed, 54 insertions(+), 48 deletions(-)
Some comments below, but I have to ask: do we really need this section
at all? Getting people to read long documents is hard, and this adds a
fair amount of length to, essentially, say that the kernel is an
open-source program like any other and its developers are not required
to address your problems...?
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 9676ba85e1b73c..745e698cb6be8b 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -1693,60 +1693,66 @@ for the subsystem where the issue seems to have its roots; CC the mailing list
> for the subsystem as well as the stable mailing list (stable@vger.kernel.org).
>
>
> -Why some issues won't get any reaction or remain unfixed after being reported
> -=============================================================================
> +Appendix: additional background information
> +===========================================
>
> -When reporting a problem to the Linux developers, be aware only 'issues of high
> -priority' (regressions, security issues, severe problems) are definitely going
> -to get resolved. The maintainers or if all else fails Linus Torvalds himself
> -will make sure of that. They and the other kernel developers will fix a lot of
> -other issues as well. But be aware that sometimes they can't or won't help; and
> -sometimes there isn't even anyone to send a report to.
> +.. _unfixedbugs_repiapdx:
This label is seemingly unused?
> -This is best explained with kernel developers that contribute to the Linux
> -kernel in their spare time. Quite a few of the drivers in the kernel were
> -written by such programmers, often because they simply wanted to make their
> -hardware usable on their favorite operating system.
> +Why some bugs remain unfixed and some report are ignored
report*s*
> +--------------------------------------------------------
> +
> +When reporting a problem to the Linux developers, be aware that they are only
> +obliged to fix regressions, security issues, and severe problems. Developers,
> +maintainers, or, if all else fails, Linus Torvalds himself will make sure of
> +that. They will fix a lot of other issues as well, but sometimes they can't or
> +won't help -- and sometimes there isn't even anyone to send a report to.
> +
> +This situation is best explained using kernel developers that contribute to the
"using" is weird; "highlighting" or some such?
> +Linux kernel in their spare time. Quite a few of the drivers in the kernel were
> +written by such programmers; often they simply wanted to make the
> +hardware they owned usable on their favorite operating system.
This really kind of reinforces the old "developed in their parents'
basement" stuff we used to hear; again, do we really need this?
> These programmers most of the time will happily fix problems other people
> -report. But nobody can force them to do, as they are contributing voluntarily.
> -
> -Then there are situations where such developers really want to fix an issue,
> -but can't: sometimes they lack hardware programming documentation to do so.
> -This often happens when the publicly available docs are superficial or the
> -driver was written with the help of reverse engineering.
> -
> -Sooner or later spare time developers will also stop caring for the driver.
> -Maybe their test hardware broke, got replaced by something more fancy, or is so
> -old that it's something you don't find much outside of computer museums
> -anymore. Sometimes developer stops caring for their code and Linux at all, as
> -something different in their life became way more important. In some cases
> -nobody is willing to take over the job as maintainer – and nobody can be forced
> -to, as contributing to the Linux kernel is done on a voluntary basis. Abandoned
> -drivers nevertheless remain in the kernel: they are still useful for people and
> -removing would be a regression.
> +report. But nobody can force them to do so, as they are contributing
> +voluntarily.
> +
> +There are also situations where such developers would like to fix issues,
> +but can't: They might lack programming documentation to do so or hardware to
> +test. The former can happen when the publicly available docs are superficial or
> +when a driver was written with the help of reverse engineering.
> +
> +Sooner or later, spare-time developers usually stop caring for the driver.
> +Maybe their test hardware broke, was replaced by something more fancy, or
> +became so old that it is something you don't find much outside of computer
> +museums anymore. Other times developers also stop caring when
> +something different in life becomes more important to them. Then sometimes
> +nobody is willing to take over the job as maintainer -- and nobody else can be
> +forced to, as contributing is voluntary. The code nevertheless often stays
> +around, as it is useful for people; removing it would also cause a regression,
> +which is not allowed in Linux.
>
> The situation is not that different with developers that are paid for their
> -work on the Linux kernel. Those contribute most changes these days. But their
> -employers sooner or later also stop caring for their code or make its
> -programmer focus on other things. Hardware vendors for example earn their money
> -mainly by selling new hardware; quite a few of them hence are not investing
> -much time and energy in maintaining a Linux kernel driver for something they
> -stopped selling years ago. Enterprise Linux distributors often care for a
> -longer time period, but in new versions often leave support for old and rare
> -hardware aside to limit the scope. Often spare time contributors take over once
> -a company orphans some code, but as mentioned above: sooner or later they will
> -leave the code behind, too.
> -
> -Priorities are another reason why some issues are not fixed, as maintainers
> -quite often are forced to set those, as time to work on Linux is limited.
> -That's true for spare time or the time employers grant their developers to
> -spend on maintenance work on the upstream kernel. Sometimes maintainers also
> -get overwhelmed with reports, even if a driver is working nearly perfectly. To
> -not get completely stuck, the programmer thus might have no other choice than
> -to prioritize issue reports and reject some of them.
> -
> -But don't worry too much about all of this, a lot of drivers have active
> +work on the upstream Linux kernel. Those contribute the most changes these days.
> +But their employers set the priorities. And those sooner or later stop caring
> +for some code or make their
> +employees focus on other things. Hardware vendors, for example, earn their money
> +mainly by selling new hardware -- they thus often are not much interested in
> +investing much time and energy in maintaining a Linux kernel driver for a chip
> +they stopped selling years ago. Enterprise Linux distributors often care for a
> +longer time period, but in new versions might set support for old and rare
> +hardware aside to limit the scope, too. Often spare-time contributors take over
> +once employed developers orphan some code, but as mentioned earlier: Sooner or
> +later they will usually leave the code behind, too.
> +
> +Priorities are another reason why some issues are not fixed, as developers
> +quite often are forced to set those: The spare-time of volunteers or the time
> +employers allot for upstream Linux kernel work is often limited. Sometimes
> +developers are also flooded with good and bad reports, even if a driver is
> +working well. To
> +not get completely stuck, the programmers might have no other choice than
> +to prioritize bug reports and ignore some.
> +
> +But do not worry too much about all of this, a lot of drivers have active
> maintainers who are quite interested in fixing as many issues as possible.
Otherwise OK, I guess, but my overall question stands: do we really need
this text?
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1 05/30] docs: reporting-issues: outline why reporting is complicated
From: Jonathan Corbet @ 2025-10-27 17:44 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <a6704ef5b3a8dcbaf645ddb5407e8f13553502b0.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Replace the closing words with a section that describes why reporting
> Linux kernel bugs is more complicated than in other FLOSS projects.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> .../admin-guide/reporting-issues.rst | 67 ++++++++++++++++---
> 1 file changed, 59 insertions(+), 8 deletions(-)
So the text is OK but ... this is now the second section that is
essentially a long apology for the kernel process being so difficult.
It seems redundant with the other text, and I'm not convinced we need
it.
Again, length is an impediment to getting people to actually read this
stuff; we should be trying to be as concise as we can. Do we really
need this?
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 21/21] Docs: add Functions parameters order section
From: Andi Shyti @ 2025-10-27 18:22 UTC (permalink / raw)
To: Jani Nikula
Cc: Yury Norov (NVIDIA), Linus Walleij, Lee Jones, linux-arm-kernel,
linux-kernel, Jonathan Corbet, workflows, linux-doc
In-Reply-To: <723c936f92352352c3b1a84b858d684f5b7a0834@intel.com>
Hi,
On Mon, Oct 27, 2025 at 11:02:48AM +0200, Jani Nikula wrote:
> On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" <yury.norov@gmail.com> wrote:
> > Standardize parameters ordering in some typical cases to minimize
> > confusion.
> >
> > Signed-off-by: Yury Norov (NVIDIA) <yury.norov@gmail.com>
> > ---
> > Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++
> > 1 file changed, 48 insertions(+)
> >
> > diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> > index d1a8e5465ed9..dde24148305c 100644
> > --- a/Documentation/process/coding-style.rst
> > +++ b/Documentation/process/coding-style.rst
> > @@ -523,6 +523,54 @@ below, compared to the **declaration** example above)::
> > ...
> > }
> >
> > +6.2) Function parameters order
> > +------------------------------
> > +
> > +The order of parameters is important both for code generation and readability.
> > +Passing parameters in an unusual order is a common source of bugs. Listing
> > +them in standard widely adopted order helps to avoid confusion.
> > +
> > +Many ABIs put first function parameter and return value in R0. If your
> > +function returns one of its parameters, passing it at the very beginning
> > +would lead to a better code generation. For example::
> > +
> > + void *memset64(uint64_t *s, uint64_t v, size_t count);
> > + void *memcpy(void *dest, const void *src, size_t count);
> > +
> > +If your function doesn't propagate a parameter, but has a meaning of copying
> > +and/or processing data, the best practice is following the traditional order:
> > +destination, source, options, flags.
> > +
> > +for_each()-like iterators should take an enumerator the first. For example::
> > +
> > + for_each_set_bit(bit, mask, nbits);
> > + do_something(bit);
> > +
> > + list_for_each_entry(pos, head, member);
> > + do_something(pos);
> > +
> > +If function operates on a range or ranges of data, corresponding parameters
> > +may be described as ``start - end`` or ``start - size`` pairs. In both cases,
> > +the parameters should follow each other. For example::
> > +
> > + int
> > + check_range(unsigned long vstart, unsigned long vend,
> > + unsigned long kstart, unsigned long kend);
> > +
> > + static inline void flush_icache_range(unsigned long start, unsigned long end);
> > +
> > + static inline void flush_icache_user_page(struct vm_area_struct *vma,
> > + struct page *page,
> > + unsigned long addr, int len);
> > +
> > +Both ``start`` and ``end`` of the interval are inclusive.
> > +
> > +Describing intervals in order ``end - start`` is unfavorable. One notable
> > +example is the ``GENMASK(high, low)`` macro. While such a notation is popular
> > +in hardware context, particularly to describe registers structure, in context
> > +of software development it looks counter intuitive and confusing. Please switch
> > +to an equivalent ``BITS(low, high)`` version.
> > +
>
> GENMASK when used for defining hardware registers is completely fine,
> and *much* easier to deal with when you cross check against the specs
> that almost invariably define high:low.
I fully agree with Jani here! When coming into describing
registers my brain is hardwired to read values from left to
right, high-low.
Linus suggested also BITS(start_bit, n_bits) which, in my
opinion, complements what we already have.
We leave GENMASK to register mask descriptions and BITS to the
rest.
Andi
^ permalink raw reply
* Re: [PATCH 21/21] Docs: add Functions parameters order section
From: Randy Dunlap @ 2025-10-27 18:43 UTC (permalink / raw)
To: Jani Nikula, Yury Norov (NVIDIA), Linus Walleij, Lee Jones,
linux-arm-kernel, linux-kernel, Jonathan Corbet, workflows,
linux-doc
In-Reply-To: <723c936f92352352c3b1a84b858d684f5b7a0834@intel.com>
On 10/27/25 2:02 AM, Jani Nikula wrote:
> On Sat, 25 Oct 2025, "Yury Norov (NVIDIA)" <yury.norov@gmail.com> wrote:
>> Standardize parameters ordering in some typical cases to minimize
>> confusion.
>>
>> Signed-off-by: Yury Norov (NVIDIA) <yury.norov@gmail.com>
>> ---
>> Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++
>> 1 file changed, 48 insertions(+)
>>
>> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
>> index d1a8e5465ed9..dde24148305c 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -523,6 +523,54 @@ below, compared to the **declaration** example above)::
>> ...
>> }
>>
>> +6.2) Function parameters order
>> +------------------------------
>> +
>> +The order of parameters is important both for code generation and readability.
>> +Passing parameters in an unusual order is a common source of bugs. Listing
>> +them in standard widely adopted order helps to avoid confusion.
>> +
>> +Many ABIs put first function parameter and return value in R0. If your
>> +function returns one of its parameters, passing it at the very beginning
>> +would lead to a better code generation. For example::
>> +
>> + void *memset64(uint64_t *s, uint64_t v, size_t count);
>> + void *memcpy(void *dest, const void *src, size_t count);
>> +
>> +If your function doesn't propagate a parameter, but has a meaning of copying
>> +and/or processing data, the best practice is following the traditional order:
>> +destination, source, options, flags.
>> +
>> +for_each()-like iterators should take an enumerator the first. For example::
>> +
>> + for_each_set_bit(bit, mask, nbits);
>> + do_something(bit);
>> +
>> + list_for_each_entry(pos, head, member);
>> + do_something(pos);
>> +
>> +If function operates on a range or ranges of data, corresponding parameters
>> +may be described as ``start - end`` or ``start - size`` pairs. In both cases,
>> +the parameters should follow each other. For example::
>> +
>> + int
>> + check_range(unsigned long vstart, unsigned long vend,
>> + unsigned long kstart, unsigned long kend);
>> +
>> + static inline void flush_icache_range(unsigned long start, unsigned long end);
>> +
>> + static inline void flush_icache_user_page(struct vm_area_struct *vma,
>> + struct page *page,
>> + unsigned long addr, int len);
>> +
>> +Both ``start`` and ``end`` of the interval are inclusive.
>> +
>> +Describing intervals in order ``end - start`` is unfavorable. One notable
>> +example is the ``GENMASK(high, low)`` macro. While such a notation is popular
>> +in hardware context, particularly to describe registers structure, in context
>> +of software development it looks counter intuitive and confusing. Please switch
>> +to an equivalent ``BITS(low, high)`` version.
>> +
>
> GENMASK when used for defining hardware registers is completely fine,
> and *much* easier to deal with when you cross check against the specs
> that almost invariably define high:low.
>
> Which other parts of coding style take on specific interfaces and tell
> you to switch? Weird. I for one don't want to encourage an influx of
> trivial patches doing GENMASK to BITS conversions, and then keep
> rejecting them. It's just a huge collective waste of time.
>
> Anyway, that's a lot of text on "function parameter order" to justify
> BITS(), but completely skips more important principles such as "context
> parameter first", or "destination first".
and usually flags or gfp_t last (if they are used).
There are several exceptions to these, but consistency helps and
lack of it has caused some argument problems in the past.
--
~Randy
^ permalink raw reply
* Re: [PATCH v1 01/30] docs: reporting-issues: mention text is best viewed rendered
From: Randy Dunlap @ 2025-10-27 21:19 UTC (permalink / raw)
To: Thorsten Leemhuis, Jonathan Corbet
Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <4f7e2de2a2336c52e55cc49dcda627a4e86b8793.1761481839.git.linux@leemhuis.info>
On 10/26/25 5:41 AM, Thorsten Leemhuis wrote:
> Add a comment before the step-by-step guide explaining that the document
> is best viewed in the rendered form, as there the internal links will
> work that later patches will add.
>
> While at it change the double quotes in the license hint at the end of
> the document into single quotes, which is the preferred style.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> Documentation/admin-guide/reporting-issues.rst | 18 ++++++++++++++----
> 1 file changed, 14 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index a68e6d90927471..3bc47afaf85ea0 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -48,6 +48,16 @@ Once 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.
>
> +..
> + Note: If you see this note, you are reading the text's source file. You
> + might want to switch to a rendered version: It makes it a lot easier to
> + read and navigate this document -- especially when you want to look something
> + up in the reference section, then jump back to where you left off.
> +..
> + Find the latest rendered version of this text here:
> + https://docs.kernel.org/admin-guide/reporting-issues.html
> +
> +
> Step-by-step guide how to report issues to the kernel maintainers
> =================================================================
>
> @@ -1748,13 +1758,13 @@ art will lay some groundwork to improve the situation over time.
> you spot a typo or small mistake, feel free to let him know directly and
> he'll fix it. You are free to do the same in a mostly informal way if you
> want to contribute changes to the text, but for copyright reasons please CC
> - linux-doc@vger.kernel.org and "sign-off" your contribution as
> - Documentation/process/submitting-patches.rst outlines in the section "Sign
> - your work - the Developer's Certificate of Origin".
> + linux-doc@vger.kernel.org and 'sign-off' your contribution as
> + Documentation/process/submitting-patches.rst outlines in the section 'Sign
> + your work - the Developer's Certificate of Origin'.
Can you have a single quote (Developer's) inside single quotes?
Anyway, nack on the quote marks changes.
> ..
> This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
> of the file. If you want to distribute this text under CC-BY-4.0 only,
> - please use "The Linux kernel developers" for author attribution and link
> + please use 'The Linux kernel developers' for author attribution and link
> this as source:
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst
> ..
--
~Randy
^ permalink raw reply
* Re: [PATCH v1 06/30] docs: reporting-issues: replace TLDR guide with more of an into
From: Jonathan Corbet @ 2025-10-28 21:32 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <bffecd192c73909b8ceb58a123842c943e51200f.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Remove the TLDR guide and just describe the essence: a email is all that
> is needed.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> ---
> .../admin-guide/reporting-issues.rst | 90 +++++++------------
> 1 file changed, 32 insertions(+), 58 deletions(-)
This one seems OK - always nice to make it shorter! :)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v1 07/30] docs: reporting-issues: explain need for fresh vanilla kernel
From: Jonathan Corbet @ 2025-10-28 21:40 UTC (permalink / raw)
To: Thorsten Leemhuis; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <616e01c3b2212e3dc7c7cc40f551618092f40c62.1761481839.git.linux@leemhuis.info>
Thorsten Leemhuis <linux@leemhuis.info> writes:
> Rewrite the section that explains why a fresh kernel is needed and why
> bug reporters might have to compile one themselves for testing and
> debugging purposes.
>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> .../admin-guide/reporting-issues.rst | 141 +++++++++++-------
> 1 file changed, 85 insertions(+), 56 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> index 7dfb3ca4b3e322..2f387e8766f21d 100644
> --- a/Documentation/admin-guide/reporting-issues.rst
> +++ b/Documentation/admin-guide/reporting-issues.rst
> @@ -49,11 +49,25 @@ Step-by-step guide on reporting Linux kernel issues
> Note: Only the steps starting with '*you must*' are strictly required -- but
> following the others is usually in your own interest.
>
> - * 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.
> +.. _intro_repisbs:
> +
> +* Be aware:
> +
> + * You should report issues using a Linux kernel that is both really fresh and
> + vanilla. That often means that you will have to remove software that
> + requires externally developed kernel modules and install the newest upstream
> + Linux development kernel yourself.
> +
> + * There is a decent chance you will have to report the problem by email, in
> + which case your email address will become part of public archives.
> +
> + * You might need to patch and build your own kernel to help developers debug
> + and fix the bug.
> +
> + If these three aspects sound too demanding, consider reporting the issue to
> + your Linux distributor or hardware manufacturer instead.
So nothing to object to here, but this does make me wonder who the
audience is for this document? It seems that you are aiming at people
who do not run upstream kernels, but who want to work with upstream to
get bugs fixed...? That seems worth saying explicitly if so. How big
of a group is this?
Thanks,
jon
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox