Commit | Line | Data |
---|---|---|
2dde123b MCC |
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 vantage: 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.pl <parse_headers>` provide a way to generate such | |
12 | cross-references. It has to be called via Makefile, while building the | |
13 | documentation. Please see ``Documentation/media/Makefile`` for an example | |
14 | about how to use it inside the Kernel tree. | |
15 | ||
16 | .. _parse_headers: | |
17 | ||
327f5a75 | 18 | parse_headers.pl |
2dde123b MCC |
19 | ^^^^^^^^^^^^^^^^ |
20 | ||
327f5a75 MCC |
21 | NAME |
22 | **** | |
23 | ||
24 | ||
25 | parse_headers.pl - parse a C file, in order to identify functions, structs, | |
26 | enums and defines and create cross-references to a Sphinx book. | |
27 | ||
28 | ||
327f5a75 MCC |
29 | SYNOPSIS |
30 | ******** | |
31 | ||
32 | ||
33 | \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] | |
34 | ||
f3821276 | 35 | Where <options> can be: --debug, --help or --usage. |
327f5a75 MCC |
36 | |
37 | ||
327f5a75 MCC |
38 | OPTIONS |
39 | ******* | |
40 | ||
41 | ||
42 | ||
43 | \ **--debug**\ | |
44 | ||
45 | Put the script in verbose mode, useful for debugging. | |
46 | ||
47 | ||
48 | ||
c3396656 | 49 | \ **--usage**\ |
327f5a75 MCC |
50 | |
51 | Prints a brief help message and exits. | |
52 | ||
53 | ||
54 | ||
c3396656 | 55 | \ **--help**\ |
327f5a75 | 56 | |
c3396656 | 57 | Prints a more detailed help message and exits. |
327f5a75 MCC |
58 | |
59 | ||
327f5a75 MCC |
60 | DESCRIPTION |
61 | *********** | |
62 | ||
63 | ||
64 | Convert a C header or source file (C_FILE), into a ReStructured Text | |
65 | included via ..parsed-literal block with cross-references for the | |
66 | documentation files that describe the API. It accepts an optional | |
67 | EXCEPTIONS_FILE with describes what elements will be either ignored or | |
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, functions, structs, typedefs, | |
73 | enums and enum symbols and create cross-references for all of them. | |
74 | It is also capable of distinguish #define used for specifying a Linux | |
75 | ioctl. | |
76 | ||
77 | The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . | |
78 | ||
79 | The syntax for the ignore tag is: | |
80 | ||
81 | ||
82 | ignore \ **type**\ \ **name**\ | |
83 | ||
84 | The \ **ignore**\ means that it won't generate cross references for a | |
85 | \ **name**\ symbol of type \ **type**\ . | |
86 | ||
87 | The syntax for the replace tag is: | |
88 | ||
89 | ||
90 | replace \ **type**\ \ **name**\ \ **new_value**\ | |
91 | ||
92 | The \ **replace**\ means that it will generate cross references for a | |
93 | \ **name**\ symbol of type \ **type**\ , but, instead of using the default | |
94 | replacement rule, it will use \ **new_value**\ . | |
95 | ||
96 | For both statements, \ **type**\ can be either one of the following: | |
97 | ||
98 | ||
99 | \ **ioctl**\ | |
100 | ||
101 | The ignore or replace statement will apply to ioctl definitions like: | |
102 | ||
103 | #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) | |
104 | ||
105 | ||
106 | ||
107 | \ **define**\ | |
108 | ||
109 | The ignore or replace statement will apply to any other #define found | |
110 | at C_FILE. | |
111 | ||
112 | ||
113 | ||
114 | \ **typedef**\ | |
115 | ||
116 | The ignore or replace statement will apply to typedef statements at C_FILE. | |
117 | ||
118 | ||
119 | ||
120 | \ **struct**\ | |
121 | ||
122 | The ignore or replace statement will apply to the name of struct statements | |
123 | at C_FILE. | |
124 | ||
125 | ||
126 | ||
127 | \ **enum**\ | |
128 | ||
129 | The ignore or replace statement will apply to the name of enum statements | |
130 | at C_FILE. | |
131 | ||
132 | ||
133 | ||
134 | \ **symbol**\ | |
135 | ||
c1ec85ff | 136 | The ignore or replace statement will apply to the name of enum value |
327f5a75 MCC |
137 | at C_FILE. |
138 | ||
139 | For replace statements, \ **new_value**\ will automatically use :c:type: | |
140 | references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: | |
141 | for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can | |
142 | also be explicitly defined at the replace statement. | |
143 | ||
144 | ||
145 | ||
327f5a75 MCC |
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 \ **PRIVATE**\ . | |
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 cross reference the foo | |
173 | symbol at the C domain. | |
174 | ||
175 | ||
327f5a75 MCC |
176 | BUGS |
177 | **** | |
178 | ||
179 | ||
32590819 | 180 | Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> |
327f5a75 MCC |
181 | |
182 | ||
327f5a75 MCC |
183 | COPYRIGHT |
184 | ********* | |
185 | ||
186 | ||
32590819 | 187 | Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. |
327f5a75 | 188 | |
93431e06 | 189 | License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. |
327f5a75 MCC |
190 | |
191 | This is free software: you are free to change and redistribute it. | |
192 | There is NO WARRANTY, to the extent permitted by law. |