In addition to #ifdef, #define and #endif, also handle
any #if since we may be using e.g. #if IS_ENABLED(...).
I didn't find any instances of this in the kernel now,
there are enums with such ifs inside, but I didn't find
any with kernel-doc as well. However, it came up as we
were adding such a construct in our driver and warnings
from kernel-doc were the result.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240214142937.80ee86a3beae.Ibcc5bd97a20cd10a792663e4b254cd46c7e8b520@changeid
Set 'softtabstop' to 4 spaces, which will hopefully help keep the
indentation in this file consistent going forwards.
This mirrors the modeline in scripts such as recordmcount.pl, ktest.pl,
and others.
Emacs seems to use 4 spaces to indent by default, so it doesn't require
anything special here.
No functional change.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240215134828.1277109-2-vegard.nossum@oracle.com
This file is using an ungodly mixture of 4 spaces, 2-wide tabs, 4-wide
tabs, _and_ 8-wide tabs, making it really hard to find good editor
settings for working with this file.
Bite the bullet and reindent it by hand. I tried using both perltidy
and vim, but neither of them were up to the task without changing too
much or getting confused about what they were supposed to be doing.
I did change a few instances of
}
else
into
} else
(and same for elsif); the file is again written using both styles, and
I left functions which already seemed self-consistent alone.
You can verify that this commit only changes whitespace using e.g.:
git diff --ignore-all-space --word-diff
or to see (only) the instances where newlines were added/removed:
git diff --ignore-all-space
You can also see the delta from what perltidy would have wanted to
do to this file (when asked to only indent it), which isn't that much
in the end:
perltidy -io -fnl scripts/kernel-doc
git diff --no-index scripts/kernel-doc{,.tdy}
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240208161705.888385-1-vegard.nossum@oracle.com
Pull documentation update from Jonathan Corbet:
"Another moderately busy cycle for documentation, including:
- The minimum Sphinx requirement has been raised to 2.4.4, following
a warning that was added in 6.2
- Some reworking of the Documentation/process front page to,
hopefully, make it more useful
- Various kernel-doc tweaks to, for example, make it deal properly
with __counted_by annotations
- We have also restored a warning for documentation of nonexistent
structure members that disappeared a while back. That had the
delightful consequence of adding some 600 warnings to the docs
build. A sustained effort by Randy, Vegard, and myself has
addressed almost all of those, bringing the documentation back into
sync with the code. The fixes are going through the appropriate
maintainer trees
- Various improvements to the HTML rendered docs, including automatic
links to Git revisions and a nice new pulldown to make translations
easy to access
- Speaking of translations, more of those for Spanish and Chinese
... plus the usual stream of documentation updates and typo fixes"
* tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits)
MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL
A reworked process/index.rst
ring-buffer/Documentation: Add documentation on buffer_percent file
Translated the RISC-V architecture boot documentation.
Docs: remove mentions of fdformat from util-linux
Docs/zh_CN: Fix the meaning of DEBUG to pr_debug()
Documentation: move driver-api/dcdbas to userspace-api/
Documentation: move driver-api/isapnp to userspace-api/
Documentation/core-api : fix typo in workqueue
Documentation/trace: Fixed typos in the ftrace FLAGS section
kernel-doc: handle a void function without producing a warning
scripts/get_abi.pl: ignore some temp files
docs: kernel_abi.py: fix command injection
scripts/get_abi: fix source path leak
CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer
docs: translations: add translations links when they exist
kernel-doc: Align quick help and the code
MAINTAINERS: add reviewer for Spanish translations
docs: ignore __counted_by attribute in structure definitions
scripts: kernel-doc: Clarify missing struct member description
..
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 <corbet@lwn.net>
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: 1081de2d2f ("scripts: kernel-doc: get rid of $nested parameter")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/all/202312060810.QT9zourt-lkp@intel.com/
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231214070200.24405-1-rdunlap@infradead.org
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 <daniel@iogearbox.net>
Acked-by: Daniel Borkmann <daniel@iogearbox.net>
Signed-off-by: Coco Li <lixiaoyan@google.com>
Reviewed-by: Eric Dumazet <edumazet@google.com>
Reviewed-by: Shakeel Butt <shakeelb@google.com>
Signed-off-by: David S. Miller <davem@davemloft.net>
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=<diagnostic-type>" 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: 91f950e8b9 ("scripts/kernel-doc: match -Werror flag strictly")
Reported-by: Swarup Laxman Kotiaklapudi <swarupkotikalapudi@gmail.com>
Signed-off-by: Yujie Liu <yujie.liu@intel.com>
Closes: https://lore.kernel.org/r/20231028182231.123996-1-swarupkotikalapudi@gmail.com/
Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231030085404.3343403-1-yujie.liu@intel.com
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 2c12c8103d ("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=<diagnostic-type>", 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: 2c12c8103d ("scripts/kernel-doc: optionally treat warnings as errors")
Signed-off-by: Yujie Liu <yujie.liu@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20231019095637.2471840-1-yujie.liu@intel.com>
drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to
initialize the enum enumerators:
enum idpf_cap_field {
IDPF_BASE_CAPS = -1,
IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities,
csum_caps),
IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities,
seg_caps),
IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities,
rss_caps),
IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities,
hsplit_caps),
IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities,
rsc_caps),
IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities,
other_caps),
};
kernel-doc parses the above enumerator with a ',' inside the
macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators
resulting in the warnings:
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'csum_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'seg_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rss_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'hsplit_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rsc_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'other_caps' not described in enum 'idpf_cap_field'
Fix it by removing the macro arguments within the parentheses.
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230815210417.98749-3-pavan.kumar.linga@intel.com
At present, if the macros DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
below, instead of parsing the parameter in the parentheses,
kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and
'DEFINE_DMA_UNMAP_LEN(' which results in the following
warnings:
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in
'idpf_tx_buf'
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in
'idpf_tx_buf'
struct idpf_tx_buf {
DEFINE_DMA_UNMAP_ADDR(dma);
DEFINE_DMA_UNMAP_LEN(len);
};
Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN().
Cc: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230815210417.98749-2-pavan.kumar.linga@intel.com
Pull mode documentation updates from Jonathan Corbet:
"A half-dozen late arriving docs patches. They are mostly fixes, but we
also have a kernel-doc tweak for enums and the long-overdue removal of
the outdated and redundant patch-submission comments at the top of the
MAINTAINERS file"
* tag 'docs-6.5-2' of git://git.lwn.net/linux:
scripts: kernel-doc: support private / public marking for enums
Documentation: KVM: SEV: add a missing backtick
Documentation: ACPI: fix typo in ssdt-overlays.rst
Fix documentation of panic_on_warn
docs: remove the tips on how to submit patches from MAINTAINERS
docs: fix typo in zh_TW and zh_CN translation
Pull Kbuild updates from Masahiro Yamada:
- Remove the deprecated rule to build *.dtbo from *.dts
- Refactor section mismatch detection in modpost
- Fix bogus ARM section mismatch detections
- Fix error of 'make gtags' with O= option
- Add Clang's target triple to KBUILD_CPPFLAGS to fix a build error
with the latest LLVM version
- Rebuild the built-in initrd when KBUILD_BUILD_TIMESTAMP is changed
- Ignore more compiler-generated symbols for kallsyms
- Fix 'make local*config' to handle the ${CONFIG_FOO} form in Makefiles
- Enable more kernel-doc warnings with W=2
- Refactor <linux/export.h> by generating KSYMTAB data by modpost
- Deprecate <asm/export.h> and <asm-generic/export.h>
- Remove the EXPORT_DATA_SYMBOL macro
- Move the check for static EXPORT_SYMBOL back to modpost, which makes
the build faster
- Re-implement CONFIG_TRIM_UNUSED_KSYMS with one-pass algorithm
- Warn missing MODULE_DESCRIPTION when building modules with W=1
- Make 'make clean' robust against too long argument error
- Exclude more objects from GCOV to fix CFI failures with GCOV
- Allow 'make modules_install' to install modules.builtin and
modules.builtin.modinfo even when CONFIG_MODULES is disabled
- Include modules.builtin and modules.builtin.modinfo in the
linux-image Debian package even when CONFIG_MODULES is disabled
- Revive "Entering directory" logging for the latest Make version
* tag 'kbuild-v6.5' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: (72 commits)
modpost: define more R_ARM_* for old distributions
kbuild: revive "Entering directory" for Make >= 4.4.1
kbuild: set correct abs_srctree and abs_objtree for package builds
scripts/mksysmap: Ignore prefixed KCFI symbols
kbuild: deb-pkg: remove the CONFIG_MODULES check in buildeb
kbuild: builddeb: always make modules_install, to install modules.builtin*
modpost: continue even with unknown relocation type
modpost: factor out Elf_Sym pointer calculation to section_rel()
modpost: factor out inst location calculation to section_rel()
kbuild: Disable GCOV for *.mod.o
kbuild: Fix CFI failures with GCOV
kbuild: make clean rule robust against too long argument error
script: modpost: emit a warning when the description is missing
kbuild: make modules_install copy modules.builtin(.modinfo)
linux/export.h: rename 'sec' argument to 'license'
modpost: show offset from symbol for section mismatch warnings
modpost: merge two similar section mismatch warnings
kbuild: implement CONFIG_TRIM_UNUSED_KSYMS without recursion
modpost: use null string instead of NULL pointer for default namespace
modpost: squash sym_update_namespace() into sym_add_exported()
...
The kernel-doc script currently reports a number of issues
only in "verbose" mode, but that's initialized from V=1
(via KBUILD_VERBOSE), so if you use KDOC_WERROR=1 then
adding V=1 might actually break the build. This is rather
unexpected.
Change kernel-doc to not change its behaviour wrt. errors
(or warnings) when verbose mode is enabled, but rather add
separate warning flags (and -Wall) for it. Allow enabling
those flags via environment/make variables in the kernel's
build system for easier user use, but to not have to parse
them in the script itself.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
In some cases we'd like to indicate the bitwise negation of a parameter,
e.g.
~@var
This will be helpful for describing the atomic andnot operations, where
we'd like to write comments of the form:
Atomically updates @v to (@v & ~@i)
Which kernel-doc currently transforms to:
Atomically updates **v** to (**v** & ~**i**)
Rather than the preferable form:
Atomically updates **v** to (**v** & **~i**)
This is similar to what we did for '!@var' in commit:
ee2aa75903 ("scripts: kernel-doc: accept negation like !@var")
This patch follows the same pattern that commit used to permit a '!'
prefix on a param ref, allowing a '~' prefix on a param ref, cuasing
kernel-doc to generate the preferred form above.
Suggested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Link: https://lore.kernel.org/r/20230605070124.3741859-25-mark.rutland@arm.com
