Commit Graph

284 Commits

Author SHA1 Message Date
Linus Torvalds
498a1cf902 Kbuild updates for v6.3
- Change V=1 option to print both short log and full command log.
 
  - Allow V=1 and V=2 to be combined as V=12.
 
  - Make W=1 detect wrong .gitignore files.
 
  - Tree-wide cleanups for unused command line arguments passed to Clang.
 
  - Stop using -Qunused-arguments with Clang.
 
  - Make scripts/setlocalversion handle only correct release tags instead
    of any arbitrary annotated tag.
 
  - Create Debian and RPM source packages without cleaning the source tree.
 
  - Various cleanups for packaging.
 -----BEGIN PGP SIGNATURE-----
 
 iQJJBAABCgAzFiEEbmPs18K1szRHjPqEPYsBB53g2wYFAmP7iHoVHG1hc2FoaXJv
 eUBrZXJuZWwub3JnAAoJED2LAQed4NsGL/cQAK9q5rsNL5a2LgTbm89ORA+UV+ST
 hrAoGo5DkJHUbVH53oPzyLynFBZPvUzLK8yjApjXkyAzy2hXYnj+vbTs0s+JVCFL
 owS4NB0YP+tpHGuy8bGpWI0GMZSMwmspUteqxk86zuH8uQVAhnCaeV1/Cr6Aqj1h
 2jk1FZid3/h7qEkEgu5U8soeyFnV6VhAT6Ie5yfZ2O2RdsSqPUh6vfKrgdyW4RWz
 gito0SOUwvjIDfSmTnIIacUibisPRv2OW29OvmDp1aXj5rMhe3UfOznVE3NR86yl
 ZbWDAIm6KYT8V1ASOoAUR80qent9IPKytThLK9BVEQCT6bsujCZMvhYhhEvO30TF
 Lzsdr+FrES//xag3+hgc63FEied2xxWGQG1cRtzAhfRL9tJ03+mY1omoW6SyKqW/
 Gc9PIcTgQbCIrkeL0HuAI1q3I1vkvHXInJKtGkoHh1J9aJ8v5gQpwGA+DDRUnA+A
 LQSeEbT2Hf3MoF4CqZRnConvfhlMuLI+j5v54YPrhokxXmv7u807kjfwMFTiZ/+m
 CJFlEMf9YRv3pi8g/AYyGAg5ZQigCwzOCRUC5kguFqzZdgnjiI907GEL804lm1Mg
 lpx/HtYPyxwWEd2XyU6/C9AEIl3gm7MBd6b1tD54Tb/VmE+AvjS/O9jFYXZqnAnM
 Llv4BfK/cQKwHb6o
 =HpFZ
 -----END PGP SIGNATURE-----

Merge tag 'kbuild-v6.3' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild

Pull Kbuild updates from Masahiro Yamada:

 - Change V=1 option to print both short log and full command log

 - Allow V=1 and V=2 to be combined as V=12

 - Make W=1 detect wrong .gitignore files

 - Tree-wide cleanups for unused command line arguments passed to Clang

 - Stop using -Qunused-arguments with Clang

 - Make scripts/setlocalversion handle only correct release tags instead
   of any arbitrary annotated tag

 - Create Debian and RPM source packages without cleaning the source
   tree

 - Various cleanups for packaging

* tag 'kbuild-v6.3' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: (74 commits)
  kbuild: rpm-pkg: remove unneeded KERNELRELEASE from modules/headers_install
  docs: kbuild: remove description of KBUILD_LDS_MODULE
  .gitattributes: use 'dts' diff driver for *.dtso files
  kbuild: deb-pkg: improve the usability of source package
  kbuild: deb-pkg: fix binary-arch and clean in debian/rules
  kbuild: tar-pkg: use tar rules in scripts/Makefile.package
  kbuild: make perf-tar*-src-pkg work without relying on git
  kbuild: deb-pkg: switch over to source format 3.0 (quilt)
  kbuild: deb-pkg: make .orig tarball a hard link if possible
  kbuild: deb-pkg: hide KDEB_SOURCENAME from Makefile
  kbuild: srcrpm-pkg: create source package without cleaning
  kbuild: rpm-pkg: build binary packages from source rpm
  kbuild: deb-pkg: create source package without cleaning
  kbuild: add a tool to list files ignored by git
  Documentation/llvm: add Chimera Linux, Google and Meta datacenters
  setlocalversion: use only the correct release tag for git-describe
  setlocalversion: clean up the construction of version output
  .gitignore: ignore *.cover and *.mbx
  kbuild: remove --include-dir MAKEFLAG from top Makefile
  kbuild: fix trivial typo in comment
  ...
2023-02-26 11:53:25 -08:00
Jonathan Neuschäfer
3bdd9f075f scripts: kernel-doc: Remove workaround for @param... syntax
Commit 43756e347f ("scripts/kernel-doc: Add support for named variable
macro arguments") improved how named variable macro arguments are
handled, and changed how they are documented in kerneldoc comments
from "@param...", to "@param", deprecating the old syntax.

All users of the old syntax have since been converted, so this commit
finally removes support for it.

The output of "make htmldocs" is the same with and without this commit.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Link: https://lore.kernel.org/r/20230129150435.1510400-1-j.neuschaefer@gmx.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2023-01-31 13:55:44 -07:00
Masahiro Yamada
c0d3b83100 kbuild: do not print extra logs for V=2
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>
2023-01-22 23:43:32 +09:00
Linus Torvalds
48ea09cdda hardening updates for v6.2-rc1
- 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
  ...
2022-12-14 12:20:00 -08:00
Linus Torvalds
08cdc21579 iommufd for 6.2
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()
  ...
2022-12-14 09:15:43 -08:00
Jason Gunthorpe
632ce1377d scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export
Parse EXPORT_SYMBOL_NS_GPL() in addition to EXPORT_SYMBOL_GPL() for use
with the -export flag.

Link: https://lore.kernel.org/r/4-v6-a196d26f289e+11787-iommufd_jgg@nvidia.com
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
2022-11-29 16:34:15 -04:00
Kees Cook
03699f271d string: Rewrite and add more kern-doc for the str*() functions
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>
2022-10-28 16:07:57 -07:00
Jonathan Corbet
eaf710ceb5 docs: improve the HTML formatting of kerneldoc comments
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>
2022-10-18 16:29:29 -06:00
Niklas Söderlund
df4bf98ec2 scripts: kernel-doc: Always increment warnings counter
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>
2022-06-13 11:07:45 -06:00
Mauro Carvalho Chehab
b79dfef0e2 scripts/kernel-doc: change the line number meta info
In order to make it more standard and ReST compatible,
change the meta-tag used with --enable-lineno from:

        #define LINENO

to
        .. LINENO

In practice, no	functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2022-03-28 13:53:46 -06:00
Akira Yokosawa
e334f873eb docs: scripts/kernel-doc: Detect absence of FILE arg
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>
2022-02-24 12:13:19 -07:00
Tomasz Warniełło
2b306ecaf5 scripts: kernel-doc: Refresh the copyright lines
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>
2022-02-24 10:52:47 -07:00
Tomasz Warniełło
258092a890 scripts: kernel-doc: Drop obsolete comments
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>
2022-02-24 10:52:47 -07:00
Tomasz Warniełło
252b47da9f scripts: kernel-doc: Replace the usage function
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
834cf6b903 scripts: kernel-doc: Translate the "Other parameters" subsection of OPTIONS
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
c15de5a19a scripts: kernel-doc: Translate the "Output selection modifiers" subsection of OPTIONS
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
9c77f108f4 scripts: kernel-doc: Translate the "Output selection" subsection of OPTIONS
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
dd803b04b0 scripts: kernel-doc: Translate the "Output format selection modifier" subsection of OPTIONS
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
2875f78708 scripts: kernel-doc: Translate the "Output format selection" subsection of OPTIONS
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
f1583922bf scripts: kernel-doc: Translate the DESCRIPTION section
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>
2022-02-24 10:52:46 -07:00
Tomasz Warniełło
43caf1a682 scripts: kernel-doc: Relink argument parsing error handling to pod2usage
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>
2022-02-24 10:52:45 -07:00
Tomasz Warniełło
a5cdaea525 scripts: kernel-doc: Add the basic POD sections
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>
2022-02-24 10:52:45 -07:00
Linus Torvalds
624ad333d4 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.
 -----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
  ...
2021-11-02 22:11:39 -07:00
Randy Dunlap
603bdf5d6c kernel-doc: support DECLARE_PHY_INTERFACE_MASK()
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>
2021-11-01 11:28:35 -06:00
Kees Cook
3080ea5553 stddef: Introduce DECLARE_FLEX_ARRAY() helper
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>
2021-10-18 12:28:52 -07:00
Kees Cook
a40a8a1103 scripts: kernel-doc: Ignore __alloc_size() attribute
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>
2021-10-12 14:11:06 -06:00
Kees Cook
50d7bd38c3 stddef: Introduce struct_group() helper macro
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>
2021-09-25 08:20:47 -07:00
Laurent Pinchart
bed4ed3057 scripts/kernel-doc: Override -Werror from KCFLAGS with KDOC_WERROR
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>
2021-08-12 08:58:13 -06:00
Aditya Srivastava
e86bdb2437 scripts: kernel-doc: reduce repeated regex expressions into variables
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>
2021-05-17 11:21:16 -06:00
Matthew Wilcox
80342d484a kernel-doc: Add support for __deprecated
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>
2021-04-27 09:59:04 -06:00
Aditya Srivastava
f9bbc12ccb scripts: kernel-doc: improve parsing for kernel-doc comments syntax
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>
2021-04-15 15:26:06 -06:00
Aditya Srivastava
3e58e83915 scripts: kernel-doc: add warning for comment not following kernel-doc syntax
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>
2021-03-29 17:08:28 -06:00
Jonathan Corbet
212209cff8 docs: kernel-doc: properly recognize parameter lines with colons
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>
2021-03-26 13:16:35 -06:00
Mauro Carvalho Chehab
8d295fbad6 kernel-doc: better handle '::' sequences
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>
2021-03-25 12:50:27 -06:00
Mauro Carvalho Chehab
0b54c2e34b scripts/kernel-doc: ignore identifier on anonymous enums
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>
2021-03-08 17:10:24 -07:00
Aditya Srivastava
084aa00162 scripts: kernel-doc: fix attribute capture in function parsing
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>
2021-03-08 16:04:20 -07:00
Aditya Srivastava
a746fe32cd scripts: kernel-doc: fix typedef support for struct/union parsing
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>
2021-03-06 17:36:51 -07:00
Aditya Srivastava
336ced2de6 scripts: kernel-doc: fix array element capture in pointer-to-func parsing
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>
2021-02-22 14:20:36 -07:00
Michal Wajdeczko
06a755d626 scripts/kernel-doc: add internal hyperlink to DOC: sections
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>
2021-01-28 16:35:00 -07:00
Mauro Carvalho Chehab
52042e2db4 scripts: kernel-doc: validate kernel-doc markup with the actual names
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>
2021-01-18 13:33:26 -07:00
Mauro Carvalho Chehab
7d2c6b1edf scripts: kernel-doc: fix parsing function-like typedefs
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>
2020-12-03 15:56:14 -07:00
Andy Shevchenko
ae5b17e464 scripts: kernel-doc: Restore anonymous enum parsing
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>
2020-11-13 15:09:19 -07:00
Mauro Carvalho Chehab
72b97d0b91 scripts: kernel-doc: use :c:union when needed
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>
2020-10-28 11:26:09 -06:00
Mauro Carvalho Chehab
7efc6c4295 scripts: kernel-doc: split typedef complex regex
The typedef regex for function prototypes are very complex.
Split them into 3 separate regex and then join them using
qr.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/3a4af999a0d62d4ab9dfae1cdefdfcad93383356.1603792384.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-10-28 11:13:34 -06:00
Mauro Carvalho Chehab
6b80975c63 scripts: kernel-doc: fix typedef parsing
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>
2020-10-28 11:13:29 -06:00
Mauro Carvalho Chehab
6e9e415854 scripts: kernel-doc: try to use c:function if possible
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>
2020-10-15 07:49:37 +02:00
Mauro Carvalho Chehab
5ef09c96d4 scripts: kernel-doc: fix line number handling
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>
2020-10-15 07:49:37 +02:00
Mauro Carvalho Chehab
93351d4196 scripts: kernel-doc: allow passing desired Sphinx C domain dialect
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>
2020-10-15 07:49:36 +02:00
Mauro Carvalho Chehab
ed8348e23a scripts: kernel-doc: don't mangle with parameter list
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>
2020-10-15 07:49:36 +02:00
Mauro Carvalho Chehab
47bcacfd2b scripts: kernel-doc: fix typedef identification
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>
2020-10-15 07:49:36 +02:00