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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Mauro Carvalho Chehab 2020-10-30 08:40:36 +01:00 committed by Greg Kroah-Hartman
parent 3c543d2989
commit a7ee04b3ef
7 changed files with 61 additions and 1 deletions

View File

@ -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

View File

@ -0,0 +1,4 @@
ABI removed symbols
===================
.. kernel-abi:: $srctree/Documentation/ABI/removed

View File

@ -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

View File

@ -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

View File

@ -0,0 +1,11 @@
=====================
Linux ABI description
=====================
.. toctree::
:maxdepth: 1
abi-stable
abi-testing
abi-obsolete
abi-removed

View File

@ -18,6 +18,8 @@ etc.
devices
sysctl/index
abi
This section describes CPU vulnerabilities and their mitigations.
.. toctree::

View File

@ -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*