From 01178ee713100c7d7e738992134545acff472d1d Mon Sep 17 00:00:00 2001 From: Lukas Bulwahn Date: Mon, 20 Feb 2023 17:57:49 +0100 Subject: [PATCH 1/4] docs: locking: refer to the actual existing config names The config is actually called CONFIG_RT_MUTEXES, not CONFIG_RT_MUTEX. The config CONFIG_LOCK_TORTURE_TEST should be connected by underscore, for the sake of consistent referencing to configs in the kernel documentation. Address those issues. Signed-off-by: Lukas Bulwahn Acked-by: Waiman Long Link: https://lore.kernel.org/r/20230220165749.12850-1-lukas.bulwahn@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/locking/locktorture.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst index dfaf9fc883f4..7f56fc0d7c31 100644 --- a/Documentation/locking/locktorture.rst +++ b/Documentation/locking/locktorture.rst @@ -5,7 +5,7 @@ Kernel Lock Torture Test Operation CONFIG_LOCK_TORTURE_TEST ======================== -The CONFIG LOCK_TORTURE_TEST config option provides a kernel module +The CONFIG_LOCK_TORTURE_TEST config option provides a kernel module that runs torture tests on core kernel locking primitives. The kernel module, 'locktorture', may be built after the fact on the running kernel to be tested, if desired. The tests periodically output status @@ -67,7 +67,7 @@ torture_type - "rtmutex_lock": rtmutex_lock() and rtmutex_unlock() pairs. - Kernel must have CONFIG_RT_MUTEX=y. + Kernel must have CONFIG_RT_MUTEXES=y. - "rwsem_lock": read/write down() and up() semaphore pairs. From 1481df6cbd0d606fa1a26b752e2e1aba0b650093 Mon Sep 17 00:00:00 2001 From: Carlos Bilbao Date: Tue, 7 Feb 2023 16:08:44 -0600 Subject: [PATCH 2/4] docs/sp_SP: Add process programming-language translation Translate Documentation/process/programming-language.rst into Spanish. Signed-off-by: Carlos Bilbao Link: https://lore.kernel.org/r/20230207220844.2661295-1-carlos.bilbao@amd.com Signed-off-by: Jonathan Corbet --- .../translations/sp_SP/process/index.rst | 1 + .../sp_SP/process/programming-language.rst | 53 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 Documentation/translations/sp_SP/process/programming-language.rst diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index c978a8132ce1..0f1e131b3bb1 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -17,3 +17,4 @@ kernel-enforcement-statement email-clients magic-number + programming-language diff --git a/Documentation/translations/sp_SP/process/programming-language.rst b/Documentation/translations/sp_SP/process/programming-language.rst new file mode 100644 index 000000000000..301f525372d8 --- /dev/null +++ b/Documentation/translations/sp_SP/process/programming-language.rst @@ -0,0 +1,53 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/programming-language.rst ` +:Translator: Carlos Bilbao + +.. _sp_programming_language: + +Lenguaje de programación +======================== + +El kernel está escrito en el lenguaje de programación C [sp-c-language]_. +Más concretamente, el kernel normalmente se compila con ``gcc`` [sp-gcc]_ +bajo ``-std=gnu11`` [sp-gcc-c-dialect-options]_: el dialecto GNU de ISO C11. +``clang`` [sp-clang]_ también es compatible, consulte los documentos en +:ref:`Building Linux with Clang/LLVM `. + +Este dialecto contiene muchas extensiones del lenguaje [sp-gnu-extensions]_, +y muchos de ellos se usan dentro del kernel de forma habitual. + +Hay algo de soporte para compilar el núcleo con ``icc`` [sp-icc]_ para varias +de las arquitecturas, aunque en el momento de escribir este texto, eso no +está terminado y requiere parches de terceros. + +Atributos +--------- + +Una de las comunes extensiones utilizadas en todo el kernel son los atributos +[sp-gcc-attribute-syntax]_. Los atributos permiten introducir semántica +definida por la implementación a las entidades del lenguaje (como variables, +funciones o tipos) sin tener que hacer cambios sintácticos significativos +al idioma (por ejemplo, agregar una nueva palabra clave) [sp-n2049]_. + +En algunos casos, los atributos son opcionales (es decir, hay compiladores +que no los admiten pero de todos modos deben producir el código adecuado, +incluso si es más lento o no realiza tantas comprobaciones/diagnósticos en +tiempo de compilación). + +El kernel define pseudo-palabras clave (por ejemplo, ``__pure``) en lugar +de usar directamente la sintaxis del atributo GNU (por ejemplo, +``__attribute__((__pure__))``) con el fin de detectar cuáles se pueden +utilizar y/o acortar el código. + +Por favor consulte ``include/linux/compiler_attributes.h`` para obtener +más información. + +.. [sp-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [sp-gcc] https://gcc.gnu.org +.. [sp-clang] https://clang.llvm.org +.. [sp-icc] https://software.intel.com/en-us/c-compilers +.. [sp-gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [sp-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [sp-gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [sp-n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf From b8885e2615f4d623334855e7fad20e49b0e0f96d Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 14 Feb 2023 16:57:26 -0800 Subject: [PATCH 3/4] Documentation: front page: use recommended heading adornments Convert the Documentation front page to use the heading adornments that are documented in doc-guide/sphinx.rst for document title and chapters. I.e., convert most section headings to chapters. This leaves "Indices and tables" as a chapter entry at the same level as the other chapters. The only visual difference from before to after is that the "Indices and tables" heading is smaller and has more vertical whitespace preceding it (although that may depend on the web browser being used). Fixes: 0c7b4366f1ab ("docs: Rewrite the front page") Signed-off-by: Randy Dunlap Cc: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/20230215005726.27320-1-rdunlap@infradead.org Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index bf6aa681c960..76d1a3ec9be3 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -2,6 +2,7 @@ .. _linux_doc: +============================== The Linux Kernel documentation ============================== @@ -13,7 +14,7 @@ documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. Working with the development community --------------------------------------- +====================================== The essential guides for interacting with the kernel's development community and getting your work upstream. @@ -29,7 +30,7 @@ community and getting your work upstream. Internal API manuals --------------------- +==================== Manuals for use by developers working to interface with the rest of the kernel. @@ -43,7 +44,7 @@ kernel. Locking in the kernel Development tools and processes -------------------------------- +=============================== Various other manuals with useful information for all kernel developers. @@ -62,7 +63,7 @@ Various other manuals with useful information for all kernel developers. 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 and application @@ -81,7 +82,7 @@ See also: the `Linux man pages `_, which are kept separately from the kernel's own documentation. Firmware-related documentation ------------------------------- +============================== The following holds information on the kernel's expectations regarding the platform firmwares. @@ -93,7 +94,7 @@ platform firmwares. Architecture-specific documentation ------------------------------------ +=================================== .. toctree:: :maxdepth: 2 @@ -102,7 +103,7 @@ Architecture-specific documentation Other documentation -------------------- +=================== There are several unsorted documents that don't seem to fit on other parts of the documentation body, or may require some adjustments and/or conversion @@ -115,7 +116,7 @@ to ReStructured Text format, or are simply too old. Translations ------------- +============ .. toctree:: :maxdepth: 2 From 901578a45950bcc4d5055a24e9016d61b84dc1a2 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Tue, 14 Feb 2023 11:13:51 +0100 Subject: [PATCH 4/4] docs: recommend using Link: whenever using Reported-by: Encourage developers to place Link: tag pointing to the report when they are using Reported-by: tags. Those links are often extremely useful for any code archaeologist that wants to know more about the backstory of a change than the commit message provides. That includes maintainers higher up in the patch-flow hierarchy, which is why Linus asks developers to add such links [1, 2, 3]. To quote [1]: > Again, the commit has a link to the patch *submission*, which is > almost entirely useless. There's no link to the actual problem the > patch fixes. > > [...] > > Put another way: I can see that > > Reported-by: Zhangfei Gao > > in the commit, but I don't have a clue what the actual report was, and > there really isn't enough information in the commit itself, except for > a fairly handwavy "Device drivers might, for instance, still need to > flush operations.." > > I don't want to know what device drivers _might_ do. I would want to > have an actual pointer to what they do and where. Another reason why these links are wanted: the ongoing regression tracking efforts can only scale with them, as they allow the regression tracking bot 'regzbot' to automatically connect tracked reports with patches that are posted or committed to fix tracked regressions. Link: https://lore.kernel.org/all/CAHk-=wjMmSZzMJ3Xnskdg4+GGz=5p5p+GSYyFBTh0f-DgvdBWg@mail.gmail.com/ [1] Link: https://lore.kernel.org/all/CAHk-=wgs38ZrfPvy=nOwVkVzjpM3VFU1zobP37Fwd_h9iAD5JQ@mail.gmail.com/ [2] Link: https://lore.kernel.org/all/CAHk-=wjxzafG-=J8oT30s7upn4RhBs6TX-uVFZ5rME+L5_DoJA@mail.gmail.com/ [3] Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/9a07ec640d809723492f8ade4f54705914e80419.1676369564.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet --- Documentation/process/5.Posting.rst | 3 ++- Documentation/process/submitting-patches.rst | 9 +++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index d87f1fee4cbc..7a670a075ab6 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -251,7 +251,8 @@ The tags in common use are: - Reported-by: names a user who reported a problem which is fixed by this patch; this tag is used to give credit to the (often underappreciated) people who test our code and let us know when things do not work - correctly. + correctly. Note, this tag should be followed by a Link: tag pointing to the + report, unless the report is not available on the web. - Cc: the named person received a copy of the patch and had the opportunity to comment on it. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 7dc94555417d..1e009dbe6991 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -496,10 +496,11 @@ Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: ---------------------------------------------------------------------- The Reported-by tag gives credit to people who find bugs and report them and it -hopefully inspires them to help us again in the future. Please note that if -the bug was reported in private, then ask for permission first before using the -Reported-by tag. The tag is intended for bugs; please do not use it to credit -feature requests. +hopefully inspires them to help us again in the future. The tag is intended for +bugs; please do not use it to credit feature requests. The tag should be +followed by a Link: tag pointing to the report, unless the report is not +available on the web. Please note that if the bug was reported in private, then +ask for permission first before using the Reported-by tag. A Tested-by: tag indicates that the patch has been successfully tested (in some environment) by the person named. This tag informs maintainers that