2016-09-21 11:51:05 +00:00
|
|
|
.. _submitchecklist:
|
|
|
|
|
2007-07-16 06:40:51 +00:00
|
|
|
Linux Kernel patch submission checklist
|
2016-09-19 11:08:01 +00:00
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2006-07-10 11:45:42 +00:00
|
|
|
Here are some basic things that developers should do if they want to see their
|
|
|
|
kernel patch submissions accepted more quickly.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2006-07-10 11:45:42 +00:00
|
|
|
These are all above and beyond the documentation that is provided in
|
2016-10-18 12:12:27 +00:00
|
|
|
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
2016-09-19 11:08:01 +00:00
|
|
|
and elsewhere regarding submitting Linux kernel patches.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
1) If you use a facility then #include the file that defines/declares
|
2010-03-10 23:21:59 +00:00
|
|
|
that facility. Don't depend on other header files pulling in ones
|
|
|
|
that you use.
|
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
2) Builds cleanly:
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
|
|
|
|
``=n``. No ``gcc`` warnings/errors, no linker warnings/errors.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
b) Passes ``allnoconfig``, ``allmodconfig``
|
2010-05-24 00:02:30 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
c) Builds successfully when using ``O=builddir``
|
|
|
|
|
2020-08-31 00:43:54 +00:00
|
|
|
d) Any Documentation/ changes build successfully without new warnings/errors.
|
|
|
|
Use ``make htmldocs`` or ``make pdfdocs`` to check the build and
|
|
|
|
fix any issues.
|
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
3) Builds on multiple CPU architectures by using local cross-compile tools
|
2009-12-16 00:46:59 +00:00
|
|
|
or some other build farm.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
4) ppc64 is a good architecture for cross-compilation checking because it
|
|
|
|
tends to use ``unsigned long`` for 64-bit quantities.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-21 11:51:05 +00:00
|
|
|
5) Check your patch for general style as detailed in
|
2016-10-18 12:12:27 +00:00
|
|
|
:ref:`Documentation/process/coding-style.rst <codingstyle>`.
|
2016-09-19 11:08:01 +00:00
|
|
|
Check for trivial violations with the patch style checker prior to
|
|
|
|
submission (``scripts/checkpatch.pl``).
|
2008-02-13 23:03:20 +00:00
|
|
|
You should be able to justify all violations that remain in
|
|
|
|
your patch.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2017-11-20 22:39:34 +00:00
|
|
|
6) Any new or modified ``CONFIG`` options do not muck up the config menu and
|
2017-12-12 10:46:51 +00:00
|
|
|
default to off unless they meet the exception criteria documented in
|
2019-06-12 17:52:48 +00:00
|
|
|
``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
7) All new ``Kconfig`` options have help text.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
8) Has been carefully reviewed with respect to relevant ``Kconfig``
|
2006-07-10 11:45:42 +00:00
|
|
|
combinations. This is very hard to get right with testing -- brainpower
|
|
|
|
pays off here.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
9) Check cleanly with sparse.
|
|
|
|
|
scripts: remove namespace.pl
namespace.pl is intended to help locate symbols which are defined but
are not used externally. The goal is to avoid bloat of the namespace in
the resulting kernel image.
The script relies on object data, and only finds unused symbols for the
configuration used to generate that object data. This results in a lot
of false positive warnings such as symbols only used by a single
architecture, or symbols which are used externally only under certain
configurations.
Running namespace.pl using allyesconfig, allmodconfig, and
x86_64_defconfig yields the following results:
* allmodconfig
* 11122 unique symbol names with no external reference
* 1194 symbols listed as multiply defined
* 214 symbols it can't resolve
* allyesconfig
* 10997 unique symbol names with no external reference
* 1194 symbols listed as multiply defined
* 214 symbols it can't resolve
* x86_64_defconfig
* 5757 unique symbol names with no external reference
* 528 symbols listed as multiply defined
* 154 symbols it can't resolve
The script also has no way to easily limit the scope of the checks to
a given subset of the kernel, such as only checking for symbols defined
within a module or subsystem.
Discussion on public mailing lists seems to indicate that many view the
tool output as suspect or not very useful (see discussions at [1] and
[2] for further context).
As described by Masahiro Yamada at [2], namespace.pl provides 3 types of
checks: listing multiply defined symbols, resolving external symbols,
and warnings about symbols with no reference.
The first category of issues is easily caught by the linker as any set
of multiply defined symbols should fail to link. The second category of
issues is also caught by linking, as undefined symbols would cause
issues. Even with modules, these types of issues where a module relies
on an external symbol are caught by modpost.
The remaining category of issues reported is the list of symbols with no
external reference, and is the primary motivation of this script.
However, it ought to be clear from the above examples that the output is
difficult to sort through. Even allyesconfig has ~10000 entries.
The current submit-checklist indicates that patches ought to go through
namespacecheck and fix any new issues arising. But that itself presents
problems. As described at [1], many cases of reports are due to
configuration where a function is used externally by some configuration
settings. Prominent maintainers appear to dislike changes modify code
such that symbols become static based on CONFIG_* flags ([3], and [4])
One possible solution is to adjust the advice and indicate that we only
care about the output of namespacecheck on allyesconfig or allmodconfig
builds...
However, given the discussion at [2], I suspect that few people are
actively using this tool. It doesn't have a maintainer in the
MAINTAINERS flie, and it produces so many warnings for unused symbols
that it is difficult to use effectively. Thus, I propose we simply
remove it.
[1] https://lore.kernel.org/netdev/20200708164812.384ae8ea@kicinski-fedora-pc1c0hjn.dhcp.thefacebook.com/
[2] https://lore.kernel.org/lkml/20190129204319.15238-1-jacob.e.keller@intel.com/
[3] https://lore.kernel.org/netdev/20190828.154744.2058157956381129672.davem@davemloft.net/
[4] https://lore.kernel.org/netdev/20190827210928.576c5fef@cakuba.netronome.com/
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
2020-10-10 00:18:44 +00:00
|
|
|
10) Use ``make checkstack`` and fix any problems that it finds.
|
2016-09-19 11:08:01 +00:00
|
|
|
|
|
|
|
.. note::
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
``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.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-21 11:51:05 +00:00
|
|
|
11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
|
2016-09-19 11:08:00 +00:00
|
|
|
(Not required for static functions, but OK there also.) Use
|
|
|
|
``make htmldocs`` or ``make pdfdocs`` to check the
|
|
|
|
:ref:`kernel-doc <kernel_doc>` and fix any issues.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
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.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
|
|
|
|
``CONFIG_PREEMPT.``
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
14) All codepaths have been exercised with all lockdep features enabled.
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
15) All new ``/proc`` entries are documented under ``Documentation/``
|
2006-06-23 09:05:49 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
16) All new kernel boot parameters are documented in
|
2016-10-18 12:12:27 +00:00
|
|
|
``Documentation/admin-guide/kernel-parameters.rst``.
|
2006-07-10 11:45:42 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
17) All new module parameters are documented with ``MODULE_PARM_DESC()``
|
2006-09-29 09:01:26 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
18) All new userspace interfaces are documented in ``Documentation/ABI/``.
|
2016-09-19 11:08:01 +00:00
|
|
|
See ``Documentation/ABI/README`` for more information.
|
2008-10-03 22:23:44 +00:00
|
|
|
Patches that change userspace interfaces should be CCed to
|
|
|
|
linux-api@vger.kernel.org.
|
2006-10-01 06:27:39 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
19) Check that it all passes ``make headers_check``.
|
2006-12-10 10:18:56 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
20) Has been checked with injection of at least slab and page-allocation
|
2016-09-19 11:08:01 +00:00
|
|
|
failures. See ``Documentation/fault-injection/``.
|
2006-12-10 10:18:56 +00:00
|
|
|
|
|
|
|
If the new code is substantial, addition of subsystem-specific fault
|
|
|
|
injection might be appropriate.
|
2007-01-23 04:40:36 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
21) Newly-added code has been compiled with ``gcc -W`` (use
|
2016-09-19 11:08:01 +00:00
|
|
|
``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good
|
|
|
|
for finding bugs like "warning: comparison between signed and unsigned".
|
2007-03-01 04:12:35 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
22) Tested after it has been merged into the -mm patchset to make sure
|
2007-03-01 04:12:35 +00:00
|
|
|
that it still works with all of the other queued patches and various
|
|
|
|
changes in the VM, VFS, and other subsystems.
|
2008-10-16 05:01:59 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
23) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
|
2016-09-19 11:08:01 +00:00
|
|
|
comment in the source code that explains the logic of what they are doing
|
|
|
|
and why.
|
2009-12-16 00:46:59 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
24) If any ioctl's are added by the patch, then also update
|
2020-04-14 16:48:35 +00:00
|
|
|
``Documentation/userspace-api/ioctl/ioctl-number.rst``.
|
2010-05-24 00:02:30 +00:00
|
|
|
|
2020-12-15 20:42:36 +00:00
|
|
|
25) If your modified source code depends on or uses any of the kernel
|
2016-09-19 11:08:01 +00:00
|
|
|
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
|
2010-05-24 00:02:30 +00:00
|
|
|
same time, just various/random combinations of them]:
|
|
|
|
|
2016-09-19 11:08:01 +00:00
|
|
|
``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``).
|