0001 .. _submitchecklist:
0002
0003 Linux Kernel patch submission checklist
0004 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0005
0006 Here are some basic things that developers should do if they want to see their
0007 kernel patch submissions accepted more quickly.
0008
0009 These are all above and beyond the documentation that is provided in
0010 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
0011 and elsewhere regarding submitting Linux kernel patches.
0012
0013
0014 1) If you use a facility then #include the file that defines/declares
0015 that facility. Don't depend on other header files pulling in ones
0016 that you use.
0017
0018 2) Builds cleanly:
0019
0020 a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
0021 ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors.
0022
0023 b) Passes ``allnoconfig``, ``allmodconfig``
0024
0025 c) Builds successfully when using ``O=builddir``
0026
0027 d) Any Documentation/ changes build successfully without new warnings/errors.
0028 Use ``make htmldocs`` or ``make pdfdocs`` to check the build and
0029 fix any issues.
0030
0031 3) Builds on multiple CPU architectures by using local cross-compile tools
0032 or some other build farm.
0033
0034 4) ppc64 is a good architecture for cross-compilation checking because it
0035 tends to use ``unsigned long`` for 64-bit quantities.
0036
0037 5) Check your patch for general style as detailed in
0038 :ref:`Documentation/process/coding-style.rst <codingstyle>`.
0039 Check for trivial violations with the patch style checker prior to
0040 submission (``scripts/checkpatch.pl``).
0041 You should be able to justify all violations that remain in
0042 your patch.
0043
0044 6) Any new or modified ``CONFIG`` options do not muck up the config menu and
0045 default to off unless they meet the exception criteria documented in
0046 ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
0047
0048 7) All new ``Kconfig`` options have help text.
0049
0050 8) Has been carefully reviewed with respect to relevant ``Kconfig``
0051 combinations. This is very hard to get right with testing -- brainpower
0052 pays off here.
0053
0054 9) Check cleanly with sparse.
0055
0056 10) Use ``make checkstack`` and fix any problems that it finds.
0057
0058 .. note::
0059
0060 ``checkstack`` does not point out problems explicitly,
0061 but any one function that uses more than 512 bytes on the stack is a
0062 candidate for change.
0063
0064 11) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
0065 (Not required for static functions, but OK there also.) Use
0066 ``make htmldocs`` or ``make pdfdocs`` to check the
0067 :ref:`kernel-doc <kernel_doc>` and fix any issues.
0068
0069 12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
0070 ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
0071 ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
0072 ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all
0073 simultaneously enabled.
0074
0075 13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
0076 ``CONFIG_PREEMPT.``
0077
0078 14) All codepaths have been exercised with all lockdep features enabled.
0079
0080 15) All new ``/proc`` entries are documented under ``Documentation/``
0081
0082 16) All new kernel boot parameters are documented in
0083 ``Documentation/admin-guide/kernel-parameters.rst``.
0084
0085 17) All new module parameters are documented with ``MODULE_PARM_DESC()``
0086
0087 18) All new userspace interfaces are documented in ``Documentation/ABI/``.
0088 See ``Documentation/ABI/README`` for more information.
0089 Patches that change userspace interfaces should be CCed to
0090 linux-api@vger.kernel.org.
0091
0092 19) Has been checked with injection of at least slab and page-allocation
0093 failures. See ``Documentation/fault-injection/``.
0094
0095 If the new code is substantial, addition of subsystem-specific fault
0096 injection might be appropriate.
0097
0098 20) Newly-added code has been compiled with ``gcc -W`` (use
0099 ``make KCFLAGS=-W``). This will generate lots of noise, but is good
0100 for finding bugs like "warning: comparison between signed and unsigned".
0101
0102 21) Tested after it has been merged into the -mm patchset to make sure
0103 that it still works with all of the other queued patches and various
0104 changes in the VM, VFS, and other subsystems.
0105
0106 22) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
0107 comment in the source code that explains the logic of what they are doing
0108 and why.
0109
0110 23) If any ioctl's are added by the patch, then also update
0111 ``Documentation/userspace-api/ioctl/ioctl-number.rst``.
0112
0113 24) If your modified source code depends on or uses any of the kernel
0114 APIs or features that are related to the following ``Kconfig`` symbols,
0115 then test multiple builds with the related ``Kconfig`` symbols disabled
0116 and/or ``=m`` (if that option is available) [not all of these at the
0117 same time, just various/random combinations of them]:
0118
0119 ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
0120 ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``).
