kernel-doc 66 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439
  1. #!/usr/bin/env perl
  2. # SPDX-License-Identifier: GPL-2.0
  3. use warnings;
  4. use strict;
  5. ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
  6. ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
  7. ## Copyright (C) 2001 Simon Huggins ##
  8. ## Copyright (C) 2005-2012 Randy Dunlap ##
  9. ## Copyright (C) 2012 Dan Luedtke ##
  10. ## ##
  11. ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
  12. ## Copyright (c) 2000 MontaVista Software, Inc. ##
  13. ## ##
  14. ## This software falls under the GNU General Public License. ##
  15. ## Please read the COPYING file for more information ##
  16. # 18/01/2001 - Cleanups
  17. # Functions prototyped as foo(void) same as foo()
  18. # Stop eval'ing where we don't need to.
  19. # -- huggie@earth.li
  20. # 27/06/2001 - Allowed whitespace after initial "/**" and
  21. # allowed comments before function declarations.
  22. # -- Christian Kreibich <ck@whoop.org>
  23. # Still to do:
  24. # - add perldoc documentation
  25. # - Look more closely at some of the scarier bits :)
  26. # 26/05/2001 - Support for separate source and object trees.
  27. # Return error code.
  28. # Keith Owens <kaos@ocs.com.au>
  29. # 23/09/2001 - Added support for typedefs, structs, enums and unions
  30. # Support for Context section; can be terminated using empty line
  31. # Small fixes (like spaces vs. \s in regex)
  32. # -- Tim Jansen <tim@tjansen.de>
  33. # 25/07/2012 - Added support for HTML5
  34. # -- Dan Luedtke <mail@danrl.de>
  35. sub usage {
  36. my $message = <<"EOF";
  37. Usage: $0 [OPTION ...] FILE ...
  38. Read C language source or header FILEs, extract embedded documentation comments,
  39. and print formatted documentation to standard output.
  40. The documentation comments are identified by "/**" opening comment mark. See
  41. Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
  42. Output format selection (mutually exclusive):
  43. -man Output troff manual page format. This is the default.
  44. -rst Output reStructuredText format.
  45. -none Do not output documentation, only warnings.
  46. Output format selection modifier (affects only ReST output):
  47. -sphinx-version Use the ReST C domain dialect compatible with an
  48. specific Sphinx Version.
  49. If not specified, kernel-doc will auto-detect using
  50. the sphinx-build version found on PATH.
  51. Output selection (mutually exclusive):
  52. -export Only output documentation for symbols that have been
  53. exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
  54. in any input FILE or -export-file FILE.
  55. -internal Only output documentation for symbols that have NOT been
  56. exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
  57. in any input FILE or -export-file FILE.
  58. -function NAME Only output documentation for the given function(s)
  59. or DOC: section title(s). All other functions and DOC:
  60. sections are ignored. May be specified multiple times.
  61. -nosymbol NAME Exclude the specified symbols from the output
  62. documentation. May be specified multiple times.
  63. Output selection modifiers:
  64. -no-doc-sections Do not output DOC: sections.
  65. -enable-lineno Enable output of #define LINENO lines. Only works with
  66. reStructuredText format.
  67. -export-file FILE Specify an additional FILE in which to look for
  68. EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
  69. -export or -internal. May be specified multiple times.
  70. Other parameters:
  71. -v Verbose output, more warnings and other information.
  72. -h Print this help.
  73. -Werror Treat warnings as errors.
  74. EOF
  75. print $message;
  76. exit 1;
  77. }
  78. #
  79. # format of comments.
  80. # In the following table, (...)? signifies optional structure.
  81. # (...)* signifies 0 or more structure elements
  82. # /**
  83. # * function_name(:)? (- short description)?
  84. # (* @parameterx: (description of parameter x)?)*
  85. # (* a blank line)?
  86. # * (Description:)? (Description of function)?
  87. # * (section header: (section description)? )*
  88. # (*)?*/
  89. #
  90. # So .. the trivial example would be:
  91. #
  92. # /**
  93. # * my_function
  94. # */
  95. #
  96. # If the Description: header tag is omitted, then there must be a blank line
  97. # after the last parameter specification.
  98. # e.g.
  99. # /**
  100. # * my_function - does my stuff
  101. # * @my_arg: its mine damnit
  102. # *
  103. # * Does my stuff explained.
  104. # */
  105. #
  106. # or, could also use:
  107. # /**
  108. # * my_function - does my stuff
  109. # * @my_arg: its mine damnit
  110. # * Description: Does my stuff explained.
  111. # */
  112. # etc.
  113. #
  114. # Besides functions you can also write documentation for structs, unions,
  115. # enums and typedefs. Instead of the function name you must write the name
  116. # of the declaration; the struct/union/enum/typedef must always precede
  117. # the name. Nesting of declarations is not supported.
  118. # Use the argument mechanism to document members or constants.
  119. # e.g.
  120. # /**
  121. # * struct my_struct - short description
  122. # * @a: first member
  123. # * @b: second member
  124. # *
  125. # * Longer description
  126. # */
  127. # struct my_struct {
  128. # int a;
  129. # int b;
  130. # /* private: */
  131. # int c;
  132. # };
  133. #
  134. # All descriptions can be multiline, except the short function description.
  135. #
  136. # For really longs structs, you can also describe arguments inside the
  137. # body of the struct.
  138. # eg.
  139. # /**
  140. # * struct my_struct - short description
  141. # * @a: first member
  142. # * @b: second member
  143. # *
  144. # * Longer description
  145. # */
  146. # struct my_struct {
  147. # int a;
  148. # int b;
  149. # /**
  150. # * @c: This is longer description of C
  151. # *
  152. # * You can use paragraphs to describe arguments
  153. # * using this method.
  154. # */
  155. # int c;
  156. # };
  157. #
  158. # This should be use only for struct/enum members.
  159. #
  160. # You can also add additional sections. When documenting kernel functions you
  161. # should document the "Context:" of the function, e.g. whether the functions
  162. # can be called form interrupts. Unlike other sections you can end it with an
  163. # empty line.
  164. # A non-void function should have a "Return:" section describing the return
  165. # value(s).
  166. # Example-sections should contain the string EXAMPLE so that they are marked
  167. # appropriately in DocBook.
  168. #
  169. # Example:
  170. # /**
  171. # * user_function - function that can only be called in user context
  172. # * @a: some argument
  173. # * Context: !in_interrupt()
  174. # *
  175. # * Some description
  176. # * Example:
  177. # * user_function(22);
  178. # */
  179. # ...
  180. #
  181. #
  182. # All descriptive text is further processed, scanning for the following special
  183. # patterns, which are highlighted appropriately.
  184. #
  185. # 'funcname()' - function
  186. # '$ENVVAR' - environmental variable
  187. # '&struct_name' - name of a structure (up to two words including 'struct')
  188. # '&struct_name.member' - name of a structure member
  189. # '@parameter' - name of a parameter
  190. # '%CONST' - name of a constant.
  191. # '``LITERAL``' - literal string without any spaces on it.
  192. ## init lots of data
  193. my $errors = 0;
  194. my $warnings = 0;
  195. my $anon_struct_union = 0;
  196. # match expressions used to find embedded type information
  197. my $type_constant = '\b``([^\`]+)``\b';
  198. my $type_constant2 = '\%([-_\w]+)';
  199. my $type_func = '(\w+)\(\)';
  200. my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
  201. my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
  202. my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
  203. my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
  204. my $type_env = '(\$\w+)';
  205. my $type_enum = '\&(enum\s*([_\w]+))';
  206. my $type_struct = '\&(struct\s*([_\w]+))';
  207. my $type_typedef = '\&(typedef\s*([_\w]+))';
  208. my $type_union = '\&(union\s*([_\w]+))';
  209. my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
  210. my $type_fallback = '\&([_\w]+)';
  211. my $type_member_func = $type_member . '\(\)';
  212. # Output conversion substitutions.
  213. # One for each output format
  214. # these are pretty rough
  215. my @highlights_man = (
  216. [$type_constant, "\$1"],
  217. [$type_constant2, "\$1"],
  218. [$type_func, "\\\\fB\$1\\\\fP"],
  219. [$type_enum, "\\\\fI\$1\\\\fP"],
  220. [$type_struct, "\\\\fI\$1\\\\fP"],
  221. [$type_typedef, "\\\\fI\$1\\\\fP"],
  222. [$type_union, "\\\\fI\$1\\\\fP"],
  223. [$type_param, "\\\\fI\$1\\\\fP"],
  224. [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
  225. [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
  226. [$type_fallback, "\\\\fI\$1\\\\fP"]
  227. );
  228. my $blankline_man = "";
  229. # rst-mode
  230. my @highlights_rst = (
  231. [$type_constant, "``\$1``"],
  232. [$type_constant2, "``\$1``"],
  233. # Note: need to escape () to avoid func matching later
  234. [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
  235. [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
  236. [$type_fp_param, "**\$1\\\\(\\\\)**"],
  237. [$type_fp_param2, "**\$1\\\\(\\\\)**"],
  238. [$type_func, "\$1()"],
  239. [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
  240. [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
  241. [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
  242. [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
  243. # in rst this can refer to any type
  244. [$type_fallback, "\\:c\\:type\\:`\$1`"],
  245. [$type_param_ref, "**\$1\$2**"]
  246. );
  247. my $blankline_rst = "\n";
  248. # read arguments
  249. if ($#ARGV == -1) {
  250. usage();
  251. }
  252. my $kernelversion;
  253. my ($sphinx_major, $sphinx_minor, $sphinx_patch);
  254. my $dohighlight = "";
  255. my $verbose = 0;
  256. my $Werror = 0;
  257. my $output_mode = "rst";
  258. my $output_preformatted = 0;
  259. my $no_doc_sections = 0;
  260. my $enable_lineno = 0;
  261. my @highlights = @highlights_rst;
  262. my $blankline = $blankline_rst;
  263. my $modulename = "Kernel API";
  264. use constant {
  265. OUTPUT_ALL => 0, # output all symbols and doc sections
  266. OUTPUT_INCLUDE => 1, # output only specified symbols
  267. OUTPUT_EXPORTED => 2, # output exported symbols
  268. OUTPUT_INTERNAL => 3, # output non-exported symbols
  269. };
  270. my $output_selection = OUTPUT_ALL;
  271. my $show_not_found = 0; # No longer used
  272. my @export_file_list;
  273. my @build_time;
  274. if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
  275. (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
  276. @build_time = gmtime($seconds);
  277. } else {
  278. @build_time = localtime;
  279. }
  280. my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
  281. 'July', 'August', 'September', 'October',
  282. 'November', 'December')[$build_time[4]] .
  283. " " . ($build_time[5]+1900);
  284. # Essentially these are globals.
  285. # They probably want to be tidied up, made more localised or something.
  286. # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
  287. # could cause "use of undefined value" or other bugs.
  288. my ($function, %function_table, %parametertypes, $declaration_purpose);
  289. my %nosymbol_table = ();
  290. my $declaration_start_line;
  291. my ($type, $declaration_name, $return_type);
  292. my ($newsection, $newcontents, $prototype, $brcount, %source_map);
  293. if (defined($ENV{'KBUILD_VERBOSE'})) {
  294. $verbose = "$ENV{'KBUILD_VERBOSE'}";
  295. }
  296. if (defined($ENV{'KDOC_WERROR'})) {
  297. $Werror = "$ENV{'KDOC_WERROR'}";
  298. }
  299. if (defined($ENV{'KCFLAGS'})) {
  300. my $kcflags = "$ENV{'KCFLAGS'}";
  301. if ($kcflags =~ /Werror/) {
  302. $Werror = 1;
  303. }
  304. }
  305. # Generated docbook code is inserted in a template at a point where
  306. # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
  307. # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
  308. # We keep track of number of generated entries and generate a dummy
  309. # if needs be to ensure the expanded template can be postprocessed
  310. # into html.
  311. my $section_counter = 0;
  312. my $lineprefix="";
  313. # Parser states
  314. use constant {
  315. STATE_NORMAL => 0, # normal code
  316. STATE_NAME => 1, # looking for function name
  317. STATE_BODY_MAYBE => 2, # body - or maybe more description
  318. STATE_BODY => 3, # the body of the comment
  319. STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
  320. STATE_PROTO => 5, # scanning prototype
  321. STATE_DOCBLOCK => 6, # documentation block
  322. STATE_INLINE => 7, # gathering doc outside main block
  323. };
  324. my $state;
  325. my $in_doc_sect;
  326. my $leading_space;
  327. # Inline documentation state
  328. use constant {
  329. STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
  330. STATE_INLINE_NAME => 1, # looking for member name (@foo:)
  331. STATE_INLINE_TEXT => 2, # looking for member documentation
  332. STATE_INLINE_END => 3, # done
  333. STATE_INLINE_ERROR => 4, # error - Comment without header was found.
  334. # Spit a warning as it's not
  335. # proper kernel-doc and ignore the rest.
  336. };
  337. my $inline_doc_state;
  338. #declaration types: can be
  339. # 'function', 'struct', 'union', 'enum', 'typedef'
  340. my $decl_type;
  341. my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
  342. my $doc_end = '\*/';
  343. my $doc_com = '\s*\*\s*';
  344. my $doc_com_body = '\s*\* ?';
  345. my $doc_decl = $doc_com . '(\w+)';
  346. # @params and a strictly limited set of supported section names
  347. my $doc_sect = $doc_com .
  348. '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
  349. my $doc_content = $doc_com_body . '(.*)';
  350. my $doc_block = $doc_com . 'DOC:\s*(.*)?';
  351. my $doc_inline_start = '^\s*/\*\*\s*$';
  352. my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
  353. my $doc_inline_end = '^\s*\*/\s*$';
  354. my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
  355. my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
  356. my %parameterdescs;
  357. my %parameterdesc_start_lines;
  358. my @parameterlist;
  359. my %sections;
  360. my @sectionlist;
  361. my %section_start_lines;
  362. my $sectcheck;
  363. my $struct_actual;
  364. my $contents = "";
  365. my $new_start_line = 0;
  366. # the canonical section names. see also $doc_sect above.
  367. my $section_default = "Description"; # default section
  368. my $section_intro = "Introduction";
  369. my $section = $section_default;
  370. my $section_context = "Context";
  371. my $section_return = "Return";
  372. my $undescribed = "-- undescribed --";
  373. reset_state();
  374. while ($ARGV[0] =~ m/^--?(.*)/) {
  375. my $cmd = $1;
  376. shift @ARGV;
  377. if ($cmd eq "man") {
  378. $output_mode = "man";
  379. @highlights = @highlights_man;
  380. $blankline = $blankline_man;
  381. } elsif ($cmd eq "rst") {
  382. $output_mode = "rst";
  383. @highlights = @highlights_rst;
  384. $blankline = $blankline_rst;
  385. } elsif ($cmd eq "none") {
  386. $output_mode = "none";
  387. } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
  388. $modulename = shift @ARGV;
  389. } elsif ($cmd eq "function") { # to only output specific functions
  390. $output_selection = OUTPUT_INCLUDE;
  391. $function = shift @ARGV;
  392. $function_table{$function} = 1;
  393. } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
  394. my $symbol = shift @ARGV;
  395. $nosymbol_table{$symbol} = 1;
  396. } elsif ($cmd eq "export") { # only exported symbols
  397. $output_selection = OUTPUT_EXPORTED;
  398. %function_table = ();
  399. } elsif ($cmd eq "internal") { # only non-exported symbols
  400. $output_selection = OUTPUT_INTERNAL;
  401. %function_table = ();
  402. } elsif ($cmd eq "export-file") {
  403. my $file = shift @ARGV;
  404. push(@export_file_list, $file);
  405. } elsif ($cmd eq "v") {
  406. $verbose = 1;
  407. } elsif ($cmd eq "Werror") {
  408. $Werror = 1;
  409. } elsif (($cmd eq "h") || ($cmd eq "help")) {
  410. usage();
  411. } elsif ($cmd eq 'no-doc-sections') {
  412. $no_doc_sections = 1;
  413. } elsif ($cmd eq 'enable-lineno') {
  414. $enable_lineno = 1;
  415. } elsif ($cmd eq 'show-not-found') {
  416. $show_not_found = 1; # A no-op but don't fail
  417. } elsif ($cmd eq "sphinx-version") {
  418. my $ver_string = shift @ARGV;
  419. if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
  420. $sphinx_major = $1;
  421. if (defined($2)) {
  422. $sphinx_minor = substr($2,1);
  423. } else {
  424. $sphinx_minor = 0;
  425. }
  426. if (defined($3)) {
  427. $sphinx_patch = substr($3,1)
  428. } else {
  429. $sphinx_patch = 0;
  430. }
  431. } else {
  432. die "Sphinx version should either major.minor or major.minor.patch format\n";
  433. }
  434. } else {
  435. # Unknown argument
  436. usage();
  437. }
  438. }
  439. # continue execution near EOF;
  440. # The C domain dialect changed on Sphinx 3. So, we need to check the
  441. # version in order to produce the right tags.
  442. sub findprog($)
  443. {
  444. foreach(split(/:/, $ENV{PATH})) {
  445. return "$_/$_[0]" if(-x "$_/$_[0]");
  446. }
  447. }
  448. sub get_sphinx_version()
  449. {
  450. my $ver;
  451. my $cmd = "sphinx-build";
  452. if (!findprog($cmd)) {
  453. my $cmd = "sphinx-build3";
  454. if (!findprog($cmd)) {
  455. $sphinx_major = 1;
  456. $sphinx_minor = 2;
  457. $sphinx_patch = 0;
  458. printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
  459. $sphinx_major, $sphinx_minor, $sphinx_patch;
  460. return;
  461. }
  462. }
  463. open IN, "$cmd --version 2>&1 |";
  464. while (<IN>) {
  465. if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
  466. $sphinx_major = $1;
  467. $sphinx_minor = $2;
  468. $sphinx_patch = $3;
  469. last;
  470. }
  471. # Sphinx 1.2.x uses a different format
  472. if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
  473. $sphinx_major = $1;
  474. $sphinx_minor = $2;
  475. $sphinx_patch = $3;
  476. last;
  477. }
  478. }
  479. close IN;
  480. }
  481. # get kernel version from env
  482. sub get_kernel_version() {
  483. my $version = 'unknown kernel version';
  484. if (defined($ENV{'KERNELVERSION'})) {
  485. $version = $ENV{'KERNELVERSION'};
  486. }
  487. return $version;
  488. }
  489. #
  490. sub print_lineno {
  491. my $lineno = shift;
  492. if ($enable_lineno && defined($lineno)) {
  493. print "#define LINENO " . $lineno . "\n";
  494. }
  495. }
  496. ##
  497. # dumps section contents to arrays/hashes intended for that purpose.
  498. #
  499. sub dump_section {
  500. my $file = shift;
  501. my $name = shift;
  502. my $contents = join "\n", @_;
  503. if ($name =~ m/$type_param/) {
  504. $name = $1;
  505. $parameterdescs{$name} = $contents;
  506. $sectcheck = $sectcheck . $name . " ";
  507. $parameterdesc_start_lines{$name} = $new_start_line;
  508. $new_start_line = 0;
  509. } elsif ($name eq "@\.\.\.") {
  510. $name = "...";
  511. $parameterdescs{$name} = $contents;
  512. $sectcheck = $sectcheck . $name . " ";
  513. $parameterdesc_start_lines{$name} = $new_start_line;
  514. $new_start_line = 0;
  515. } else {
  516. if (defined($sections{$name}) && ($sections{$name} ne "")) {
  517. # Only warn on user specified duplicate section names.
  518. if ($name ne $section_default) {
  519. print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
  520. ++$warnings;
  521. }
  522. $sections{$name} .= $contents;
  523. } else {
  524. $sections{$name} = $contents;
  525. push @sectionlist, $name;
  526. $section_start_lines{$name} = $new_start_line;
  527. $new_start_line = 0;
  528. }
  529. }
  530. }
  531. ##
  532. # dump DOC: section after checking that it should go out
  533. #
  534. sub dump_doc_section {
  535. my $file = shift;
  536. my $name = shift;
  537. my $contents = join "\n", @_;
  538. if ($no_doc_sections) {
  539. return;
  540. }
  541. return if (defined($nosymbol_table{$name}));
  542. if (($output_selection == OUTPUT_ALL) ||
  543. (($output_selection == OUTPUT_INCLUDE) &&
  544. defined($function_table{$name})))
  545. {
  546. dump_section($file, $name, $contents);
  547. output_blockhead({'sectionlist' => \@sectionlist,
  548. 'sections' => \%sections,
  549. 'module' => $modulename,
  550. 'content-only' => ($output_selection != OUTPUT_ALL), });
  551. }
  552. }
  553. ##
  554. # output function
  555. #
  556. # parameterdescs, a hash.
  557. # function => "function name"
  558. # parameterlist => @list of parameters
  559. # parameterdescs => %parameter descriptions
  560. # sectionlist => @list of sections
  561. # sections => %section descriptions
  562. #
  563. sub output_highlight {
  564. my $contents = join "\n",@_;
  565. my $line;
  566. # DEBUG
  567. # if (!defined $contents) {
  568. # use Carp;
  569. # confess "output_highlight got called with no args?\n";
  570. # }
  571. # print STDERR "contents b4:$contents\n";
  572. eval $dohighlight;
  573. die $@ if $@;
  574. # print STDERR "contents af:$contents\n";
  575. foreach $line (split "\n", $contents) {
  576. if (! $output_preformatted) {
  577. $line =~ s/^\s*//;
  578. }
  579. if ($line eq ""){
  580. if (! $output_preformatted) {
  581. print $lineprefix, $blankline;
  582. }
  583. } else {
  584. if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
  585. print "\\&$line";
  586. } else {
  587. print $lineprefix, $line;
  588. }
  589. }
  590. print "\n";
  591. }
  592. }
  593. ##
  594. # output function in man
  595. sub output_function_man(%) {
  596. my %args = %{$_[0]};
  597. my ($parameter, $section);
  598. my $count;
  599. print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
  600. print ".SH NAME\n";
  601. print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
  602. print ".SH SYNOPSIS\n";
  603. if ($args{'functiontype'} ne "") {
  604. print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
  605. } else {
  606. print ".B \"" . $args{'function'} . "\n";
  607. }
  608. $count = 0;
  609. my $parenth = "(";
  610. my $post = ",";
  611. foreach my $parameter (@{$args{'parameterlist'}}) {
  612. if ($count == $#{$args{'parameterlist'}}) {
  613. $post = ");";
  614. }
  615. $type = $args{'parametertypes'}{$parameter};
  616. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  617. # pointer-to-function
  618. print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
  619. } else {
  620. $type =~ s/([^\*])$/$1 /;
  621. print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
  622. }
  623. $count++;
  624. $parenth = "";
  625. }
  626. print ".SH ARGUMENTS\n";
  627. foreach $parameter (@{$args{'parameterlist'}}) {
  628. my $parameter_name = $parameter;
  629. $parameter_name =~ s/\[.*//;
  630. print ".IP \"" . $parameter . "\" 12\n";
  631. output_highlight($args{'parameterdescs'}{$parameter_name});
  632. }
  633. foreach $section (@{$args{'sectionlist'}}) {
  634. print ".SH \"", uc $section, "\"\n";
  635. output_highlight($args{'sections'}{$section});
  636. }
  637. }
  638. ##
  639. # output enum in man
  640. sub output_enum_man(%) {
  641. my %args = %{$_[0]};
  642. my ($parameter, $section);
  643. my $count;
  644. print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
  645. print ".SH NAME\n";
  646. print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
  647. print ".SH SYNOPSIS\n";
  648. print "enum " . $args{'enum'} . " {\n";
  649. $count = 0;
  650. foreach my $parameter (@{$args{'parameterlist'}}) {
  651. print ".br\n.BI \" $parameter\"\n";
  652. if ($count == $#{$args{'parameterlist'}}) {
  653. print "\n};\n";
  654. last;
  655. }
  656. else {
  657. print ", \n.br\n";
  658. }
  659. $count++;
  660. }
  661. print ".SH Constants\n";
  662. foreach $parameter (@{$args{'parameterlist'}}) {
  663. my $parameter_name = $parameter;
  664. $parameter_name =~ s/\[.*//;
  665. print ".IP \"" . $parameter . "\" 12\n";
  666. output_highlight($args{'parameterdescs'}{$parameter_name});
  667. }
  668. foreach $section (@{$args{'sectionlist'}}) {
  669. print ".SH \"$section\"\n";
  670. output_highlight($args{'sections'}{$section});
  671. }
  672. }
  673. ##
  674. # output struct in man
  675. sub output_struct_man(%) {
  676. my %args = %{$_[0]};
  677. my ($parameter, $section);
  678. print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
  679. print ".SH NAME\n";
  680. print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
  681. my $declaration = $args{'definition'};
  682. $declaration =~ s/\t/ /g;
  683. $declaration =~ s/\n/"\n.br\n.BI \"/g;
  684. print ".SH SYNOPSIS\n";
  685. print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
  686. print ".BI \"$declaration\n};\n.br\n\n";
  687. print ".SH Members\n";
  688. foreach $parameter (@{$args{'parameterlist'}}) {
  689. ($parameter =~ /^#/) && next;
  690. my $parameter_name = $parameter;
  691. $parameter_name =~ s/\[.*//;
  692. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  693. print ".IP \"" . $parameter . "\" 12\n";
  694. output_highlight($args{'parameterdescs'}{$parameter_name});
  695. }
  696. foreach $section (@{$args{'sectionlist'}}) {
  697. print ".SH \"$section\"\n";
  698. output_highlight($args{'sections'}{$section});
  699. }
  700. }
  701. ##
  702. # output typedef in man
  703. sub output_typedef_man(%) {
  704. my %args = %{$_[0]};
  705. my ($parameter, $section);
  706. print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
  707. print ".SH NAME\n";
  708. print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
  709. foreach $section (@{$args{'sectionlist'}}) {
  710. print ".SH \"$section\"\n";
  711. output_highlight($args{'sections'}{$section});
  712. }
  713. }
  714. sub output_blockhead_man(%) {
  715. my %args = %{$_[0]};
  716. my ($parameter, $section);
  717. my $count;
  718. print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
  719. foreach $section (@{$args{'sectionlist'}}) {
  720. print ".SH \"$section\"\n";
  721. output_highlight($args{'sections'}{$section});
  722. }
  723. }
  724. ##
  725. # output in restructured text
  726. #
  727. #
  728. # This could use some work; it's used to output the DOC: sections, and
  729. # starts by putting out the name of the doc section itself, but that tends
  730. # to duplicate a header already in the template file.
  731. #
  732. sub output_blockhead_rst(%) {
  733. my %args = %{$_[0]};
  734. my ($parameter, $section);
  735. foreach $section (@{$args{'sectionlist'}}) {
  736. next if (defined($nosymbol_table{$section}));
  737. if ($output_selection != OUTPUT_INCLUDE) {
  738. print "**$section**\n\n";
  739. }
  740. print_lineno($section_start_lines{$section});
  741. output_highlight_rst($args{'sections'}{$section});
  742. print "\n";
  743. }
  744. }
  745. #
  746. # Apply the RST highlights to a sub-block of text.
  747. #
  748. sub highlight_block($) {
  749. # The dohighlight kludge requires the text be called $contents
  750. my $contents = shift;
  751. eval $dohighlight;
  752. die $@ if $@;
  753. return $contents;
  754. }
  755. #
  756. # Regexes used only here.
  757. #
  758. my $sphinx_literal = '^[^.].*::$';
  759. my $sphinx_cblock = '^\.\.\ +code-block::';
  760. sub output_highlight_rst {
  761. my $input = join "\n",@_;
  762. my $output = "";
  763. my $line;
  764. my $in_literal = 0;
  765. my $litprefix;
  766. my $block = "";
  767. foreach $line (split "\n",$input) {
  768. #
  769. # If we're in a literal block, see if we should drop out
  770. # of it. Otherwise pass the line straight through unmunged.
  771. #
  772. if ($in_literal) {
  773. if (! ($line =~ /^\s*$/)) {
  774. #
  775. # If this is the first non-blank line in a literal
  776. # block we need to figure out what the proper indent is.
  777. #
  778. if ($litprefix eq "") {
  779. $line =~ /^(\s*)/;
  780. $litprefix = '^' . $1;
  781. $output .= $line . "\n";
  782. } elsif (! ($line =~ /$litprefix/)) {
  783. $in_literal = 0;
  784. } else {
  785. $output .= $line . "\n";
  786. }
  787. } else {
  788. $output .= $line . "\n";
  789. }
  790. }
  791. #
  792. # Not in a literal block (or just dropped out)
  793. #
  794. if (! $in_literal) {
  795. $block .= $line . "\n";
  796. if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
  797. $in_literal = 1;
  798. $litprefix = "";
  799. $output .= highlight_block($block);
  800. $block = ""
  801. }
  802. }
  803. }
  804. if ($block) {
  805. $output .= highlight_block($block);
  806. }
  807. foreach $line (split "\n", $output) {
  808. print $lineprefix . $line . "\n";
  809. }
  810. }
  811. sub output_function_rst(%) {
  812. my %args = %{$_[0]};
  813. my ($parameter, $section);
  814. my $oldprefix = $lineprefix;
  815. my $start = "";
  816. my $is_macro = 0;
  817. if ($sphinx_major < 3) {
  818. if ($args{'typedef'}) {
  819. print ".. c:type:: ". $args{'function'} . "\n\n";
  820. print_lineno($declaration_start_line);
  821. print " **Typedef**: ";
  822. $lineprefix = "";
  823. output_highlight_rst($args{'purpose'});
  824. $start = "\n\n**Syntax**\n\n ``";
  825. $is_macro = 1;
  826. } else {
  827. print ".. c:function:: ";
  828. }
  829. } else {
  830. if ($args{'typedef'} || $args{'functiontype'} eq "") {
  831. $is_macro = 1;
  832. print ".. c:macro:: ". $args{'function'} . "\n\n";
  833. } else {
  834. print ".. c:function:: ";
  835. }
  836. if ($args{'typedef'}) {
  837. print_lineno($declaration_start_line);
  838. print " **Typedef**: ";
  839. $lineprefix = "";
  840. output_highlight_rst($args{'purpose'});
  841. $start = "\n\n**Syntax**\n\n ``";
  842. } else {
  843. print "``" if ($is_macro);
  844. }
  845. }
  846. if ($args{'functiontype'} ne "") {
  847. $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
  848. } else {
  849. $start .= $args{'function'} . " (";
  850. }
  851. print $start;
  852. my $count = 0;
  853. foreach my $parameter (@{$args{'parameterlist'}}) {
  854. if ($count ne 0) {
  855. print ", ";
  856. }
  857. $count++;
  858. $type = $args{'parametertypes'}{$parameter};
  859. if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  860. # pointer-to-function
  861. print $1 . $parameter . ") (" . $2 . ")";
  862. } else {
  863. print $type;
  864. }
  865. }
  866. if ($is_macro) {
  867. print ")``\n\n";
  868. } else {
  869. print ")\n\n";
  870. }
  871. if (!$args{'typedef'}) {
  872. print_lineno($declaration_start_line);
  873. $lineprefix = " ";
  874. output_highlight_rst($args{'purpose'});
  875. print "\n";
  876. }
  877. print "**Parameters**\n\n";
  878. $lineprefix = " ";
  879. foreach $parameter (@{$args{'parameterlist'}}) {
  880. my $parameter_name = $parameter;
  881. $parameter_name =~ s/\[.*//;
  882. $type = $args{'parametertypes'}{$parameter};
  883. if ($type ne "") {
  884. print "``$type``\n";
  885. } else {
  886. print "``$parameter``\n";
  887. }
  888. print_lineno($parameterdesc_start_lines{$parameter_name});
  889. if (defined($args{'parameterdescs'}{$parameter_name}) &&
  890. $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
  891. output_highlight_rst($args{'parameterdescs'}{$parameter_name});
  892. } else {
  893. print " *undescribed*\n";
  894. }
  895. print "\n";
  896. }
  897. $lineprefix = $oldprefix;
  898. output_section_rst(@_);
  899. }
  900. sub output_section_rst(%) {
  901. my %args = %{$_[0]};
  902. my $section;
  903. my $oldprefix = $lineprefix;
  904. $lineprefix = "";
  905. foreach $section (@{$args{'sectionlist'}}) {
  906. print "**$section**\n\n";
  907. print_lineno($section_start_lines{$section});
  908. output_highlight_rst($args{'sections'}{$section});
  909. print "\n";
  910. }
  911. print "\n";
  912. $lineprefix = $oldprefix;
  913. }
  914. sub output_enum_rst(%) {
  915. my %args = %{$_[0]};
  916. my ($parameter);
  917. my $oldprefix = $lineprefix;
  918. my $count;
  919. if ($sphinx_major < 3) {
  920. my $name = "enum " . $args{'enum'};
  921. print "\n\n.. c:type:: " . $name . "\n\n";
  922. } else {
  923. my $name = $args{'enum'};
  924. print "\n\n.. c:enum:: " . $name . "\n\n";
  925. }
  926. print_lineno($declaration_start_line);
  927. $lineprefix = " ";
  928. output_highlight_rst($args{'purpose'});
  929. print "\n";
  930. print "**Constants**\n\n";
  931. $lineprefix = " ";
  932. foreach $parameter (@{$args{'parameterlist'}}) {
  933. print "``$parameter``\n";
  934. if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
  935. output_highlight_rst($args{'parameterdescs'}{$parameter});
  936. } else {
  937. print " *undescribed*\n";
  938. }
  939. print "\n";
  940. }
  941. $lineprefix = $oldprefix;
  942. output_section_rst(@_);
  943. }
  944. sub output_typedef_rst(%) {
  945. my %args = %{$_[0]};
  946. my ($parameter);
  947. my $oldprefix = $lineprefix;
  948. my $name;
  949. if ($sphinx_major < 3) {
  950. $name = "typedef " . $args{'typedef'};
  951. } else {
  952. $name = $args{'typedef'};
  953. }
  954. print "\n\n.. c:type:: " . $name . "\n\n";
  955. print_lineno($declaration_start_line);
  956. $lineprefix = " ";
  957. output_highlight_rst($args{'purpose'});
  958. print "\n";
  959. $lineprefix = $oldprefix;
  960. output_section_rst(@_);
  961. }
  962. sub output_struct_rst(%) {
  963. my %args = %{$_[0]};
  964. my ($parameter);
  965. my $oldprefix = $lineprefix;
  966. if ($sphinx_major < 3) {
  967. my $name = $args{'type'} . " " . $args{'struct'};
  968. print "\n\n.. c:type:: " . $name . "\n\n";
  969. } else {
  970. my $name = $args{'struct'};
  971. if ($args{'type'} eq 'union') {
  972. print "\n\n.. c:union:: " . $name . "\n\n";
  973. } else {
  974. print "\n\n.. c:struct:: " . $name . "\n\n";
  975. }
  976. }
  977. print_lineno($declaration_start_line);
  978. $lineprefix = " ";
  979. output_highlight_rst($args{'purpose'});
  980. print "\n";
  981. print "**Definition**\n\n";
  982. print "::\n\n";
  983. my $declaration = $args{'definition'};
  984. $declaration =~ s/\t/ /g;
  985. print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
  986. print "**Members**\n\n";
  987. $lineprefix = " ";
  988. foreach $parameter (@{$args{'parameterlist'}}) {
  989. ($parameter =~ /^#/) && next;
  990. my $parameter_name = $parameter;
  991. $parameter_name =~ s/\[.*//;
  992. ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  993. $type = $args{'parametertypes'}{$parameter};
  994. print_lineno($parameterdesc_start_lines{$parameter_name});
  995. print "``" . $parameter . "``\n";
  996. output_highlight_rst($args{'parameterdescs'}{$parameter_name});
  997. print "\n";
  998. }
  999. print "\n";
  1000. $lineprefix = $oldprefix;
  1001. output_section_rst(@_);
  1002. }
  1003. ## none mode output functions
  1004. sub output_function_none(%) {
  1005. }
  1006. sub output_enum_none(%) {
  1007. }
  1008. sub output_typedef_none(%) {
  1009. }
  1010. sub output_struct_none(%) {
  1011. }
  1012. sub output_blockhead_none(%) {
  1013. }
  1014. ##
  1015. # generic output function for all types (function, struct/union, typedef, enum);
  1016. # calls the generated, variable output_ function name based on
  1017. # functype and output_mode
  1018. sub output_declaration {
  1019. no strict 'refs';
  1020. my $name = shift;
  1021. my $functype = shift;
  1022. my $func = "output_${functype}_$output_mode";
  1023. return if (defined($nosymbol_table{$name}));
  1024. if (($output_selection == OUTPUT_ALL) ||
  1025. (($output_selection == OUTPUT_INCLUDE ||
  1026. $output_selection == OUTPUT_EXPORTED) &&
  1027. defined($function_table{$name})) ||
  1028. ($output_selection == OUTPUT_INTERNAL &&
  1029. !($functype eq "function" && defined($function_table{$name}))))
  1030. {
  1031. &$func(@_);
  1032. $section_counter++;
  1033. }
  1034. }
  1035. ##
  1036. # generic output function - calls the right one based on current output mode.
  1037. sub output_blockhead {
  1038. no strict 'refs';
  1039. my $func = "output_blockhead_" . $output_mode;
  1040. &$func(@_);
  1041. $section_counter++;
  1042. }
  1043. ##
  1044. # takes a declaration (struct, union, enum, typedef) and
  1045. # invokes the right handler. NOT called for functions.
  1046. sub dump_declaration($$) {
  1047. no strict 'refs';
  1048. my ($prototype, $file) = @_;
  1049. my $func = "dump_" . $decl_type;
  1050. &$func(@_);
  1051. }
  1052. sub dump_union($$) {
  1053. dump_struct(@_);
  1054. }
  1055. sub dump_struct($$) {
  1056. my $x = shift;
  1057. my $file = shift;
  1058. if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
  1059. my $decl_type = $1;
  1060. $declaration_name = $2;
  1061. my $members = $3;
  1062. # ignore members marked private:
  1063. $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
  1064. $members =~ s/\/\*\s*private:.*//gosi;
  1065. # strip comments:
  1066. $members =~ s/\/\*.*?\*\///gos;
  1067. # strip attributes
  1068. $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
  1069. $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
  1070. $members =~ s/\s*__packed\s*/ /gos;
  1071. $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
  1072. $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
  1073. $members =~ s/\s*____cacheline_aligned/ /gos;
  1074. # replace DECLARE_BITMAP
  1075. $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
  1076. $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
  1077. # replace DECLARE_HASHTABLE
  1078. $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
  1079. # replace DECLARE_KFIFO
  1080. $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
  1081. # replace DECLARE_KFIFO_PTR
  1082. $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
  1083. my $declaration = $members;
  1084. # Split nested struct/union elements as newer ones
  1085. while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
  1086. my $newmember;
  1087. my $maintype = $1;
  1088. my $ids = $4;
  1089. my $content = $3;
  1090. foreach my $id(split /,/, $ids) {
  1091. $newmember .= "$maintype $id; ";
  1092. $id =~ s/[:\[].*//;
  1093. $id =~ s/^\s*\**(\S+)\s*/$1/;
  1094. foreach my $arg (split /;/, $content) {
  1095. next if ($arg =~ m/^\s*$/);
  1096. if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
  1097. # pointer-to-function
  1098. my $type = $1;
  1099. my $name = $2;
  1100. my $extra = $3;
  1101. next if (!$name);
  1102. if ($id =~ m/^\s*$/) {
  1103. # anonymous struct/union
  1104. $newmember .= "$type$name$extra; ";
  1105. } else {
  1106. $newmember .= "$type$id.$name$extra; ";
  1107. }
  1108. } else {
  1109. my $type;
  1110. my $names;
  1111. $arg =~ s/^\s+//;
  1112. $arg =~ s/\s+$//;
  1113. # Handle bitmaps
  1114. $arg =~ s/:\s*\d+\s*//g;
  1115. # Handle arrays
  1116. $arg =~ s/\[.*\]//g;
  1117. # The type may have multiple words,
  1118. # and multiple IDs can be defined, like:
  1119. # const struct foo, *bar, foobar
  1120. # So, we remove spaces when parsing the
  1121. # names, in order to match just names
  1122. # and commas for the names
  1123. $arg =~ s/\s*,\s*/,/g;
  1124. if ($arg =~ m/(.*)\s+([\S+,]+)/) {
  1125. $type = $1;
  1126. $names = $2;
  1127. } else {
  1128. $newmember .= "$arg; ";
  1129. next;
  1130. }
  1131. foreach my $name (split /,/, $names) {
  1132. $name =~ s/^\s*\**(\S+)\s*/$1/;
  1133. next if (($name =~ m/^\s*$/));
  1134. if ($id =~ m/^\s*$/) {
  1135. # anonymous struct/union
  1136. $newmember .= "$type $name; ";
  1137. } else {
  1138. $newmember .= "$type $id.$name; ";
  1139. }
  1140. }
  1141. }
  1142. }
  1143. }
  1144. $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/;
  1145. }
  1146. # Ignore other nested elements, like enums
  1147. $members =~ s/(\{[^\{\}]*\})//g;
  1148. create_parameterlist($members, ';', $file, $declaration_name);
  1149. check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
  1150. # Adjust declaration for better display
  1151. $declaration =~ s/([\{;])/$1\n/g;
  1152. $declaration =~ s/\}\s+;/};/g;
  1153. # Better handle inlined enums
  1154. do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
  1155. my @def_args = split /\n/, $declaration;
  1156. my $level = 1;
  1157. $declaration = "";
  1158. foreach my $clause (@def_args) {
  1159. $clause =~ s/^\s+//;
  1160. $clause =~ s/\s+$//;
  1161. $clause =~ s/\s+/ /;
  1162. next if (!$clause);
  1163. $level-- if ($clause =~ m/(\})/ && $level > 1);
  1164. if (!($clause =~ m/^\s*#/)) {
  1165. $declaration .= "\t" x $level;
  1166. }
  1167. $declaration .= "\t" . $clause . "\n";
  1168. $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
  1169. }
  1170. output_declaration($declaration_name,
  1171. 'struct',
  1172. {'struct' => $declaration_name,
  1173. 'module' => $modulename,
  1174. 'definition' => $declaration,
  1175. 'parameterlist' => \@parameterlist,
  1176. 'parameterdescs' => \%parameterdescs,
  1177. 'parametertypes' => \%parametertypes,
  1178. 'sectionlist' => \@sectionlist,
  1179. 'sections' => \%sections,
  1180. 'purpose' => $declaration_purpose,
  1181. 'type' => $decl_type
  1182. });
  1183. }
  1184. else {
  1185. print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
  1186. ++$errors;
  1187. }
  1188. }
  1189. sub show_warnings($$) {
  1190. my $functype = shift;
  1191. my $name = shift;
  1192. return 0 if (defined($nosymbol_table{$name}));
  1193. return 1 if ($output_selection == OUTPUT_ALL);
  1194. if ($output_selection == OUTPUT_EXPORTED) {
  1195. if (defined($function_table{$name})) {
  1196. return 1;
  1197. } else {
  1198. return 0;
  1199. }
  1200. }
  1201. if ($output_selection == OUTPUT_INTERNAL) {
  1202. if (!($functype eq "function" && defined($function_table{$name}))) {
  1203. return 1;
  1204. } else {
  1205. return 0;
  1206. }
  1207. }
  1208. if ($output_selection == OUTPUT_INCLUDE) {
  1209. if (defined($function_table{$name})) {
  1210. return 1;
  1211. } else {
  1212. return 0;
  1213. }
  1214. }
  1215. die("Please add the new output type at show_warnings()");
  1216. }
  1217. sub dump_enum($$) {
  1218. my $x = shift;
  1219. my $file = shift;
  1220. my $members;
  1221. $x =~ s@/\*.*?\*/@@gos; # strip comments.
  1222. # strip #define macros inside enums
  1223. $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
  1224. if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
  1225. $declaration_name = $2;
  1226. $members = $1;
  1227. } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
  1228. $declaration_name = $1;
  1229. $members = $2;
  1230. }
  1231. if ($members) {
  1232. my %_members;
  1233. $members =~ s/\s+$//;
  1234. foreach my $arg (split ',', $members) {
  1235. $arg =~ s/^\s*(\w+).*/$1/;
  1236. push @parameterlist, $arg;
  1237. if (!$parameterdescs{$arg}) {
  1238. $parameterdescs{$arg} = $undescribed;
  1239. if (show_warnings("enum", $declaration_name)) {
  1240. print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
  1241. }
  1242. }
  1243. $_members{$arg} = 1;
  1244. }
  1245. while (my ($k, $v) = each %parameterdescs) {
  1246. if (!exists($_members{$k})) {
  1247. if (show_warnings("enum", $declaration_name)) {
  1248. print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
  1249. }
  1250. }
  1251. }
  1252. output_declaration($declaration_name,
  1253. 'enum',
  1254. {'enum' => $declaration_name,
  1255. 'module' => $modulename,
  1256. 'parameterlist' => \@parameterlist,
  1257. 'parameterdescs' => \%parameterdescs,
  1258. 'sectionlist' => \@sectionlist,
  1259. 'sections' => \%sections,
  1260. 'purpose' => $declaration_purpose
  1261. });
  1262. } else {
  1263. print STDERR "${file}:$.: error: Cannot parse enum!\n";
  1264. ++$errors;
  1265. }
  1266. }
  1267. my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
  1268. my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
  1269. my $typedef_args = qr { \s*\((.*)\); }x;
  1270. my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
  1271. my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
  1272. sub dump_typedef($$) {
  1273. my $x = shift;
  1274. my $file = shift;
  1275. $x =~ s@/\*.*?\*/@@gos; # strip comments.
  1276. # Parse function typedef prototypes
  1277. if ($x =~ $typedef1 || $x =~ $typedef2) {
  1278. $return_type = $1;
  1279. $declaration_name = $2;
  1280. my $args = $3;
  1281. $return_type =~ s/^\s+//;
  1282. create_parameterlist($args, ',', $file, $declaration_name);
  1283. output_declaration($declaration_name,
  1284. 'function',
  1285. {'function' => $declaration_name,
  1286. 'typedef' => 1,
  1287. 'module' => $modulename,
  1288. 'functiontype' => $return_type,
  1289. 'parameterlist' => \@parameterlist,
  1290. 'parameterdescs' => \%parameterdescs,
  1291. 'parametertypes' => \%parametertypes,
  1292. 'sectionlist' => \@sectionlist,
  1293. 'sections' => \%sections,
  1294. 'purpose' => $declaration_purpose
  1295. });
  1296. return;
  1297. }
  1298. while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
  1299. $x =~ s/\(*.\)\s*;$/;/;
  1300. $x =~ s/\[*.\]\s*;$/;/;
  1301. }
  1302. if ($x =~ /typedef.*\s+(\w+)\s*;/) {
  1303. $declaration_name = $1;
  1304. output_declaration($declaration_name,
  1305. 'typedef',
  1306. {'typedef' => $declaration_name,
  1307. 'module' => $modulename,
  1308. 'sectionlist' => \@sectionlist,
  1309. 'sections' => \%sections,
  1310. 'purpose' => $declaration_purpose
  1311. });
  1312. }
  1313. else {
  1314. print STDERR "${file}:$.: error: Cannot parse typedef!\n";
  1315. ++$errors;
  1316. }
  1317. }
  1318. sub save_struct_actual($) {
  1319. my $actual = shift;
  1320. # strip all spaces from the actual param so that it looks like one string item
  1321. $actual =~ s/\s*//g;
  1322. $struct_actual = $struct_actual . $actual . " ";
  1323. }
  1324. sub create_parameterlist($$$$) {
  1325. my $args = shift;
  1326. my $splitter = shift;
  1327. my $file = shift;
  1328. my $declaration_name = shift;
  1329. my $type;
  1330. my $param;
  1331. # temporarily replace commas inside function pointer definition
  1332. while ($args =~ /(\([^\),]+),/) {
  1333. $args =~ s/(\([^\),]+),/$1#/g;
  1334. }
  1335. foreach my $arg (split($splitter, $args)) {
  1336. # strip comments
  1337. $arg =~ s/\/\*.*\*\///;
  1338. # strip leading/trailing spaces
  1339. $arg =~ s/^\s*//;
  1340. $arg =~ s/\s*$//;
  1341. $arg =~ s/\s+/ /;
  1342. if ($arg =~ /^#/) {
  1343. # Treat preprocessor directive as a typeless variable just to fill
  1344. # corresponding data structures "correctly". Catch it later in
  1345. # output_* subs.
  1346. push_parameter($arg, "", "", $file);
  1347. } elsif ($arg =~ m/\(.+\)\s*\(/) {
  1348. # pointer-to-function
  1349. $arg =~ tr/#/,/;
  1350. $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
  1351. $param = $1;
  1352. $type = $arg;
  1353. $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
  1354. save_struct_actual($param);
  1355. push_parameter($param, $type, $arg, $file, $declaration_name);
  1356. } elsif ($arg) {
  1357. $arg =~ s/\s*:\s*/:/g;
  1358. $arg =~ s/\s*\[/\[/g;
  1359. my @args = split('\s*,\s*', $arg);
  1360. if ($args[0] =~ m/\*/) {
  1361. $args[0] =~ s/(\*+)\s*/ $1/;
  1362. }
  1363. my @first_arg;
  1364. if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
  1365. shift @args;
  1366. push(@first_arg, split('\s+', $1));
  1367. push(@first_arg, $2);
  1368. } else {
  1369. @first_arg = split('\s+', shift @args);
  1370. }
  1371. unshift(@args, pop @first_arg);
  1372. $type = join " ", @first_arg;
  1373. foreach $param (@args) {
  1374. if ($param =~ m/^(\*+)\s*(.*)/) {
  1375. save_struct_actual($2);
  1376. push_parameter($2, "$type $1", $arg, $file, $declaration_name);
  1377. }
  1378. elsif ($param =~ m/(.*?):(\d+)/) {
  1379. if ($type ne "") { # skip unnamed bit-fields
  1380. save_struct_actual($1);
  1381. push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
  1382. }
  1383. }
  1384. else {
  1385. save_struct_actual($param);
  1386. push_parameter($param, $type, $arg, $file, $declaration_name);
  1387. }
  1388. }
  1389. }
  1390. }
  1391. }
  1392. sub push_parameter($$$$$) {
  1393. my $param = shift;
  1394. my $type = shift;
  1395. my $org_arg = shift;
  1396. my $file = shift;
  1397. my $declaration_name = shift;
  1398. if (($anon_struct_union == 1) && ($type eq "") &&
  1399. ($param eq "}")) {
  1400. return; # ignore the ending }; from anon. struct/union
  1401. }
  1402. $anon_struct_union = 0;
  1403. $param =~ s/[\[\)].*//;
  1404. if ($type eq "" && $param =~ /\.\.\.$/)
  1405. {
  1406. if (!$param =~ /\w\.\.\.$/) {
  1407. # handles unnamed variable parameters
  1408. $param = "...";
  1409. }
  1410. elsif ($param =~ /\w\.\.\.$/) {
  1411. # for named variable parameters of the form `x...`, remove the dots
  1412. $param =~ s/\.\.\.$//;
  1413. }
  1414. if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
  1415. $parameterdescs{$param} = "variable arguments";
  1416. }
  1417. }
  1418. elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1419. {
  1420. $param="void";
  1421. $parameterdescs{void} = "no arguments";
  1422. }
  1423. elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
  1424. # handle unnamed (anonymous) union or struct:
  1425. {
  1426. $type = $param;
  1427. $param = "{unnamed_" . $param . "}";
  1428. $parameterdescs{$param} = "anonymous\n";
  1429. $anon_struct_union = 1;
  1430. }
  1431. # warn if parameter has no description
  1432. # (but ignore ones starting with # as these are not parameters
  1433. # but inline preprocessor statements);
  1434. # Note: It will also ignore void params and unnamed structs/unions
  1435. if (!defined $parameterdescs{$param} && $param !~ /^#/) {
  1436. $parameterdescs{$param} = $undescribed;
  1437. if (show_warnings($type, $declaration_name) && $param !~ /\./) {
  1438. print STDERR
  1439. "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
  1440. ++$warnings;
  1441. }
  1442. }
  1443. # strip spaces from $param so that it is one continuous string
  1444. # on @parameterlist;
  1445. # this fixes a problem where check_sections() cannot find
  1446. # a parameter like "addr[6 + 2]" because it actually appears
  1447. # as "addr[6", "+", "2]" on the parameter list;
  1448. # but it's better to maintain the param string unchanged for output,
  1449. # so just weaken the string compare in check_sections() to ignore
  1450. # "[blah" in a parameter string;
  1451. ###$param =~ s/\s*//g;
  1452. push @parameterlist, $param;
  1453. $org_arg =~ s/\s\s+/ /g;
  1454. $parametertypes{$param} = $org_arg;
  1455. }
  1456. sub check_sections($$$$$) {
  1457. my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
  1458. my @sects = split ' ', $sectcheck;
  1459. my @prms = split ' ', $prmscheck;
  1460. my $err;
  1461. my ($px, $sx);
  1462. my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
  1463. foreach $sx (0 .. $#sects) {
  1464. $err = 1;
  1465. foreach $px (0 .. $#prms) {
  1466. $prm_clean = $prms[$px];
  1467. $prm_clean =~ s/\[.*\]//;
  1468. $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
  1469. # ignore array size in a parameter string;
  1470. # however, the original param string may contain
  1471. # spaces, e.g.: addr[6 + 2]
  1472. # and this appears in @prms as "addr[6" since the
  1473. # parameter list is split at spaces;
  1474. # hence just ignore "[..." for the sections check;
  1475. $prm_clean =~ s/\[.*//;
  1476. ##$prm_clean =~ s/^\**//;
  1477. if ($prm_clean eq $sects[$sx]) {
  1478. $err = 0;
  1479. last;
  1480. }
  1481. }
  1482. if ($err) {
  1483. if ($decl_type eq "function") {
  1484. print STDERR "${file}:$.: warning: " .
  1485. "Excess function parameter " .
  1486. "'$sects[$sx]' " .
  1487. "description in '$decl_name'\n";
  1488. ++$warnings;
  1489. }
  1490. }
  1491. }
  1492. }
  1493. ##
  1494. # Checks the section describing the return value of a function.
  1495. sub check_return_section {
  1496. my $file = shift;
  1497. my $declaration_name = shift;
  1498. my $return_type = shift;
  1499. # Ignore an empty return type (It's a macro)
  1500. # Ignore functions with a "void" return type. (But don't ignore "void *")
  1501. if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
  1502. return;
  1503. }
  1504. if (!defined($sections{$section_return}) ||
  1505. $sections{$section_return} eq "") {
  1506. print STDERR "${file}:$.: warning: " .
  1507. "No description found for return value of " .
  1508. "'$declaration_name'\n";
  1509. ++$warnings;
  1510. }
  1511. }
  1512. ##
  1513. # takes a function prototype and the name of the current file being
  1514. # processed and spits out all the details stored in the global
  1515. # arrays/hashes.
  1516. sub dump_function($$) {
  1517. my $prototype = shift;
  1518. my $file = shift;
  1519. my $noret = 0;
  1520. print_lineno($new_start_line);
  1521. $prototype =~ s/^static +//;
  1522. $prototype =~ s/^extern +//;
  1523. $prototype =~ s/^asmlinkage +//;
  1524. $prototype =~ s/^inline +//;
  1525. $prototype =~ s/^__inline__ +//;
  1526. $prototype =~ s/^__inline +//;
  1527. $prototype =~ s/^__always_inline +//;
  1528. $prototype =~ s/^noinline +//;
  1529. $prototype =~ s/__init +//;
  1530. $prototype =~ s/__init_or_module +//;
  1531. $prototype =~ s/__meminit +//;
  1532. $prototype =~ s/__must_check +//;
  1533. $prototype =~ s/__weak +//;
  1534. $prototype =~ s/__sched +//;
  1535. $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
  1536. my $define = $prototype =~ s/^#\s*define\s+//; #ak added
  1537. $prototype =~ s/__attribute__\s*\(\(
  1538. (?:
  1539. [\w\s]++ # attribute name
  1540. (?:\([^)]*+\))? # attribute arguments
  1541. \s*+,? # optional comma at the end
  1542. )+
  1543. \)\)\s+//x;
  1544. # Yes, this truly is vile. We are looking for:
  1545. # 1. Return type (may be nothing if we're looking at a macro)
  1546. # 2. Function name
  1547. # 3. Function parameters.
  1548. #
  1549. # All the while we have to watch out for function pointer parameters
  1550. # (which IIRC is what the two sections are for), C types (these
  1551. # regexps don't even start to express all the possibilities), and
  1552. # so on.
  1553. #
  1554. # If you mess with these regexps, it's a good idea to check that
  1555. # the following functions' documentation still comes out right:
  1556. # - parport_register_device (function pointer parameters)
  1557. # - atomic_set (macro)
  1558. # - pci_match_device, __copy_to_user (long return type)
  1559. if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
  1560. # This is an object-like macro, it has no return type and no parameter
  1561. # list.
  1562. # Function-like macros are not allowed to have spaces between
  1563. # declaration_name and opening parenthesis (notice the \s+).
  1564. $return_type = $1;
  1565. $declaration_name = $2;
  1566. $noret = 1;
  1567. } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1568. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1569. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1570. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1571. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1572. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1573. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1574. $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1575. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1576. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1577. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1578. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1579. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1580. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1581. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1582. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1583. $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
  1584. $return_type = $1;
  1585. $declaration_name = $2;
  1586. my $args = $3;
  1587. create_parameterlist($args, ',', $file, $declaration_name);
  1588. } else {
  1589. print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
  1590. return;
  1591. }
  1592. my $prms = join " ", @parameterlist;
  1593. check_sections($file, $declaration_name, "function", $sectcheck, $prms);
  1594. # This check emits a lot of warnings at the moment, because many
  1595. # functions don't have a 'Return' doc section. So until the number
  1596. # of warnings goes sufficiently down, the check is only performed in
  1597. # verbose mode.
  1598. # TODO: always perform the check.
  1599. if ($verbose && !$noret) {
  1600. check_return_section($file, $declaration_name, $return_type);
  1601. }
  1602. # The function parser can be called with a typedef parameter.
  1603. # Handle it.
  1604. if ($return_type =~ /typedef/) {
  1605. output_declaration($declaration_name,
  1606. 'function',
  1607. {'function' => $declaration_name,
  1608. 'typedef' => 1,
  1609. 'module' => $modulename,
  1610. 'functiontype' => $return_type,
  1611. 'parameterlist' => \@parameterlist,
  1612. 'parameterdescs' => \%parameterdescs,
  1613. 'parametertypes' => \%parametertypes,
  1614. 'sectionlist' => \@sectionlist,
  1615. 'sections' => \%sections,
  1616. 'purpose' => $declaration_purpose
  1617. });
  1618. } else {
  1619. output_declaration($declaration_name,
  1620. 'function',
  1621. {'function' => $declaration_name,
  1622. 'module' => $modulename,
  1623. 'functiontype' => $return_type,
  1624. 'parameterlist' => \@parameterlist,
  1625. 'parameterdescs' => \%parameterdescs,
  1626. 'parametertypes' => \%parametertypes,
  1627. 'sectionlist' => \@sectionlist,
  1628. 'sections' => \%sections,
  1629. 'purpose' => $declaration_purpose
  1630. });
  1631. }
  1632. }
  1633. sub reset_state {
  1634. $function = "";
  1635. %parameterdescs = ();
  1636. %parametertypes = ();
  1637. @parameterlist = ();
  1638. %sections = ();
  1639. @sectionlist = ();
  1640. $sectcheck = "";
  1641. $struct_actual = "";
  1642. $prototype = "";
  1643. $state = STATE_NORMAL;
  1644. $inline_doc_state = STATE_INLINE_NA;
  1645. }
  1646. sub tracepoint_munge($) {
  1647. my $file = shift;
  1648. my $tracepointname = 0;
  1649. my $tracepointargs = 0;
  1650. if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
  1651. $tracepointname = $1;
  1652. }
  1653. if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
  1654. $tracepointname = $1;
  1655. }
  1656. if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
  1657. $tracepointname = $2;
  1658. }
  1659. $tracepointname =~ s/^\s+//; #strip leading whitespace
  1660. if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
  1661. $tracepointargs = $1;
  1662. }
  1663. if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
  1664. print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
  1665. "$prototype\n";
  1666. } else {
  1667. $prototype = "static inline void trace_$tracepointname($tracepointargs)";
  1668. }
  1669. }
  1670. sub syscall_munge() {
  1671. my $void = 0;
  1672. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
  1673. ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
  1674. if ($prototype =~ m/SYSCALL_DEFINE0/) {
  1675. $void = 1;
  1676. ## $prototype = "long sys_$1(void)";
  1677. }
  1678. $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
  1679. if ($prototype =~ m/long (sys_.*?),/) {
  1680. $prototype =~ s/,/\(/;
  1681. } elsif ($void) {
  1682. $prototype =~ s/\)/\(void\)/;
  1683. }
  1684. # now delete all of the odd-number commas in $prototype
  1685. # so that arg types & arg names don't have a comma between them
  1686. my $count = 0;
  1687. my $len = length($prototype);
  1688. if ($void) {
  1689. $len = 0; # skip the for-loop
  1690. }
  1691. for (my $ix = 0; $ix < $len; $ix++) {
  1692. if (substr($prototype, $ix, 1) eq ',') {
  1693. $count++;
  1694. if ($count % 2 == 1) {
  1695. substr($prototype, $ix, 1) = ' ';
  1696. }
  1697. }
  1698. }
  1699. }
  1700. sub process_proto_function($$) {
  1701. my $x = shift;
  1702. my $file = shift;
  1703. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1704. if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
  1705. # do nothing
  1706. }
  1707. elsif ($x =~ /([^\{]*)/) {
  1708. $prototype .= $1;
  1709. }
  1710. if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
  1711. $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
  1712. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1713. $prototype =~ s@^\s+@@gos; # strip leading spaces
  1714. # Handle prototypes for function pointers like:
  1715. # int (*pcs_config)(struct foo)
  1716. $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
  1717. if ($prototype =~ /SYSCALL_DEFINE/) {
  1718. syscall_munge();
  1719. }
  1720. if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
  1721. $prototype =~ /DEFINE_SINGLE_EVENT/)
  1722. {
  1723. tracepoint_munge($file);
  1724. }
  1725. dump_function($prototype, $file);
  1726. reset_state();
  1727. }
  1728. }
  1729. sub process_proto_type($$) {
  1730. my $x = shift;
  1731. my $file = shift;
  1732. $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1733. $x =~ s@^\s+@@gos; # strip leading spaces
  1734. $x =~ s@\s+$@@gos; # strip trailing spaces
  1735. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1736. if ($x =~ /^#/) {
  1737. # To distinguish preprocessor directive from regular declaration later.
  1738. $x .= ";";
  1739. }
  1740. while (1) {
  1741. if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
  1742. if( length $prototype ) {
  1743. $prototype .= " "
  1744. }
  1745. $prototype .= $1 . $2;
  1746. ($2 eq '{') && $brcount++;
  1747. ($2 eq '}') && $brcount--;
  1748. if (($2 eq ';') && ($brcount == 0)) {
  1749. dump_declaration($prototype, $file);
  1750. reset_state();
  1751. last;
  1752. }
  1753. $x = $3;
  1754. } else {
  1755. $prototype .= $x;
  1756. last;
  1757. }
  1758. }
  1759. }
  1760. sub map_filename($) {
  1761. my $file;
  1762. my ($orig_file) = @_;
  1763. if (defined($ENV{'SRCTREE'})) {
  1764. $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
  1765. } else {
  1766. $file = $orig_file;
  1767. }
  1768. if (defined($source_map{$file})) {
  1769. $file = $source_map{$file};
  1770. }
  1771. return $file;
  1772. }
  1773. sub process_export_file($) {
  1774. my ($orig_file) = @_;
  1775. my $file = map_filename($orig_file);
  1776. if (!open(IN,"<$file")) {
  1777. print STDERR "Error: Cannot open file $file\n";
  1778. ++$errors;
  1779. return;
  1780. }
  1781. while (<IN>) {
  1782. if (/$export_symbol/) {
  1783. next if (defined($nosymbol_table{$2}));
  1784. $function_table{$2} = 1;
  1785. }
  1786. }
  1787. close(IN);
  1788. }
  1789. #
  1790. # Parsers for the various processing states.
  1791. #
  1792. # STATE_NORMAL: looking for the /** to begin everything.
  1793. #
  1794. sub process_normal() {
  1795. if (/$doc_start/o) {
  1796. $state = STATE_NAME; # next line is always the function name
  1797. $in_doc_sect = 0;
  1798. $declaration_start_line = $. + 1;
  1799. }
  1800. }
  1801. #
  1802. # STATE_NAME: Looking for the "name - description" line
  1803. #
  1804. sub process_name($$) {
  1805. my $file = shift;
  1806. my $identifier;
  1807. my $descr;
  1808. if (/$doc_block/o) {
  1809. $state = STATE_DOCBLOCK;
  1810. $contents = "";
  1811. $new_start_line = $.;
  1812. if ( $1 eq "" ) {
  1813. $section = $section_intro;
  1814. } else {
  1815. $section = $1;
  1816. }
  1817. }
  1818. elsif (/$doc_decl/o) {
  1819. $identifier = $1;
  1820. if (/\s*([\w\s]+?)(\(\))?\s*-/) {
  1821. $identifier = $1;
  1822. }
  1823. $state = STATE_BODY;
  1824. # if there's no @param blocks need to set up default section
  1825. # here
  1826. $contents = "";
  1827. $section = $section_default;
  1828. $new_start_line = $. + 1;
  1829. if (/-(.*)/) {
  1830. # strip leading/trailing/multiple spaces
  1831. $descr= $1;
  1832. $descr =~ s/^\s*//;
  1833. $descr =~ s/\s*$//;
  1834. $descr =~ s/\s+/ /g;
  1835. $declaration_purpose = $descr;
  1836. $state = STATE_BODY_MAYBE;
  1837. } else {
  1838. $declaration_purpose = "";
  1839. }
  1840. if (($declaration_purpose eq "") && $verbose) {
  1841. print STDERR "${file}:$.: warning: missing initial short description on line:\n";
  1842. print STDERR $_;
  1843. ++$warnings;
  1844. }
  1845. if ($identifier =~ m/^struct\b/) {
  1846. $decl_type = 'struct';
  1847. } elsif ($identifier =~ m/^union\b/) {
  1848. $decl_type = 'union';
  1849. } elsif ($identifier =~ m/^enum\b/) {
  1850. $decl_type = 'enum';
  1851. } elsif ($identifier =~ m/^typedef\b/) {
  1852. $decl_type = 'typedef';
  1853. } else {
  1854. $decl_type = 'function';
  1855. }
  1856. if ($verbose) {
  1857. print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
  1858. }
  1859. } else {
  1860. print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
  1861. " - I thought it was a doc line\n";
  1862. ++$warnings;
  1863. $state = STATE_NORMAL;
  1864. }
  1865. }
  1866. #
  1867. # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
  1868. #
  1869. sub process_body($$) {
  1870. my $file = shift;
  1871. # Until all named variable macro parameters are
  1872. # documented using the bare name (`x`) rather than with
  1873. # dots (`x...`), strip the dots:
  1874. if ($section =~ /\w\.\.\.$/) {
  1875. $section =~ s/\.\.\.$//;
  1876. if ($verbose) {
  1877. print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
  1878. ++$warnings;
  1879. }
  1880. }
  1881. if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
  1882. dump_section($file, $section, $contents);
  1883. $section = $section_default;
  1884. $new_start_line = $.;
  1885. $contents = "";
  1886. }
  1887. if (/$doc_sect/i) { # case insensitive for supported section names
  1888. $newsection = $1;
  1889. $newcontents = $2;
  1890. # map the supported section names to the canonical names
  1891. if ($newsection =~ m/^description$/i) {
  1892. $newsection = $section_default;
  1893. } elsif ($newsection =~ m/^context$/i) {
  1894. $newsection = $section_context;
  1895. } elsif ($newsection =~ m/^returns?$/i) {
  1896. $newsection = $section_return;
  1897. } elsif ($newsection =~ m/^\@return$/) {
  1898. # special: @return is a section, not a param description
  1899. $newsection = $section_return;
  1900. }
  1901. if (($contents ne "") && ($contents ne "\n")) {
  1902. if (!$in_doc_sect && $verbose) {
  1903. print STDERR "${file}:$.: warning: contents before sections\n";
  1904. ++$warnings;
  1905. }
  1906. dump_section($file, $section, $contents);
  1907. $section = $section_default;
  1908. }
  1909. $in_doc_sect = 1;
  1910. $state = STATE_BODY;
  1911. $contents = $newcontents;
  1912. $new_start_line = $.;
  1913. while (substr($contents, 0, 1) eq " ") {
  1914. $contents = substr($contents, 1);
  1915. }
  1916. if ($contents ne "") {
  1917. $contents .= "\n";
  1918. }
  1919. $section = $newsection;
  1920. $leading_space = undef;
  1921. } elsif (/$doc_end/) {
  1922. if (($contents ne "") && ($contents ne "\n")) {
  1923. dump_section($file, $section, $contents);
  1924. $section = $section_default;
  1925. $contents = "";
  1926. }
  1927. # look for doc_com + <text> + doc_end:
  1928. if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
  1929. print STDERR "${file}:$.: warning: suspicious ending line: $_";
  1930. ++$warnings;
  1931. }
  1932. $prototype = "";
  1933. $state = STATE_PROTO;
  1934. $brcount = 0;
  1935. $new_start_line = $. + 1;
  1936. } elsif (/$doc_content/) {
  1937. if ($1 eq "") {
  1938. if ($section eq $section_context) {
  1939. dump_section($file, $section, $contents);
  1940. $section = $section_default;
  1941. $contents = "";
  1942. $new_start_line = $.;
  1943. $state = STATE_BODY;
  1944. } else {
  1945. if ($section ne $section_default) {
  1946. $state = STATE_BODY_WITH_BLANK_LINE;
  1947. } else {
  1948. $state = STATE_BODY;
  1949. }
  1950. $contents .= "\n";
  1951. }
  1952. } elsif ($state == STATE_BODY_MAYBE) {
  1953. # Continued declaration purpose
  1954. chomp($declaration_purpose);
  1955. $declaration_purpose .= " " . $1;
  1956. $declaration_purpose =~ s/\s+/ /g;
  1957. } else {
  1958. my $cont = $1;
  1959. if ($section =~ m/^@/ || $section eq $section_context) {
  1960. if (!defined $leading_space) {
  1961. if ($cont =~ m/^(\s+)/) {
  1962. $leading_space = $1;
  1963. } else {
  1964. $leading_space = "";
  1965. }
  1966. }
  1967. $cont =~ s/^$leading_space//;
  1968. }
  1969. $contents .= $cont . "\n";
  1970. }
  1971. } else {
  1972. # i dont know - bad line? ignore.
  1973. print STDERR "${file}:$.: warning: bad line: $_";
  1974. ++$warnings;
  1975. }
  1976. }
  1977. #
  1978. # STATE_PROTO: reading a function/whatever prototype.
  1979. #
  1980. sub process_proto($$) {
  1981. my $file = shift;
  1982. if (/$doc_inline_oneline/) {
  1983. $section = $1;
  1984. $contents = $2;
  1985. if ($contents ne "") {
  1986. $contents .= "\n";
  1987. dump_section($file, $section, $contents);
  1988. $section = $section_default;
  1989. $contents = "";
  1990. }
  1991. } elsif (/$doc_inline_start/) {
  1992. $state = STATE_INLINE;
  1993. $inline_doc_state = STATE_INLINE_NAME;
  1994. } elsif ($decl_type eq 'function') {
  1995. process_proto_function($_, $file);
  1996. } else {
  1997. process_proto_type($_, $file);
  1998. }
  1999. }
  2000. #
  2001. # STATE_DOCBLOCK: within a DOC: block.
  2002. #
  2003. sub process_docblock($$) {
  2004. my $file = shift;
  2005. if (/$doc_end/) {
  2006. dump_doc_section($file, $section, $contents);
  2007. $section = $section_default;
  2008. $contents = "";
  2009. $function = "";
  2010. %parameterdescs = ();
  2011. %parametertypes = ();
  2012. @parameterlist = ();
  2013. %sections = ();
  2014. @sectionlist = ();
  2015. $prototype = "";
  2016. $state = STATE_NORMAL;
  2017. } elsif (/$doc_content/) {
  2018. if ( $1 eq "" ) {
  2019. $contents .= $blankline;
  2020. } else {
  2021. $contents .= $1 . "\n";
  2022. }
  2023. }
  2024. }
  2025. #
  2026. # STATE_INLINE: docbook comments within a prototype.
  2027. #
  2028. sub process_inline($$) {
  2029. my $file = shift;
  2030. # First line (state 1) needs to be a @parameter
  2031. if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
  2032. $section = $1;
  2033. $contents = $2;
  2034. $new_start_line = $.;
  2035. if ($contents ne "") {
  2036. while (substr($contents, 0, 1) eq " ") {
  2037. $contents = substr($contents, 1);
  2038. }
  2039. $contents .= "\n";
  2040. }
  2041. $inline_doc_state = STATE_INLINE_TEXT;
  2042. # Documentation block end */
  2043. } elsif (/$doc_inline_end/) {
  2044. if (($contents ne "") && ($contents ne "\n")) {
  2045. dump_section($file, $section, $contents);
  2046. $section = $section_default;
  2047. $contents = "";
  2048. }
  2049. $state = STATE_PROTO;
  2050. $inline_doc_state = STATE_INLINE_NA;
  2051. # Regular text
  2052. } elsif (/$doc_content/) {
  2053. if ($inline_doc_state == STATE_INLINE_TEXT) {
  2054. $contents .= $1 . "\n";
  2055. # nuke leading blank lines
  2056. if ($contents =~ /^\s*$/) {
  2057. $contents = "";
  2058. }
  2059. } elsif ($inline_doc_state == STATE_INLINE_NAME) {
  2060. $inline_doc_state = STATE_INLINE_ERROR;
  2061. print STDERR "${file}:$.: warning: ";
  2062. print STDERR "Incorrect use of kernel-doc format: $_";
  2063. ++$warnings;
  2064. }
  2065. }
  2066. }
  2067. sub process_file($) {
  2068. my $file;
  2069. my $initial_section_counter = $section_counter;
  2070. my ($orig_file) = @_;
  2071. $file = map_filename($orig_file);
  2072. if (!open(IN_FILE,"<$file")) {
  2073. print STDERR "Error: Cannot open file $file\n";
  2074. ++$errors;
  2075. return;
  2076. }
  2077. $. = 1;
  2078. $section_counter = 0;
  2079. while (<IN_FILE>) {
  2080. while (s/\\\s*$//) {
  2081. $_ .= <IN_FILE>;
  2082. }
  2083. # Replace tabs by spaces
  2084. while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
  2085. # Hand this line to the appropriate state handler
  2086. if ($state == STATE_NORMAL) {
  2087. process_normal();
  2088. } elsif ($state == STATE_NAME) {
  2089. process_name($file, $_);
  2090. } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
  2091. $state == STATE_BODY_WITH_BLANK_LINE) {
  2092. process_body($file, $_);
  2093. } elsif ($state == STATE_INLINE) { # scanning for inline parameters
  2094. process_inline($file, $_);
  2095. } elsif ($state == STATE_PROTO) {
  2096. process_proto($file, $_);
  2097. } elsif ($state == STATE_DOCBLOCK) {
  2098. process_docblock($file, $_);
  2099. }
  2100. }
  2101. # Make sure we got something interesting.
  2102. if ($initial_section_counter == $section_counter && $
  2103. output_mode ne "none") {
  2104. if ($output_selection == OUTPUT_INCLUDE) {
  2105. print STDERR "${file}:1: warning: '$_' not found\n"
  2106. for keys %function_table;
  2107. }
  2108. else {
  2109. print STDERR "${file}:1: warning: no structured comments found\n";
  2110. }
  2111. }
  2112. close IN_FILE;
  2113. }
  2114. if ($output_mode eq "rst") {
  2115. get_sphinx_version() if (!$sphinx_major);
  2116. }
  2117. $kernelversion = get_kernel_version();
  2118. # generate a sequence of code that will splice in highlighting information
  2119. # using the s// operator.
  2120. for (my $k = 0; $k < @highlights; $k++) {
  2121. my $pattern = $highlights[$k][0];
  2122. my $result = $highlights[$k][1];
  2123. # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
  2124. $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
  2125. }
  2126. # Read the file that maps relative names to absolute names for
  2127. # separate source and object directories and for shadow trees.
  2128. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  2129. my ($relname, $absname);
  2130. while(<SOURCE_MAP>) {
  2131. chop();
  2132. ($relname, $absname) = (split())[0..1];
  2133. $relname =~ s:^/+::;
  2134. $source_map{$relname} = $absname;
  2135. }
  2136. close(SOURCE_MAP);
  2137. }
  2138. if ($output_selection == OUTPUT_EXPORTED ||
  2139. $output_selection == OUTPUT_INTERNAL) {
  2140. push(@export_file_list, @ARGV);
  2141. foreach (@export_file_list) {
  2142. chomp;
  2143. process_export_file($_);
  2144. }
  2145. }
  2146. foreach (@ARGV) {
  2147. chomp;
  2148. process_file($_);
  2149. }
  2150. if ($verbose && $errors) {
  2151. print STDERR "$errors errors\n";
  2152. }
  2153. if ($verbose && $warnings) {
  2154. print STDERR "$warnings warnings\n";
  2155. }
  2156. if ($Werror && $warnings) {
  2157. print STDERR "$warnings warnings as Errors\n";
  2158. exit($warnings);
  2159. } else {
  2160. exit($output_mode eq "none" ? 0 : $errors)
  2161. }