From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: "Mauro Carvalho Chehab" <mchehab+huawei@kernel.org>,
"Daniel W. S. Almeida" <dwlsalmeida@gmail.com>,
"Jonathan Corbet" <corbet@lwn.net>,
"Jonathan Neuschäfer" <j.neuschaefer@gmx.net>,
"Masami Hiramatsu" <mhiramat@kernel.org>,
linux-kernel@vger.kernel.org
Subject: [PATCH v2 17/39] docs: add ABI documentation to the admin-guide book
Date: Fri, 30 Oct 2020 08:40:36 +0100 [thread overview]
Message-ID: <5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1604042072.git.mchehab+huawei@kernel.org>
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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 ++
Documentation/conf.py | 3 ++-
7 files changed, 61 insertions(+), 1 deletion(-)
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
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::
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7ee05fd4cb17..ed2b43ec7754 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -38,7 +38,8 @@ needs_sphinx = '1.3'
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
- 'maintainers_include', 'sphinx.ext.autosectionlabel' ]
+ 'maintainers_include', 'sphinx.ext.autosectionlabel',
+ 'kernel_abi']
#
# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
--
2.26.2
next prev parent reply other threads:[~2020-10-30 7:43 UTC|newest]
Thread overview: 62+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-30 7:40 [PATCH v2 00/39] ABI: add it to the documentation build system Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 01/39] scripts: get_abi.pl: change script to allow parsing in ReST mode Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 02/39] scripts: get_abi.pl: fix parsing on " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 03/39] scripts: get_abi.pl: Allow optionally record from where a line came from Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 04/39] scripts: get_abi.pl: improve its parser to better catch up indentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 05/39] scripts: get_abi.pl: cleanup ABI cross-reference logic Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 06/39] scripts: get_abi.pl: detect duplicated ABI definitions Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 07/39] scripts: get_abi.pl: output users in ReST format Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 08/39] scripts: get_abi.pl: prevent duplicated file names Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 09/39] scripts: get_abi.pl: use bold font for ABI definitions Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 10/39] scripts: get_abi.pl: auto-generate cross references Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 11/39] docs: kernellog.py: add support for info() Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 12/39] docs: kernel_abi.py: add a script to parse ABI documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 13/39] docs: kernel_abi.py: fix UTF-8 support Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 14/39] docs: kernel_abi.py: make it compatible with Sphinx 1.7+ Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 15/39] docs: kernel_abi.py: use --enable-lineno for get_abi.pl Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 16/39] docs: kernel_abi.py: Handle with a lazy Sphinx parser Mauro Carvalho Chehab
2020-10-30 7:40 ` Mauro Carvalho Chehab [this message]
2020-10-30 7:40 ` [PATCH v2 18/39] docs: ABI: README: specify that files should be ReST compatible Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 19/39] docs: ABI: stable: make files " Mauro Carvalho Chehab
2020-10-30 10:04 ` Srinivas Kandagatla
2020-10-30 7:40 ` [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output Mauro Carvalho Chehab
2020-10-30 9:19 ` Fabrice Gasnier
2020-10-30 10:09 ` Mauro Carvalho Chehab
2020-11-02 11:04 ` Fabrice Gasnier
2020-11-02 12:46 ` Greg Kroah-Hartman
2020-11-02 14:42 ` Mauro Carvalho Chehab
2020-11-08 16:56 ` Jonathan Cameron
2020-11-10 7:26 ` Duplicated ABI entries - Was: " Mauro Carvalho Chehab
2020-11-10 18:18 ` Randy Dunlap
2020-11-14 15:27 ` Jonathan Cameron
2020-10-30 17:26 ` Frederic Barrat
2020-10-30 7:40 ` [PATCH v2 21/39] docs: ABI: sysfs-uevent: make it " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 22/39] docs: ABI: make it parse ABI/stable as ReST-compatible files Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 23/39] docs: ABI: create a 2-depth index for ABI Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 24/39] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 25/39] docs: abi-testing.rst: enable --rst-sources when building docs Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 26/39] docs: Kconfig/Makefile: add a check for broken ABI files Mauro Carvalho Chehab
2020-10-30 16:49 ` Randy Dunlap
2020-10-30 7:40 ` [PATCH v2 27/39] docs: ABI: convert testing/configfs-acpi to ReST Mauro Carvalho Chehab
2020-10-30 14:33 ` Rafael J. Wysocki
2020-10-30 7:40 ` [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation Mauro Carvalho Chehab
2020-10-30 14:39 ` Rafael J. Wysocki
2020-11-02 5:50 ` Jinpu Wang
2020-11-02 18:39 ` Joseph, Jithu
2020-10-30 7:40 ` [PATCH v2 29/39] docs: ABI: vdso: use the right format for ABI Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 30/39] docs: ABI: sysfs-bus-nvdimm: " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 31/39] docs: ABI: cleanup several ABI documents Mauro Carvalho Chehab
2020-10-30 8:27 ` Rojewski, Cezary
2020-10-30 9:49 ` Suzuki K Poulose
2020-10-30 11:11 ` Ilya Dryomov
2020-10-30 16:42 ` Mathieu Poirier
2020-10-30 23:23 ` Peter Chen
2020-11-01 3:43 ` Dmitry Torokhov
2020-10-30 7:40 ` [PATCH v2 32/39] docs: ABI: change read/write attributes Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 33/39] docs: ABI: stable: remove a duplicated documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 34/39] docs: ABI: unify /sys/class/leds/<led>/brightness documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 35/39] docs: ABI: sysfs-class-power: unify duplicated properties Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 36/39] docs: ABI: sysfs-c2port: remove a duplicated entry Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 37/39] docs: ABI: sysfs-class-backlight: unify ABI documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 38/39] docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 39/39] scripts: get_abi.pl: assume ReST format by default Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=dwlsalmeida@gmail.com \
--cc=j.neuschaefer@gmx.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mhiramat@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).