From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>,
"Jonathan Corbet" <corbet@lwn.net>,
"Mauro Carvalho Chehab" <mchehab+huawei@kernel.org>,
"peterz@infradead.org" <peterz@infradead.org>,
Andrew Morton <akpm@linux-foundation.org>,
Changbin Du <changbin.du@intel.com>,
Krzysztof Kozlowski <krzk@kernel.org>,
Masahiro Yamada <masahiroy@kernel.org>,
Peter Enderborg <peter.enderborg@sony.com>,
Randy Dunlap <rdunlap@infradead.org>,
linux-kernel@vger.kernel.org
Subject: [PATCH 25/33] docs: Kconfig/Makefile: add a check for broken ABI files
Date: Wed, 28 Oct 2020 15:23:23 +0100 [thread overview]
Message-ID: <f97df0ea6dd59cf5fe1655c71eb34af71c67d20c.1603893146.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1603893146.git.mchehab+huawei@kernel.org>
From: Mauro Carvalho Chehab <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>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/Kconfig | 10 ++++++++++
Documentation/Makefile | 5 +++++
lib/Kconfig.debug | 2 ++
scripts/get_abi.pl | 14 +++++++++++---
4 files changed, 28 insertions(+), 3 deletions(-)
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index 66046fa1c341..e549a61f4d96 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS
If unsure, select 'N'.
+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 4e47dff8b315..61a7310b49e0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -10,6 +10,11 @@ ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
$(shell $(srctree)/scripts/documentation-file-ref-check --warn)
endif
+# 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 d7a7bc3b6098..c789b39ed527 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2446,4 +2446,6 @@ config HYPERV_TESTING
endmenu # "Kernel Testing and Coverage"
+source "Documentation/Kconfig"
+
endmenu # Kernel hacking
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 3cff7cdf1397..413349789145 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -50,7 +50,15 @@ my %symbols;
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";
+ }
}
#
@@ -110,7 +118,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";
}
@@ -225,7 +233,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+// if ($data{$nametag}->{description});
if ($what) {
--
2.26.2
next prev parent reply other threads:[~2020-10-29 1:01 UTC|newest]
Thread overview: 58+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-28 14:22 [PATCH 00/33] ABI: add it to the documentation build system Mauro Carvalho Chehab
2020-10-28 14:22 ` [PATCH 01/33] scripts: get_abi.pl: change script to allow parsing in ReST mode Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 02/33] scripts: get_abi.pl: fix parsing on " Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 03/33] scripts: get_abi.pl: Allow optionally record from where a line came from Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 04/33] scripts: get_abi.pl: improve its parser to better catch up indentation Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 05/33] scripts: get_abi.pl: cleanup ABI cross-reference logic Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 06/33] scripts: get_abi.pl: detect duplicated ABI definitions Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 07/33] scripts: get_abi.pl: output users in ReST format Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 08/33] scripts: get_abi.pl: prevent duplicated file names Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 09/33] scripts: get_abi.pl: use bold font for ABI definitions Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 10/33] scripts: get_abi.pl: auto-generate cross references Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 11/33] docs: kernellog.py: add support for info() Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 12/33] docs: kernel_abi.py: add a script to parse ABI documentation Mauro Carvalho Chehab
2020-10-28 16:21 ` Jonathan Corbet
2020-10-28 17:02 ` Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 13/33] docs: kernel_abi.py: fix UTF-8 support Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 14/33] docs: kernel_abi.py: make it compatible with Sphinx 1.7+ Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 15/33] docs: kernel_abi.py: use --enable-lineno for get_abi.pl Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 16/33] docs: kernel_abi.py: Handle with a lazy Sphinx parser Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 17/33] docs: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 18/33] docs: ABI: README: specify that files should be ReST compatible Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 19/33] docs: ABI: stable: make files " Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 20/33] docs: ABI: testing: make the files compatible with ReST output Mauro Carvalho Chehab
2020-10-28 17:44 ` Richard Cochran
2020-10-29 7:21 ` Mauro Carvalho Chehab
2020-10-29 14:49 ` Jonathan Cameron
2020-10-30 7:11 ` Mauro Carvalho Chehab
2020-11-02 15:06 ` Gautham R Shenoy
2020-10-28 14:23 ` [PATCH 21/33] docs: ABI: make it parse ABI/stable as ReST-compatible files Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 22/33] docs: ABI: create a 2-depth index for ABI Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 23/33] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed Mauro Carvalho Chehab
2020-11-05 13:56 ` Linus Walleij
2020-10-28 14:23 ` [PATCH 24/33] docs: abi-testing.rst: enable --rst-sources when building docs Mauro Carvalho Chehab
2020-10-28 14:23 ` Mauro Carvalho Chehab [this message]
2020-10-28 14:23 ` [PATCH 26/33] docs: ABI: convert testing/configfs-acpi to ReST Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 27/33] docs: ABI: fix syntax to be parsed using ReST notation Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 28/33] docs: ABI: vdso: use the right format for ABI Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 29/33] docs: ABI: sysfs-bus-nvdimm: " Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 30/33] docs: ABI: cleanup several ABI documents Mauro Carvalho Chehab
2020-10-29 14:42 ` Jonathan Cameron
2020-10-29 15:29 ` kajoljain
2020-10-29 16:14 ` Oded Gabbay
2020-10-29 14:54 ` Tom Rix
2020-10-30 6:33 ` Vaibhav Jain
2020-10-30 7:52 ` Jinpu Wang
2020-11-03 15:24 ` Bjorn Andersson
2020-10-28 14:23 ` [PATCH 31/33] docs: ABI: change read/write attributes Mauro Carvalho Chehab
2020-10-28 14:23 ` [PATCH 32/33] docs: ABI: stable: remove a duplicated documentation Mauro Carvalho Chehab
2020-10-28 14:57 ` Wei Liu
2020-10-28 14:23 ` [PATCH 33/33] docs: ABI: unify /sys/class/leds/<led>/max_brightness documentation Mauro Carvalho Chehab
2020-10-29 17:16 ` Pavel Machek
2020-10-29 22:11 ` Jacek Anaszewski
2020-10-28 14:39 ` [PATCH 00/33] ABI: add it to the documentation build system Greg Kroah-Hartman
2020-10-28 15:10 ` Mauro Carvalho Chehab
2020-10-28 14:43 ` Greg Kroah-Hartman
2020-10-28 16:22 ` Jonathan Corbet
2020-10-28 16:54 ` Greg Kroah-Hartman
2020-10-29 9:07 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f97df0ea6dd59cf5fe1655c71eb34af71c67d20c.1603893146.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=akpm@linux-foundation.org \
--cc=changbin.du@intel.com \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=krzk@kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=masahiroy@kernel.org \
--cc=mchehab+samsung@kernel.org \
--cc=peter.enderborg@sony.com \
--cc=peterz@infradead.org \
--cc=rdunlap@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®