From nobody Thu Apr 2 15:04:09 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 6E3E0C54EE9 for ; Thu, 22 Sep 2022 20:42:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229996AbiIVUmD (ORCPT ); Thu, 22 Sep 2022 16:42:03 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44114 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229963AbiIVUmB (ORCPT ); Thu, 22 Sep 2022 16:42:01 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 419902BE03; Thu, 22 Sep 2022 13:42:00 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 80493735; Thu, 22 Sep 2022 20:41:59 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 80493735 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879319; bh=zC5DmfnmcyjofvsDiYdnGJiX2/WFvTpVfVyoJDzoBRw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=tZPw2TKP4JRFemmvCM8ulF8zPezrAaKTfjc3y+lD75IosWwhT3CVqE4GfNPO6ljwB MK7c4YtnxWAegAZVs0eI2OGWILlRFscaYYLcbvaslN5yDoMRFlOWGkpnSL8M0kDpKG Fo6hix36a3+gkyoB7UgMg048B5iFXCC8f0+FM3WXVE04b8a0cD7VcaUHM/J7nETFNX /+SYre1Wbv1roQMmItTFnchBtG9ZqNSjWg225dXWMi7eFKORBWW/lqq7e647liTZqX jlYcPkpXnknRRQbuo+tRS1JTSMvqQVO0yjBD7ENal/mTf28HxnVhVvtXNVy+37iMek oQDC30UgdW9LQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 1/7] docs: promote the title of process/index.html Date: Thu, 22 Sep 2022 14:41:32 -0600 Message-Id: <20220922204138.153146-2-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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 Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: David Vernet --- 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:04:09 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 77805C6FA82 for ; Thu, 22 Sep 2022 20:42:08 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230037AbiIVUmG (ORCPT ); Thu, 22 Sep 2022 16:42:06 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44214 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229974AbiIVUmC (ORCPT ); Thu, 22 Sep 2022 16:42:02 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 18FFA2BE00; Thu, 22 Sep 2022 13:42:00 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 2E284845; Thu, 22 Sep 2022 20:42:00 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2E284845 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879320; bh=hbXxi/o9yXRSMapz7jMNxcodnhQ4mcFG1KalhkuX7Qk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XjLMNb2qPbsA5ZboTItlvj7IxLkOdDjgyq2wh9jRKn+3E5J8bxq8c5JWAy/ioI5JP FGUNXBKcQpl9LoHQLDQ6pgNiv1emPWb3J+cKHMoGgFPvYaKR6PO6yDLi32G6Z5hO3k 3K8S4UtZ1Al5oxppmjl7r8lwVG+2/5zfwuDMiXciFTnT1p4Ize5UARXj7WaHRgE9/N Tfv/0GtdPgMSjWtNVL/04+7jrFOiJZsMlWJH0Iy9Gs9NzW4b+zuKYNoi9OPN4HiscH VpZ+rNxtmo5qi/y0lb5V1VZQJp05JouqutsogRoO+dK5N139M3ISea9YTcfDV0bKGS AWKaZSLqBHYdQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 2/7] docs: Rewrite the front page Date: Thu, 22 Sep 2022 14:41:33 -0600 Message-Id: <20220922204138.153146-3-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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. Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: David Vernet --- Documentation/index.rst | 150 +++++++++++-------------------- Documentation/subsystem-apis.rst | 58 ++++++++++++ 2 files changed, 111 insertions(+), 97 deletions(-) create mode 100644 Documentation/subsystem-apis.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index 4737c18c97ff..e0b593486e7d 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 @@ -150,7 +107,7 @@ Architecture-specific documentation ----------------------------------- =20 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 =20 arch =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:04:09 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 3FDA9C6FA8B for ; Thu, 22 Sep 2022 20:42:10 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230104AbiIVUmI (ORCPT ); Thu, 22 Sep 2022 16:42:08 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44216 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229978AbiIVUmC (ORCPT ); Thu, 22 Sep 2022 16:42:02 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7E2552BE01; Thu, 22 Sep 2022 13:42:01 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id BBA087F8; Thu, 22 Sep 2022 20:42:00 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net BBA087F8 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879321; bh=pjEqGsC3o1cCyVpcxwjXhbptLW8M3DxLII6MXHLKxx4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=iWbxNZ1XAipsse42nS+MNazVPJlCC7b34fZWJxBpwzReFOUFFM4i1f5/7aQZNXkTq 6yXrURAPxiLLTti3nYhSEg3Nqxi3mycUcXKQuQzTgGYzfen4TgK4pyH85jkONumqIY wzXvv6Hy7pQFgLCAMxl3cWBDslrmUubZTt4ppSnDIhUGV2QdUCUceKm/9/U6y+Q26A +XeWD/x5RZnFc08kYTCbwBoZ6NrxUPgsxWlH4dBwnZCUL61I7JGrelXIYuY+tK+3Da Dmvezp+UkU4vLurABReZjxVMBiXkidy7jdOGApP8VXNbsxoBtuPZVmmmu/fSZl18Ac C9vRbxVkf/aCA== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 3/7] docs: reconfigure the HTML left column Date: Thu, 22 Sep 2022 14:41:34 -0600 Message-Id: <20220922204138.153146-4-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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. Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: David Vernet --- 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:04:09 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 5A259ECAAD8 for ; Thu, 22 Sep 2022 20:42:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230110AbiIVUmM (ORCPT ); Thu, 22 Sep 2022 16:42:12 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44114 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229942AbiIVUmC (ORCPT ); Thu, 22 Sep 2022 16:42:02 -0400 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E55292BE03; Thu, 22 Sep 2022 13:42:01 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 56A42846; Thu, 22 Sep 2022 20:42:01 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 56A42846 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879321; bh=6sP6TgEn0oAnSqDQCNMm+wTqmFofLWhnY9PfhVjPR6Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=bA1vQkR7rycquO3nVRijtKMGdn4y5OwIK6pzfTYrRw8Rj+QOJzmu6R84dbo+V1vuj Q7ZOnZ6pS5A9d3jsqL9L0+iZeI3u8FYeCOp00V4DWJUPQTCZ4SbeeegsnuawtTNWU+ b1WaT6Il7y/pahhKPWzeNivOi9k6nyam+l/pNFa4vYu3gMb8MXVLi7EvDxdQKZATTn P1cOAoHgJxn6cJYbucV1MlsdJ/Ef5M8KX9XWTcijZyVTSwwPVbdWMpaIGQqcqnzUVo MAWTWIdnweJ0EiV2omLmXvhTJxSA30GGDZjJzqeXPJgirUUcMOXPjDvuP6ZM1LFkWW c+NJ40kKvg/UQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 4/7] docs: remove some index.rst cruft Date: Thu, 22 Sep 2022 14:41:35 -0600 Message-Id: <20220922204138.153146-5-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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. Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: David Vernet --- Documentation/index.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index e0b593486e7d..7f63f70bb8d6 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:04:09 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 B237CECAAD8 for ; Thu, 22 Sep 2022 20:42:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230138AbiIVUmS (ORCPT ); Thu, 22 Sep 2022 16:42:18 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44250 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229990AbiIVUmD (ORCPT ); Thu, 22 Sep 2022 16:42:03 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B43992BE06; Thu, 22 Sep 2022 13:42:02 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id E4A6D993; Thu, 22 Sep 2022 20:42:01 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E4A6D993 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879322; bh=l41J3Gn2aG8FufC8JDRIT1b+hjiJuDa/+pmymj285Ng=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=n+52tmkEcObgXX8PdkIzUtGU7ekOSAPpnBTJEUMzxyX+4ymLnthU7C9qS4BkQDsvh UpQwMIKQ0MYQgWKeQ6SrgziqkLYr+rkK54O50vxlR13bwSeKRqVwXALY7Wpu6hRH+5 jkpmjCgH2f0+8DRer9MiT0xvJdct3albmeg76Xb41VTbJIwqTQdsgPmj/0u4wCak2q kRppjPSQVvhmbMWdQ380vF/pGgzDBOmFqzHquqkoBR4jl3GuCO0Yw0uEESKjPqJZiw 0U41+sVBjgnmRNbEcA8mcaF1JdlXq3mXC3V3dRAtFmvORpHCj/HpwmercWWBgIQ+yo u5tAiG2oTJanQ== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet , Jiri Slaby Subject: [PATCH v2 5/7] docs: move asm-annotations.rst into core-api Date: Thu, 22 Sep 2022 14:41:36 -0600 Message-Id: <20220922204138.153146-6-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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. Cc: Jiri Slaby Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula Reviewed-by: David Vernet --- Documentation/{ =3D> core-api}/asm-annotations.rst | 7 ++++--- Documentation/core-api/index.rst | 1 + Documentation/index.rst | 8 -------- 3 files changed, 5 insertions(+), 11 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 7f63f70bb8d6..6d01c2e38573 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 --=20 2.37.2 From nobody Thu Apr 2 15:04:09 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 DF221C54EE9 for ; Thu, 22 Sep 2022 20:42:16 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230124AbiIVUmP (ORCPT ); Thu, 22 Sep 2022 16:42:15 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44252 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229993AbiIVUmD (ORCPT ); Thu, 22 Sep 2022 16:42:03 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2D7E62BE01; Thu, 22 Sep 2022 13:42:03 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 7B7593485; Thu, 22 Sep 2022 20:42:02 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 7B7593485 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879322; bh=mDxQXQ4NurBox4LsoF5to14jeYq+gAafXUk9PwOPWrk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Imj0aX1VxffoffDyE9sDm6f8S1Fqi7Gu4/og3bpqCvkvCTYVxBknNwT8FpGoZ68Dq J93aj1SSDQmctCdZ9dEeR7kwExw3gRaUQxXVN3Gkgnb+bdX3Y9RoADvHWv7H0Fs0RQ eUanToJFhiGDvD/7Hac6hLETLjD279hsQlvBT6o2icdaWQGL1fuZg3/pPl5y1QEfC4 RxuyQuZ7xb97gUVzfnamsGFydj0Znm749J6xsjS2u2fL9YBN5jFRSGOkjElAxDs5qf mnSUNllJnGfT+dSIvVE+gVNMd0kX6V5MCrONS/4GBCpRJcVBLyhOtp+eg7dnoOnXX1 e5mhF+WL9p/4g== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 6/7] docs: Expand the front-page CPU-architecture section Date: Thu, 22 Sep 2022 14:41:37 -0600 Message-Id: <20220922204138.153146-7-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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" Actually show the entries for individual architectures, since otherwise a single line reading "CPU architectures" is not very enlightening. We should really move all of the architecture directories under an arch/ directory, as we do with the top-level directory, but that's a task for another day. Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula --- Documentation/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index 6d01c2e38573..5a700548ae82 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -93,7 +93,7 @@ Architecture-specific documentation ----------------------------------- =20 .. toctree:: - :maxdepth: 1 + :maxdepth: 2 =20 arch =20 --=20 2.37.2 From nobody Thu Apr 2 15:04:09 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 4E72CC54EE9 for ; Thu, 22 Sep 2022 20:42:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230163AbiIVUmX (ORCPT ); Thu, 22 Sep 2022 16:42:23 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44276 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230001AbiIVUmE (ORCPT ); Thu, 22 Sep 2022 16:42:04 -0400 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A99B02BE08; Thu, 22 Sep 2022 13:42:03 -0700 (PDT) Received: from meer.lwn.net (unknown [IPv6:2601:281:8300:73::5f6]) by ms.lwn.net (Postfix) with ESMTPA id 10DB9383; Thu, 22 Sep 2022 20:42:03 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 10DB9383 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1663879323; bh=O2wLRUp8cjLqcHTIqydpm4tGkQwiA1in+6jJri0y4nA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Ad8lnygXLt0vmhNy/dCz41MGdUXuI/ASP146Pgk1SPcmUs3jWljzdzpNX0NsaDDpF w1g/Bxio6NG18RxTQva+byutgqYZ5Qhv/R50YwEDI/Z6hw1wUkEcD4qiIwmIlUUotK 99jNwFWxEPZz+hj+5hygo+MbdKQ42A/PZCk3FASOEGGORT7Fl9ObKcTAwfkyWn3zay ZNHDMe7CwQwUmfq1zqBnXzzBZQUJPW89iIhg/I/MkErY95AZJ5mS5RRAOed8bm70vO lBkedq0U+rj/6nNRY8cXbzvfZCo5aB4RAg1//e4hmp092mBTPirOtYRDlHlE1cMPZm mw3MOmjKVQL7w== From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Thorsten Leemhuis , Kees Cook , Jani Nikula , Jonathan Corbet Subject: [PATCH v2 7/7] docs: put atomic*.txt and memory-barriers.txt into the core-api book Date: Thu, 22 Sep 2022 14:41:38 -0600 Message-Id: <20220922204138.153146-8-corbet@lwn.net> X-Mailer: git-send-email 2.37.2 In-Reply-To: <20220922204138.153146-1-corbet@lwn.net> References: <20220922204138.153146-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. Signed-off-by: Jonathan Corbet Acked-by: Jani Nikula --- 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