kernel-doc 66 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441
  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. $arg =~ s/\s*EFIAPI\s*/ /g;
  1339. # strip leading/trailing spaces
  1340. $arg =~ s/^\s*//;
  1341. $arg =~ s/\s*$//;
  1342. $arg =~ s/\s+/ /;
  1343. if ($arg =~ /^#/) {
  1344. # Treat preprocessor directive as a typeless variable just to fill
  1345. # corresponding data structures "correctly". Catch it later in
  1346. # output_* subs.
  1347. push_parameter($arg, "", "", $file);
  1348. } elsif ($arg =~ m/\(.+\)\s*\(/) {
  1349. # pointer-to-function
  1350. $arg =~ tr/#/,/;
  1351. $arg =~ m/[^\(]+\(\s*\*?\s*([\w\.]*)\s*\)/;
  1352. $param = $1;
  1353. $type = $arg;
  1354. $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
  1355. save_struct_actual($param);
  1356. push_parameter($param, $type, $arg, $file, $declaration_name);
  1357. } elsif ($arg) {
  1358. $arg =~ s/\s*:\s*/:/g;
  1359. $arg =~ s/\s*\[/\[/g;
  1360. my @args = split('\s*,\s*', $arg);
  1361. if ($args[0] =~ m/\*/) {
  1362. $args[0] =~ s/(\*+)\s*/ $1/;
  1363. }
  1364. my @first_arg;
  1365. if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
  1366. shift @args;
  1367. push(@first_arg, split('\s+', $1));
  1368. push(@first_arg, $2);
  1369. } else {
  1370. @first_arg = split('\s+', shift @args);
  1371. }
  1372. unshift(@args, pop @first_arg);
  1373. $type = join " ", @first_arg;
  1374. foreach $param (@args) {
  1375. if ($param =~ m/^(\*+)\s*(.*)/) {
  1376. save_struct_actual($2);
  1377. push_parameter($2, "$type $1", $arg, $file, $declaration_name);
  1378. }
  1379. elsif ($param =~ m/(.*?):(\d+)/) {
  1380. if ($type ne "") { # skip unnamed bit-fields
  1381. save_struct_actual($1);
  1382. push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
  1383. }
  1384. }
  1385. else {
  1386. save_struct_actual($param);
  1387. push_parameter($param, $type, $arg, $file, $declaration_name);
  1388. }
  1389. }
  1390. }
  1391. }
  1392. }
  1393. sub push_parameter($$$$$) {
  1394. my $param = shift;
  1395. my $type = shift;
  1396. my $org_arg = shift;
  1397. my $file = shift;
  1398. my $declaration_name = shift;
  1399. if (($anon_struct_union == 1) && ($type eq "") &&
  1400. ($param eq "}")) {
  1401. return; # ignore the ending }; from anon. struct/union
  1402. }
  1403. $anon_struct_union = 0;
  1404. $param =~ s/[\[\)].*//;
  1405. if ($type eq "" && $param =~ /\.\.\.$/)
  1406. {
  1407. if (!$param =~ /\w\.\.\.$/) {
  1408. # handles unnamed variable parameters
  1409. $param = "...";
  1410. }
  1411. elsif ($param =~ /\w\.\.\.$/) {
  1412. # for named variable parameters of the form `x...`, remove the dots
  1413. $param =~ s/\.\.\.$//;
  1414. }
  1415. if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
  1416. $parameterdescs{$param} = "variable arguments";
  1417. }
  1418. }
  1419. elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1420. {
  1421. $param="void";
  1422. $parameterdescs{void} = "no arguments";
  1423. }
  1424. elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
  1425. # handle unnamed (anonymous) union or struct:
  1426. {
  1427. $type = $param;
  1428. $param = "{unnamed_" . $param . "}";
  1429. $parameterdescs{$param} = "anonymous\n";
  1430. $anon_struct_union = 1;
  1431. }
  1432. # warn if parameter has no description
  1433. # (but ignore ones starting with # as these are not parameters
  1434. # but inline preprocessor statements);
  1435. # Note: It will also ignore void params and unnamed structs/unions
  1436. if (!defined $parameterdescs{$param} && $param !~ /^#/) {
  1437. $parameterdescs{$param} = $undescribed;
  1438. if (show_warnings($type, $declaration_name) && $param !~ /\./) {
  1439. print STDERR
  1440. "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
  1441. ++$warnings;
  1442. }
  1443. }
  1444. # strip spaces from $param so that it is one continuous string
  1445. # on @parameterlist;
  1446. # this fixes a problem where check_sections() cannot find
  1447. # a parameter like "addr[6 + 2]" because it actually appears
  1448. # as "addr[6", "+", "2]" on the parameter list;
  1449. # but it's better to maintain the param string unchanged for output,
  1450. # so just weaken the string compare in check_sections() to ignore
  1451. # "[blah" in a parameter string;
  1452. ###$param =~ s/\s*//g;
  1453. push @parameterlist, $param;
  1454. $org_arg =~ s/\s\s+/ /g;
  1455. $parametertypes{$param} = $org_arg;
  1456. }
  1457. sub check_sections($$$$$) {
  1458. my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
  1459. my @sects = split ' ', $sectcheck;
  1460. my @prms = split ' ', $prmscheck;
  1461. my $err;
  1462. my ($px, $sx);
  1463. my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
  1464. foreach $sx (0 .. $#sects) {
  1465. $err = 1;
  1466. foreach $px (0 .. $#prms) {
  1467. $prm_clean = $prms[$px];
  1468. $prm_clean =~ s/\[.*\]//;
  1469. $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
  1470. # ignore array size in a parameter string;
  1471. # however, the original param string may contain
  1472. # spaces, e.g.: addr[6 + 2]
  1473. # and this appears in @prms as "addr[6" since the
  1474. # parameter list is split at spaces;
  1475. # hence just ignore "[..." for the sections check;
  1476. $prm_clean =~ s/\[.*//;
  1477. ##$prm_clean =~ s/^\**//;
  1478. if ($prm_clean eq $sects[$sx]) {
  1479. $err = 0;
  1480. last;
  1481. }
  1482. }
  1483. if ($err) {
  1484. if ($decl_type eq "function") {
  1485. print STDERR "${file}:$.: warning: " .
  1486. "Excess function parameter " .
  1487. "'$sects[$sx]' " .
  1488. "description in '$decl_name'\n";
  1489. ++$warnings;
  1490. }
  1491. }
  1492. }
  1493. }
  1494. ##
  1495. # Checks the section describing the return value of a function.
  1496. sub check_return_section {
  1497. my $file = shift;
  1498. my $declaration_name = shift;
  1499. my $return_type = shift;
  1500. # Ignore an empty return type (It's a macro)
  1501. # Ignore functions with a "void" return type. (But don't ignore "void *")
  1502. if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
  1503. return;
  1504. }
  1505. if (!defined($sections{$section_return}) ||
  1506. $sections{$section_return} eq "") {
  1507. print STDERR "${file}:$.: warning: " .
  1508. "No description found for return value of " .
  1509. "'$declaration_name'\n";
  1510. ++$warnings;
  1511. }
  1512. }
  1513. ##
  1514. # takes a function prototype and the name of the current file being
  1515. # processed and spits out all the details stored in the global
  1516. # arrays/hashes.
  1517. sub dump_function($$) {
  1518. my $prototype = shift;
  1519. my $file = shift;
  1520. my $noret = 0;
  1521. print_lineno($new_start_line);
  1522. $prototype =~ s/^static +//;
  1523. $prototype =~ s/^extern +//;
  1524. $prototype =~ s/^asmlinkage +//;
  1525. $prototype =~ s/^inline +//;
  1526. $prototype =~ s/^__inline__ +//;
  1527. $prototype =~ s/^__inline +//;
  1528. $prototype =~ s/^__always_inline +//;
  1529. $prototype =~ s/^noinline +//;
  1530. $prototype =~ s/__init +//;
  1531. $prototype =~ s/__init_or_module +//;
  1532. $prototype =~ s/__meminit +//;
  1533. $prototype =~ s/__must_check +//;
  1534. $prototype =~ s/__weak +//;
  1535. $prototype =~ s/__sched +//;
  1536. $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
  1537. my $define = $prototype =~ s/^#\s*define\s+//; #ak added
  1538. $prototype =~ s/__attribute__\s*\(\(
  1539. (?:
  1540. [\w\s]++ # attribute name
  1541. (?:\([^)]*+\))? # attribute arguments
  1542. \s*+,? # optional comma at the end
  1543. )+
  1544. \)\)\s+//x;
  1545. # Yes, this truly is vile. We are looking for:
  1546. # 1. Return type (may be nothing if we're looking at a macro)
  1547. # 2. Function name
  1548. # 3. Function parameters.
  1549. #
  1550. # All the while we have to watch out for function pointer parameters
  1551. # (which IIRC is what the two sections are for), C types (these
  1552. # regexps don't even start to express all the possibilities), and
  1553. # so on.
  1554. #
  1555. # If you mess with these regexps, it's a good idea to check that
  1556. # the following functions' documentation still comes out right:
  1557. # - parport_register_device (function pointer parameters)
  1558. # - atomic_set (macro)
  1559. # - pci_match_device, __copy_to_user (long return type)
  1560. if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
  1561. # This is an object-like macro, it has no return type and no parameter
  1562. # list.
  1563. # Function-like macros are not allowed to have spaces between
  1564. # declaration_name and opening parenthesis (notice the \s+).
  1565. $return_type = $1;
  1566. $declaration_name = $2;
  1567. $noret = 1;
  1568. } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1569. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1570. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1571. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1572. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1573. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1574. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1575. $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1576. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1577. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1578. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1579. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1580. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1581. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1582. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1583. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1584. $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
  1585. $return_type = $1;
  1586. $declaration_name = $2;
  1587. my $args = $3;
  1588. create_parameterlist($args, ',', $file, $declaration_name);
  1589. } else {
  1590. print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
  1591. return;
  1592. }
  1593. my $prms = join " ", @parameterlist;
  1594. check_sections($file, $declaration_name, "function", $sectcheck, $prms);
  1595. # This check emits a lot of warnings at the moment, because many
  1596. # functions don't have a 'Return' doc section. So until the number
  1597. # of warnings goes sufficiently down, the check is only performed in
  1598. # verbose mode.
  1599. # TODO: always perform the check.
  1600. if ($verbose && !$noret) {
  1601. check_return_section($file, $declaration_name, $return_type);
  1602. }
  1603. # The function parser can be called with a typedef parameter.
  1604. # Handle it.
  1605. if ($return_type =~ /typedef/) {
  1606. output_declaration($declaration_name,
  1607. 'function',
  1608. {'function' => $declaration_name,
  1609. 'typedef' => 1,
  1610. 'module' => $modulename,
  1611. 'functiontype' => $return_type,
  1612. 'parameterlist' => \@parameterlist,
  1613. 'parameterdescs' => \%parameterdescs,
  1614. 'parametertypes' => \%parametertypes,
  1615. 'sectionlist' => \@sectionlist,
  1616. 'sections' => \%sections,
  1617. 'purpose' => $declaration_purpose
  1618. });
  1619. } else {
  1620. output_declaration($declaration_name,
  1621. 'function',
  1622. {'function' => $declaration_name,
  1623. 'module' => $modulename,
  1624. 'functiontype' => $return_type,
  1625. 'parameterlist' => \@parameterlist,
  1626. 'parameterdescs' => \%parameterdescs,
  1627. 'parametertypes' => \%parametertypes,
  1628. 'sectionlist' => \@sectionlist,
  1629. 'sections' => \%sections,
  1630. 'purpose' => $declaration_purpose
  1631. });
  1632. }
  1633. }
  1634. sub reset_state {
  1635. $function = "";
  1636. %parameterdescs = ();
  1637. %parametertypes = ();
  1638. @parameterlist = ();
  1639. %sections = ();
  1640. @sectionlist = ();
  1641. $sectcheck = "";
  1642. $struct_actual = "";
  1643. $prototype = "";
  1644. $state = STATE_NORMAL;
  1645. $inline_doc_state = STATE_INLINE_NA;
  1646. }
  1647. sub tracepoint_munge($) {
  1648. my $file = shift;
  1649. my $tracepointname = 0;
  1650. my $tracepointargs = 0;
  1651. if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
  1652. $tracepointname = $1;
  1653. }
  1654. if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
  1655. $tracepointname = $1;
  1656. }
  1657. if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
  1658. $tracepointname = $2;
  1659. }
  1660. $tracepointname =~ s/^\s+//; #strip leading whitespace
  1661. if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
  1662. $tracepointargs = $1;
  1663. }
  1664. if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
  1665. print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
  1666. "$prototype\n";
  1667. } else {
  1668. $prototype = "static inline void trace_$tracepointname($tracepointargs)";
  1669. }
  1670. }
  1671. sub syscall_munge() {
  1672. my $void = 0;
  1673. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
  1674. ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
  1675. if ($prototype =~ m/SYSCALL_DEFINE0/) {
  1676. $void = 1;
  1677. ## $prototype = "long sys_$1(void)";
  1678. }
  1679. $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
  1680. if ($prototype =~ m/long (sys_.*?),/) {
  1681. $prototype =~ s/,/\(/;
  1682. } elsif ($void) {
  1683. $prototype =~ s/\)/\(void\)/;
  1684. }
  1685. # now delete all of the odd-number commas in $prototype
  1686. # so that arg types & arg names don't have a comma between them
  1687. my $count = 0;
  1688. my $len = length($prototype);
  1689. if ($void) {
  1690. $len = 0; # skip the for-loop
  1691. }
  1692. for (my $ix = 0; $ix < $len; $ix++) {
  1693. if (substr($prototype, $ix, 1) eq ',') {
  1694. $count++;
  1695. if ($count % 2 == 1) {
  1696. substr($prototype, $ix, 1) = ' ';
  1697. }
  1698. }
  1699. }
  1700. }
  1701. sub process_proto_function($$) {
  1702. my $x = shift;
  1703. my $file = shift;
  1704. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1705. if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
  1706. # do nothing
  1707. }
  1708. elsif ($x =~ /([^\{]*)/) {
  1709. $prototype .= $1;
  1710. }
  1711. if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
  1712. $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
  1713. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1714. $prototype =~ s@^\s+@@gos; # strip leading spaces
  1715. # Handle prototypes for function pointers like:
  1716. # int (*pcs_config)(struct foo)
  1717. $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
  1718. if ($prototype =~ /SYSCALL_DEFINE/) {
  1719. syscall_munge();
  1720. }
  1721. if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
  1722. $prototype =~ /DEFINE_SINGLE_EVENT/)
  1723. {
  1724. tracepoint_munge($file);
  1725. }
  1726. dump_function($prototype, $file);
  1727. reset_state();
  1728. }
  1729. }
  1730. sub process_proto_type($$) {
  1731. my $x = shift;
  1732. my $file = shift;
  1733. $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1734. $x =~ s@^\s+@@gos; # strip leading spaces
  1735. $x =~ s@\s+$@@gos; # strip trailing spaces
  1736. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1737. if ($x =~ /^#/) {
  1738. # To distinguish preprocessor directive from regular declaration later.
  1739. $x .= ";";
  1740. }
  1741. while (1) {
  1742. if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
  1743. if( length $prototype ) {
  1744. $prototype .= " "
  1745. }
  1746. $prototype .= $1 . $2;
  1747. ($2 eq '{') && $brcount++;
  1748. ($2 eq '}') && $brcount--;
  1749. if (($2 eq ';') && ($brcount == 0)) {
  1750. dump_declaration($prototype, $file);
  1751. reset_state();
  1752. last;
  1753. }
  1754. $x = $3;
  1755. } else {
  1756. $prototype .= $x;
  1757. last;
  1758. }
  1759. }
  1760. }
  1761. sub map_filename($) {
  1762. my $file;
  1763. my ($orig_file) = @_;
  1764. if (defined($ENV{'SRCTREE'})) {
  1765. $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
  1766. } else {
  1767. $file = $orig_file;
  1768. }
  1769. if (defined($source_map{$file})) {
  1770. $file = $source_map{$file};
  1771. }
  1772. return $file;
  1773. }
  1774. sub process_export_file($) {
  1775. my ($orig_file) = @_;
  1776. my $file = map_filename($orig_file);
  1777. if (!open(IN,"<$file")) {
  1778. print STDERR "Error: Cannot open file $file\n";
  1779. ++$errors;
  1780. return;
  1781. }
  1782. while (<IN>) {
  1783. if (/$export_symbol/) {
  1784. next if (defined($nosymbol_table{$2}));
  1785. $function_table{$2} = 1;
  1786. }
  1787. }
  1788. close(IN);
  1789. }
  1790. #
  1791. # Parsers for the various processing states.
  1792. #
  1793. # STATE_NORMAL: looking for the /** to begin everything.
  1794. #
  1795. sub process_normal() {
  1796. if (/$doc_start/o) {
  1797. $state = STATE_NAME; # next line is always the function name
  1798. $in_doc_sect = 0;
  1799. $declaration_start_line = $. + 1;
  1800. }
  1801. }
  1802. #
  1803. # STATE_NAME: Looking for the "name - description" line
  1804. #
  1805. sub process_name($$) {
  1806. my $file = shift;
  1807. my $identifier;
  1808. my $descr;
  1809. if (/$doc_block/o) {
  1810. $state = STATE_DOCBLOCK;
  1811. $contents = "";
  1812. $new_start_line = $.;
  1813. if ( $1 eq "" ) {
  1814. $section = $section_intro;
  1815. } else {
  1816. $section = $1;
  1817. }
  1818. }
  1819. elsif (/$doc_decl/o) {
  1820. $identifier = $1;
  1821. if (/\s*([\w\s]+?)(\(\))?\s*-/) {
  1822. $identifier = $1;
  1823. }
  1824. $state = STATE_BODY;
  1825. # if there's no @param blocks need to set up default section
  1826. # here
  1827. $contents = "";
  1828. $section = $section_default;
  1829. $new_start_line = $. + 1;
  1830. if (/-(.*)/) {
  1831. # strip leading/trailing/multiple spaces
  1832. $descr= $1;
  1833. $descr =~ s/^\s*//;
  1834. $descr =~ s/\s*$//;
  1835. $descr =~ s/\s+/ /g;
  1836. $declaration_purpose = $descr;
  1837. $state = STATE_BODY_MAYBE;
  1838. } else {
  1839. $declaration_purpose = "";
  1840. }
  1841. if (($declaration_purpose eq "") && $verbose) {
  1842. print STDERR "${file}:$.: warning: missing initial short description on line:\n";
  1843. print STDERR $_;
  1844. ++$warnings;
  1845. }
  1846. if ($identifier =~ m/^struct\b/) {
  1847. $decl_type = 'struct';
  1848. } elsif ($identifier =~ m/^union\b/) {
  1849. $decl_type = 'union';
  1850. } elsif ($identifier =~ m/^enum\b/) {
  1851. $decl_type = 'enum';
  1852. } elsif ($identifier =~ m/^typedef\b/) {
  1853. $decl_type = 'typedef';
  1854. } else {
  1855. $decl_type = 'function';
  1856. }
  1857. if ($verbose) {
  1858. print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
  1859. }
  1860. } else {
  1861. print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
  1862. " - I thought it was a doc line\n";
  1863. ++$warnings;
  1864. $state = STATE_NORMAL;
  1865. }
  1866. }
  1867. #
  1868. # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
  1869. #
  1870. sub process_body($$) {
  1871. my $file = shift;
  1872. # Until all named variable macro parameters are
  1873. # documented using the bare name (`x`) rather than with
  1874. # dots (`x...`), strip the dots:
  1875. if ($section =~ /\w\.\.\.$/) {
  1876. $section =~ s/\.\.\.$//;
  1877. if ($verbose) {
  1878. print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
  1879. ++$warnings;
  1880. }
  1881. }
  1882. if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
  1883. dump_section($file, $section, $contents);
  1884. $section = $section_default;
  1885. $new_start_line = $.;
  1886. $contents = "";
  1887. }
  1888. if (/$doc_sect/i) { # case insensitive for supported section names
  1889. $newsection = $1;
  1890. $newcontents = $2;
  1891. # map the supported section names to the canonical names
  1892. if ($newsection =~ m/^description$/i) {
  1893. $newsection = $section_default;
  1894. } elsif ($newsection =~ m/^context$/i) {
  1895. $newsection = $section_context;
  1896. } elsif ($newsection =~ m/^returns?$/i) {
  1897. $newsection = $section_return;
  1898. } elsif ($newsection =~ m/^\@return$/) {
  1899. # special: @return is a section, not a param description
  1900. $newsection = $section_return;
  1901. }
  1902. if (($contents ne "") && ($contents ne "\n")) {
  1903. if (!$in_doc_sect && $verbose) {
  1904. print STDERR "${file}:$.: warning: contents before sections\n";
  1905. ++$warnings;
  1906. }
  1907. dump_section($file, $section, $contents);
  1908. $section = $section_default;
  1909. }
  1910. $in_doc_sect = 1;
  1911. $state = STATE_BODY;
  1912. $contents = $newcontents;
  1913. $new_start_line = $.;
  1914. while (substr($contents, 0, 1) eq " ") {
  1915. $contents = substr($contents, 1);
  1916. }
  1917. if ($contents ne "") {
  1918. $contents .= "\n";
  1919. }
  1920. $section = $newsection;
  1921. $leading_space = undef;
  1922. } elsif (/$doc_end/) {
  1923. if (($contents ne "") && ($contents ne "\n")) {
  1924. dump_section($file, $section, $contents);
  1925. $section = $section_default;
  1926. $contents = "";
  1927. }
  1928. # look for doc_com + <text> + doc_end:
  1929. if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
  1930. print STDERR "${file}:$.: warning: suspicious ending line: $_";
  1931. ++$warnings;
  1932. }
  1933. $prototype = "";
  1934. $state = STATE_PROTO;
  1935. $brcount = 0;
  1936. $new_start_line = $. + 1;
  1937. } elsif (/$doc_content/) {
  1938. if ($1 eq "") {
  1939. if ($section eq $section_context) {
  1940. dump_section($file, $section, $contents);
  1941. $section = $section_default;
  1942. $contents = "";
  1943. $new_start_line = $.;
  1944. $state = STATE_BODY;
  1945. } else {
  1946. if ($section ne $section_default) {
  1947. $state = STATE_BODY_WITH_BLANK_LINE;
  1948. } else {
  1949. $state = STATE_BODY;
  1950. }
  1951. $contents .= "\n";
  1952. }
  1953. } elsif ($state == STATE_BODY_MAYBE) {
  1954. # Continued declaration purpose
  1955. chomp($declaration_purpose);
  1956. $declaration_purpose .= " " . $1;
  1957. $declaration_purpose =~ s/\s+/ /g;
  1958. } else {
  1959. my $cont = $1;
  1960. if ($section =~ m/^@/ || $section eq $section_context) {
  1961. if (!defined $leading_space) {
  1962. if ($cont =~ m/^(\s+)/) {
  1963. $leading_space = $1;
  1964. } else {
  1965. $leading_space = "";
  1966. }
  1967. }
  1968. $cont =~ s/^$leading_space//;
  1969. }
  1970. $contents .= $cont . "\n";
  1971. }
  1972. } else {
  1973. # i dont know - bad line? ignore.
  1974. print STDERR "${file}:$.: warning: bad line: $_";
  1975. ++$warnings;
  1976. }
  1977. }
  1978. #
  1979. # STATE_PROTO: reading a function/whatever prototype.
  1980. #
  1981. sub process_proto($$) {
  1982. my $file = shift;
  1983. if (/$doc_inline_oneline/) {
  1984. $section = $1;
  1985. $contents = $2;
  1986. if ($contents ne "") {
  1987. $contents .= "\n";
  1988. dump_section($file, $section, $contents);
  1989. $section = $section_default;
  1990. $contents = "";
  1991. }
  1992. } elsif (/$doc_inline_start/) {
  1993. $state = STATE_INLINE;
  1994. $inline_doc_state = STATE_INLINE_NAME;
  1995. } elsif ($decl_type eq 'function') {
  1996. process_proto_function($_, $file);
  1997. } else {
  1998. process_proto_type($_, $file);
  1999. }
  2000. }
  2001. #
  2002. # STATE_DOCBLOCK: within a DOC: block.
  2003. #
  2004. sub process_docblock($$) {
  2005. my $file = shift;
  2006. if (/$doc_end/) {
  2007. dump_doc_section($file, $section, $contents);
  2008. $section = $section_default;
  2009. $contents = "";
  2010. $function = "";
  2011. %parameterdescs = ();
  2012. %parametertypes = ();
  2013. @parameterlist = ();
  2014. %sections = ();
  2015. @sectionlist = ();
  2016. $prototype = "";
  2017. $state = STATE_NORMAL;
  2018. } elsif (/$doc_content/) {
  2019. if ( $1 eq "" ) {
  2020. $contents .= $blankline;
  2021. } else {
  2022. $contents .= $1 . "\n";
  2023. }
  2024. }
  2025. }
  2026. #
  2027. # STATE_INLINE: docbook comments within a prototype.
  2028. #
  2029. sub process_inline($$) {
  2030. my $file = shift;
  2031. # First line (state 1) needs to be a @parameter
  2032. if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
  2033. $section = $1;
  2034. $contents = $2;
  2035. $new_start_line = $.;
  2036. if ($contents ne "") {
  2037. while (substr($contents, 0, 1) eq " ") {
  2038. $contents = substr($contents, 1);
  2039. }
  2040. $contents .= "\n";
  2041. }
  2042. $inline_doc_state = STATE_INLINE_TEXT;
  2043. # Documentation block end */
  2044. } elsif (/$doc_inline_end/) {
  2045. if (($contents ne "") && ($contents ne "\n")) {
  2046. dump_section($file, $section, $contents);
  2047. $section = $section_default;
  2048. $contents = "";
  2049. }
  2050. $state = STATE_PROTO;
  2051. $inline_doc_state = STATE_INLINE_NA;
  2052. # Regular text
  2053. } elsif (/$doc_content/) {
  2054. if ($inline_doc_state == STATE_INLINE_TEXT) {
  2055. $contents .= $1 . "\n";
  2056. # nuke leading blank lines
  2057. if ($contents =~ /^\s*$/) {
  2058. $contents = "";
  2059. }
  2060. } elsif ($inline_doc_state == STATE_INLINE_NAME) {
  2061. $inline_doc_state = STATE_INLINE_ERROR;
  2062. print STDERR "${file}:$.: warning: ";
  2063. print STDERR "Incorrect use of kernel-doc format: $_";
  2064. ++$warnings;
  2065. }
  2066. }
  2067. }
  2068. sub process_file($) {
  2069. my $file;
  2070. my $initial_section_counter = $section_counter;
  2071. my ($orig_file) = @_;
  2072. $file = map_filename($orig_file);
  2073. if (!open(IN_FILE,"<$file")) {
  2074. print STDERR "Error: Cannot open file $file\n";
  2075. ++$errors;
  2076. return;
  2077. }
  2078. $. = 1;
  2079. $section_counter = 0;
  2080. while (<IN_FILE>) {
  2081. while (s/\\\s*$//) {
  2082. $_ .= <IN_FILE>;
  2083. }
  2084. # Replace tabs by spaces
  2085. while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
  2086. # Hand this line to the appropriate state handler
  2087. if ($state == STATE_NORMAL) {
  2088. process_normal();
  2089. } elsif ($state == STATE_NAME) {
  2090. process_name($file, $_);
  2091. } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
  2092. $state == STATE_BODY_WITH_BLANK_LINE) {
  2093. process_body($file, $_);
  2094. } elsif ($state == STATE_INLINE) { # scanning for inline parameters
  2095. process_inline($file, $_);
  2096. } elsif ($state == STATE_PROTO) {
  2097. process_proto($file, $_);
  2098. } elsif ($state == STATE_DOCBLOCK) {
  2099. process_docblock($file, $_);
  2100. }
  2101. }
  2102. # Make sure we got something interesting.
  2103. if ($initial_section_counter == $section_counter && $
  2104. output_mode ne "none") {
  2105. if ($output_selection == OUTPUT_INCLUDE) {
  2106. print STDERR "${file}:1: warning: '$_' not found\n"
  2107. for keys %function_table;
  2108. }
  2109. else {
  2110. print STDERR "${file}:1: warning: no structured comments found\n";
  2111. }
  2112. }
  2113. close IN_FILE;
  2114. }
  2115. if ($output_mode eq "rst") {
  2116. get_sphinx_version() if (!$sphinx_major);
  2117. }
  2118. $kernelversion = get_kernel_version();
  2119. # generate a sequence of code that will splice in highlighting information
  2120. # using the s// operator.
  2121. for (my $k = 0; $k < @highlights; $k++) {
  2122. my $pattern = $highlights[$k][0];
  2123. my $result = $highlights[$k][1];
  2124. # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
  2125. $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
  2126. }
  2127. # Read the file that maps relative names to absolute names for
  2128. # separate source and object directories and for shadow trees.
  2129. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  2130. my ($relname, $absname);
  2131. while(<SOURCE_MAP>) {
  2132. chop();
  2133. ($relname, $absname) = (split())[0..1];
  2134. $relname =~ s:^/+::;
  2135. $source_map{$relname} = $absname;
  2136. }
  2137. close(SOURCE_MAP);
  2138. }
  2139. if ($output_selection == OUTPUT_EXPORTED ||
  2140. $output_selection == OUTPUT_INTERNAL) {
  2141. push(@export_file_list, @ARGV);
  2142. foreach (@export_file_list) {
  2143. chomp;
  2144. process_export_file($_);
  2145. }
  2146. }
  2147. foreach (@ARGV) {
  2148. chomp;
  2149. process_file($_);
  2150. }
  2151. if ($verbose && $errors) {
  2152. print STDERR "$errors errors\n";
  2153. }
  2154. if ($verbose && $warnings) {
  2155. print STDERR "$warnings warnings\n";
  2156. }
  2157. if ($Werror && $warnings) {
  2158. print STDERR "$warnings warnings as Errors\n";
  2159. exit($warnings);
  2160. } else {
  2161. exit($output_mode eq "none" ? 0 : $errors)
  2162. }