From 9d0f5cd167444dcffcd46fe19a2cf86f30371f5c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:53 -0600 Subject: docs: promote the title of process/index.rst ...otherwise Sphinx won't cooperate when trying to list it explicitly in the top-level index.rst file Reviewed-by: David Vernet Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-2-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/process/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 2ba2a1582bbe..d4b6217472b0 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -5,6 +5,7 @@ .. _process_index: +============================================= Working with the kernel development community ============================================= -- cgit v1.2.3 From 0c7b4366f1ab955f0b8411c14e764d75e21e1a1c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:54 -0600 Subject: docs: Rewrite the front page The front page is the entry point to the documentation, especially for people who read it online. It's a big mess of everything we could think to toss into it. Rewrite the page with an eye toward simplicity and making it easy for readers to get going toward what they really want to find. This is only a beginning, but it makes our docs more approachable than before. Acked-by: Jani Nikula Reviewed-by: David Vernet Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-3-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 148 ++++++++++++++------------------------- Documentation/subsystem-apis.rst | 58 +++++++++++++++ 2 files changed, 110 insertions(+), 96 deletions(-) create mode 100644 Documentation/subsystem-apis.rst (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index 4737c18c97ff..bc492e79f1be 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -18,131 +18,88 @@ documents into a coherent whole. Please note that improvements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. -Licensing documentation ------------------------ +Working with the development community +-------------------------------------- -The following describes the license of the Linux kernel source code -(GPLv2), how to properly mark the license of individual files in the source -tree, as well as links to the full license text. - -* :ref:`kernel_licensing` - -User-oriented documentation ---------------------------- - -The following manuals are written for *users* of the kernel — those who are -trying to get it to work optimally on a given system. +The essential guides for interacting with the kernel's development +community and getting your work upstream. .. toctree:: - :maxdepth: 2 - - admin-guide/index - kbuild/index - -Firmware-related documentation ------------------------------- -The following holds information on the kernel's expectations regarding the -platform firmwares. + :maxdepth: 1 -.. toctree:: - :maxdepth: 2 + process/development-process + process/submitting-patches + Code of conduct + maintainer/index + All development-process docs - firmware-guide/index - devicetree/index -Application-developer documentation ------------------------------------ +Internal API manuals +-------------------- -The user-space API manual gathers together documents describing aspects of -the kernel interface as seen by application developers. +Manuals for use by developers working to interface with the rest of the +kernel. .. toctree:: - :maxdepth: 2 - - userspace-api/index + :maxdepth: 1 + core-api/index + driver-api/index + subsystem-apis + Locking in the kernel -Introduction to kernel development ----------------------------------- +Development tools and processes +------------------------------- -These manuals contain overall information about how to develop the kernel. -The kernel community is quite large, with thousands of developers -contributing over the course of a year. As with any large community, -knowing how things are done will make the process of getting your changes -merged much easier. +Various other manuals with useful information for all kernel developers. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index - dev-tools/index + process/license-rules doc-guide/index + dev-tools/index + dev-tools/testing-overview kernel-hacking/index trace/index - maintainer/index fault-injection/index livepatch/index -Kernel API documentation ------------------------- +User-oriented documentation +--------------------------- -These books get into the details of how specific kernel subsystems work -from the point of view of a kernel developer. Much of the information here -is taken directly from the kernel source, with supplemental material added -as needed (or at least as we managed to add it — probably *not* all that is -needed). +The following manuals are written for *users* of the kernel — those who are +trying to get it to work optimally on a given system and application +developers seeking information on the kernel's user-space APIs. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + admin-guide/index + The kernel build system + admin-guide/reporting-issues.rst + User-space tools + userspace-api/index + + +Firmware-related documentation +------------------------------ +The following holds information on the kernel's expectations regarding the +platform firmwares. + +.. toctree:: + :maxdepth: 1 + + firmware-guide/index + devicetree/index - driver-api/index - core-api/index - locking/index - accounting/index - block/index - cdrom/index - cpu-freq/index - fb/index - fpga/index - hid/index - i2c/index - iio/index - isdn/index - infiniband/index - leds/index - netlabel/index - networking/index - pcmcia/index - power/index - target/index - timers/index - spi/index - w1/index - watchdog/index - virt/index - input/index - hwmon/index - gpu/index - security/index - sound/index - crypto/index - filesystems/index - mm/index - bpf/index - usb/index - PCI/index - scsi/index - misc-devices/index - scheduler/index - mhi/index - peci/index Architecture-agnostic documentation ----------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 asm-annotations @@ -163,9 +120,8 @@ of the documentation body, or may require some adjustments and/or conversion to ReStructured Text format, or are simply too old. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - tools/index staging/index diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst new file mode 100644 index 000000000000..af65004a80aa --- /dev/null +++ b/Documentation/subsystem-apis.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Kernel subsystem documentation +============================== + +These books get into the details of how specific kernel subsystems work +from the point of view of a kernel developer. Much of the information here +is taken directly from the kernel source, with supplemental material added +as needed (or at least as we managed to add it — probably *not* all that is +needed). + +**Fixme**: much more organizational work is needed here. + +.. toctree:: + :maxdepth: 1 + + driver-api/index + core-api/index + locking/index + accounting/index + block/index + cdrom/index + cpu-freq/index + fb/index + fpga/index + hid/index + i2c/index + iio/index + isdn/index + infiniband/index + leds/index + netlabel/index + networking/index + pcmcia/index + power/index + target/index + timers/index + spi/index + w1/index + watchdog/index + virt/index + input/index + hwmon/index + gpu/index + security/index + sound/index + crypto/index + filesystems/index + mm/index + bpf/index + usb/index + PCI/index + scsi/index + misc-devices/index + scheduler/index + mhi/index + peci/index -- cgit v1.2.3 From 3aa024e4e91249524e1342a6790bb561fbea89a4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:55 -0600 Subject: docs: reconfigure the HTML left column Use the html_sidebars directive to get a more useful set of links in the left column. Unfortunately, this is a no-op with the default RTD theme, but others observe it. Reviewed-by: David Vernet Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-4-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/conf.py b/Documentation/conf.py index cdcc8e0f46a6..c45a3b7f7717 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -369,7 +369,8 @@ html_static_path = ['sphinx-static'] html_use_smartypants = False # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# Note that the RTD theme ignores this. +html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} # Additional templates that should be rendered to pages, maps page names to # template names. -- cgit v1.2.3 From 90c0bf89dec0c66d2e6538857060586073427059 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:56 -0600 Subject: docs: remove some index.rst cruft There is some useless boilerplate text that was added by sphinx when this file was first created; take it out. Reviewed-by: David Vernet Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-5-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 6 ------ 1 file changed, 6 deletions(-) (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index bc492e79f1be..da80c584133c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,11 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 - -.. The Linux Kernel documentation master file, created by - sphinx-quickstart on Fri Feb 12 13:51:46 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - .. _linux_doc: The Linux Kernel documentation -- cgit v1.2.3 From f4bf1cd4ac9c8c4610b687e49a1ba691ab286235 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:57 -0600 Subject: docs: move asm-annotations.rst into core-api This one file should not really be in the top-level documentation directory. core-api/ may not be a perfect fit but seems to be best, so move it there. Adjust a couple of internal document references to make them location-independent, and point checkpatch.pl at the new location. Cc: Jiri Slaby Cc: Joe Perches Reviewed-by: David Vernet Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-6-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/asm-annotations.rst | 221 ---------------------------- Documentation/core-api/asm-annotations.rst | 222 +++++++++++++++++++++++++++++ Documentation/core-api/index.rst | 1 + Documentation/index.rst | 8 -- scripts/checkpatch.pl | 2 +- 5 files changed, 224 insertions(+), 230 deletions(-) delete mode 100644 Documentation/asm-annotations.rst create mode 100644 Documentation/core-api/asm-annotations.rst (limited to 'Documentation') diff --git a/Documentation/asm-annotations.rst b/Documentation/asm-annotations.rst deleted file mode 100644 index a64f2ca469d4..000000000000 --- a/Documentation/asm-annotations.rst +++ /dev/null @@ -1,221 +0,0 @@ -Assembler Annotations -===================== - -Copyright (c) 2017-2019 Jiri Slaby - -This document describes the new macros for annotation of data and code in -assembly. In particular, it contains information about ``SYM_FUNC_START``, -``SYM_FUNC_END``, ``SYM_CODE_START``, and similar. - -Rationale ---------- -Some code like entries, trampolines, or boot code needs to be written in -assembly. The same as in C, such code is grouped into functions and -accompanied with data. Standard assemblers do not force users into precisely -marking these pieces as code, data, or even specifying their length. -Nevertheless, assemblers provide developers with such annotations to aid -debuggers throughout assembly. On top of that, developers also want to mark -some functions as *global* in order to be visible outside of their translation -units. - -Over time, the Linux kernel has adopted macros from various projects (like -``binutils``) to facilitate such annotations. So for historic reasons, -developers have been using ``ENTRY``, ``END``, ``ENDPROC``, and other -annotations in assembly. Due to the lack of their documentation, the macros -are used in rather wrong contexts at some locations. Clearly, ``ENTRY`` was -intended to denote the beginning of global symbols (be it data or code). -``END`` used to mark the end of data or end of special functions with -*non-standard* calling convention. In contrast, ``ENDPROC`` should annotate -only ends of *standard* functions. - -When these macros are used correctly, they help assemblers generate a nice -object with both sizes and types set correctly. For example, the result of -``arch/x86/lib/putuser.S``:: - - Num: Value Size Type Bind Vis Ndx Name - 25: 0000000000000000 33 FUNC GLOBAL DEFAULT 1 __put_user_1 - 29: 0000000000000030 37 FUNC GLOBAL DEFAULT 1 __put_user_2 - 32: 0000000000000060 36 FUNC GLOBAL DEFAULT 1 __put_user_4 - 35: 0000000000000090 37 FUNC GLOBAL DEFAULT 1 __put_user_8 - -This is not only important for debugging purposes. When there are properly -annotated objects like this, tools can be run on them to generate more useful -information. In particular, on properly annotated objects, ``objtool`` can be -run to check and fix the object if needed. Currently, ``objtool`` can report -missing frame pointer setup/destruction in functions. It can also -automatically generate annotations for :doc:`ORC unwinder ` -for most code. Both of these are especially important to support reliable -stack traces which are in turn necessary for :doc:`Kernel live patching -`. - -Caveat and Discussion ---------------------- -As one might realize, there were only three macros previously. That is indeed -insufficient to cover all the combinations of cases: - -* standard/non-standard function -* code/data -* global/local symbol - -There was a discussion_ and instead of extending the current ``ENTRY/END*`` -macros, it was decided that brand new macros should be introduced instead:: - - So how about using macro names that actually show the purpose, instead - of importing all the crappy, historic, essentially randomly chosen - debug symbol macro names from the binutils and older kernels? - -.. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz - -Macros Description ------------------- - -The new macros are prefixed with the ``SYM_`` prefix and can be divided into -three main groups: - -1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with - standard C calling conventions. For example, on x86, this means that the - stack contains a return address at the predefined place and a return from - the function can happen in a standard way. When frame pointers are enabled, - save/restore of frame pointer shall happen at the start/end of a function, - respectively, too. - - Checking tools like ``objtool`` should ensure such marked functions conform - to these rules. The tools can also easily annotate these functions with - debugging information (like *ORC data*) automatically. - -2. ``SYM_CODE_*`` -- special functions called with special stack. Be it - interrupt handlers with special stack content, trampolines, or startup - functions. - - Checking tools mostly ignore checking of these functions. But some debug - information still can be generated automatically. For correct debug data, - this code needs hints like ``UNWIND_HINT_REGS`` provided by developers. - -3. ``SYM_DATA*`` -- obviously data belonging to ``.data`` sections and not to - ``.text``. Data do not contain instructions, so they have to be treated - specially by the tools: they should not treat the bytes as instructions, - nor assign any debug information to them. - -Instruction Macros -~~~~~~~~~~~~~~~~~~ -This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above. - -``objtool`` requires that all code must be contained in an ELF symbol. Symbol -names that have a ``.L`` prefix do not emit symbol table entries. ``.L`` -prefixed symbols can be used within a code region, but should be avoided for -denoting a range of code via ``SYM_*_START/END`` annotations. - -* ``SYM_FUNC_START`` and ``SYM_FUNC_START_LOCAL`` are supposed to be **the - most frequent markings**. They are used for functions with standard calling - conventions -- global and local. Like in C, they both align the functions to - architecture specific ``__ALIGN`` bytes. There are also ``_NOALIGN`` variants - for special cases where developers do not want this implicit alignment. - - ``SYM_FUNC_START_WEAK`` and ``SYM_FUNC_START_WEAK_NOALIGN`` markings are - also offered as an assembler counterpart to the *weak* attribute known from - C. - - All of these **shall** be coupled with ``SYM_FUNC_END``. First, it marks - the sequence of instructions as a function and computes its size to the - generated object file. Second, it also eases checking and processing such - object files as the tools can trivially find exact function boundaries. - - So in most cases, developers should write something like in the following - example, having some asm instructions in between the macros, of course:: - - SYM_FUNC_START(memset) - ... asm insns ... - SYM_FUNC_END(memset) - - In fact, this kind of annotation corresponds to the now deprecated ``ENTRY`` - and ``ENDPROC`` macros. - -* ``SYM_FUNC_ALIAS``, ``SYM_FUNC_ALIAS_LOCAL``, and ``SYM_FUNC_ALIAS_WEAK`` can - be used to define multiple names for a function. The typical use is:: - - SYM_FUNC_START(__memset) - ... asm insns ... - SYN_FUNC_END(__memset) - SYM_FUNC_ALIAS(memset, __memset) - - In this example, one can call ``__memset`` or ``memset`` with the same - result, except the debug information for the instructions is generated to - the object file only once -- for the non-``ALIAS`` case. - -* ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in - special cases -- if you know what you are doing. This is used exclusively - for interrupt handlers and similar where the calling convention is not the C - one. ``_NOALIGN`` variants exist too. The use is the same as for the ``FUNC`` - category above:: - - SYM_CODE_START_LOCAL(bad_put_user) - ... asm insns ... - SYM_CODE_END(bad_put_user) - - Again, every ``SYM_CODE_START*`` **shall** be coupled by ``SYM_CODE_END``. - - To some extent, this category corresponds to deprecated ``ENTRY`` and - ``END``. Except ``END`` had several other meanings too. - -* ``SYM_INNER_LABEL*`` is used to denote a label inside some - ``SYM_{CODE,FUNC}_START`` and ``SYM_{CODE,FUNC}_END``. They are very similar - to C labels, except they can be made global. An example of use:: - - SYM_CODE_START(ftrace_caller) - /* save_mcount_regs fills in first two parameters */ - ... - - SYM_INNER_LABEL(ftrace_caller_op_ptr, SYM_L_GLOBAL) - /* Load the ftrace_ops into the 3rd parameter */ - ... - - SYM_INNER_LABEL(ftrace_call, SYM_L_GLOBAL) - call ftrace_stub - ... - retq - SYM_CODE_END(ftrace_caller) - -Data Macros -~~~~~~~~~~~ -Similar to instructions, there is a couple of macros to describe data in the -assembly. - -* ``SYM_DATA_START`` and ``SYM_DATA_START_LOCAL`` mark the start of some data - and shall be used in conjunction with either ``SYM_DATA_END``, or - ``SYM_DATA_END_LABEL``. The latter adds also a label to the end, so that - people can use ``lstack`` and (local) ``lstack_end`` in the following - example:: - - SYM_DATA_START_LOCAL(lstack) - .skip 4096 - SYM_DATA_END_LABEL(lstack, SYM_L_LOCAL, lstack_end) - -* ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line - data:: - - SYM_DATA(HEAP, .long rm_heap) - SYM_DATA(heap_end, .long rm_stack) - - In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END`` - internally. - -Support Macros -~~~~~~~~~~~~~~ -All the above reduce themselves to some invocation of ``SYM_START``, -``SYM_END``, or ``SYM_ENTRY`` at last. Normally, developers should avoid using -these. - -Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also -``SYM_L_GLOBAL`` and ``SYM_L_WEAK``. All are intended to denote linkage of a -symbol marked by them. They are used either in ``_LABEL`` variants of the -earlier macros, or in ``SYM_START``. - - -Overriding Macros -~~~~~~~~~~~~~~~~~ -Architecture can also override any of the macros in their own -``asm/linkage.h``, including macros specifying the type of a symbol -(``SYM_T_FUNC``, ``SYM_T_OBJECT``, and ``SYM_T_NONE``). As every macro -described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough -to define the macros differently in the aforementioned architecture-dependent -header. diff --git a/Documentation/core-api/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst new file mode 100644 index 000000000000..bc514ed59887 --- /dev/null +++ b/Documentation/core-api/asm-annotations.rst @@ -0,0 +1,222 @@ +Assembler Annotations +===================== + +Copyright (c) 2017-2019 Jiri Slaby + +This document describes the new macros for annotation of data and code in +assembly. In particular, it contains information about ``SYM_FUNC_START``, +``SYM_FUNC_END``, ``SYM_CODE_START``, and similar. + +Rationale +--------- +Some code like entries, trampolines, or boot code needs to be written in +assembly. The same as in C, such code is grouped into functions and +accompanied with data. Standard assemblers do not force users into precisely +marking these pieces as code, data, or even specifying their length. +Nevertheless, assemblers provide developers with such annotations to aid +debuggers throughout assembly. On top of that, developers also want to mark +some functions as *global* in order to be visible outside of their translation +units. + +Over time, the Linux kernel has adopted macros from various projects (like +``binutils``) to facilitate such annotations. So for historic reasons, +developers have been using ``ENTRY``, ``END``, ``ENDPROC``, and other +annotations in assembly. Due to the lack of their documentation, the macros +are used in rather wrong contexts at some locations. Clearly, ``ENTRY`` was +intended to denote the beginning of global symbols (be it data or code). +``END`` used to mark the end of data or end of special functions with +*non-standard* calling convention. In contrast, ``ENDPROC`` should annotate +only ends of *standard* functions. + +When these macros are used correctly, they help assemblers generate a nice +object with both sizes and types set correctly. For example, the result of +``arch/x86/lib/putuser.S``:: + + Num: Value Size Type Bind Vis Ndx Name + 25: 0000000000000000 33 FUNC GLOBAL DEFAULT 1 __put_user_1 + 29: 0000000000000030 37 FUNC GLOBAL DEFAULT 1 __put_user_2 + 32: 0000000000000060 36 FUNC GLOBAL DEFAULT 1 __put_user_4 + 35: 0000000000000090 37 FUNC GLOBAL DEFAULT 1 __put_user_8 + +This is not only important for debugging purposes. When there are properly +annotated objects like this, tools can be run on them to generate more useful +information. In particular, on properly annotated objects, ``objtool`` can be +run to check and fix the object if needed. Currently, ``objtool`` can report +missing frame pointer setup/destruction in functions. It can also +automatically generate annotations for the ORC unwinder +(Documentation/x86/orc-unwinder.rst) +for most code. Both of these are especially important to support reliable +stack traces which are in turn necessary for kernel live patching +(Documentation/livepatch/livepatch.rst). + +Caveat and Discussion +--------------------- +As one might realize, there were only three macros previously. That is indeed +insufficient to cover all the combinations of cases: + +* standard/non-standard function +* code/data +* global/local symbol + +There was a discussion_ and instead of extending the current ``ENTRY/END*`` +macros, it was decided that brand new macros should be introduced instead:: + + So how about using macro names that actually show the purpose, instead + of importing all the crappy, historic, essentially randomly chosen + debug symbol macro names from the binutils and older kernels? + +.. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz + +Macros Description +------------------ + +The new macros are prefixed with the ``SYM_`` prefix and can be divided into +three main groups: + +1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with + standard C calling conventions. For example, on x86, this means that the + stack contains a return address at the predefined place and a return from + the function can happen in a standard way. When frame pointers are enabled, + save/restore of frame pointer shall happen at the start/end of a function, + respectively, too. + + Checking tools like ``objtool`` should ensure such marked functions conform + to these rules. The tools can also easily annotate these functions with + debugging information (like *ORC data*) automatically. + +2. ``SYM_CODE_*`` -- special functions called with special stack. Be it + interrupt handlers with special stack content, trampolines, or startup + functions. + + Checking tools mostly ignore checking of these functions. But some debug + information still can be generated automatically. For correct debug data, + this code needs hints like ``UNWIND_HINT_REGS`` provided by developers. + +3. ``SYM_DATA*`` -- obviously data belonging to ``.data`` sections and not to + ``.text``. Data do not contain instructions, so they have to be treated + specially by the tools: they should not treat the bytes as instructions, + nor assign any debug information to them. + +Instruction Macros +~~~~~~~~~~~~~~~~~~ +This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above. + +``objtool`` requires that all code must be contained in an ELF symbol. Symbol +names that have a ``.L`` prefix do not emit symbol table entries. ``.L`` +prefixed symbols can be used within a code region, but should be avoided for +denoting a range of code via ``SYM_*_START/END`` annotations. + +* ``SYM_FUNC_START`` and ``SYM_FUNC_START_LOCAL`` are supposed to be **the + most frequent markings**. They are used for functions with standard calling + conventions -- global and local. Like in C, they both align the functions to + architecture specific ``__ALIGN`` bytes. There are also ``_NOALIGN`` variants + for special cases where developers do not want this implicit alignment. + + ``SYM_FUNC_START_WEAK`` and ``SYM_FUNC_START_WEAK_NOALIGN`` markings are + also offered as an assembler counterpart to the *weak* attribute known from + C. + + All of these **shall** be coupled with ``SYM_FUNC_END``. First, it marks + the sequence of instructions as a function and computes its size to the + generated object file. Second, it also eases checking and processing such + object files as the tools can trivially find exact function boundaries. + + So in most cases, developers should write something like in the following + example, having some asm instructions in between the macros, of course:: + + SYM_FUNC_START(memset) + ... asm insns ... + SYM_FUNC_END(memset) + + In fact, this kind of annotation corresponds to the now deprecated ``ENTRY`` + and ``ENDPROC`` macros. + +* ``SYM_FUNC_ALIAS``, ``SYM_FUNC_ALIAS_LOCAL``, and ``SYM_FUNC_ALIAS_WEAK`` can + be used to define multiple names for a function. The typical use is:: + + SYM_FUNC_START(__memset) + ... asm insns ... + SYN_FUNC_END(__memset) + SYM_FUNC_ALIAS(memset, __memset) + + In this example, one can call ``__memset`` or ``memset`` with the same + result, except the debug information for the instructions is generated to + the object file only once -- for the non-``ALIAS`` case. + +* ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in + special cases -- if you know what you are doing. This is used exclusively + for interrupt handlers and similar where the calling convention is not the C + one. ``_NOALIGN`` variants exist too. The use is the same as for the ``FUNC`` + category above:: + + SYM_CODE_START_LOCAL(bad_put_user) + ... asm insns ... + SYM_CODE_END(bad_put_user) + + Again, every ``SYM_CODE_START*`` **shall** be coupled by ``SYM_CODE_END``. + + To some extent, this category corresponds to deprecated ``ENTRY`` and + ``END``. Except ``END`` had several other meanings too. + +* ``SYM_INNER_LABEL*`` is used to denote a label inside some + ``SYM_{CODE,FUNC}_START`` and ``SYM_{CODE,FUNC}_END``. They are very similar + to C labels, except they can be made global. An example of use:: + + SYM_CODE_START(ftrace_caller) + /* save_mcount_regs fills in first two parameters */ + ... + + SYM_INNER_LABEL(ftrace_caller_op_ptr, SYM_L_GLOBAL) + /* Load the ftrace_ops into the 3rd parameter */ + ... + + SYM_INNER_LABEL(ftrace_call, SYM_L_GLOBAL) + call ftrace_stub + ... + retq + SYM_CODE_END(ftrace_caller) + +Data Macros +~~~~~~~~~~~ +Similar to instructions, there is a couple of macros to describe data in the +assembly. + +* ``SYM_DATA_START`` and ``SYM_DATA_START_LOCAL`` mark the start of some data + and shall be used in conjunction with either ``SYM_DATA_END``, or + ``SYM_DATA_END_LABEL``. The latter adds also a label to the end, so that + people can use ``lstack`` and (local) ``lstack_end`` in the following + example:: + + SYM_DATA_START_LOCAL(lstack) + .skip 4096 + SYM_DATA_END_LABEL(lstack, SYM_L_LOCAL, lstack_end) + +* ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line + data:: + + SYM_DATA(HEAP, .long rm_heap) + SYM_DATA(heap_end, .long rm_stack) + + In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END`` + internally. + +Support Macros +~~~~~~~~~~~~~~ +All the above reduce themselves to some invocation of ``SYM_START``, +``SYM_END``, or ``SYM_ENTRY`` at last. Normally, developers should avoid using +these. + +Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also +``SYM_L_GLOBAL`` and ``SYM_L_WEAK``. All are intended to denote linkage of a +symbol marked by them. They are used either in ``_LABEL`` variants of the +earlier macros, or in ``SYM_START``. + + +Overriding Macros +~~~~~~~~~~~~~~~~~ +Architecture can also override any of the macros in their own +``asm/linkage.h``, including macros specifying the type of a symbol +(``SYM_T_FUNC``, ``SYM_T_OBJECT``, and ``SYM_T_NONE``). As every macro +described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough +to define the macros differently in the aforementioned architecture-dependent +header. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index dc95df462eea..f5d8e3779fe8 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -23,6 +23,7 @@ it. printk-formats printk-index symbol-namespaces + asm-annotations Data structures and low-level utilities ======================================= diff --git a/Documentation/index.rst b/Documentation/index.rst index da80c584133c..5a700548ae82 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -89,14 +89,6 @@ platform firmwares. devicetree/index -Architecture-agnostic documentation ------------------------------------ - -.. toctree:: - :maxdepth: 1 - - asm-annotations - Architecture-specific documentation ----------------------------------- diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 79e759aac543..812af52f97d2 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -3751,7 +3751,7 @@ sub process { if ($realfile =~ /\.S$/ && $line =~ /^\+\s*(?:[A-Z]+_)?SYM_[A-Z]+_(?:START|END)(?:_[A-Z_]+)?\s*\(\s*\.L/) { WARN("AVOID_L_PREFIX", - "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/asm-annotations.rst\n" . $herecurr); + "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr); } # check we are in a valid source file C or perl if not then ignore this hunk -- cgit v1.2.3 From e40573a43d163a5c9fe14c647bc4c5201d782893 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:58 -0600 Subject: docs: put atomic*.txt and memory-barriers.txt into the core-api book These files describe part of the core API, but have never been converted to RST due to ... let's say local oppposition. So, create a set of special-purpose wrappers to ..include these files into a separate page so that they can be a part of the htmldocs build. Then link them into the core-api manual and remove them from the "staging" dumping ground. Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet Reviewed-by: David Vernet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-7-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 3 ++ Documentation/core-api/wrappers/atomic_bitops.rst | 18 ++++++++++ Documentation/core-api/wrappers/atomic_t.rst | 19 ++++++++++ .../core-api/wrappers/memory-barriers.rst | 18 ++++++++++ Documentation/staging/index.rst | 42 ---------------------- 5 files changed, 58 insertions(+), 42 deletions(-) create mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst create mode 100644 Documentation/core-api/wrappers/atomic_t.rst create mode 100644 Documentation/core-api/wrappers/memory-barriers.rst (limited to 'Documentation') diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index f5d8e3779fe8..b0e7b4771fff 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -45,6 +45,8 @@ Library functionality that is used throughout the kernel. this_cpu_ops timekeeping errseq + wrappers/atomic_t + wrappers/atomic_bitops Low level entry and exit ======================== @@ -68,6 +70,7 @@ Documentation/locking/index.rst for more related documentation. local_ops padata ../RCU/index + wrappers/memory-barriers.rst Low-level hardware management ============================= diff --git a/Documentation/core-api/wrappers/atomic_bitops.rst b/Documentation/core-api/wrappers/atomic_bitops.rst new file mode 100644 index 000000000000..bf24e4081a8f --- /dev/null +++ b/Documentation/core-api/wrappers/atomic_bitops.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring atomic_bitops.txt into the RST world + until such a time as that file can be converted directly. + +============= +Atomic bitops +============= + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_bitops.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/core-api/wrappers/atomic_t.rst b/Documentation/core-api/wrappers/atomic_t.rst new file mode 100644 index 000000000000..ed109a964c77 --- /dev/null +++ b/Documentation/core-api/wrappers/atomic_t.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring atomic_t.txt into the RST world + until such a time as that file can be converted directly. + +============ +Atomic types +============ + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_t.txt + :literal: + +.. raw:: latex + + \normalsize + diff --git a/Documentation/core-api/wrappers/memory-barriers.rst b/Documentation/core-api/wrappers/memory-barriers.rst new file mode 100644 index 000000000000..532460b5e3eb --- /dev/null +++ b/Documentation/core-api/wrappers/memory-barriers.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + This is a simple wrapper to bring memory-barriers.txt into the RST world + until such a time as that file can be converted directly. + +============================ +Linux kernel memory barriers +============================ + +.. raw:: latex + + \footnotesize + +.. include:: ../../memory-barriers.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index abd0d18254d2..ded8254bc0d7 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -14,45 +14,3 @@ Unsorted Documentation static-keys tee xz - -Atomic Types -============ - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_t.txt - :literal: - -.. raw:: latex - - \normalsize - -Atomic bitops -============= - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_bitops.txt - :literal: - -.. raw:: latex - - \normalsize - -Memory Barriers -=============== - -.. raw:: latex - - \footnotesize - -.. include:: ../memory-barriers.txt - :literal: - -.. raw:: latex - - \normalsize -- cgit v1.2.3 From 489876063fb14290d2d1b6080c5fdc02b7a481d4 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 27 Sep 2022 10:05:59 -0600 Subject: docs: add a man-pages link to the front page Readers looking for user-oriented information may benefit from it. Signed-off-by: Jonathan Corbet Reviewed-by: David Vernet Acked-by: Randy Dunlap Link: https://lore.kernel.org/r/20220927160559.97154-8-corbet@lwn.net Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'Documentation') diff --git a/Documentation/index.rst b/Documentation/index.rst index 5a700548ae82..85eab6e990ab 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -76,6 +76,8 @@ developers seeking information on the kernel's user-space APIs. User-space tools userspace-api/index +See also: the `Linux man pages `_, +which are kept separately from the kernel's own documentation. Firmware-related documentation ------------------------------ -- cgit v1.2.3 From e94102e5067591aa713e623d7d1226f07d4431cf Mon Sep 17 00:00:00 2001 From: Tiezhu Yang Date: Fri, 16 Sep 2022 17:55:06 +0800 Subject: docs, kprobes: Fix the wrong location of Kprobes After commit 22471e1313f2 ("kconfig: use a menu in arch/Kconfig to reduce clutter"), the location of Kprobes is under "General architecture-dependent options" rather than "General setup". Signed-off-by: Tiezhu Yang Acked-by: Steven Rostedt (Google) Fixes: 22471e1313f2 ("kconfig: use a menu in arch/Kconfig to reduce clutter") Link: https://lore.kernel.org/r/1663322106-12178-1-git-send-email-yangtiezhu@loongson.cn Signed-off-by: Jonathan Corbet --- Documentation/trace/kprobes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/trace/kprobes.rst b/Documentation/trace/kprobes.rst index f318bceda1e6..48cf778a2468 100644 --- a/Documentation/trace/kprobes.rst +++ b/Documentation/trace/kprobes.rst @@ -328,8 +328,8 @@ Configuring Kprobes =================== When configuring the kernel using make menuconfig/xconfig/oldconfig, -ensure that CONFIG_KPROBES is set to "y". Under "General setup", look -for "Kprobes". +ensure that CONFIG_KPROBES is set to "y", look for "Kprobes" under +"General architecture-dependent options". So that you can load and unload Kprobes-based instrumentation modules, make sure "Loadable module support" (CONFIG_MODULES) and "Module -- cgit v1.2.3 From 2f993509a97ed210ed0ada9198d380885265fa0b Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Wed, 28 Sep 2022 15:39:40 +0200 Subject: docs: process/5.Posting.rst: clarify use of Reported-by: tag Bring the description on when to use the Reported-by: tag found in Documentation/process/5.Posting.rst more in line with the description in Documentation/process/submitting-patches.rst: before this change the two were contradicting each other, as the latter is way more permissive and only states '[...] if the bug was reported in private, then ask for permission first before using the Reported-by tag.' Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/2fc7162dfb76e04da5ea903c9c170d913e735dad.1664372256.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet --- Documentation/process/5.Posting.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index 906235c11c24..d87f1fee4cbc 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -256,8 +256,10 @@ The tags in common use are: - Cc: the named person received a copy of the patch and had the opportunity to comment on it. -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. +Be careful in the addition of tags to your patches, as only Cc: is appropriate +for addition without the explicit permission of the person named; using +Reported-by: is fine most of the time as well, but ask for permission if +the bug was reported in private. Sending the patch -- cgit v1.2.3 From 679b4bc25fc7b5b742622eb760211f2b5b1dc4db Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Fri, 16 Sep 2022 19:08:05 +0900 Subject: docs/doc-guide: Add documentation on SPHINX_IMGMATH Now that building html docs with math expressions does not need texlive packages, remove the note on the requirement in the "Sphinx Install" section. Instead, add sections of "Math Expressions in HTML" and "Choice of Math Renderer". Describe the effect of setting SPHINX_IMGMATH in the latter section. Signed-off-by: Akira Yokosawa Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/sphinx.rst | 57 +++++++++++++++++++++++++++++++++++--- 1 file changed, 53 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 1228b85f6f77..c708cec889af 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -48,10 +48,6 @@ or ``virtualenv``, depending on how your distribution packaged Python 3. on the Sphinx version, it should be installed separately, with ``pip install sphinx_rtd_theme``. - #) Some ReST pages contain math expressions. Due to the way Sphinx works, - those expressions are written using LaTeX notation. It needs texlive - installed with amsfonts and amsmath in order to evaluate them. - In summary, if you want to install Sphinx version 2.4.4, you should do:: $ virtualenv sphinx_2.4.4 @@ -86,6 +82,27 @@ Depending on the distribution, you may also need to install a series of ``texlive`` packages that provide the minimal set of functionalities required for ``XeLaTeX`` to work. +Math Expressions in HTML +------------------------ + +Some ReST pages contain math expressions. Due to the way Sphinx works, +those expressions are written using LaTeX notation. +There are two options for Sphinx to render math expressions in html output. +One is an extension called `imgmath`_ which converts math expressions into +images and embeds them in html pages. +The other is an extension called `mathjax`_ which delegates math rendering +to JavaScript capable web browsers. +The former was the only option for pre-6.1 kernel documentation and it +requires quite a few texlive packages including amsfonts and amsmath among +others. + +Since kernel release 6.1, html pages with math expressions can be built +without installing any texlive packages. See `Choice of Math Renderer`_ for +further info. + +.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath +.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax + .. _sphinx-pre-install: Checking for Sphinx dependencies @@ -164,6 +181,38 @@ To remove the generated documentation, run ``make cleandocs``. as well would improve the quality of images embedded in PDF documents, especially for kernel releases 5.18 and later. +Choice of Math Renderer +----------------------- + +Since kernel release 6.1, mathjax works as a fallback math renderer for +html output.\ [#sph1_8]_ + +Math renderer is chosen depending on available commands as shown below: + +.. table:: Math Renderer Choices for HTML + + ============= ================= ============ + Math renderer Required commands Image format + ============= ================= ============ + imgmath latex, dvipng PNG (raster) + mathjax + ============= ================= ============ + +The choice can be overridden by setting an environment variable +``SPHINX_IMGMATH`` as shown below: + +.. table:: Effect of Setting ``SPHINX_IMGMATH`` + + ====================== ======== + Setting Renderer + ====================== ======== + ``SPHINX_IMGMATH=yes`` imgmath + ``SPHINX_IMGMATH=no`` mathjax + ====================== ======== + +.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8. + + Writing Documentation ===================== -- cgit v1.2.3 From 26e54448092917edd54c4255382f78b24e07b01f Mon Sep 17 00:00:00 2001 From: Kristen Carlson Accardi Date: Mon, 26 Sep 2022 14:11:49 -0700 Subject: Documentation/CoC: Reflect current CoC interpretation and practices The Code of Conduct interpretation does not reflect the current practices of the CoC committee or the TAB. Update the documentation to remove references to initial committees and boot strap periods since it is past that time, and note that the this document does serve as the documentation for the CoC committee processes. Signed-off-by: Kristen Carlson Accardi Reviewed-by: Shuah Khan Reviewed-by: Greg Kroah-Hartman Link: https://lore.kernel.org/r/20220926211149.2278214-1-kristen@linux.intel.com Signed-off-by: Jonathan Corbet --- .../process/code-of-conduct-interpretation.rst | 24 ++++++++++++---------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'Documentation') diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst index 4f8a06b00f60..922e0b547bc3 100644 --- a/Documentation/process/code-of-conduct-interpretation.rst +++ b/Documentation/process/code-of-conduct-interpretation.rst @@ -127,10 +127,12 @@ are listed at https://kernel.org/code-of-conduct.html. Members can not access reports made before they joined or after they have left the committee. -The initial Code of Conduct Committee consists of volunteer members of -the TAB, as well as a professional mediator acting as a neutral third -party. The first task of the committee is to establish documented -processes, which will be made public. +The Code of Conduct Committee consists of volunteer community members +appointed by the TAB, as well as a professional mediator acting as a +neutral third party. The processes the Code of Conduct committee will +use to address reports is varied and will depend on the individual +circumstance, however, this file serves as documentation for the +general process used. Any member of the committee, including the mediator, can be contacted directly if a reporter does not wish to include the full committee in a @@ -141,16 +143,16 @@ processes (see above) and consults with the TAB as needed and appropriate, for instance to request and receive information about the kernel community. -Any decisions by the committee will be brought to the TAB, for -implementation of enforcement with the relevant maintainers if needed. -A decision by the Code of Conduct Committee can be overturned by the TAB -by a two-thirds vote. +Any decisions regarding enforcement recommendations will be brought to +the TAB for implementation of enforcement with the relevant maintainers +if needed. A decision by the Code of Conduct Committee can be overturned +by the TAB by a two-thirds vote. At quarterly intervals, the Code of Conduct Committee and TAB will provide a report summarizing the anonymised reports that the Code of Conduct committee has received and their status, as well details of any overridden decisions including complete and identifiable voting details. -We expect to establish a different process for Code of Conduct Committee -staffing beyond the bootstrap period. This document will be updated -with that information when this occurs. +Because how we interpret and enforce the Code of Conduct will evolve over +time, this document will be updated when necessary to reflect any +changes. -- cgit v1.2.3 From 9a7d7a80e11025e5e8b4dedf75c97096b67a7b9b Mon Sep 17 00:00:00 2001 From: Vernon Yang Date: Mon, 26 Sep 2022 23:20:32 +0800 Subject: Documentation/mm: modify page_referenced to folio_referenced Since commit b3ac04132c4b ("mm/rmap: Turn page_referenced() into folio_referenced()") the page_referenced function name was modified, so fix it up to use the correct one. Signed-off-by: Vernon Yang Reviewed-by: Mike Rapoport Link: https://lore.kernel.org/r/20220926152032.74621-1-vernon2gm@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/mm/unevictable-lru.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index b280367d6a44..4a0e158aa9ce 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -197,7 +197,7 @@ unevictable list for the memory cgroup and node being scanned. There may be situations where a page is mapped into a VM_LOCKED VMA, but the page is not marked as PG_mlocked. Such pages will make it all the way to shrink_active_list() or shrink_page_list() where they will be detected when -vmscan walks the reverse map in page_referenced() or try_to_unmap(). The page +vmscan walks the reverse map in folio_referenced() or try_to_unmap(). The page is culled to the unevictable list when it is released by the shrinker. To "cull" an unevictable page, vmscan simply puts the page back on the LRU list @@ -267,7 +267,7 @@ the LRU. Such pages can be "noticed" by memory management in several places: (4) in the fault path and when a VM_LOCKED stack segment is expanded; or (5) as mentioned above, in vmscan:shrink_page_list() when attempting to - reclaim a page in a VM_LOCKED VMA by page_referenced() or try_to_unmap(). + reclaim a page in a VM_LOCKED VMA by folio_referenced() or try_to_unmap(). mlocked pages become unlocked and rescued from the unevictable list when: @@ -547,7 +547,7 @@ vmscan's shrink_inactive_list() and shrink_page_list() also divert obviously unevictable pages found on the inactive lists to the appropriate memory cgroup and node unevictable list. -rmap's page_referenced_one(), called via vmscan's shrink_active_list() or +rmap's folio_referenced_one(), called via vmscan's shrink_active_list() or shrink_page_list(), and rmap's try_to_unmap_one() called via shrink_page_list(), check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_page() to correct them. Such pages are culled to the unevictable list when released -- cgit v1.2.3 From 06699e6915536b88ec9457f105a5facf5bc81f88 Mon Sep 17 00:00:00 2001 From: Yang Yingliang Date: Tue, 27 Sep 2022 16:38:19 +0800 Subject: Documentation: devres: update IRQ helper devm_irq_sim_init() has been changed to devm_irq_domain_create_sim() in commit 337cbeb2c13e ("genirq/irq_sim: Simplify the API"). Signed-off-by: Yang Yingliang Link: https://lore.kernel.org/r/20220927083819.12484-1-yangyingliang@huawei.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/devres.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 6f190967ba2e..79c80ecf6a42 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -334,7 +334,7 @@ IRQ devm_irq_alloc_descs_from() devm_irq_alloc_generic_chip() devm_irq_setup_generic_chip() - devm_irq_sim_init() + devm_irq_domain_create_sim() LED devm_led_classdev_register() -- cgit v1.2.3 From 657ed9c9bca059660238771dd1fcecb57b59f90a Mon Sep 17 00:00:00 2001 From: Yang Yingliang Date: Tue, 27 Sep 2022 16:02:15 +0800 Subject: Documentation: devres: add missing IO helper Add missing devm_request_free_mem_region() to devres.rst. It's introduced by commit 0092908d16c6 ("mm: factor out a devm_request_free_mem_region helper"). Signed-off-by: Yang Yingliang Link: https://lore.kernel.org/r/20220927080215.1359979-1-yangyingliang@huawei.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/devres.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation') diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 79c80ecf6a42..dc1b2353cea3 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -301,6 +301,7 @@ IO region devm_release_region() devm_release_resource() devm_request_mem_region() + devm_request_free_mem_region() devm_request_region() devm_request_resource() -- cgit v1.2.3 From 1cfd9d7e43d5a1cf739d1420b10b1e65feb02f88 Mon Sep 17 00:00:00 2001 From: David Hildenbrand Date: Fri, 23 Sep 2022 13:34:24 +0200 Subject: coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel") Linus notes [1] that the introduction of new code that uses VM_BUG_ON() is just as bad as BUG_ON(), because it will crash the kernel on distributions that enable CONFIG_DEBUG_VM (like Fedora): VM_BUG_ON() has the exact same semantics as BUG_ON. It is literally no different, the only difference is "we can make the code smaller because these are less important". [2] This resulted in a more generic discussion about usage of BUG() and friends. While there might be corner cases that still deserve a BUG_ON(), most BUG_ON() cases should simply use WARN_ON_ONCE() and implement a recovery path if reasonable: The only possible case where BUG_ON can validly be used is "I have some fundamental data corruption and cannot possibly return an error". [2] As a very good approximation is the general rule: "absolutely no new BUG_ON() calls _ever_" [2] ... not even if something really shouldn't ever happen and is merely for documenting that an invariant always has to hold. However, there are sill exceptions where BUG_ON() may be used: If you have a "this is major internal corruption, there's no way we can continue", then BUG_ON() is appropriate. [3] There is only one good BUG_ON(): Now, that said, there is one very valid sub-form of BUG_ON(): BUILD_BUG_ON() is absolutely 100% fine. [2] While WARN will also crash the machine with panic_on_warn set, that's exactly to be expected: So we have two very different cases: the "virtual machine with good logging where a dead machine is fine" - use 'panic_on_warn'. And the actual real hardware with real drivers, running real loads by users. [4] The basic idea is that warnings will similarly get reported by users and be found during testing. However, in contrast to a BUG(), there is a way to actually influence the expected behavior (e.g., panic_on_warn) and to eventually keep the machine alive to extract some debug info. Ingo notes that not all WARN_ON_ONCE cases need recovery. If we don't ever expect this code to trigger in any case, recovery code is not really helpful. I'd prefer to keep all these warnings 'simple' - i.e. no attempted recovery & control flow, unless we ever expect these to trigger. [5] There have been different rules floating around that were never properly documented. Let's try to clarify. [1] https://lkml.kernel.org/r/CAHk-=wiEAH+ojSpAgx_Ep=NKPWHU8AdO3V56BXcCsU97oYJ1EA@mail.gmail.com [2] https://lore.kernel.org/r/CAHk-=wg40EAZofO16Eviaj7mfqDhZ2gVEbvfsMf6gYzspRjYvw@mail.gmail.com [3] https://lkml.kernel.org/r/CAHk-=wit-DmhMfQErY29JSPjFgebx_Ld+pnerc4J2Ag990WwAA@mail.gmail.com [4] https://lore.kernel.org/r/CAHk-=wgF7K2gSSpy=m_=K3Nov4zaceUX9puQf1TjkTJLA2XC_g@mail.gmail.com [5] https://lore.kernel.org/r/YwIW+mVeZoTOxn%2F4@gmail.com Reviewed-by: John Hubbard Signed-off-by: David Hildenbrand Link: https://lore.kernel.org/r/20220923113426.52871-2-david@redhat.com Signed-off-by: Jonathan Corbet --- Documentation/process/coding-style.rst | 62 ++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) (limited to 'Documentation') diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 03eb53fd029a..007e49ef6cec 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1186,6 +1186,68 @@ expression used. For instance: #endif /* CONFIG_SOMETHING */ +22) Do not crash the kernel +--------------------------- + +In general, the decision to crash the kernel belongs to the user, rather +than to the kernel developer. + +Avoid panic() +************* + +panic() should be used with care and primarily only during system boot. +panic() is, for example, acceptable when running out of memory during boot and +not being able to continue. + +Use WARN() rather than BUG() +**************************** + +Do not add new code that uses any of the BUG() variants, such as BUG(), +BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably +WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not +required if there is no reasonable way to at least partially recover. + +"I'm too lazy to do error handling" is not an excuse for using BUG(). Major +internal corruptions with no way of continuing may still use BUG(), but need +good justification. + +Use WARN_ON_ONCE() rather than WARN() or WARN_ON() +************************************************** + +WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it +is common for a given warning condition, if it occurs at all, to occur +multiple times. This can fill up and wrap the kernel log, and can even slow +the system enough that the excessive logging turns into its own, additional +problem. + +Do not WARN lightly +******************* + +WARN*() is intended for unexpected, this-should-never-happen situations. +WARN*() macros are not to be used for anything that is expected to happen +during normal operation. These are not pre- or post-condition asserts, for +example. Again: WARN*() must not be used for a condition that is expected +to trigger easily, for example, by user space actions. pr_warn_once() is a +possible alternative, if you need to notify the user of a problem. + +Do not worry about panic_on_warn users +************************************** + +A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an +available kernel option, and that many users set this option. This is why +there is a "Do not WARN lightly" writeup, above. However, the existence of +panic_on_warn users is not a valid reason to avoid the judicious use +WARN*(). That is because, whoever enables panic_on_warn has explicitly +asked the kernel to crash if a WARN*() fires, and such users must be +prepared to deal with the consequences of a system that is somewhat more +likely to crash. + +Use BUILD_BUG_ON() for compile-time assertions +********************************************** + +The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a +compile-time assertion that has no effect at runtime. + Appendix I) References ---------------------- -- cgit v1.2.3