From 5c7944ca7b13978744ec83e131aef9255fdbabbe Mon Sep 17 00:00:00 2001 From: Abhishek Pandit-Subedi Date: Thu, 25 Jan 2024 16:53:11 -0800 Subject: coding-style: Add guidance to prefer dev_dbg During review, it was suggested that drivers only emit messages when something is wrong or it is a debug message. Document this as a formal recommendation. https://lore.kernel.org/linux-usb/2024012525-alienate-frown-916b@gregkh/ Signed-off-by: Abhishek Pandit-Subedi Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240125165311.1.I8d9c88e747e233917e527c7dad1feb8a18f070e2@changeid --- Documentation/process/coding-style.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index c48382c6b477..f8ec23fa89bc 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -899,7 +899,8 @@ which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a particular device, defines pr_notice(), pr_info(), -pr_warn(), pr_err(), etc. +pr_warn(), pr_err(), etc. When drivers are working properly they are quiet, +so prefer to use dev_dbg/pr_debug unless something is wrong. Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. However -- cgit From 932be49b71e7a67a288b29e78c45bd095a4be704 Mon Sep 17 00:00:00 2001 From: Thorsten Blum Date: Sat, 3 Feb 2024 00:13:16 +0100 Subject: Documentation: coding-style: Fix indentation in code-blocks - Remove spaces in C code-blocks to align error labels consistently - Replace tab characters with spaces in emacs-lisp code blocks Signed-off-by: Thorsten Blum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240202231316.7606-1-thorsten.blum@toblux.com --- Documentation/process/coding-style.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index f8ec23fa89bc..a15a2159b2a9 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -586,9 +586,9 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; @@ -679,7 +679,7 @@ values. To do the latter, you can stick the following in your .emacs file: (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) -- cgit From 185ea7676ef3220de1ee90f288df3601f83afda0 Mon Sep 17 00:00:00 2001 From: Thorsten Blum Date: Sat, 3 Feb 2024 23:39:26 +0100 Subject: Documentation: coding-style: Update syntax highlighting for code-blocks Use c and elisp instead of none in code-blocks Signed-off-by: Thorsten Blum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240203223926.5077-1-thorsten.blum@toblux.com --- Documentation/process/coding-style.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index a15a2159b2a9..9c7cf7347394 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -203,7 +203,7 @@ Do not unnecessarily use braces where a single statement will do. and -.. code-block:: none +.. code-block:: c if (condition) do_this(); @@ -660,7 +660,7 @@ make a good program). So, you can either get rid of GNU emacs, or change it to use saner values. To do the latter, you can stick the following in your .emacs file: -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" -- cgit From 40be2369dc0ee803b2bacf32471472604a948b88 Mon Sep 17 00:00:00 2001 From: Thorsten Blum Date: Mon, 5 Feb 2024 01:01:17 +0100 Subject: Documentation: multiple .rst files: Fix grammar and more consistent formatting sphinx.rst: - Remove unnecessary newline - Fix grammar s/on/in/ - Fix grammar s/check/checks/ - Capitalize heading "The C domain" changes.rst: - Remove colon after "pahole" to be consistent with other entries howto.rst: - Fix grammar s/you will/will you/ - Hyphenate "real-world problems" Signed-off-by: Thorsten Blum Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240205000117.3285-1-thorsten.blum@toblux.com --- Documentation/process/changes.rst | 4 ++-- Documentation/process/howto.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 50b3d1cb1115..4c1552160321 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -144,8 +144,8 @@ Bison Since Linux 4.16, the build system generates parsers during build. This requires bison 2.0 or later. -pahole: -------- +pahole +------ Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6c73889c98fc..eebda4910a88 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -351,8 +351,8 @@ Managing bug reports -------------------- One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, but you'll also learn to fix real world problems and you will +bugs reported by other people. Not only will you help to make the kernel +more stable, but you'll also learn to fix real-world problems and you will improve your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. -- cgit From 094666eed2ce7b7d0e384e7de6b5d53d66e69952 Mon Sep 17 00:00:00 2001 From: Jeffrey Hugo Date: Fri, 2 Feb 2024 09:41:19 -0700 Subject: Documentation: embargoed-hardware-issues.rst: Fix Trilok's email The servers for the @codeaurora domain have long been retired and any messages addressed to @codeaurora will bounce. Trilok has an entry in .mailmap, but the raw documentation files still list an old @codeaurora address. Update the address in the documentation files for anyone reading them. Signed-off-by: Jeffrey Hugo Reviewed-by: Carlos Bilbao Reviewed-by: Trilok Soni Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240202164119.4090703-1-quic_jhugo@quicinc.com --- Documentation/process/embargoed-hardware-issues.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index 31000f075707..bb2100228cc7 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -255,7 +255,7 @@ an involved disclosed party. The current ambassadors list: IBM Power Anton Blanchard IBM Z Christian Borntraeger Intel Tony Luck - Qualcomm Trilok Soni + Qualcomm Trilok Soni RISC-V Palmer Dabbelt Samsung Javier González -- cgit From 27103dddc2dafd32de3ac04f4ab94478f083f1ac Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Wed, 14 Feb 2024 15:09:53 -0500 Subject: Documentation: update mailing list addresses The mailman2 server running on lists.linuxfoundation.org will be shut down in very imminent future. Update all instances of obsolete list addresses throughout the tree with their new destinations. Signed-off-by: Konstantin Ryabitsev Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240214-lf-org-list-migration-v1-1-ef1eab4b1543@linuxfoundation.org --- Documentation/process/researcher-guidelines.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/process') diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst index d159cd4f5e5b..beb484c5965d 100644 --- a/Documentation/process/researcher-guidelines.rst +++ b/Documentation/process/researcher-guidelines.rst @@ -167,4 +167,4 @@ If no one can be found to internally review patches and you need help finding such a person, or if you have any other questions related to this document and the developer community's expectations, please reach out to the private Technical Advisory Board mailing list: -. +. -- cgit From 5969fbf302741c5faf7c25d481593918cad559c6 Mon Sep 17 00:00:00 2001 From: Lukas Bulwahn Date: Thu, 29 Feb 2024 04:07:41 +0100 Subject: docs: submit-checklist: structure by category While going through the submit checklist, the list order seemed rather random, probably just by historical coincidences of always adding yet the next point someone thought of at the end of the list. Structure and order them by the category of such activity, reviewing, documenting, checking with tools, building and testing. As the diff of the reordering is large: Review code now includes previous points 1, 5 and 22. Review Kconfig includes previous 6, 7 and 8. Documenting includes previous 11, 15, 16, 17, 18 and 23. Checking with tools includes previous 5, 9 and 10. Building includes previous 2, 3, 20 and 24. Testing includes previous 12, 13, 14, 19 and 21. Previous point 4 (compile for ppc64) was merged into point 3 (build for many architectures), as it was just a further note to cross-compiling. Previous point 5 was split into one in review and one in checking to have every previous point in the right category. Point 11 was shortened, as building documentation is mentioned already in Build your code, 1d. A note that was presented visually much too aggressive in the HTML view was turned into a simple "Note that..." sentence in the enumeration. The recommendation to test with the -mm patchset (previous 21, now testing, point 5) was updated to the current state of affairs to test with a recent tag of linux-next. Note that the previous first point still remains the first list even after reordering. Randy confirmed that it was important to Stephen Rothwell to keep 'include what you use' to be the first in the list. While at it, replace the reference to the obsolete CONFIG_DEBUG_SLAB with CONFIG_SLUB_DEBUG. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Lukas Bulwahn Signed-off-by: Jonathan Corbet Message-ID: <20240229030743.9125-2-lukas.bulwahn@gmail.com> --- Documentation/process/submit-checklist.rst | 157 +++++++++++++++-------------- 1 file changed, 84 insertions(+), 73 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index b1bc2d37bd0a..7d8dba942fe8 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -11,110 +11,121 @@ These are all above and beyond the documentation that is provided in and elsewhere regarding submitting Linux kernel patches. +*Review your code:* + 1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2) Builds cleanly: +2) Check your patch for general style as detailed in + :ref:`Documentation/process/coding-style.rst `. - a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and - ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. +3) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. - b) Passes ``allnoconfig``, ``allmodconfig`` - c) Builds successfully when using ``O=builddir`` +*Review Kconfig changes:* - d) Any Documentation/ changes build successfully without new warnings/errors. - Use ``make htmldocs`` or ``make pdfdocs`` to check the build and - fix any issues. +1) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. -3) Builds on multiple CPU architectures by using local cross-compile tools - or some other build farm. +2) All new ``Kconfig`` options have help text. -4) ppc64 is a good architecture for cross-compilation checking because it - tends to use ``unsigned long`` for 64-bit quantities. +3) Has been carefully reviewed with respect to relevant ``Kconfig`` + combinations. This is very hard to get right with testing---brainpower + pays off here. -5) Check your patch for general style as detailed in - :ref:`Documentation/process/coding-style.rst `. - Check for trivial violations with the patch style checker prior to - submission (``scripts/checkpatch.pl``). - You should be able to justify all violations that remain in - your patch. +*Provide documentation:* -6) Any new or modified ``CONFIG`` options do not muck up the config menu and - default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. +1) Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) -7) All new ``Kconfig`` options have help text. +2) All new ``/proc`` entries are documented under ``Documentation/`` -8) Has been carefully reviewed with respect to relevant ``Kconfig`` - combinations. This is very hard to get right with testing -- brainpower - pays off here. +3) All new kernel boot parameters are documented in + ``Documentation/admin-guide/kernel-parameters.rst``. + +4) All new module parameters are documented with ``MODULE_PARM_DESC()`` -9) Check cleanly with sparse. +5) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. + Patches that change userspace interfaces should be CCed to + linux-api@vger.kernel.org. -10) Use ``make checkstack`` and fix any problems that it finds. +6) If any ioctl's are added by the patch, then also update + ``Documentation/userspace-api/ioctl/ioctl-number.rst``. - .. note:: - ``checkstack`` does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. +*Check your code with tools:* -11) Include :ref:`kernel-doc ` to document global kernel APIs. - (Not required for static functions, but OK there also.) Use - ``make htmldocs`` or ``make pdfdocs`` to check the - :ref:`kernel-doc ` and fix any issues. +1) Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). + You should be able to justify all violations that remain in + your patch. -12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, - ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, - ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all - simultaneously enabled. +2) Check cleanly with sparse. -13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and - ``CONFIG_PREEMPT.`` +3) Use ``make checkstack`` and fix any problems that it finds. + Note that ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. -14) All codepaths have been exercised with all lockdep features enabled. -15) All new ``/proc`` entries are documented under ``Documentation/`` +*Build your code:* + +1) Builds cleanly: + + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. + + b) Passes ``allnoconfig``, ``allmodconfig`` + + c) Builds successfully when using ``O=builddir`` + + d) Any Documentation/ changes build successfully without new warnings/errors. + Use ``make htmldocs`` or ``make pdfdocs`` to check the build and + fix any issues. -16) All new kernel boot parameters are documented in - ``Documentation/admin-guide/kernel-parameters.rst``. +2) Builds on multiple CPU architectures by using local cross-compile tools + or some other build farm. Note that ppc64 is a good architecture for + cross-compilation checking because it tends to use ``unsigned long`` for + 64-bit quantities. -17) All new module parameters are documented with ``MODULE_PARM_DESC()`` +3) Newly-added code has been compiled with ``gcc -W`` (use + ``make KCFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". -18) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. - Patches that change userspace interfaces should be CCed to - linux-api@vger.kernel.org. +4) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the + same time, just various/random combinations of them]: -19) Has been checked with injection of at least slab and page-allocation - failures. See ``Documentation/fault-injection/``. + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). - If the new code is substantial, addition of subsystem-specific fault - injection might be appropriate. -20) Newly-added code has been compiled with ``gcc -W`` (use - ``make KCFLAGS=-W``). This will generate lots of noise, but is good - for finding bugs like "warning: comparison between signed and unsigned". +*Test your code:* -21) Tested after it has been merged into the -mm patchset to make sure - that it still works with all of the other queued patches and various - changes in the VM, VFS, and other subsystems. +1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. -22) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a - comment in the source code that explains the logic of what they are doing - and why. +2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` -23) If any ioctl's are added by the patch, then also update - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. +3) All codepaths have been exercised with all lockdep features enabled. -24) If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following ``Kconfig`` symbols, - then test multiple builds with the related ``Kconfig`` symbols disabled - and/or ``=m`` (if that option is available) [not all of these at the - same time, just various/random combinations of them]: +4) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). +5) Tested with the most recent tag of linux-next to make sure that it still + works with all of the other queued patches and various changes in the VM, + VFS, and other subsystems. -- cgit From 47c67ec1e8ef7372fa062dcb062f0de53d7aa2d2 Mon Sep 17 00:00:00 2001 From: Lukas Bulwahn Date: Thu, 29 Feb 2024 04:07:42 +0100 Subject: docs: submit-checklist: use subheadings During review (see Link), Jani Nikula suggested to use proper subheadings instead of using italics to indicate the different new top-level categories in the checklist. Further the top heading should follow the common scheme. Use subheadings. Adjust to common heading adornment. Link: https://lore.kernel.org/linux-doc/87o7c3mlwb.fsf@intel.com/ Signed-off-by: Lukas Bulwahn Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20240229030743.9125-3-lukas.bulwahn@gmail.com> --- Documentation/process/submit-checklist.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 7d8dba942fe8..e531dd504b6c 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -1,7 +1,8 @@ .. _submitchecklist: +======================================= Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +======================================= Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. @@ -10,8 +11,8 @@ These are all above and beyond the documentation that is provided in :ref:`Documentation/process/submitting-patches.rst ` and elsewhere regarding submitting Linux kernel patches. - -*Review your code:* +Review your code +================ 1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones @@ -24,8 +25,8 @@ and elsewhere regarding submitting Linux kernel patches. comment in the source code that explains the logic of what they are doing and why. - -*Review Kconfig changes:* +Review Kconfig changes +====================== 1) Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in @@ -37,7 +38,8 @@ and elsewhere regarding submitting Linux kernel patches. combinations. This is very hard to get right with testing---brainpower pays off here. -*Provide documentation:* +Provide documentation +===================== 1) Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) @@ -57,8 +59,8 @@ and elsewhere regarding submitting Linux kernel patches. 6) If any ioctl's are added by the patch, then also update ``Documentation/userspace-api/ioctl/ioctl-number.rst``. - -*Check your code with tools:* +Check your code with tools +========================== 1) Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). @@ -72,8 +74,8 @@ and elsewhere regarding submitting Linux kernel patches. but any one function that uses more than 512 bytes on the stack is a candidate for change. - -*Build your code:* +Build your code +=============== 1) Builds cleanly: @@ -107,8 +109,8 @@ and elsewhere regarding submitting Linux kernel patches. ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). - -*Test your code:* +Test your code +============== 1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, -- cgit