* [PATCH v1 01/30] docs: reporting-issues: mention text is best viewed rendered
From: Thorsten Leemhuis @ 2025-10-26 12:41 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
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'.
..
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
..
--
2.51.0
^ permalink raw reply related
* [PATCH v1 18/30] docs: reporting-issues: improve text on looking up place to report
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 checking the MAINTAINERS file.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 169 +++++++++---------
1 file changed, 86 insertions(+), 83 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index e9d304040e3b54..56e004ba038403 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -149,10 +149,13 @@ following the others is usually in your own interest.
[:ref:`details <reginquiry_repiref>`]
- * Locate the driver or kernel subsystem that seems to be causing the issue.
- Find out how and where its developers expect reports. Note: most of the
- time this won't be bugzilla.kernel.org, as issues typically need to be sent
- by mail to a maintainer and a public mailing list.
+.. _maintainers_repisbs:
+
+* *You must* consult ':ref:`MAINTAINERS <maintainers>`' to determine where
+ developers of the affected driver or subsystem want bugs to be submitted to;
+ use your best guess if in doubt which is appropriate.
+
+ [:ref:`details <maintainers_repiref>`]
* Create a fresh backup and put system repair and restore tools at hand.
@@ -705,119 +708,121 @@ answer these emails on a best-effort basis.
[:ref:`back to step-by-step guide <reginquiry_repisbs>`]
-Check where you need to report your issue
------------------------------------------
+.. _maintainers_repiref:
- *Locate the driver or kernel subsystem that seems to be causing the issue.
- Find out how and where its developers expect reports. Note: most of the
- time this won't be bugzilla.kernel.org, as issues typically need to be sent
- by mail to a maintainer and a public mailing list.*
+Check how to report your issue
+------------------------------
-It's crucial to send your report to the right people, as the Linux kernel is a
+ *You must consult MAINTAINERS to determine where developers of the affected
+ driver or subsystem want bugs to be submitted to; use your best guess, if* [:ref:`... <maintainers_repisbs>`]
+
+It is crucial to submit your report to the right place, as the Linux kernel is a
big project and most of its developers are only familiar with a small subset of
-it. Quite a few programmers for example only care for just one driver, for
-example one for a WiFi chip; its developer likely will only have small or no
-knowledge about the internals of remote or unrelated "subsystems", like the TCP
-stack, the PCIe/PCI subsystem, memory management or file systems.
+it. Quite a few programmers, for example, only care for just one driver, like
+one for a particular WiFi chip; its developer likely will only have small or no
+knowledge about the internals of near, remote, or unrelated subsystems, like
+the TCP stack, the PCIe/PCI subsystem, memory management, or file systems.
-Problem is: the Linux kernel lacks a central bug tracker where you can simply
+Problem is: The Linux kernel lacks a central bug tracker where you can simply
file your issue and make it reach the developers that need to know about it.
-That's why you have to find the right place and way to report issues yourself.
+That is why you have to find the right place and way to report issues yourself.
You can do that with the help of a script (see below), but it mainly targets
-kernel developers and experts. For everybody else the MAINTAINERS file is the
-better place.
+kernel developers and experts. For everybody else, using the MAINTAINERS file is
+the better approach.
How to read the MAINTAINERS file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, let's assume
-the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
-case it's likely an issue in the WiFi driver. Obviously it could also be some
-code it builds upon, but unless you suspect something like that stick to the
-driver. If it's really something else, the driver's developers will get the
-right people involved.
+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.
-In case of a problem with the WiFi driver you for example might want to look at
-the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and the
+In case of a problem with the WiFi driver, you, for example, might want to look
+at the output of ``lspci -k``, as it lists devices on the PCI/PCIe bus and the
kernel module driving it::
- [user@something ~]$ lspci -k
- [...]
- 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
- Subsystem: Bigfoot Networks, Inc. Device 1535
- Kernel driver in use: ath10k_pci
- Kernel modules: ath10k_pci
- [...]
+ [user@something ~]$ lspci -k
+ [...]
+ 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
+ Subsystem: Bigfoot Networks, Inc. Device 1535
+ Kernel driver in use: ath10k_pci
+ Kernel modules: ath10k_pci
+ [...]
But this approach won't work if your WiFi chip is connected over USB or some
-other internal bus. In those cases you might want to check your WiFi manager or
-the output of ``ip link``. Look for the name of the problematic network
+other internal bus. In those cases you might want to check your network manager
+or the output of ``ip link``. Look for the name of the problematic network
interface, which might be something like 'wlp58s0'. This name can be used like
this to find the module driving it::
- [user@something ~]$ realpath --relative-to=/sys/module/ /sys/class/net/wlp58s0/device/driver/module
- ath10k_pci
+ [user@something ~]$ realpath --relative-to=/sys/module/ /sys/class/net/wlp58s0/device/driver/module
+ ath10k_pci
In case tricks like these don't bring you any further, try to search the
internet on how to narrow down the driver or subsystem in question. And if you
-are unsure which it is: just try your best guess, somebody will help you if you
-guessed poorly.
+are unsure which it is: Just try your best guess, somebody will usually help out
+if you guessed poorly.
Once you know the driver or subsystem, you want to search for it in the
MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, as the
name is too specific. Sometimes you will need to search on the net for help;
-but before doing so, try a somewhat shorted or modified name when searching the
-MAINTAINERS file, as then you might find something like this::
-
- QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
- Mail: A. Some Human <shuman@example.com>
- Mailing list: ath10k@lists.infradead.org
- Status: Supported
- Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
- SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
- Files: drivers/net/wireless/ath/ath10k/
-
-Note: the line description will be abbreviations, if you read the plain
-MAINTAINERS file found in the root of the Linux source tree. 'Mail:' for
-example will be 'M:', 'Mailing list:' will be 'L', and 'Status:' will be 'S:'.
-A section near the top of the file explains these and other abbreviations.
-
-First look at the line 'Status'. Ideally it should be 'Supported' or
+but before doing so, try a somewhat shortened or modified name when searching
+the MAINTAINERS file, as then you might find something like this::
+
+ QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
+ Mail: A. Some Human <shuman@example.com>
+ Mailing list: ath10k@lists.infradead.org
+ Status: Supported
+ Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
+ SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
+ Files: drivers/net/wireless/ath/ath10k/
+
+Note: Line descriptions like 'Status' will be abbreviations like 'S:' if you
+read the plain MAINTAINERS file found in the root of the Linux source tree.
+
+First look at the line 'Status' ('S:'). Ideally it should be 'Supported' or
'Maintained'. If it states 'Obsolete' then you are using some outdated approach
that was replaced by a newer solution you need to switch to. Sometimes the code
only has someone who provides 'Odd Fixes' when feeling motivated. And with
'Orphan' you are totally out of luck, as nobody takes care of the code anymore.
-That only leaves these options: arrange yourself to live with the issue, fix it
+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:': 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 mail. Very few subsystems use
+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.
-In this and many other cases you thus have to look for lines starting with
-'Mail:' instead. Those mention the name and the email addresses for the
+In this and many other cases, you thus have to look for lines starting with
+'Mail:' ('M:') instead. Those mention the name and the email addresses for the
maintainers of the particular code. Also look for a line starting with 'Mailing
-list:', which tells you the public mailing list where the code is developed.
-Your report later needs to go by mail to those addresses. Additionally, for all
-issue reports sent by email, make sure to add the Linux Kernel Mailing List
-(LKML) <linux-kernel@vger.kernel.org> to CC. Don't omit either of the mailing
-lists when sending your issue report by mail later! Maintainers are busy people
-and might leave some work for other developers on the subsystem specific list;
-and LKML is important to have one place where all issue reports can be found.
+List:' ('L:'), which tells you the public mailing list where the code is
+developed. Your report later needs to go by email to those addresses.
+Additionally, for all issue reports sent by email, make sure to add the Linux
+Kernel Mailing List (LKML) <linux-kernel@vger.kernel.org> to CC. Don't omit
+either of the mailing lists when sending your issue report by email later!
+Maintainers are busy people and might leave some work for other developers on
+the subsystem-specific list -- and LKML is important to have one place where all
+issue reports can be found.
Finding the maintainers with the help of a script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For people that have the Linux sources at hand there is a second option to find
-the proper place to report: the script 'scripts/get_maintainer.pl' which tries
+For people that have the Linux sources at hand, there is a second option to find
+the proper place to report: The script 'scripts/get_maintainer.pl' which tries
to find all people to contact. It queries the MAINTAINERS file and needs to be
called with a path to the source code in question. For drivers compiled as
-module if often can be found with a command like this::
+module, it often can be found with a command like this::
$ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
drivers/net/wireless/ath/ath10k/ath10k_pci.ko
@@ -832,20 +837,18 @@ Pass parts of this to the script::
netdev@vger.kernel.org (open list:NETWORKING DRIVERS)
linux-kernel@vger.kernel.org (open list)
-Don't sent your report to all of them. Send it to the maintainers, which the
-script calls "supporter:"; additionally CC the most specific mailing list for
-the code as well as the Linux Kernel Mailing List (LKML). In this case you thus
-would need to send the report to 'Some Human <shuman@example.com>' with
-'ath10k@lists.infradead.org' and 'linux-kernel@vger.kernel.org' in CC.
+Usually you want to send your report to all of them.
-Note: in case you cloned the Linux sources with git you might want to call
+Note: In case you cloned the Linux sources with Git, you might want to call
``get_maintainer.pl`` a second time with ``--git``. The script then will look
at the commit history to find which people recently worked on the code in
-question, as they might be able to help. But use these results with care, as it
-can easily send you in a wrong direction. That for example happens quickly in
-areas rarely changed (like old or unmaintained drivers): sometimes such code is
-modified during tree-wide cleanups by developers that do not care about the
-particular driver at all.
+question, as they might be able to help. But use these results with care, as
+they can easily send you in the wrong direction. That, for example, happens
+quickly in areas rarely changed (like old or unmaintained drivers): Sometimes
+such code is modified during tree-wide cleanups by developers that do not care
+about the particular driver at all.
+
+[:ref:`back to step-by-step guide <maintainers_repisbs>`]
Prepare for emergencies
--
2.51.0
^ permalink raw reply related
* [PATCH v1 19/30] docs: reporting-issues: move text on 'check other places' 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 a follow-up patch.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 82 +++++++++----------
1 file changed, 41 insertions(+), 41 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 56e004ba038403..baee1da327d116 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -157,6 +157,10 @@ following the others is usually in your own interest.
[:ref:`details <maintainers_repiref>`]
+ * Search the archives of the bug tracker or mailing list in question
+ thoroughly for reports that might match your issue. If you find anything,
+ join the discussion instead of sending a new report.
+
* Create a fresh backup and put system repair and restore tools at hand.
* Ensure your system does not enhance its kernels by building additional
@@ -169,10 +173,6 @@ following the others is usually in your own interest.
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
'Dealing with regressions within a stable and longterm kernel line'.
- * Search the archives of the bug tracker or mailing list in question
- thoroughly for reports that might match your issue. If you find anything,
- join the discussion instead of sending a new report.
-
After these preparations you'll now enter the main part:
* Unless you are already running the latest 'mainline' Linux kernel, better
@@ -851,6 +851,43 @@ about the particular driver at all.
[:ref:`back to step-by-step guide <maintainers_repisbs>`]
+Search for existing reports, second run
+---------------------------------------
+
+ *Search the archives of the bug tracker or mailing list in question
+ thoroughly for reports that might match your issue. If you find anything,
+ join the discussion instead of sending a new report.*
+
+As mentioned earlier already: reporting an issue that someone else already
+brought forward is often a waste of time for everyone involved, especially you
+as the reporter. That's why you should search for existing report again, now
+that you know where they need to be reported to. If it's mailing list, you will
+often find its archives on `lore.kernel.org <https://lore.kernel.org/>`_.
+
+But some list are hosted in different places. That for example is the case for
+the ath10k WiFi driver used as example in the previous step. But you'll often
+find the archives for these lists easily on the net. Searching for 'archive
+ath10k@lists.infradead.org' for example will lead you to the `Info page for the
+ath10k mailing list <https://lists.infradead.org/mailman/listinfo/ath10k>`_,
+which at the top links to its
+`list archives <https://lists.infradead.org/pipermail/ath10k/>`_. Sadly this and
+quite a few other lists miss a way to search the archives. In those cases use a
+regular internet search engine and add something like
+'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
+the results to the archives at that URL.
+
+It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again
+at this point. If your report needs to be filed in a bug tracker, you may want
+to check the mailing list archives for the subsystem as well, as someone might
+have reported it only there.
+
+For details how to search and what to do if you find matching reports see
+"Search for existing reports, first run" above.
+
+Do not hurry with this step of the reporting process: spending 30 to 60 minutes
+or even more time can save you and others quite a lot of time and trouble.
+
+
Prepare for emergencies
-----------------------
@@ -918,43 +955,6 @@ regressions with newer kernel version line (say something broke when switching
from 5.9.15 to 5.10.5) do not qualify.
-Search for existing reports, second run
----------------------------------------
-
- *Search the archives of the bug tracker or mailing list in question
- thoroughly for reports that might match your issue. If you find anything,
- join the discussion instead of sending a new report.*
-
-As mentioned earlier already: reporting an issue that someone else already
-brought forward is often a waste of time for everyone involved, especially you
-as the reporter. That's why you should search for existing report again, now
-that you know where they need to be reported to. If it's mailing list, you will
-often find its archives on `lore.kernel.org <https://lore.kernel.org/>`_.
-
-But some list are hosted in different places. That for example is the case for
-the ath10k WiFi driver used as example in the previous step. But you'll often
-find the archives for these lists easily on the net. Searching for 'archive
-ath10k@lists.infradead.org' for example will lead you to the `Info page for the
-ath10k mailing list <https://lists.infradead.org/mailman/listinfo/ath10k>`_,
-which at the top links to its
-`list archives <https://lists.infradead.org/pipermail/ath10k/>`_. Sadly this and
-quite a few other lists miss a way to search the archives. In those cases use a
-regular internet search engine and add something like
-'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
-the results to the archives at that URL.
-
-It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again
-at this point. If your report needs to be filed in a bug tracker, you may want
-to check the mailing list archives for the subsystem as well, as someone might
-have reported it only there.
-
-For details how to search and what to do if you find matching reports see
-"Search for existing reports, first run" above.
-
-Do not hurry with this step of the reporting process: spending 30 to 60 minutes
-or even more time can save you and others quite a lot of time and trouble.
-
-
Install a fresh kernel for testing
----------------------------------
--
2.51.0
^ permalink raw reply related
* [PATCH v1 17/30] docs: reporting-issues: move text on 'check MAINTAINERS file' 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 a follow-up patch.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 162 +++++++++---------
1 file changed, 81 insertions(+), 81 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index f040ca7c0a2f59..e9d304040e3b54 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -149,6 +149,11 @@ following the others is usually in your own interest.
[:ref:`details <reginquiry_repiref>`]
+ * Locate the driver or kernel subsystem that seems to be causing the issue.
+ Find out how and where its developers expect reports. Note: most of the
+ time this won't be bugzilla.kernel.org, as issues typically need to be sent
+ by mail to a maintainer and a public mailing list.
+
* Create a fresh backup and put system repair and restore tools at hand.
* Ensure your system does not enhance its kernels by building additional
@@ -161,11 +166,6 @@ following the others is usually in your own interest.
(say something broke when updating from 5.10.4 to 5.10.5), scroll down to
'Dealing with regressions within a stable and longterm kernel line'.
- * Locate the driver or kernel subsystem that seems to be causing the issue.
- Find out how and where its developers expect reports. Note: most of the
- time this won't be bugzilla.kernel.org, as issues typically need to be sent
- by mail to a maintainer and a public mailing list.
-
* Search the archives of the bug tracker or mailing list in question
thoroughly for reports that might match your issue. If you find anything,
join the discussion instead of sending a new report.
@@ -705,73 +705,6 @@ answer these emails on a best-effort basis.
[:ref:`back to step-by-step guide <reginquiry_repisbs>`]
-Prepare for emergencies
------------------------
-
- *Create a fresh backup and put system repair and restore tools at hand.*
-
-Reminder, you are dealing with computers, which sometimes do unexpected things,
-especially if you fiddle with crucial parts like the kernel of its operating
-system. That's what you are about to do in this process. Thus, make sure to
-create a fresh backup; also ensure you have all tools at hand to repair or
-reinstall the operating system as well as everything you need to restore the
-backup.
-
-
-Make sure your kernel doesn't get enhanced
-------------------------------------------
-
- *Ensure your system does not enhance its kernels by building additional
- kernel modules on-the-fly, which solutions like DKMS might be doing locally
- without your knowledge.*
-
-The risk your issue report gets ignored or rejected dramatically increases if
-your kernel gets enhanced in any way. That's why you should remove or disable
-mechanisms like akmods and DKMS: those build add-on kernel modules
-automatically, for example when you install a new Linux kernel or boot it for
-the first time. Also remove any modules they might have installed. Then reboot
-before proceeding.
-
-Note, you might not be aware that your system is using one of these solutions:
-they often get set up silently when you install Nvidia's proprietary graphics
-driver, VirtualBox, or other software that requires a some support from a
-module not part of the Linux kernel. That why your might need to uninstall the
-packages with such software to get rid of any 3rd party kernel module.
-
-
-Document how to reproduce issue
--------------------------------
-
- *Write down coarsely how to reproduce the issue.*
-
-During the reporting process you will have to test if the issue
-happens with other kernel versions. Therefore, it will make your work easier if
-you know exactly how to reproduce an issue quickly on a freshly booted system.
-
-Note: it's often fruitless to report issues that only happened once, as they
-might be caused by a bit flip due to cosmic radiation. That's why you should
-try to rule that out by reproducing the issue before going further. Feel free
-to ignore this advice if you are experienced enough to tell a one-time error
-due to faulty hardware apart from a kernel issue that rarely happens and thus
-is hard to reproduce.
-
-
-Regression in stable or longterm kernel?
-----------------------------------------
-
- *If you are facing a regression within a stable or longterm version line
- (say something broke when updating from 5.10.4 to 5.10.5), scroll down to
- 'Dealing with regressions within a stable and longterm kernel line'.*
-
-Regression within a stable and longterm kernel version line are something the
-Linux developers want to fix badly, as such issues are even more unwanted than
-regression in the main development branch, as they can quickly affect a lot of
-people. The developers thus want to learn about such issues as quickly as
-possible, hence there is a streamlined process to report them. Note,
-regressions with newer kernel version line (say something broke when switching
-from 5.9.15 to 5.10.5) do not qualify.
-
-
Check where you need to report your issue
-----------------------------------------
@@ -886,18 +819,18 @@ to find all people to contact. It queries the MAINTAINERS file and needs to be
called with a path to the source code in question. For drivers compiled as
module if often can be found with a command like this::
- $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
- drivers/net/wireless/ath/ath10k/ath10k_pci.ko
+ $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
+ drivers/net/wireless/ath/ath10k/ath10k_pci.ko
Pass parts of this to the script::
- $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k*
- Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
- Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS)
- ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
- linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS))
- netdev@vger.kernel.org (open list:NETWORKING DRIVERS)
- linux-kernel@vger.kernel.org (open list)
+ $ ./scripts/get_maintainer.pl --no-git -f drivers/net/wireless/ath/ath10k*
+ Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
+ Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS)
+ ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
+ linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS))
+ netdev@vger.kernel.org (open list:NETWORKING DRIVERS)
+ linux-kernel@vger.kernel.org (open list)
Don't sent your report to all of them. Send it to the maintainers, which the
script calls "supporter:"; additionally CC the most specific mailing list for
@@ -915,6 +848,73 @@ modified during tree-wide cleanups by developers that do not care about the
particular driver at all.
+Prepare for emergencies
+-----------------------
+
+ *Create a fresh backup and put system repair and restore tools at hand.*
+
+Reminder, you are dealing with computers, which sometimes do unexpected things,
+especially if you fiddle with crucial parts like the kernel of its operating
+system. That's what you are about to do in this process. Thus, make sure to
+create a fresh backup; also ensure you have all tools at hand to repair or
+reinstall the operating system as well as everything you need to restore the
+backup.
+
+
+Make sure your kernel doesn't get enhanced
+------------------------------------------
+
+ *Ensure your system does not enhance its kernels by building additional
+ kernel modules on-the-fly, which solutions like DKMS might be doing locally
+ without your knowledge.*
+
+The risk your issue report gets ignored or rejected dramatically increases if
+your kernel gets enhanced in any way. That's why you should remove or disable
+mechanisms like akmods and DKMS: those build add-on kernel modules
+automatically, for example when you install a new Linux kernel or boot it for
+the first time. Also remove any modules they might have installed. Then reboot
+before proceeding.
+
+Note, you might not be aware that your system is using one of these solutions:
+they often get set up silently when you install Nvidia's proprietary graphics
+driver, VirtualBox, or other software that requires a some support from a
+module not part of the Linux kernel. That why your might need to uninstall the
+packages with such software to get rid of any 3rd party kernel module.
+
+
+Document how to reproduce issue
+-------------------------------
+
+ *Write down coarsely how to reproduce the issue.*
+
+During the reporting process you will have to test if the issue
+happens with other kernel versions. Therefore, it will make your work easier if
+you know exactly how to reproduce an issue quickly on a freshly booted system.
+
+Note: it's often fruitless to report issues that only happened once, as they
+might be caused by a bit flip due to cosmic radiation. That's why you should
+try to rule that out by reproducing the issue before going further. Feel free
+to ignore this advice if you are experienced enough to tell a one-time error
+due to faulty hardware apart from a kernel issue that rarely happens and thus
+is hard to reproduce.
+
+
+Regression in stable or longterm kernel?
+----------------------------------------
+
+ *If you are facing a regression within a stable or longterm version line
+ (say something broke when updating from 5.10.4 to 5.10.5), scroll down to
+ 'Dealing with regressions within a stable and longterm kernel line'.*
+
+Regression within a stable and longterm kernel version line are something the
+Linux developers want to fix badly, as such issues are even more unwanted than
+regression in the main development branch, as they can quickly affect a lot of
+people. The developers thus want to learn about such issues as quickly as
+possible, hence there is a streamlined process to report them. Note,
+regressions with newer kernel version line (say something broke when switching
+from 5.9.15 to 5.10.5) do not qualify.
+
+
Search for existing reports, second run
---------------------------------------
--
2.51.0
^ permalink raw reply related
* [PATCH v1 02/30] docs: reporting-issues: tweak the reference section intro
From: Thorsten Leemhuis @ 2025-10-26 12:41 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
Small improvements to the intro of the reference section.
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.
Reference section: Reporting issues to the kernel maintainers
=============================================================
-The detailed guides above outline all the major steps in brief fashion, which
-should be enough for most people. But sometimes there are situations where even
-experienced users might wonder how to actually do one of those steps. That's
-what this section is for, as it will provide a lot more details on each of the
-above steps. Consider this as reference documentation: it's possible to read it
-from top to bottom. But it's mainly meant to skim over and a place to look up
-details how to actually perform those steps.
-
-A few words of general advice before digging into the details:
-
- * The Linux kernel developers are well aware this process is complicated and
- demands more than other FLOSS projects. We'd love to make it simpler. But
- that would require work in various places as well as some infrastructure,
- which would need constant maintenance; nobody has stepped up to do that
- work, so that's just how things are for now.
-
- * A warranty or support contract with some vendor doesn't entitle you to
- request fixes from developers in the upstream Linux kernel community: such
- contracts are completely outside the scope of the Linux kernel, its
- development community, and this document. That's why you can't demand
- anything such a contract guarantees in this context, not even if the
- developer handling the issue works for the vendor in question. If you want
- to claim your rights, use the vendor's support channel instead. When doing
- so, you might want to mention you'd like to see the issue fixed in the
- upstream Linux kernel; motivate them by saying it's the only way to ensure
- the fix in the end will get incorporated in all Linux distributions.
-
- * If you never reported an issue to a FLOSS project before you should consider
- reading `How to Report Bugs Effectively
- <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_, `How To Ask
- Questions The Smart Way
- <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good
- questions <https://jvns.ca/blog/good-questions/>`_.
-
-With that off the table, find below the details on how to properly report
-issues to the Linux kernel developers.
+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.
+
+* A warranty or support contract with some vendor doesn't entitle you to
+ request fixes from the upstream Linux developers: Such contracts are
+ completely outside the scope of the upstream Linux kernel, its development
+ community, and this document -- even if those handling the issue work for the
+ vendor who issued the contract. If you want to claim your rights, use the
+ vendor's support channel.
+
+* If you never reported an issue to a FLOSS project before, consider skimming
+ guides like `How to ask good questions
+ <https://jvns.ca/blog/good-questions/>`_, `How To Ask Questions The Smart Way
+ <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to Report
+ Bugs Effectively <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_,.
+
+With that off the table, find below details for the steps from the detailed
+guide on reporting issues to the Linux kernel developers.
Make sure you're using the upstream Linux kernel
--
2.51.0
^ permalink raw reply related
* [PATCH v1 03/30] docs: reporting-issues: add conclusion to the step-by-step guide
From: Thorsten Leemhuis @ 2025-10-26 12:41 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
In-Reply-To: <cover.1761481839.git.linux@leemhuis.info>
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.
+
+
Reference section: Reporting issues to the kernel maintainers
=============================================================
--
2.51.0
^ permalink raw reply related
* [PATCH v1 00/30] docs: reporting-issues: rework
From: Thorsten Leemhuis @ 2025-10-26 12:41 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: workflows, linux-doc, regressions, linux-kernel
Hi! This patch reworks various parts of our text on bug reporting. I
started working on it for six reasons:
* I noticed that even experienced Linux users had trouble with the TLDR
text, despite it being already quite long.
* I noticed a few areas where people were struggling when reporting
issues and saw potential for improving the situation somewhat by
rearranging and fine-tuning the order and the description of the
step-by-step guide a little.
* I wanted to add a simple to follow "is this regression maybe known
already?" option to avoid unnecessary trouble for reporters.
* I wanted to improve the interaction with
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst,
which has a few bits with roots in reporting-issues.rst, but covers
verifying bugs and bisecting a lot better.
* I wanted to make it easier to jump to the reference section and back
by adding internal links, similar to how we did it in
Documentation/admin-guide/quickly-build-trimmed-linux.rst and
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst.
* I found the tone of the old text somewhat off-putting; I think I made
it better in a lot of places, but I suspect I missed a few areas that
needed treatment – and maybe did not go far enough in some others. So
please let me know if you spot cases that are too dim, some external
feedback really would help.
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.
If you want to see how the resulting text looks like, check out:
https://www.leemhuis.info/files/misc/Reporting%20issues%20%e2%80%94%20The%20Linux%20Kernel%20documentation.html
Feel also free to fix any typos you spot
https://docs.google.com/document/d/1To4xVY8M6BDMBXEhEbaXuacZESdMzNFGECHk1a6nVPI/edit?usp=sharing,
I'll pick those up for the next version. You can also add notes with
suggestions there. But please do not add anything that might be covered
by copyright.
Ciao, Thorsten
To: Jonathan Corbet <corbet@lwn.net>
CC: linux-doc@vger.kernel.org
Thorsten Leemhuis (30):
docs: reporting-issues: mention text is best viewed rendered
docs: reporting-issues: tweak the reference section intro
docs: reporting-issues: add conclusion to the step-by-step guide
docs: reporting-issues: add proper appendix
docs: reporting-issues: outline why reporting is complicated
docs: reporting-issues: replace TLDR guide with more of an into
docs: reporting-issues: explain need for fresh vanilla kernel
docs: reporting-issues: add step about processing issues separately
docs: reporting-issues: tell users to check the kernel log
docs: reporting-issues: move 'check tainted flag' upwards
docs: reporting-issues: improve first tainted check
docs: reporting-issues: move 'check environment' upwards
docs: reporting-issues: improve environment check
docs: reporting-issues: improve text about checking for existing
issues
docs: reporting-issues: improve text on classifying the bug
docs: reporting-issues: add fast-track for regressions
docs: reporting-issues: move text on 'check MAINTAINERS file' upwards
docs: reporting-issues: improve text on looking up place to report
docs: reporting-issues: move text on 'check other places' upwards
docs: reporting-issues: improve text on check other places
docs: reporting-issues: improve text on backup et. al
docs: reporting-issues: move text on 'initial write-up' upwards
docs: reporting-issues: improve text on initial write-up
docs: reporting-issues: improve text on bug verification
docs: reporting-issues: improve text on non-regressions in stable
docs: reporting-issues: improve text on second search
docs: reporting-issues: make collecting files a separate step
docs: reporting-issues: separate steps for optimizing and submitting
reports
docs: reporting-issues: separate steps for follow-up tasks
docs: reporting-issues: fix a few line breaks
.../admin-guide/reporting-issues.rst | 2958 ++++++++---------
1 file changed, 1426 insertions(+), 1532 deletions(-)
base-commit: b14a05303f06d951c6ef7e23e5c8f3e3be21e17e
--
2.51.0
^ permalink raw reply
* [PATCH 21/21] Docs: add Functions parameters order section
From: Yury Norov (NVIDIA) @ 2025-10-25 16:40 UTC (permalink / raw)
To: Linus Torvalds, Linus Walleij, Nicolas Frattaroli,
Jonathan Corbet, workflows, linux-doc, linux-kernel
Cc: Yury Norov (NVIDIA), Rasmus Villemoes
In-Reply-To: <20251025164023.308884-1-yury.norov@gmail.com>
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.
+
7) Centralized exiting of functions
-----------------------------------
--
2.43.0
^ permalink raw reply related
* [PATCH 21/21] Docs: add Functions parameters order section
From: Yury Norov (NVIDIA) @ 2025-10-25 16:33 UTC (permalink / raw)
To: Linus Walleij, Lee Jones, linux-arm-kernel, linux-kernel,
Jonathan Corbet, workflows, linux-doc
Cc: Yury Norov (NVIDIA)
In-Reply-To: <20251025162858.305236-1-yury.norov@gmail.com>
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.
+
7) Centralized exiting of functions
-----------------------------------
--
2.43.0
^ permalink raw reply related
* [PATCH v3] checkpatch: add uninitialized pointer with __free attribute check
From: Ally Heev @ 2025-10-25 7:56 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams, Ally Heev
uninitialized pointers with __free attribute can cause undefined
behaviour as the memory allocated to the pointer is freed
automatically when the pointer goes out of scope.
add check in checkpatch to detect such issues
Suggested-by: Dan Carpenter <dan.carpenter@linaro.org>
Link: https://lore.kernel.org/all/8a4c0b43-cf63-400d-b33d-d9c447b7e0b9@suswa.mountain/
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Ally Heev <allyheev@gmail.com>
---
Testing:
ran checkpatch.pl before and after the change on
crypto/asymmetric_keys/x509_public_key.c, which has
both initialized with NULL and uninitialized pointers
---
Changes in v3:
- remove $FreeAttribute
- Link to v2: https://lore.kernel.org/r/20251024-aheev-checkpatch-uninitialized-free-v2-0-16c0900e8130@gmail.com
Changes in v2:
- change cover letter and title to reflect new changes
- fix regex to handle multiple declarations in a single line case
- convert WARN to ERROR for uninitialized pointers
- add a new WARN for pointers initialized with NULL
- NOTE: tried handling multiple declarations on a single line by splitting
them and matching the parts with regex, but, it turned out to be
complex and overkill. Moreover, multi-line declarations pose a threat
- Link to v1: https://lore.kernel.org/r/20251021-aheev-checkpatch-uninitialized-free-v1-1-18fb01bc6a7a@gmail.com
---
Documentation/dev-tools/checkpatch.rst | 5 +++++
scripts/checkpatch.pl | 6 ++++++
2 files changed, 11 insertions(+)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index d5c47e560324fb2399a5b1bc99c891ed1de10535..1a304bf38bcd27e50bbb7cd4383b07ac54d20b0a 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -1009,6 +1009,11 @@ Functions and Variables
return bar;
+ **UNINITIALIZED_PTR_WITH_FREE**
+ Pointers with __free attribute should be initialized. Not doing so
+ may lead to undefined behavior as the memory allocated (garbage,
+ in case not initialized) to the pointer is freed automatically
+ when the pointer goes out of scope.
Permissions
-----------
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 92669904eecc7a8d2afd3f2625528e02b6d17cd6..e697d81d71c0b3628f7b59807e8bc40d582621bb 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -7721,6 +7721,12 @@ sub process {
ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
}
}
+
+# check for uninitialized pointers with __free attribute
+ while ($line =~ /\*\s*($Ident)\s+__free\s*\(\s*$Ident\s*\)\s*[,;]/g) {
+ ERROR("UNINITIALIZED_PTR_WITH_FREE",
+ "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
+ }
}
# If we have no input at all, then there is nothing to report on
---
base-commit: 6548d364a3e850326831799d7e3ea2d7bb97ba08
change-id: 20251021-aheev-checkpatch-uninitialized-free-5c39f75e10a1
Best regards,
--
Ally Heev <allyheev@gmail.com>
^ permalink raw reply related
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: ally heev @ 2025-10-25 6:29 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <20251024-aheev-checkpatch-uninitialized-free-v2-2-16c0900e8130@gmail.com>
Based on the comments. I will drop this patch in next version
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: ally heev @ 2025-10-25 6:23 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: <aPvAm1E7CvQfOIuS@stanley.mountain>
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 ? 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
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: ally heev @ 2025-10-25 6:17 UTC (permalink / raw)
To: Joe Perches, Dwaipayan Ray, Lukas Bulwahn, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <769268a5035b5a711a375591c25d48d077b46faa.camel@perches.com>
On Fri, 2025-10-24 at 11:01 -0700, Joe Perches wrote:
[..]
> > @@ -7728,6 +7728,12 @@ sub process {
> > ERROR("UNINITIALIZED_PTR_WITH_FREE",
> > "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> > }
> > +
> > +# check for pointers with __free attribute initialized to NULL
> > + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*=\s*NULL\b/g) {
> > + WARN("NULL_INITIALIZED_PTR_WITH_FREE",
> > + "pointer '$1' with __free attribute should be initialized to a non-NULL address\n" . $herecurr);
> > + }
> > }
>
> I think this a poor idea as almost all the instances where this
> initialization is done are fine.
>
> And there are a lot of them.
>
> $ git grep -P '\b__free\b.*=\s*NULL\s*;' | wc -l
> 490
Sorry for not checking this earlier. I looked at quite a few of them
none were real issues
>
> And what about these uses that depend on struct path members
> .mnt and .dentry being NULL.
>
> $ git grep -P '\b__free\b.*=\s*\{.*\}\s*;'
> fs/configfs/symlink.c: struct path path __free(path_put) = {};
> fs/fhandle.c: struct path path __free(path_put) = {};
> fs/file_attr.c: struct path filepath __free(path_put) = {};
> fs/file_attr.c: struct path filepath __free(path_put) = {};
> fs/namei.c: struct path parent_path __free(path_put) = {};
> fs/namei.c: struct path parent_path __free(path_put) = {};
> fs/namespace.c: struct path old_path __free(path_put) = {};
> fs/namespace.c: struct path path __free(path_put) = {};
> fs/namespace.c: struct path old_path __free(path_put) = {};
> fs/namespace.c: struct path path __free(path_put) = {};
> fs/namespace.c: struct path to_path __free(path_put) = {};
> fs/namespace.c: struct path from_path __free(path_put) = {};
> fs/namespace.c: struct path new __free(path_put) = {};
> fs/namespace.c: struct path old __free(path_put) = {};
> fs/namespace.c: struct path root __free(path_put) = {};
> fs/namespace.c: struct klistmount kls __free(klistmount_free) = {};
> fs/namespace.c: struct path fs_root __free(path_put) = {};
> fs/nsfs.c: struct path path __free(path_put) = {};
> fs/nsfs.c: struct path path __free(path_put) = {};
> fs/nsfs.c: struct path path __free(path_put) = {};
> fs/overlayfs/params.c: struct path layer_path __free(path_put) = {};
> fs/overlayfs/params.c: struct path path __free(path_put) = {};
> fs/pidfs.c: struct path path __free(path_put) = {};
> include/linux/path.h: * struct path path __free(path_put) = {};
> kernel/acct.c: struct path internal __free(path_put) = {}; // in that order
> kernel/trace/trace_uprobe.c: struct path path __free(path_put) = {};
These are not valid issues too
^ permalink raw reply
* Re: [PATCH v2 1/2] checkpatch: add uninitialized pointer with __free attribute check
From: ally heev @ 2025-10-25 3:37 UTC (permalink / raw)
To: Joe Perches, Dwaipayan Ray, Lukas Bulwahn, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <026a32413b0c9e4edb5d3ab411d18134078430d8.camel@perches.com>
On Fri, 2025-10-24 at 11:14 -0700, Joe Perches wrote:
> On Fri, 2025-10-24 at 22:59 +0530, Ally Heev wrote:
> > uninitialized pointers with __free attribute can cause undefined
> > behaviour as the memory allocated to the pointer is freed
> > automatically when the pointer goes out of scope.
> > add check in checkpatch to detect such issues
> >
> > Suggested-by: Dan Carpenter <dan.carpenter@linaro.org>
> > Link: https://lore.kernel.org/all/8a4c0b43-cf63-400d-b33d-d9c447b7e0b9@suswa.mountain/
> > Acked-by: Dan Williams <dan.j.williams@intel.com>
> > Signed-off-by: Ally Heev <allyheev@gmail.com>
> > ---
> > Documentation/dev-tools/checkpatch.rst | 5 +++++
> > scripts/checkpatch.pl | 7 +++++++
> > 2 files changed, 12 insertions(+)
> >
> > diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> > index d5c47e560324fb2399a5b1bc99c891ed1de10535..1a304bf38bcd27e50bbb7cd4383b07ac54d20b0a 100644
> > --- a/Documentation/dev-tools/checkpatch.rst
> > +++ b/Documentation/dev-tools/checkpatch.rst
> > @@ -1009,6 +1009,11 @@ Functions and Variables
> >
> > return bar;
> >
> > + **UNINITIALIZED_PTR_WITH_FREE**
> > + Pointers with __free attribute should be initialized. Not doing so
> > + may lead to undefined behavior as the memory allocated (garbage,
> > + in case not initialized) to the pointer is freed automatically
> > + when the pointer goes out of scope.
> >
> > Permissions
> > -----------
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> > index 92669904eecc7a8d2afd3f2625528e02b6d17cd6..1009a4a065e910143dabeee6640b3b3a4bd3fe06 100755
> > --- a/scripts/checkpatch.pl
> > +++ b/scripts/checkpatch.pl
> > @@ -509,6 +509,7 @@ our $InitAttributeData = qr{$InitAttributePrefix(?:initdata\b)};
> > our $InitAttributeConst = qr{$InitAttributePrefix(?:initconst\b)};
> > our $InitAttributeInit = qr{$InitAttributePrefix(?:init\b)};
> > our $InitAttribute = qr{$InitAttributeData|$InitAttributeConst|$InitAttributeInit};
> > +our $FreeAttribute = qr{__free\s*\(\s*$Ident\s*\)};
>
> If you are really suggesting using this, and I don't think it's
> particularly useful, please use
>
> out $InitAttributeFree = qr{$InitAttributePrefix(?:free\s*\(\s*$Ident\s*\)};
Thanks, I'll check it out
> >
> > # Notes to $Attribute:
> > # We need \b after 'init' otherwise 'initconst' will cause a false positive in a check
> > @@ -7721,6 +7722,12 @@ sub process {
> > ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
> > }
> > }
> > +
> > +# check for uninitialized pointers with __free attribute
> > + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*[,;]/g) {
> > + ERROR("UNINITIALIZED_PTR_WITH_FREE",
> > + "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> > + }
> > }
> >
> > # If we have no input at all, then there is nothing to report on
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: dan.j.williams @ 2025-10-24 18:37 UTC (permalink / raw)
To: Joe Perches, dan.j.williams, Ally Heev, Dwaipayan Ray,
Lukas Bulwahn, Jonathan Corbet, Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm
In-Reply-To: <df0d47c9ca7e984a38f56c6f0ca4696cd4ff1b21.camel@perches.com>
Joe Perches wrote:
[..]
> > > And there are a lot of them.
> > >
> > > $ git grep -P '\b__free\b.*=\s*NULL\s*;' | wc -l
> > > 490
> >
> > That is significant. ...but you did say "almost" above. What about
> > moving this from WARN level to CHK level?
>
> I have no idea how many instances in the tree are inappropriate.
> Do you? I believe it to be a difficult analysis problem.
>
> But given the number is likely to be extremely low, I think it should
> not be added to checkpatch even as a CHK.
>
> If you can show that the reporting rate of defects is significant,
> say >10%, then OK, but I rather doubt it's that high.
Fair enough. Ally, thanks for taking a look.
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: Joe Perches @ 2025-10-24 18:23 UTC (permalink / raw)
To: dan.j.williams, Ally Heev, Dwaipayan Ray, Lukas Bulwahn,
Jonathan Corbet, Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm
In-Reply-To: <68fbc211c59b9_10e910034@dwillia2-mobl4.notmuch>
On Fri, 2025-10-24 at 11:14 -0700, dan.j.williams@intel.com wrote:
> Joe Perches wrote:
> > On Fri, 2025-10-24 at 22:59 +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>
> > []
> > > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> > []
> > > @@ -7728,6 +7728,12 @@ sub process {
> > > ERROR("UNINITIALIZED_PTR_WITH_FREE",
> > > "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> > > }
> > > +
> > > +# check for pointers with __free attribute initialized to NULL
> > > + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*=\s*NULL\b/g) {
> > > + WARN("NULL_INITIALIZED_PTR_WITH_FREE",
> > > + "pointer '$1' with __free attribute should be initialized to a non-NULL address\n" . $herecurr);
> > > + }
> > > }
> >
> > I think this a poor idea as almost all the instances where this
> > initialization is done are fine.
> >
> > And there are a lot of them.
> >
> > $ git grep -P '\b__free\b.*=\s*NULL\s*;' | wc -l
> > 490
>
> That is significant. ...but you did say "almost" above. What about
> moving this from WARN level to CHK level?
I have no idea how many instances in the tree are inappropriate.
Do you? I believe it to be a difficult analysis problem.
But given the number is likely to be extremely low, I think it should
not be added to checkpatch even as a CHK.
If you can show that the reporting rate of defects is significant,
say >10%, then OK, but I rather doubt it's that high.
^ permalink raw reply
* Re: [PATCH v2 1/2] checkpatch: add uninitialized pointer with __free attribute check
From: Joe Perches @ 2025-10-24 18:14 UTC (permalink / raw)
To: Ally Heev, Dwaipayan Ray, Lukas Bulwahn, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <20251024-aheev-checkpatch-uninitialized-free-v2-1-16c0900e8130@gmail.com>
On Fri, 2025-10-24 at 22:59 +0530, Ally Heev wrote:
> uninitialized pointers with __free attribute can cause undefined
> behaviour as the memory allocated to the pointer is freed
> automatically when the pointer goes out of scope.
> add check in checkpatch to detect such issues
>
> Suggested-by: Dan Carpenter <dan.carpenter@linaro.org>
> Link: https://lore.kernel.org/all/8a4c0b43-cf63-400d-b33d-d9c447b7e0b9@suswa.mountain/
> Acked-by: Dan Williams <dan.j.williams@intel.com>
> Signed-off-by: Ally Heev <allyheev@gmail.com>
> ---
> Documentation/dev-tools/checkpatch.rst | 5 +++++
> scripts/checkpatch.pl | 7 +++++++
> 2 files changed, 12 insertions(+)
>
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> index d5c47e560324fb2399a5b1bc99c891ed1de10535..1a304bf38bcd27e50bbb7cd4383b07ac54d20b0a 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -1009,6 +1009,11 @@ Functions and Variables
>
> return bar;
>
> + **UNINITIALIZED_PTR_WITH_FREE**
> + Pointers with __free attribute should be initialized. Not doing so
> + may lead to undefined behavior as the memory allocated (garbage,
> + in case not initialized) to the pointer is freed automatically
> + when the pointer goes out of scope.
>
> Permissions
> -----------
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index 92669904eecc7a8d2afd3f2625528e02b6d17cd6..1009a4a065e910143dabeee6640b3b3a4bd3fe06 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -509,6 +509,7 @@ our $InitAttributeData = qr{$InitAttributePrefix(?:initdata\b)};
> our $InitAttributeConst = qr{$InitAttributePrefix(?:initconst\b)};
> our $InitAttributeInit = qr{$InitAttributePrefix(?:init\b)};
> our $InitAttribute = qr{$InitAttributeData|$InitAttributeConst|$InitAttributeInit};
> +our $FreeAttribute = qr{__free\s*\(\s*$Ident\s*\)};
If you are really suggesting using this, and I don't think it's
particularly useful, please use
out $InitAttributeFree = qr{$InitAttributePrefix(?:free\s*\(\s*$Ident\s*\)};
>
> # Notes to $Attribute:
> # We need \b after 'init' otherwise 'initconst' will cause a false positive in a check
> @@ -7721,6 +7722,12 @@ sub process {
> ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
> }
> }
> +
> +# check for uninitialized pointers with __free attribute
> + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*[,;]/g) {
> + ERROR("UNINITIALIZED_PTR_WITH_FREE",
> + "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> + }
> }
>
> # If we have no input at all, then there is nothing to report on
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: dan.j.williams @ 2025-10-24 18:14 UTC (permalink / raw)
To: Joe Perches, Ally Heev, Dwaipayan Ray, Lukas Bulwahn,
Jonathan Corbet, Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <769268a5035b5a711a375591c25d48d077b46faa.camel@perches.com>
Joe Perches wrote:
> On Fri, 2025-10-24 at 22:59 +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>
> []
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
> > @@ -7728,6 +7728,12 @@ sub process {
> > ERROR("UNINITIALIZED_PTR_WITH_FREE",
> > "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> > }
> > +
> > +# check for pointers with __free attribute initialized to NULL
> > + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*=\s*NULL\b/g) {
> > + WARN("NULL_INITIALIZED_PTR_WITH_FREE",
> > + "pointer '$1' with __free attribute should be initialized to a non-NULL address\n" . $herecurr);
> > + }
> > }
>
> I think this a poor idea as almost all the instances where this
> initialization is done are fine.
>
> And there are a lot of them.
>
> $ git grep -P '\b__free\b.*=\s*NULL\s*;' | wc -l
> 490
That is significant. ...but you did say "almost" above. What about
moving this from WARN level to CHK level?
With that change you can add:
Acked-by: Dan Williams <dan.j.williams@intel.com>
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: Dan Carpenter @ 2025-10-24 18:08 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: <20251024-aheev-checkpatch-uninitialized-free-v2-2-16c0900e8130@gmail.com>
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
^ permalink raw reply
* Re: [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: Joe Perches @ 2025-10-24 18:01 UTC (permalink / raw)
To: Ally Heev, Dwaipayan Ray, Lukas Bulwahn, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <20251024-aheev-checkpatch-uninitialized-free-v2-2-16c0900e8130@gmail.com>
On Fri, 2025-10-24 at 22:59 +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>
[]
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> @@ -7728,6 +7728,12 @@ sub process {
> ERROR("UNINITIALIZED_PTR_WITH_FREE",
> "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
> }
> +
> +# check for pointers with __free attribute initialized to NULL
> + while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*=\s*NULL\b/g) {
> + WARN("NULL_INITIALIZED_PTR_WITH_FREE",
> + "pointer '$1' with __free attribute should be initialized to a non-NULL address\n" . $herecurr);
> + }
> }
I think this a poor idea as almost all the instances where this
initialization is done are fine.
And there are a lot of them.
$ git grep -P '\b__free\b.*=\s*NULL\s*;' | wc -l
490
And what about these uses that depend on struct path members
.mnt and .dentry being NULL.
$ git grep -P '\b__free\b.*=\s*\{.*\}\s*;'
fs/configfs/symlink.c: struct path path __free(path_put) = {};
fs/fhandle.c: struct path path __free(path_put) = {};
fs/file_attr.c: struct path filepath __free(path_put) = {};
fs/file_attr.c: struct path filepath __free(path_put) = {};
fs/namei.c: struct path parent_path __free(path_put) = {};
fs/namei.c: struct path parent_path __free(path_put) = {};
fs/namespace.c: struct path old_path __free(path_put) = {};
fs/namespace.c: struct path path __free(path_put) = {};
fs/namespace.c: struct path old_path __free(path_put) = {};
fs/namespace.c: struct path path __free(path_put) = {};
fs/namespace.c: struct path to_path __free(path_put) = {};
fs/namespace.c: struct path from_path __free(path_put) = {};
fs/namespace.c: struct path new __free(path_put) = {};
fs/namespace.c: struct path old __free(path_put) = {};
fs/namespace.c: struct path root __free(path_put) = {};
fs/namespace.c: struct klistmount kls __free(klistmount_free) = {};
fs/namespace.c: struct path fs_root __free(path_put) = {};
fs/nsfs.c: struct path path __free(path_put) = {};
fs/nsfs.c: struct path path __free(path_put) = {};
fs/nsfs.c: struct path path __free(path_put) = {};
fs/overlayfs/params.c: struct path layer_path __free(path_put) = {};
fs/overlayfs/params.c: struct path path __free(path_put) = {};
fs/pidfs.c: struct path path __free(path_put) = {};
include/linux/path.h: * struct path path __free(path_put) = {};
kernel/acct.c: struct path internal __free(path_put) = {}; // in that order
kernel/trace/trace_uprobe.c: struct path path __free(path_put) = {};
^ permalink raw reply
* [PATCH v2 2/2] add check for pointers with __free attribute initialized to NULL
From: Ally Heev @ 2025-10-24 17:29 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams, Ally Heev
In-Reply-To: <20251024-aheev-checkpatch-uninitialized-free-v2-0-16c0900e8130@gmail.com>
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>
---
Documentation/dev-tools/checkpatch.rst | 6 ++++++
scripts/checkpatch.pl | 6 ++++++
2 files changed, 12 insertions(+)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index 1a304bf38bcd27e50bbb7cd4383b07ac54d20b0a..c39213b814f487290d2b0e5d320a4313ada9bbad 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -1015,6 +1015,12 @@ Functions and Variables
in case not initialized) to the pointer is freed automatically
when the pointer goes out of scope.
+ **NULL_INITIALIZED_PTR_WITH_FREE**
+ Pointers with __free attribute should not be initialized to NULL.
+ Always define and assign such pointers in one statement.
+
+ See: https://docs.kernel.org/core-api/cleanup.html
+
Permissions
-----------
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 1009a4a065e910143dabeee6640b3b3a4bd3fe06..cf186dafc191f1c39d01b3660f19101f6cc61a82 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -7728,6 +7728,12 @@ sub process {
ERROR("UNINITIALIZED_PTR_WITH_FREE",
"pointer '$1' with __free attribute should be initialized\n" . $herecurr);
}
+
+# check for pointers with __free attribute initialized to NULL
+ while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*=\s*NULL\b/g) {
+ WARN("NULL_INITIALIZED_PTR_WITH_FREE",
+ "pointer '$1' with __free attribute should be initialized to a non-NULL address\n" . $herecurr);
+ }
}
# If we have no input at all, then there is nothing to report on
--
2.47.3
^ permalink raw reply related
* [PATCH v2 1/2] checkpatch: add uninitialized pointer with __free attribute check
From: Ally Heev @ 2025-10-24 17:29 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams, Ally Heev
In-Reply-To: <20251024-aheev-checkpatch-uninitialized-free-v2-0-16c0900e8130@gmail.com>
uninitialized pointers with __free attribute can cause undefined
behaviour as the memory allocated to the pointer is freed
automatically when the pointer goes out of scope.
add check in checkpatch to detect such issues
Suggested-by: Dan Carpenter <dan.carpenter@linaro.org>
Link: https://lore.kernel.org/all/8a4c0b43-cf63-400d-b33d-d9c447b7e0b9@suswa.mountain/
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Ally Heev <allyheev@gmail.com>
---
Documentation/dev-tools/checkpatch.rst | 5 +++++
scripts/checkpatch.pl | 7 +++++++
2 files changed, 12 insertions(+)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index d5c47e560324fb2399a5b1bc99c891ed1de10535..1a304bf38bcd27e50bbb7cd4383b07ac54d20b0a 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -1009,6 +1009,11 @@ Functions and Variables
return bar;
+ **UNINITIALIZED_PTR_WITH_FREE**
+ Pointers with __free attribute should be initialized. Not doing so
+ may lead to undefined behavior as the memory allocated (garbage,
+ in case not initialized) to the pointer is freed automatically
+ when the pointer goes out of scope.
Permissions
-----------
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 92669904eecc7a8d2afd3f2625528e02b6d17cd6..1009a4a065e910143dabeee6640b3b3a4bd3fe06 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -509,6 +509,7 @@ our $InitAttributeData = qr{$InitAttributePrefix(?:initdata\b)};
our $InitAttributeConst = qr{$InitAttributePrefix(?:initconst\b)};
our $InitAttributeInit = qr{$InitAttributePrefix(?:init\b)};
our $InitAttribute = qr{$InitAttributeData|$InitAttributeConst|$InitAttributeInit};
+our $FreeAttribute = qr{__free\s*\(\s*$Ident\s*\)};
# Notes to $Attribute:
# We need \b after 'init' otherwise 'initconst' will cause a false positive in a check
@@ -7721,6 +7722,12 @@ sub process {
ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
}
}
+
+# check for uninitialized pointers with __free attribute
+ while ($line =~ /\*\s*($Ident)\s+$FreeAttribute\s*[,;]/g) {
+ ERROR("UNINITIALIZED_PTR_WITH_FREE",
+ "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
+ }
}
# If we have no input at all, then there is nothing to report on
--
2.47.3
^ permalink raw reply related
* [PATCH v2 0/2] checkpatch: add checks incorrectly initialized pointers with __free attr
From: Ally Heev @ 2025-10-24 17:29 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams, Ally Heev
Badly initialized pointers with __free attr can
cause cleanup issues. So,
Adding checks for
- uninitialized pointers
- initialized pointers with NULL
Testing:
ran checkpatch.pl before and after the change on
crypto/asymmetric_keys/x509_public_key.c, which has
both initialized with NULL and uninitialized pointers
---
Changes in v2:
- change cover letter and title to reflect new changes
- fix regex to handle multiple declarations in a single line case
- convert WARN to ERROR for uninitialized pointers
- add a new WARN for pointers initialized with NULL
- NOTE: tried handling multiple declarations on a single line by splitting
them and matching the parts with regex, but, it turned out to be
complex and overkill. Moreover, multi-line declarations pose a threat
- Link to v1: https://lore.kernel.org/r/20251021-aheev-checkpatch-uninitialized-free-v1-1-18fb01bc6a7a@gmail.com
---
Ally Heev (2):
checkpatch: add uninitialized pointer with __free attribute check
add check for pointers with __free attribute initialized to NULL
Documentation/dev-tools/checkpatch.rst | 11 +++++++++++
scripts/checkpatch.pl | 13 +++++++++++++
2 files changed, 24 insertions(+)
---
base-commit: 6548d364a3e850326831799d7e3ea2d7bb97ba08
change-id: 20251021-aheev-checkpatch-uninitialized-free-5c39f75e10a1
Best regards,
--
Ally Heev <allyheev@gmail.com>
^ permalink raw reply
* Re: [PATCH] checkpatch: add uninitialized pointer with __free attribute check
From: ally heev @ 2025-10-23 15:14 UTC (permalink / raw)
To: Joe Perches, Dwaipayan Ray, Lukas Bulwahn, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams
In-Reply-To: <5e11f1bacb6430e1331f02e3e0e326a78e5b0d12.camel@perches.com>
On Tue, 2025-10-21 at 10:06 -0700, Joe Perches wrote:
> On Tue, 2025-10-21 at 17:00 +0530, Ally Heev wrote:
> > uninitialized pointers with __free attribute can cause undefined
> > behaviour as the memory allocated to the pointer is freed
> > automatically when the pointer goes out of scope.
> > add check in checkpatch to detect such issues
>
> Seems sensible. Couple minor points below:
>
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> []
> > @@ -7721,6 +7721,12 @@ sub process {
> > ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
> > }
> > }
> > +
> > +# check for uninitialized pointers with __free attribute
> > + if ($line =~ /\s*$Type\s*($Ident)\s+__free\s*\(\s*$Ident\s*\)\s*;/) {
>
> The leading \s* isn't useful, but \b should be used.
Sure
>
> Perhaps verify that $Type is a pointer as well
>
> if ($line =~ /\b($Type)\s*($Ident)\s*__free\s*\(\s*$Ident\s*\)\s*;/ &&
> $1 =~ /\*\s*$/) {
>
> to avoid things like:
>
> drivers/net/ethernet/microsoft/mana/gdma_main.c: cpumask_var_t cpus __free(free_cpumask_var);
>
>
> > + WARN("UNINITIALIZED_PTR_WITH_FREE",
> > + "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
>
> pointer '$2' etc
>
Nice find. Thanks!
> And this would not find uses like the below where another definition
> is done before a definition with __free on the same line:
>
> crypto/testmgr.c: u8 *ptr, *key __free(kfree);
I will add the check for each pointer defined on the same line
^ permalink raw reply
* Re: [PATCH] checkpatch: add uninitialized pointer with __free attribute check
From: Dan Carpenter @ 2025-10-23 14:01 UTC (permalink / raw)
To: ally heev
Cc: dan.j.williams, 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
In-Reply-To: <CAMB6jUG+ES6XY7NL5TF-hFVDmz6O5rd9T-HNk7Q+pJA2_9g4Mw@mail.gmail.com>
On Thu, Oct 23, 2025 at 04:38:43PM +0530, ally heev wrote:
> I will take this back. Found this in `include/linux/cleanup.h`
> ```
> * Given that the "__free(...) = NULL" pattern for variables defined at
> * the top of the function poses this potential interdependency problem
> * the recommendation is to always define and assign variables in one
> * statement and not group variable definitions at the top of the
> * function when __free() is used.
> ```
Ah, right.
regards,
dan carpenter
^ 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