From 2644ccef6f289c0bd545f5b79a4bfc6eb67318fe Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Oct 2020 10:51:08 +0100 Subject: docs: admin-guide: net.rst: add a missing blank line There's a missing blank line after a literal block, which causes this warning: Documentation/admin-guide/sysctl/net.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/b2545be4a4c71269d10278b5990c3e06c4b65f84.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/net.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 57fd6ce68fe0..f2ab8a5b6a4b 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -300,6 +300,7 @@ Note: 0: 0 1 2 3 4 5 6 7 RSS hash key: 84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89 + netdev_tstamp_prequeue ---------------------- -- cgit v1.2.3 From afc74ce7b484da5c5698d8eb2472a58c547cbc2b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Oct 2020 10:51:36 +0100 Subject: docs: SafeSetID: fix a warning As reported by Sphinx 2.4.4: docs/Documentation/admin-guide/LSM/SafeSetID.rst:110: WARNING: Title underline too short. Note on GID policies and setgroups() ================== Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/4afa281c170daabd1ce522653d5d5d5078ebd92c.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/LSM/SafeSetID.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 17996c9070e2..0ec34863c674 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -107,7 +107,7 @@ for a UID/GID will prevent that UID/GID from obtaining auxiliary setid privileges, such as allowing a user to set up user namespace UID/GID mappings. Note on GID policies and setgroups() -================== +==================================== In v5.9 we are adding support for limiting CAP_SETGID privileges as was done previously for CAP_SETUID. However, for compatibility with common sandboxing related code conventions in userspace, we currently allow arbitrary -- cgit v1.2.3 From a7ee04b3ef0d2b2514730928a04a112f04ffe7df Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:36 +0100 Subject: docs: add ABI documentation to the admin-guide book As we don't want a generic Sphinx extension to execute commands, change the one proposed to Markus to call the abi_book.pl script. Use a script to parse the Documentation/ABI directory and output it at the admin-guide. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/admin-guide/abi-obsolete.rst | 10 ++++++++++ Documentation/admin-guide/abi-removed.rst | 4 ++++ Documentation/admin-guide/abi-stable.rst | 13 +++++++++++++ Documentation/admin-guide/abi-testing.rst | 19 +++++++++++++++++++ Documentation/admin-guide/abi.rst | 11 +++++++++++ Documentation/admin-guide/index.rst | 2 ++ 6 files changed, 59 insertions(+) create mode 100644 Documentation/admin-guide/abi-obsolete.rst create mode 100644 Documentation/admin-guide/abi-removed.rst create mode 100644 Documentation/admin-guide/abi-stable.rst create mode 100644 Documentation/admin-guide/abi-testing.rst create mode 100644 Documentation/admin-guide/abi.rst (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst new file mode 100644 index 000000000000..cda9168445a5 --- /dev/null +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -0,0 +1,10 @@ +ABI obsolete symbols +==================== + +Documents interfaces that are still remaining in the kernel, but are +marked to be removed at some later point in time. + +The description of the interface will document the reason why it is +obsolete and when it can be expected to be removed. + +.. kernel-abi:: $srctree/Documentation/ABI/obsolete diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst new file mode 100644 index 000000000000..497978fc9632 --- /dev/null +++ b/Documentation/admin-guide/abi-removed.rst @@ -0,0 +1,4 @@ +ABI removed symbols +=================== + +.. kernel-abi:: $srctree/Documentation/ABI/removed diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst new file mode 100644 index 000000000000..7495d7a35048 --- /dev/null +++ b/Documentation/admin-guide/abi-stable.rst @@ -0,0 +1,13 @@ +ABI stable symbols +================== + +Documents the interfaces that the developer has defined to be stable. + +Userspace programs are free to use these interfaces with no +restrictions, and backward compatibility for them will be guaranteed +for at least 2 years. + +Most interfaces (like syscalls) are expected to never change and always +be available. + +.. kernel-abi:: $srctree/Documentation/ABI/stable diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst new file mode 100644 index 000000000000..5c886fc50b9e --- /dev/null +++ b/Documentation/admin-guide/abi-testing.rst @@ -0,0 +1,19 @@ +ABI testing symbols +=================== + +Documents interfaces that are felt to be stable, +as the main development of this interface has been completed. + +The interface can be changed to add new features, but the +current interface will not break by doing this, unless grave +errors or security problems are found in them. + +Userspace programs can start to rely on these interfaces, but they must +be aware of changes that can occur before these interfaces move to +be marked stable. + +Programs that use these interfaces are strongly encouraged to add their +name to the description of these interfaces, so that the kernel +developers can easily notify them if any changes occur. + +.. kernel-abi:: $srctree/Documentation/ABI/testing diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst new file mode 100644 index 000000000000..3b9645c77469 --- /dev/null +++ b/Documentation/admin-guide/abi.rst @@ -0,0 +1,11 @@ +===================== +Linux ABI description +===================== + +.. toctree:: + :maxdepth: 1 + + abi-stable + abi-testing + abi-obsolete + abi-removed diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index ed1cf94ea50c..4e0c4ae44acd 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -18,6 +18,8 @@ etc. devices sysctl/index + abi + This section describes CPU vulnerabilities and their mitigations. .. toctree:: -- cgit v1.2.3 From 642514df1bc1c6a9318b537670fdb55a6ee38e45 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:41 +0100 Subject: docs: ABI: make it parse ABI/stable as ReST-compatible files Now that the stable ABI files are compatible with ReST, parse them without converting complex descriptions as literal blocks nor escaping special characters. Please notice that escaping special characters will probably be needed at descriptions, at least for the asterisk character. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/59ccbaa75ff05f23e701dd9a0bbe118e9343a553.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/admin-guide/abi-stable.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst index 7495d7a35048..70490736e0d3 100644 --- a/Documentation/admin-guide/abi-stable.rst +++ b/Documentation/admin-guide/abi-stable.rst @@ -11,3 +11,4 @@ Most interfaces (like syscalls) are expected to never change and always be available. .. kernel-abi:: $srctree/Documentation/ABI/stable + :rst: -- cgit v1.2.3 From c12759ff2dd029ce74b026e6b6bc62060383a5a7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:42 +0100 Subject: docs: ABI: create a 2-depth index for ABI That helps to identify what ABI files are adding titles. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/e267b36ae7f32bab2a86f1da6b40bb3e62c877d4.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/admin-guide/abi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst index 3b9645c77469..bcab3ef2597c 100644 --- a/Documentation/admin-guide/abi.rst +++ b/Documentation/admin-guide/abi.rst @@ -3,7 +3,7 @@ Linux ABI description ===================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 abi-stable abi-testing -- cgit v1.2.3 From 7832dea738dc3ea4a40860dc8b9f83ca1e092ab9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:43 +0100 Subject: docs: ABI: don't escape ReST-incompatible chars from obsolete and removed With just a single fix, the contents there can be parsed properly without the need to escape any ReST incompatible stuff. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/472f4574b6aa2ff4de5a819db1a4a5c9a34f5168.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/admin-guide/abi-obsolete.rst | 1 + Documentation/admin-guide/abi-removed.rst | 1 + 2 files changed, 2 insertions(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst index cda9168445a5..d095867899c5 100644 --- a/Documentation/admin-guide/abi-obsolete.rst +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -8,3 +8,4 @@ The description of the interface will document the reason why it is obsolete and when it can be expected to be removed. .. kernel-abi:: $srctree/Documentation/ABI/obsolete + :rst: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst index 497978fc9632..f7e9e43023c1 100644 --- a/Documentation/admin-guide/abi-removed.rst +++ b/Documentation/admin-guide/abi-removed.rst @@ -2,3 +2,4 @@ ABI removed symbols =================== .. kernel-abi:: $srctree/Documentation/ABI/removed + :rst: -- cgit v1.2.3 From 50865d041eead18b110e589674ff91ffcd243e7e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:44 +0100 Subject: docs: abi-testing.rst: enable --rst-sources when building docs Now that ABI/testing documents were fixed, add --rst-sources to the ABI/testing too. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/9242473fd3df785565bb6084b1b814cc15074fb2.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/admin-guide/abi-testing.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst index 5c886fc50b9e..b205b16a72d0 100644 --- a/Documentation/admin-guide/abi-testing.rst +++ b/Documentation/admin-guide/abi-testing.rst @@ -17,3 +17,4 @@ name to the description of these interfaces, so that the kernel developers can easily notify them if any changes occur. .. kernel-abi:: $srctree/Documentation/ABI/testing + :rst: -- cgit v1.2.3 From 6841ca15fe13038b9d27f8e7168700e1427b7a72 Mon Sep 17 00:00:00 2001 From: Julia Lawall Date: Sat, 31 Oct 2020 10:39:28 +0100 Subject: Documentation: PM: cpuidle: correct typo cerainly -> certainly Signed-off-by: Julia Lawall Signed-off-by: Rafael J. Wysocki --- Documentation/admin-guide/pm/cpuidle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index 37940a0584ec..a26a94bc0071 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -494,7 +494,7 @@ object corresponding to it, as follows: residency. ``below`` - Total number of times this idle state had been asked for, but cerainly + Total number of times this idle state had been asked for, but certainly a deeper idle state would have been a better match for the observed idle duration. -- cgit v1.2.3 From 23d18dcfc5275fbd53a515a4a1cf946b22fe7463 Mon Sep 17 00:00:00 2001 From: Julia Lawall Date: Sat, 31 Oct 2020 10:39:39 +0100 Subject: Documentation: PM: cpuidle: correct path name cpu/ is needed before cpu/ Signed-off-by: Julia Lawall Signed-off-by: Rafael J. Wysocki --- Documentation/admin-guide/pm/cpuidle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst index a26a94bc0071..10fde58d0869 100644 --- a/Documentation/admin-guide/pm/cpuidle.rst +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -478,7 +478,7 @@ order to ask the hardware to enter that state. Also, for each statistics of the given idle state. That information is exposed by the kernel via ``sysfs``. -For each CPU in the system, there is a :file:`/sys/devices/system/cpu/cpuidle/` +For each CPU in the system, there is a :file:`/sys/devices/system/cpu/cpu/cpuidle/` directory in ``sysfs``, where the number ```` is assigned to the given CPU at the initialization time. That directory contains a set of subdirectories called :file:`state0`, :file:`state1` and so on, up to the number of idle state -- cgit v1.2.3