Documentation/doc-guide/parse-headers.rst

   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/userspace-api/media/Makefile`` for an example
  14 about how to use it inside the Kernel tree.
  15
  16 .. _parse_headers:
  17
  18 parse_headers.pl
  19 ^^^^^^^^^^^^^^^^
  20
  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
  29 SYNOPSIS
  30 ********
  31
  32
  33 \ **parse_headers.pl**\  [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
  34
  35 Where <options> can be: --debug, --help or --usage.
  36
  37
  38 OPTIONS
  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
  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
 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
 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
 176 BUGS
 177 ****
 178
 179
 180 Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>
 181
 182
 183 COPYRIGHT
 184 *********
 185
 186
 187 Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
 188
 189 License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
 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.