Based on kernel version 6.8. Page generated on 2024-03-11 21:26 EST.
| 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.
|
