Some scripts increase the verbose level when V=1, but others when
not V=0.
I think the former is correct because V=2 is not a log level but
a switch to print the reason for rebuilding.
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
Reviewed-by: Nicolas Schier <nicolas@fjasle.eu>
- Convert flexible array members, fix -Wstringop-overflow warnings,
and fix KCFI function type mismatches that went ignored by
maintainers (Gustavo A. R. Silva, Nathan Chancellor, Kees Cook).
- Remove the remaining side-effect users of ksize() by converting
dma-buf, btrfs, and coredump to using kmalloc_size_roundup(),
add more __alloc_size attributes, and introduce full testing
of all allocator functions. Finally remove the ksize() side-effect
so that each allocation-aware checker can finally behave without
exceptions.
- Introduce oops_limit (default 10,000) and warn_limit (default off)
to provide greater granularity of control for panic_on_oops and
panic_on_warn (Jann Horn, Kees Cook).
- Introduce overflows_type() and castable_to_type() helpers for
cleaner overflow checking.
- Improve code generation for strscpy() and update str*() kern-doc.
- Convert strscpy and sigphash tests to KUnit, and expand memcpy
tests.
- Always use a non-NULL argument for prepare_kernel_cred().
- Disable structleak plugin in FORTIFY KUnit test (Anders Roxell).
- Adjust orphan linker section checking to respect CONFIG_WERROR
(Xin Li).
- Make sure siginfo is cleared for forced SIGKILL (haifeng.xu).
- Fix um vs FORTIFY warnings for always-NULL arguments.
-----BEGIN PGP SIGNATURE-----
iQJKBAABCgA0FiEEpcP2jyKd1g9yPm4TiXL039xtwCYFAmOZSOoWHGtlZXNjb29r
QGNocm9taXVtLm9yZwAKCRCJcvTf3G3AJjAAD/0YkvpU7f03f8hcQMJK6wv//24K
AW41hEaBikq9RcmkuvkLLrJRibGgZ5O2xUkUkxRs/HxhkhrZ0kEw8sbwZe8MoWls
F4Y9+TDjsrdHmjhfcBZdLnVxwcKK5wlaEcpjZXtbsfcdhx3TbgcDA23YELl5t0K+
I11j4kYmf9SLl4CwIrSP5iACml8CBHARDh8oIMF7FT/LrjNbM8XkvBcVVT6hTbOV
yjgA8WP2e9GXvj9GzKgqvd0uE/kwPkVAeXLNFWopPi4FQ8AWjlxbBZR0gamA6/EB
d7TIs0ifpVU2JGQaTav4xO6SsFMj3ntoUI0qIrFaTxZAvV4KYGrPT/Kwz1O4SFaG
rN5lcxseQbPQSBTFNG4zFjpywTkVCgD2tZqDwz5Rrmiraz0RyIokCN+i4CD9S0Ds
oEd8JSyLBk1sRALczkuEKo0an5AyC9YWRcBXuRdIHpLo08PsbeUUSe//4pe303cw
0ApQxYOXnrIk26MLElTzSMImlSvlzW6/5XXzL9ME16leSHOIfDeerPnc9FU9Eb3z
ODv22z6tJZ9H/apSUIHZbMciMbbVTZ8zgpkfydr08o87b342N/ncYHZ5cSvQ6DWb
jS5YOIuvl46/IhMPT16qWC8p0bP5YhxoPv5l6Xr0zq0ooEj0E7keiD/SzoLvW+Qs
AHXcibguPRQBPAdiPQ==
=yaaN
-----END PGP SIGNATURE-----
Merge tag 'hardening-v6.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux
Pull kernel hardening updates from Kees Cook:
- Convert flexible array members, fix -Wstringop-overflow warnings, and
fix KCFI function type mismatches that went ignored by maintainers
(Gustavo A. R. Silva, Nathan Chancellor, Kees Cook)
- Remove the remaining side-effect users of ksize() by converting
dma-buf, btrfs, and coredump to using kmalloc_size_roundup(), add
more __alloc_size attributes, and introduce full testing of all
allocator functions. Finally remove the ksize() side-effect so that
each allocation-aware checker can finally behave without exceptions
- Introduce oops_limit (default 10,000) and warn_limit (default off) to
provide greater granularity of control for panic_on_oops and
panic_on_warn (Jann Horn, Kees Cook)
- Introduce overflows_type() and castable_to_type() helpers for cleaner
overflow checking
- Improve code generation for strscpy() and update str*() kern-doc
- Convert strscpy and sigphash tests to KUnit, and expand memcpy tests
- Always use a non-NULL argument for prepare_kernel_cred()
- Disable structleak plugin in FORTIFY KUnit test (Anders Roxell)
- Adjust orphan linker section checking to respect CONFIG_WERROR (Xin
Li)
- Make sure siginfo is cleared for forced SIGKILL (haifeng.xu)
- Fix um vs FORTIFY warnings for always-NULL arguments
* tag 'hardening-v6.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux: (31 commits)
ksmbd: replace one-element arrays with flexible-array members
hpet: Replace one-element array with flexible-array member
um: virt-pci: Avoid GCC non-NULL warning
signal: Initialize the info in ksignal
lib: fortify_kunit: build without structleak plugin
panic: Expose "warn_count" to sysfs
panic: Introduce warn_limit
panic: Consolidate open-coded panic_on_warn checks
exit: Allow oops_limit to be disabled
exit: Expose "oops_count" to sysfs
exit: Put an upper limit on how often we can oops
panic: Separate sysctl logic from CONFIG_SMP
mm/pgtable: Fix multiple -Wstringop-overflow warnings
mm: Make ksize() a reporting-only function
kunit/fortify: Validate __alloc_size attribute results
drm/sti: Fix return type of sti_{dvo,hda,hdmi}_connector_mode_valid()
drm/fsl-dcu: Fix return type of fsl_dcu_drm_connector_mode_valid()
driver core: Add __alloc_size hint to devm allocators
overflow: Introduce overflows_type() and castable_to_type()
coredump: Proactively round up to kmalloc bucket size
...
iommufd is the user API to control the IOMMU subsystem as it relates to
managing IO page tables that point at user space memory.
It takes over from drivers/vfio/vfio_iommu_type1.c (aka the VFIO
container) which is the VFIO specific interface for a similar idea.
We see a broad need for extended features, some being highly IOMMU device
specific:
- Binding iommu_domain's to PASID/SSID
- Userspace IO page tables, for ARM, x86 and S390
- Kernel bypassed invalidation of user page tables
- Re-use of the KVM page table in the IOMMU
- Dirty page tracking in the IOMMU
- Runtime Increase/Decrease of IOPTE size
- PRI support with faults resolved in userspace
Many of these HW features exist to support VM use cases - for instance the
combination of PASID, PRI and Userspace IO Page Tables allows an
implementation of DMA Shared Virtual Addressing (vSVA) within a
guest. Dirty tracking enables VM live migration with SRIOV devices and
PASID support allow creating "scalable IOV" devices, among other things.
As these features are fundamental to a VM platform they need to be
uniformly exposed to all the driver families that do DMA into VMs, which
is currently VFIO and VDPA.
-----BEGIN PGP SIGNATURE-----
iHUEABYIAB0WIQRRRCHOFoQz/8F5bUaFwuHvBreFYQUCY5ct7wAKCRCFwuHvBreF
YZZ5AQDciXfcgXLt0UBEmWupNb0f/asT6tk717pdsKm8kAZMNAEAsIyLiKT5HqGl
s7fAu+CQ1pr9+9NKGevD+frw8Solsw4=
=jJkd
-----END PGP SIGNATURE-----
Merge tag 'for-linus-iommufd' of git://git.kernel.org/pub/scm/linux/kernel/git/jgg/iommufd
Pull iommufd implementation from Jason Gunthorpe:
"iommufd is the user API to control the IOMMU subsystem as it relates
to managing IO page tables that point at user space memory.
It takes over from drivers/vfio/vfio_iommu_type1.c (aka the VFIO
container) which is the VFIO specific interface for a similar idea.
We see a broad need for extended features, some being highly IOMMU
device specific:
- Binding iommu_domain's to PASID/SSID
- Userspace IO page tables, for ARM, x86 and S390
- Kernel bypassed invalidation of user page tables
- Re-use of the KVM page table in the IOMMU
- Dirty page tracking in the IOMMU
- Runtime Increase/Decrease of IOPTE size
- PRI support with faults resolved in userspace
Many of these HW features exist to support VM use cases - for instance
the combination of PASID, PRI and Userspace IO Page Tables allows an
implementation of DMA Shared Virtual Addressing (vSVA) within a guest.
Dirty tracking enables VM live migration with SRIOV devices and PASID
support allow creating "scalable IOV" devices, among other things.
As these features are fundamental to a VM platform they need to be
uniformly exposed to all the driver families that do DMA into VMs,
which is currently VFIO and VDPA"
For more background, see the extended explanations in Jason's pull request:
https://lore.kernel.org/lkml/Y5dzTU8dlmXTbzoJ@nvidia.com/
* tag 'for-linus-iommufd' of git://git.kernel.org/pub/scm/linux/kernel/git/jgg/iommufd: (62 commits)
iommufd: Change the order of MSI setup
iommufd: Improve a few unclear bits of code
iommufd: Fix comment typos
vfio: Move vfio group specific code into group.c
vfio: Refactor dma APIs for emulated devices
vfio: Wrap vfio group module init/clean code into helpers
vfio: Refactor vfio_device open and close
vfio: Make vfio_device_open() truly device specific
vfio: Swap order of vfio_device_container_register() and open_device()
vfio: Set device->group in helper function
vfio: Create wrappers for group register/unregister
vfio: Move the sanity check of the group to vfio_create_group()
vfio: Simplify vfio_create_group()
iommufd: Allow iommufd to supply /dev/vfio/vfio
vfio: Make vfio_container optionally compiled
vfio: Move container related MODULE_ALIAS statements into container.c
vfio-iommufd: Support iommufd for emulated VFIO devices
vfio-iommufd: Support iommufd for physical VFIO devices
vfio-iommufd: Allow iommufd to be used in place of a container fd
vfio: Use IOMMU_CAP_ENFORCE_CACHE_COHERENCY for vfio_file_enforced_coherent()
...
While there were varying degrees of kern-doc for various str*()-family
functions, many needed updating and clarification, or to just be
entirely written. Update (and relocate) existing kern-doc and add missing
functions, sadly shaking my head at how many times I have written "Do
not use this function". Include the results in the core kernel API doc.
Cc: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Andy Shevchenko <andy@kernel.org>
Cc: Rasmus Villemoes <linux@rasmusvillemoes.dk>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: linux-hardening@vger.kernel.org
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/lkml/9b0cf584-01b3-3013-b800-1ef59fe82476@gmail.com
Signed-off-by: Kees Cook <keescook@chromium.org>
Make a few changes to cause functions documented by kerneldoc to stand out
better in the rendered documentation. Specifically, change kernel-doc to
put the description section into a ".. container::" section, then add a bit
of CSS to indent that section relative to the function prototype (or struct
or enum definition). Tweak a few other CSS parameters while in the
neighborhood to improve the formatting.
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some warnings do not increment the warnings counter making the behavior
of running kernel-doc with -Werror unlogical as some warnings will be
generated but not treated as errors.
Fix this by creating a helper function that always incrementing the
warnings counter every time a warning is emitted. There is one location
in get_sphinx_version() where a warning is not touched as it concerns
the execution environment of the kernel-doc and not the documentation
being processed.
Incrementing the counter only have effect when running kernel-doc in
either verbose mode (-v or environment variable KBUILD_VERBOSE) or when
treating warnings as errors (-Werror or environment variable
KDOC_WERROR). In both cases the number of warnings printed is printed to
stderr and for the later the exit code of kernel-doc is non-zero if
warnings where encountered.
Simple test case to demo one of the warnings,
$ cat test.c
/**
* foo() - Description
*/
int bar();
# Without this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for
bar() instead
# With this change
$ ./scripts/kernel-doc -Werror -none test.c
test.c:4: warning: expecting prototype for foo(). Prototype was for
bar() instead
1 warnings as Errors
Signed-off-by: Niklas Söderlund <niklas.soderlund@corigine.com>
Link: https://lore.kernel.org/r/20220613090510.3088294-1-niklas.soderlund@corigine.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, when there is no FILE argument following a switch such
as -man, -rst, or -none, kernel-doc exits with a warning from perl
(long msg folded):
Use of uninitialized value $ARGV[0] in pattern match (m//)
at ./scripts/kernel-doc line 438.
, which is unhelpful.
Improve the behavior by adding a check at the bottom of parsing
loop.
If the argument is absent, display help text and exit with
the code of 1 (via usage()).
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/7b136049-a3ba-0eb5-8717-364d773ff914@gmail.com
[jc: reworked to fix conflict with pod patches]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
I wanted to clean up these lines, but in the end decided not to touch
the old ones and just add my own about POD. I'll leave the cleanup
for lawyers.
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-12-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
What for? To improve the script maintainability.
1. License
As stated by Jonathan Corbet in the reply to my version 1, the SPDX line
is enough.
2. The to-do list comment
As suggested by Jonathan Corbet in reply to my version 3, this section
doesn't need to be transitioned. And so it is removed for clarity.
3. The historical changelog comments
As suggested by Jonathan Corbet in a reply to v3, this section can go.
I wanted to keep it, but since it doesn't contain copyright notices,
let's just have it clean and simple.
4. The "format of comments" comment block
As suggested by Jani Nikula in a reply to my first version of this
transformation, Documentation/doc-guide/kernel-doc.rst can serve as the
information hub for comment formatting. The section DESCRIPTION already
points there, so the original comment block can just be removed.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Suggested-by: Jani Nikula <jani.nikula@linux.intel.com>
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-11-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aim: unified POD, user more satisfied, script better structured
You can see the results with:
$ scripts/kernel-doc -help
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-10-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aim: unified POD, user more satisfied, script better structured
Notes:
- The -help token is added.
- The entries are sorted alphbetically.
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-9-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aim: unified POD, user more satisfied, script better structured
A subsection "reStructuredText only" is added for -enable-lineno.
Other notes:
- paragraphing correction
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-8-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aim: unified POD, user more satisfied, script better structured
The plurals in -function and -nosymbol are corrected to singulars.
That's how the script works now. I think this describes the syntax better.
The plurar suggests multiple FILE arguments might be possible. So this
seems more coherent.
Other notes:
- paragraphing correction
- article correction
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-7-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Aim: unified POD, user more happy
This section is renamed to "Output format modifiers" to make it simple.
To make it even more simple, a subsection is added:
"reStructuredText only".
Other notes:
- paragraphing correction
- article correction
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-6-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Another step in the direction of a uniform POD documentation, which will
make users happier.
Options land at the end of the script, not to clutter the file top.
The default output format is corrected to rst. That's what it is now.
A POD delimiting comment is added to the script head, which improves
the script logical structure.
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-5-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Transition the description section into POD. This is one of the standard
documentation sections. This adjustment makes the section available for
POD and makes it look better.
Notes:
- an article addition
- paragraphing correction
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-4-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The former usage function is substituted, although not as the -h and -help
parameter handler yet.
Purpose: Use Pod::Usage to handle documentation printing in an integrated
way.
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-3-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The NAME section provides the doc title, while SYNOPSIS contains
the basic syntax and usage description, which will be printed
in the help document and in the error output produced on wrong script
usage.
The rationale is to give users simple and succinct enlightment,
at the same time structuring the script internally for the maintainers.
In the synopsis, Rst-only options are grouped around rst, and the rest is
arranged as in the OPTIONS subsections (yet to be translated into POD,
check at the end of the series).
The third of the basic sections, DESCRIPTION, is added separately.
Signed-off-by: Tomasz Warniełło <tomasz.warniello@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Disliked-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220218181628.1411551-2-tomasz.warniello@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
- Some small scripts/kerneldoc fixes
- More Chinese translation work, but at a much reduced rate.
- The tip-tree maintainer's handbook
...plus the usual array of build fixes, typo fixes, etc.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmGBqbYPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5YzMoH+wQwUbILvf4FB9h6l0qhbPnvcLMJtDiuIGSu
Ivfc1t+Vh7/waehaYfn9erCNps6oE13Arsy0DDFZcr6vbjXFO5clFoh5jvSJsk+G
zTXzZNB99SoJcZw9r8F7aJDbQNJfSXoyTTOg1mSeXNo+nkBFTSWO7QwCx5M2obaT
76+r8HQpnEYmrGePsOXriV4aOP+yJxuGgkPb+VPlPtQhA7v6dzo5hmoh5tPIzCLd
Fz8ek4aAm9sPEtu1UUoA+7MALZHTFwPv6aSAuyVeNfF/UBL6M4iAwusQyLdPFfoj
JPO7f+1h6a8jKTfTWGjPI3o33DtU/8nc6DgnuBaXBTKW8Dl5Exk=
=q37Q
-----END PGP SIGNATURE-----
Merge tag 'docs-5.16' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This is a relatively unexciting cycle for documentation.
- Some small scripts/kerneldoc fixes
- More Chinese translation work, but at a much reduced rate.
- The tip-tree maintainer's handbook
...plus the usual array of build fixes, typo fixes, etc"
* tag 'docs-5.16' of git://git.lwn.net/linux: (53 commits)
kernel-doc: support DECLARE_PHY_INTERFACE_MASK()
docs/zh_CN: add core-api xarray translation
docs/zh_CN: add core-api assoc_array translation
speakup: Fix typo in documentation "boo" -> "boot"
docs: submitting-patches: make section about the Link: tag more explicit
docs: deprecated.rst: Clarify open-coded arithmetic with literals
scripts: documentation-file-ref-check: fix bpf selftests path
scripts: documentation-file-ref-check: ignore hidden files
coding-style.rst: trivial: fix location of driver model macros
docs: f2fs: fix text alignment
docs/zh_CN add PCI pci.rst translation
docs/zh_CN add PCI index.rst translation
docs: translations: zh_CN: memory-hotplug.rst: fix a typo
docs: translations: zn_CN: irq-affinity.rst: add a missing extension
block: add documentation for inflight
scripts: kernel-doc: Ignore __alloc_size() attribute
docs: pdfdocs: Adjust \headheight for fancyhdr
docs: UML: user_mode_linux_howto_v2 edits
docs: use the lore redirector everywhere
docs: proc.rst: mountinfo: align columns
...
Support the DECLARE_PHY_INTERFACE_MASK() macro that is used to declare
a bitmap by converting the macro to DECLARE_BITMAP(), as has been done
for the __ETHTOOL_DECLARE_LINK_MODE_MASK() macro.
This fixes a 'make htmldocs' warning:
include/linux/phylink.h:82: warning: Function parameter or member 'DECLARE_PHY_INTERFACE_MASK(supported_interfaces' not described in 'phylink_config'
that was introduced by commit
38c310eb46 ("net: phylink: add MAC phy_interface_t bitmap")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Cc: Russell King (Oracle) <linux@armlinux.org.uk>
Link: https://lore.kernel.org/r/45934225-7942-4326-f883-a15378939db9@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are many places where kernel code wants to have several different
typed trailing flexible arrays. This would normally be done with multiple
flexible arrays in a union, but since GCC and Clang don't (on the surface)
allow this, there have been many open-coded workarounds, usually involving
neighboring 0-element arrays at the end of a structure. For example,
instead of something like this:
struct thing {
...
union {
struct type1 foo[];
struct type2 bar[];
};
};
code works around the compiler with:
struct thing {
...
struct type1 foo[0];
struct type2 bar[];
};
Another case is when a flexible array is wanted as the single member
within a struct (which itself is usually in a union). For example, this
would be worked around as:
union many {
...
struct {
struct type3 baz[0];
};
};
These kinds of work-arounds cause problems with size checks against such
zero-element arrays (for example when building with -Warray-bounds and
-Wzero-length-bounds, and with the coming FORTIFY_SOURCE improvements),
so they must all be converted to "real" flexible arrays, avoiding warnings
like this:
fs/hpfs/anode.c: In function 'hpfs_add_sector_to_btree':
fs/hpfs/anode.c:209:27: warning: array subscript 0 is outside the bounds of an interior zero-length array 'struct bplus_internal_node[0]' [-Wzero-length-bounds]
209 | anode->btree.u.internal[0].down = cpu_to_le32(a);
| ~~~~~~~~~~~~~~~~~~~~~~~^~~
In file included from fs/hpfs/hpfs_fn.h:26,
from fs/hpfs/anode.c:10:
fs/hpfs/hpfs.h:412:32: note: while referencing 'internal'
412 | struct bplus_internal_node internal[0]; /* (internal) 2-word entries giving
| ^~~~~~~~
drivers/net/can/usb/etas_es58x/es58x_fd.c: In function 'es58x_fd_tx_can_msg':
drivers/net/can/usb/etas_es58x/es58x_fd.c:360:35: warning: array subscript 65535 is outside the bounds of an interior zero-length array 'u8[0]' {aka 'unsigned char[]'} [-Wzero-length-bounds]
360 | tx_can_msg = (typeof(tx_can_msg))&es58x_fd_urb_cmd->raw_msg[msg_len];
| ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In file included from drivers/net/can/usb/etas_es58x/es58x_core.h:22,
from drivers/net/can/usb/etas_es58x/es58x_fd.c:17:
drivers/net/can/usb/etas_es58x/es58x_fd.h:231:6: note: while referencing 'raw_msg'
231 | u8 raw_msg[0];
| ^~~~~~~
However, it _is_ entirely possible to have one or more flexible arrays
in a struct or union: it just has to be in another struct. And since it
cannot be alone in a struct, such a struct must have at least 1 other
named member -- but that member can be zero sized. Wrap all this nonsense
into the new DECLARE_FLEX_ARRAY() in support of having flexible arrays
in unions (or alone in a struct).
As with struct_group(), since this is needed in UAPI headers as well,
implement the core there, with a non-UAPI wrapper.
Additionally update kernel-doc to understand its existence.
https://github.com/KSPP/linux/issues/137
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: "Gustavo A. R. Silva" <gustavoars@kernel.org>
Signed-off-by: Kees Cook <keescook@chromium.org>
Fixes "Compiler Attributes: add __alloc_size() for better bounds checking"
so that the __alloc_size() macro is ignored for function prototypes when
generating kerndoc. Avoids warnings like:
./include/linux/slab.h:662: warning: Function parameter or member '1' not described in '__alloc_size'
./include/linux/slab.h:662: warning: Function parameter or member '2' not described in '__alloc_size'
./include/linux/slab.h:662: warning: expecting prototype for kcalloc(). Prototype was for __alloc_size() instead
Suggested-by: Matthew Wilcox <willy@infradead.org>
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20211011180650.3603988-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Kernel code has a regular need to describe groups of members within a
structure usually when they need to be copied or initialized separately
from the rest of the surrounding structure. The generally accepted design
pattern in C is to use a named sub-struct:
struct foo {
int one;
struct {
int two;
int three, four;
} thing;
int five;
};
This would allow for traditional references and sizing:
memcpy(&dst.thing, &src.thing, sizeof(dst.thing));
However, doing this would mean that referencing struct members enclosed
by such named structs would always require including the sub-struct name
in identifiers:
do_something(dst.thing.three);
This has tended to be quite inflexible, especially when such groupings
need to be added to established code which causes huge naming churn.
Three workarounds exist in the kernel for this problem, and each have
other negative properties.
To avoid the naming churn, there is a design pattern of adding macro
aliases for the named struct:
#define f_three thing.three
This ends up polluting the global namespace, and makes it difficult to
search for identifiers.
Another common work-around in kernel code avoids the pollution by avoiding
the named struct entirely, instead identifying the group's boundaries using
either a pair of empty anonymous structs of a pair of zero-element arrays:
struct foo {
int one;
struct { } start;
int two;
int three, four;
struct { } finish;
int five;
};
struct foo {
int one;
int start[0];
int two;
int three, four;
int finish[0];
int five;
};
This allows code to avoid needing to use a sub-struct named for member
references within the surrounding structure, but loses the benefits of
being able to actually use such a struct, making it rather fragile. Using
these requires open-coded calculation of sizes and offsets. The efforts
made to avoid common mistakes include lots of comments, or adding various
BUILD_BUG_ON()s. Such code is left with no way for the compiler to reason
about the boundaries (e.g. the "start" object looks like it's 0 bytes
in length), making bounds checking depend on open-coded calculations:
if (length > offsetof(struct foo, finish) -
offsetof(struct foo, start))
return -EINVAL;
memcpy(&dst.start, &src.start, offsetof(struct foo, finish) -
offsetof(struct foo, start));
However, the vast majority of places in the kernel that operate on
groups of members do so without any identification of the grouping,
relying either on comments or implicit knowledge of the struct contents,
which is even harder for the compiler to reason about, and results in
even more fragile manual sizing, usually depending on member locations
outside of the region (e.g. to copy "two" and "three", use the start of
"four" to find the size):
BUILD_BUG_ON((offsetof(struct foo, four) <
offsetof(struct foo, two)) ||
(offsetof(struct foo, four) <
offsetof(struct foo, three));
if (length > offsetof(struct foo, four) -
offsetof(struct foo, two))
return -EINVAL;
memcpy(&dst.two, &src.two, length);
In order to have a regular programmatic way to describe a struct
region that can be used for references and sizing, can be examined for
bounds checking, avoids forcing the use of intermediate identifiers,
and avoids polluting the global namespace, introduce the struct_group()
macro. This macro wraps the member declarations to create an anonymous
union of an anonymous struct (no intermediate name) and a named struct
(for references and sizing):
struct foo {
int one;
struct_group(thing,
int two;
int three, four;
);
int five;
};
if (length > sizeof(src.thing))
return -EINVAL;
memcpy(&dst.thing, &src.thing, length);
do_something(dst.three);
There are some rare cases where the resulting struct_group() needs
attributes added, so struct_group_attr() is also introduced to allow
for specifying struct attributes (e.g. __align(x) or __packed).
Additionally, there are places where such declarations would like to
have the struct be tagged, so struct_group_tagged() is added.
Given there is a need for a handful of UAPI uses too, the underlying
__struct_group() macro has been defined in UAPI so it can be used there
too.
To avoid confusing scripts/kernel-doc, hide the macro from its struct
parsing.
Co-developed-by: Keith Packard <keithp@keithp.com>
Signed-off-by: Keith Packard <keithp@keithp.com>
Acked-by: Gustavo A. R. Silva <gustavoars@kernel.org>
Link: https://lore.kernel.org/lkml/20210728023217.GC35706@embeddedor
Enhanced-by: Rasmus Villemoes <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/41183a98-bdb9-4ad6-7eab-5a7292a6df84@rasmusvillemoes.dk
Enhanced-by: Dan Williams <dan.j.williams@intel.com>
Link: https://lore.kernel.org/lkml/1d9a2e6df2a9a35b2cdd50a9a68cac5991e7e5f0.camel@intel.com
Enhanced-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://lore.kernel.org/lkml/YQKa76A6XuFqgM03@phenom.ffwll.local
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Since commit 2c12c8103d ("scripts/kernel-doc: optionally treat
warnings as errors"), the kernel-doc script will treat warnings as
errors when one of the following conditions is true:
- The KDOC_WERROR environment variable is non-zero
- The KCFLAGS environment variable contains -Werror
- The -Werror parameter is passed to kernel-doc
Checking KCFLAGS for -Werror allows piggy-backing on the C compiler
error handling. However, unlike the C compiler, kernel-doc has no
provision for -Wno-error. This makes compiling the kernel with -Werror
(to catch regressions) and W=1 (to enable more checks) always fail,
without the same possibility as offered by the C compiler to treating
some selected warnings as warnings despite the global -Werror setting.
To fix this, evaluate KDOC_WERROR after KCFLAGS, which allows disabling
the warnings-as-errors behaviour of kernel-doc selectively by setting
KDOC_WERROR=0.
Signed-off-by: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Link: https://lore.kernel.org/r/20210730225401.4401-1-laurent.pinchart+renesas@ideasonboard.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are some regex expressions in the kernel-doc script, which are used
repeatedly in the script.
Reduce such expressions into variables, which can be used everywhere.
A quick manual check found that no errors and warnings were added/removed
in this process.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210514144244.25341-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The current linux-next tree has a new error:
./Documentation/gpu/drm-mm:445: ./drivers/gpu/drm/drm_prime.c:994: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 17]
int __deprecated drm_prime_sg_to_page_array (struct sg_table *sgt, struct page **pages, int max_entries)
-----------------^
While we might consider that documenting a deprecated interface is not
necessarily best practice, removing the error is easy.
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Link: https://lore.kernel.org/r/20210427114828.GY235567@casper.infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently kernel-doc does not identify some cases of probable kernel
doc comments, for e.g. pointer used as declaration type for identifier,
space separated identifier, etc.
Some example of these cases in files can be:
i)" * journal_t * jbd2_journal_init_dev() - creates and initialises a journal structure"
in fs/jbd2/journal.c
ii) "* dget, dget_dlock - get a reference to a dentry" in
include/linux/dcache.h
iii) " * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t"
in include/linux/seqlock.h
Also improve identification for non-kerneldoc comments. For e.g.,
i) " * The following functions allow us to read data using a swap map"
in kernel/power/swap.c does follow the kernel-doc like syntax, but the
content inside does not adheres to the expected format.
Improve parsing by adding support for these probable attempts to write
kernel-doc comment.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com
[ jc: fixed some line-length issues ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, kernel-doc start parsing the comment as a kernel-doc comment if
it starts with '/**', but does not take into account if the content inside
the comment too, adheres with the expected format.
This results in unexpected and unclear warnings for the user.
E.g., running scripts/kernel-doc -none mm/memcontrol.c emits:
"mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead"
Here kernel-doc parses the corresponding comment as a kernel-doc comment
and expects prototype for it in the next lines, and as a result causing
this warning.
Provide a clearer warning message to the users regarding the same, if the
content inside the comment does not follow the kernel-doc expected format.
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The previous attempt to properly handle literal blocks broke parsing of
parameter lines containing colons; fix it by tweaking the regex to
specifically exclude the "::" pattern while accepting lines containing
colons in general. Add a little documentation to the regex while in the
neighborhood.
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Fixes: 8d295fbad6 ("kernel-doc: better handle '::' sequences")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Right now, if one of the following headers end with a '::', the
kernel-doc script will do the wrong thing:
description|context|returns?|notes?|examples?
The real issue is with examples, as people could try to write
something like:
example::
/* Some C code */
and this won't be properly evaluated. So, improve the regex
to not catch '\w+::' regex for the above identifiers.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When anonymous enums are used, the identifier is empty.
While, IMO, it should be avoided the usage of such enums,
adding support for it is not hard.
So, postpone the check for empty identifiers to happen
only at the dump phase.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/055ad57879f1b9381b90879e00f72fde1c3a5647.1614760910.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, kernel-doc warns for function prototype parsing on the
presence of attributes "__attribute_const__" and "__flatten" in the
definition.
There are 166 occurrences in ~70 files in the kernel tree for
"__attribute_const__" and 5 occurrences in 4 files for "__flatten".
Out of 166, there are 3 occurrences in three different files with
"__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in
./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other
occurrences have no preceding kernel-doc.
Add support for "__attribute_const__" and "__flatten" attributes.
A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals
that no additional warning or error has been added or removed by the fix.
Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210306113510.31023-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, there are ~1290 occurrences in 447 files in the kernel tree
'typedef struct/union' syntax for defining some struct/union. However,
kernel-doc currently does not support that syntax. Of the ~1290
occurrences, there are four occurrences in ./include/linux/zstd.h with
typedef struct/union syntax and a preceding kernel-doc; all other
occurrences have no preceding kernel-doc.
Add support for parsing struct/union following this syntax.
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210225145033.11431-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, kernel-doc causes an unexpected error when array element (i.e.,
"type (*foo[bar])(args)") is present as pointer parameter in
pointer-to-function parsing.
For e.g., running kernel-doc -none on kernel/gcov/gcc_4_7.c causes this
error:
"Use of uninitialized value $param in regexp compilation at ...", in
combination with:
"warning: Function parameter or member '' not described in 'gcov_info'"
Here, the parameter parsing does not take into account the presence of
array element (i.e. square brackets) in $param.
Provide a simple fix by adding square brackets in the regex, responsible
for capturing $param.
A quick evaluation, by running 'kernel-doc -none' on entire kernel-tree,
reveals that no additional warning or error has been added or removed by
the fix.
Suggested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Tested-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20210217145625.14006-1-yashsri421@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While DOC: section titles are not converted into RST headings
sections and are only decorated with strong emphasis markup,
nothing stops us from generating internal hyperlinks for them,
to mimic implicit hyperlinks to RST headings.
Signed-off-by: Michal Wajdeczko <michal.wajdeczko@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Link: https://lore.kernel.org/r/20210118110813.1490-1-michal.wajdeczko@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Kernel-doc currently expects that the kernel-doc markup to come
just before the function/enum/struct/union/typedef prototype.
Yet, if it find things like:
/**
* refcount_add - add a value to a refcount
* @i: the value to add to the refcount
* @r: the refcount
*/
static inline void __refcount_add(int i, refcount_t *r, int *oldp);
static inline void refcount_add(int i, refcount_t *r);
Kernel-doc will do the wrong thing:
foobar.h:6: warning: Function parameter or member 'oldp' not described in '__refcount_add'
.. c:function:: void __refcount_add (int i, refcount_t *r, int *oldp)
add a value to a refcount
**Parameters**
``int i``
the value to add to the refcount
``refcount_t *r``
the refcount
``int *oldp``
*undescribed*
Basically, it will document "__refcount_add" with the kernel-doc
markup for refcount_add.
If both functions have the same arguments, this won't even
produce any warning!
Add a logic to check if the kernel-doc identifier matches the actual
name of the C function or data structure that will be documented.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/081546f141a496d6cabb99a4adc140444c705e93.1610610937.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changeset 6b80975c63 ("scripts: kernel-doc: fix typedef parsing")
added support for things like:
typedef unsigned long foo();
However, it caused a regression on this prototype:
typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
This is only noticed after adding a patch that checks if the
kernel-doc identifier matches the typedef:
./scripts/kernel-doc -none $(git grep '^.. kernel-doc::' Documentation/ |cut -d ' ' -f 3|sort|uniq) 2>&1|grep expecting
include/media/v4l2-dv-timings.h:38: warning: expecting prototype for typedef v4l2_check_dv_timings_fnc. Prototype was for typedef nc instead
The problem is that, with the new parsing logic, it is not
checking for complete words at the type part.
Fix it by adding a \b at the end of each type word at the
regex.
fixes: 6b80975c63 ("scripts: kernel-doc: fix typedef parsing")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/218ff56dcb8e73755005d3fb64586eb1841a276b.1606896997.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The commit d38c8cfb05 ("scripts: kernel-doc: add support for typedef enum")
broke anonymous enum parsing. Restore it by relying on members rather than
its name.
Fixes: d38c8cfb05 ("scripts: kernel-doc: add support for typedef enum")
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20201102170637.36138-1-andriy.shevchenko@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx C domain code after 3.2.1 will start complaning if :c:struct
would be used for an union type:
.../Documentation/gpu/drm-kms-helpers:352: ../drivers/video/hdmi.c:851: WARNING: C 'identifier' cross-reference uses wrong tag: reference name is 'union hdmi_infoframe' but found name is 'struct hdmi_infoframe'. Full reference name is 'union hdmi_infoframe'. Full found name is 'struct hdmi_infoframe'.
So, let's address this issue too in advance, in order to
avoid future issues.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/6e4ec3eec914df62389a299797a3880ae4490f35.1603791716.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The include/linux/genalloc.h file defined this typedef:
typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr);
Because it has a type composite of two words (unsigned long),
the parser gets the typedef name wrong:
.. c:macro:: long
**Typedef**: Allocation callback function type definition
Fix the regex in order to accept composite types when
defining a typedef for a function pointer.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/328e8018041cc44f7a1684e57f8d111230761c4f.1603792384.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are a few namespace clashes by using c:macro everywhere:
basically, when using it, we can't have something like:
.. c:struct:: pwm_capture
.. c:macro:: pwm_capture
So, we need to use, instead:
.. c:function:: int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)
for the function declaration.
The kernel-doc change was proposed by Jakob Lykke Andersen here:
6fd2076ec0
Although I did a different implementation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Address several issues related to pointing to the wrong line
number:
1) ensure that line numbers will always be initialized
When section is the default (Description), the line number
is not initializing, producing this:
$ ./scripts/kernel-doc --enable-lineno ./drivers/media/v4l2-core/v4l2-mem2mem.c|less
**Description**
#define LINENO 0
In case of streamoff or release called on any context,
1] If the context is currently running, then abort job will be called
2] If the context is queued, then the context will be removed from
the job_queue
Which is not right. Ensure that the line number will always
be there. After applied, the result now points to the right location:
**Description**
#define LINENO 410
In case of streamoff or release called on any context,
1] If the context is currently running, then abort job will be called
2] If the context is queued, then the context will be removed from
the job_queue
2) The line numbers for function prototypes are always + 1,
because it is taken at the line after handling the prototype.
Change the logic to point to the next line after the /** */
block;
3) The "DOC:" line number should point to the same line as this
markup is found, and not to the next one.
Probably part of the issues were due to a but that was causing
the line number offset to be incremented by one, if --export
were used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.
As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.
I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:
m/^(\d+)\.(\d+)(?:\.?(\d+)?)/
in order to get the optional <patch> argument.
Thanks-to: Joe Perches <joe@perches.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
While kernel-doc needs to parse parameters in order to
identify its name, it shouldn't be touching the type,
as parsing it is very difficult, and errors happen.
One current error is when parsing this parameter:
const u32 (*tab)[256]
Found at ./lib/crc32.c, on this function:
u32 __pure crc32_be_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial);
The current logic mangles it, producing this output:
const u32 ( *tab
That's something that it is not recognizeable.
So, instead, let's push the argument as-is, and use it
when printing the function prototype and when describing
each argument.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Some typedef expressions are output as normal functions.
As we need to be clearer about the type with Sphinx 3.x,
detect such cases.
While here, fix a wrongly-indented block.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Right now, the build system doesn't use -nofunction, as
it is pretty much useless, because it doesn't consider
the other output modes (extern, internal), working only
with all.
Also, it is limited to exclude functions.
Re-implement it in order to allow excluding any symbols from
the document output, no matter what mode is used.
The parameter was also renamed to "-nosymbol", as it express
better its meaning.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
There's currently a bug with the way kernel-doc script
counts line numbers that can be seen with:
$ ./scripts/kernel-doc -rst -enable-lineno include/linux/math64.h >all && ./scripts/kernel-doc -rst -internal -enable-lineno include/linux/math64.h >int && diff -U0 int all
--- int 2020-09-28 12:58:08.927486808 +0200
+++ all 2020-09-28 12:58:08.905486845 +0200
@@ -1 +1 @@
-#define LINENO 27
+#define LINENO 26
@@ -3 +3 @@
-#define LINENO 16
+#define LINENO 15
@@ -9 +9 @@
-#define LINENO 17
+#define LINENO 16
...
This is happening with perl version 5.30.3, but I'm not
so sure if this is a perl bug, or if this is due to something
else.
In any case, fixing it is easy. Basically, when "-internal"
parameter is used, the process_export_file() function opens the
handle "IN". This makes the line number to be incremented, as the
handler for the main open is also "IN".
Fix the problem by using a different handler for the
main open().
While here, add a missing close for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Unfortunately, Sphinx 3.x parser for c functions is too pedantic:
https://github.com/sphinx-doc/sphinx/issues/8241
While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.
So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:
.. c:type:: typedef-like declaration
.. c:type:: name
Using it for other types (including functions) don't work anymore.
So, there are newer tags for macro, enum, struct, union, and others,
which doesn't exist on older versions.
Add a check for the Sphinx version and change the produced tags
accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
The PHY kernel-doc markup has gained support for documenting
a typedef enum.
However, right now the parser was not prepared for it.
So, add support for parsing it.
Fixes: 4069a572d4 ("net: phy: Document core PHY structures")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.
Based on previous patch to add ____cacheline_aligned_in_smp.
Motivated by patches to reorder this attribute to before the
variable name. Whilst we could do that in all cases, that would
be a massive change and it is more common in the kernel to place
this particular attribute after the variable name. A quick grep
suggests approximately 400 instances of which 341 have this
attribute just before a semicolon and hence after the variable name.
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Lee Jones <lee.jones@linaro.org>
Link: https://lore.kernel.org/r/20200910185415.653139-1-jic23@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The kbuild bot recently added the W=1 option, which triggered
documentation cleanups to squelch hundreds of kernel-doc warnings.
To make sure new kernel contributions don't add regressions to
kernel-doc descriptors, this patch suggests an option to treat
warnings as errors in CI/automated tests.
A -Werror command-line option is added to the kernel-doc script. When
this option is set, the script will return the number of warnings
found. The caller can then treat this positive return value as an
error and stop the build.
Using this command line option is however not straightforward when the
kernel-doc script is called from other scripts. To align with typical
kernel compilation or documentation generation, the Werror option is
also set by checking the KCFLAGS environment variable, or if
KDOC_WERROR is defined, as in the following examples:
KCFLAGS="-Wall -Werror" make W=1 sound/
KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
KDOC_WERROR=1 make htmldocs
Note that in the last example the documentation build does not stop,
only an additional log is provided.
Credits to Randy Dunlap for suggesting the use of environment variables.
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are some function pointer prototypes inside the net
includes, like this one:
int (*pcs_config)(struct phylink_config *config, unsigned int mode,
phy_interface_t interface, const unsigned long *advertising);
There's nothing wrong using it with kernel-doc, but we need to
add a rule for it to parse such kind of prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/fec520dd731a273013ae06b7653a19c7d15b9562.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of
DECLARE_BITMAP(), used by phylink.h. As we have already a
parser for DECLARE_BITMAP(), let's add one for this macro,
in order to avoid such warnings:
./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising' not described in 'phylink_link_state'
./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising' not described in 'phylink_link_state'
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d1d1dea67a28117c0b0c33271b139c4455fef287.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a blank line. However, currently, any blank line inside a
kernel-doc comment like:
/*
* @foo: bar
*
* foobar
*
* some description
will be considered as if "foobar" was part of the description.
This patch changes kernel-doc behavior. After it, foobar will
be considered as part of the parameter text. The description
will only be considered as such if it starts with:
zero spaces after asterisk:
*foo
one space after asterisk:
* foo
or have a explicit Description section:
* Description:
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
On a few places, it sometimes need to indicate a negation of a
parameter, like:
!@fshared
This pattern happens, for example, at:
kernel/futex.c
and it is perfectly valid. However, kernel-doc currently
transforms it into:
!**fshared**
This won't do what it would be expected.
Fortunately, fixing the script is a simple matter of storing
the "!" before "@" and adding it after the bold markup, like:
**!fshared**
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.
Right now, it causes a warning:
./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.
In this specific case, the kernel-doc markup is:
/**
* fw_core_remove_address_handler() - unregister an address handler
* @handler: callback
*
* To be called in process context.
*
* When fw_core_remove_address_handler() returns, @handler->callback() is
* guaranteed to not run on any CPU anymore.
*/
With seems valid on my eyes. So, instead of trying to hack
the kernel-doc markup, let's teach it about how to handle
such things. This should likely remove lots of other similar
warnings as well.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print
the close-paren after the argument list of the function pointer
argument. For instance:
long work_on_cpu(int cpu, long (*fn) (void *, void * arg)
in driver-api/basics.html is missing a ')' separating the
"void *" of the 'fn' arguments from the ", void * arg" which
is an argument to work_on_cpu().
Add the missing close-paren, so that we render the prototype
correctly:
long work_on_cpu(int cpu, long (*fn)(void *), void * arg)
(Note that Sphinx stops rendering a space between the '(fn*)' and the
'(void *)' once it gets something that's syntactically valid.)
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Link: https://lore.kernel.org/r/20200414143743.32677-1-peter.maydell@linaro.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, when kernel-doc encounters a macro with a named variable
argument[1], such as this:
#define hlist_for_each_entry_rcu(pos, head, member, cond...)
... it expects the variable argument to be documented as `cond...`,
rather than `cond`. This is semantically wrong, because the name (as
used in the macro body) is actually `cond`.
With this patch, kernel-doc will accept the name without dots (`cond`
in the example above) in doc comments, and warn if the name with dots
(`cond...`) is used and verbose mode[2] is enabled.
The support for the `cond...` syntax can be removed later, when the
documentation of all such macros has been switched to the new syntax.
Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few
changes in log output and HTML output:
1) The following warnings[3] are eliminated:
./include/linux/rculist.h:374: warning:
Excess function parameter 'cond' description in 'list_for_each_entry_rcu'
./include/linux/rculist.h:651: warning:
Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'
2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the
correct description is shown
3) Named variable arguments are shown without dots
[1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
[2]: scripts/kernel-doc -v
[3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Tested-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned_in_smp` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround the attribute. After that, the code will split structs and
iterate for each symbol separated by comma at the end of struct
definition (e.g. "} alias1, alias2;"). However, if the nested struct
does not have any alias and has an attribute, it will result in a
empty string at the closing bracket (e.g "};"). This will make the
split return nothing and $newmember will keep uninitialized. Fix
that, by ensuring that the attribute substitution will leave at least
one whitespace.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
In C is a valid construction to have an anonymous enumerator.
Though we have now:
drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum!
Support it in the kernel-doc script.
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Ignore __printf() function attributes just as other __attribute__
strings are ignored.
Fixes this kernel-doc warning message:
include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf'
Reported-by: kbuild test robot <lkp@intel.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Brendan Higgins <brendanhiggins@google.com>
Tested-by: Brendan Higgins <brendanhiggins@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs. Sort of
discouraging that nobody ever noticed...:)
As a first step toward the removal of impenetrable regex magic from
kernel-doc it's a tiny one, but you have to start somewhere.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The "no structured comments found" warning is not particularly useful if
there are several invocations, one of which is looking for something
wrong. So if something specific has been requested, make it clear that
it's the one we weren't able to find.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The ability to add kerneldoc comments for fields in embedded structures is
useful, but it brought along a whole bunch of warnings for fields that
could not be described before. In many cases, there's little value in
adding docs for these nested fields, and in cases like:
struct a {
struct b {
int c;
} d, e;
};
"c" would have to be described twice (as d.c and e.c) to make the warnings
go away.
We can no doubt do something smarter, but simply suppressing the warnings
for this case removes about 70 warnings from the docs build, freeing us to
focus on the ones that matter more. So make kerneldoc be silent about
missing descriptions for any field containing a ".".
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The kernel-doc attempts to clear the struct and struct member attributes
from the API documentation it produces. It falls short of the job in the
following respects:
- extra whitespaces are left where __attribute__((...)) was removed,
- only a single attribute is removed per struct,
- attributes (such as aligned) containing numbers were not removed,
- attributes are only cleared from struct fields, not structs themselves.
This patch addresses these issues by removing the attributes.
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, function parameter description can match '@type.member'
expressions but fails to match '@type->member'.
Extend the $type_param regex to allow matching both
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Make declaration type determination more robust.
When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union, a typedef, or a function,
it does a pattern match on the beginning of the string, looking
for a match with one of "struct", "union", "enum", or "typedef",
and otherwise defaults to a function declaration type.
However, if a function or a function-like macro has a name that
begins with "struct" (e.g., struct_size()), then kernel-doc
incorrectly decides that this is a struct declaration.
Fix this by looking for the declaration type keywords having an
ending word boundary (\b), so that "struct_size" will not match
a struct declaration.
I compared lots of html before/after output from core-api, driver-api,
and networking. There were no differences in any of the files that
I checked.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 701b3a3c0a ("PATCH scripts/kernel-doc") fixed the two
instances of literal braces that Perl 5.28 warns about, but there are
still more than it doesn't warn about.
Escape all left braces that are treated as literal characters. Also
escape literal right braces, for consistency and to avoid confusing
bracket-matching in text editors.
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions"
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE [^\{\}]*})/ at ./scripts/kernel-doc line 1155.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE )/ at ./scripts/kernel-doc line 1179.
Signed-off-by: Valdis Kletnieks <valdis.kletnieks@vt.edu>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The logic with parses array has a bug that prevents it to
parse arrays like:
struct {
...
struct {
u64 msdu[IEEE80211_NUM_TIDS + 1];
...
...
Fix the parser to accept it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
I find the __sched annotations unaesthetic in the kernel-doc. Remove
them like we remove __inline, __weak, __init and so on.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing. On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.
As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational. Sphinx output is unchanged
after these are applied. Then, at the end, there's a tweak to stop messing
with literal blocks.
If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.
Add the SPDX header while I'm in the neighborhood. The source itself just
says "GNU General Public License", but it also refers people to the COPYING
file for further information. Since COPYING says 2.0-only, that is what I
have put into the header.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The parser at kernel-doc rejects names with dots in the middle.
Fix it, in order to support nested structs/unions.
Tested-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When function description includes brackets after the function name as
suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script
omits the function name from "Scanning doc for" report.
Extending match for identifier name with optional brackets fixes this
issue.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::
if (desperate)
run_in_circles();
The ".. code-block::" directive can also be used to this end. kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx. The result is
unsightly markup instead of a useful code snippet.
Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them. It's ugly, but that means it fits
in well with the rest of the script.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen. Delete an unused variable and add a
couple of comments while I'm at it.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move the top-level prototype-processing code out of process_file().
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Also group the pseudo-global $leading_space variable with its peers.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move this code out of process_file() in the name of readability and
maintainability.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Begin the process of splitting up the nearly 500-line process_file()
function by moving STATE_NORMAL processing to a separate function.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.
The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead. This will make the
subsequent process_file() splitup easier.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
XML escaping is a worry that came with DocBook, which we no longer have any
dealings with. So get rid of the useless xml_escape()/xml_unescape()
functions. No change to the generated output.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The logic with inhibits warnings for definitions that is not
output is incomplete: it doesn't cover the cases where
OUTPUT_INTERNAL and OUTPUT_EXPORTED are used.
As the most common case is OUTPUT_ALL, place it first,
in order to optimize a litte bit the check logic.
Fixes: 2defb27292 ("scripts: kernel-doc: apply filtering rules to warnings")
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When kernel-doc is called with output selection filters,
it will be called lots of time for a single file. If
there is a warning present there, it means that it may
print hundreds of identical warnings.
Worse than that, the -function NAME actually filters only
functions. So, it makes no sense at all to print warnings
for structs or enums.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};
Handling it requires to split each parameter. Change the logic
to allow such definitions.
In order to test the new nested logic, the following file
was used to test
<code>
struct foo { int a; }; /* Just to avoid errors if compiled */
/**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning */
/* private: */
int undoc_privat; /* is undocumented but private, no warning */
/* public: */
int undoc_public; /* is undocumented, cause a warning */
};
</code>
It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Function arguments are different than usual ones. So, an
special logic is needed in order to handle such arguments
on nested structs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.
However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().
I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.
While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The check_sections() function has a $nested parameter, meant
to identify when a nested struct is present. As we now have
a logic that handles it, get rid of such parameter.
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are several places within the Kernel tree with nested
structs/unions, like this one:
struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};
Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};
**Members**
``name``
name of the clock
With is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'
However, there's nothing wrong with this kernel-doc markup: everything
is documented there.
It makes sense to document all fields there. So, add a
way for the core to parse those structs.
With this patch, all documented fields will properly generate
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx has a hard time dealing with tabs, causing it to
misinterpret paragraph continuation.
As we're now mainly focused on supporting ReST output,
replace tabs by spaces, in order to avoid troubles when
the output is parsed by Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Right now, if kernel-doc is called without arguments, it
defaults to man pages. IMO, it makes more sense to
default to ReST, as this is the output that it is most
used nowadays, and it easier to check if everything got
parsed fine on an enriched text mode format.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
