Debian Codegraph @

Documentation/doc-guide/parse-headers.rst

raw
1 ===========================
2 Including uAPI header files
3 ===========================
4
5 Sometimes, it is useful to include header files and C example codes in
6 order to describe the userspace API and to generate cross-references
7 between the code and the documentation. Adding cross-references for
8 userspace API files has an additional advantage: Sphinx will generate warnings
9 if a symbol is not found at the documentation. That helps to keep the
10 uAPI documentation in sync with the Kernel changes.
11 The :ref:`parse_headers.py <parse_headers>` provides a way to generate such
12 cross-references. It has to be called via Makefile, while building the
13 documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
14 about how to use it inside the Kernel tree.
15
16 .. _parse_headers:
17
18 tools/docs/parse_headers.py
19 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
20
21 NAME
22 ****
23
24 parse_headers.py - parse a C file, in order to identify functions, structs,
25 enums and defines and create cross-references to a Sphinx book.
26
27 USAGE
28 *****
29
30 parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
31
32 SYNOPSIS
33 ********
34
35 Converts a C header or source file ``FILE_IN`` into a ReStructured Text
36 included via ..parsed-literal block with cross-references for the
37 documentation files that describe the API. It accepts an optional
38 ``FILE_RULES`` file to describe what elements will be either ignored or
39 be pointed to a non-default reference type/name.
40
41 The output is written at ``FILE_OUT``.
42
43 It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum``
44 and enum ``symbol``, creating cross-references for all of them.
45
46 It is also capable of distinguishing ``#define`` used for specifying
47 Linux-specific macros used to define ``ioctl``.
48
49 The optional ``FILE_RULES`` contains a set of rules like::
50
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`
54
55 POSITIONAL ARGUMENTS
56 ********************
57
58 ``FILE_IN``
59 Input C file
60
61 ``FILE_OUT``
62 Output RST file
63
64 ``FILE_RULES``
65 Exceptions file (optional)
66
67 OPTIONS
68 *******
69
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
76
77
78 DESCRIPTION
79 ***********
80
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.
84
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.
88
89 It is meant to allow having more comprehensive documentation, where
90 uAPI headers will create cross-reference links to the code.
91
92 The output is written at the ``FILE_OUT``.
93
94 The ``FILE_RULES`` may contain contain three types of statements:
95 **ignore**, **replace** and **namespace**.
96
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:
100
101 1. Ignore rules:
102
103 ignore *type* *symbol*
104
105 Removes the symbol from reference generation.
106
107 2. Replace rules:
108
109 replace *type* *old_symbol* *new_reference*
110
111 Replaces *old_symbol* with a *new_reference*.
112 The *new_reference* can be:
113
114 - A simple symbol name;
115 - A full Sphinx reference.
116
117 3. Namespace rules
118
119 namespace *namespace*
120
121 Sets C *namespace* to be used during cross-reference generation. Can
122 be overridden by replace rules.
123
124 On ignore and replace rules, *type* can be:
125
126 - ioctl:
127 for defines of the form ``_IO*``, e.g., ioctl definitions
128
129 - define:
130 for other defines
131
132 - symbol:
133 for symbols defined within enums;
134
135 - typedef:
136 for typedefs;
137
138 - enum:
139 for the name of a non-anonymous enum;
140
141 - struct:
142 for structs.
143
144
145 EXAMPLES
146 ********
147
148 - Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``::
149
150 ignore define _VIDEODEV2_H
151
152 - On an data structure like this enum::
153
154 enum foo { BAR1, BAR2, PRIVATE };
155
156 It won't generate cross-references for ``PRIVATE``::
157
158 ignore symbol PRIVATE
159
160 At the same struct, instead of creating one cross reference per symbol,
161 make them all point to the ``enum foo`` C type::
162
163 replace symbol BAR1 :c:type:\`foo\`
164 replace symbol BAR2 :c:type:\`foo\`
165
166
167 - Use C namespace ``MC`` for all symbols at ``FILE_IN``::
168
169 namespace MC
170
171 BUGS
172 ****
173
174
175 Report bugs to Mauro Carvalho Chehab <[email protected]>
176
177
178 COPYRIGHT
179 *********
180
181
182 Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <[email protected]>.
183
184 License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
185
186 This is free software: you are free to change and redistribute it.
187 There is NO WARRANTY, to the extent permitted by law.