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. 193