docs: doc-guide: parse-headers.rst update its documentation

userspace API files has an additional vantage: Sphinx will generate warnings

if a symbol is not found at the documentation. That helps to keep the

uAPI documentation in sync with the Kernel changes.

The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such

The :ref:`parse_headers.py <parse_headers>` provides a way to generate such

cross-references. It has to be called via Makefile, while building the

documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example

about how to use it inside the Kernel tree.

.. _parse_headers:

parse_headers.pl

^^^^^^^^^^^^^^^^

tools/docs/parse_headers.py

^^^^^^^^^^^^^^^^^^^^^^^^^^^

NAME

****

parse_headers.pl - parse a C file, in order to identify functions, structs,

parse_headers.py - parse a C file, in order to identify functions, structs,

enums and defines and create cross-references to a Sphinx book.

USAGE

*****

parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``

SYNOPSIS

********

\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Where <options> can be: --debug, --help or --usage.

OPTIONS

*******

\ **--debug**\

 Put the script in verbose mode, useful for debugging.

\ **--usage**\

 Prints a brief help message and exits.

\ **--help**\

 Prints a more detailed help message and exits.

DESCRIPTION

***********

Convert a C header or source file (C_FILE), into a reStructuredText

Converts a C header or source file ``FILE_IN`` into a ReStructured Text

included via ..parsed-literal block with cross-references for the

documentation files that describe the API. It accepts an optional

EXCEPTIONS_FILE with describes what elements will be either ignored or

be pointed to a non-default reference.

``FILE_RULES`` file to describe what elements will be either ignored or

be pointed to a non-default reference type/name.

The output is written at the (OUT_FILE).

The output is written at ``FILE_OUT``.

It is capable of identifying defines, functions, structs, typedefs,

enums and enum symbols and create cross-references for all of them.

It is also capable of distinguish #define used for specifying a Linux

ioctl.

It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum``

and enum ``symbol``, creating cross-references for all of them.

The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\  or \ **replace**\ .

It is also capable of distinguishing ``#define`` used for specifying

Linux-specific macros used to define ``ioctl``.

The syntax for the ignore tag is:

The optional ``FILE_RULES`` 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`

ignore \ **type**\  \ **name**\

POSITIONAL ARGUMENTS

********************

The \ **ignore**\  means that it won't generate cross references for a

\ **name**\  symbol of type \ **type**\ .

  ``FILE_IN``

      Input C file

The syntax for the replace tag is:

  ``FILE_OUT``

      Output RST file

  ``FILE_RULES``

      Exceptions file (optional)

replace \ **type**\  \ **name**\  \ **new_value**\

The \ **replace**\  means that it will generate cross references for a

\ **name**\  symbol of type \ **type**\ , but, instead of using the default

replacement rule, it will use \ **new_value**\ .

For both statements, \ **type**\  can be either one of the following:

OPTIONS

*******

  ``-h``, ``--help``

      show a help message and exit

  ``-d``, ``--debug``

      Increase debug level. Can be used multiple times

  ``-t``, ``--toc``

      instead of a literal block, outputs a TOC table at the RST file

\ **ioctl**\

 The ignore or replace statement will apply to ioctl definitions like:

DESCRIPTION

***********

 #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)

Creates an enriched version of a Kernel header file with cross-links

to each C data structure type, from ``FILE_IN``, formatting it with

reStructuredText notation, either as-is or as a table of contents.

It accepts an optional ``FILE_RULES`` which describes what elements will be

either ignored or be pointed to a non-default reference, and optionally

defines the C namespace to be used.

It is meant to allow having more comprehensive documentation, where

uAPI headers will create cross-reference links to the code.

\ **define**\

The output is written at the (``FILE_OUT``).

 The ignore or replace statement will apply to any other #define found

 at C_FILE.

The ``FILE_RULES`` may contain contain three types of statements:

**ignore**, **replace** and **namespace**.

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:

\ **typedef**\

    ignore *type* *symbol*

 The ignore or replace statement will apply to typedef statements at C_FILE.

Removes the symbol from reference generation.

2. Replace rules:

    replace *type* *old_symbol* *new_reference*

\ **struct**\

    Replaces *old_symbol* with a *new_reference*.

    The *new_reference* can be:

 The ignore or replace statement will apply to the name of struct statements

 at C_FILE.

    - A simple symbol name;

    - A full Sphinx reference.

3. Namespace rules

    namespace *namespace*

\ **enum**\

    Sets C *namespace* to be used during cross-reference generation. Can

    be overridden by replace rules.

 The ignore or replace statement will apply to the name of enum statements

 at C_FILE.

On ignore and replace rules, *type* can be:

    - ioctl:

        for defines of the form ``_IO*``, e.g., ioctl definitions

    - define:

        for other defines

\ **symbol**\

    - symbol:

        for symbols defined within enums;

 The ignore or replace statement will apply to the name of enum value

 at C_FILE.

    - typedef:

        for typedefs;

 For replace statements, \ **new_value**\  will automatically use :c:type:

 references for \ **typedef**\ , \ **enum**\  and \ **struct**\  types. It will use :ref:

 for \ **ioctl**\ , \ **define**\  and \ **symbol**\  types. The type of reference can

 also be explicitly defined at the replace statement.

    - enum:

        for the name of a non-anonymous enum;

    - struct:

        for structs.

EXAMPLES

********

- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``::

    ignore define _VIDEODEV2_H

- On an data structure like this enum::

Ignore a #define _VIDEODEV2_H at the C_FILE.

ignore symbol PRIVATE

    enum foo { BAR1, BAR2, PRIVATE };

On a struct like:

  It won't generate cross-references for ``PRIVATE``::

enum foo { BAR1, BAR2, PRIVATE };

    ignore symbol PRIVATE

It won't generate cross-references for \ **PRIVATE**\ .

  At the same struct, instead of creating one cross reference per symbol,

  make them all point to the ``enum foo`` C type::

    replace symbol BAR1 :c:type:\`foo\`

    replace symbol BAR2 :c:type:\`foo\`

On a struct like:

enum foo { BAR1, BAR2, PRIVATE };

It will make the BAR1 and BAR2 enum symbols to cross reference the foo

symbol at the C domain.

- Use C namespace ``MC`` for all symbols at ``FILE_IN``::

    namespace MC

BUGS

****

*********

Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.

Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.

License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.

d'avviso se un simbolo non viene trovato nella documentazione. Questo permette

di mantenere allineate la documentazione della uAPI (API spazio utente)

con le modifiche del kernel.

Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti.

Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi riferimenti.

Esso dev'essere invocato attraverso un Makefile, mentre si genera la

documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel

consultate ``Documentation/userspace-api/media/Makefile``.

.. _it_parse_headers:

parse_headers.pl

parse_headers.py

^^^^^^^^^^^^^^^^

NOME

****

parse_headers.pl - analizza i file C al fine di identificare funzioni,

parse_headers.py - analizza i file C al fine di identificare funzioni,

strutture, enumerati e definizioni, e creare riferimenti per Sphinx

SINTASSI

********

\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

\ **parse_headers.py**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]

Dove <options> può essere: --debug, --usage o --help.

有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例

C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号，

Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。

:ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。

:ref:`parse_headers.py <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。

在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅

``Documentation/userspace-api/media/Makefile`` 。

.. _parse_headers_zh:

parse_headers.pl

parse_headers.py

----------------

脚本名称

~~~~~~~~

parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档

parse_headers.py——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档

创建交叉引用。

~~~~~~~~

\ **parse_headers.pl**\  [<选项>] <C文件> <输出文件> [<例外文件>]

\ **parse_headers.py**\  [<选项>] <C文件> <输出文件> [<例外文件>]

<选项> 可以是： --debug, --help 或 --usage 。