* [PATCH v2 20/22] docs: admin-guide, x86: add a features list
From: Mauro Carvalho Chehab @ 2019-06-20 17:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, Greg Kroah-Hartman, Alexey Budankov,
Darrick J. Wong, Changbin Du
In-Reply-To: <cover.1561050806.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/sphinx/kernel_feat.py | 169 +++++++++++++++++++++++++
Documentation/x86/features.rst | 3 +
Documentation/x86/index.rst | 1 +
6 files changed, 178 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
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/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
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 v2 16/22] docs: Kconfig/Makefile: add a check for broken ABI files
From: Mauro Carvalho Chehab @ 2019-06-20 17:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Andrew Morton, Kees Cook, Masahiro Yamada,
Petr Mladek, Andy Shevchenko, Joe Lawrence, Matthew Wilcox,
Tetsuo Handa, Sri Krishna chowdary, Uladzislau Rezki (Sony),
Changbin Du
In-Reply-To: <cover.1561050806.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 774e9b809ead..25248c012eb3 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -38,7 +38,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";
+ }
}
#
@@ -94,7 +102,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";
}
@@ -190,7 +198,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
* [PATCH v2 00/22] Add ABI and features docs to the Kernel documentation
From: Mauro Carvalho Chehab @ 2019-06-20 17:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Kees Cook, Anton Vorontsov, Colin Cross,
Tony Luck
This is a rebased version of the scripts with parse
Documentation/ABI and Documentation/feature files
and produce a ReST output. Those scripts are added to the
Kernel building system, in order to output their contents
inside the Kernel documentation.
Please notice that, as discussed, I added support at get_abi.pl
to handle ABI files as if they're compatible with ReST. Right
now, this feature can't be enabled for normal builds, as it will
cause Sphinx crashes. After getting the offending ABI files fixed,
a single line change will be enough to make it default.
a version "0" was sent back on 2017.
v1:
- rebased version of ABI scripts requested during KS/2019 discussions,
with some additional changes for it to parse newer ABI files;
v2:
- Some additional fixes and improvements to get_abi.pl script;
- get_abi.pl script now optionally suports parsing ABI files with
uses ReST format (by default, this is disabled);
- Added scripts/get_feat.pl to parse Documentation/features;
- Added SPDX headers.
Mauro Carvalho Chehab (22):
ABI: sysfs-bus-pci-devices-aer_stats uses an invalid tag
ABI: Fix KernelVersion tags
scripts: add an script to parse the ABI files
scripts/get_abi.pl: parse files with text at beginning
scripts/get_abi.pl: avoid use literal blocks when not needed
scripts/get_abi.pl: split label naming from xref logic
scripts/get_abi.pl: add support for searching for ABI symbols
scripts/get_abi.pl: represent what in tables
scripts/get_abi.pl: fix parse issues with some files
scripts/get_abi.pl: avoid creating duplicate names
scripts/get_abi.pl: add a handler for invalid "where" tag
scripts/get_abi.pl: add a validate command
doc-rst: add ABI documentation to the admin-guide book
docs: sphinx/kernel_abi.py: fix UTF-8 support
sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
docs: Kconfig/Makefile: add a check for broken ABI files
docs: kernel_abi.py: Update copyrights
doc: ABI scripts: add a SPDX header file
scripts: add a script to handle Documentation/features
docs: admin-guide, x86: add a features list
scripts/get_feat.pl: handle ".." special case
scripts/get_abi.pl: change script to allow parsing in ReST mode
Documentation/ABI/testing/pstore | 2 +-
.../sysfs-bus-event_source-devices-format | 2 +-
.../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 +-
.../testing/sysfs-bus-pci-devices-aer_stats | 24 +-
.../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +-
.../testing/sysfs-bus-usb-devices-usbsevseg | 10 +-
.../ABI/testing/sysfs-driver-altera-cvp | 2 +-
Documentation/ABI/testing/sysfs-driver-ppi | 2 +-
Documentation/ABI/testing/sysfs-driver-st | 2 +-
Documentation/ABI/testing/sysfs-driver-wacom | 2 +-
Documentation/Kconfig | 11 +
Documentation/Makefile | 5 +
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/features.rst | 3 +
Documentation/admin-guide/index.rst | 2 +
Documentation/conf.py | 2 +-
Documentation/sphinx/kernel_abi.py | 166 ++++++
Documentation/sphinx/kernel_feat.py | 169 ++++++
Documentation/x86/features.rst | 3 +
Documentation/x86/index.rst | 1 +
lib/Kconfig.debug | 2 +
scripts/get_abi.pl | 498 ++++++++++++++++++
scripts/get_feat.pl | 474 +++++++++++++++++
27 files changed, 1429 insertions(+), 38 deletions(-)
create mode 100644 Documentation/Kconfig
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/admin-guide/features.rst
create mode 100644 Documentation/sphinx/kernel_abi.py
create mode 100644 Documentation/sphinx/kernel_feat.py
create mode 100644 Documentation/x86/features.rst
create mode 100755 scripts/get_abi.pl
create mode 100755 scripts/get_feat.pl
--
2.21.0
^ permalink raw reply
* [PATCH v2 10/22] scripts/get_abi.pl: avoid creating duplicate names
From: Mauro Carvalho Chehab @ 2019-06-20 17:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561050806.git.mchehab+samsung@kernel.org>
The file the Documentation/ABI/testing/sysfs-class-power has
voltage_min, voltage_max and voltage_now symbols duplicated.
They are defined first for "General Properties" and then for
"USB Properties".
This cause those warnings:
get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26933: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_max".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26968: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_min".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing:27008: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_now".
And, as the references are not valid, it will also generate
warnings about links to undefined references.
Fix it by storing labels into a hash table and, when a duplicated
one is found, appending random characters at the end.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 116f0c33c16d..329ace635ac2 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -194,6 +194,8 @@ sub parse_abi {
# Outputs the book on ReST format
#
+my %labels;
+
sub output_rest {
foreach my $what (sort {
($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
@@ -217,6 +219,13 @@ sub output_rest {
$label =~ s,_+,_,g;
$label =~ s,_$,,;
+ # Avoid duplicated labels
+ while (defined($labels{$label})) {
+ my @chars = ("A".."Z", "a".."z");
+ $label .= $chars[rand @chars];
+ }
+ $labels{$label} = 1;
+
$data{$what}->{label} .= $label;
printf ".. _%s:\n\n", $label;
--
2.21.0
^ permalink raw reply related
* [PATCH v2 08/22] scripts/get_abi.pl: represent what in tables
From: Mauro Carvalho Chehab @ 2019-06-20 17:23 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <cover.1561050806.git.mchehab+samsung@kernel.org>
Several entries at the ABI have multiple What: with the same
description.
Instead of showing those symbols as sections, let's show them
as tables. That makes easier to read on the final output,
and avoid too much recursion at Sphinx parsing.
We need to put file references at the end, as we don't want
non-file tables to be mangled with other entries.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
scripts/get_abi.pl | 41 ++++++++++++++++++++++++++++++++++++-----
1 file changed, 36 insertions(+), 5 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ecf6b91df7c4..7d454e359d25 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -193,16 +193,19 @@ sub parse_abi {
#
# Outputs the book on ReST format
#
+
sub output_rest {
- foreach my $what (sort keys %data) {
+ foreach my $what (sort {
+ ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
+ $a cmp $b
+ } keys %data) {
my $type = $data{$what}->{type};
my $file = $data{$what}->{file};
+ my $filepath = $data{$what}->{filepath};
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
- my $bar = $w;
- $bar =~ s/./-/g;
foreach my $p (@{$data{$what}->{label}}) {
my ($content, $label) = @{$p};
@@ -222,9 +225,37 @@ sub output_rest {
last;
}
- print "$w\n$bar\n\n";
- print "- defined on file $file (type: $type)\n\n" if ($type ne "File");
+ $filepath =~ s,.*/(.*/.*),\1,;;
+ $filepath =~ s,[/\-],_,g;;
+ my $fileref = "abi_file_".$filepath;
+
+ if ($type eq "File") {
+ my $bar = $w;
+ $bar =~ s/./-/g;
+
+ print ".. _$fileref:\n\n";
+ print "$w\n$bar\n\n";
+ } else {
+ my @names = split /\s*,\s*/,$w;
+
+ my $len = 0;
+
+ foreach my $name (@names) {
+ $len = length($name) if (length($name) > $len);
+ }
+
+ print "What:\n\n";
+
+ print "+-" . "-" x $len . "-+\n";
+ foreach my $name (@names) {
+ printf "| %s", $name . " " x ($len - length($name)) . " |\n";
+ print "+-" . "-" x $len . "-+\n";
+ }
+ print "\n";
+ }
+
+ print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
my $desc = $data{$what}->{description};
$desc =~ s/^\s+//;
--
2.21.0
^ permalink raw reply related
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-20 17:16 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190620162945.GC23052@kroah.com>
Em Thu, 20 Jun 2019 18:29:45 +0200
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> On Thu, Jun 20, 2019 at 11:20:34AM -0300, Mauro Carvalho Chehab wrote:
> > Em Thu, 20 Jun 2019 14:54:13 +0200
> > Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> >
> > > On Thu, Jun 20, 2019 at 02:01:50PM +0200, Johan Hovold wrote:
> > > > > I don't know when "Description" and "RST-Description" would be used.
> > > > > Why not just parse "Description" like rst text and if things are "messy"
> > > > > we fix them up as found, like you did with the ":" here? It doesn't
> > > > > have to be complex, we can always fix them up after-the-fact if new
> > > > > stuff gets added that doesn't quite parse properly.
> > > > >
> > > > > Just like we do for most kernel-doc formatting :)
> > > >
> > > > But kernel-doc has a documented format, which was sort of the point I
> > > > was trying to make. If the new get_abi.pl scripts expects a colon I
> > > > think it should be mentioned somewhere (e.g. Documentation/ABI/README).
> > > >
> > > > Grepping for attribute entries in linux-next still reveals a number
> > > > descriptions that still lack that colon and use varying formatting. More
> > > > are bound to be added later, but perhaps that's ok depending on what
> > > > you're aiming at here.
> > >
> > > I'm aiming for "good enough" to start with, and then we can work through
> > > the exceptions.
> > >
> > > But given that Mauro hasn't resent the script that does the conversion
> > > of the files, I don't know if that will even matter... {hint}
> >
> > It sounds I missed something... are you expecting a new version?
>
> Yes, the last round of patches didn't have a SPDX header on the script,
> so I couldn't add it to the tree :(
I could swear I sent you a version with SPDX on it... anyway, I'm
re-sending the hole thing. The SPDX header addition is on a separate
patch.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Greg Kroah-Hartman @ 2019-06-20 16:29 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190620112034.0d2be447@coco.lan>
On Thu, Jun 20, 2019 at 11:20:34AM -0300, Mauro Carvalho Chehab wrote:
> Em Thu, 20 Jun 2019 14:54:13 +0200
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
>
> > On Thu, Jun 20, 2019 at 02:01:50PM +0200, Johan Hovold wrote:
> > > > I don't know when "Description" and "RST-Description" would be used.
> > > > Why not just parse "Description" like rst text and if things are "messy"
> > > > we fix them up as found, like you did with the ":" here? It doesn't
> > > > have to be complex, we can always fix them up after-the-fact if new
> > > > stuff gets added that doesn't quite parse properly.
> > > >
> > > > Just like we do for most kernel-doc formatting :)
> > >
> > > But kernel-doc has a documented format, which was sort of the point I
> > > was trying to make. If the new get_abi.pl scripts expects a colon I
> > > think it should be mentioned somewhere (e.g. Documentation/ABI/README).
> > >
> > > Grepping for attribute entries in linux-next still reveals a number
> > > descriptions that still lack that colon and use varying formatting. More
> > > are bound to be added later, but perhaps that's ok depending on what
> > > you're aiming at here.
> >
> > I'm aiming for "good enough" to start with, and then we can work through
> > the exceptions.
> >
> > But given that Mauro hasn't resent the script that does the conversion
> > of the files, I don't know if that will even matter... {hint}
>
> It sounds I missed something... are you expecting a new version?
Yes, the last round of patches didn't have a SPDX header on the script,
so I couldn't add it to the tree :(
thanks,
greg k-h
^ permalink raw reply
* Re: [PATCH] scripts/sphinx-pre-install: fix out-of-tree build
From: Mauro Carvalho Chehab @ 2019-06-20 15:20 UTC (permalink / raw)
To: Mike Rapoport; +Cc: Jonathan Corbet, linux-doc
In-Reply-To: <1561034637-12902-1-git-send-email-rppt@linux.ibm.com>
Em Thu, 20 Jun 2019 15:43:57 +0300
Mike Rapoport <rppt@linux.ibm.com> escreveu:
> Build of htmldocs fails for out-of-tree builds:
>
> $ make V=1 O=~/build/kernel/ htmldocs
> make -C /home/rppt/build/kernel -f /home/rppt/git/linux-docs/Makefile htmldocs
> make[1]: Entering directory '/home/rppt/build/kernel'
> make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=scripts/basic
> rm -f .tmp_quiet_recordmcount
> make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=Documentation htmldocs
> Can't open Documentation/conf.py at /home/rppt/git/linux-docs/scripts/sphinx-pre-install line 230.
> /home/rppt/git/linux-docs/Documentation/Makefile:80: recipe for target 'htmldocs' failed
> make[2]: *** [htmldocs] Error 2
>
> The scripts/sphinx-pre-install is trying to open files in the current
> directory which is $KBUILD_OUTPUT rather than in $srctree.
>
> Fix it.
>
> Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
> ---
> scripts/sphinx-pre-install | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> index 0b44d51..f710bbd 100755
> --- a/scripts/sphinx-pre-install
> +++ b/scripts/sphinx-pre-install
> @@ -5,8 +5,9 @@ use strict;
> # Copyright (c) 2017-2019 Mauro Carvalho Chehab <mchehab@kernel.org>
> #
>
> -my $conf = "Documentation/conf.py";
> -my $requirement_file = "Documentation/sphinx/requirements.txt";
> +my $prefix = "$ENV{'srctree'}/";
looks OK when called from Makefile, but if someone runs the script
directly, it will fail. Better to code it as:
my $prefix = ".";
$prefix = "$ENV{'srctree'}/" if ($ENV{'srctree'});
> +my $conf = $prefix . "Documentation/conf.py";
> +my $requirement_file = $prefix . "Documentation/sphinx/requirements.txt";
> my $virtenv_prefix = "sphinx_";
>
> #
Thanks,
Mauro
^ permalink raw reply
* [PATCH next] softirq: enable MAX_SOFTIRQ_TIME tuning with sysctl max_softirq_time_usecs
From: Zhiqiang Liu @ 2019-06-20 15:14 UTC (permalink / raw)
To: corbet, mcgrof, Kees Cook
Cc: akpm, manfred, jwilk, dvyukov, feng.tang, sunilmut,
quentin.perret, linux, alex.popov, tglx, linux-doc, linux-kernel,
linux-fsdevel, wangxiaogang (F), Zhoukang (A), Mingfangsen,
tedheadster, Eric Dumazet
From: Zhiqiang liu <liuzhiqiang26@huawei.com>
In __do_softirq func, MAX_SOFTIRQ_TIME was set to 2ms via experimentation by
commit c10d73671 ("softirq: reduce latencies") in 2013, which was designed
to reduce latencies for various network workloads. The key reason is that the
maximum number of microseconds in one NAPI polling cycle in net_rx_action func
was set to 2 jiffies, so different HZ settting will lead to different latencies.
However, commit 7acf8a1e8 ("Replace 2 jiffies with sysctl netdev_budget_usecs
to enable softirq tuning") adopts netdev_budget_usecs to tun maximum number of
microseconds in one NAPI polling cycle. So the latencies of net_rx_action can be
controlled by sysadmins to copy with hardware changes over time.
Correspondingly, the MAX_SOFTIRQ_TIME should be able to be tunned by sysadmins,
who knows best about hardware performance, for excepted tradeoff between latence
and fairness.
Here, we add sysctl variable max_softirq_time_usecs to replace MAX_SOFTIRQ_TIME
with 2ms default value.
Signed-off-by: Zhiqiang liu <liuzhiqiang26@huawei.com>
---
Documentation/sysctl/kernel.txt | 7 +++++++
kernel/softirq.c | 10 ++++++----
kernel/sysctl.c | 9 +++++++++
3 files changed, 22 insertions(+), 4 deletions(-)
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index f0c86fbb3b48..647233faf896 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -44,6 +44,7 @@ show up in /proc/sys/kernel:
- kexec_load_disabled
- kptr_restrict
- l2cr [ PPC only ]
+- max_softirq_time_usecs
- modprobe ==> Documentation/debugging-modules.txt
- modules_disabled
- msg_next_id [ sysv ipc ]
@@ -445,6 +446,12 @@ This flag controls the L2 cache of G3 processor boards. If
==============================================================
+max_softirq_time_usecs:
+Maximum number of microseconds to break the loop of restarting softirq
+processing for at most MAX_SOFTIRQ_RESTART times in __do_softirq().
+
+==============================================================
+
modules_disabled:
A toggle value indicating if modules are allowed to be loaded
diff --git a/kernel/softirq.c b/kernel/softirq.c
index a6b81c6b6bff..32f93d82e2e8 100644
--- a/kernel/softirq.c
+++ b/kernel/softirq.c
@@ -199,8 +199,9 @@ EXPORT_SYMBOL(__local_bh_enable_ip);
/*
* We restart softirq processing for at most MAX_SOFTIRQ_RESTART times,
- * but break the loop if need_resched() is set or after 2 ms.
- * The MAX_SOFTIRQ_TIME provides a nice upper bound in most cases, but in
+ * but break the loop if need_resched() is set or after
+ * max_softirq_time_usecs usecs.
+ * The max_softirq_time_usecs provides a nice upper bound in most cases, but in
* certain cases, such as stop_machine(), jiffies may cease to
* increment and so we need the MAX_SOFTIRQ_RESTART limit as
* well to make sure we eventually return from this method.
@@ -210,7 +211,7 @@ EXPORT_SYMBOL(__local_bh_enable_ip);
* we want to handle softirqs as soon as possible, but they
* should not be able to lock up the box.
*/
-#define MAX_SOFTIRQ_TIME msecs_to_jiffies(2)
+unsigned int __read_mostly max_softirq_time_usecs = 2000;
#define MAX_SOFTIRQ_RESTART 10
#ifdef CONFIG_TRACE_IRQFLAGS
@@ -248,7 +249,8 @@ static inline void lockdep_softirq_end(bool in_hardirq) { }
asmlinkage __visible void __softirq_entry __do_softirq(void)
{
- unsigned long end = jiffies + MAX_SOFTIRQ_TIME;
+ unsigned long end = jiffies +
+ usecs_to_jiffies(max_softirq_time_usecs);
unsigned long old_flags = current->flags;
int max_restart = MAX_SOFTIRQ_RESTART;
struct softirq_action *h;
diff --git a/kernel/sysctl.c b/kernel/sysctl.c
index 1beca96fb625..db4bc18f84de 100644
--- a/kernel/sysctl.c
+++ b/kernel/sysctl.c
@@ -118,6 +118,7 @@ extern unsigned int sysctl_nr_open_min, sysctl_nr_open_max;
#ifndef CONFIG_MMU
extern int sysctl_nr_trim_pages;
#endif
+extern unsigned int max_softirq_time_usecs;
/* Constants used for minimum and maximum */
#ifdef CONFIG_LOCKUP_DETECTOR
@@ -1276,6 +1277,14 @@ static struct ctl_table kern_table[] = {
.extra2 = &one,
},
#endif
+ {
+ .procname = "max_softirq_time_usecs",
+ .data = &max_softirq_time_usecs,
+ .maxlen = sizeof(unsigned int),
+ .mode = 0644,
+ .proc_handler = proc_dointvec_minmax,
+ .extra1 = &zero,
+ },
{ }
};
--
2.19.1
^ permalink raw reply related
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-20 14:27 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190619131408.26b45c3b@coco.lan>
Em Wed, 19 Jun 2019 13:14:08 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> Em Wed, 19 Jun 2019 17:02:07 +0200
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
>
> > On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> > > Hi Johan,
> > >
> > > Em Wed, 19 Jun 2019 14:51:35 +0200
> > > Johan Hovold <johan@kernel.org> escreveu:
> > >
> > > > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > > >
> > > > > When parsing via script, it is important to know if the script
> > > > > should consider a description as a literal block that should
> > > > > be displayed as-is, or if the description can be considered
> > > > > as a normal text.
> > > > >
> > > > > Change descriptions to ensure that the preceding line of a table
> > > > > ends with a colon. That makes easy to identify the need of a
> > > > > literal block.
> > > >
> > > > In the cover letter you say that the first four patches of this series,
> > > > including this one, "fix some ABI descriptions that are violating the
> > > > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > > > given that it's you that is now *introducing* a new syntax requirement
> > > > to assist your script.
> > >
> > > Yeah, what's there at the cover letter doesn't apply to this specific
> > > patch. The thing is that I wrote this series a lot of time ago (2016/17).
> > >
> > > I revived those per a request at KS ML, as we still need to expose the
> > > ABI content on some book that will be used by userspace people.
> > >
> > > So, I just rebased it on the top of curent Kernel, add a cover letter
> > > with the things I remembered and re-sent.
> > >
> > > In the specific case of this patch, the ":" there actually makes sense
> > > for someone that it is reading it as a text file, and it is an easy
> > > hack to make it parse better.
> > >
> > > > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > > > how will anyone adding new ABI descriptions learn about it?
> > >
> > > Yeah, either that or provide an alternative to "Description" tag, to be
> > > used with more complex ABI descriptions.
> > >
> > > One of the things that occurred to me, back on 2017, is that we should
> > > have a way to to specify that an specific ABI description would have
> > > a rich format. Something like:
> > >
> > > What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi
> > > Date: August 2010
> > > Contact: Stefan Achatz <erazor_de@users.sourceforge.net>
> > > RST-Description:
> > > It is possible to switch the cpi setting of the mouse with the
> > > press of a button.
> > > When read, this file returns the raw number of the actual cpi
> > > setting reported by the mouse. This number has to be further
> > > processed to receive the real dpi value:
> > >
> > > ===== =====
> > > VALUE DPI
> > > ===== =====
> > > 1 400
> > > 2 800
> > > 4 1600
> > > ===== =====
> > >
> > > With that, the script will know that the description contents will be using
> > > the ReST markup, and parse it accordingly. Right now, what it does, instead,
> > > is to place the description on a code-block, e. g. it will produce this
> > > output for the description:
> > >
> > > ::
> > >
> > > It is possible to switch the cpi setting of the mouse with the
> > > press of a button.
> > > When read, this file returns the raw number of the actual cpi
> > > setting reported by the mouse. This number has to be further
> > > processed to receive the real dpi value:
> > >
> > > VALUE DPI
> > > 1 400
> > > 2 800
> > > 4 1600
> > >
> > >
> > > Greg,
> > >
> > > what do you think?
> >
> > I don't know when "Description" and "RST-Description" would be used.
> > Why not just parse "Description" like rst text and if things are "messy"
> > we fix them up as found, like you did with the ":" here? It doesn't
> > have to be complex, we can always fix them up after-the-fact if new
> > stuff gets added that doesn't quite parse properly.
> >
> > Just like we do for most kernel-doc formatting :)
>
> Works for me. Yet, I guess I tried that, back on 2017.
>
> If I'm not mistaken, the initial patchset to solve the broken things
> won't be small, and will be require a lot of attention in order to
> identify what's broken and where.
>
> Btw, one thing is to pass at ReST validation. Another thing is to
> produce something that people can read.
>
> Right now, the pertinent logic at the script I wrote (scripts/get_abi.pl)
> is here:
>
> 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;
>
> print "$desc\n\n";
> }
> }
>
> If it discovers something weird enough, it just places everything
> into a comment block. Otherwise, it assumes that it is a plain
> text and that any special characters should be escaped.
>
> If the above block is replaced by a simple:
>
> print "$desc\n\n";
>
> The description content will be handled as a ReST file.
>
> I don't have any time right now to do this change and to handle the
> warnings that will start to popup.
>
> Btw, a single replace there is enough to show the amount of problems that
> it will rise, as it will basically break Sphinx build with:
>
> reading sources... [ 1%] admin-guide/abi-testing
> reST markup error:
> get_abi.pl rest --dir $srctree/Documentation/ABI/testing:45261: (SEVERE/4) Missing matching underline for section title overline.
>
> ==========================
> PCIe Device AER statistics
> These attributes show up under all the devices that are AER capable. These
To be clear here: the problem with the above is that ReST has zero
tolerance and actually behaves like a crash, if it receives something like:
==========================
PCIe Device AER statistics
==========================
For it to work, it has to have zero spaces before ===..=== line, e. g.:
==========================
PCIe Device AER statistics
==========================
Ok, maybe we could try to teach the parser a way to identify the initial
spacing of the first description line and remove that amount of
spaces/tabs for the following lines, but it may require some heuristics.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Mauro Carvalho Chehab @ 2019-06-20 14:20 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Johan Hovold, Linux Doc Mailing List, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Stefan Achatz
In-Reply-To: <20190620125413.GA5170@kroah.com>
Em Thu, 20 Jun 2019 14:54:13 +0200
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> On Thu, Jun 20, 2019 at 02:01:50PM +0200, Johan Hovold wrote:
> > > I don't know when "Description" and "RST-Description" would be used.
> > > Why not just parse "Description" like rst text and if things are "messy"
> > > we fix them up as found, like you did with the ":" here? It doesn't
> > > have to be complex, we can always fix them up after-the-fact if new
> > > stuff gets added that doesn't quite parse properly.
> > >
> > > Just like we do for most kernel-doc formatting :)
> >
> > But kernel-doc has a documented format, which was sort of the point I
> > was trying to make. If the new get_abi.pl scripts expects a colon I
> > think it should be mentioned somewhere (e.g. Documentation/ABI/README).
> >
> > Grepping for attribute entries in linux-next still reveals a number
> > descriptions that still lack that colon and use varying formatting. More
> > are bound to be added later, but perhaps that's ok depending on what
> > you're aiming at here.
>
> I'm aiming for "good enough" to start with, and then we can work through
> the exceptions.
>
> But given that Mauro hasn't resent the script that does the conversion
> of the files, I don't know if that will even matter... {hint}
It sounds I missed something... are you expecting a new version?
If so, what changes are you expecting?
Thanks,
Mauro
^ permalink raw reply
* Re: [Linux-kernel-mentees] [PATCH] Documentation: platform: convert x86-laptop-drivers.txt to reST
From: Shuah Khan @ 2019-06-20 13:38 UTC (permalink / raw)
To: Andy Shevchenko, Puranjay Mohan
Cc: Greg KH, Jonathan Corbet, Cezary Jackiewicz, Darren Hart,
Andy Shevchenko, Linux Documentation List, linux-kernel-mentees,
Linux Kernel Mailing List, Platform Driver, Shuah Khan
In-Reply-To: <CAHp75Vf__EtLVTOf0XvA3w7RPj+bnoQOud3gCXr1Fya0b_o4cw@mail.gmail.com>
On 6/20/19 12:19 AM, Andy Shevchenko wrote:
> On Tue, Jun 18, 2019 at 6:06 PM Shuah Khan <skhan@linuxfoundation.org> wrote:
>> On 6/18/19 7:39 AM, Greg KH wrote:
>>> On Tue, Jun 18, 2019 at 07:17:17AM -0600, Jonathan Corbet wrote:
>>>> On Tue, 18 Jun 2019 07:41:58 +0200
>>>> Greg KH <gregkh@linuxfoundation.org> wrote:
>>>>> On Tue, Jun 18, 2019 at 11:02:27AM +0530, Puranjay Mohan wrote:
>
>>> I bet it should be deleted, but we should ask the platform driver
>>> maintainers first before we do that :)
>
>> Adding Platform driver maintainers Darren Hart and Andy Shevchenko, and
>> Compal laptop maintainer Cezary Jackiewicz to the discussion.
>>
>> + platform-driver-x86@vger.kernel.org
>>
>> Hi Darren, Andy, and Cezary,
>>
>> Would it be okay to remove the x86-laptop-drivers.txt or should it be
>> converted to .rst and kept around?
>
> Shuan, thanks for heads up.
> The list of laptops supported by drivers in PDx86 subsystem is quite
> big and growing. The mentioned file contains less than per cent out of
> it and I don't think there is sense to make it up to date with
> thousands lines. Agree on removal.
>
Thanks Andy!
Puranjay!
Please remove the file and cc everybody on this list on the v2 patch.
Make sure to build docs and see if this removal doesn't cause errors.
thanks,
-- Shuah
^ permalink raw reply
* Re: [PATCH 04/14] ABI: better identificate tables
From: Greg Kroah-Hartman @ 2019-06-20 12:54 UTC (permalink / raw)
To: Johan Hovold
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Stefan Achatz
In-Reply-To: <20190620120150.GH6241@localhost>
On Thu, Jun 20, 2019 at 02:01:50PM +0200, Johan Hovold wrote:
> > I don't know when "Description" and "RST-Description" would be used.
> > Why not just parse "Description" like rst text and if things are "messy"
> > we fix them up as found, like you did with the ":" here? It doesn't
> > have to be complex, we can always fix them up after-the-fact if new
> > stuff gets added that doesn't quite parse properly.
> >
> > Just like we do for most kernel-doc formatting :)
>
> But kernel-doc has a documented format, which was sort of the point I
> was trying to make. If the new get_abi.pl scripts expects a colon I
> think it should be mentioned somewhere (e.g. Documentation/ABI/README).
>
> Grepping for attribute entries in linux-next still reveals a number
> descriptions that still lack that colon and use varying formatting. More
> are bound to be added later, but perhaps that's ok depending on what
> you're aiming at here.
I'm aiming for "good enough" to start with, and then we can work through
the exceptions.
But given that Mauro hasn't resent the script that does the conversion
of the files, I don't know if that will even matter... {hint}
thanks,
greg k-h
^ permalink raw reply
* [PATCH] scripts/sphinx-pre-install: fix out-of-tree build
From: Mike Rapoport @ 2019-06-20 12:43 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Mauro Carvalho Chehab, linux-doc, Mike Rapoport
Build of htmldocs fails for out-of-tree builds:
$ make V=1 O=~/build/kernel/ htmldocs
make -C /home/rppt/build/kernel -f /home/rppt/git/linux-docs/Makefile htmldocs
make[1]: Entering directory '/home/rppt/build/kernel'
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=scripts/basic
rm -f .tmp_quiet_recordmcount
make -f /home/rppt/git/linux-docs/scripts/Makefile.build obj=Documentation htmldocs
Can't open Documentation/conf.py at /home/rppt/git/linux-docs/scripts/sphinx-pre-install line 230.
/home/rppt/git/linux-docs/Documentation/Makefile:80: recipe for target 'htmldocs' failed
make[2]: *** [htmldocs] Error 2
The scripts/sphinx-pre-install is trying to open files in the current
directory which is $KBUILD_OUTPUT rather than in $srctree.
Fix it.
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
---
scripts/sphinx-pre-install | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 0b44d51..f710bbd 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -5,8 +5,9 @@ use strict;
# Copyright (c) 2017-2019 Mauro Carvalho Chehab <mchehab@kernel.org>
#
-my $conf = "Documentation/conf.py";
-my $requirement_file = "Documentation/sphinx/requirements.txt";
+my $prefix = "$ENV{'srctree'}/";
+my $conf = $prefix . "Documentation/conf.py";
+my $requirement_file = $prefix . "Documentation/sphinx/requirements.txt";
my $virtenv_prefix = "sphinx_";
#
--
2.7.4
^ permalink raw reply related
* Re: [PATCH 04/14] ABI: better identificate tables
From: Johan Hovold @ 2019-06-20 12:01 UTC (permalink / raw)
To: Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Johan Hovold, Linux Doc Mailing List,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Stefan Achatz
In-Reply-To: <20190619150207.GA19346@kroah.com>
On Wed, Jun 19, 2019 at 05:02:07PM +0200, Greg Kroah-Hartman wrote:
> On Wed, Jun 19, 2019 at 10:56:33AM -0300, Mauro Carvalho Chehab wrote:
> > Hi Johan,
> >
> > Em Wed, 19 Jun 2019 14:51:35 +0200
> > Johan Hovold <johan@kernel.org> escreveu:
> >
> > > On Thu, Jun 13, 2019 at 11:04:10PM -0300, Mauro Carvalho Chehab wrote:
> > > > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > > >
> > > > When parsing via script, it is important to know if the script
> > > > should consider a description as a literal block that should
> > > > be displayed as-is, or if the description can be considered
> > > > as a normal text.
> > > >
> > > > Change descriptions to ensure that the preceding line of a table
> > > > ends with a colon. That makes easy to identify the need of a
> > > > literal block.
> > >
> > > In the cover letter you say that the first four patches of this series,
> > > including this one, "fix some ABI descriptions that are violating the
> > > syntax described at Documentation/ABI/README". This seems a bit harsh,
> > > given that it's you that is now *introducing* a new syntax requirement
> > > to assist your script.
> >
> > Yeah, what's there at the cover letter doesn't apply to this specific
> > patch. The thing is that I wrote this series a lot of time ago (2016/17).
Got it, thanks.
[...]
> > In the specific case of this patch, the ":" there actually makes sense
> > for someone that it is reading it as a text file, and it is an easy
> > hack to make it parse better.
Human readers probably depend on more on tabulation and white space.
When the preceding description wasn't using a colon to begin with (and
you just replace s/\./:/) it can even look weird, but no big deal.
> > > Specifically, this new requirement isn't documented anywhere AFAICT, so
> > > how will anyone adding new ABI descriptions learn about it?
> >
> > Yeah, either that or provide an alternative to "Description" tag, to be
> > used with more complex ABI descriptions.
> >
> > One of the things that occurred to me, back on 2017, is that we should
> > have a way to to specify that an specific ABI description would have
> > a rich format. Something like:
[...]
> I don't know when "Description" and "RST-Description" would be used.
> Why not just parse "Description" like rst text and if things are "messy"
> we fix them up as found, like you did with the ":" here? It doesn't
> have to be complex, we can always fix them up after-the-fact if new
> stuff gets added that doesn't quite parse properly.
>
> Just like we do for most kernel-doc formatting :)
But kernel-doc has a documented format, which was sort of the point I
was trying to make. If the new get_abi.pl scripts expects a colon I
think it should be mentioned somewhere (e.g. Documentation/ABI/README).
Grepping for attribute entries in linux-next still reveals a number
descriptions that still lack that colon and use varying formatting. More
are bound to be added later, but perhaps that's ok depending on what
you're aiming at here.
Johan
^ permalink raw reply
* Re: [PATCH v2] replace timeconst bc script with an sh script
From: Borislav Petkov @ 2019-06-20 8:45 UTC (permalink / raw)
To: Ethan Sommer
Cc: hpa, Jonathan Corbet, Masahiro Yamada, Randy Dunlap,
Nick Desaulniers, Kees Cook, Joe Perches, Federico Vaga,
Ingo Molnar, Kieran Bingham, Peter Zijlstra (Intel), Mark Rutland,
John Stultz, Corey Minyard, Thomas Gleixner, linux-doc,
linux-kernel
In-Reply-To: <CAMEGPiqk5TU=z2_wvMfPuihVc5zOLRrTSVCpLA23k0r-hmAzmg@mail.gmail.com>
On Thu, Jun 20, 2019 at 04:29:19AM -0400, Ethan Sommer wrote:
> Ah sorry about that, I accidentally replied to Kieran only instead of to
> all, my response was "I will upload a patch with those issues fixed
> shortly, in terms of the dependency as far as I know commands only required
> for running tests don't count as kernel compilation dependencies, and I
> don't see any other uses of bc except for Documentation/EDID/Makefile, so I
> believe that bc can be removed from the kernel compilation section of the
> process document and will include that change with the updated patch that
> fixes the 2 issues you pointed out."
Sounds like parts of it should be in your commit message as a
justification *why* you're doing it. You can do that for your next
revision once you've waited a couple of days to gather feedback.
Also, please do not top-post.
Thx.
--
Regards/Gruss,
Boris.
SUSE Linux GmbH, GF: Felix Imendörffer, Mary Higgins, Sri Rasiah, HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH v2] replace timeconst bc script with an sh script
From: Ethan Sommer @ 2019-06-20 8:43 UTC (permalink / raw)
To: Borislav Petkov
Cc: hpa, Jonathan Corbet, Masahiro Yamada, Randy Dunlap,
Nick Desaulniers, Kees Cook, Joe Perches, Federico Vaga,
Ingo Molnar, Kieran Bingham, Peter Zijlstra (Intel), Mark Rutland,
John Stultz, Corey Minyard, Thomas Gleixner, linux-doc,
linux-kernel
In-Reply-To: <20190620082557.GB28346@zn.tnic>
(resend because I didn't know gmail would make it html)
Ah sorry about that, I accidentally replied to Kieran only instead of
to all, my response was "I will upload a patch with those issues fixed
shortly, in terms of the dependency as far as I know commands only required
for running tests don't count as kernel compilation dependencies, and I
don't see any other uses of bc except for Documentation/EDID/Makefile, so
I believe that bc can be removed from the kernel compilation section of the
process document and will include that change with the updated patch that
fixes the 2 issues you pointed out."
On Thu, Jun 20, 2019 at 4:26 AM Borislav Petkov <bp@suse.de> wrote:
>
> On Thu, Jun 20, 2019 at 04:11:32AM -0400, Ethan Sommer wrote:
> > removes the bc build dependency introduced when timeconst.pl was
> > replaced by timeconst.bc:
> > 70730bca1331 ("kernel: Replace timeconst.pl with a bc script")
>
> I don't see you answering Kieran's questions anywhere...
>
> --
> Regards/Gruss,
> Boris.
>
> SUSE Linux GmbH, GF: Felix Imendörffer, Mary Higgins, Sri Rasiah, HRB 21284 (AG Nürnberg)
^ permalink raw reply
* Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
From: Miguel Ojeda @ 2019-06-20 8:37 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet
In-Reply-To: <20190618201455.04e8743d@coco.lan>
On Wed, Jun 19, 2019 at 1:15 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Yeah, the plan is to move all text files inside Documentation/ to .rst[1].
>
> [1] There are some exceptions: for ABI and features, the current plan
> is to have a script that parses their strict formats and produce
> a ReST output.
>
>
> Btw, Still pending to be sent, I have already a patch removing the
> :orphan: from this file and adding it to the admin guide:
>
> https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames_v5.1&id=eae5b48cab115c83be8dd59ee99b9e45f8142134
>
> And the corresponding output, after the patches I currently have:
>
> https://www.infradead.org/~mchehab/rst_conversion/admin-guide/lcd-panel-cgram.html
Thanks for the pointers! I guess you will take all these
patches/series on your tree(s), but if you want maintainers to do it,
please let me know!
Cheers,
Miguel
^ permalink raw reply
* Re: [PATCH v2] replace timeconst bc script with an sh script
From: Borislav Petkov @ 2019-06-20 8:25 UTC (permalink / raw)
To: Ethan Sommer
Cc: hpa, Jonathan Corbet, Masahiro Yamada, Randy Dunlap,
Nick Desaulniers, Kees Cook, Joe Perches, Federico Vaga,
Ingo Molnar, Kieran Bingham, Peter Zijlstra (Intel), Mark Rutland,
John Stultz, Corey Minyard, Thomas Gleixner, linux-doc,
linux-kernel
In-Reply-To: <20190620081142.31302-1-e5ten.arch@gmail.com>
On Thu, Jun 20, 2019 at 04:11:32AM -0400, Ethan Sommer wrote:
> removes the bc build dependency introduced when timeconst.pl was
> replaced by timeconst.bc:
> 70730bca1331 ("kernel: Replace timeconst.pl with a bc script")
I don't see you answering Kieran's questions anywhere...
--
Regards/Gruss,
Boris.
SUSE Linux GmbH, GF: Felix Imendörffer, Mary Higgins, Sri Rasiah, HRB 21284 (AG Nürnberg)
^ permalink raw reply
* [PATCH v2] replace timeconst bc script with an sh script
From: Ethan Sommer @ 2019-06-20 8:11 UTC (permalink / raw)
Cc: hpa, Ethan Sommer, Jonathan Corbet, Masahiro Yamada, Randy Dunlap,
Nick Desaulniers, Kees Cook, Joe Perches, Federico Vaga,
Ingo Molnar, Kieran Bingham, Peter Zijlstra (Intel),
Borislav Petkov, Mark Rutland, John Stultz, Corey Minyard,
Thomas Gleixner, linux-doc, linux-kernel
In-Reply-To: <8a9ffb4b-791d-35d1-bb2a-7b6ad812bff1@ideasonboard.com>
removes the bc build dependency introduced when timeconst.pl was
replaced by timeconst.bc:
70730bca1331 ("kernel: Replace timeconst.pl with a bc script")
Signed-off-by: Ethan Sommer <e5ten.arch@gmail.com>
---
Documentation/process/changes.rst | 6 --
Kbuild | 4 +-
kernel/time/timeconst.bc | 117 -----------------------------
kernel/time/timeconst.sh | 118 ++++++++++++++++++++++++++++++
4 files changed, 120 insertions(+), 125 deletions(-)
delete mode 100644 kernel/time/timeconst.bc
create mode 100755 kernel/time/timeconst.sh
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 18735dc460a0..14347f6752ea 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -108,12 +108,6 @@ Perl
You will need perl 5 and the following modules: ``Getopt::Long``,
``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
-BC
---
-
-You will need bc to build kernels 3.10 and higher
-
-
OpenSSL
-------
diff --git a/Kbuild b/Kbuild
index 8637fd14135f..2b5f2957cf04 100644
--- a/Kbuild
+++ b/Kbuild
@@ -20,9 +20,9 @@ timeconst-file := include/generated/timeconst.h
targets += $(timeconst-file)
-filechk_gentimeconst = echo $(CONFIG_HZ) | bc -q $<
+filechk_gentimeconst = $(CONFIG_SHELL) $< $(CONFIG_HZ)
-$(timeconst-file): kernel/time/timeconst.bc FORCE
+$(timeconst-file): kernel/time/timeconst.sh FORCE
$(call filechk,gentimeconst)
#####
diff --git a/kernel/time/timeconst.bc b/kernel/time/timeconst.bc
deleted file mode 100644
index 7ed0e0fb5831..000000000000
--- a/kernel/time/timeconst.bc
+++ /dev/null
@@ -1,117 +0,0 @@
-/* SPDX-License-Identifier: GPL-2.0 */
-
-scale=0
-
-define gcd(a,b) {
- auto t;
- while (b) {
- t = b;
- b = a % b;
- a = t;
- }
- return a;
-}
-
-/* Division by reciprocal multiplication. */
-define fmul(b,n,d) {
- return (2^b*n+d-1)/d;
-}
-
-/* Adjustment factor when a ceiling value is used. Use as:
- (imul * n) + (fmulxx * n + fadjxx) >> xx) */
-define fadj(b,n,d) {
- auto v;
- d = d/gcd(n,d);
- v = 2^b*(d-1)/d;
- return v;
-}
-
-/* Compute the appropriate mul/adj values as well as a shift count,
- which brings the mul value into the range 2^b-1 <= x < 2^b. Such
- a shift value will be correct in the signed integer range and off
- by at most one in the upper half of the unsigned range. */
-define fmuls(b,n,d) {
- auto s, m;
- for (s = 0; 1; s++) {
- m = fmul(s,n,d);
- if (m >= 2^(b-1))
- return s;
- }
- return 0;
-}
-
-define timeconst(hz) {
- print "/* Automatically generated by kernel/time/timeconst.bc */\n"
- print "/* Time conversion constants for HZ == ", hz, " */\n"
- print "\n"
-
- print "#ifndef KERNEL_TIMECONST_H\n"
- print "#define KERNEL_TIMECONST_H\n\n"
-
- print "#include <linux/param.h>\n"
- print "#include <linux/types.h>\n\n"
-
- print "#if HZ != ", hz, "\n"
- print "#error \qinclude/generated/timeconst.h has the wrong HZ value!\q\n"
- print "#endif\n\n"
-
- if (hz < 2) {
- print "#error Totally bogus HZ value!\n"
- } else {
- s=fmuls(32,1000,hz)
- obase=16
- print "#define HZ_TO_MSEC_MUL32\tU64_C(0x", fmul(s,1000,hz), ")\n"
- print "#define HZ_TO_MSEC_ADJ32\tU64_C(0x", fadj(s,1000,hz), ")\n"
- obase=10
- print "#define HZ_TO_MSEC_SHR32\t", s, "\n"
-
- s=fmuls(32,hz,1000)
- obase=16
- print "#define MSEC_TO_HZ_MUL32\tU64_C(0x", fmul(s,hz,1000), ")\n"
- print "#define MSEC_TO_HZ_ADJ32\tU64_C(0x", fadj(s,hz,1000), ")\n"
- obase=10
- print "#define MSEC_TO_HZ_SHR32\t", s, "\n"
-
- obase=10
- cd=gcd(hz,1000)
- print "#define HZ_TO_MSEC_NUM\t\t", 1000/cd, "\n"
- print "#define HZ_TO_MSEC_DEN\t\t", hz/cd, "\n"
- print "#define MSEC_TO_HZ_NUM\t\t", hz/cd, "\n"
- print "#define MSEC_TO_HZ_DEN\t\t", 1000/cd, "\n"
- print "\n"
-
- s=fmuls(32,1000000,hz)
- obase=16
- print "#define HZ_TO_USEC_MUL32\tU64_C(0x", fmul(s,1000000,hz), ")\n"
- print "#define HZ_TO_USEC_ADJ32\tU64_C(0x", fadj(s,1000000,hz), ")\n"
- obase=10
- print "#define HZ_TO_USEC_SHR32\t", s, "\n"
-
- s=fmuls(32,hz,1000000)
- obase=16
- print "#define USEC_TO_HZ_MUL32\tU64_C(0x", fmul(s,hz,1000000), ")\n"
- print "#define USEC_TO_HZ_ADJ32\tU64_C(0x", fadj(s,hz,1000000), ")\n"
- obase=10
- print "#define USEC_TO_HZ_SHR32\t", s, "\n"
-
- obase=10
- cd=gcd(hz,1000000)
- print "#define HZ_TO_USEC_NUM\t\t", 1000000/cd, "\n"
- print "#define HZ_TO_USEC_DEN\t\t", hz/cd, "\n"
- print "#define USEC_TO_HZ_NUM\t\t", hz/cd, "\n"
- print "#define USEC_TO_HZ_DEN\t\t", 1000000/cd, "\n"
-
- cd=gcd(hz,1000000000)
- print "#define HZ_TO_NSEC_NUM\t\t", 1000000000/cd, "\n"
- print "#define HZ_TO_NSEC_DEN\t\t", hz/cd, "\n"
- print "#define NSEC_TO_HZ_NUM\t\t", hz/cd, "\n"
- print "#define NSEC_TO_HZ_DEN\t\t", 1000000000/cd, "\n"
- print "\n"
-
- print "#endif /* KERNEL_TIMECONST_H */\n"
- }
- halt
-}
-
-hz = read();
-timeconst(hz)
diff --git a/kernel/time/timeconst.sh b/kernel/time/timeconst.sh
new file mode 100755
index 000000000000..20dd24815ae1
--- /dev/null
+++ b/kernel/time/timeconst.sh
@@ -0,0 +1,118 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-2.0
+
+if [ -z "$1" ]; then
+ printf '%s <HZ>\n' "$0"
+ exit 1
+else
+ hz="$1"
+fi
+
+# 2 to the power of n
+pot() {
+ local i=1
+ local j=1
+ while [ "${j}" -le "$1" ]; do
+ i="$((i * 2))"
+ j="$((j + 1))"
+ done
+ printf '%s\n' "${i}"
+}
+
+# Greatest common denominator
+gcd() {
+ local i="$1"
+ local j="$2"
+ local k
+ while [ "${j}" -ne 0 ]; do
+ k="${j}"
+ j="$((i % j))"
+ i="${k}"
+ done
+ printf '%s\n' "${i}"
+}
+
+# Division by reciprocal multiplication.
+fmul() {
+ printf '%s\n' "$((($(pot "$1") * $2 + $3 - 1) / $3))"
+}
+
+# Adjustment factor when a ceiling value is used.
+fadj() {
+ local i="$(gcd "$2" "$3")"
+ printf '%s\n' "$(($(pot "$1") * ($3 / i - 1) / ($3 / i)))"
+}
+
+# Compute the appropriate mul/adj values as well as a shift count,
+# which brings the mul value into the range 2^b-1 <= x < 2^b. Such
+# a shift value will be correct in the signed integer range and off
+# by at most one in the upper half of the unsigned range.
+fmuls() {
+ local i=0
+ local j
+ while true; do
+ j="$(fmul "${i}" "$2" "$3")"
+ if [ "${j}" -ge "$(pot "$(($1 - 1))")" ]; then
+ printf '%s\n' "${i}" && return
+ fi
+ i="$((i + 1))"
+ done
+}
+
+printf '/* Automatically generated by kernel/time/timeconst.sh */\n'
+printf '/* Time conversion constants for HZ == %s */\n\n' "$1"
+
+printf '#ifndef KERNEL_TIMECONST_H\n'
+printf '#define KERNEL_TIMECONST_H\n\n'
+
+printf '#include <linux/param.h>\n'
+printf '#include <linux/types.h>\n\n'
+
+printf '#if HZ != %s\n' "$1"
+printf '#error "include/generated/timeconst.h has the wrong HZ value!"\n'
+printf '#endif\n\n'
+
+if [ "$1" -lt 2 ]; then
+ printf '#error Totally bogus HZ value!\n'
+ exit 1
+fi
+
+s="$(fmuls 32 1000 "$1")"
+printf '#define HZ_TO_MSEC_MUL32\tU64_C(0x%X)\n' "$(fmul "${s}" 1000 "$1")"
+printf '#define HZ_TO_MSEC_ADJ32\tU64_C(0x%X)\n' "$(fadj "${s}" 1000 "$1")"
+printf '#define HZ_TO_MSEC_SHR32\t%s\n' "${s}"
+
+s="$(fmuls 32 "$1" 1000)"
+printf '#define MSEC_TO_HZ_MUL32\tU64_C(0x%X)\n' "$(fmul "${s}" "$1" 1000)"
+printf '#define MSEC_TO_HZ_ADJ32\tU64_C(0x%X)\n' "$(fadj "${s}" "$1" 1000)"
+printf '#define MSEC_TO_HZ_SHR32\t%s\n' "${s}"
+
+cd="$(gcd "$1" 1000)"
+printf '#define HZ_TO_MSEC_NUM\t\t%s\n' "$((1000 / cd))"
+printf '#define HZ_TO_MSEC_DEN\t\t%s\n' "$((hz / cd))"
+printf '#define MSEC_TO_HZ_NUM\t\t%s\n' "$((hz / cd))"
+printf '#define MSEC_TO_HZ_DEN\t\t%s\n\n' "$((1000 / cd))"
+
+s="$(fmuls 32 1000000 "$1")"
+printf '#define HZ_TO_USEC_MUL32\tU64_C(0x%X)\n' "$(fmul "${s}" 1000000 "$1")"
+printf '#define HZ_TO_USEC_ADJ32\tU64_C(0x%X)\n' "$(fadj "${s}" 1000000 "$1")"
+printf '#define HZ_TO_USEC_SHR32\t%s\n' "${s}"
+
+s="$(fmuls 32 "$1" 1000000)"
+printf '#define USEC_TO_HZ_MUL32\tU64_C(0x%X)\n' "$(fmul "${s}" "$1" 1000000)"
+printf '#define USEC_TO_HZ_ADJ32\tU64_C(0x%X)\n' "$(fadj "${s}" "$1" 1000000)"
+printf '#define USEC_TO_HZ_SHR32\t%s\n' "${s}"
+
+cd="$(gcd "$1" 1000000)"
+printf '#define HZ_TO_USEC_NUM\t\t%s\n' "$((1000000 / cd))"
+printf '#define HZ_TO_USEC_DEN\t\t%s\n' "$((hz / cd))"
+printf '#define USEC_TO_HZ_NUM\t\t%s\n' "$((hz / cd))"
+printf '#define USEC_TO_HZ_DEN\t\t%s\n' "$((1000000 / cd))"
+
+cd="$(gcd "$1" 1000000000)"
+printf '#define HZ_TO_NSEC_NUM\t\t%s\n' "$((1000000000 / cd))"
+printf '#define HZ_TO_NSEC_DEN\t\t%s\n' "$((hz / cd))"
+printf '#define NSEC_TO_HZ_NUM\t\t%s\n' "$((hz / cd))"
+printf '#define NSEC_TO_HZ_DEN\t\t%s\n' "$((1000000000 / cd))"
+
+printf '\n#endif /* KERNEL_TIMECONST_H */\n'
--
2.22.0
^ permalink raw reply related
* Re: [Linux-kernel-mentees] [PATCH] Documentation: platform: convert x86-laptop-drivers.txt to reST
From: Andy Shevchenko @ 2019-06-20 6:19 UTC (permalink / raw)
To: Shuah Khan
Cc: Greg KH, Jonathan Corbet, Cezary Jackiewicz, Darren Hart,
Andy Shevchenko, Puranjay Mohan, Linux Documentation List,
linux-kernel-mentees, Linux Kernel Mailing List, Platform Driver
In-Reply-To: <8aeb222a-ee44-4125-45fd-ce9a741e7ecc@linuxfoundation.org>
On Tue, Jun 18, 2019 at 6:06 PM Shuah Khan <skhan@linuxfoundation.org> wrote:
> On 6/18/19 7:39 AM, Greg KH wrote:
> > On Tue, Jun 18, 2019 at 07:17:17AM -0600, Jonathan Corbet wrote:
> >> On Tue, 18 Jun 2019 07:41:58 +0200
> >> Greg KH <gregkh@linuxfoundation.org> wrote:
> >>> On Tue, Jun 18, 2019 at 11:02:27AM +0530, Puranjay Mohan wrote:
> > I bet it should be deleted, but we should ask the platform driver
> > maintainers first before we do that :)
> Adding Platform driver maintainers Darren Hart and Andy Shevchenko, and
> Compal laptop maintainer Cezary Jackiewicz to the discussion.
>
> + platform-driver-x86@vger.kernel.org
>
> Hi Darren, Andy, and Cezary,
>
> Would it be okay to remove the x86-laptop-drivers.txt or should it be
> converted to .rst and kept around?
Shuan, thanks for heads up.
The list of laptops supported by drivers in PDx86 subsystem is quite
big and growing. The mentioned file contains less than per cent out of
it and I don't think there is sense to make it up to date with
thousands lines. Agree on removal.
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v1 21/22] docs: admin-guide: add laptops documentation
From: Andy Shevchenko @ 2019-06-20 6:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
Linux Kernel Mailing List, Jonathan Corbet, Matan Ziv-Av,
Mattia Dongili, Arnd Bergmann, Greg Kroah-Hartman, Darren Hart,
Andy Shevchenko, Platform Driver
In-Reply-To: <48cf367612aeec99f9eef54bb57685eb3b6c4ebf.1560891322.git.mchehab+samsung@kernel.org>
On Wed, Jun 19, 2019 at 12:05 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> The docs under Documentation/laptops contain users specific
> information.
>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
with a caveat about Documentation/admin-guide/sysctl/vm.rst.
How block bump is related to laptops? It sounds rather common
debugging feature, no?
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> Documentation/ABI/testing/sysfs-block-device | 2 +-
> Documentation/ABI/testing/sysfs-platform-asus-laptop | 2 +-
> Documentation/admin-guide/index.rst | 1 +
> Documentation/admin-guide/kernel-parameters.txt | 2 +-
> Documentation/{ => admin-guide}/laptops/asus-laptop.rst | 0
> .../{ => admin-guide}/laptops/disk-shock-protection.rst | 0
> Documentation/{ => admin-guide}/laptops/index.rst | 1 -
> Documentation/{ => admin-guide}/laptops/laptop-mode.rst | 0
> Documentation/{ => admin-guide}/laptops/lg-laptop.rst | 1 -
> Documentation/{ => admin-guide}/laptops/sony-laptop.rst | 0
> Documentation/{ => admin-guide}/laptops/sonypi.rst | 0
> Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst | 0
> Documentation/{ => admin-guide}/laptops/toshiba_haps.rst | 0
> Documentation/admin-guide/sysctl/vm.rst | 4 ++--
> MAINTAINERS | 4 ++--
> drivers/char/Kconfig | 2 +-
> drivers/platform/x86/Kconfig | 4 ++--
> 17 files changed, 11 insertions(+), 12 deletions(-)
> rename Documentation/{ => admin-guide}/laptops/asus-laptop.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/disk-shock-protection.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/index.rst (95%)
> rename Documentation/{ => admin-guide}/laptops/laptop-mode.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/lg-laptop.rst (99%)
> rename Documentation/{ => admin-guide}/laptops/sony-laptop.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/sonypi.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/thinkpad-acpi.rst (100%)
> rename Documentation/{ => admin-guide}/laptops/toshiba_haps.rst (100%)
>
> diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
> index 0d57bbb4fddc..17f2bc7dd261 100644
> --- a/Documentation/ABI/testing/sysfs-block-device
> +++ b/Documentation/ABI/testing/sysfs-block-device
> @@ -45,7 +45,7 @@ Description:
> - Values below -2 are rejected with -EINVAL
>
> For more information, see
> - Documentation/laptops/disk-shock-protection.rst
> + Documentation/admin-guide/laptops/disk-shock-protection.rst
>
>
> What: /sys/block/*/device/ncq_prio_enable
> diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> index d67fa4bafa70..8b0e8205a6a2 100644
> --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
> +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> @@ -31,7 +31,7 @@ Description:
> To control the LED display, use the following :
> echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
> where T control the 3 letters display, and DDD the 3 digits display.
> - The DDD table can be found in Documentation/laptops/asus-laptop.rst
> + The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
>
> What: /sys/devices/platform/asus_laptop/bluetooth
> Date: January 2007
> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
> index 5940ce8d16af..e4f0cb2a02bd 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -79,6 +79,7 @@ configure specific aspects of kernel behavior to your liking.
> aoe/index
> perf-security
> acpi/index
> + laptops/index
>
> btmrvl
> clearing-warn-once
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 0b17312b9198..69a9e2e66dfb 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -4356,7 +4356,7 @@
> Format: <integer>
>
> sonypi.*= [HW] Sony Programmable I/O Control Device driver
> - See Documentation/laptops/sonypi.rst
> + See Documentation/admin-guide/laptops/sonypi.rst
>
> spectre_v2= [X86] Control mitigation of Spectre variant 2
> (indirect branch speculation) vulnerability.
> diff --git a/Documentation/laptops/asus-laptop.rst b/Documentation/admin-guide/laptops/asus-laptop.rst
> similarity index 100%
> rename from Documentation/laptops/asus-laptop.rst
> rename to Documentation/admin-guide/laptops/asus-laptop.rst
> diff --git a/Documentation/laptops/disk-shock-protection.rst b/Documentation/admin-guide/laptops/disk-shock-protection.rst
> similarity index 100%
> rename from Documentation/laptops/disk-shock-protection.rst
> rename to Documentation/admin-guide/laptops/disk-shock-protection.rst
> diff --git a/Documentation/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst
> similarity index 95%
> rename from Documentation/laptops/index.rst
> rename to Documentation/admin-guide/laptops/index.rst
> index 001a30910d09..6b554e39863b 100644
> --- a/Documentation/laptops/index.rst
> +++ b/Documentation/admin-guide/laptops/index.rst
> @@ -1,4 +1,3 @@
> -:orphan:
>
> ==============
> Laptop Drivers
> diff --git a/Documentation/laptops/laptop-mode.rst b/Documentation/admin-guide/laptops/laptop-mode.rst
> similarity index 100%
> rename from Documentation/laptops/laptop-mode.rst
> rename to Documentation/admin-guide/laptops/laptop-mode.rst
> diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/admin-guide/laptops/lg-laptop.rst
> similarity index 99%
> rename from Documentation/laptops/lg-laptop.rst
> rename to Documentation/admin-guide/laptops/lg-laptop.rst
> index f2c2ffe31101..ce9b14671cb9 100644
> --- a/Documentation/laptops/lg-laptop.rst
> +++ b/Documentation/admin-guide/laptops/lg-laptop.rst
> @@ -1,6 +1,5 @@
> .. SPDX-License-Identifier: GPL-2.0+
>
> -:orphan:
>
> LG Gram laptop extra features
> =============================
> diff --git a/Documentation/laptops/sony-laptop.rst b/Documentation/admin-guide/laptops/sony-laptop.rst
> similarity index 100%
> rename from Documentation/laptops/sony-laptop.rst
> rename to Documentation/admin-guide/laptops/sony-laptop.rst
> diff --git a/Documentation/laptops/sonypi.rst b/Documentation/admin-guide/laptops/sonypi.rst
> similarity index 100%
> rename from Documentation/laptops/sonypi.rst
> rename to Documentation/admin-guide/laptops/sonypi.rst
> diff --git a/Documentation/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst
> similarity index 100%
> rename from Documentation/laptops/thinkpad-acpi.rst
> rename to Documentation/admin-guide/laptops/thinkpad-acpi.rst
> diff --git a/Documentation/laptops/toshiba_haps.rst b/Documentation/admin-guide/laptops/toshiba_haps.rst
> similarity index 100%
> rename from Documentation/laptops/toshiba_haps.rst
> rename to Documentation/admin-guide/laptops/toshiba_haps.rst
> diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst
> index 4940ab610eb7..d918b11326f3 100644
> --- a/Documentation/admin-guide/sysctl/vm.rst
> +++ b/Documentation/admin-guide/sysctl/vm.rst
> @@ -108,7 +108,7 @@ block_dump
> ==========
>
> block_dump enables block I/O debugging when set to a nonzero value. More
> -information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
> +information on block I/O debugging is in Documentation/admin-guide/laptops/laptop-mode.rst.
>
>
> compact_memory
> @@ -298,7 +298,7 @@ laptop_mode
> ===========
>
> laptop_mode is a knob that controls "laptop mode". All the things that are
> -controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
> +controlled by this knob are discussed in Documentation/admin-guide/laptops/laptop-mode.rst.
>
>
> legacy_va_layout
> diff --git a/MAINTAINERS b/MAINTAINERS
> index b7c81bd0f8e8..ab170522ec55 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -8927,7 +8927,7 @@ M: Matan Ziv-Av <matan@svgalib.org>
> L: platform-driver-x86@vger.kernel.org
> S: Maintained
> F: Documentation/ABI/testing/sysfs-platform-lg-laptop
> -F: Documentation/laptops/lg-laptop.rst
> +F: Documentation/admin-guide/laptops/lg-laptop.rst
> F: drivers/platform/x86/lg-laptop.c
>
> LG2160 MEDIA DRIVER
> @@ -14756,7 +14756,7 @@ M: Mattia Dongili <malattia@linux.it>
> L: platform-driver-x86@vger.kernel.org
> W: http://www.linux.it/~malattia/wiki/index.php/Sony_drivers
> S: Maintained
> -F: Documentation/laptops/sony-laptop.rst
> +F: Documentation/admin-guide/laptops/sony-laptop.rst
> F: drivers/char/sonypi.c
> F: drivers/platform/x86/sony-laptop.c
> F: include/linux/sony-laptop.h
> diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
> index 3a0f94929814..3e866885a405 100644
> --- a/drivers/char/Kconfig
> +++ b/drivers/char/Kconfig
> @@ -382,7 +382,7 @@ config SONYPI
> Device which can be found in many (all ?) Sony Vaio laptops.
>
> If you have one of those laptops, read
> - <file:Documentation/laptops/sonypi.rst>, and say Y or M here.
> + <file:Documentation/admin-guide/laptops/sonypi.rst>, and say Y or M here.
>
> To compile this driver as a module, choose M here: the
> module will be called sonypi.
> diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
> index 9d866b6753fe..430f7f619553 100644
> --- a/drivers/platform/x86/Kconfig
> +++ b/drivers/platform/x86/Kconfig
> @@ -451,7 +451,7 @@ config SONY_LAPTOP
> screen brightness control, Fn keys and allows powering on/off some
> devices.
>
> - Read <file:Documentation/laptops/sony-laptop.rst> for more information.
> + Read <file:Documentation/admin-guide/laptops/sony-laptop.rst> for more information.
>
> config SONYPI_COMPAT
> bool "Sonypi compatibility"
> @@ -503,7 +503,7 @@ config THINKPAD_ACPI
> support for Fn-Fx key combinations, Bluetooth control, video
> output switching, ThinkLight control, UltraBay eject and more.
> For more information about this driver see
> - <file:Documentation/laptops/thinkpad-acpi.rst> and
> + <file:Documentation/admin-guide/laptops/thinkpad-acpi.rst> and
> <http://ibm-acpi.sf.net/> .
>
> This driver was formerly known as ibm-acpi.
> --
> 2.21.0
>
--
With Best Regards,
Andy Shevchenko
^ permalink raw reply
* Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir
From: Mauro Carvalho Chehab @ 2019-06-20 2:24 UTC (permalink / raw)
To: Peter Zijlstra; +Cc: Linux Doc Mailing List, Jonathan Corbet, linux-kernel
In-Reply-To: <20190619212753.GQ3419@hirez.programming.kicks-ass.net>
Em Wed, 19 Jun 2019 23:27:53 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:
> On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> > (c/c list cleaned)
> >
> > Em Wed, 19 Jun 2019 13:43:56 +0200
> > Peter Zijlstra <peterz@infradead.org> escreveu:
> >
> > > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> > >
> > > > .../{ => driver-api}/atomic_bitops.rst | 2 -
> > >
> > > That's a .txt file, big fat NAK for making it an rst.
> >
> > Rst is a text file. This one is parsed properly by Sphinx without
> > any changes.
>
> In my tree it is a .txt file, I've not seen patches changing it. And I
> disagree, rst is just as much 'a text file' as .c is.
ReStructured text is just text with a stricter style + some commands,
if the text author wants to enhance it.
Btw, I'm glad you mentioned c.
This is c:
int
func( int a, int
b ) {
return a + b;
}
This is also c:
func(int a,int b) { goto foo;
foo:
return(a+b) }
K&R style is also c, and this is also c:
#define f(a,b) (a+b)
Despite none of the above matches my taste - and some have issues - they
all build with gcc.
Yet, none of the above follows the Kernel coding style.
The way we use ReST (with absolute minimal changes), it becomes just
a text style.
Btw, I agree with you: there are some odd things at its style - and we
should work to try to reduce this to its minimal extent.
>
> > > > .../{ => driver-api}/futex-requeue-pi.rst | 2 -
> > >
> > > > .../{ => driver-api}/gcc-plugins.rst | 2 -
> > >
> > > > Documentation/{ => driver-api}/kprobes.rst | 2 -
> > > > .../{ => driver-api}/percpu-rw-semaphore.rst | 2 -
> > >
> > > More NAK for rst conversion
> >
> > Again, those don't need any conversion. Those files already parse
> > as-is by Sphinx, with no need for any change.
>
> And yet, they're a .txt file in my tree. And I've not seen a rename,
> just this move.
Rename is on patch 1/22.
No matter the extension, all the above files pass at the Sphinx style
validation without warnings or errors. Patch 1/22 doesn't make any
conversion.
Btw, the .rst extension is just a convenient way to help identifying what
was not validated. If I'm not mistaken, when the discussions about a
replacement for DocBook started at at linux-doc, someone proposed to
keep the .txt extension (changing it to accept .rst, .txt or both is
a single line change at conf.py).
>
> > The only change here is that, on patch 1/22, the files that
> > aren't listed on an index file got a :orphan: added in order
> > to make this explicit. This patch removes it.
>
> I've no idea what :orphan: is. Text file don't have markup.
>
> > > > Documentation/{ => driver-api}/pi-futex.rst | 2 -
> > > > .../{ => driver-api}/preempt-locking.rst | 2 -
> > >
> > > > Documentation/{ => driver-api}/rbtree.rst | 2 -
> > >
> > > > .../{ => driver-api}/robust-futex-ABI.rst | 2 -
> > > > .../{ => driver-api}/robust-futexes.rst | 2 -
> > >
> > > > .../{ => driver-api}/speculation.rst | 8 +--
> > > > .../{ => driver-api}/static-keys.rst | 2 -
> > >
> > > > .../{ => driver-api}/this_cpu_ops.rst | 2 -
> > >
> > > > Documentation/locking/rt-mutex.rst | 2 +-
> > >
> > > NAK. None of the above have anything to do with driver-api.
> >
> > Ok. Where do you think they should sit instead? core-api?
>
> Pretty much all of then are core-api I tihnk, with exception of the one
> that are ABI, which have nothing to do with API.
OK.
> And i've no idea where
> GCC plugins go, but it's definitely nothing to do with drivers.
I suspect that Documentation/security would be a better place
for GCC plugins (as it has been discussed at kernel-hardening ML),
but I'm waiting a feedback from Kees.
>
> Many of the futex ones are about the sys_futex user API, which
> apparently we have Documentation/userspace-api/ for.
Yeah, it makes sense to place sys_futex there.
Despite being an old dir, it is not too popular: there are
very few document there. I only discovered this one a few
days ago.
>
> Why are you doing this if you've no clue what they're on about?
I don't pretend to know precisely where each document will fit.
If you read carefully the content of each orphaned document, you'll see
that many of them have uAPI, kAPI and admin-guide info inside.
To be frank, I actually tried to get rid of this document shift
part, but a Jon's feedback when I submitted a much simpler RFC
patchset challenged me to try to place each document on some place. The
renaming part is by far a lot more complex than the conversion,
because depending on how you interpret the file contents -
and the description of each documentation chapter - it may fit on a
different subdir.
-
My main goal is to have an organized body with the documentation.
Try to read our docs as if it is a book, and you'll see what I'm talking
about: there are important missing parts, the document order isn't in
an order that would make easier for the headers, several documents are
placed on random places, etc.
Just like we have Makefiles, the index.rst files, plus the subdirectories
help to classify and organize the documentation on a coherent way.
-
The main problem I want to address with this particular patch is that
there are so many random documents from all sorts of subject at
Documentation/*.txt that it makes really hard to see the document
structure or to organize them.
Also, keeping txt files there at the root doc dir is a bad idea, as
people keep flooding Documentation/ root with new unclassified documents
on almost every Kernel version.
After 5.1, there are two new documents added inside Documentation/*.txt
(I guess both added at linux-next for 5.3).
I proposed a few months ago to create a Documentation/staging, and do:
mv Documentation/*.txt Documentation/*.rst Documentation/staging
Jani proposed today something similar to it (Documentation/attic)
The name is not important. Having a place were we can temporarily
place documents while we organize the directory structure and the
documentation indexes seem to be the best way to reorganize the
docs on a coherent way.
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v5 00/18] kunit: introduce KUnit, the Linux kernel unit testing framework
From: Frank Rowand @ 2019-06-20 1:17 UTC (permalink / raw)
To: Brendan Higgins, gregkh, jpoimboe, keescook, kieran.bingham,
mcgrof, peterz, robh, sboyd, shuah, tytso, yamada.masahiro
Cc: devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg
In-Reply-To: <20190617082613.109131-1-brendanhiggins@google.com>
Hi Brendan,
I am only responding to this because you asked me to in the v4 thread.
Thank you for evaluating my comments in the v4 thread and asking me to
comment on v5
On 6/17/19 1:25 AM, Brendan Higgins wrote:
> ## TL;DR
>
> A not so quick follow-up to Stephen's suggestions on PATCH v4. Nothing
> that really changes any functionality or usage with the minor exception
> of a couple public functions that Stephen asked me to rename.
> Nevertheless, a good deal of clean up and fixes. See changes below.
>
> As for our current status, right now we got Reviewed-bys on all patches
> except:
>
> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> list
>
> However, it would probably be good to get reviews/acks from the
> subsystem maintainers on:
>
> - [PATCH v5 06/18] kbuild: enable building KUnit
> - [PATCH v5 08/18] objtool: add kunit_try_catch_throw to the noreturn
> list
> - [PATCH v5 15/18] Documentation: kunit: add documentation for KUnit
> - [PATCH v5 17/18] kernel/sysctl-test: Add null pointer test for
> sysctl.c:proc_dointvec()
> - [PATCH v5 18/18] MAINTAINERS: add proc sysctl KUnit test to PROC
> SYSCTL section
>
> Other than that, I think we should be good to go.
>
> One last thing, I updated the background to include my thoughts on KUnit
> vs. in kernel testing with kselftest in the background sections as
> suggested by Frank in the discussion on PATCH v2.
>
> ## Background
>
> This patch set proposes KUnit, a lightweight unit testing and mocking
> framework for the Linux kernel.
>
> Unlike Autotest and kselftest, KUnit is a true unit testing framework;
> it does not require installing the kernel on a test machine or in a VM
> (however, KUnit still allows you to run tests on test machines or in VMs
> if you want[1]) and does not require tests to be written in userspace
> running on a host kernel. Additionally, KUnit is fast: From invocation
> to completion KUnit can run several dozen tests in under a second.
> Currently, the entire KUnit test suite for KUnit runs in under a second
> from the initial invocation (build time excluded).
>
> KUnit is heavily inspired by JUnit, Python's unittest.mock, and
> Googletest/Googlemock for C++. KUnit provides facilities for defining
> unit test cases, grouping related test cases into test suites, providing
> common infrastructure for running tests, mocking, spying, and much more.
>
I looked only at this section, as was specifically requested:
> ### But wait! Doesn't kselftest support in kernel testing?!
>
> In a previous version of this patchset Frank pointed out that kselftest
> already supports writing a test that resides in the kernel using the
> test module feature[2]. LWN did a really great summary on this
> discussion here[3].
>
> Kselftest has a feature that allows a test module to be loaded into a
> kernel using the kselftest framework; this does allow someone to write
> tests against kernel code not directly exposed to userland; however, it
> does not provide much of a framework around how to structure the tests.
> The kselftest test module feature just provides a header which has a
> standardized way of reporting test failures,
> and then provides
> infrastructure to load and run the tests using the kselftest test
> harness.
The in-kernel tests can also be invoked at boot time if they are
configured (Kconfig) as in-kernel instead of as modules. I did not
check how many of the tests have tri-state configuration to allow
this, but the few that I looked at did.
>
> The kselftest test module does not seem to be opinionated at all in
> regards to how tests are structured, how they check for failures, how
> tests are organized. Even in the method it provides for reporting
> failures is pretty simple; it doesn't have any more advanced failure
> reporting or logging features. Given what's there, I think it is fair to
> say that it is not actually a framework, but a feature that makes it
> possible for someone to do some checks in kernel space.
I would call that description a little dismissive. The set of in-kernel
tests that I looked like followed a common pattern and reported results
in a uniform manner.
>
> Furthermore, kselftest test module has very few users. I checked for all
> the tests that use it using the following grep command:
>
> grep -Hrn -e 'kselftest_module\.h'
>
> and only got three results: lib/test_strscpy.c, lib/test_printf.c, and
> lib/test_bitmap.c.
You missed many tests. I listed much more than that in the v4 thread, and
someone else also listed more in the v4 thread.
>
> So despite kselftest test module's existence, there really is no feature
> overlap between kselftest and KUnit, save one: that you can use either
> to write an in-kernel test, but this is a very small feature in
> comparison to everything that KUnit allows you to do. KUnit is a full
> x-unit style unit testing framework, whereas kselftest looks a lot more
> like an end-to-end/functional testing framework, with a feature that
> makes it possible to write in-kernel tests.
The description does not give enough credit to what is in kselftest.
It does not matter whether KUnit provides additional things, relative
to kselftest. The point I was making is that there appears to be
_some_ overlap between kselftest and KUnit, and if there is overlap
then it is worth considering whether the overlap can be unified instead
of duplicated.
I don't have a dog in this fight and the discussion in the v4 thread
went way off track. Thus I am not going to get sucked back into a
pointless debate in this thread.
Thanks for adding this section to address the issue.
-Frank
>
> ### What's so special about unit testing?
>
> A unit test is supposed to test a single unit of code in isolation,
> hence the name. There should be no dependencies outside the control of
> the test; this means no external dependencies, which makes tests orders
> of magnitudes faster. Likewise, since there are no external dependencies,
> there are no hoops to jump through to run the tests. Additionally, this
> makes unit tests deterministic: a failing unit test always indicates a
> problem. Finally, because unit tests necessarily have finer granularity,
> they are able to test all code paths easily solving the classic problem
> of difficulty in exercising error handling code.
>
> ### Is KUnit trying to replace other testing frameworks for the kernel?
>
> No. Most existing tests for the Linux kernel are end-to-end tests, which
> have their place. A well tested system has lots of unit tests, a
> reasonable number of integration tests, and some end-to-end tests. KUnit
> is just trying to address the unit test space which is currently not
> being addressed.
>
> ### More information on KUnit
>
> There is a bunch of documentation near the end of this patch set that
> describes how to use KUnit and best practices for writing unit tests.
> For convenience I am hosting the compiled docs here[4].
>
> Additionally for convenience, I have applied these patches to a
> branch[5]. The repo may be cloned with:
> git clone https://kunit.googlesource.com/linux
> This patchset is on the kunit/rfc/v5.2-rc4/v5 branch.
>
> ## Changes Since Last Version
>
> Aside from a couple public function renames, there isn't really anything
> in here that changes any functionality.
>
> - Went through and fixed a couple of anti-patterns suggested by Stephen
> Boyd. Things like:
> - Dropping an else clause at the end of a function.
> - Dropping the comma on the closing sentinel, `{}`, of a list.
> - Inlines a bunch of functions in the test case running logic in patch
> 01/18 to make it more readable as suggested by Stephen Boyd
> - Found and fixed bug in resource deallocation logic in patch 02/18. Bug
> was discovered as a result of making a change suggested by Stephen
> Boyd. This does not substantially change how any of the code works
> conceptually.
> - Renamed new_string_stream() to alloc_string_stream() as suggested by
> Stephen Boyd.
> - Made string-stream a KUnit managed object - based on a suggestion made
> by Stephen Boyd.
> - Renamed kunit_new_stream() to alloc_kunit_stream() as suggested by
> Stephen Boyd.
> - Removed the ability to set log level after allocating a kunit_stream,
> as suggested by Stephen Boyd.
>
> [1] https://google.github.io/kunit-docs/third_party/kernel/docs/usage.html#kunit-on-non-uml-architectures
> [2] https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html#test-module
> [3] https://lwn.net/Articles/790235/
> [4] https://google.github.io/kunit-docs/third_party/kernel/docs/
> [5] https://kunit.googlesource.com/linux/+/kunit/rfc/v5.2-rc4/v5
>
^ permalink raw reply
* Re: [PATCH v5 01/18] kunit: test: add KUnit test runner core
From: Stephen Boyd @ 2019-06-20 0:15 UTC (permalink / raw)
To: Brendan Higgins, frowand.list, gregkh, jpoimboe, keescook,
kieran.bingham, mcgrof, peterz, robh, shuah, tytso,
yamada.masahiro
Cc: devicetree, dri-devel, kunit-dev, linux-doc, linux-fsdevel,
linux-kbuild, linux-kernel, linux-kselftest, linux-nvdimm,
linux-um, Alexander.Levin, Tim.Bird, amir73il, dan.carpenter,
daniel, jdike, joel, julia.lawall, khilman, knut.omang, logang,
mpe, pmladek, rdunlap, richard, rientjes, rostedt, wfg,
Brendan Higgins
In-Reply-To: <20190617082613.109131-2-brendanhiggins@google.com>
Quoting Brendan Higgins (2019-06-17 01:25:56)
> diff --git a/kunit/test.c b/kunit/test.c
> new file mode 100644
> index 0000000000000..d05d254f1521f
> --- /dev/null
> +++ b/kunit/test.c
> @@ -0,0 +1,210 @@
> +// SPDX-License-Identifier: GPL-2.0
> +/*
> + * Base unit test (KUnit) API.
> + *
> + * Copyright (C) 2019, Google LLC.
> + * Author: Brendan Higgins <brendanhiggins@google.com>
> + */
> +
> +#include <linux/sched/debug.h>
> +#include <kunit/test.h>
> +
> +static bool kunit_get_success(struct kunit *test)
> +{
> + unsigned long flags;
> + bool success;
> +
> + spin_lock_irqsave(&test->lock, flags);
> + success = test->success;
> + spin_unlock_irqrestore(&test->lock, flags);
I still don't understand the locking scheme in this code. Is the
intention to make getter and setter APIs that are "safe" by adding in a
spinlock that is held around getting and setting various members in the
kunit structure?
In what situation is there more than one thread reading or writing the
kunit struct? Isn't it only a single process that is going to be
operating on this structure? And why do we need to disable irqs? Are we
expecting to be modifying the unit tests from irq contexts?
> +
> + return success;
> +}
> +
> +static void kunit_set_success(struct kunit *test, bool success)
> +{
> + unsigned long flags;
> +
> + spin_lock_irqsave(&test->lock, flags);
> + test->success = success;
> + spin_unlock_irqrestore(&test->lock, flags);
> +}
> +
> +static int kunit_vprintk_emit(int level, const char *fmt, va_list args)
> +{
> + return vprintk_emit(0, level, NULL, 0, fmt, args);
> +}
> +
> +static int kunit_printk_emit(int level, const char *fmt, ...)
> +{
> + va_list args;
> + int ret;
> +
> + va_start(args, fmt);
> + ret = kunit_vprintk_emit(level, fmt, args);
> + va_end(args);
> +
> + return ret;
> +}
> +
> +static void kunit_vprintk(const struct kunit *test,
> + const char *level,
> + struct va_format *vaf)
> +{
> + kunit_printk_emit(level[1] - '0', "\t# %s: %pV", test->name, vaf);
> +}
> +
> +static bool kunit_has_printed_tap_version;
Can you please move this into function local scope in the function
below?
> +
> +static void kunit_print_tap_version(void)
> +{
> + if (!kunit_has_printed_tap_version) {
> + kunit_printk_emit(LOGLEVEL_INFO, "TAP version 14\n");
> + kunit_has_printed_tap_version = true;
> + }
> +}
> +
[...]
> +
> +static bool kunit_module_has_succeeded(struct kunit_module *module)
> +{
> + const struct kunit_case *test_case;
> + bool success = true;
> +
> + for (test_case = module->test_cases; test_case->run_case; test_case++)
> + if (!test_case->success) {
> + success = false;
> + break;
Why not 'return false'?
> + }
> +
> + return success;
And 'return true'?
> +}
> +
> +static size_t kunit_module_counter = 1;
> +
> +static void kunit_print_subtest_end(struct kunit_module *module)
> +{
> + kunit_print_ok_not_ok(false,
> + kunit_module_has_succeeded(module),
> + kunit_module_counter++,
> + module->name);
> +}
> +
> +static void kunit_print_test_case_ok_not_ok(struct kunit_case *test_case,
> + size_t test_number)
> +{
> + kunit_print_ok_not_ok(true,
> + test_case->success,
> + test_number,
> + test_case->name);
> +}
> +
> +void kunit_init_test(struct kunit *test, const char *name)
> +{
> + spin_lock_init(&test->lock);
> + test->name = name;
> + test->success = true;
> +}
> +
> +/*
> + * Performs all logic to run a test case.
> + */
> +static void kunit_run_case(struct kunit_module *module,
> + struct kunit_case *test_case)
> +{
> + struct kunit test;
> + int ret = 0;
> +
> + kunit_init_test(&test, test_case->name);
> +
> + if (module->init) {
> + ret = module->init(&test);
> + if (ret) {
> + kunit_err(&test, "failed to initialize: %d\n", ret);
> + kunit_set_success(&test, false);
> + return;
> + }
> + }
> +
> + if (!ret)
> + test_case->run_case(&test);
Do we need this if condition? ret can only be set to non-zero above but
then we'll exit the function early so it seems unnecessary. Given that,
ret should probably be moved into the module->init path.
> +
> + if (module->exit)
> + module->exit(&test);
> +
> + test_case->success = kunit_get_success(&test);
> +}
> +
^ 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