Commit Graph
21 Commits
Author SHA1 Message Date
Linus Torvalds cb01c6914e Merge tag 'docs-7.4-2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux
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
2026-10-29 07:46:22 -10:00
Pasha Tatashin 4180abdb5d docs: xforms_lists: Handle DECLARE_KHOSER_PTR() struct members
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]>
2026-10-22 09:45:11 -06:00
Linus Torvalds 14c8977403 Merge tag 'docs-7.4' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux
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
  ...
2026-10-20 14:38:38 -10:00
Christian Brauner fd0349aadb pid: add helpers to operate on a struct pid array
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]>
2026-10-12 10:58:20 +02:00
Omokefe Emmanuel Onanaroghene 2d72a4c098 docs: kdoc: parse context_lock_struct() as struct declaration
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]>
2026-09-29 16:59:29 -06:00
Hemanth Selam 09c12a4e05 tools/lib: fix typos in comments
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]>
2026-09-07 10:37:58 -06:00
Randy Dunlap 7bcc15b256 docs: xforms_lists: support DEFINE_IDTENTRY_IRQ()
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]>
2026-08-03 12:57:56 -06:00
Randy Dunlap d42197c735 kdoc: xforms: ignore special static/inline macros
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]>
2026-06-23 14:41:52 -06:00
Randy Dunlap da5e67d0e1 kdoc: xforms_lists: handle DECLARE_PER_CPU() in kernel-doc
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]>
2026-06-23 14:37:25 -06:00
Randy Dunlap 3b61bb3fe1 kernel-doc: xforms: support __SYSFS_FUNCTION_ALTERNATIVE()
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]>
2026-06-23 14:31:25 -06:00
Randy Dunlap 026d7010f1 kdoc: xforms: move context attrs to function_xforms list
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]>
2026-05-15 08:15:54 -06:00
Tudor Ambarus 8bf5a177c3 docs: kernel-doc: python: strip __counted_by_ptr macro
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]>
2026-05-15 08:11:36 -06:00
Randy Dunlap 713e899a68 docs: xforms_lists: allow __maybe_unused in func parameters
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]>
2026-04-27 04:07:06 -06:00
Mauro Carvalho Chehab 7538df7a2d docs: xforms_lists: use CMatch for all identifiers
CMatch is lexically correct and replaces only identifiers,
which is exactly where macro transformations happen.

Use it to make the output safer and ensure that all arguments
will be parsed the right way, even on complex cases.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <86d4a07ff0e054207747fabf38d6bb261b52b5fa.1773770483.git.mchehab+huawei@kernel.org>
2026-03-22 15:02:29 -06:00
Mauro Carvalho Chehab 79d881beb7 docs: kdoc_parser: avoid tokenizing structs everytime
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>
2026-03-22 15:02:29 -06:00
Mauro Carvalho Chehab 2f07ddbd57 docs: xforms_lists: better evaluate struct_group macros
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>
2026-03-22 15:02:29 -06:00
Mauro Carvalho Chehab f63e6163c7 docs: xforms_lists: handle struct_group directly
The previous logic was handling struct_group on two steps.
Remove the previous approach, as CMatch can do it the right
way on a single step.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <da7f879d90e3ffbc1f47771522f212a60df1fab6.1773770483.git.mchehab+huawei@kernel.org>
2026-03-22 15:02:29 -06:00
Mauro Carvalho Chehab 600079fdcf docs: kdoc: replace NestedMatch with CMatch
Our previous approach to solve nested structs were to use
NestedMatch. It works well, but adding support to parse delimiters
is very complex.

Instead, use CMatch, which uses a C tokenizer, making the code more
reliable and simpler.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <900bff66f8093402999f9fe055fbfa3fa33a8d8b.1773770483.git.mchehab+huawei@kernel.org>
2026-03-22 15:02:29 -06:00
Mauro Carvalho Chehab 85c2a51357 docs: kdoc_parser: move nested match transforms to xforms_lists.py
As NestedMatch now has a sub method and a declaration close to
what KernRe does, we can move the rules to xforms_lists and
simplify kdoc_parser a little bit.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <762ce2a58ff024c1b0b6f6a6e05020d1415b8308.1772469446.git.mchehab+huawei@kernel.org>
2026-03-03 10:47:25 -07:00
Randy Dunlap 4ff59bdd93 docs: xforms_lists: ignore context analysis and lock attributes
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>
2026-03-03 10:47:25 -07:00
Mauro Carvalho Chehab d842057c4a docs: kdoc_parser: move transform lists to a separate file
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>
2026-03-03 10:47:25 -07:00