1*4882a593Smuzhiyun=========================== 2*4882a593SmuzhiyunIncluding uAPI header files 3*4882a593Smuzhiyun=========================== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunSometimes, it is useful to include header files and C example codes in 6*4882a593Smuzhiyunorder to describe the userspace API and to generate cross-references 7*4882a593Smuzhiyunbetween the code and the documentation. Adding cross-references for 8*4882a593Smuzhiyunuserspace API files has an additional vantage: Sphinx will generate warnings 9*4882a593Smuzhiyunif a symbol is not found at the documentation. That helps to keep the 10*4882a593SmuzhiyunuAPI documentation in sync with the Kernel changes. 11*4882a593SmuzhiyunThe :ref:`parse_headers.pl <parse_headers>` provide a way to generate such 12*4882a593Smuzhiyuncross-references. It has to be called via Makefile, while building the 13*4882a593Smuzhiyundocumentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example 14*4882a593Smuzhiyunabout how to use it inside the Kernel tree. 15*4882a593Smuzhiyun 16*4882a593Smuzhiyun.. _parse_headers: 17*4882a593Smuzhiyun 18*4882a593Smuzhiyunparse_headers.pl 19*4882a593Smuzhiyun^^^^^^^^^^^^^^^^ 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunNAME 22*4882a593Smuzhiyun**** 23*4882a593Smuzhiyun 24*4882a593Smuzhiyun 25*4882a593Smuzhiyunparse_headers.pl - parse a C file, in order to identify functions, structs, 26*4882a593Smuzhiyunenums and defines and create cross-references to a Sphinx book. 27*4882a593Smuzhiyun 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunSYNOPSIS 30*4882a593Smuzhiyun******** 31*4882a593Smuzhiyun 32*4882a593Smuzhiyun 33*4882a593Smuzhiyun\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] 34*4882a593Smuzhiyun 35*4882a593SmuzhiyunWhere <options> can be: --debug, --help or --usage. 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunOPTIONS 39*4882a593Smuzhiyun******* 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun 42*4882a593Smuzhiyun 43*4882a593Smuzhiyun\ **--debug**\ 44*4882a593Smuzhiyun 45*4882a593Smuzhiyun Put the script in verbose mode, useful for debugging. 46*4882a593Smuzhiyun 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun 49*4882a593Smuzhiyun\ **--usage**\ 50*4882a593Smuzhiyun 51*4882a593Smuzhiyun Prints a brief help message and exits. 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun\ **--help**\ 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun Prints a more detailed help message and exits. 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun 60*4882a593SmuzhiyunDESCRIPTION 61*4882a593Smuzhiyun*********** 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun 64*4882a593SmuzhiyunConvert a C header or source file (C_FILE), into a ReStructured Text 65*4882a593Smuzhiyunincluded via ..parsed-literal block with cross-references for the 66*4882a593Smuzhiyundocumentation files that describe the API. It accepts an optional 67*4882a593SmuzhiyunEXCEPTIONS_FILE with describes what elements will be either ignored or 68*4882a593Smuzhiyunbe pointed to a non-default reference. 69*4882a593Smuzhiyun 70*4882a593SmuzhiyunThe output is written at the (OUT_FILE). 71*4882a593Smuzhiyun 72*4882a593SmuzhiyunIt is capable of identifying defines, functions, structs, typedefs, 73*4882a593Smuzhiyunenums and enum symbols and create cross-references for all of them. 74*4882a593SmuzhiyunIt is also capable of distinguish #define used for specifying a Linux 75*4882a593Smuzhiyunioctl. 76*4882a593Smuzhiyun 77*4882a593SmuzhiyunThe EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . 78*4882a593Smuzhiyun 79*4882a593SmuzhiyunThe syntax for the ignore tag is: 80*4882a593Smuzhiyun 81*4882a593Smuzhiyun 82*4882a593Smuzhiyunignore \ **type**\ \ **name**\ 83*4882a593Smuzhiyun 84*4882a593SmuzhiyunThe \ **ignore**\ means that it won't generate cross references for a 85*4882a593Smuzhiyun\ **name**\ symbol of type \ **type**\ . 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunThe syntax for the replace tag is: 88*4882a593Smuzhiyun 89*4882a593Smuzhiyun 90*4882a593Smuzhiyunreplace \ **type**\ \ **name**\ \ **new_value**\ 91*4882a593Smuzhiyun 92*4882a593SmuzhiyunThe \ **replace**\ means that it will generate cross references for a 93*4882a593Smuzhiyun\ **name**\ symbol of type \ **type**\ , but, instead of using the default 94*4882a593Smuzhiyunreplacement rule, it will use \ **new_value**\ . 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunFor both statements, \ **type**\ can be either one of the following: 97*4882a593Smuzhiyun 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun\ **ioctl**\ 100*4882a593Smuzhiyun 101*4882a593Smuzhiyun The ignore or replace statement will apply to ioctl definitions like: 102*4882a593Smuzhiyun 103*4882a593Smuzhiyun #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) 104*4882a593Smuzhiyun 105*4882a593Smuzhiyun 106*4882a593Smuzhiyun 107*4882a593Smuzhiyun\ **define**\ 108*4882a593Smuzhiyun 109*4882a593Smuzhiyun The ignore or replace statement will apply to any other #define found 110*4882a593Smuzhiyun at C_FILE. 111*4882a593Smuzhiyun 112*4882a593Smuzhiyun 113*4882a593Smuzhiyun 114*4882a593Smuzhiyun\ **typedef**\ 115*4882a593Smuzhiyun 116*4882a593Smuzhiyun The ignore or replace statement will apply to typedef statements at C_FILE. 117*4882a593Smuzhiyun 118*4882a593Smuzhiyun 119*4882a593Smuzhiyun 120*4882a593Smuzhiyun\ **struct**\ 121*4882a593Smuzhiyun 122*4882a593Smuzhiyun The ignore or replace statement will apply to the name of struct statements 123*4882a593Smuzhiyun at C_FILE. 124*4882a593Smuzhiyun 125*4882a593Smuzhiyun 126*4882a593Smuzhiyun 127*4882a593Smuzhiyun\ **enum**\ 128*4882a593Smuzhiyun 129*4882a593Smuzhiyun The ignore or replace statement will apply to the name of enum statements 130*4882a593Smuzhiyun at C_FILE. 131*4882a593Smuzhiyun 132*4882a593Smuzhiyun 133*4882a593Smuzhiyun 134*4882a593Smuzhiyun\ **symbol**\ 135*4882a593Smuzhiyun 136*4882a593Smuzhiyun The ignore or replace statement will apply to the name of enum value 137*4882a593Smuzhiyun at C_FILE. 138*4882a593Smuzhiyun 139*4882a593Smuzhiyun For replace statements, \ **new_value**\ will automatically use :c:type: 140*4882a593Smuzhiyun references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref: 141*4882a593Smuzhiyun for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can 142*4882a593Smuzhiyun also be explicitly defined at the replace statement. 143*4882a593Smuzhiyun 144*4882a593Smuzhiyun 145*4882a593Smuzhiyun 146*4882a593SmuzhiyunEXAMPLES 147*4882a593Smuzhiyun******** 148*4882a593Smuzhiyun 149*4882a593Smuzhiyun 150*4882a593Smuzhiyunignore define _VIDEODEV2_H 151*4882a593Smuzhiyun 152*4882a593Smuzhiyun 153*4882a593SmuzhiyunIgnore a #define _VIDEODEV2_H at the C_FILE. 154*4882a593Smuzhiyun 155*4882a593Smuzhiyunignore symbol PRIVATE 156*4882a593Smuzhiyun 157*4882a593Smuzhiyun 158*4882a593SmuzhiyunOn a struct like: 159*4882a593Smuzhiyun 160*4882a593Smuzhiyunenum foo { BAR1, BAR2, PRIVATE }; 161*4882a593Smuzhiyun 162*4882a593SmuzhiyunIt won't generate cross-references for \ **PRIVATE**\ . 163*4882a593Smuzhiyun 164*4882a593Smuzhiyunreplace symbol BAR1 :c:type:\`foo\` 165*4882a593Smuzhiyunreplace symbol BAR2 :c:type:\`foo\` 166*4882a593Smuzhiyun 167*4882a593Smuzhiyun 168*4882a593SmuzhiyunOn a struct like: 169*4882a593Smuzhiyun 170*4882a593Smuzhiyunenum foo { BAR1, BAR2, PRIVATE }; 171*4882a593Smuzhiyun 172*4882a593SmuzhiyunIt will make the BAR1 and BAR2 enum symbols to cross reference the foo 173*4882a593Smuzhiyunsymbol at the C domain. 174*4882a593Smuzhiyun 175*4882a593Smuzhiyun 176*4882a593SmuzhiyunBUGS 177*4882a593Smuzhiyun**** 178*4882a593Smuzhiyun 179*4882a593Smuzhiyun 180*4882a593SmuzhiyunReport bugs to Mauro Carvalho Chehab <mchehab@kernel.org> 181*4882a593Smuzhiyun 182*4882a593Smuzhiyun 183*4882a593SmuzhiyunCOPYRIGHT 184*4882a593Smuzhiyun********* 185*4882a593Smuzhiyun 186*4882a593Smuzhiyun 187*4882a593SmuzhiyunCopyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. 188*4882a593Smuzhiyun 189*4882a593SmuzhiyunLicense GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. 190*4882a593Smuzhiyun 191*4882a593SmuzhiyunThis is free software: you are free to change and redistribute it. 192*4882a593SmuzhiyunThere is NO WARRANTY, to the extent permitted by law. 193