1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
===========================
Including uAPI header files
===========================
Sometimes, it is useful to include header files and C example codes in
order to describe the userspace API and to generate cross-references
between the code and the documentation. Adding cross-references for
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
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
^^^^^^^^^^^^^^^^
NAME
****
parse_headers.pl - parse a C file, in order to identify functions, structs,
enums and defines and create cross-references to a Sphinx book.
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 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.
The output is written at the (OUT_FILE).
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 EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ .
The syntax for the ignore tag is:
ignore \ **type**\ \ **name**\
The \ **ignore**\ means that it won't generate cross references for a
\ **name**\ symbol of type \ **type**\ .
The syntax for the replace tag is:
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:
\ **ioctl**\
The ignore or replace statement will apply to ioctl definitions like:
#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
\ **define**\
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_FILE.
\ **struct**\
The ignore or replace statement will apply to the name of struct statements
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 reference can
also be explicitly defined at the replace statement.
EXAMPLES
********
ignore define _VIDEODEV2_H
Ignore a #define _VIDEODEV2_H at the C_FILE.
ignore symbol PRIVATE
On a struct like:
enum foo { BAR1, BAR2, PRIVATE };
It won't generate cross-references for \ **PRIVATE**\ .
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.
BUGS
****
Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
COPYRIGHT
*********
Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
|
