Pull more documentation updates from Jonathan Corbet:
"A handful of late-arriving changes, most of which were ready ahead of
the merge window:
- More Portuguese translation updates
- Some docs-build and self-test fixes
- Bring documentation for the user-space access primitives
in include/linux/uaccess.h into the docs build.
This revealed a number of malformed kerneldoc comments,
which are fixed in a subsequent tweak to uaccess.h"
* tag 'docs-7.4-2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux:
uaccess: fix some erroneous kerneldoc comments
docs/translations/pt_BR: admin-guide: add efi-stub.rst
docs/translations/pt_BR: admin-guide: add kernel-parameters.rst
docs/translations/pt_BR: admin-guide: add bootconfig.rst
docs/translations/pt_BR: admin-guide: add perf-security.rst
docs/translations/pt_BR: admin-guide: add LSM/index.rst
docs/translations/pt_BR: admin-guide: add hw-vuln/index.rst
docs/translations/pt_BR: admin-guide: add cputopology.rst
docs/translations/pt_BR: admin-guide: add sysctl/index.rst
docs/translations/pt_BR: admin-guide: add sysfs-rules.rst
docs/translations/pt_BR: admin-guide: add features.rst
docs: pt_BR: process: translate userspace debugging guide
docs: kerneldoc.py: preserve headings in kernel-doc output
docs: xforms_lists: Handle DECLARE_KHOSER_PTR() struct members
docs: test_doc_build: don't select urllib3 yanked version
docs: test_doc_build: address pylint warnings
docs: test_doc_build: update it to support newer Sphinx versions
docs: test_doc_build: better handle python version
docs: admin-guide: Fix typo in kernel-parameters.txt
docs: core-api: include documentation from linux/uaccess.h
KHO ABI structures declare their preservation pointers with
DECLARE_KHOSER_PTR(name, type), which expands to a union of the pointer
and its physical address. kernel-doc does not know the macro and does
not see the member: it warns that an unnamed member is not described
and that the description of the member is excess.
Translate DECLARE_KHOSER_PTR(name, type) into "type name", as is done
for DECLARE_KFIFO_PTR().
Signed-off-by: Pasha Tatashin <[email protected]>
Message-ID: <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Pull documentation updates from Jonathan Corbet:
"It was a reasonably busy cycle for docs; changes include:
- Add the AGENTS.md symbolic link into the top-level directory in the
hopes that LLMs will read it and produce better work
- The removal of the Assisted-by requirement, as concluded at the
Maintainer Summit
- A new "testdocs" make target to run the documentation unit tests
- Lots of work on the Portuguese, and Chinese translations; there is
now maintenance for the traditional Chinese translations as well
...and the usual pile of minor fixes, documentation updates, etc"
* tag 'docs-7.4' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (125 commits)
docs: add AGENTS.md as a symlink to README
docs: kernel-parameters: adjust reserve_mem build option
docs: kernel-parameters: don't mix cmdline options & build options
docs/ja_JP: translate submitting-patches.rst (review and report tags)
docs: remove Assisted-by references
Revert "docs: landlock: fix ENOMSG condition in create_ruleset kernel-doc"
docs: kdoc: parse context_lock_struct() as struct declaration
docs: timers: hpet: Document userspace API and ioctl commands
docs: timers: hpet: Modernize file references
Documentation: sched-preemption: Add a SPDX license identifier
docs: ABI: sysfs-driver-xdata: use literal blocks for console commands
docs: ABI: sysfs-class-firmware-attributes: use literal blocks for console commands
ABI: sysfs-bus-usb: use literal block for console commands
docs/ABI: testing: aspeed-uart-routing: use literal block for console commands
docs: kernel-parameters: fix a truncated sentence for preempt=lazy
sched/doc: add a preemption model overview
docs: ABI: TMR manager: use literal blocks for console I/O
Documentation/ABI: IFS: use literal blocks for commands
ABI: sysfs-bus-pci: use literal blocks for commands
docs: translations: pt_BR: add debugging index
...
We're about to extend af_unix sockets and coredump code with the ability
to hand out thread-specific pidfds. Add a few simple helpers that allow
to operate on multiple struct pids up to PIDTYPE_MAX with automatic
bounds checking.
Reviewed-by: Alexander Mikhalitsyn <[email protected]>
Reviewed-by: Kuniyuki Iwashima <[email protected]>
Signed-off-by: Andrew Halaney <[email protected]>
Link: https://patch.msgid.link/[email protected]
Signed-off-by: Christian Brauner (Amutable) <[email protected]>
kernel-doc fails to parse struct declarations wrapped in
context_lock_struct(), e.g. struct debugfs_cancellation:
include/linux/debugfs.h:245 ... error: Cannot parse struct or union!
Add a struct transform that expands context_lock_struct() to a plain
struct declaration, and apply the struct transforms to the whole
declaration before split_struct_proto(), matching what dump_var() and
dump_function() already do for their prototypes. The member-only
transform in dump_struct() is then redundant.
Add a regression test for the debugfs_cancellation declaration.
Fixes: 6e530e2e31 ("debugfs: Make debugfs_cancellation a context lock struct")
Signed-off-by: Omokefe Emmanuel Onanaroghene <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Reviewed-by: Aleksandr Loktionov <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Fix typos in comments, reported by scripts/checkpatch.pl using the
misspelling list in scripts/spelling.txt. Only touches comments, no code
changes.
Assisted-by: Cursor:claude-opus-5
Signed-off-by: Hemanth Selam <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Avoid kernel-doc warnings by supported DEFINE_IDTENTRY_IRQ() as a
function transform.
Warning: arch/x86/kernel/apic/apic.c:2157 function parameter
'spurious_interrupt' not described in 'DEFINE_IDTENTRY_IRQ'
Warning: arch/x86/kernel/apic/apic.c:2157 expecting prototype for
spurious_interrupt(). Prototype was for DEFINE_IDTENTRY_IRQ() instead
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c contains 7 (for
now) functions that use STATIC_IFN_KUNIT or INLINE_IFN_KUNIT macros for
function qualifiers (static or not, inline or not).
These cause parse warnings from kernel-doc:
Invalid C declaration: Expected identifier in nested name, got keyword:
struct [error at 29]
STATIC_IFN_KUNIT const struct drm_color_lut * __extract_blob_lut (const
struct drm_property_blob *blob, uint32_t *size)
Handle these in kernel-doc to prevent multiple warnings.
Fixes: 647d1fd046 ("drm/amd/display: Add KUnit test for color helpers")
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Add support for DECLARE_PER_CPU() as a var (variable) as used in
<linux/netfilter/x_tables.h>.
Warning: include/linux/netfilter/x_tables.h:345 function parameter 'seqcount_t' not described in 'DECLARE_PER_CPU'
Warning: include/linux/netfilter/x_tables.h:345 function parameter 'xt_recseq' not described in 'DECLARE_PER_CPU'
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Add support for __SYSFS_FUNCTION_ALTERNATIVE() to create a union of its
members (as though CONFIG_CFI is unset).
Fixes these docs build warnings:
WARNING: include/linux/device.h:117 Invalid param: __SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf)
WARNING: include/linux/device.h:117 struct member '__SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*show' not described in 'device_attribute'
WARNING: include/linux/device.h:117 Invalid param: __SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*store)(struct device *dev, struct device_attribute *attr, const char *buf, size_t count)
WARNING: include/linux/device.h:117 struct member '__SYSFS_FUNCTION_ALTERNATIVE( ssize_t (*store' not described in 'device_attribute'
Signed-off-by: Randy Dunlap <[email protected]>
Reviewed-by: Thomas Weißschuh <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
The context analysis macros are function attributes that should be
in the function_xforms list. Somewhere along the way they were
inserted into the struct_xforms list instead. This causes docs build
warnings to continue to be emitted for context macros.
Move the context analysis macros to the function_xforms list where
they should be to eliminate these warnings.
Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex)
Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
The `__counted_by_ptr` macro was recently introduced [1] to extend
bounds checking semantics to standard dynamically allocated pointers.
However, the new Python implementation of kernel-doc does not currently
recognize it as a compiler attribute. When kernel-doc encounters a
struct member annotated with this macro, it fails to parse the variable
name correctly, resulting in false-positive warnings like:
Warning: ... struct member '__counted_by_ptr(cmdcnt' not described
Add `__counted_by_ptr` to the `struct_xforms` regex list so it gets
safely stripped out during the parsing phase, mirroring the existing
behavior for `__counted_by`. Update the corresponding unit tests.
Link: https://git.kernel.org/torvalds/c/150a04d817d8 [1]
Signed-off-by: Tudor Ambarus <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Kees Cook <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Bart has a patch (not yet merged) that causes kernel-doc warnings:
WARNING: ./include/linux/highmem.h:235 function parameter '__maybe_unused' not described in 'clear_user_pages'
Documentation/mm/highmem:211: ./include/linux/highmem.h:222: WARNING: Error in declarator or parameters
Handle this by adding "__maybe_unused" to the list of known function
parameter modifiers.
Reported-by: kernel test robot <[email protected]>
Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Bart Van Assche <[email protected]>
Reviewed-by: Bart Van Assche <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>
Most of the rules inside CTransforms are of the type CMatch.
Don't re-parse the source code every time.
Doing this doesn't change the output, but makes kdoc almost
as fast as before the tokenizer patches:
# Before tokenizer patches
$ time ./scripts/kernel-doc . -man >original 2>&1
real 0m42.933s
user 0m36.523s
sys 0m1.145s
# After tokenizer patches
$ time ./scripts/kernel-doc . -man >before 2>&1
real 1m29.853s
user 1m23.974s
sys 0m1.237s
# After this patch
$ time ./scripts/kernel-doc . -man >after 2>&1
real 0m48.579s
user 0m45.938s
sys 0m0.988s
$ diff -s before after
Files before and after are identical
Manually checked the differences between original and after
with:
$ diff -U0 -prBw original after|grep -v Warning|grep -v "@@"|less
They're due:
- whitespace fixes;
- struct_group are now better handled;
- several badly-generated man pages from broken inline kernel-doc
markups are now fixed.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <1cc2a4286ebf7d4b2d03fcaf42a1ba9fa09004b9.1773770483.git.mchehab+huawei@kernel.org>
The previous approach were to unwind nested structs/unions.
Now that we have a logic that can handle it well, use it to
ensure that struct_group macros will properly reflect the
actual struct.
Note that the replacemend logic still simplifies the code
a little bit, as the basic build block for struct group is:
union { \
struct { MEMBERS } ATTRS; \
struct __struct_group_tag(TAG) { MEMBERS } ATTRS NAME; \
} ATTRS
There:
- ATTRS is meant to add extra macro attributes like __packed
which we already discard, as they aren't relevant to
document struct members;
- TAG is used only when built with __cplusplus.
So, instead, convert them into just:
struct { MEMBERS };
Please notice that here, we're using the greedy version of the
backrefs, as MEMBERS is actually MEMBERS... on all such macros.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Aleksandr Loktionov <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <24bf2c036b08814d9b4aabc27542fd3b2ff54424.1773770483.git.mchehab+huawei@kernel.org>
Drop context analysis and lock (tracking) attributes to avoid
kernel-doc warnings.
There are now lots of warnings like these:
Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex)
------------------------------------------------------------------------------------------------^
Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
--------------------------------------------------------------------------------------------^
The regex is suggested by Mauro; mine was too greedy. Thanks.
Updated context analysis and lock macros list provided by PeterZ. Thanks.
[mchehab: modified to be applied after xforms_lists split]
Reported-by: Stephen Rothwell <[email protected]>
Closes: https://lore.kernel.org/all/[email protected]/
Signed-off-by: Randy Dunlap <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Aleksandr Loktionov <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <3c7fdfc364a8920f92530b47bdbf4bb29a40371f.1772469446.git.mchehab+huawei@kernel.org>
Over the time, most of the changes at kernel-doc are related
to maintaining a list of transforms to convert macros into pure
C code.
Place such transforms on a separate module, to cleanup the
parser module.
There is an advantage on that: QEMU also uses our own kernel-doc,
but the xforms list there is different. By placing it on a
separate module, we can minimize the differences and make it
easier to keep QEMU in sync with Kernel upstream.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Aleksandr Loktionov <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <ccd74b7589e1fff340a74bf8ed16a974532cb54f.1772469446.git.mchehab+huawei@kernel.org>