From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7BFCBC54EE9 for ; Tue, 27 Sep 2022 16:07:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232875AbiI0QHu (ORCPT ); Tue, 27 Sep 2022 12:07:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49872 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233038AbiI0QHa (ORCPT ); Tue, 27 Sep 2022 12:07:30 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 63C3D88DD0; Tue, 27 Sep 2022 09:06:14 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id BBD3B7C0; Tue, 27 Sep 2022 16:06:13 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BBD3B7C0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294774; bh=NQmxtQEpC+9DH6q+r1zxViObPFBeWowpPclmQS6mOUg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EFcQHzC6h+PT9jsWWqF/vEd5hGVbKEmKfGObf6ggYUu0yqH/3TeMZ0fSgS4QsvwD/ 7RDStbIVUKbZu8NZJH2jF/F00rKUBDWVR3NudJiuwLT5PezLtWuBTfRproZWHqv6Ju T4665ZeT+KHsSocQCsKn1y9AYPvq+MZnuG93eAz4CfIky+DcEnIMlVHDbrqEne9IjV TGzwhnRE7qLl24QY14iwmkGCdcb1V52EW8CRggrzjbBFSnSTb2VEIb0nEKmJIcYYVn R5wPCQlrCAPbXH96k48GfuWrlQlkr1kJ2+hF5/g2WpOYca6XgiFUmGZRF4kD8ZthTW wOBMmSJwZ6bfQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jani Nikula Subject: [PATCH v3 1/7] docs: promote the title of process/index.rst Date: Tue, 27 Sep 2022 10:05:53 -0600 Message-Id: <20220927160559.97154-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" ...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 --- Documentation/process/index.rst | 1 + 1 file changed, 1 insertion(+) 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 @@ =20 .. _process_index: =20 +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Working with the kernel development community =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 67E66C07E9D for ; Tue, 27 Sep 2022 16:08:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232268AbiI0QIE (ORCPT ); Tue, 27 Sep 2022 12:08:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49868 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232679AbiI0QHa (ORCPT ); Tue, 27 Sep 2022 12:07:30 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 576F612636; Tue, 27 Sep 2022 09:06:15 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 5EA1D734; Tue, 27 Sep 2022 16:06:14 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 5EA1D734 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294774; bh=UFYe8xzWcuhHcQH4mg5EAhC1oMb+VzADqFPyelWq9YE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=q0IlrMlmAoXaltAh1IGt8EiCQYVtD16CT3KW4wcrNrAyv6qX97oSOXNSfQjmxA0Yl lqDlnZCvyODndylh6vgJoO9sJjM2G0Jl9wI3nc6rbClkF5q2BgTVl/BdSG73tzcB1O 6KAcAFAmBKiSYcvp3joh39zzbYgeAV6NHzOsF+7b2oRVzKDgagdLlbzMScvzPNIbn1 sAedST2Q76GX1MwIAlvtOhFGr//fGTqT2Xf8BKSuVzehLwK+ntwcr+7ylqUQ5JgQYV 3IHh6ZeQU/xu0fSgS0pIlvoUATTzCyP+LLRz/CMCT4f1pcoyXQn4IjLElmF0C4C16V wQvPqR82QVvXw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jani Nikula Subject: [PATCH v3 2/7] docs: Rewrite the front page Date: Tue, 27 Sep 2022 10:05:54 -0600 Message-Id: <20220927160559.97154-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- Documentation/index.rst | 148 +++++++++++-------------------- Documentation/subsystem-apis.rst | 58 ++++++++++++ 2 files changed, 110 insertions(+), 96 deletions(-) create mode 100644 Documentation/subsystem-apis.rst 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 imp= rovements to the documentation are welcome; join the linux-doc list at vger.kernel.org if you want to help out. =20 -Licensing documentation ------------------------ +Working with the development community +-------------------------------------- =20 -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 =E2=80=94 thos= e 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. =20 .. 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 =20 -.. toctree:: - :maxdepth: 2 + process/development-process + process/submitting-patches + Code of conduct + maintainer/index + All development-process docs =20 - firmware-guide/index - devicetree/index =20 -Application-developer documentation ------------------------------------ +Internal API manuals +-------------------- =20 -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. =20 .. toctree:: - :maxdepth: 2 - - userspace-api/index + :maxdepth: 1 =20 + core-api/index + driver-api/index + subsystem-apis + Locking in the kernel =20 -Introduction to kernel development ----------------------------------- +Development tools and processes +------------------------------- =20 -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. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 - 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 =20 =20 -Kernel API documentation ------------------------- +User-oriented documentation +--------------------------- =20 -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 =E2=80=94 probably *not* al= l that is -needed). +The following manuals are written for *users* of the kernel =E2=80=94 thos= e 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. =20 .. 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 =20 - 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 =20 Architecture-agnostic documentation ----------------------------------- =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 asm-annotations =20 @@ -163,9 +120,8 @@ of the documentation body, or may require some adjustme= nts and/or conversion to ReStructured Text format, or are simply too old. =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 - tools/index staging/index =20 =20 diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-api= s.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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D +Kernel subsystem documentation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + +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 =E2=80=94 probably *not* al= l 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 --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 18583C07E9D for ; Tue, 27 Sep 2022 16:08:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232631AbiI0QIA (ORCPT ); Tue, 27 Sep 2022 12:08:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45972 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232851AbiI0QHa (ORCPT ); Tue, 27 Sep 2022 12:07:30 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E4AF913CF0; Tue, 27 Sep 2022 09:06:15 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id EC06F7DA; Tue, 27 Sep 2022 16:06:14 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net EC06F7DA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294775; bh=cuGw4du26WfBnI3n9GP89PwXgPcoYV+BdrHL5FFQfyo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=rJx/eGZPyZW7i4fLlp1toR1Ehf9Et1PGq3+KOvixc0GOew/FGgTEUk0BqydNq1yM5 DzWljfkfKDOWuPXGC/R+KpFjpvol4sOMNfH0wUpb+btD+mkkED/fXSN3blSdAGZmG3 p779PNzgGrnnvxS7QyRHT+ANOJO/Ay2P8FDf9gdGpOCXczLvvuhAdup7FZhD1j91Ud NskBx/vKt/Eoxj3rw3WBzHV1Ato3ipH+g7uq0+MqpM8iVItABMllzC4oTYzNFKpQjR iH/ClnY9MI2mhIrfDOnuzDyXwPOkpO1htjXpnv84XhMGHq9O72cblJsRRVSJAHkAbS mlsIzfZyi8bKw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jani Nikula Subject: [PATCH v3 3/7] docs: reconfigure the HTML left column Date: Tue, 27 Sep 2022 10:05:55 -0600 Message-Id: <20220927160559.97154-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- Documentation/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 78dd6d1e7b88..22c9d4df1967 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -370,7 +370,8 @@ html_static_path =3D ['sphinx-static'] html_use_smartypants =3D False =20 # Custom sidebar templates, maps document names to template names. -#html_sidebars =3D {} +# Note that the RTD theme ignores this. +html_sidebars =3D { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.= html']} =20 # Additional templates that should be rendered to pages, maps page names to # template names. --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5C65CC54EE9 for ; Tue, 27 Sep 2022 16:08:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233007AbiI0QIF (ORCPT ); Tue, 27 Sep 2022 12:08:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45982 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232712AbiI0QHc (ORCPT ); Tue, 27 Sep 2022 12:07:32 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B31F7A2A8A; Tue, 27 Sep 2022 09:06:16 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 8F5EA823; Tue, 27 Sep 2022 16:06:15 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 8F5EA823 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294776; bh=iwHrGHGlM3+zgEEEw8s3BogUveCH90vBib0d9fdqPx0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=kBzHBDXG0gi3tUzS/vpeTcqmjlhCtBbR+gJwNbTj+cveOmVrOlBaP6zMTuvodUPFS a2lxN1eT0DSbDj8seqkMSBxySuX8tciysAYCJrwPDR4k5QGIOHiCL3iTs1ZUmjshef 8dxpvmpHh77iFLHNLuAl3e/PhalgXJrkioIHKyTsaZZeMOd3Axqj/3wzrtbQakVWfh bYdyXD2cEV4ne4+RWe5oUX6fd9W8thTP7r75VO1iYzSD9VjDYZpytYW5JZBDtHQsYF w0p/jwAqApAom5dmYpfKDWBLiERSbayqw1fqosM9CMxFgJWuMRbcwDXFAy4Ey/Ei0m Yh/L5Wc2BH0+w== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jani Nikula Subject: [PATCH v3 4/7] docs: remove some index.rst cruft Date: Tue, 27 Sep 2022 10:05:56 -0600 Message-Id: <20220927160559.97154-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- Documentation/index.rst | 6 ------ 1 file changed, 6 deletions(-) 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 =20 - -.. 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 lea= st - contain the root `toctree` directive. - .. _linux_doc: =20 The Linux Kernel documentation --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 19EBEC07E9D for ; Tue, 27 Sep 2022 16:08:11 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233111AbiI0QII (ORCPT ); Tue, 27 Sep 2022 12:08:08 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33124 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232736AbiI0QHc (ORCPT ); Tue, 27 Sep 2022 12:07:32 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0A0BAB14F1; Tue, 27 Sep 2022 09:06:16 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 366BC7F8; Tue, 27 Sep 2022 16:06:16 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 366BC7F8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294776; bh=Fwtxq3iIjYwQxaI52YLezdXTv1SluuHrldzBLIG1uo0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LKVkY7nu+tM4Evl53NUeinYcIixA+N9Y4ehwB3Gke60aYLEnCwnegEzP3Ud0CQB6r 06mNGBy7cwNFjj2MzXw8vNhBxVS2tksO0AmetzIrwpTpsSRNitewpclFNOwwpwGDq4 XTqogzFXIlZBw4Rfw0F3Z+h+vGXBQ1Ni3+cEO3PSd6jWq5nI8dOMMxge97DqUTXpf/ JI2H92amiMEXpx/MpcmZa3+6o33t7UzMBdWG/Z1G/nKAeY991P+LyB6DhdLDlp0GgE yPRDmL++xkhbj3GY257wtiZg09xsk/XaTN5+JqJOTbBYo2KZqKLH9L/B5aK6fKjDV6 cZrsCzxy23Wpw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jiri Slaby , Jani Nikula Subject: [PATCH v3 5/7] docs: move asm-annotations.rst into core-api Date: Tue, 27 Sep 2022 10:05:57 -0600 Message-Id: <20220927160559.97154-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- Documentation/{ =3D> core-api}/asm-annotations.rst | 7 ++++--- Documentation/core-api/index.rst | 1 + Documentation/index.rst | 8 -------- scripts/checkpatch.pl | 2 +- 4 files changed, 6 insertions(+), 12 deletions(-) rename Documentation/{ =3D> core-api}/asm-annotations.rst (97%) diff --git a/Documentation/asm-annotations.rst b/Documentation/core-api/asm= -annotations.rst similarity index 97% rename from Documentation/asm-annotations.rst rename to Documentation/core-api/asm-annotations.rst index a64f2ca469d4..bc514ed59887 100644 --- a/Documentation/asm-annotations.rst +++ b/Documentation/core-api/asm-annotations.rst @@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them t= o 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 repo= rt missing frame pointer setup/destruction in functions. It can also -automatically generate annotations for :doc:`ORC unwinder ` +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 :doc:`Kernel live patching -`. +stack traces which are in turn necessary for kernel live patching +(Documentation/livepatch/livepatch.rst). =20 Caveat and Discussion --------------------- diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/inde= x.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 =20 Data structures and low-level utilities =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 =20 =20 -Architecture-agnostic documentation ------------------------------------ - -.. toctree:: - :maxdepth: 1 - - asm-annotations - Architecture-specific documentation ----------------------------------- =20 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 =3D~ /\.S$/ && $line =3D~ /^\+\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-annotatio= ns.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); } =20 # check we are in a valid source file C or perl if not then ignore this hu= nk --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3024AC54EE9 for ; Tue, 27 Sep 2022 16:08:27 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232903AbiI0QIY (ORCPT ); Tue, 27 Sep 2022 12:08:24 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46008 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233059AbiI0QHc (ORCPT ); Tue, 27 Sep 2022 12:07:32 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EB9FA56032; Tue, 27 Sep 2022 09:06:17 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id CCA5C8B2; Tue, 27 Sep 2022 16:06:16 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net CCA5C8B2 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294777; bh=Uq/aOCxVvfG5MiT72IUzEcUWMPEku718na4X3SHiJv4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lAgIYAZ6PrjRRclwu7LkcB1V3TeNrtyBCgV/Ivc+Z/k3G7G25KY+cybxfHz+DfKNn 32n4b1RLMwkv7Q+WY/3wJuNOmxTIb0nf2OjD8eYb/baSVVryjPe1F7zPDILxpWXdOI RGgpe6IqxGga/2MSdh+S7cAFnayjxZ8s4SU0cntSQoSkMVFxUfFjxc8L5d6O625WNw Ri5ZC1tQUFC9VVUQpwZEsinZ6tpliL7cYysJmIJeDu6r4kh+fOS078Niu8LDrPe5wG gvaj1xOO3NNwh+H89ceZd9bQKINNsqKHZpWCBA9IPQPXrAM++iUq3gUm9S2F2/t6EL gmpQ+8RKfTJwQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet , Jani Nikula Subject: [PATCH v3 6/7] docs: put atomic*.txt and memory-barriers.txt into the core-api book Date: Tue, 27 Sep 2022 10:05:58 -0600 Message-Id: <20220927160559.97154-7-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 Acked-by: Randy Dunlap Reviewed-by: David Vernet --- Documentation/core-api/index.rst | 3 ++ .../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 diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/inde= x.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 =20 Low level entry and exit =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -68,6 +70,7 @@ Documentation/locking/index.rst for more related document= ation. local_ops padata ../RCU/index + wrappers/memory-barriers.rst =20 Low-level hardware management =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D diff --git a/Documentation/core-api/wrappers/atomic_bitops.rst b/Documentat= ion/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. + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Atomic bitops +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_bitops.txt + :literal: + +.. raw:: latex + + \normalsize diff --git a/Documentation/core-api/wrappers/atomic_t.rst b/Documentation/c= ore-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. + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Atomic types +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. raw:: latex + + \footnotesize + +.. include:: ../../atomic_t.txt + :literal: + +.. raw:: latex + + \normalsize + diff --git a/Documentation/core-api/wrappers/memory-barriers.rst b/Document= ation/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. + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D +Linux kernel memory barriers +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D + +.. 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 -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_t.txt - :literal: - -.. raw:: latex - - \normalsize - -Atomic bitops -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -.. raw:: latex - - \footnotesize - -.. include:: ../atomic_bitops.txt - :literal: - -.. raw:: latex - - \normalsize - -Memory Barriers -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -.. raw:: latex - - \footnotesize - -.. include:: ../memory-barriers.txt - :literal: - -.. raw:: latex - - \normalsize --=20 2.37.2 From nobody Thu Apr 2 15:02:25 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 92F3AC54EE9 for ; Tue, 27 Sep 2022 16:08:18 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232566AbiI0QIO (ORCPT ); Tue, 27 Sep 2022 12:08:14 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46012 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233058AbiI0QHc (ORCPT ); Tue, 27 Sep 2022 12:07:32 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 1F5031BF0DD; Tue, 27 Sep 2022 09:06:17 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 64394844; Tue, 27 Sep 2022 16:06:17 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 64394844 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1664294777; bh=mYEI8X3YQvLK/RUu/d22/5zHkkKnMAgHHDcj2TDiJVY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=mb/pw2FS39AP+Af+44V0wdrH25DDwQiNiPhe5hGjVq7MeCtyiRR0kdx3rexffJXL8 ZWZ/EuFJWJOtW1Pm6ibk+COonfqqu6XQQwr8A77AgkhzeIBPVkByjUYNZPV8nxMbBW Z4g62f3NwcIfEgmY6+2eRWbq1B9Cfdqa43IHxJj8f6uNDQUQZV2ysoxiClY73cpG32 NfDprW83mv9xhENMHMHNyhn3AIxvYDTl6oL0YA7L8/M1F52hMsbuYUa4ibevJutw/n FDufSlH3enHKjLMN7n6+FvNTIPm4CJZ6GAVeHGH5QzOsKM+Im6VLkZw2r9CXMc5xQm vwBqYO+kHmoQw== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Joe Perches , David Vernet , Jonathan Corbet Subject: [PATCH v3 7/7] docs: add a man-pages link to the front page Date: Tue, 27 Sep 2022 10:05:59 -0600 Message-Id: <20220927160559.97154-8-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220927160559.97154-1-corbet@lwn.net> References: <20220927160559.97154-1-corbet@lwn.net> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Readers looking for user-oriented information may benefit from it. Signed-off-by: Jonathan Corbet Acked-by: Randy Dunlap Reviewed-by: David Vernet --- Documentation/index.rst | 2 ++ 1 file changed, 2 insertions(+) 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 =20 +See also: the `Linux man pages `_, +which are kept separately from the kernel's own documentation. =20 Firmware-related documentation ------------------------------ --=20 2.37.2