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 vantage: 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.pl <parse_headers>` provide a way to generate such
 12cross-references. It has to be called via Makefile, while building the
 13documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
 14about how to use it inside the Kernel tree.
 15
 16.. _parse_headers:
 17
 18parse_headers.pl
 19^^^^^^^^^^^^^^^^
 20
 21NAME
 22****
 23
 24
 25parse_headers.pl - parse a C file, in order to identify functions, structs,
 26enums and defines and create cross-references to a Sphinx book.
 27
 28
 29SYNOPSIS
 30********
 31
 32
 33\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
 34
 35Where <options> can be: --debug, --help or --usage.
 36
 37
 38OPTIONS
 39*******
 40
 41
 42
 43\ **--debug**\
 44
 45 Put the script in verbose mode, useful for debugging.
 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
 60DESCRIPTION
 61***********
 62
 63
 64Convert a C header or source file (C_FILE), into a reStructuredText
 65included via ..parsed-literal block with cross-references for the
 66documentation files that describe the API. It accepts an optional
 67EXCEPTIONS_FILE with describes what elements will be either ignored or
 68be pointed to a non-default reference.
 69
 70The output is written at the (OUT_FILE).
 71
 72It is capable of identifying defines, functions, structs, typedefs,
 73enums and enum symbols and create cross-references for all of them.
 74It is also capable of distinguish #define used for specifying a Linux
 75ioctl.
 76
 77The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\  or \ **replace**\ .
 78
 79The syntax for the ignore tag is:
 80
 81
 82ignore \ **type**\  \ **name**\
 83
 84The \ **ignore**\  means that it won't generate cross references for a
 85\ **name**\  symbol of type \ **type**\ .
 86
 87The syntax for the replace tag is:
 88
 89
 90replace \ **type**\  \ **name**\  \ **new_value**\
 91
 92The \ **replace**\  means that it will generate cross references for a
 93\ **name**\  symbol of type \ **type**\ , but, instead of using the default
 94replacement rule, it will use \ **new_value**\ .
 95
 96For 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
136 The ignore or replace statement will apply to the name of enum value
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
146EXAMPLES
147********
148
149
150ignore define _VIDEODEV2_H
151
152
153Ignore a #define _VIDEODEV2_H at the C_FILE.
154
155ignore symbol PRIVATE
156
157
158On a struct like:
159
160enum foo { BAR1, BAR2, PRIVATE };
161
162It won't generate cross-references for \ **PRIVATE**\ .
163
164replace symbol BAR1 :c:type:\`foo\`
165replace symbol BAR2 :c:type:\`foo\`
166
167
168On a struct like:
169
170enum foo { BAR1, BAR2, PRIVATE };
171
172It will make the BAR1 and BAR2 enum symbols to cross reference the foo
173symbol at the C domain.
174
175
176BUGS
177****
178
179
180Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
181
182
183COPYRIGHT
184*********
185
186
187Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
188
189License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
190
191This is free software: you are free to change and redistribute it.
192There is NO WARRANTY, to the extent permitted by law.

  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 vantage: 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.pl <parse_headers>` provide a way to generate such
 12cross-references. It has to be called via Makefile, while building the
 13documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
 14about how to use it inside the Kernel tree.
 15
 16.. _parse_headers:
 17
 18parse_headers.pl
 19^^^^^^^^^^^^^^^^
 20
 21NAME
 22****
 23
 24
 25parse_headers.pl - parse a C file, in order to identify functions, structs,
 26enums and defines and create cross-references to a Sphinx book.
 27
 28
 29SYNOPSIS
 30********
 31
 32
 33\ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
 34
 35Where <options> can be: --debug, --help or --usage.
 36
 37
 38OPTIONS
 39*******
 40
 41
 42
 43\ **--debug**\
 44
 45 Put the script in verbose mode, useful for debugging.
 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
 60DESCRIPTION
 61***********
 62
 63
 64Convert a C header or source file (C_FILE), into a ReStructured Text
 65included via ..parsed-literal block with cross-references for the
 66documentation files that describe the API. It accepts an optional
 67EXCEPTIONS_FILE with describes what elements will be either ignored or
 68be pointed to a non-default reference.
 69
 70The output is written at the (OUT_FILE).
 71
 72It is capable of identifying defines, functions, structs, typedefs,
 73enums and enum symbols and create cross-references for all of them.
 74It is also capable of distinguish #define used for specifying a Linux
 75ioctl.
 76
 77The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\  or \ **replace**\ .
 78
 79The syntax for the ignore tag is:
 80
 81
 82ignore \ **type**\  \ **name**\
 83
 84The \ **ignore**\  means that it won't generate cross references for a
 85\ **name**\  symbol of type \ **type**\ .
 86
 87The syntax for the replace tag is:
 88
 89
 90replace \ **type**\  \ **name**\  \ **new_value**\
 91
 92The \ **replace**\  means that it will generate cross references for a
 93\ **name**\  symbol of type \ **type**\ , but, instead of using the default
 94replacement rule, it will use \ **new_value**\ .
 95
 96For 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
136 The ignore or replace statement will apply to the name of enum value
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
146EXAMPLES
147********
148
149
150ignore define _VIDEODEV2_H
151
152
153Ignore a #define _VIDEODEV2_H at the C_FILE.
154
155ignore symbol PRIVATE
156
157
158On a struct like:
159
160enum foo { BAR1, BAR2, PRIVATE };
161
162It won't generate cross-references for \ **PRIVATE**\ .
163
164replace symbol BAR1 :c:type:\`foo\`
165replace symbol BAR2 :c:type:\`foo\`
166
167
168On a struct like:
169
170enum foo { BAR1, BAR2, PRIVATE };
171
172It will make the BAR1 and BAR2 enum symbols to cross reference the foo
173symbol at the C domain.
174
175
176BUGS
177****
178
179
180Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
181
182
183COPYRIGHT
184*********
185
186
187Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
188
189License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
190
191This is free software: you are free to change and redistribute it.
192There is NO WARRANTY, to the extent permitted by law.