diff options
Diffstat (limited to 'Documentation/process')
20 files changed, 293 insertions, 93 deletions
diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst index e782ae2eef58..c3d0270bbfb3 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -1,3 +1,5 @@ +.. _development_process_intro: + Introduction ============ diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 51d0349c7809..ae020d84d7c4 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -82,7 +82,7 @@ As an example, here is how the 4.16 development cycle went (all dates in March 11 4.16-rc5 March 18 4.16-rc6 March 25 4.16-rc7 - April 1 4.17 stable release + April 1 4.16 stable release ============== =============================== How do the developers decide when to close the development cycle and create diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index eb4b185d168c..cfe264889447 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -315,7 +315,8 @@ variety of potential coding problems; it can also propose fixes for those problems. Quite a few "semantic patches" for the kernel have been packaged under the scripts/coccinelle directory; running "make coccicheck" will run through those semantic patches and report on any problems found. See -Documentation/dev-tools/coccinelle.rst for more information. +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` +for more information. Other kinds of portability errors are best found by compiling your code for other architectures. If you do not happen to have an S/390 system or a diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index c418c5d6cae4..4213e580f273 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -9,9 +9,10 @@ kernel. Unsurprisingly, the kernel development community has evolved a set of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files process/submitting-patches.rst, -process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel -documentation directory. +more information can also be found in the files +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`, +:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`. When to post @@ -198,8 +199,10 @@ pass it to diff with the "-X" option. The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in -detail in the process/submitting-patches.rst document; what follows here is a -brief summary. Each of these lines has the format: +detail in +the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document; what follows here is a brief summary. Each of these lines has +the format: :: @@ -210,8 +213,8 @@ The tags in common use are: - Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/process/submitting-patches.rst. Code - without a proper signoff cannot be merged into the mainline. + which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + Code without a proper signoff cannot be merged into the mainline. - Co-developed-by: states that the patch was also created by another developer along with the original author. This is useful at times when multiple @@ -226,7 +229,7 @@ The tags in common use are: it to work. - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/process/submitting-patches.rst + see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` for more detail. - Reported-by: names a user who reported a problem which is fixed by this @@ -253,8 +256,8 @@ take care of: be examined in any detail. If there is any doubt at all, mail the patch to yourself and convince yourself that it shows up intact. - Documentation/process/email-clients.rst has some helpful hints on making - specific mail clients work for sending patches. + :ref:`Documentation/process/email-clients.rst <email_clients>` has some + helpful hints on making specific mail clients work for sending patches. - Are you sure your patch is free of silly mistakes? You should always run patches through scripts/checkpatch.pl and address the complaints it diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index 1c7f54cd0261..8395aa2c1f3a 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -5,9 +5,10 @@ For more information There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level process/howto.rst -file is an important starting point; process/submitting-patches.rst and -process/submitting-drivers.rst are also something which all kernel developers should +directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>` +file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>` +and :ref:`process/submitting-drivers.rst <submittingdrivers>` +are also something which all kernel developers should read. Many internal kernel APIs are documented using the kerneldoc mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those documents in HTML or PDF format (though the version of TeX shipped by some diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 0d4f29bc798b..1c3a840d06b9 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -1,3 +1,6 @@ + +.. _addsyscalls: + Adding a New System Call ======================== @@ -232,7 +235,7 @@ normally be optional, so add a ``CONFIG`` option (typically to by the option. - Make the option depend on EXPERT if it should be hidden from normal users. - Make any new source files implementing the function dependent on the CONFIG - option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). + option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``). - Double check that the kernel still builds with the new CONFIG option turned off. diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index dc2ddc345044..fbb9297e6360 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -216,14 +216,14 @@ You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. -This will let you move from something like 4.7.2 to 4.7.3 in a single +This will let you move from something like 5.7.2 to 5.7.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: +Here's how you'd go from 5.7.2 to 5.7.3 in a single step:: - interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 + interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. @@ -245,62 +245,67 @@ The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. -The 4.x.y (-stable) and 4.x patches live at +The 5.x.y (-stable) and 5.x patches live at - https://www.kernel.org/pub/linux/kernel/v4.x/ + https://www.kernel.org/pub/linux/kernel/v5.x/ -The -rc patches live at +The -rc patches are not stored on the webserver but are generated on +demand from git tags such as - https://www.kernel.org/pub/linux/kernel/v4.x/testing/ + https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0 +The stable -rc patches live at -The 4.x kernels + https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/ + + +The 5.x kernels =============== These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 4.x base +will be released (see below) on top of this base. Once a new 5.x base kernel is released, a patch is made available that is a delta between the -previous 4.x kernel and the new one. +previous 5.x kernel and the new one. -To apply a patch moving from 4.6 to 4.7, you'd do the following (note -that such patches do **NOT** apply on top of 4.x.y kernels but on top of the -base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to -first revert the 4.x.y patch). +To apply a patch moving from 5.6 to 5.7, you'd do the following (note +that such patches do **NOT** apply on top of 5.x.y kernels but on top of the +base 5.x kernel -- if you need to move from 5.x.y to 5.x+1 you need to +first revert the 5.x.y patch). Here are some examples:: - # moving from 4.6 to 4.7 + # moving from 5.6 to 5.7 - $ cd ~/linux-4.6 # change to kernel source dir - $ patch -p1 < ../patch-4.7 # apply the 4.7 patch + $ cd ~/linux-5.6 # change to kernel source dir + $ patch -p1 < ../patch-5.7 # apply the 5.7 patch $ cd .. - $ mv linux-4.6 linux-4.7 # rename source dir + $ mv linux-5.6 linux-5.7 # rename source dir - # moving from 4.6.1 to 4.7 + # moving from 5.6.1 to 5.7 - $ cd ~/linux-4.6.1 # change to kernel source dir - $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch - # source dir is now 4.6 - $ patch -p1 < ../patch-4.7 # apply new 4.7 patch + $ cd ~/linux-5.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-5.6.1 # revert the 5.6.1 patch + # source dir is now 5.6 + $ patch -p1 < ../patch-5.7 # apply new 5.7 patch $ cd .. - $ mv linux-4.6.1 linux-4.7 # rename source dir + $ mv linux-5.6.1 linux-5.7 # rename source dir -The 4.x.y kernels +The 5.x.y kernels ================= Kernels with 3-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered -in a given 4.x kernel. +in a given 5.x kernel. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 4.x.y kernel is available, then the highest numbered 4.x kernel is +If no 5.x.y kernel is available, then the highest numbered 5.x kernel is the current stable kernel. .. note:: @@ -308,23 +313,23 @@ the current stable kernel. The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - https://www.kernel.org/pub/linux/kernel/v4.x/incr/ + https://www.kernel.org/pub/linux/kernel/v5.x/incr/ -These patches are not incremental, meaning that for example the 4.7.3 -patch does not apply on top of the 4.7.2 kernel source, but rather on top -of the base 4.7 kernel source. +These patches are not incremental, meaning that for example the 5.7.3 +patch does not apply on top of the 5.7.2 kernel source, but rather on top +of the base 5.7 kernel source. -So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel -source you have to first back out the 4.7.2 patch (so you are left with a -base 4.7 kernel source) and then apply the new 4.7.3 patch. +So, in order to apply the 5.7.3 patch to your existing 5.7.2 kernel +source you have to first back out the 5.7.2 patch (so you are left with a +base 5.7 kernel source) and then apply the new 5.7.3 patch. Here's a small example:: - $ cd ~/linux-4.7.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch - $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch + $ cd ~/linux-5.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-5.7.2 # revert the 5.7.2 patch + $ patch -p1 < ../patch-5.7.3 # apply the new 5.7.3 patch $ cd .. - $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir + $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir The -rc kernels =============== @@ -343,38 +348,38 @@ This is a good branch to run for people who want to help out testing development kernels but do not want to run some of the really experimental stuff (such people should see the sections about -next and -mm kernels below). -The -rc patches are not incremental, they apply to a base 4.x kernel, just -like the 4.x.y patches described above. The kernel version before the -rcN +The -rc patches are not incremental, they apply to a base 5.x kernel, just +like the 5.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. -So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 -kernel and the patch should be applied on top of the 4.7 kernel source. +So, 5.8-rc5 means that this is the fifth release candidate for the 5.8 +kernel and the patch should be applied on top of the 5.7 kernel source. Here are 3 examples of how to apply these patches:: - # first an example of moving from 4.7 to 4.8-rc3 + # first an example of moving from 5.7 to 5.8-rc3 - $ cd ~/linux-4.7 # change to the 4.7 source dir - $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch + $ cd ~/linux-5.7 # change to the 5.7 source dir + $ patch -p1 < ../patch-5.8-rc3 # apply the 5.8-rc3 patch $ cd .. - $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + $ mv linux-5.7 linux-5.8-rc3 # rename the source dir - # now let's move from 4.8-rc3 to 4.8-rc5 + # now let's move from 5.8-rc3 to 5.8-rc5 - $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir - $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch + $ cd ~/linux-5.8-rc3 # change to the 5.8-rc3 dir + $ patch -p1 -R < ../patch-5.8-rc3 # revert the 5.8-rc3 patch + $ patch -p1 < ../patch-5.8-rc5 # apply the new 5.8-rc5 patch $ cd .. - $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + $ mv linux-5.8-rc3 linux-5.8-rc5 # rename the source dir - # finally let's try and move from 4.7.3 to 4.8-rc5 + # finally let's try and move from 5.7.3 to 5.8-rc5 - $ cd ~/linux-4.7.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd ~/linux-5.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-5.7.3 # revert the 5.7.3 patch + $ patch -p1 < ../patch-5.8-rc5 # apply new 5.8-rc5 patch $ cd .. - $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir + $ mv linux-5.7.3 linux-5.8-rc5 # rename the kernel source dir The -mm patches and the linux-next tree diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index d1bf143b446f..18735dc460a0 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -326,7 +326,7 @@ Kernel documentation Sphinx ------ -Please see :ref:`sphinx_install` in ``Documentation/doc-guide/sphinx.rst`` +Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>` for details about Sphinx requirements. Getting updated software diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 4e7c0a1c427a..b78dd680c038 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -443,6 +443,9 @@ In function prototypes, include parameter names with their data types. Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader. +Do not use the `extern' keyword with function prototypes as this makes +lines longer and isn't strictly necessary. + 7) Centralized exiting of functions ----------------------------------- @@ -1075,5 +1078,5 @@ gcc internals and indent, all available from http://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: +Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst new file mode 100644 index 000000000000..0ef5a63c06ba --- /dev/null +++ b/Documentation/process/deprecated.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================================================== +Deprecated Interfaces, Language Features, Attributes, and Conventions +===================================================================== + +In a perfect world, it would be possible to convert all instances of +some deprecated API into the new API and entirely remove the old API in +a single development cycle. However, due to the size of the kernel, the +maintainership hierarchy, and timing, it's not always feasible to do these +kinds of conversions at once. This means that new instances may sneak into +the kernel while old ones are being removed, only making the amount of +work to remove the API grow. In order to educate developers about what +has been deprecated and why, this list has been created as a place to +point when uses of deprecated things are proposed for inclusion in the +kernel. + +__deprecated +------------ +While this attribute does visually mark an interface as deprecated, +it `does not produce warnings during builds any more +<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ +because one of the standing goals of the kernel is to build without +warnings and no one was actually doing anything to remove these deprecated +interfaces. While using `__deprecated` is nice to note an old API in +a header file, it isn't the full solution. Such interfaces must either +be fully removed from the kernel, or added to this file to discourage +others from using them in the future. + +open-coded arithmetic in allocator arguments +-------------------------------------------- +Dynamic size calculations (especially multiplication) should not be +performed in memory allocator (or similar) function arguments due to the +risk of them overflowing. This could lead to values wrapping around and a +smaller allocation being made than the caller was expecting. Using those +allocations could lead to linear overflows of heap memory and other +misbehaviors. (One exception to this is literal values where the compiler +can warn if they might overflow. Though using literals for arguments as +suggested below is also harmless.) + +For example, do not use ``count * size`` as an argument, as in:: + + foo = kmalloc(count * size, GFP_KERNEL); + +Instead, the 2-factor form of the allocator should be used:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +If no 2-factor form is available, the saturate-on-overflow helpers should +be used:: + + bar = vmalloc(array_size(count, size)); + +Another common case to avoid is calculating the size of a structure with +a trailing array of others structures, as in:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +Instead, use the helper:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +See :c:func:`array_size`, :c:func:`array3_size`, and :c:func:`struct_size`, +for more details as well as the related :c:func:`check_add_overflow` and +:c:func:`check_mul_overflow` family of functions. + +simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() +---------------------------------------------------------------------- +The :c:func:`simple_strtol`, :c:func:`simple_strtoll`, +:c:func:`simple_strtoul`, and :c:func:`simple_strtoull` functions +explicitly ignore overflows, which may lead to unexpected results +in callers. The respective :c:func:`kstrtol`, :c:func:`kstrtoll`, +:c:func:`kstrtoul`, and :c:func:`kstrtoull` functions tend to be the +correct replacements, though note that those require the string to be +NUL or newline terminated. + +strcpy() +-------- +:c:func:`strcpy` performs no bounds checking on the destination +buffer. This could result in linear overflows beyond the +end of the buffer, leading to all kinds of misbehaviors. While +`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the +risk of using this function, there is no good reason to add new uses of +this function. The safe replacement is :c:func:`strscpy`. + +strncpy() on NUL-terminated strings +----------------------------------- +Use of :c:func:`strncpy` does not guarantee that the destination buffer +will be NUL terminated. This can lead to various linear read overflows +and other misbehavior due to the missing termination. It also NUL-pads the +destination buffer if the source contents are shorter than the destination +buffer size, which may be a needless performance penalty for callers using +only NUL-terminated strings. The safe replacement is :c:func:`strscpy`. +(Users of :c:func:`strscpy` still needing NUL-padding will need an +explicit :c:func:`memset` added.) + +If a caller is using non-NUL-terminated strings, :c:func:`strncpy()` can +still be used, but destinations should be marked with the `__nonstring +<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ +attribute to avoid future compiler warnings. + +strlcpy() +--------- +:c:func:`strlcpy` reads the entire source buffer first, possibly exceeding +the given limit of bytes to copy. This is inefficient and can lead to +linear read overflows if a source string is not NUL-terminated. The +safe replacement is :c:func:`strscpy`. + +Variable Length Arrays (VLAs) +----------------------------- +Using stack VLAs produces much worse machine code than statically +sized stack arrays. While these non-trivial `performance issues +<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to +eliminate VLAs, they are also a security risk. Dynamic growth of a stack +array may exceed the remaining memory in the stack segment. This could +lead to a crash, possible overwriting sensitive contents at the end of the +stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting +memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`) diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 130bf0f48875..58b2f46c4f98 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -1,3 +1,5 @@ +.. _process_howto: + HOWTO do Linux kernel development ================================= @@ -57,12 +59,13 @@ of doing things. Legal Issues ------------ -The Linux kernel source code is released under the GPL. Please see the -file, COPYING, in the main directory of the source tree, for details on -the license. If you have further questions about the license, please -contact a lawyer, and do not ask on the Linux kernel mailing list. The -people on the mailing lists are not lawyers, and you should not rely on -their statements on legal matters. +The Linux kernel source code is released under the GPL. Please see the file +COPYING in the main directory of the source tree. The Linux kernel licensing +rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are +descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`. +If you have further questions about the license, please contact a lawyer, and do +not ask on the Linux kernel mailing list. The people on the mailing lists are +not lawyers, and you should not rely on their statements on legal matters. For common questions and answers about the GPL, please see: @@ -295,9 +298,9 @@ two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost instantly. -The file Documentation/process/stable-kernel-rules.rst in the kernel tree -documents what kinds of changes are acceptable for the -stable tree, and -how the release process works. +The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +in the kernel tree documents what kinds of changes are acceptable for +the -stable tree, and how the release process works. 4.x -git patches ~~~~~~~~~~~~~~~~ @@ -357,7 +360,8 @@ tool. For details on how to use the kernel bugzilla, please see: https://bugzilla.kernel.org/page.cgi?id=faq.html -The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good +The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>` +in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind of information is needed by the kernel developers to help track down the problem. @@ -423,7 +427,7 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/process/submitting-patches.rst. +as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 42691e2880eb..878ebfda7eef 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -19,11 +19,13 @@ Below are the essential guides that every developer should read. .. toctree:: :maxdepth: 1 + license-rules howto code-of-conduct code-of-conduct-interpretation development-process submitting-patches + programming-language coding-style maintainer-pgp-guide email-clients @@ -42,6 +44,7 @@ Other guides to the community that are of interest to most developers are: stable-kernel-rules submit-checklist kernel-docs + deprecated These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst index e78452c2164c..a849790a68bc 100644 --- a/Documentation/process/kernel-driver-statement.rst +++ b/Documentation/process/kernel-driver-statement.rst @@ -1,3 +1,5 @@ +.. _process_statement_driver: + Kernel Driver Statement ----------------------- diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index 6816c12d6956..e5a1be476047 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -1,4 +1,6 @@ -Linux Kernel Enforcement Statement +.. _process_statement_kernel: + +Linux Kernel Enforcement Statement ---------------------------------- As developers of the Linux kernel, we have a keen interest in how our software diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst index 8ea26325fe3f..2bb8c0fc2238 100644 --- a/Documentation/process/license-rules.rst +++ b/Documentation/process/license-rules.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _kernel_licensing: + Linux kernel licensing rules ============================ diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index 633be1043690..547bbf28e615 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -1,3 +1,5 @@ +.. _magicnumbers: + Linux magic numbers =================== diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst index 85ef8ca8f639..186753ff3d2d 100644 --- a/Documentation/process/management-style.rst +++ b/Documentation/process/management-style.rst @@ -5,8 +5,9 @@ Linux kernel management style This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to -mirror the process/coding-style.rst document to some degree, and mainly written to -avoid answering [#f1]_ the same (or similar) questions over and over again. +mirror the :ref:`process/coding-style.rst <codingstyle>` document to some +degree, and mainly written to avoid answering [#f1]_ the same (or similar) +questions over and over again. Management style is very personal and much harder to quantify than simple coding style rules, so this document may or may not have anything diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst new file mode 100644 index 000000000000..e5f5f065dc24 --- /dev/null +++ b/Documentation/process/programming-language.rst @@ -0,0 +1,45 @@ +.. _programming_language: + +Programming Language +==================== + +The kernel is written in the C programming language [c-language]_. +More precisely, the kernel is typically compiled with ``gcc`` [gcc]_ +under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90 +(including some C99 features). + +This dialect contains many extensions to the language [gnu-extensions]_, +and many of them are used within the kernel as a matter of course. + +There is some support for compiling the kernel with ``clang`` [clang]_ +and ``icc`` [icc]_ for several of the architectures, although at the time +of writing it is not completed, requiring third-party patches. + +Attributes +---------- + +One of the common extensions used throughout the kernel are attributes +[gcc-attribute-syntax]_. Attributes allow to introduce +implementation-defined semantics to language entities (like variables, +functions or types) without having to make significant syntactic changes +to the language (e.g. adding a new keyword) [n2049]_. + +In some cases, attributes are optional (i.e. a compiler not supporting them +should still produce proper code, even if it is slower or does not perform +as many compile-time checks/diagnostics). + +The kernel defines pseudo-keywords (e.g. ``__pure``) instead of using +directly the GNU attribute syntax (e.g. ``__attribute__((__pure__))``) +in order to feature detect which ones can be used and/or to shorten the code. + +Please refer to ``include/linux/compiler_attributes.h`` for more information. + +.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [gcc] https://gcc.gnu.org +.. [clang] https://clang.llvm.org +.. [icc] https://software.intel.com/en-us/c-compilers +.. [gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf + diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index b38bf2054ce3..58bc047e7b95 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -16,7 +16,8 @@ you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org Oh, and we don't really recommend submitting changes to XFree86 :) -Also read the Documentation/process/submitting-patches.rst document. +Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document. Allocating Device Numbers @@ -27,7 +28,8 @@ by the Linux assigned name and number authority (currently this is Torben Mathiasen). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. -See Documentation/admin-guide/devices.rst for more information on this. +See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` +for more information on this. If you don't use assigned numbers then when your device is submitted it will be given an assigned number even if that is different from values you may @@ -117,7 +119,7 @@ PM support: anything. For the driver testing instructions see Documentation/power/drivers-testing.txt and for a relatively complete overview of the power management issues related to - drivers see Documentation/driver-api/pm/devices.rst. + drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`. Control: In general if there is active maintenance of a driver by diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index c0917107b90a..30dc00a364e8 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -510,7 +510,7 @@ tracking your trees, and to people trying to troubleshoot bugs in your tree. -12) When to use Acked-by:, Cc:, and Co-Developed-by: +12) When to use Acked-by:, Cc:, and Co-developed-by: ------------------------------------------------------- The Signed-off-by: tag indicates that the signer was involved in the @@ -543,7 +543,7 @@ person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties have been included in the discussion. -A Co-Developed-by: states that the patch was also created by another developer +A Co-developed-by: states that the patch was also created by another developer along with the original author. This is useful at times when multiple people work on a single patch. Note, this person also needs to have a Signed-off-by: line in the patch as well. |