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