mirror of
https://github.com/torvalds/linux.git
synced 2026-11-20 13:03:48 +00:00
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
164 lines
5.9 KiB
Python
164 lines
5.9 KiB
Python
#!/usr/bin/env python3
|
|
# SPDX-License-Identifier: GPL-2.0
|
|
# Copyright(c) 2026: Mauro Carvalho Chehab <[email protected]>.
|
|
|
|
import re
|
|
|
|
from kdoc.kdoc_re import KernRe
|
|
from kdoc.c_lex import CMatch, CTokenizer
|
|
|
|
struct_args_pattern = r"([^,)]+)"
|
|
|
|
|
|
class CTransforms:
|
|
"""
|
|
Data class containing a long set of transformations to turn
|
|
structure member prefixes, and macro invocations and variables
|
|
into something we can parse and generate kdoc for.
|
|
"""
|
|
|
|
#
|
|
# NOTE:
|
|
# Due to performance reasons, place CMatch rules before KernRe,
|
|
# as this avoids running the C parser every time.
|
|
#
|
|
|
|
#: Transforms for structs and unions.
|
|
struct_xforms = [
|
|
(CMatch("__attribute__"), ""),
|
|
(CMatch("__aligned"), ""),
|
|
(CMatch("__counted_by"), ""),
|
|
(CMatch("__counted_by_(le|be)"), ""),
|
|
(CMatch("__counted_by_ptr"), ""),
|
|
(CMatch("__guarded_by"), ""),
|
|
(CMatch("__pt_guarded_by"), ""),
|
|
(CMatch("__packed"), ""),
|
|
(CMatch("CRYPTO_MINALIGN_ATTR"), ""),
|
|
(CMatch("__private"), ""),
|
|
(CMatch("__rcu"), ""),
|
|
(CMatch("____cacheline_aligned_in_smp"), ""),
|
|
(CMatch("____cacheline_aligned"), ""),
|
|
(CMatch("__cacheline_group_(?:begin|end)"), ""),
|
|
(CMatch("__ETHTOOL_DECLARE_LINK_MODE_MASK"), r"DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)"),
|
|
(CMatch("DECLARE_PHY_INTERFACE_MASK",),r"DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)"),
|
|
(CMatch("DECLARE_BITMAP"), r"unsigned long \1[BITS_TO_LONGS(\2)]"),
|
|
(CMatch("DECLARE_HASHTABLE"), r"unsigned long \1[1 << ((\2) - 1)]"),
|
|
(CMatch("DECLARE_KFIFO"), r"\2 *\1"),
|
|
(CMatch("DECLARE_KFIFO_PTR"), r"\2 *\1"),
|
|
(CMatch("DECLARE_KHOSER_PTR"), r"\2 \1"),
|
|
(CMatch("DECLARE_PIDS"), r"struct pid *\1[(\2) + 1]"),
|
|
(CMatch("(?:__)?DECLARE_FLEX_ARRAY"), r"\1 \2[]"),
|
|
(CMatch("DEFINE_DMA_UNMAP_ADDR"), r"dma_addr_t \1"),
|
|
(CMatch("DEFINE_DMA_UNMAP_LEN"), r"__u32 \1"),
|
|
(CMatch("VIRTIO_DECLARE_FEATURES"), r"union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }"),
|
|
(CMatch("__SYSFS_FUNCTION_ALTERNATIVE"), r"union { \1+ }"),
|
|
(CMatch("__attribute__"), ""),
|
|
|
|
#
|
|
# Macro __struct_group() creates a union with an anonymous
|
|
# and a non-anonymous struct, depending on the parameters. We only
|
|
# need one of those at kernel-doc, as we won't be documenting the same
|
|
# members twice.
|
|
#
|
|
(CMatch("struct_group"), r"struct { \2+ };"),
|
|
(CMatch("struct_group_attr"), r"struct { \3+ };"),
|
|
(CMatch("struct_group_tagged"), r"struct { \3+ };"),
|
|
(CMatch("__struct_group"), r"struct { \4+ };"),
|
|
(CMatch("context_lock_struct"), r"struct \1"),
|
|
]
|
|
|
|
#: Transforms for function prototypes.
|
|
function_xforms = [
|
|
(CMatch("static"), ""),
|
|
(CMatch("extern"), ""),
|
|
(CMatch("asmlinkage"), ""),
|
|
(CMatch("inline"), ""),
|
|
(CMatch("__inline__"), ""),
|
|
(CMatch("__inline"), ""),
|
|
(CMatch("__always_inline"), ""),
|
|
(CMatch("noinline"), ""),
|
|
(CMatch("__FORTIFY_INLINE"), ""),
|
|
(CMatch("__init"), ""),
|
|
(CMatch("__init_or_module"), ""),
|
|
(CMatch("__exit"), ""),
|
|
(CMatch("__deprecated"), ""),
|
|
(CMatch("__flatten"), ""),
|
|
(CMatch("__meminit"), ""),
|
|
(CMatch("__must_check"), ""),
|
|
(CMatch("__weak"), ""),
|
|
(CMatch("__sched"), ""),
|
|
(CMatch("__always_unused"), ""),
|
|
(CMatch("__maybe_unused"), ""),
|
|
(CMatch("__printf"), ""),
|
|
(CMatch("__(?:re)?alloc_size"), ""),
|
|
(CMatch("__diagnose_as"), ""),
|
|
(CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
|
|
(CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
|
|
(CMatch("__cond_acquires"), ""),
|
|
(CMatch("__cond_releases"), ""),
|
|
(CMatch("__acquires"), ""),
|
|
(CMatch("__releases"), ""),
|
|
(CMatch("__must_hold"), ""),
|
|
(CMatch("__must_not_hold"), ""),
|
|
(CMatch("__must_hold_shared"), ""),
|
|
(CMatch("__cond_acquires_shared"), ""),
|
|
(CMatch("__acquires_shared"), ""),
|
|
(CMatch("__releases_shared"), ""),
|
|
(CMatch("__no_context_analysis"), ""),
|
|
(CMatch("__attribute_const__"), ""),
|
|
(CMatch("__attribute__"), ""),
|
|
(CMatch("STATIC_IFN_KUNIT"), ""),
|
|
(CMatch("INLINE_IFN_KUNIT"), ""),
|
|
|
|
#
|
|
# HACK: this is similar to process_export() hack. It is meant to
|
|
# drop _noproof from function name. See for instance:
|
|
# ahash_request_alloc kernel-doc declaration at include/crypto/hash.h.
|
|
#
|
|
(KernRe("_noprof"), ""),
|
|
]
|
|
|
|
#: Transforms for variable prototypes.
|
|
var_xforms = [
|
|
(CMatch("__read_mostly"), ""),
|
|
(CMatch("__ro_after_init"), ""),
|
|
(CMatch("__guarded_by"), ""),
|
|
(CMatch("__pt_guarded_by"), ""),
|
|
(CMatch("LIST_HEAD"), r"struct list_head \1"),
|
|
(CMatch("DECLARE_PER_CPU"), r"\1 \2[PER_CPU]; }"),
|
|
|
|
(KernRe(r"(?://.*)$"), ""),
|
|
(KernRe(r"(?:/\*.*\*/)"), ""),
|
|
(KernRe(r";$"), ""),
|
|
]
|
|
|
|
#: Transforms main dictionary used at apply_transforms().
|
|
xforms = {
|
|
"struct": struct_xforms,
|
|
"func": function_xforms,
|
|
"var": var_xforms,
|
|
}
|
|
|
|
def apply(self, xforms_type, source):
|
|
"""
|
|
Apply a set of transforms to a block of source.
|
|
|
|
As tokenizer is used here, this function also remove comments
|
|
at the end.
|
|
"""
|
|
if xforms_type not in self.xforms:
|
|
return source
|
|
|
|
if isinstance(source, str):
|
|
source = CTokenizer(source)
|
|
|
|
for search, subst in self.xforms[xforms_type]:
|
|
#
|
|
# KernRe only accept strings.
|
|
#
|
|
if isinstance(search, KernRe):
|
|
source = str(source)
|
|
|
|
source = search.sub(subst, source)
|
|
return str(source)
|