@@ -8,170 +8,165 @@ between the code and the documentation. Adding cross-references for
88userspace API files has an additional vantage: Sphinx will generate warnings
99if a symbol is not found at the documentation. That helps to keep the
1010uAPI documentation in sync with the Kernel changes.
11- The :ref: `parse_headers.pl <parse_headers >` provide a way to generate such
11+ The :ref: `parse_headers.py <parse_headers >` provides a way to generate such
1212cross-references. It has to be called via Makefile, while building the
1313documentation. Please see ``Documentation/userspace-api/media/Makefile `` for an example
1414about how to use it inside the Kernel tree.
1515
1616.. _parse_headers :
1717
18- parse_headers.pl
19- ^^^^^^^^^^^^^^^^
18+ tools/docs/ parse_headers.py
19+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
2020
2121NAME
2222****
2323
24-
25- parse_headers.pl - parse a C file, in order to identify functions, structs,
24+ parse_headers.py - parse a C file, in order to identify functions, structs,
2625enums and defines and create cross-references to a Sphinx book.
2726
27+ USAGE
28+ *****
29+
30+ parse-headers.py [-h] [-d] [-t] ``FILE_IN `` ``FILE_OUT `` ``FILE_RULES ``
2831
2932SYNOPSIS
3033********
3134
32-
33- \ **parse_headers.pl **\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
34-
35- Where <options> can be: --debug, --help or --usage.
36-
37-
38- OPTIONS
39- *******
40-
41-
42-
43- \ **--debug **\
44-
45- Put the script in verbose mode, useful for debugging.
46-
47-
48-
49- \ **--usage **\
50-
51- Prints a brief help message and exits.
52-
53-
54-
55- \ **--help **\
56-
57- Prints a more detailed help message and exits.
58-
59-
60- DESCRIPTION
61- ***********
62-
63-
64- Convert a C header or source file (C_FILE), into a reStructuredText
35+ Converts a C header or source file ``FILE_IN `` into a ReStructured Text
6536included via ..parsed-literal block with cross-references for the
6637documentation files that describe the API. It accepts an optional
67- EXCEPTIONS_FILE with describes what elements will be either ignored or
68- be pointed to a non-default reference.
69-
70- The output is written at the (OUT_FILE).
38+ ``FILE_RULES `` file to describe what elements will be either ignored or
39+ be pointed to a non-default reference type/name.
7140
72- It is capable of identifying defines, functions, structs, typedefs,
73- enums and enum symbols and create cross-references for all of them.
74- It is also capable of distinguish #define used for specifying a Linux
75- ioctl.
41+ The output is written at ``FILE_OUT ``.
7642
77- The EXCEPTIONS_FILE contain two types of statements: \ **ignore **\ or \ **replace **\ .
43+ It is capable of identifying ``define ``, ``struct ``, ``typedef ``, ``enum ``
44+ and enum ``symbol ``, creating cross-references for all of them.
7845
79- The syntax for the ignore tag is:
46+ It is also capable of distinguishing ``#define `` used for specifying
47+ Linux-specific macros used to define ``ioctl ``.
8048
49+ The optional ``FILE_RULES `` contains a set of rules like::
8150
82- ignore \ **type **\ \ **name **\
51+ ignore ioctl VIDIOC_ENUM_FMT
52+ replace ioctl VIDIOC_DQBUF vidioc_qbuf
53+ replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
8354
84- The \ ** ignore ** \ means that it won't generate cross references for a
85- \ ** name ** \ symbol of type \ ** type ** \ .
55+ POSITIONAL ARGUMENTS
56+ ********************
8657
87- The syntax for the replace tag is:
58+ ``FILE_IN ``
59+ Input C file
8860
61+ ``FILE_OUT ``
62+ Output RST file
8963
90- replace \ **type **\ \ **name **\ \ **new_value **\
64+ ``FILE_RULES ``
65+ Exceptions file (optional)
9166
92- The \ **replace **\ means that it will generate cross references for a
93- \ **name **\ symbol of type \ **type **\ , but, instead of using the default
94- replacement rule, it will use \ **new_value **\ .
95-
96- For both statements, \ **type **\ can be either one of the following:
67+ OPTIONS
68+ *******
9769
70+ ``-h ``, ``--help ``
71+ show a help message and exit
72+ ``-d ``, ``--debug ``
73+ Increase debug level. Can be used multiple times
74+ ``-t ``, ``--toc ``
75+ instead of a literal block, outputs a TOC table at the RST file
9876
99- \ **ioctl **\
10077
101- The ignore or replace statement will apply to ioctl definitions like:
78+ DESCRIPTION
79+ ***********
10280
103- #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
81+ Creates an enriched version of a Kernel header file with cross-links
82+ to each C data structure type, from ``FILE_IN ``, formatting it with
83+ reStructuredText notation, either as-is or as a table of contents.
10484
85+ It accepts an optional ``FILE_RULES `` which describes what elements will be
86+ either ignored or be pointed to a non-default reference, and optionally
87+ defines the C namespace to be used.
10588
89+ It is meant to allow having more comprehensive documentation, where
90+ uAPI headers will create cross-reference links to the code.
10691
107- \ ** define **\
92+ The output is written at the (`` FILE_OUT ``).
10893
109- The ignore or replace statement will apply to any other #define found
110- at C_FILE .
94+ The `` FILE_RULES `` may contain contain three types of statements:
95+ ** ignore **, ** replace ** and ** namespace ** .
11196
97+ By default, it create rules for all symbols and defines, but it also
98+ allows parsing an exception file. Such file contains a set of rules
99+ using the syntax below:
112100
101+ 1. Ignore rules:
113102
114- \ ** typedef **\
103+ ignore * type * * symbol *
115104
116- The ignore or replace statement will apply to typedef statements at C_FILE .
105+ Removes the symbol from reference generation .
117106
107+ 2. Replace rules:
118108
109+ replace *type * *old_symbol * *new_reference *
119110
120- \ **struct **\
111+ Replaces *old_symbol * with a *new_reference *.
112+ The *new_reference * can be:
121113
122- The ignore or replace statement will apply to the name of struct statements
123- at C_FILE .
114+ - A simple symbol name;
115+ - A full Sphinx reference .
124116
117+ 3. Namespace rules
125118
119+ namespace *namespace *
126120
127- \ **enum **\
121+ Sets C *namespace * to be used during cross-reference generation. Can
122+ be overridden by replace rules.
128123
129- The ignore or replace statement will apply to the name of enum statements
130- at C_FILE.
124+ On ignore and replace rules, *type * can be:
131125
126+ - ioctl:
127+ for defines of the form ``_IO* ``, e.g., ioctl definitions
132128
129+ - define:
130+ for other defines
133131
134- \ **symbol **\
132+ - symbol:
133+ for symbols defined within enums;
135134
136- The ignore or replace statement will apply to the name of enum value
137- at C_FILE.
135+ - typedef:
136+ for typedefs;
138137
139- For replace statements, \ **new_value **\ will automatically use :c: type:
140- references for \ **typedef **\ , \ **enum **\ and \ **struct **\ types. It will use :ref:
141- for \ **ioctl **\ , \ **define **\ and \ **symbol **\ types. The type of reference can
142- also be explicitly defined at the replace statement.
138+ - enum:
139+ for the name of a non-anonymous enum;
143140
141+ - struct:
142+ for structs.
144143
145144
146145EXAMPLES
147146********
148147
148+ - Ignore a define ``_VIDEODEV2_H `` at ``FILE_IN ``::
149149
150- ignore define _VIDEODEV2_H
151-
152-
153- Ignore a #define _VIDEODEV2_H at the C_FILE.
154-
155- ignore symbol PRIVATE
156-
150+ ignore define _VIDEODEV2_H
157151
158- On a struct like:
152+ - On an data structure like this enum: :
159153
160- enum foo { BAR1, BAR2, PRIVATE };
154+ enum foo { BAR1, BAR2, PRIVATE };
161155
162- It won't generate cross-references for \ ** PRIVATE ** \ .
156+ It won't generate cross-references for `` PRIVATE``::
163157
164- replace symbol BAR1 :c: type:\` foo\`
165- replace symbol BAR2 :c: type:\` foo\`
158+ ignore symbol PRIVATE
166159
160+ At the same struct, instead of creating one cross reference per symbol,
161+ make them all point to the ``enum foo`` C type::
167162
168- On a struct like:
163+ replace symbol BAR1 :c:type:\`foo\`
164+ replace symbol BAR2 :c:type:\`foo\`
169165
170- enum foo { BAR1, BAR2, PRIVATE };
171166
172- It will make the BAR1 and BAR2 enum symbols to cross reference the foo
173- symbol at the C domain.
167+ - Use C namespace ``MC `` for all symbols at ``FILE_IN ``::
174168
169+ namespace MC
175170
176171BUGS
177172****
@@ -184,7 +179,7 @@ COPYRIGHT
184179*********
185180
186181
187- Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung @kernel.org>.
182+ Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <mchehab+huawei @kernel.org>.
188183
189184License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
190185
0 commit comments