From nobody Fri Dec 19 19:01:30 2025 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3FBC02ECD28; Sat, 8 Nov 2025 09:37:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1762594639; cv=none; b=bQxldRnGv+fsw/DDKW94bEfsgTOdjRtlSMsTgr+LVHuzQ/KBTIm1mvhz9MyioyJrGyokVjjF9j1T9thJ86lpZ9YYxTUyzcaM21CbzMvJbc/MDqT6LMEbTS98Qpb+6Nj1+ZQKTYrX1U04fhH8u6e84Kr8FXZh4BCOAC9HqQ7JA6o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1762594639; c=relaxed/simple; bh=/cI6VjvtvWO0Jp/lxRJssMuHKbiAHhJq+1lYCdrQmcM=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type; b=NbNz/UwbyWxQp/NW0H/Tsks6vZm9oxiKKWkO7K5AFxjzCVYV0O+a8rCAyLMKUimHoP1YBlkXY1CRImvMuaKcZsPW7tj9TQ0O9gSaeVDz8r9oY/wSYkShhbR0hOzt8tU5Lc5XoO50Bl5fzK/c9aF8l0XcooJxrdC770lr2GS/NyQ= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EKRj4Sh5; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="EKRj4Sh5" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 9CB15C113D0; Sat, 8 Nov 2025 09:37:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1762594638; bh=/cI6VjvtvWO0Jp/lxRJssMuHKbiAHhJq+1lYCdrQmcM=; h=From:To:Cc:Subject:Date:From; b=EKRj4Sh5NdDK7Ew0ou2CPH3qjo+JzmWsmjL8ErwGafMXiyb1F2hzVdW9xxF1TOUPs aQK0GPK4THqMnsBgMU+2KoHW82dZVh3qDnKO8W0hKZ9r4mZ9S1bsv1oj7Rp4hzrMvL izWSyjT+M2yM968Nq0XZ1mfj6B5mutBjbZeDOqhMa3OqJDI26pqG2NGZfD7lD4eDRY /x5IZcYIRbxfT+8OX6kWHC4/bzCGoMOozJEx00UvefmNZEZYoHrk/DQb4DUrXys4bc Y7NhOS+wParys/4trSYaD1UGRXpTnd3lS1ZOBZPy+upnoe7qFtVhtLRTD955iu8s56 hmH8zjiCWZ2bA== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1vHfNk-000000033KL-2D3x; Sat, 08 Nov 2025 10:37:16 +0100 From: Mauro Carvalho Chehab To: "Jonathan Corbet" , Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , Alex Shi , Dongliang Mu , Federico Vaga , Randy Dunlap , Yanteng Si , linux-kernel@vger.kernel.org Subject: [PATCH v4] docs: doc-guide: parse-headers.rst update its documentation Date: Sat, 8 Nov 2025 10:37:04 +0100 Message-ID: <1f9025dc98dc58da3cc31f3343d5027f351be338.1762594622.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.1 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Besides converting from Perl to Python, parse-headers has gained some new functionality and was moved to tools/docs. Update its documentation accordingly. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/9391a0f0-7c92-42aa-8190-28255b22e= 131@infradead.org/ Acked-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- Documentation/doc-guide/parse-headers.rst | 195 +++++++++--------- .../it_IT/doc-guide/parse-headers.rst | 8 +- .../zh_CN/doc-guide/parse-headers.rst | 8 +- 3 files changed, 103 insertions(+), 108 deletions(-) diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-= guide/parse-headers.rst index 204b025f1349..954f3285ddf6 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -8,170 +8,165 @@ between the code and the documentation. Adding cross-re= ferences for userspace API files has an additional vantage: Sphinx will generate warnin= gs 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 ` provide a way to generate such +The :ref:`parse_headers.py ` 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`` f= or an example about how to use it inside the Kernel tree. =20 .. _parse_headers: =20 -parse_headers.pl -^^^^^^^^^^^^^^^^ +tools/docs/parse_headers.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 NAME **** =20 - -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. =20 +USAGE +***** + +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` =20 SYNOPSIS ******** =20 +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 +``FILE_RULES`` file to describe what elements will be either ignored or +be pointed to a non-default reference type/name. =20 -\ **parse_headers.pl**\ [] [] +The output is written at ``FILE_OUT``. =20 -Where can be: --debug, --help or --usage. +It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` +and enum ``symbol``, creating cross-references for all of them. =20 +It is also capable of distinguishing ``#define`` used for specifying +Linux-specific macros used to define ``ioctl``. + +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_mot= ion_det` + +POSITIONAL ARGUMENTS +******************** + + ``FILE_IN`` + Input C file + + ``FILE_OUT`` + Output RST file + + ``FILE_RULES`` + Exceptions file (optional) =20 OPTIONS ******* =20 - - -\ **--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. + ``-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 =20 =20 DESCRIPTION *********** =20 +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. =20 -Convert a C header or source file (C_FILE), into a reStructuredText -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. +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. =20 -The output is written at the (OUT_FILE). +It is meant to allow having more comprehensive documentation, where +uAPI headers will create cross-reference links to the code. =20 -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. +The output is written at the (``FILE_OUT``). =20 -The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ *= *replace**\ . +The ``FILE_RULES`` may contain contain three types of statements: +**ignore**, **replace** and **namespace**. =20 -The syntax for the ignore tag is: +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: =20 +1. Ignore rules: =20 -ignore \ **type**\ \ **name**\ + ignore *type* *symbol* =20 -The \ **ignore**\ means that it won't generate cross references for a -\ **name**\ symbol of type \ **type**\ . +Removes the symbol from reference generation. =20 -The syntax for the replace tag is: +2. Replace rules: =20 + replace *type* *old_symbol* *new_reference* =20 -replace \ **type**\ \ **name**\ \ **new_value**\ + Replaces *old_symbol* with a *new_reference*. + The *new_reference* can be: =20 -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**\ . + - A simple symbol name; + - A full Sphinx reference. =20 -For both statements, \ **type**\ can be either one of the following: +3. Namespace rules =20 + namespace *namespace* =20 -\ **ioctl**\ + Sets C *namespace* to be used during cross-reference generation. Can + be overridden by replace rules. =20 - The ignore or replace statement will apply to ioctl definitions like: +On ignore and replace rules, *type* can be: =20 - #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + - ioctl: + for defines of the form ``_IO*``, e.g., ioctl definitions =20 + - define: + for other defines =20 + - symbol: + for symbols defined within enums; =20 -\ **define**\ + - typedef: + for typedefs; =20 - The ignore or replace statement will apply to any other #define found - at C_FILE. - - - -\ **typedef**\ - - The ignore or replace statement will apply to typedef statements at C_FIL= E. - - - -\ **struct**\ - - The ignore or replace statement will apply to the name of struct statemen= ts - at C_FILE. - - - -\ **enum**\ - - The ignore or replace statement will apply to the name of enum statements - at C_FILE. - - - -\ **symbol**\ - - The ignore or replace statement will apply to the name of enum value - at C_FILE. - - 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 r= eference can - also be explicitly defined at the replace statement. + - enum: + for the name of a non-anonymous enum; =20 + - struct: + for structs. =20 =20 EXAMPLES ******** =20 +- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: =20 -ignore define _VIDEODEV2_H + ignore define _VIDEODEV2_H =20 +- On an data structure like this enum:: =20 -Ignore a #define _VIDEODEV2_H at the C_FILE. + enum foo { BAR1, BAR2, PRIVATE }; =20 -ignore symbol PRIVATE + It won't generate cross-references for ``PRIVATE``:: =20 + ignore symbol PRIVATE =20 -On a struct like: + At the same struct, instead of creating one cross reference per symbol, + make them all point to the ``enum foo`` C type:: =20 -enum foo { BAR1, BAR2, PRIVATE }; + replace symbol BAR1 :c:type:\`foo\` + replace symbol BAR2 :c:type:\`foo\` =20 -It won't generate cross-references for \ **PRIVATE**\ . =20 -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``:: =20 + namespace MC =20 BUGS **** @@ -184,7 +179,7 @@ COPYRIGHT ********* =20 =20 -Copyright (c) 2016 by Mauro Carvalho Chehab . +Copyright (c) 2016, 2025 by Mauro Carvalho Chehab . =20 License GPLv2: GNU GPL version 2 . =20 diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b= /Documentation/translations/it_IT/doc-guide/parse-headers.rst index 026a23e49767..b0caa40fe1e9 100644 --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -13,28 +13,28 @@ dello spazio utente ha ulteriori vantaggi: Sphinx gener= er=C3=A0 dei messaggi d'avviso se un simbolo non viene trovato nella documentazione. Questo perm= ette di mantenere allineate la documentazione della uAPI (API spazio utente) con le modifiche del kernel. -Il programma :ref:`parse_headers.pl ` genera questi rife= rimenti. +Il programma :ref:`parse_headers.py ` genera questi rife= rimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera la documentazione. Per avere un esempio su come utilizzarlo all'interno del k= ernel consultate ``Documentation/userspace-api/media/Makefile``. =20 .. _it_parse_headers: =20 -parse_headers.pl +parse_headers.py ^^^^^^^^^^^^^^^^ =20 NOME **** =20 =20 -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 =20 SINTASSI ******** =20 =20 -\ **parse_headers.pl**\ [] [] +\ **parse_headers.py**\ [] [] =20 Dove pu=C3=B2 essere: --debug, --usage o --help. =20 diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b= /Documentation/translations/zh_CN/doc-guide/parse-headers.rst index a08819e904ed..65d9dc5143ff 100644 --- a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -13,20 +13,20 @@ =E6=9C=89=E6=97=B6=EF=BC=8C=E4=B8=BA=E4=BA=86=E6=8F=8F=E8=BF=B0=E7=94=A8= =E6=88=B7=E7=A9=BA=E9=97=B4API=E5=B9=B6=E5=9C=A8=E4=BB=A3=E7=A0=81=E5=92=8C= =E6=96=87=E6=A1=A3=E4=B9=8B=E9=97=B4=E7=94=9F=E6=88=90=E4=BA=A4=E5=8F=89=E5= =BC=95=E7=94=A8=EF=BC=8C=E9=9C=80=E8=A6=81=E5=8C=85=E5=90=AB=E5=A4=B4=E6=96= =87=E4=BB=B6=E5=92=8C=E7=A4=BA=E4=BE=8B C=E4=BB=A3=E7=A0=81=E3=80=82=E4=B8=BA=E7=94=A8=E6=88=B7=E7=A9=BA=E9=97=B4A= PI=E6=96=87=E4=BB=B6=E6=B7=BB=E5=8A=A0=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8= =E8=BF=98=E6=9C=89=E4=B8=80=E4=B8=AA=E5=A5=BD=E5=A4=84=EF=BC=9A=E5=A6=82=E6= =9E=9C=E5=9C=A8=E6=96=87=E6=A1=A3=E4=B8=AD=E6=89=BE=E4=B8=8D=E5=88=B0=E7=9B= =B8=E5=BA=94=E7=AC=A6=E5=8F=B7=EF=BC=8C Sphinx=E5=B0=86=E7=94=9F=E6=88=90=E8=AD=A6=E5=91=8A=E3=80=82=E8=BF=99=E6= =9C=89=E5=8A=A9=E4=BA=8E=E4=BF=9D=E6=8C=81=E7=94=A8=E6=88=B7=E7=A9=BA=E9=97= =B4API=E6=96=87=E6=A1=A3=E4=B8=8E=E5=86=85=E6=A0=B8=E6=9B=B4=E6=94=B9=E5=90= =8C=E6=AD=A5=E3=80=82 -:ref:`parse_headers.pl ` =E6=8F=90=E4=BE=9B=E4=BA=86=E7= =94=9F=E6=88=90=E6=AD=A4=E7=B1=BB=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8=E7=9A= =84=E4=B8=80=E7=A7=8D=E6=96=B9=E6=B3=95=E3=80=82 +:ref:`parse_headers.py ` =E6=8F=90=E4=BE=9B=E4=BA=86=E7= =94=9F=E6=88=90=E6=AD=A4=E7=B1=BB=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8=E7=9A= =84=E4=B8=80=E7=A7=8D=E6=96=B9=E6=B3=95=E3=80=82 =E5=9C=A8=E6=9E=84=E5=BB=BA=E6=96=87=E6=A1=A3=E6=97=B6=EF=BC=8C=E5=BF=85= =E9=A1=BB=E9=80=9A=E8=BF=87Makefile=E8=B0=83=E7=94=A8=E5=AE=83=E3=80=82=E6= =9C=89=E5=85=B3=E5=A6=82=E4=BD=95=E5=9C=A8=E5=86=85=E6=A0=B8=E6=A0=91=E4=B8= =AD=E4=BD=BF=E7=94=A8=E5=AE=83=E7=9A=84=E7=A4=BA=E4=BE=8B=EF=BC=8C=E8=AF=B7= =E5=8F=82=E9=98=85 ``Documentation/userspace-api/media/Makefile`` =E3=80=82 =20 .. _parse_headers_zh: =20 -parse_headers.pl +parse_headers.py ---------------- =20 =E8=84=9A=E6=9C=AC=E5=90=8D=E7=A7=B0 ~~~~~~~~ =20 =20 -parse_headers.pl=E2=80=94=E2=80=94=E8=A7=A3=E6=9E=90=E4=B8=80=E4=B8=AAC=E6= =96=87=E4=BB=B6=EF=BC=8C=E8=AF=86=E5=88=AB=E5=87=BD=E6=95=B0=E3=80=81=E7=BB= =93=E6=9E=84=E4=BD=93=E3=80=81=E6=9E=9A=E4=B8=BE=E3=80=81=E5=AE=9A=E4=B9=89= =E5=B9=B6=E5=AF=B9Sphinx=E6=96=87=E6=A1=A3 +parse_headers.py=E2=80=94=E2=80=94=E8=A7=A3=E6=9E=90=E4=B8=80=E4=B8=AAC=E6= =96=87=E4=BB=B6=EF=BC=8C=E8=AF=86=E5=88=AB=E5=87=BD=E6=95=B0=E3=80=81=E7=BB= =93=E6=9E=84=E4=BD=93=E3=80=81=E6=9E=9A=E4=B8=BE=E3=80=81=E5=AE=9A=E4=B9=89= =E5=B9=B6=E5=AF=B9Sphinx=E6=96=87=E6=A1=A3 =E5=88=9B=E5=BB=BA=E4=BA=A4=E5=8F=89=E5=BC=95=E7=94=A8=E3=80=82 =20 =20 @@ -34,7 +34,7 @@ parse_headers.pl=E2=80=94=E2=80=94=E8=A7=A3=E6=9E=90=E4= =B8=80=E4=B8=AAC=E6=96=87=E4=BB=B6=EF=BC=8C=E8=AF=86=E5=88=AB=E5=87=BD=E6= =95=B0=E3=80=81=E7=BB=93=E6=9E=84=E4=BD=93=E3=80=81=E6=9E=9A=E4=B8=BE=E3=80= =81 ~~~~~~~~ =20 =20 -\ **parse_headers.pl**\ [<=E9=80=89=E9=A1=B9>] <=E8= =BE=93=E5=87=BA=E6=96=87=E4=BB=B6> [<=E4=BE=8B=E5=A4=96=E6=96=87=E4=BB=B6>] +\ **parse_headers.py**\ [<=E9=80=89=E9=A1=B9>] <=E8= =BE=93=E5=87=BA=E6=96=87=E4=BB=B6> [<=E4=BE=8B=E5=A4=96=E6=96=87=E4=BB=B6>] =20 <=E9=80=89=E9=A1=B9> =E5=8F=AF=E4=BB=A5=E6=98=AF=EF=BC=9A --debug, --help = =E6=88=96 --usage =E3=80=82 =20 --=20 2.51.1