diff options
| author | Mauro Carvalho Chehab <mchehab+huawei@kernel.org> | 2020-10-30 10:40:36 +0300 |
|---|---|---|
| committer | Greg Kroah-Hartman <gregkh@linuxfoundation.org> | 2020-10-30 15:07:01 +0300 |
| commit | a7ee04b3ef0d2b2514730928a04a112f04ffe7df (patch) | |
| tree | a35f0f7f8fa1027d6bb847a75c5c2311b38178f7 | |
| parent | 3c543d29891a42b23c1f9a3a4788ae37fb94cce2 (diff) | |
| download | linux-a7ee04b3ef0d2b2514730928a04a112f04ffe7df.tar.xz | |
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>
| -rw-r--r-- | Documentation/admin-guide/abi-obsolete.rst | 10 | ||||
| -rw-r--r-- | Documentation/admin-guide/abi-removed.rst | 4 | ||||
| -rw-r--r-- | Documentation/admin-guide/abi-stable.rst | 13 | ||||
| -rw-r--r-- | Documentation/admin-guide/abi-testing.rst | 19 | ||||
| -rw-r--r-- | Documentation/admin-guide/abi.rst | 11 | ||||
| -rw-r--r-- | Documentation/admin-guide/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/conf.py | 3 |
7 files changed, 61 insertions, 1 deletions
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 376dd0ddf39c..1e44983853a2 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* |