tools/lib/python/kdoc/xforms_lists.py

Source file repositories/reference/linux-study-clean/tools/lib/python/kdoc/xforms_lists.py

File Facts

System
Linux kernel
Corpus path
tools/lib/python/kdoc/xforms_lists.py
Extension
.py
Size
5521 bytes
Lines
156
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: tools
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# Copyright(c) 2026: Mauro Carvalho Chehab <mchehab@kernel.org>.

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_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("__attribute__"), ""),

        #
        # Macro __struct_group() creates an 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+ };"),
    ]

    #: Transforms for function prototypes.
    function_xforms = [
        (CMatch("static"), ""),
        (CMatch("extern"), ""),
        (CMatch("asmlinkage"), ""),

Annotation

Implementation Notes