tools/lib/python/kdoc/parse_data_structs.py

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

File Facts

System
Linux kernel
Corpus path
tools/lib/python/kdoc/parse_data_structs.py
Extension
.py
Size
16842 bytes
Lines
499
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) 2016-2025 by Mauro Carvalho Chehab <mchehab@kernel.org>.
# pylint: disable=R0912,R0915

"""
Parse a source file or header, creating ReStructured Text cross references.

It accepts an optional file to change the default symbol reference or to
suppress symbols from the output.

It is capable of identifying ``define``, function, ``struct``, ``typedef``,
``enum`` and ``enum`` symbols and create cross-references for all of them.
It is also capable of distinguish #define used for specifying a Linux
ioctl.

The optional rules file contains a set of rules like::

    ignore ioctl VIDIOC_ENUM_FMT
    replace ioctl VIDIOC_DQBUF vidioc_qbuf
    replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
"""

import os
import re
import sys


class ParseDataStructs:
    """
    Creates an enriched version of a Kernel header file with cross-links
    to each C data structure type.

    It is meant to allow having a more comprehensive documentation, where
    uAPI headers will create cross-reference links to the code.

    It is capable of identifying ``define``, function, ``struct``, ``typedef``,
    ``enum`` and ``enum`` symbols and create cross-references for all of them.
    It is also capable of distinguish #define used for specifying a Linux
    ioctl.

    By default, it create rules for all symbols and defines, but it also
    allows parsing an exception file. Such file contains a set of rules
    using the syntax below:

    1. Ignore rules::

        ignore <type> <symbol>`

    Removes the symbol from reference generation.

    2. Replace rules::

        replace <type> <old_symbol> <new_reference>

       Replaces how old_symbol with a new reference. The new_reference can be:

        - A simple symbol name;
        - A full Sphinx reference.

    3. Namespace rules::

        namespace <namespace>

       Sets C namespace to be used during cross-reference generation. Can
       be overridden by replace rules.

    On ignore and replace rules, ``<type>`` can be:
        - ``ioctl``: for defines that end with ``_IO*``, e.g. ioctl definitions
        - ``define``: for other defines

Annotation

Implementation Notes