projects/linux·blob master · refs

188 lines · 4.9 KiB

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