kernel-doc 61 KB

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