0001 ===========================
0002 Including uAPI header files
0003 ===========================
0004
0005 Sometimes, it is useful to include header files and C example codes in
0006 order to describe the userspace API and to generate cross-references
0007 between the code and the documentation. Adding cross-references for
0008 userspace API files has an additional vantage: Sphinx will generate warnings
0009 if a symbol is not found at the documentation. That helps to keep the
0010 uAPI documentation in sync with the Kernel changes.
0011 The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such
0012 cross-references. It has to be called via Makefile, while building the
0013 documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example
0014 about how to use it inside the Kernel tree.
0015
0016 .. _parse_headers:
0017
0018 parse_headers.pl
0019 ^^^^^^^^^^^^^^^^
0020
0021 NAME
0022 ****
0023
0024
0025 parse_headers.pl - parse a C file, in order to identify functions, structs,
0026 enums and defines and create cross-references to a Sphinx book.
0027
0028
0029 SYNOPSIS
0030 ********
0031
0032
0033 \ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
0034
0035 Where <options> can be: --debug, --help or --usage.
0036
0037
0038 OPTIONS
0039 *******
0040
0041
0042
0043 \ **--debug**\
0044
0045 Put the script in verbose mode, useful for debugging.
0046
0047
0048
0049 \ **--usage**\
0050
0051 Prints a brief help message and exits.
0052
0053
0054
0055 \ **--help**\
0056
0057 Prints a more detailed help message and exits.
0058
0059
0060 DESCRIPTION
0061 ***********
0062
0063
0064 Convert a C header or source file (C_FILE), into a ReStructured Text
0065 included via ..parsed-literal block with cross-references for the
0066 documentation files that describe the API. It accepts an optional
0067 EXCEPTIONS_FILE with describes what elements will be either ignored or
0068 be pointed to a non-default reference.
0069
0070 The output is written at the (OUT_FILE).
0071
0072 It is capable of identifying defines, functions, structs, typedefs,
0073 enums and enum symbols and create cross-references for all of them.
0074 It is also capable of distinguish #define used for specifying a Linux
0075 ioctl.
0076
0077 The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ .
0078
0079 The syntax for the ignore tag is:
0080
0081
0082 ignore \ **type**\ \ **name**\
0083
0084 The \ **ignore**\ means that it won't generate cross references for a
0085 \ **name**\ symbol of type \ **type**\ .
0086
0087 The syntax for the replace tag is:
0088
0089
0090 replace \ **type**\ \ **name**\ \ **new_value**\
0091
0092 The \ **replace**\ means that it will generate cross references for a
0093 \ **name**\ symbol of type \ **type**\ , but, instead of using the default
0094 replacement rule, it will use \ **new_value**\ .
0095
0096 For both statements, \ **type**\ can be either one of the following:
0097
0098
0099 \ **ioctl**\
0100
0101 The ignore or replace statement will apply to ioctl definitions like:
0102
0103 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
0104
0105
0106
0107 \ **define**\
0108
0109 The ignore or replace statement will apply to any other #define found
0110 at C_FILE.
0111
0112
0113
0114 \ **typedef**\
0115
0116 The ignore or replace statement will apply to typedef statements at C_FILE.
0117
0118
0119
0120 \ **struct**\
0121
0122 The ignore or replace statement will apply to the name of struct statements
0123 at C_FILE.
0124
0125
0126
0127 \ **enum**\
0128
0129 The ignore or replace statement will apply to the name of enum statements
0130 at C_FILE.
0131
0132
0133
0134 \ **symbol**\
0135
0136 The ignore or replace statement will apply to the name of enum value
0137 at C_FILE.
0138
0139 For replace statements, \ **new_value**\ will automatically use :c:type:
0140 references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref:
0141 for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can
0142 also be explicitly defined at the replace statement.
0143
0144
0145
0146 EXAMPLES
0147 ********
0148
0149
0150 ignore define _VIDEODEV2_H
0151
0152
0153 Ignore a #define _VIDEODEV2_H at the C_FILE.
0154
0155 ignore symbol PRIVATE
0156
0157
0158 On a struct like:
0159
0160 enum foo { BAR1, BAR2, PRIVATE };
0161
0162 It won't generate cross-references for \ **PRIVATE**\ .
0163
0164 replace symbol BAR1 :c:type:\`foo\`
0165 replace symbol BAR2 :c:type:\`foo\`
0166
0167
0168 On a struct like:
0169
0170 enum foo { BAR1, BAR2, PRIVATE };
0171
0172 It will make the BAR1 and BAR2 enum symbols to cross reference the foo
0173 symbol at the C domain.
0174
0175
0176 BUGS
0177 ****
0178
0179
0180 Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
0181
0182
0183 COPYRIGHT
0184 *********
0185
0186
0187 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
0188
0189 License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
0190
0191 This is free software: you are free to change and redistribute it.
0192 There is NO WARRANTY, to the extent permitted by law.
