From 91f950e8b9d8419d72e9f06250b6471cdfd534d7 Mon Sep 17 00:00:00 2001 From: Yujie Liu Date: Thu, 19 Oct 2023 17:56:37 +0800 Subject: scripts/kernel-doc: match -Werror flag strictly In our CI testing, we use some commands as below to only turn a specific type of warnings into errors, but we notice that kernel-doc warnings are also turned into errors unexpectedly. $ make KCFLAGS="-Werror=return-type" W=1 kernel/fork.o kernel/fork.c:1406: warning: Function parameter or member 'mm' not described in 'set_mm_exe_file' kernel/fork.c:1406: warning: Function parameter or member 'new_exe_file' not described in 'set_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'mm' not described in 'replace_mm_exe_file' kernel/fork.c:1441: warning: Function parameter or member 'new_exe_file' not described in 'replace_mm_exe_file' kernel/fork.c:1491: warning: Function parameter or member 'mm' not described in 'get_mm_exe_file' kernel/fork.c:1510: warning: Function parameter or member 'task' not described in 'get_task_exe_file' kernel/fork.c:1534: warning: Function parameter or member 'task' not described in 'get_task_mm' kernel/fork.c:2109: warning: bad line: kernel/fork.c:2130: warning: Function parameter or member 'ret' not described in '__pidfd_prepare' kernel/fork.c:2130: warning: Excess function parameter 'pidfd' description in '__pidfd_prepare' kernel/fork.c:2179: warning: Function parameter or member 'ret' not described in 'pidfd_prepare' kernel/fork.c:2179: warning: Excess function parameter 'pidfd' description in 'pidfd_prepare' kernel/fork.c:3195: warning: expecting prototype for clone3(). Prototype was for sys_clone3() instead 13 warnings as Errors make[3]: *** [scripts/Makefile.build:243: kernel/fork.o] Error 13 make[3]: *** Deleting file 'kernel/fork.o' make[2]: *** [scripts/Makefile.build:480: kernel] Error 2 make[1]: *** [/root/linux/Makefile:1913: .] Error 2 make: *** [Makefile:234: __sub-make] Error 2 >From the git history, commit 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") introduces a new command-line option to make kernel-doc warnings into errors. It can also read the KCFLAGS environment variable to decide whether to turn this option on, but the regex used for matching may not be accurate enough. It can match both "-Werror" and "-Werror=", so the option is turned on by mistake in the latter case. Fix this by strictly matching the flag "-Werror": there must be a space or start of string in the front, and a space or end of string at the end. This can handle all the following cases correctly: KCFLAGS="-Werror" make W=1 [MATCH] KCFLAGS="-Werror=return-type" make W=1 [NO MATCH] KCFLAGS="-Wcomment -Werror -Wundef" make W=1 [MATCH] KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 [NO MATCH] Fixes: 2c12c8103d8f ("scripts/kernel-doc: optionally treat warnings as errors") Signed-off-by: Yujie Liu Signed-off-by: Jonathan Corbet Message-ID: <20231019095637.2471840-1-yujie.liu@intel.com> --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 6e199a745ccb..d660e1f4b483 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -185,7 +185,7 @@ if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') { if (defined($ENV{'KCFLAGS'})) { my $kcflags = "$ENV{'KCFLAGS'}"; - if ($kcflags =~ /Werror/) { + if ($kcflags =~ /(?<=^|\s)-Werror(?=$|\s)/) { $Werror = 1; } } -- cgit v1.2.3 From cf63348b4c45384d02126f86676d5afc75d661a7 Mon Sep 17 00:00:00 2001 From: Yujie Liu Date: Mon, 30 Oct 2023 16:54:04 +0800 Subject: scripts/kernel-doc: Fix the regex for matching -Werror flag Swarup reported a "make htmldocs" warning: Variable length lookbehind is experimental in regex; marked by <-- HERE in m/(?<=^|\s)-Werror(?=$|\s) <-- HERE / at ./scripts/kernel-doc line 188. Akira managed to reproduce it by perl v5.34.0. On second thought, it is not necessary to have the complicated "lookahead and lookbehind" things, and the regex can be simplified. Generally, the kernel-doc warnings should be considered as errors only when "-Werror" flag is set in KCFLAGS, but not when "-Werror=" is set, which means there needs to be a space or start of string before "-Werror", and a space or end of string after "-Werror". The following cases have been tested to work as expected: * kernel-doc warnings are considered as errors: $ KCFLAGS="-Werror" make W=1 $ KCFLAGS="-Wcomment -Werror" make W=1 $ KCFLAGS="-Werror -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror -Wundef" make W=1 * kernel-doc warnings remain as warnings: $ KCFLAGS="-Werror=return-type" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type" make W=1 $ KCFLAGS="-Werror=return-type -Wundef" make W=1 $ KCFLAGS="-Wcomment -Werror=return-type -Wundef" make W=1 The "Variable length lookbehind is experimental in regex" warning is also resolved by this patch. Fixes: 91f950e8b9d8 ("scripts/kernel-doc: match -Werror flag strictly") Reported-by: Swarup Laxman Kotiaklapudi Signed-off-by: Yujie Liu Closes: https://lore.kernel.org/r/20231028182231.123996-1-swarupkotikalapudi@gmail.com/ Reviewed-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231030085404.3343403-1-yujie.liu@intel.com --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d660e1f4b483..08a3e603db19 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -185,7 +185,7 @@ if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') { if (defined($ENV{'KCFLAGS'})) { my $kcflags = "$ENV{'KCFLAGS'}"; - if ($kcflags =~ /(?<=^|\s)-Werror(?=$|\s)/) { + if ($kcflags =~ /(\s|^)-Werror(\s|$)/) { $Werror = 1; } } -- cgit v1.2.3 From aeb9ce058d7c6193dc41e06b3a5b29d22c446b14 Mon Sep 17 00:00:00 2001 From: Coco Li Date: Wed, 29 Nov 2023 07:27:53 +0000 Subject: cache: enforce cache groups Set up build time warnings to safeguard against future header changes of organized structs. Warning includes: 1) whether all variables are still in the same cache group 2) whether all the cache groups have the sum of the members size (in the maximum condition, including all members defined in configs) The __cache_group* variables are ignored in kernel-doc check in the various header files they appear in to enforce the cache groups. Suggested-by: Daniel Borkmann Acked-by: Daniel Borkmann Signed-off-by: Coco Li Reviewed-by: Eric Dumazet Reviewed-by: Shakeel Butt Signed-off-by: David S. Miller --- scripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 08a3e603db19..0a890fe4d22b 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1592,6 +1592,11 @@ sub push_parameter($$$$$) { $parameterdescs{$param} = "anonymous\n"; $anon_struct_union = 1; } + elsif ($param =~ "__cacheline_group" ) + # handle cache group enforcing variables: they do not need be described in header files + { + return; # ignore __cacheline_group_begin and __cacheline_group_end + } # warn if parameter has no description # (but ignore ones starting with # as these are not parameters -- cgit v1.2.3 From b77fdd6a48e60a0ed1865edbe6d9bf0538551f85 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 13 Dec 2023 23:02:00 -0800 Subject: scripts/kernel-doc: restore warning for Excess struct/union The warning for Excess struct or union member description was removed when the $nested parameter of check_sections() was removed. This causes some kernel-doc notation warnings to be missed. Recently the kernel test robot somehow reported an Excess member. The code in kernel-doc has not issued that warning since kernel v4.16, so I don't know how the robot did it. (See the Link for the report.) drivers/net/wireless/intel/iwlwifi/fw/dbg.c:86: warning: Excess struct/union/enum/typedef member 'trans_len' description in 'iwl_fw_dump_ptrs' I patched that warning away even though I could not reproduce the warning from kernel-doc. The warning should be issued for extraneous struct member or union member description, so restore it. Fixes: 1081de2d2f91 ("scripts: kernel-doc: get rid of $nested parameter") Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/ Cc: Mauro Carvalho Chehab Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231214070200.24405-1-rdunlap@infradead.org --- scripts/kernel-doc | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 08a3e603db19..cb1af401d3ff 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1654,6 +1654,13 @@ sub check_sections($$$$$) { "'$sects[$sx]' " . "description in '$decl_name'\n"); } + elsif (($decl_type eq "struct") or + ($decl_type eq "union")) { + emit_warning("${file}:$.", + "Excess $decl_type member " . + "'$sects[$sx]' " . + "description in '$decl_name'\n"); + } } } } -- cgit v1.2.3 From 0c3ebff535956d2718594dc90aa9cc87521ec9fd Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 14 Dec 2023 16:15:13 -0800 Subject: scripts: kernel-doc: Clarify missing struct member description The output "or member" should be more specific, instead saying "struct member". Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215001513.work.563-kees@kernel.org --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb1af401d3ff..df158c3a9abc 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1601,7 +1601,7 @@ sub push_parameter($$$$$) { $parameterdescs{$param} = $undescribed; if (show_warnings($type, $declaration_name) && $param !~ /\./) { - emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n"); + emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n"); } } -- cgit v1.2.3 From f600c77aeaff6e59806d7eef9ac269a7c1a6d817 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 18 Dec 2023 17:18:08 -0700 Subject: docs: ignore __counted_by attribute in structure definitions kernel-doc appeared to ignore __counted_by, but appearances can be deceiving; it caused member names to not be recognized, which manifested as a number of spurious "Excess struct member" warnings. Filter that attribute out and reduce the warning onslaught slightly. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index df158c3a9abc..6acc39c56ac3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1143,6 +1143,7 @@ sub dump_struct($$) { # strip attributes $members =~ s/\s*$attribute/ /gi; $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; + $members =~ s/\s*__counted_by\s*\([^;]*\)/ /gos; $members =~ s/\s*__packed\s*/ /gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; -- cgit v1.2.3 From dcd39fa2be95efd5cbce74661151f68510cb67fe Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Fri, 15 Dec 2023 17:03:41 +0200 Subject: kernel-doc: Align quick help and the code The update to the quick help mentions -Wshort-description, but code never supported for that. Align that with the code by allowing both: -Wshort-description and -Wshort-desc. Fixes: 56b0f453db74 ("kernel-doc: don't let V=1 change outcome") Signed-off-by: Andy Shevchenko Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215150341.1996720-1-andriy.shevchenko@linux.intel.com --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 6acc39c56ac3..3cdc7dba37e3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -23,7 +23,7 @@ kernel-doc - Print formatted kernel documentation to stdout =head1 SYNOPSIS - kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-description] [-Wcontents-before-sections] + kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections] [ -man | -rst [-sphinx-version VERSION] [-enable-lineno] | -none @@ -328,7 +328,7 @@ while ($ARGV[0] =~ m/^--?(.*)/) { $Werror = 1; } elsif ($cmd eq "Wreturn") { $Wreturn = 1; - } elsif ($cmd eq "Wshort-desc") { + } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") { $Wshort_desc = 1; } elsif ($cmd eq "Wcontents-before-sections") { $Wcontents_before_sections = 1; -- cgit v1.2.3 From afa751e84c30b517aebd418970d222c39c81acb8 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Mon, 25 Dec 2023 22:52:19 -0800 Subject: kernel-doc: handle a void function without producing a warning Currently a void function can produce a warning: main.c:469: warning: contents before sections This one is from arch/x86/kernel/cpu/sgx/main.c (which is not included in any produced kernel documentation output). Handle this by setting $in_doc_sect to 1 whenever any recognized document section name is processed. Fixes: f624adef3d0b ("kernel-doc: limit the "section header:" detection to a select few") Signed-off-by: Randy Dunlap Cc: Jani Nikula Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231226065219.319-1-rdunlap@infradead.org --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3cdc7dba37e3..3ecdab5ca612 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2121,6 +2121,7 @@ sub process_body($$) { } if (/$doc_sect/i) { # case insensitive for supported section names + $in_doc_sect = 1; $newsection = $1; $newcontents = $2; -- cgit v1.2.3