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 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 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 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 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 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