From nobody Thu Dec 18 00:27:12 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 079FB18A6D5; Fri, 13 Dec 2024 18:21:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114090; cv=none; b=L4IAFNLbM3cKh2ZQGF6Ajl1dis2HqNCm1oypx0bosXJj7QnrQ21/xY/WA+OOlsKP7twZsb2qpEZH5mGn5LIPm0T4ICJOQpACPFMpwocns2JDqWGKXnRlf64XW1SyaITzl5RBCbhbpXrFwh2f0Rul5NJhUZUvzb743jYHMBhYmCM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114090; c=relaxed/simple; bh=P0PrWDL3CG+647eom8x1NzoVJppZe2tsxKJaG5QN0iM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Ff8Wr7Y6rCRQ66KHbYcZg1nrV6uSVNVGl6tGg7W0VmOfkIo0lbXaPtXwu0DAyfr+n1dPyRyix5k7qgL8cN5u1NlN5qDYI5VjM8z1bm8z/LlV6th3TODUjruBnRoQoc6FCdwfal6Gtoi3rstWKhYlGQ1vVk9ERDyv6cVPXpYJNW8= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=VyUn/nkK; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="VyUn/nkK" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 36BD9403FD DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1734114088; bh=QXEu0v0T33DDpelHsiC6ROVGofv4AqOE4HtQlF7GJzE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=VyUn/nkKs1nVzPnAY8U1r5u3I4UaBtmNC6qhCRkia2IdXbdgFOo/IQpPm2OFffuR+ A0ybZmi6gS6+zRCMlw9G4XfBHmkTHFCGKCukd3QqNO6BM6U/T8RCACAZnFz4n5fJj4 xdxNnW7QkOaGfM/zq0XrVPUilftGliWZ7dH8lfmkI+0JtAMLBXdK5+b+8tHP/BnuFA rmjJuo6WAlPYzbZ38ssR6DPmFK2adQnm0VNrGoN3KSVdIHyXAHiMHR4a+CUTri7ehA fl6GTMahRc70emKDCKVr6FBlWPIh6WJmFen/aSPvrrxKB3s9Qcet47l4kkF2R+mX0k O6abUkIcEiQow== Received: from trenco.lwn.net (unknown [IPv6:2601:280:5e00:625::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 36BD9403FD; Fri, 13 Dec 2024 18:21:28 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 1/3] docs: admin-guide: join the sysfs information in one place Date: Fri, 13 Dec 2024 11:20:52 -0700 Message-ID: <20241213182057.343527-2-corbet@lwn.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241213182057.343527-1-corbet@lwn.net> References: <20241213182057.343527-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The documents describing sysfs are spread out in the admin guide; bring them together in one place. Signed-off-by: Jonathan Corbet Reviewed-by: Bagas Sanjaya Reviewed-by: Randy Dunlap --- Documentation/admin-guide/index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guid= e/index.rst index 15a522a96e76..94b70bb203cc 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -19,7 +19,6 @@ etc. devices sysctl/index =20 - abi features =20 This section describes CPU vulnerabilities and their mitigations. @@ -49,14 +48,14 @@ problems and bugs in particular. perf/index pstore-blk =20 -This is the beginning of a section with information of interest to -application developers. Documents covering various aspects of the kernel -ABI will be found here. +A big part of the kernel's administrative interface is the sysfs virtual +filesystem; these documents describe how to interact with sysfs. =20 .. toctree:: :maxdepth: 1 =20 sysfs-rules + abi =20 This is the beginning of a section with information of interest to application developers and system integrators doing analysis of the --=20 2.47.1 From nobody Thu Dec 18 00:27:12 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 9C27F1AC8B9; Fri, 13 Dec 2024 18:21:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114091; cv=none; b=OMdCMyTGqXW3EOONg40dJUpHxH+YTwUjvC+MIy4DISoZBpGtedeOHYA576pK3qtq01nbTQCO4RQ92f18bHE0CCEo1PSkirWmt2JExesyLyQHe7Yd9EWJsmhziGF2ZJ/qi7XUadJ/m3Eo3hKyauOPXvOLwAQdLe4TMDWftkJvT8U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114091; c=relaxed/simple; bh=jm7N5YKqnQnD9VuuO+738auNMFHpTFzR2WtTBGXDk4A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=ZgE3KFbKGn9vyLrMAECxQPwXJqJkm2f9W7S83AqgYAyyHom7A7WiIFJPM3S5phTOJZzh9znXnutpq3XrO+xood97jNQmmHoYXlzsjwcV7DCHI4W534N2t8q9u/6nT+Mys8i0DKpPHeajy8RyklDAg14r7RCaTyUf0mipOL9lMuY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=FQujxeoo; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="FQujxeoo" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net A6FF64040F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1734114088; bh=4bzl5OvAbFEFDVzd4foCsplht08EqOXC8NWYSa15j/c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=FQujxeoonO+ctAlaNftsh/fIQzhQ/5y6ZqaJItsEp78inbxMu7KOnAGK+wkDD0TvX baJLbi7HCep6kFVKxidJnIdgqkrYntA4KPpLtfbNbugIL4Vg0hYNH4JjYA2lA2+bfU S6xPqZHtvZWmJjTo2YjPWwoXWb1KnMuiu6wAPLqYy7bUEbI4eIh1Fez1HHpsNqh4QY tPl7/F4mx0dLAKl7/EHA8ND+Xfav9+RZWt0fangamonb9TYukLgiRmqWpZoXac8UBX 7ZuFEK4xlL/xP1J2j61IpeXU3PDGAZGVrx1a5Ff7Tv5GVc9O6bJJgFb1j09BIZH/+Q DC1U4LKldbtMA== Received: from trenco.lwn.net (unknown [IPv6:2601:280:5e00:625::1fe]) by ms.lwn.net (Postfix) with ESMTPA id A6FF64040F; Fri, 13 Dec 2024 18:21:28 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 2/3] docs: admin-guide: add some subsection headings Date: Fri, 13 Dec 2024 11:20:53 -0700 Message-ID: <20241213182057.343527-3-corbet@lwn.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241213182057.343527-1-corbet@lwn.net> References: <20241213182057.343527-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable As part of the goal of bringing some order to this file, add subsection headings to help readers find what they are looking for. Signed-off-by: Jonathan Corbet Reviewed-by: Bagas Sanjaya Reviewed-by: Randy Dunlap --- Documentation/admin-guide/index.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guid= e/index.rst index 94b70bb203cc..6864b079b391 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -7,6 +7,9 @@ added to the kernel over time. There is, as yet, little ov= erall order or organization here =E2=80=94 this material was not written to be a single, = coherent document! With luck things will improve quickly over time. =20 +General guides to kernel administration +--------------------------------------- + This initial section contains overall information, including the README file describing the kernel as a whole, documentation on kernel parameters, etc. @@ -28,6 +31,9 @@ This section describes CPU vulnerabilities and their miti= gations. =20 hw-vuln/index =20 +Tracking down and identifying problems +-------------------------------------- + Here is a set of documents aimed at users who are trying to track down problems and bugs in particular. =20 @@ -48,6 +54,9 @@ problems and bugs in particular. perf/index pstore-blk =20 +sysfs +----- + A big part of the kernel's administrative interface is the sysfs virtual filesystem; these documents describe how to interact with sysfs. =20 @@ -57,6 +66,9 @@ filesystem; these documents describe how to interact with= sysfs. sysfs-rules abi =20 +Workload analysis +----------------- + This is the beginning of a section with information of interest to application developers and system integrators doing analysis of the Linux kernel for safety critical applications. Documents supporting @@ -68,6 +80,9 @@ subsystems expectations will be found here. =20 workload-tracing =20 +Everything else +--------------- + The rest of this manual consists of various unordered guides on how to configure specific aspects of kernel behavior to your liking. =20 --=20 2.47.1 From nobody Thu Dec 18 00:27:12 2025 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E2DD41E048B; Fri, 13 Dec 2024 18:21:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=45.79.88.28 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114091; cv=none; b=mglVqCTpd6fSjHxjj/hg/RhDfbMCM1JBb/ZR3K+WUa6DCQo5eMD025W7bXANyWBLy7IbPBoTFXkOb73sAdm1Kj1ik9KbACLjwuvCc2NYn6yavCFy1cMMukNdPRe48zi2VC/Q3J9aFvbM5LqKHPHTte8vR1/YmMKape6BManLdp4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1734114091; c=relaxed/simple; bh=FjPXo6BxFKKLA8ZrbiSiN4Fx69AHdFEAFlcVbFHNz4s=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ZrhopBiKyPtTjVMsJYGoxZAoAoish+D33/nBjsVl3oBGgPf+gFLz+ISA7GE1YXmU0ZwhS2WPYgO5GbjHkVLplUWzg+G9iD975lH/gVF8rDNJtjw/Ed1ZILRJf6NTmpaMZEFHYzAIqLoZXLWHGfw0QrsLFjdmqChf/84diwkMlck= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net; spf=pass smtp.mailfrom=lwn.net; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b=jiXHgLc+; arc=none smtp.client-ip=45.79.88.28 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=lwn.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=lwn.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=lwn.net header.i=@lwn.net header.b="jiXHgLc+" DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 186E0404EA DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1734114089; bh=F6/aLflciz6wVnpv9AxpaYczVWgHDtrn6Q0EXWxfMWs=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jiXHgLc+u3SAk5aJiklQ2ednZdNnnbtap9Bdy9B2XWgf9Ec1v3RhricJ3VfVYx4yA fpA2YiHSihRbtAi+zgBwsFvTCy4/jpc1lZsnDEOOY4t3e7sgmB7+ICo76u+Th3qyZD QpUNEMlJ2/RqaB+1zqzsGxWQ0Gx7xzSXV+p7F5RAnRSsFep2MAJ7DZ1C/QQs2DqpaE VfMduuZR00lzVp5r2xc3/C7AB78OmKihv5CCDfo9d1jMBKiP3lbrsAALSd+FrDo0Lj IR59GBNStrhznFCzpjffA79B/piPOuGz5Hht/CfpifIK5W/oGXbcDZEc1Q4nhV5H6t bTp88OF3x2puQ== Received: from trenco.lwn.net (unknown [IPv6:2601:280:5e00:625::1fe]) by ms.lwn.net (Postfix) with ESMTPA id 186E0404EA; Fri, 13 Dec 2024 18:21:29 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH 3/3] docs: admin-guide: bring some order to the "everything else" section Date: Fri, 13 Dec 2024 11:20:54 -0700 Message-ID: <20241213182057.343527-4-corbet@lwn.net> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20241213182057.343527-1-corbet@lwn.net> References: <20241213182057.343527-1-corbet@lwn.net> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The bulk of the admin guide had become a big pile of stuff haphazardly tossed together, mostly in the catch-all "everything else" section. Split that section into a few broad categories and sort the documents into them as appropriate. No documents have been added or removed, they are just reordered. Note that many of these documents are severely obsolete and should be considered for removal. Signed-off-by: Jonathan Corbet Reviewed-by: Bagas Sanjaya Reviewed-by: Randy Dunlap --- Documentation/admin-guide/index.rst | 161 +++++++++++++++++----------- 1 file changed, 100 insertions(+), 61 deletions(-) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guid= e/index.rst index 6864b079b391..c8af32a8f800 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -18,18 +18,41 @@ etc. :maxdepth: 1 =20 README - kernel-parameters devices - sysctl/index =20 features =20 -This section describes CPU vulnerabilities and their mitigations. +A big part of the kernel's administrative interface is the /proc and sysfs +virtual filesystems; these documents describe how to interact with tem + +.. toctree:: + :maxdepth: 1 + + sysfs-rules + sysctl/index + cputopology + abi + +Security-related documentation: =20 .. toctree:: :maxdepth: 1 =20 hw-vuln/index + LSM/index + perf-security + +Booting the kernel +------------------ + +.. toctree:: + :maxdepth: 1 + + bootconfig + kernel-parameters + efi-stub + initrd + =20 Tracking down and identifying problems -------------------------------------- @@ -53,104 +76,120 @@ problems and bugs in particular. kdump/index perf/index pstore-blk + clearing-warn-once + kernel-per-CPU-kthreads + lockup-watchdogs + RAS/index + sysrq + =20 -sysfs ------ +Core-kernel subsystems +---------------------- =20 -A big part of the kernel's administrative interface is the sysfs virtual -filesystem; these documents describe how to interact with sysfs. +These documents describe core-kernel administration interfaces that are +likely to be of interest on almost any system. =20 .. toctree:: :maxdepth: 1 =20 - sysfs-rules - abi - -Workload analysis ------------------ + cgroup-v2 + cgroup-v1/index + cpu-load + mm/index + module-signing + namespaces/index + numastat + pm/index + syscall-user-dispatch =20 -This is the beginning of a section with information of interest to -application developers and system integrators doing analysis of the -Linux kernel for safety critical applications. Documents supporting -analysis of kernel interactions with applications, and key kernel -subsystems expectations will be found here. +Support for non-native binary formats. Note that some of these +documents are ... old ... =20 .. toctree:: :maxdepth: 1 =20 - workload-tracing + binfmt-misc + java + mono =20 -Everything else ---------------- =20 -The rest of this manual consists of various unordered guides on how to -configure specific aspects of kernel behavior to your liking. +Block-layer and filesystem administration +----------------------------------------- =20 .. toctree:: :maxdepth: 1 =20 - acpi/index - aoe/index - auxdisplay/index bcache binderfs - binfmt-misc blockdev/index - bootconfig - braille-console - btmrvl - cgroup-v1/index - cgroup-v2 cifs/index - clearing-warn-once - cpu-load - cputopology - dell_rbu device-mapper/index - edid - efi-stub ext4 filesystem-monitoring nfs/index - gpio/index - highuid - hw_random - initrd iostats - java jfs - kernel-per-CPU-kthreads + md + ufs + xfs + +Device-specific guides +---------------------- + +How to configure your hardware within your Linux system. + +.. toctree:: + :maxdepth: 1 + + acpi/index + aoe/index + auxdisplay/index + braille-console + btmrvl + dell_rbu + edid + gpio/index + hw_random laptops/index lcd-panel-cgram - ldm - lockup-watchdogs - LSM/index - md media/index - mm/index - module-signing - mono - namespaces/index - numastat + nvme-multipath parport - perf-security - pm/index pnp rapidio - RAS/index rtc serial-console svga - syscall-user-dispatch - sysrq thermal/index thunderbolt - ufs - unicode vga-softcursor video-output - xfs - nvme-multipath + +Workload analysis +----------------- + +This is the beginning of a section with information of interest to +application developers and system integrators doing analysis of the +Linux kernel for safety critical applications. Documents supporting +analysis of kernel interactions with applications, and key kernel +subsystems expectations will be found here. + +.. toctree:: + :maxdepth: 1 + + workload-tracing + +Everything else +--------------- + +A few hard-to-categorize and generally obsolete documents. + +.. toctree:: + :maxdepth: 1 + + highuid + ldm + unicode =20 .. only:: subproject and html =20 --=20 2.47.1