Orange Pi5 kernel

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