1 ===========================
2 Including uAPI header files
3 ===========================
4
5 Sometimes, it is useful to include header file
6 order to describe the userspace API and to gen
7 between the code and the documentation. Adding
8 userspace API files has an additional vantage:
9 if a symbol is not found at the documentation.
10 uAPI documentation in sync with the Kernel cha
11 The :ref:`parse_headers.pl <parse_headers>` pr
12 cross-references. It has to be called via Make
13 documentation. Please see ``Documentation/user
14 about how to use it inside the Kernel tree.
15
16 .. _parse_headers:
17
18 parse_headers.pl
19 ^^^^^^^^^^^^^^^^
20
21 NAME
22 ****
23
24
25 parse_headers.pl - parse a C file, in order to
26 enums and defines and create cross-references
27
28
29 SYNOPSIS
30 ********
31
32
33 \ **parse_headers.pl**\ [<options>] <C_FILE>
34
35 Where <options> can be: --debug, --help or --u
36
37
38 OPTIONS
39 *******
40
41
42
43 \ **--debug**\
44
45 Put the script in verbose mode, useful for de
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), in
65 included via ..parsed-literal block with cross
66 documentation files that describe the API. It
67 EXCEPTIONS_FILE with describes what elements w
68 be pointed to a non-default reference.
69
70 The output is written at the (OUT_FILE).
71
72 It is capable of identifying defines, function
73 enums and enum symbols and create cross-refere
74 It is also capable of distinguish #define used
75 ioctl.
76
77 The EXCEPTIONS_FILE contain two types of state
78
79 The syntax for the ignore tag is:
80
81
82 ignore \ **type**\ \ **name**\
83
84 The \ **ignore**\ means that it won't generat
85 \ **name**\ symbol of type \ **type**\ .
86
87 The syntax for the replace tag is:
88
89
90 replace \ **type**\ \ **name**\ \ **new_valu
91
92 The \ **replace**\ means that it will generat
93 \ **name**\ symbol of type \ **type**\ , but,
94 replacement rule, it will use \ **new_value**\
95
96 For both statements, \ **type**\ can be eithe
97
98
99 \ **ioctl**\
100
101 The ignore or replace statement will apply to
102
103 #define VIDIOC_DBG_S_REGISTER _IOW(
104
105
106
107 \ **define**\
108
109 The ignore or replace statement will apply to
110 at C_FILE.
111
112
113
114 \ **typedef**\
115
116 The ignore or replace statement will apply to
117
118
119
120 \ **struct**\
121
122 The ignore or replace statement will apply to
123 at C_FILE.
124
125
126
127 \ **enum**\
128
129 The ignore or replace statement will apply to
130 at C_FILE.
131
132
133
134 \ **symbol**\
135
136 The ignore or replace statement will apply to
137 at C_FILE.
138
139 For replace statements, \ **new_value**\ wil
140 references for \ **typedef**\ , \ **enum**\
141 for \ **ioctl**\ , \ **define**\ and \ **sym
142 also be explicitly defined at the replace sta
143
144
145
146 EXAMPLES
147 ********
148
149
150 ignore define _VIDEODEV2_H
151
152
153 Ignore a #define _VIDEODEV2_H at the C_FILE.
154
155 ignore symbol PRIVATE
156
157
158 On a struct like:
159
160 enum foo { BAR1, BAR2, PRIVATE };
161
162 It won't generate cross-references for \ **PRI
163
164 replace symbol BAR1 :c:type:\`foo\`
165 replace symbol BAR2 :c:type:\`foo\`
166
167
168 On a struct like:
169
170 enum foo { BAR1, BAR2, PRIVATE };
171
172 It will make the BAR1 and BAR2 enum symbols to
173 symbol at the C domain.
174
175
176 BUGS
177 ****
178
179
180 Report bugs to Mauro Carvalho Chehab <mchehab@k
181
182
183 COPYRIGHT
184 *********
185
186
187 Copyright (c) 2016 by Mauro Carvalho Chehab <mc
188
189 License GPLv2: GNU GPL version 2 <https://gnu.
190
191 This is free software: you are free to change
192 There is NO WARRANTY, to the extent permitted
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.