* [PATCH 10/12] docs: kernel_abi.py: use --enable-lineno for get_abi.pl
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
Just like kernel-doc extension, we need to be able to identify
what part of an imported document has issues, as reporting them
as:
get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
Makes a lot harder for someone to fix.
It should be noticed that it the line which will be reported is
the line where the "What:" definition is, and not the line
with actually has an error.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 18 ++++++++++++++----
1 file changed, 14 insertions(+), 4 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 5d43cac73d0a..efa338e18764 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -35,6 +35,7 @@ import codecs
import os
import subprocess
import sys
+import re
from os import path
@@ -92,7 +93,7 @@ class KernelCmd(Directive):
env = doc.settings.env
cwd = path.dirname(doc.current_source)
- cmd = "get_abi.pl rest --dir "
+ cmd = "get_abi.pl rest --enable-lineno --dir "
cmd += self.arguments[0]
srctree = path.abspath(os.environ["srctree"])
@@ -136,7 +137,7 @@ class KernelCmd(Directive):
% (self.name, ErrorString(exc)))
return out
- def nestedParse(self, lines, fname):
+ def nestedParse(self, lines, f):
content = ViewList()
node = nodes.section()
@@ -146,8 +147,17 @@ class KernelCmd(Directive):
code_block += "\n " + l
lines = code_block + "\n\n"
- for c, l in enumerate(lines.split("\n")):
- content.append(l, fname, c)
+ line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
+ ln = 0
+
+ for line in lines.split("\n"):
+ match = line_regex.search(line)
+ if match:
+ f = match.group(1)
+ # sphinx counts lines from 0
+ ln = int(match.group(2)) - 1
+ else:
+ content.append(line, f, ln)
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
--
2.21.0
^ permalink raw reply related
* [PATCH 11/12] docs: kernel_abi.py: Handle with a lazy Sphinx parser
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
The Sphinx docutils parser is lazy: if the content is bigger than
a certain number of lines, it silenlty stops parsing it,
producing an incomplete content. This seems to be worse on newer
Sphinx versions, like 2.0.
So, change the logic to parse the contents per input file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 39 ++++++++++++++++++++----------
1 file changed, 26 insertions(+), 13 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index efa338e18764..a417026ed690 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -36,6 +36,7 @@ import os
import subprocess
import sys
import re
+import kernellog
from os import path
@@ -79,12 +80,6 @@ class KernelCmd(Directive):
"debug" : directives.flag
}
- def warn(self, message, **replace):
- replace["fname"] = self.state.document.current_source
- replace["line_no"] = replace.get("line_no", self.lineno)
- message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
- self.state.document.settings.env.app.warn(message, prefix="")
-
def run(self):
doc = self.state.document
@@ -110,7 +105,7 @@ class KernelCmd(Directive):
shell_env["srctree"] = srctree
lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
- nodeList = self.nestedParse(lines, fname)
+ nodeList = self.nestedParse(lines, self.arguments[0])
return nodeList
def runCmd(self, cmd, **kwargs):
@@ -137,9 +132,9 @@ class KernelCmd(Directive):
% (self.name, ErrorString(exc)))
return out
- def nestedParse(self, lines, f):
+ def nestedParse(self, lines, fname):
content = ViewList()
- node = nodes.section()
+ node = nodes.section()
if "debug" in self.options:
code_block = "\n\n.. code-block:: rst\n :linenos:\n"
@@ -149,22 +144,42 @@ class KernelCmd(Directive):
line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
ln = 0
+ n = 0
+ f = fname
for line in lines.split("\n"):
+ n = n + 1
match = line_regex.search(line)
if match:
- f = match.group(1)
+ new_f = match.group(1)
+
+ # Sphinx parser is lazy: it stops parsing contents in the
+ # middle, if it is too big. So, handle it per input file
+ if new_f != f and content:
+ self.do_parse(content, node)
+ content = ViewList()
+
+ f = new_f
+
# sphinx counts lines from 0
ln = int(match.group(2)) - 1
else:
content.append(line, f, ln)
- buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n))
+ if content:
+ self.do_parse(content, node)
+
+ return node.children
+
+ def do_parse(self, content, node):
if Use_SSI:
with switch_source_input(self.state, content):
self.state.nested_parse(content, 0, node, match_titles=1)
else:
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+
self.state.memo.title_styles = []
self.state.memo.section_level = 0
self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
@@ -172,5 +187,3 @@ class KernelCmd(Directive):
self.state.nested_parse(content, 0, node, match_titles=1)
finally:
self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
-
- return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 09/12] docs: kernel_abi.py: add a SPDX header file
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
This file is released under GPL v2.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index ef91b1e1ff4b..5d43cac73d0a 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -1,4 +1,5 @@
# coding=utf-8
+# SPDX-License-Identifier: GPL-2.0
#
u"""
kernel-abi
--
2.21.0
^ permalink raw reply related
* [PATCH 12/12] docs: add ABI documentation to the admin-guide book
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@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+samsung@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 | 1 +
Documentation/conf.py | 2 +-
7 files changed, 59 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 8001917ee012..20c3020fd73c 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -16,6 +16,7 @@ etc.
README
kernel-parameters
devices
+ abi
This section describes CPU vulnerabilities and their mitigations.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7ace3f8852bd..598256fb5c98 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi']
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
--
2.21.0
^ permalink raw reply related
* [PATCH 03/12] scripts/get_abi.pl: Allow optionally record from where a line came from
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
The get_abi.pl reads a lot of files and can join them on a
single output file. Store where each "What:" output came from,
in order to be able to optionally display it.
This is useful for the Sphinx extension, with can now be
able to blame what ABI file has issues, and on what line
the What: description with problems begin.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 0c403af86fd5..6a4d387ebf3b 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -10,6 +10,7 @@ use Fcntl ':mode';
my $help;
my $man;
my $debug;
+my $enable_lineno;
my $prefix="Documentation/ABI";
#
@@ -19,6 +20,7 @@ my $description_is_rst = 0;
GetOptions(
"debug|d+" => \$debug,
+ "enable-lineno" => \$enable_lineno,
"rst-source!" => \$description_is_rst,
"dir=s" => \$prefix,
'help|?' => \$help,
@@ -67,6 +69,7 @@ sub parse_abi {
$data{$nametag}->{file} = $name;
$data{$nametag}->{filepath} = $file;
$data{$nametag}->{is_file} = 1;
+ $data{$nametag}->{line_no} = 1;
my $type = $file;
$type =~ s,.*/(.*)/.*,$1,;
@@ -126,6 +129,8 @@ sub parse_abi {
if ($tag ne "" && $new_tag) {
$tag = $new_tag;
+ $data{$what}->{line_no} = $ln;
+
if ($new_what) {
@{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
@labels = ();
@@ -221,6 +226,12 @@ sub output_rest {
my $file = $data{$what}->{file};
my $filepath = $data{$what}->{filepath};
+ if ($enable_lineno) {
+ printf "#define LINENO %s%s#%s\n\n",
+ $prefix, $data{$what}->{file},
+ $data{$what}->{line_no};
+ }
+
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
@@ -369,6 +380,10 @@ sub search_symbols {
}
}
+# Ensure that the prefix will always end with a slash
+# While this is not needed for find, it makes the patch nicer
+# with --enable-lineno
+$prefix =~ s,/?$,/,;
#
# Parses all ABI files located at $prefix dir
@@ -395,7 +410,8 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
=head1 SYNOPSIS
-B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--enable-lineno] [--man] [--help]
+ [--(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
@@ -425,6 +441,10 @@ selecting between a rst-compliant source ABI (--rst-source), or a
plain text that may be violating ReST spec, so it requres some escaping
logic (--no-rst-source).
+=item B<--enable-lineno>
+
+Enable output of #define LINENO lines.
+
=item B<--debug>
Put the script in verbose mode, useful for debugging. Can be called multiple
--
2.21.0
^ permalink raw reply related
* [PATCH 06/12] docs: kernel_abi.py: fix UTF-8 support
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
The parser breaks with UTF-8 characters with Sphinx 1.4.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 20 +++++++-------------
1 file changed, 7 insertions(+), 13 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 32ce90775d96..0f3e51e67e8d 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -1,4 +1,5 @@
-# -*- coding: utf-8; mode: python -*-
+# coding=utf-8
+#
u"""
kernel-abi
~~~~~~~~~~
@@ -28,6 +29,7 @@ u"""
"""
+import codecs
import sys
import os
from os import path
@@ -43,14 +45,6 @@ from docutils.utils.error_reporting import ErrorString
__version__ = '1.0'
-# We can't assume that six is installed
-PY3 = sys.version_info[0] == 3
-PY2 = sys.version_info[0] == 2
-if PY3:
- # pylint: disable=C0103, W0622
- unicode = str
- basestring = str
-
def setup(app):
app.add_directive("kernel-abi", KernelCmd)
@@ -115,12 +109,12 @@ class KernelCmd(Directive):
cmd
, stdout = subprocess.PIPE
, stderr = subprocess.PIPE
- , universal_newlines = True
, **kwargs
)
out, err = proc.communicate()
- if err:
- self.warn(err)
+
+ out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
if proc.returncode != 0:
raise self.severe(
u"command '%s' failed with return code %d"
@@ -129,7 +123,7 @@ class KernelCmd(Directive):
except OSError as exc:
raise self.severe(u"problems with '%s' directive: %s."
% (self.name, ErrorString(exc)))
- return unicode(out)
+ return out
def nestedParse(self, lines, fname):
content = ViewList()
--
2.21.0
^ permalink raw reply related
* [PATCH 00/12] Add the ABI documentation to the admin guide
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
Hi Greg/Jon,
That's the rebased patches with add the ABI documentation to the
admin-guide. It is rebased on the top of driver-core/driver-core-next,
and it can work both on the "old" mode, where the scripts will
avoid codes that would cause troubles for ReST, or at the new mode,
with parses the description to the ReST output untouched.
Patches 1 to 3 improves the get_abi.pl for it to parse ReST format,
and to report where the errors/warnings occur at the ABI file.
Patch 4 is implements support for a Sphinx log facility (info).
Patches 5 to 10 adds the new kernel ABI extension, making it ready
to parse files in ether "normal" or "rst-source" mode.
Patch 11 addresses a Sphinx issue, with is there since old vesions,
but it gets worse on Sphins 2.0: basically, the ReST parser is lazy:
if it receives too much stuff, it silently ignores the end of the content.
So, the extension needs to split the content on small chunks.
IMO, it is safe to apply patches 1 to 11 via Greg's tree. The only
potential conflict would be at patch 4, but looking at docs-next,
I don't see any changes at Documentation/scripts/kernelog.py.
Patch 12 actually enables everything.
If Patch 12 gets merged via Greg's tree, it may rise a single-line
trivial conflict with docs-next, as it will be adding kernel_abi to the
list of extensions at Documentation/conf.py, and Jon is likely
adding another extension. too.
So, it could be wise postpone patch 12 to be merged after both
trees got merged upstream.
Patch 12 adds ABI with ReST-scaping code. I'll submit soon a
second version for the RFC patches with turns it to "clean" mode.
The entire ABI series (plus Documentation/features) is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.2
And the ReST output (with Sphinx 2.0 - with IMO provides a nicer
output) is at:
https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
Mauro Carvalho Chehab (12):
scripts/get_abi.pl: change script to allow parsing in ReST mode
scripts/get_abi.pl: fix parsing on ReST mode
scripts/get_abi.pl: Allow optionally record from where a line came
from
docs: kernellog.py: add support for info()
docs: kernel_abi.py: add a script to parse ABI documentation
docs: kernel_abi.py: fix UTF-8 support
docs: kernel_abi.py: make it compatible with Sphinx 1.7+
docs: kernel_abi.py: Update copyrights
docs: kernel_abi.py: add a SPDX header file
docs: kernel_abi.py: use --enable-lineno for get_abi.pl
docs: kernel_abi.py: Handle with a lazy Sphinx parser
docs: add ABI documentation to the admin-guide book
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 | 1 +
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_abi.py | 189 +++++++++++++++++++++
Documentation/sphinx/kernellog.py | 6 +-
scripts/get_abi.pl | 104 ++++++++----
10 files changed, 325 insertions(+), 34 deletions(-)
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
create mode 100644 Documentation/sphinx/kernel_abi.py
--
2.21.0
^ permalink raw reply
* [PATCH 04/12] docs: kernellog.py: add support for info()
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
An extension may want to just inform about something. So, add
support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernellog.py | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/kernellog.py b/Documentation/sphinx/kernellog.py
index af924f51a7dc..8ac7d274f542 100644
--- a/Documentation/sphinx/kernellog.py
+++ b/Documentation/sphinx/kernellog.py
@@ -25,4 +25,8 @@ def verbose(app, message):
else:
app.verbose(message)
-
+def info(app, message):
+ if UseLogging:
+ logger.info(message)
+ else:
+ app.info(message)
--
2.21.0
^ permalink raw reply related
* [PATCH 02/12] scripts/get_abi.pl: fix parsing on ReST mode
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
When the source ABI file is using ReST notation, the script
should handle whitespaces and lines with care, as otherwise
the file won't be properly recognized.
Address the bugs that are on such part of the script.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 107672cdacb3..0c403af86fd5 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -151,7 +151,8 @@ sub parse_abi {
$content = $2;
}
while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= $content;
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
$data{$what}->{$tag} = $content;
}
@@ -166,31 +167,28 @@ sub parse_abi {
}
if ($tag eq "description") {
+ my $content = $_;
+ while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
if (!$data{$what}->{description}) {
- s/^($space)//;
- if (m/^(\s*)(.*)/) {
- my $sp = $1;
- while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- my $content = "$sp$2";
-
- $content =~ s/^($space)//;
-
- $data{$what}->{$tag} .= "$content";
+ # Preserve initial spaces for the first line
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
- my $content = $_;
if (m/^\s*\n/) {
$data{$what}->{$tag} .= $content;
next;
}
- while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
$space = "" if (!($content =~ s/^($space)//));
- # Compress spaces with tabs
- $content =~ s<^ {8}> <\t>;
- $content =~ s<^ {1,7}\t> <\t>;
- $content =~ s< {1,7}\t> <\t>;
+# # Compress spaces with tabs
+# $content =~ s<^ {8}> <\t>;
+# $content =~ s<^ {1,7}\t> <\t>;
+# $content =~ s< {1,7}\t> <\t>;
$data{$what}->{$tag} .= $content;
}
next;
--
2.21.0
^ permalink raw reply related
* [PATCH 05/12] docs: kernel_abi.py: add a script to parse ABI documentation
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
The ABI documentation is special: it is not plain text files,
but, instead, files with an strict format, as specified by
Documentation/ABI/README.
Add a parser for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 155 +++++++++++++++++++++++++++++
1 file changed, 155 insertions(+)
create mode 100644 Documentation/sphinx/kernel_abi.py
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
new file mode 100644
index 000000000000..32ce90775d96
--- /dev/null
+++ b/Documentation/sphinx/kernel_abi.py
@@ -0,0 +1,155 @@
+# -*- coding: utf-8; mode: python -*-
+u"""
+ kernel-abi
+ ~~~~~~~~~~
+
+ Implementation of the ``kernel-abi`` reST-directive.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :copyright: Copyright (C) 2016 Mauro Carvalho Chehab
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
+ scripts/get_abi.pl script to parse the Kernel ABI files.
+
+ Overview of directive's argument and options.
+
+ .. code-block:: rst
+
+ .. kernel-abi:: <ABI directory location>
+ :debug:
+
+ The argument ``<ABI directory location>`` is required. It contains the
+ location of the ABI files to be parsed.
+
+ ``debug``
+ Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+ what reST is generated.
+
+"""
+
+import sys
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__ = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+ # pylint: disable=C0103, W0622
+ unicode = str
+ basestring = str
+
+def setup(app):
+
+ app.add_directive("kernel-abi", KernelCmd)
+ return dict(
+ version = __version__
+ , parallel_read_safe = True
+ , parallel_write_safe = True
+ )
+
+class KernelCmd(Directive):
+
+ u"""KernelABI (``kernel-abi``) directive"""
+
+ required_arguments = 1
+ optional_arguments = 0
+ has_content = False
+ final_argument_whitespace = True
+
+ option_spec = {
+ "debug" : directives.flag
+ }
+
+ def warn(self, message, **replace):
+ replace["fname"] = self.state.document.current_source
+ replace["line_no"] = replace.get("line_no", self.lineno)
+ message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
+ self.state.document.settings.env.app.warn(message, prefix="")
+
+ def run(self):
+
+ doc = self.state.document
+ if not doc.settings.file_insertion_enabled:
+ raise self.warning("docutils: file insertion disabled")
+
+ env = doc.settings.env
+ cwd = path.dirname(doc.current_source)
+ cmd = "get_abi.pl rest --dir "
+ cmd += self.arguments[0]
+
+ srctree = path.abspath(os.environ["srctree"])
+
+ fname = cmd
+
+ # extend PATH with $(srctree)/scripts
+ path_env = os.pathsep.join([
+ srctree + os.sep + "scripts",
+ os.environ["PATH"]
+ ])
+ shell_env = os.environ.copy()
+ shell_env["PATH"] = path_env
+ shell_env["srctree"] = srctree
+
+ lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+ nodeList = self.nestedParse(lines, fname)
+ return nodeList
+
+ def runCmd(self, cmd, **kwargs):
+ u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+ try:
+ proc = subprocess.Popen(
+ cmd
+ , stdout = subprocess.PIPE
+ , stderr = subprocess.PIPE
+ , universal_newlines = True
+ , **kwargs
+ )
+ out, err = proc.communicate()
+ if err:
+ self.warn(err)
+ if proc.returncode != 0:
+ raise self.severe(
+ u"command '%s' failed with return code %d"
+ % (cmd, proc.returncode)
+ )
+ except OSError as exc:
+ raise self.severe(u"problems with '%s' directive: %s."
+ % (self.name, ErrorString(exc)))
+ return unicode(out)
+
+ def nestedParse(self, lines, fname):
+ content = ViewList()
+ node = nodes.section()
+
+ if "debug" in self.options:
+ code_block = "\n\n.. code-block:: rst\n :linenos:\n"
+ for l in lines.split("\n"):
+ code_block += "\n " + l
+ lines = code_block + "\n\n"
+
+ for c, l in enumerate(lines.split("\n")):
+ content.append(l, fname, c)
+
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+ return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 07/12] docs: kernel_abi.py: make it compatible with Sphinx 1.7+
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
The same way kerneldoc.py needed changes to work with newer
Sphinx, this script needs the same changes.
While here, reorganize the include order to match kerneldoc.py.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 39 +++++++++++++++++++++---------
1 file changed, 27 insertions(+), 12 deletions(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 0f3e51e67e8d..2d5d582207f7 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -30,18 +30,27 @@ u"""
"""
import codecs
-import sys
import os
-from os import path
import subprocess
+import sys
-from sphinx.ext.autodoc import AutodocReporter
+from os import path
-from docutils import nodes
-from docutils.parsers.rst import Directive, directives
+from docutils import nodes, statemachine
from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives, Directive
from docutils.utils.error_reporting import ErrorString
+#
+# AutodocReporter is only good up to Sphinx 1.7
+#
+import sphinx
+
+Use_SSI = sphinx.__version__[:3] >= '1.7'
+if Use_SSI:
+ from sphinx.util.docutils import switch_source_input
+else:
+ from sphinx.ext.autodoc import AutodocReporter
__version__ = '1.0'
@@ -139,11 +148,17 @@ class KernelCmd(Directive):
content.append(l, fname, c)
buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
- self.state.memo.title_styles = []
- self.state.memo.section_level = 0
- self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
- try:
- self.state.nested_parse(content, 0, node, match_titles=1)
- finally:
- self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+ if Use_SSI:
+ with switch_source_input(self.state, content):
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ else:
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 08/12] docs: kernel_abi.py: Update copyrights
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
As Markus doesn't want to maintain ths file, update it to
put me as its maintainer.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_abi.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 2d5d582207f7..ef91b1e1ff4b 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -7,7 +7,8 @@ u"""
Implementation of the ``kernel-abi`` reST-directive.
:copyright: Copyright (C) 2016 Markus Heiser
- :copyright: Copyright (C) 2016 Mauro Carvalho Chehab
+ :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab
+ :maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
:license: GPL Version 2, June 1991 see Linux/COPYING for details.
The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
--
2.21.0
^ permalink raw reply related
* [PATCH 01/12] scripts/get_abi.pl: change script to allow parsing in ReST mode
From: Mauro Carvalho Chehab @ 2019-06-22 16:58 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561221403.git.mchehab+samsung@kernel.org>
Right now, several ABI files won't parse as ReST, as they
contain severe violations to the spec, with makes the script
to crash.
So, the code has a sanity logic with escapes bad code and
cleans tags that can cause Sphinx to crash.
Add support for disabling this mode.
Right now, as enabling rst-mode causes crash, it is disabled
by default.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 74 ++++++++++++++++++++++++++++++----------------
1 file changed, 48 insertions(+), 26 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c738cb795514..107672cdacb3 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -12,8 +12,14 @@ my $man;
my $debug;
my $prefix="Documentation/ABI";
+#
+# If true, assumes that the description is formatted with ReST
+#
+my $description_is_rst = 0;
+
GetOptions(
"debug|d+" => \$debug,
+ "rst-source!" => \$description_is_rst,
"dir=s" => \$prefix,
'help|?' => \$help,
man => \$man
@@ -137,14 +143,15 @@ sub parse_abi {
next;
}
if ($tag eq "description") {
- next if ($content =~ m/^\s*$/);
- if ($content =~ m/^(\s*)(.*)/) {
- my $new_content = $2;
- $space = $new_tag . $sep . $1;
- while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $space =~ s/./ /g;
- $data{$what}->{$tag} .= "$new_content\n";
+ # Preserve initial spaces for the first line
+ $content = ' ' x length($new_tag) . $sep . $content;
+ $content =~ s,^(\s*):,$1 ,;
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+ while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ $data{$what}->{$tag} .= $content;
} else {
$data{$what}->{$tag} = $content;
}
@@ -160,11 +167,15 @@ sub parse_abi {
if ($tag eq "description") {
if (!$data{$what}->{description}) {
- next if (m/^\s*\n/);
+ s/^($space)//;
if (m/^(\s*)(.*)/) {
- $space = $1;
- while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= "$2\n";
+ my $sp = $1;
+ while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+ my $content = "$sp$2";
+
+ $content =~ s/^($space)//;
+
+ $data{$what}->{$tag} .= "$content";
}
} else {
my $content = $_;
@@ -274,23 +285,27 @@ sub output_rest {
print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
my $desc = $data{$what}->{description};
- $desc =~ s/^\s+//;
-
- # Remove title markups from the description, as they won't work
- $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
if (!($desc =~ /^\s*$/)) {
- if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
- # put everything inside a code block
- $desc =~ s/\n/\n /g;
-
- print "::\n\n";
- print " $desc\n\n";
- } else {
- # Escape any special chars from description
- $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
-
+ if ($description_is_rst) {
print "$desc\n\n";
+ } else {
+ $desc =~ s/^\s+//;
+
+ # Remove title markups from the description, as they won't work
+ $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
+
+ if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
+ # put everything inside a code block
+ $desc =~ s/\n/\n /g;
+
+ print "::\n\n";
+ print " $desc\n\n";
+ } else {
+ # Escape any special chars from description
+ $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
+ print "$desc\n\n";
+ }
}
} else {
print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
@@ -382,7 +397,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
=head1 SYNOPSIS
-B<abi_book.pl> [--debug] [--man] [--help] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
@@ -405,6 +420,13 @@ B<validate> - validate the ABI contents
Changes the location of the ABI search. By default, it uses
the Documentation/ABI directory.
+=item B<--rst-source> and B<--no-rst-source>
+
+The input file may be using ReST syntax or not. Those two options allow
+selecting between a rst-compliant source ABI (--rst-source), or a
+plain text that may be violating ReST spec, so it requres some escaping
+logic (--no-rst-source).
+
=item B<--debug>
Put the script in verbose mode, useful for debugging. Can be called multiple
--
2.21.0
^ permalink raw reply related
* [PATCH 2/4] scripts/get_feat.pl: handle ".." special case
From: Mauro Carvalho Chehab @ 2019-06-22 17:17 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561222784.git.mchehab+samsung@kernel.org>
The status ".." Means that the feature can't be implemented
on a given architecture.
The problem is that this doesn't show anything at the
output, so replace it by "---", with is a markup for a long
hyphen.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_feat.pl | 2 ++
1 file changed, 2 insertions(+)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 401cbc820caa..79d83595addd 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -141,6 +141,8 @@ sub parse_feat {
$max_size_arch = length($a);
}
+ $status = "---" if ($status =~ m/^\.\.$/);
+
$archs{$a} = 1;
$arch_table{$a} = $status;
next;
--
2.21.0
^ permalink raw reply related
* [PATCH 4/4] docs: admin-guide, x86: add a features list
From: Mauro Carvalho Chehab @ 2019-06-22 17:17 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H. Peter Anvin,
x86
In-Reply-To: <cover.1561222784.git.mchehab+samsung@kernel.org>
Add a feature list matrix at the admin-guide and a x86-specific
feature list to the respective Kernel books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/features.rst | 3 +++
Documentation/admin-guide/index.rst | 1 +
Documentation/conf.py | 2 +-
Documentation/x86/features.rst | 3 +++
Documentation/x86/index.rst | 1 +
5 files changed, 9 insertions(+), 1 deletion(-)
create mode 100644 Documentation/admin-guide/features.rst
create mode 100644 Documentation/x86/features.rst
diff --git a/Documentation/admin-guide/features.rst b/Documentation/admin-guide/features.rst
new file mode 100644
index 000000000000..8c167082a84f
--- /dev/null
+++ b/Documentation/admin-guide/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 20c3020fd73c..14c8464f6ca9 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -17,6 +17,7 @@ etc.
kernel-parameters
devices
abi
+ features
This section describes CPU vulnerabilities and their mitigations.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 598256fb5c98..a0ef76ce5615 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi', 'kernel_feat']
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
diff --git a/Documentation/x86/features.rst b/Documentation/x86/features.rst
new file mode 100644
index 000000000000..b663f15053ce
--- /dev/null
+++ b/Documentation/x86/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features x86
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index ae36fc5fc649..ed42c8c9154d 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -29,3 +29,4 @@ x86-specific Documentation
usb-legacy-support
i386/index
x86_64/index
+ features
--
2.21.0
^ permalink raw reply related
* [PATCH 3/4] sphinx/kernel_feat.py: add a script to parse feature files
From: Mauro Carvalho Chehab @ 2019-06-22 17:17 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561222784.git.mchehab+samsung@kernel.org>
The feature files have a special well-defined format. Add
a script that parses them, allowing to search for a feature
and/or by an architecture and to produce ReST-compatible
outputs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/sphinx/kernel_feat.py | 169 ++++++++++++++++++++++++++++
1 file changed, 169 insertions(+)
create mode 100644 Documentation/sphinx/kernel_feat.py
diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py
new file mode 100644
index 000000000000..2fee04f1dedd
--- /dev/null
+++ b/Documentation/sphinx/kernel_feat.py
@@ -0,0 +1,169 @@
+# coding=utf-8
+# SPDX-License-Identifier: GPL-2.0
+#
+u"""
+ kernel-feat
+ ~~~~~~~~~~~
+
+ Implementation of the ``kernel-feat`` reST-directive.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab
+ :maintained-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
+ scripts/get_feat.pl script to parse the Kernel ABI files.
+
+ Overview of directive's argument and options.
+
+ .. code-block:: rst
+
+ .. kernel-feat:: <ABI directory location>
+ :debug:
+
+ The argument ``<ABI directory location>`` is required. It contains the
+ location of the ABI files to be parsed.
+
+ ``debug``
+ Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+ what reST is generated.
+
+"""
+
+import codecs
+import os
+import subprocess
+import sys
+
+from os import path
+
+from docutils import nodes, statemachine
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives, Directive
+from docutils.utils.error_reporting import ErrorString
+
+#
+# AutodocReporter is only good up to Sphinx 1.7
+#
+import sphinx
+
+Use_SSI = sphinx.__version__[:3] >= '1.7'
+if Use_SSI:
+ from sphinx.util.docutils import switch_source_input
+else:
+ from sphinx.ext.autodoc import AutodocReporter
+
+__version__ = '1.0'
+
+def setup(app):
+
+ app.add_directive("kernel-feat", KernelFeat)
+ return dict(
+ version = __version__
+ , parallel_read_safe = True
+ , parallel_write_safe = True
+ )
+
+class KernelFeat(Directive):
+
+ u"""KernelFeat (``kernel-feat``) directive"""
+
+ required_arguments = 1
+ optional_arguments = 2
+ has_content = False
+ final_argument_whitespace = True
+
+ option_spec = {
+ "debug" : directives.flag
+ }
+
+ def warn(self, message, **replace):
+ replace["fname"] = self.state.document.current_source
+ replace["line_no"] = replace.get("line_no", self.lineno)
+ message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace
+ self.state.document.settings.env.app.warn(message, prefix="")
+
+ def run(self):
+
+ doc = self.state.document
+ if not doc.settings.file_insertion_enabled:
+ raise self.warning("docutils: file insertion disabled")
+
+ env = doc.settings.env
+ cwd = path.dirname(doc.current_source)
+ cmd = "get_feat.pl rest --dir "
+ cmd += self.arguments[0]
+
+ if len(self.arguments) > 1:
+ cmd += " --arch " + self.arguments[1]
+
+ srctree = path.abspath(os.environ["srctree"])
+
+ fname = cmd
+
+ # extend PATH with $(srctree)/scripts
+ path_env = os.pathsep.join([
+ srctree + os.sep + "scripts",
+ os.environ["PATH"]
+ ])
+ shell_env = os.environ.copy()
+ shell_env["PATH"] = path_env
+ shell_env["srctree"] = srctree
+
+ lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+ nodeList = self.nestedParse(lines, fname)
+ return nodeList
+
+ def runCmd(self, cmd, **kwargs):
+ u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+ try:
+ proc = subprocess.Popen(
+ cmd
+ , stdout = subprocess.PIPE
+ , stderr = subprocess.PIPE
+ , **kwargs
+ )
+ out, err = proc.communicate()
+
+ out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
+ if proc.returncode != 0:
+ raise self.severe(
+ u"command '%s' failed with return code %d"
+ % (cmd, proc.returncode)
+ )
+ except OSError as exc:
+ raise self.severe(u"problems with '%s' directive: %s."
+ % (self.name, ErrorString(exc)))
+ return out
+
+ def nestedParse(self, lines, fname):
+ content = ViewList()
+ node = nodes.section()
+
+ if "debug" in self.options:
+ code_block = "\n\n.. code-block:: rst\n :linenos:\n"
+ for l in lines.split("\n"):
+ code_block += "\n " + l
+ lines = code_block + "\n\n"
+
+ for c, l in enumerate(lines.split("\n")):
+ content.append(l, fname, c)
+
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+
+ if Use_SSI:
+ with switch_source_input(self.state, content):
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ else:
+ self.state.memo.title_styles = []
+ self.state.memo.section_level = 0
+ self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter)
+ try:
+ self.state.nested_parse(content, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+ return node.children
--
2.21.0
^ permalink raw reply related
* [PATCH 0/4] Add Documentation/features to admin-guide and x86
From: Mauro Carvalho Chehab @ 2019-06-22 17:17 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Borislav Petkov, H. Peter Anvin, Ingo Molnar, Thomas Gleixner,
x86
Jon, Greg & all:
Not sure what tree this would fit better.
The first 2 patches on this series reimplement the logic at:
Documentation/features/list-arch.sh
I opted to not remove the old script, as someone could depend on
its specific format. The new script does the same with:
./scripts/get_feat.pl current
The difference is that it outputs with using ascii table artwork.
The way it works is that it parse all feature files and produce 3 different
types of contents, depending on its arguments:
- a feature x arch matrix:
./scripts/get_feat.pl rest
- a per-architecture feature table:
./scripts/get_feat.pl current
or
./scripts/get_feat.pl rest --arch=arm64
- a per-feature table:
./scripts/get_feat.pl rest --feat=perf-regs
All outputs are compatible with the ReST format.
Patch 3 adds a new Sphinx plugin with handles its output.
Patch 4 adds the feature x arch matrix at the admin-guide.
Patch 4 also adds the features supported on x86 at the x86 arch guide.
IMHO, it makes sense to have a similar table on all other architectures, but
the best is to wait for the next Kernel version, in order to see what arch
conversion files got included.
So far, I didn't add the per-feature table anywhere.
Mauro Carvalho Chehab (4):
scripts/get_feat.pl: add a script to handle Documentation/features
scripts/get_feat.pl: handle ".." special case
sphinx/kernel_feat.py: add a script to parse feature files
docs: admin-guide, x86: add a features list
Documentation/admin-guide/features.rst | 3 +
Documentation/admin-guide/index.rst | 1 +
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_feat.py | 169 +++++++++
Documentation/x86/features.rst | 3 +
Documentation/x86/index.rst | 1 +
scripts/get_feat.pl | 474 +++++++++++++++++++++++++
7 files changed, 652 insertions(+), 1 deletion(-)
create mode 100644 Documentation/admin-guide/features.rst
create mode 100644 Documentation/sphinx/kernel_feat.py
create mode 100644 Documentation/x86/features.rst
create mode 100755 scripts/get_feat.pl
--
2.21.0
^ permalink raw reply
* [PATCH 1/4] scripts/get_feat.pl: add a script to handle Documentation/features
From: Mauro Carvalho Chehab @ 2019-06-22 17:17 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh, Jonathan Corbet
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel
In-Reply-To: <cover.1561222784.git.mchehab+samsung@kernel.org>
The Documentation/features contains a set of parseable files.
It is not worth converting them to ReST format, as they're
useful the way it is. It is, however, interesting to parse
them and produce output on different formats:
1) Output the contents of a feature in ReST format;
2) Output what features a given architecture supports;
3) Output a matrix with features x architectures.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_feat.pl | 472 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 472 insertions(+)
create mode 100755 scripts/get_feat.pl
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
new file mode 100755
index 000000000000..401cbc820caa
--- /dev/null
+++ b/scripts/get_feat.pl
@@ -0,0 +1,472 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0
+
+use strict;
+use Pod::Usage;
+use Getopt::Long;
+use File::Find;
+use Fcntl ':mode';
+
+my $help;
+my $man;
+my $debug;
+my $arch;
+my $feat;
+my $prefix="Documentation/features";
+
+GetOptions(
+ "debug|d+" => \$debug,
+ "dir=s" => \$prefix,
+ 'help|?' => \$help,
+ 'arch=s' => \$arch,
+ 'feat=s' => \$feat,
+ man => \$man
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
+
+my ($cmd, $arg) = @ARGV;
+
+pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate");
+
+require Data::Dumper if ($debug);
+
+my %data;
+my %archs;
+
+#
+# Displays an error message, printing file name and line
+#
+sub parse_error($$$$) {
+ my ($file, $ln, $msg, $data) = @_;
+
+ $data =~ s/\s+$/\n/;
+
+ print STDERR "Warning: file $file#$ln:\n\t$msg";
+
+ if ($data ne "") {
+ print STDERR ". Line\n\t\t$data";
+ } else {
+ print STDERR "\n";
+ }
+}
+
+#
+# Parse a features file, storing its contents at %data
+#
+
+my $h_name = "Feature";
+my $h_kconfig = "Kconfig";
+my $h_description = "Description";
+my $h_subsys = "Subsystem";
+my $h_status = "Status";
+my $h_arch = "Architecture";
+
+my $max_size_name = length($h_name);
+my $max_size_kconfig = length($h_kconfig);
+my $max_size_description = length($h_description);
+my $max_size_subsys = length($h_subsys);
+my $max_size_status = length($h_status);
+my $max_size_arch = length($h_arch);
+
+sub parse_feat {
+ my $file = $File::Find::name;
+
+ my $mode = (stat($file))[2];
+ return if ($mode & S_IFDIR);
+ return if ($file =~ m,($prefix)/arch-support.txt,);
+ return if (!($file =~ m,arch-support.txt$,));
+
+ my $subsys = "";
+ $subsys = $2 if ( m,.*($prefix)/([^/]+).*,);
+
+ if (length($subsys) > $max_size_subsys) {
+ $max_size_subsys = length($subsys);
+ }
+
+ my $name;
+ my $kconfig;
+ my $description;
+ my $comments = "";
+ my $last_status;
+ my $ln;
+ my %arch_table;
+
+ print STDERR "Opening $file\n" if ($debug > 1);
+ open IN, $file;
+
+ while(<IN>) {
+ $ln++;
+
+ if (m/^\#\s+Feature\s+name:\s*(.*\S)/) {
+ $name = $1;
+ if (length($name) > $max_size_name) {
+ $max_size_name = length($name);
+ }
+ next;
+ }
+ if (m/^\#\s+Kconfig:\s*(.*\S)/) {
+ $kconfig = $1;
+ if (length($kconfig) > $max_size_kconfig) {
+ $max_size_kconfig = length($kconfig);
+ }
+ next;
+ }
+ if (m/^\#\s+description:\s*(.*\S)/) {
+ $description = $1;
+ if (length($description) > $max_size_description) {
+ $max_size_description = length($description);
+ }
+ next;
+ }
+ next if (m/^\\s*$/);
+ next if (m/^\s*\-+\s*$/);
+ next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/);
+
+ if (m/^\#\s*(.*)/) {
+ $comments .= "$1\n";
+ next;
+ }
+ if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) {
+ my $a = $1;
+ my $status = $2;
+
+ if (length($status) > $max_size_status) {
+ $max_size_status = length($status);
+ }
+ if (length($a) > $max_size_arch) {
+ $max_size_arch = length($a);
+ }
+
+ $archs{$a} = 1;
+ $arch_table{$a} = $status;
+ next;
+ }
+
+ #Everything else is an error
+ parse_error($file, $ln, "line is invalid", $_);
+ }
+ close IN;
+
+ if (!$name) {
+ parse_error($file, $ln, "Feature name not found", "");
+ return;
+ }
+
+ parse_error($file, $ln, "Subsystem not found", "") if (!$subsys);
+ parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig);
+ parse_error($file, $ln, "Description not found", "") if (!$description);
+
+ if (!%arch_table) {
+ parse_error($file, $ln, "Architecture table not found", "");
+ return;
+ }
+
+ $data{$name}->{where} = $file;
+ $data{$name}->{subsys} = $subsys;
+ $data{$name}->{kconfig} = $kconfig;
+ $data{$name}->{description} = $description;
+ $data{$name}->{comments} = $comments;
+ $data{$name}->{table} = \%arch_table;
+}
+
+#
+# Output feature(s) for a given architecture
+#
+sub output_arch_table {
+ my $title = "Feature status on $arch architecture";
+
+ print "=" x length($title) . "\n";
+ print "$title\n";
+ print "=" x length($title) . "\n\n";
+
+ print "=" x $max_size_subsys;
+ print " ";
+ print "=" x $max_size_name;
+ print " ";
+ print "=" x $max_size_kconfig;
+ print " ";
+ print "=" x $max_size_status;
+ print " ";
+ print "=" x $max_size_description;
+ print "\n";
+ printf "%-${max_size_subsys}s ", $h_subsys;
+ printf "%-${max_size_name}s ", $h_name;
+ printf "%-${max_size_kconfig}s ", $h_kconfig;
+ printf "%-${max_size_status}s ", $h_status;
+ printf "%-${max_size_description}s\n", $h_description;
+ print "=" x $max_size_subsys;
+ print " ";
+ print "=" x $max_size_name;
+ print " ";
+ print "=" x $max_size_kconfig;
+ print " ";
+ print "=" x $max_size_status;
+ print " ";
+ print "=" x $max_size_description;
+ print "\n";
+
+ foreach my $name (sort {
+ ($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
+ ($data{$a}->{name} cmp $data{$b}->{name})
+ } keys %data) {
+ next if ($feat && $name ne $feat);
+
+ my %arch_table = %{$data{$name}->{table}};
+ printf "%-${max_size_subsys}s ", $data{$name}->{subsys};
+ printf "%-${max_size_name}s ", $name;
+ printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig};
+ printf "%-${max_size_status}s ", $arch_table{$arch};
+ printf "%-${max_size_description}s\n", $data{$name}->{description};
+ }
+
+ print "=" x $max_size_subsys;
+ print " ";
+ print "=" x $max_size_name;
+ print " ";
+ print "=" x $max_size_kconfig;
+ print " ";
+ print "=" x $max_size_status;
+ print " ";
+ print "=" x $max_size_description;
+ print "\n";
+}
+
+#
+# Output a feature on all architectures
+#
+sub output_feature {
+ my $title = "Feature $feat";
+
+ print "=" x length($title) . "\n";
+ print "$title\n";
+ print "=" x length($title) . "\n\n";
+
+ print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys});
+ print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig});
+
+ my $desc = $data{$feat}->{description};
+ $desc =~ s/^([a-z])/\U$1/;
+ $desc =~ s/\.?\s*//;
+ print "\n$desc.\n\n";
+
+ my $com = $data{$feat}->{comments};
+ $com =~ s/^\s+//;
+ $com =~ s/\s+$//;
+ if ($com) {
+ print "Comments\n";
+ print "--------\n\n";
+ print "$com\n\n";
+ }
+
+ print "=" x $max_size_arch;
+ print " ";
+ print "=" x $max_size_status;
+ print "\n";
+
+ printf "%-${max_size_arch}s ", $h_arch;
+ printf "%-${max_size_status}s", $h_status . "\n";
+
+ print "=" x $max_size_arch;
+ print " ";
+ print "=" x $max_size_status;
+ print "\n";
+
+ my %arch_table = %{$data{$feat}->{table}};
+ foreach my $arch (sort keys %arch_table) {
+ printf "%-${max_size_arch}s ", $arch;
+ printf "%-${max_size_status}s\n", $arch_table{$arch};
+ }
+
+ print "=" x $max_size_arch;
+ print " ";
+ print "=" x $max_size_status;
+ print "\n";
+}
+
+#
+# Output all features for all architectures
+#
+
+sub matrix_lines {
+ print "=" x $max_size_subsys;
+ print " ";
+ print "=" x $max_size_name;
+ print " ";
+
+ foreach my $arch (sort keys %archs) {
+ my $len = $max_size_status;
+
+ $len = length($arch) if ($len < length($arch));
+
+ print "=" x $len;
+ print " ";
+ }
+ print "=" x $max_size_kconfig;
+ print " ";
+ print "=" x $max_size_description;
+ print "\n";
+}
+
+sub output_matrix {
+
+ my $title = "Feature List (feature x architecture)";
+
+ print "=" x length($title) . "\n";
+ print "$title\n";
+ print "=" x length($title) . "\n\n";
+
+ matrix_lines;
+
+ printf "%-${max_size_subsys}s ", $h_subsys;
+ printf "%-${max_size_name}s ", $h_name;
+
+ foreach my $arch (sort keys %archs) {
+ printf "%-${max_size_status}s ", $arch;
+ }
+ printf "%-${max_size_kconfig}s ", $h_kconfig;
+ printf "%-${max_size_description}s\n", $h_description;
+
+ matrix_lines;
+
+ foreach my $name (sort {
+ ($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
+ ($data{$a}->{name} cmp $data{$b}->{name})
+ } keys %data) {
+ printf "%-${max_size_subsys}s ", $data{$name}->{subsys};
+ printf "%-${max_size_name}s ", $name;
+
+ my %arch_table = %{$data{$name}->{table}};
+
+ foreach my $arch (sort keys %arch_table) {
+ my $len = $max_size_status;
+
+ $len = length($arch) if ($len < length($arch));
+
+ printf "%-${len}s ", $arch_table{$arch};
+ }
+ printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig};
+ printf "%-${max_size_description}s\n", $data{$name}->{description};
+ }
+
+ matrix_lines;
+}
+
+
+#
+# Parses all feature files located at $prefix dir
+#
+find({wanted =>\&parse_feat, no_chdir => 1}, $prefix);
+
+print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
+
+#
+# Handles the command
+#
+if ($cmd eq "current") {
+ $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
+ $arch =~s/\s+$//;
+}
+
+if ($cmd ne "validate") {
+ if ($arch) {
+ output_arch_table;
+ } elsif ($feat) {
+ output_feature;
+ } else {
+ output_matrix;
+ }
+}
+
+__END__
+
+=head1 NAME
+
+get_feat.pl - parse the Linux Feature files and produce a ReST book.
+
+=head1 SYNOPSIS
+
+B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>]
+ [--arch=<arch>] [--feat=<feature>] <COMAND> [<ARGUMENT>]
+
+Where <COMMAND> can be:
+
+=over 8
+
+B<current> - output features for this machine's architecture
+
+B<rest> - output features in ReST markup language
+
+B<validate> - validate the feature contents
+
+=back
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--arch>
+
+Output features for an specific architecture, optionally filtering for
+a single specific feature.
+
+=item B<--feat>
+
+Output features for a single specific architecture.
+
+=item B<--dir>
+
+Changes the location of the Feature files. By default, it uses
+the Documentation/features directory.
+
+=item B<--debug>
+
+Put the script in verbose mode, useful for debugging. Can be called multiple
+times, to increase verbosity.
+
+=item B<--help>
+
+Prints a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+Parse the Linux feature files from Documentation/features (by default),
+optionally producing results at ReST format.
+
+It supports output data per architecture, per feature or a
+feature x arch matrix.
+
+When used with B<rest> command, it will use either one of the tree formats:
+
+If neither B<--arch> or B<--feature> arguments are used, it will output a
+matrix with features per architecture.
+
+If B<--arch> argument is used, it will output the features availability for
+a given architecture.
+
+If B<--feat> argument is used, it will output the content of the feature
+file using ReStructured Text markup.
+
+=head1 BUGS
+
+Report bugs to Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+=cut
--
2.21.0
^ permalink raw reply related
* [RFC v2 5/8] docs: ABI: create a 2-depth index for ABI
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
That helps to identify what ABI files are adding titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
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
--
2.21.0
^ permalink raw reply related
* [RFC v2 8/8] docs: Kconfig/Makefile: add a check for broken ABI files
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.
Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.
With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/Kconfig | 11 +++++++++++
Documentation/Makefile | 5 +++++
lib/Kconfig.debug | 2 ++
scripts/get_abi.pl | 14 +++++++++++---
4 files changed, 29 insertions(+), 3 deletions(-)
create mode 100644 Documentation/Kconfig
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
new file mode 100644
index 000000000000..a8b0701c1422
--- /dev/null
+++ b/Documentation/Kconfig
@@ -0,0 +1,11 @@
+config WARN_ABI_ERRORS
+ bool "Warn if there are errors at ABI files"
+ depends on COMPILE_TEST
+ help
+ The files under Documentation/ABI should follow what's
+ described at Documentation/ABI/README. Yet, as they're manually
+ written, it would be possible that some of those files would
+ have errors that would break them for being parsed by
+ scripts/get_abi.pl. Add a check to verify them.
+
+ If unsure, select 'N'.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index e889e7cb8511..c6480ed22884 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,6 +4,11 @@
subdir-y := devicetree/bindings/
+# Check for broken ABI files
+ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
+$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
+endif
+
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
SPHINXOPTS =
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index cbdfae379896..b1b7e141ca99 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2110,4 +2110,6 @@ config IO_STRICT_DEVMEM
source "arch/$(SRCARCH)/Kconfig.debug"
+source "Documentation/Kconfig"
+
endmenu # Kernel hacking
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 6a4d387ebf3b..e80f9ab2ed26 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -47,7 +47,15 @@ my %data;
sub parse_error($$$$) {
my ($file, $ln, $msg, $data) = @_;
- print STDERR "file $file#$ln: $msg at\n\t$data";
+ $data =~ s/\s+$/\n/;
+
+ print STDERR "Warning: file $file#$ln:\n\t$msg";
+
+ if ($data ne "") {
+ print STDERR ". Line\n\t\t$data";
+ } else {
+ print STDERR "\n";
+ }
}
#
@@ -104,7 +112,7 @@ sub parse_abi {
# Invalid, but it is a common mistake
if ($new_tag eq "where") {
- parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_);
+ parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
$new_tag = "what";
}
@@ -205,7 +213,7 @@ sub parse_abi {
}
# Everything else is error
- parse_error($file, $ln, "Unexpected line:", $_);
+ parse_error($file, $ln, "Unexpected content", $_);
}
$data{$nametag}->{description} =~ s/^\n+//;
close IN;
--
2.21.0
^ permalink raw reply related
* [RFC v2 1/8] docs: ABI: README: specify that files should be ReST compatible
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
As we plan to remove the escaping code from the scripts/get_abi.pl,
specify at the ABI README file that the content of the file should
be ReST compatible.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/README | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 3121029dce21..8bac9cb09a6d 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -32,7 +32,7 @@ The different levels of stability are:
layout of the files below for details on how to do this.)
obsolete/
- This directory documents interfaces that are still remaining in
+ This directory 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.
@@ -58,6 +58,14 @@ Users: All users of this interface who wish to be notified when
be changed further.
+Note:
+ The fields should be use a simple notation, compatible with ReST markup.
+ Also, the file **should not** have a top-level index, like::
+
+ ===
+ foo
+ ===
+
How things move between levels:
Interfaces in stable may move to obsolete, as long as the proper
--
2.21.0
^ permalink raw reply related
* [RFC v2 7/8] docs: abi-testing.rst: enable --rst-sources when building docs
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
Now that ABI/testing documents were fixed, add --rst-sources to
the ABI/testing too.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi-testing.rst | 1 +
1 file changed, 1 insertion(+)
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:
--
2.21.0
^ permalink raw reply related
* [RFC v2 4/8] docs: ABI: make it parse ABI/stable as ReST-compatible files
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/sphinx/kernel_abi.py | 8 ++++++--
2 files changed, 7 insertions(+), 2 deletions(-)
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:
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index a417026ed690..a00eccfbafea 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -72,12 +72,13 @@ class KernelCmd(Directive):
u"""KernelABI (``kernel-abi``) directive"""
required_arguments = 1
- optional_arguments = 0
+ optional_arguments = 2
has_content = False
final_argument_whitespace = True
option_spec = {
- "debug" : directives.flag
+ "debug" : directives.flag,
+ "rst" : directives.unchanged
}
def run(self):
@@ -91,6 +92,9 @@ class KernelCmd(Directive):
cmd = "get_abi.pl rest --enable-lineno --dir "
cmd += self.arguments[0]
+ if 'rst' in self.options:
+ cmd += " --rst-source"
+
srctree = path.abspath(os.environ["srctree"])
fname = cmd
--
2.21.0
^ permalink raw reply related
* [RFC v2 6/8] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561224093.git.mchehab+samsung@kernel.org>
With just a single fix, the contents there can be parsed properly
without the need to escape any ReST incompatible stuff.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/obsolete/sysfs-gpio | 2 ++
Documentation/admin-guide/abi-obsolete.rst | 1 +
Documentation/admin-guide/abi-removed.rst | 1 +
3 files changed, 4 insertions(+)
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio
index 40d41ea1a3f5..18ba539e365c 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -13,6 +13,8 @@ Description:
GPIOs are identified as they are inside the kernel, using integers in
the range 0..INT_MAX. See Documentation/gpio for more information.
+ ::
+
/sys/class/gpio
/export ... asks the kernel to export a GPIO to userspace
/unexport ... to return a GPIO to the kernel
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:
--
2.21.0
^ permalink raw reply related
* [RFC v2 0/8]Produce ABI guide without escaping ReST source files
From: Mauro Carvalho Chehab @ 2019-06-22 17:31 UTC (permalink / raw)
To: Linux Doc Mailing List, gregkh
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
Hi Greg,
It turns out that fixing ABI/testing for it to be parsed transparently
was easy :-)
This series goes on top of the series I pasted early today:
Subject: [PATCH 00/12] Add the ABI documentation to the admin guide
It basically change the ABI parser to not try to escape ReST code.
With that, the descriptions inside the ABI files should now be compatible
with ReST output.
Patch 1 states that at ABI/README;
Patch 2 and 3 fix troubles at stable and testing ABI files. No changes at the
content of the ABI themselves. Most of the changes there are due to some
examples, tables and some parameter descriptions with weird formats.
Patch 4 enables the "clear mode" for stable;
Patch 5 is just a helper patch: it adds a second level to the ABI index, in order
to allow seeing what sections the parsed files will produce;
patch 6 enables "clear mode" to obsolete and removed;
patch 7 enables "clear mode" to testing
-
Patch 8 is here just for us not to forget it - it causes any COMPILE_TEST
build to validate if the ABI files are following the syntax described at
ABI/README. It won't try to build it with Sphinx, though. As this is quick
(~100ms on my desktop), I think it is worth to have it.
Mauro Carvalho Chehab (8):
docs: ABI: README: specify that files should be ReST compatible
docs: ABI: stable: make files ReST compatible
docs: ABI: testing: make the files compatible with ReST output
docs: ABI: make it parse ABI/stable as ReST-compatible files
docs: ABI: create a 2-depth index for ABI
docs: ABI: don't escape ReST-incompatible chars from obsolete and
removed
docs: abi-testing.rst: enable --rst-sources when building docs
docs: Kconfig/Makefile: add a check for broken ABI files
Documentation/ABI/README | 10 +-
Documentation/ABI/obsolete/sysfs-gpio | 2 +
Documentation/ABI/stable/firewire-cdev | 4 +
Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +-
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 +-
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 97 +++++--
Documentation/ABI/stable/sysfs-class-rfkill | 13 +-
Documentation/ABI/stable/sysfs-class-tpm | 90 +++----
Documentation/ABI/stable/sysfs-devices | 5 +-
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 5 +-
.../ABI/testing/configfs-spear-pcie-gadget | 36 +--
Documentation/ABI/testing/configfs-usb-gadget | 77 +++---
.../ABI/testing/configfs-usb-gadget-hid | 10 +-
.../ABI/testing/configfs-usb-gadget-rndis | 16 +-
.../ABI/testing/configfs-usb-gadget-uac1 | 18 +-
.../ABI/testing/configfs-usb-gadget-uvc | 220 +++++++++-------
Documentation/ABI/testing/debugfs-ec | 11 +-
Documentation/ABI/testing/debugfs-pktcdvd | 11 +-
Documentation/ABI/testing/dev-kmsg | 27 +-
Documentation/ABI/testing/evm | 17 +-
Documentation/ABI/testing/ima_policy | 132 +++++-----
Documentation/ABI/testing/procfs-diskstats | 40 +--
Documentation/ABI/testing/sysfs-block | 26 +-
Documentation/ABI/testing/sysfs-block-device | 2 +
Documentation/ABI/testing/sysfs-bus-acpi | 18 +-
.../sysfs-bus-event_source-devices-format | 3 +-
.../ABI/testing/sysfs-bus-i2c-devices-pca954x | 27 +-
Documentation/ABI/testing/sysfs-bus-iio | 10 +
.../sysfs-bus-iio-adc-envelope-detector | 5 +-
.../ABI/testing/sysfs-bus-iio-cros-ec | 2 +-
.../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 | 10 +-
.../ABI/testing/sysfs-bus-iio-lptimer-stm32 | 29 ++-
.../sysfs-bus-iio-magnetometer-hmc5843 | 19 +-
.../sysfs-bus-iio-temperature-max31856 | 19 +-
.../ABI/testing/sysfs-bus-iio-timer-stm32 | 114 +++++----
.../testing/sysfs-bus-intel_th-devices-msc | 4 +
.../testing/sysfs-bus-pci-devices-aer_stats | 119 +++++----
Documentation/ABI/testing/sysfs-bus-rapidio | 23 +-
.../ABI/testing/sysfs-bus-thunderbolt | 40 +--
Documentation/ABI/testing/sysfs-bus-usb | 30 ++-
.../testing/sysfs-bus-usb-devices-usbsevseg | 7 +-
Documentation/ABI/testing/sysfs-bus-vfio-mdev | 10 +-
Documentation/ABI/testing/sysfs-class-cxl | 15 +-
Documentation/ABI/testing/sysfs-class-led | 2 +-
Documentation/ABI/testing/sysfs-class-mic.txt | 52 ++--
Documentation/ABI/testing/sysfs-class-ocxl | 3 +
Documentation/ABI/testing/sysfs-class-power | 73 +++++-
.../ABI/testing/sysfs-class-power-twl4030 | 33 +--
Documentation/ABI/testing/sysfs-class-rc | 30 ++-
.../ABI/testing/sysfs-class-scsi_host | 7 +-
Documentation/ABI/testing/sysfs-class-typec | 12 +-
.../testing/sysfs-devices-platform-ACPI-TAD | 4 +
.../ABI/testing/sysfs-devices-platform-docg3 | 10 +-
.../sysfs-devices-platform-sh_mobile_lcdc_fb | 8 +-
.../ABI/testing/sysfs-devices-system-cpu | 99 +++++---
.../ABI/testing/sysfs-devices-system-ibm-rtl | 6 +-
.../testing/sysfs-driver-bd9571mwv-regulator | 4 +
Documentation/ABI/testing/sysfs-driver-genwqe | 11 +-
.../testing/sysfs-driver-hid-logitech-lg4ff | 18 +-
.../ABI/testing/sysfs-driver-hid-wiimote | 11 +-
.../ABI/testing/sysfs-driver-samsung-laptop | 13 +-
.../ABI/testing/sysfs-driver-toshiba_acpi | 26 ++
.../ABI/testing/sysfs-driver-toshiba_haps | 2 +
Documentation/ABI/testing/sysfs-driver-wacom | 4 +-
Documentation/ABI/testing/sysfs-firmware-acpi | 237 +++++++++---------
.../ABI/testing/sysfs-firmware-dmi-entries | 50 ++--
Documentation/ABI/testing/sysfs-firmware-gsmi | 2 +-
.../ABI/testing/sysfs-firmware-memmap | 16 +-
Documentation/ABI/testing/sysfs-fs-ext4 | 4 +-
.../ABI/testing/sysfs-hypervisor-xen | 13 +-
.../ABI/testing/sysfs-kernel-boot_params | 23 +-
.../ABI/testing/sysfs-kernel-mm-hugepages | 12 +-
.../ABI/testing/sysfs-platform-asus-laptop | 21 +-
.../ABI/testing/sysfs-platform-asus-wmi | 1 +
Documentation/ABI/testing/sysfs-platform-at91 | 10 +-
.../ABI/testing/sysfs-platform-eeepc-laptop | 14 +-
.../ABI/testing/sysfs-platform-ideapad-laptop | 9 +-
.../sysfs-platform-intel-wmi-thunderbolt | 1 +
.../ABI/testing/sysfs-platform-sst-atom | 13 +-
.../ABI/testing/sysfs-platform-usbip-vudc | 11 +-
Documentation/ABI/testing/sysfs-ptp | 2 +-
Documentation/ABI/testing/sysfs-uevent | 10 +-
Documentation/Kconfig | 11 +
Documentation/Makefile | 5 +
Documentation/admin-guide/abi-obsolete.rst | 1 +
Documentation/admin-guide/abi-removed.rst | 1 +
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/admin-guide/abi-testing.rst | 1 +
Documentation/admin-guide/abi.rst | 2 +-
Documentation/sphinx/kernel_abi.py | 8 +-
lib/Kconfig.debug | 2 +
scripts/get_abi.pl | 14 +-
100 files changed, 1457 insertions(+), 905 deletions(-)
create mode 100644 Documentation/Kconfig
--
2.21.0
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox