kernel-doc 61 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223
  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+)|(->\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*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\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/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
  948. $members =~ s/\s*__aligned\s*\([^;]*\)//gos;
  949. $members =~ s/\s*__packed\s*//gos;
  950. $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
  951. # replace DECLARE_BITMAP
  952. $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
  953. # replace DECLARE_HASHTABLE
  954. $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
  955. # replace DECLARE_KFIFO
  956. $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
  957. # replace DECLARE_KFIFO_PTR
  958. $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
  959. my $declaration = $members;
  960. # Split nested struct/union elements as newer ones
  961. while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
  962. my $newmember;
  963. my $maintype = $1;
  964. my $ids = $4;
  965. my $content = $3;
  966. foreach my $id(split /,/, $ids) {
  967. $newmember .= "$maintype $id; ";
  968. $id =~ s/[:\[].*//;
  969. $id =~ s/^\s*\**(\S+)\s*/$1/;
  970. foreach my $arg (split /;/, $content) {
  971. next if ($arg =~ m/^\s*$/);
  972. if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
  973. # pointer-to-function
  974. my $type = $1;
  975. my $name = $2;
  976. my $extra = $3;
  977. next if (!$name);
  978. if ($id =~ m/^\s*$/) {
  979. # anonymous struct/union
  980. $newmember .= "$type$name$extra; ";
  981. } else {
  982. $newmember .= "$type$id.$name$extra; ";
  983. }
  984. } else {
  985. my $type;
  986. my $names;
  987. $arg =~ s/^\s+//;
  988. $arg =~ s/\s+$//;
  989. # Handle bitmaps
  990. $arg =~ s/:\s*\d+\s*//g;
  991. # Handle arrays
  992. $arg =~ s/\[.*\]//g;
  993. # The type may have multiple words,
  994. # and multiple IDs can be defined, like:
  995. # const struct foo, *bar, foobar
  996. # So, we remove spaces when parsing the
  997. # names, in order to match just names
  998. # and commas for the names
  999. $arg =~ s/\s*,\s*/,/g;
  1000. if ($arg =~ m/(.*)\s+([\S+,]+)/) {
  1001. $type = $1;
  1002. $names = $2;
  1003. } else {
  1004. $newmember .= "$arg; ";
  1005. next;
  1006. }
  1007. foreach my $name (split /,/, $names) {
  1008. $name =~ s/^\s*\**(\S+)\s*/$1/;
  1009. next if (($name =~ m/^\s*$/));
  1010. if ($id =~ m/^\s*$/) {
  1011. # anonymous struct/union
  1012. $newmember .= "$type $name; ";
  1013. } else {
  1014. $newmember .= "$type $id.$name; ";
  1015. }
  1016. }
  1017. }
  1018. }
  1019. }
  1020. $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/;
  1021. }
  1022. # Ignore other nested elements, like enums
  1023. $members =~ s/(\{[^\{\}]*\})//g;
  1024. create_parameterlist($members, ';', $file, $declaration_name);
  1025. check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
  1026. # Adjust declaration for better display
  1027. $declaration =~ s/([\{;])/$1\n/g;
  1028. $declaration =~ s/\}\s+;/};/g;
  1029. # Better handle inlined enums
  1030. do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
  1031. my @def_args = split /\n/, $declaration;
  1032. my $level = 1;
  1033. $declaration = "";
  1034. foreach my $clause (@def_args) {
  1035. $clause =~ s/^\s+//;
  1036. $clause =~ s/\s+$//;
  1037. $clause =~ s/\s+/ /;
  1038. next if (!$clause);
  1039. $level-- if ($clause =~ m/(\})/ && $level > 1);
  1040. if (!($clause =~ m/^\s*#/)) {
  1041. $declaration .= "\t" x $level;
  1042. }
  1043. $declaration .= "\t" . $clause . "\n";
  1044. $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
  1045. }
  1046. output_declaration($declaration_name,
  1047. 'struct',
  1048. {'struct' => $declaration_name,
  1049. 'module' => $modulename,
  1050. 'definition' => $declaration,
  1051. 'parameterlist' => \@parameterlist,
  1052. 'parameterdescs' => \%parameterdescs,
  1053. 'parametertypes' => \%parametertypes,
  1054. 'sectionlist' => \@sectionlist,
  1055. 'sections' => \%sections,
  1056. 'purpose' => $declaration_purpose,
  1057. 'type' => $decl_type
  1058. });
  1059. }
  1060. else {
  1061. print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
  1062. ++$errors;
  1063. }
  1064. }
  1065. sub show_warnings($$) {
  1066. my $functype = shift;
  1067. my $name = shift;
  1068. return 1 if ($output_selection == OUTPUT_ALL);
  1069. if ($output_selection == OUTPUT_EXPORTED) {
  1070. if (defined($function_table{$name})) {
  1071. return 1;
  1072. } else {
  1073. return 0;
  1074. }
  1075. }
  1076. if ($output_selection == OUTPUT_INTERNAL) {
  1077. if (!($functype eq "function" && defined($function_table{$name}))) {
  1078. return 1;
  1079. } else {
  1080. return 0;
  1081. }
  1082. }
  1083. if ($output_selection == OUTPUT_INCLUDE) {
  1084. if (defined($function_table{$name})) {
  1085. return 1;
  1086. } else {
  1087. return 0;
  1088. }
  1089. }
  1090. if ($output_selection == OUTPUT_EXCLUDE) {
  1091. if (!defined($function_table{$name})) {
  1092. return 1;
  1093. } else {
  1094. return 0;
  1095. }
  1096. }
  1097. die("Please add the new output type at show_warnings()");
  1098. }
  1099. sub dump_enum($$) {
  1100. my $x = shift;
  1101. my $file = shift;
  1102. $x =~ s@/\*.*?\*/@@gos; # strip comments.
  1103. # strip #define macros inside enums
  1104. $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
  1105. if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) {
  1106. $declaration_name = $1;
  1107. my $members = $2;
  1108. my %_members;
  1109. $members =~ s/\s+$//;
  1110. foreach my $arg (split ',', $members) {
  1111. $arg =~ s/^\s*(\w+).*/$1/;
  1112. push @parameterlist, $arg;
  1113. if (!$parameterdescs{$arg}) {
  1114. $parameterdescs{$arg} = $undescribed;
  1115. if (show_warnings("enum", $declaration_name)) {
  1116. print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
  1117. }
  1118. }
  1119. $_members{$arg} = 1;
  1120. }
  1121. while (my ($k, $v) = each %parameterdescs) {
  1122. if (!exists($_members{$k})) {
  1123. if (show_warnings("enum", $declaration_name)) {
  1124. print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
  1125. }
  1126. }
  1127. }
  1128. output_declaration($declaration_name,
  1129. 'enum',
  1130. {'enum' => $declaration_name,
  1131. 'module' => $modulename,
  1132. 'parameterlist' => \@parameterlist,
  1133. 'parameterdescs' => \%parameterdescs,
  1134. 'sectionlist' => \@sectionlist,
  1135. 'sections' => \%sections,
  1136. 'purpose' => $declaration_purpose
  1137. });
  1138. }
  1139. else {
  1140. print STDERR "${file}:$.: error: Cannot parse enum!\n";
  1141. ++$errors;
  1142. }
  1143. }
  1144. sub dump_typedef($$) {
  1145. my $x = shift;
  1146. my $file = shift;
  1147. $x =~ s@/\*.*?\*/@@gos; # strip comments.
  1148. # Parse function prototypes
  1149. if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
  1150. $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
  1151. # Function typedefs
  1152. $return_type = $1;
  1153. $declaration_name = $2;
  1154. my $args = $3;
  1155. create_parameterlist($args, ',', $file, $declaration_name);
  1156. output_declaration($declaration_name,
  1157. 'function',
  1158. {'function' => $declaration_name,
  1159. 'typedef' => 1,
  1160. 'module' => $modulename,
  1161. 'functiontype' => $return_type,
  1162. 'parameterlist' => \@parameterlist,
  1163. 'parameterdescs' => \%parameterdescs,
  1164. 'parametertypes' => \%parametertypes,
  1165. 'sectionlist' => \@sectionlist,
  1166. 'sections' => \%sections,
  1167. 'purpose' => $declaration_purpose
  1168. });
  1169. return;
  1170. }
  1171. while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
  1172. $x =~ s/\(*.\)\s*;$/;/;
  1173. $x =~ s/\[*.\]\s*;$/;/;
  1174. }
  1175. if ($x =~ /typedef.*\s+(\w+)\s*;/) {
  1176. $declaration_name = $1;
  1177. output_declaration($declaration_name,
  1178. 'typedef',
  1179. {'typedef' => $declaration_name,
  1180. 'module' => $modulename,
  1181. 'sectionlist' => \@sectionlist,
  1182. 'sections' => \%sections,
  1183. 'purpose' => $declaration_purpose
  1184. });
  1185. }
  1186. else {
  1187. print STDERR "${file}:$.: error: Cannot parse typedef!\n";
  1188. ++$errors;
  1189. }
  1190. }
  1191. sub save_struct_actual($) {
  1192. my $actual = shift;
  1193. # strip all spaces from the actual param so that it looks like one string item
  1194. $actual =~ s/\s*//g;
  1195. $struct_actual = $struct_actual . $actual . " ";
  1196. }
  1197. sub create_parameterlist($$$$) {
  1198. my $args = shift;
  1199. my $splitter = shift;
  1200. my $file = shift;
  1201. my $declaration_name = shift;
  1202. my $type;
  1203. my $param;
  1204. # temporarily replace commas inside function pointer definition
  1205. while ($args =~ /(\([^\),]+),/) {
  1206. $args =~ s/(\([^\),]+),/$1#/g;
  1207. }
  1208. foreach my $arg (split($splitter, $args)) {
  1209. # strip comments
  1210. $arg =~ s/\/\*.*\*\///;
  1211. # strip leading/trailing spaces
  1212. $arg =~ s/^\s*//;
  1213. $arg =~ s/\s*$//;
  1214. $arg =~ s/\s+/ /;
  1215. if ($arg =~ /^#/) {
  1216. # Treat preprocessor directive as a typeless variable just to fill
  1217. # corresponding data structures "correctly". Catch it later in
  1218. # output_* subs.
  1219. push_parameter($arg, "", $file);
  1220. } elsif ($arg =~ m/\(.+\)\s*\(/) {
  1221. # pointer-to-function
  1222. $arg =~ tr/#/,/;
  1223. $arg =~ m/[^\(]+\([\w\s]*\*?\s*([\w\.]*)\s*\)/;
  1224. $param = $1;
  1225. $type = $arg;
  1226. $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
  1227. save_struct_actual($param);
  1228. push_parameter($param, $type, $file, $declaration_name);
  1229. } elsif ($arg) {
  1230. $arg =~ s/\s*:\s*/:/g;
  1231. $arg =~ s/\s*\[/\[/g;
  1232. my @args = split('\s*,\s*', $arg);
  1233. if ($args[0] =~ m/\*/) {
  1234. $args[0] =~ s/(\*+)\s*/ $1/;
  1235. }
  1236. my @first_arg;
  1237. if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
  1238. shift @args;
  1239. push(@first_arg, split('\s+', $1));
  1240. push(@first_arg, $2);
  1241. } else {
  1242. @first_arg = split('\s+', shift @args);
  1243. }
  1244. unshift(@args, pop @first_arg);
  1245. $type = join " ", @first_arg;
  1246. foreach $param (@args) {
  1247. if ($param =~ m/^(\*+)\s*(.*)/) {
  1248. save_struct_actual($2);
  1249. push_parameter($2, "$type $1", $file, $declaration_name);
  1250. }
  1251. elsif ($param =~ m/(.*?):(\d+)/) {
  1252. if ($type ne "") { # skip unnamed bit-fields
  1253. save_struct_actual($1);
  1254. push_parameter($1, "$type:$2", $file, $declaration_name)
  1255. }
  1256. }
  1257. else {
  1258. save_struct_actual($param);
  1259. push_parameter($param, $type, $file, $declaration_name);
  1260. }
  1261. }
  1262. }
  1263. }
  1264. }
  1265. sub push_parameter($$$$) {
  1266. my $param = shift;
  1267. my $type = shift;
  1268. my $file = shift;
  1269. my $declaration_name = shift;
  1270. if (($anon_struct_union == 1) && ($type eq "") &&
  1271. ($param eq "}")) {
  1272. return; # ignore the ending }; from anon. struct/union
  1273. }
  1274. $anon_struct_union = 0;
  1275. $param =~ s/[\[\)].*//;
  1276. if ($type eq "" && $param =~ /\.\.\.$/)
  1277. {
  1278. if (!$param =~ /\w\.\.\.$/) {
  1279. # handles unnamed variable parameters
  1280. $param = "...";
  1281. }
  1282. if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
  1283. $parameterdescs{$param} = "variable arguments";
  1284. }
  1285. }
  1286. elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1287. {
  1288. $param="void";
  1289. $parameterdescs{void} = "no arguments";
  1290. }
  1291. elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
  1292. # handle unnamed (anonymous) union or struct:
  1293. {
  1294. $type = $param;
  1295. $param = "{unnamed_" . $param . "}";
  1296. $parameterdescs{$param} = "anonymous\n";
  1297. $anon_struct_union = 1;
  1298. }
  1299. # warn if parameter has no description
  1300. # (but ignore ones starting with # as these are not parameters
  1301. # but inline preprocessor statements);
  1302. # Note: It will also ignore void params and unnamed structs/unions
  1303. if (!defined $parameterdescs{$param} && $param !~ /^#/) {
  1304. $parameterdescs{$param} = $undescribed;
  1305. if (show_warnings($type, $declaration_name) && $param !~ /\./) {
  1306. print STDERR
  1307. "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
  1308. ++$warnings;
  1309. }
  1310. }
  1311. # strip spaces from $param so that it is one continuous string
  1312. # on @parameterlist;
  1313. # this fixes a problem where check_sections() cannot find
  1314. # a parameter like "addr[6 + 2]" because it actually appears
  1315. # as "addr[6", "+", "2]" on the parameter list;
  1316. # but it's better to maintain the param string unchanged for output,
  1317. # so just weaken the string compare in check_sections() to ignore
  1318. # "[blah" in a parameter string;
  1319. ###$param =~ s/\s*//g;
  1320. push @parameterlist, $param;
  1321. $type =~ s/\s\s+/ /g;
  1322. $parametertypes{$param} = $type;
  1323. }
  1324. sub check_sections($$$$$) {
  1325. my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
  1326. my @sects = split ' ', $sectcheck;
  1327. my @prms = split ' ', $prmscheck;
  1328. my $err;
  1329. my ($px, $sx);
  1330. my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
  1331. foreach $sx (0 .. $#sects) {
  1332. $err = 1;
  1333. foreach $px (0 .. $#prms) {
  1334. $prm_clean = $prms[$px];
  1335. $prm_clean =~ s/\[.*\]//;
  1336. $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
  1337. # ignore array size in a parameter string;
  1338. # however, the original param string may contain
  1339. # spaces, e.g.: addr[6 + 2]
  1340. # and this appears in @prms as "addr[6" since the
  1341. # parameter list is split at spaces;
  1342. # hence just ignore "[..." for the sections check;
  1343. $prm_clean =~ s/\[.*//;
  1344. ##$prm_clean =~ s/^\**//;
  1345. if ($prm_clean eq $sects[$sx]) {
  1346. $err = 0;
  1347. last;
  1348. }
  1349. }
  1350. if ($err) {
  1351. if ($decl_type eq "function") {
  1352. print STDERR "${file}:$.: warning: " .
  1353. "Excess function parameter " .
  1354. "'$sects[$sx]' " .
  1355. "description in '$decl_name'\n";
  1356. ++$warnings;
  1357. }
  1358. }
  1359. }
  1360. }
  1361. ##
  1362. # Checks the section describing the return value of a function.
  1363. sub check_return_section {
  1364. my $file = shift;
  1365. my $declaration_name = shift;
  1366. my $return_type = shift;
  1367. # Ignore an empty return type (It's a macro)
  1368. # Ignore functions with a "void" return type. (But don't ignore "void *")
  1369. if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
  1370. return;
  1371. }
  1372. if (!defined($sections{$section_return}) ||
  1373. $sections{$section_return} eq "") {
  1374. print STDERR "${file}:$.: warning: " .
  1375. "No description found for return value of " .
  1376. "'$declaration_name'\n";
  1377. ++$warnings;
  1378. }
  1379. }
  1380. ##
  1381. # takes a function prototype and the name of the current file being
  1382. # processed and spits out all the details stored in the global
  1383. # arrays/hashes.
  1384. sub dump_function($$) {
  1385. my $prototype = shift;
  1386. my $file = shift;
  1387. my $noret = 0;
  1388. $prototype =~ s/^static +//;
  1389. $prototype =~ s/^extern +//;
  1390. $prototype =~ s/^asmlinkage +//;
  1391. $prototype =~ s/^inline +//;
  1392. $prototype =~ s/^__inline__ +//;
  1393. $prototype =~ s/^__inline +//;
  1394. $prototype =~ s/^__always_inline +//;
  1395. $prototype =~ s/^noinline +//;
  1396. $prototype =~ s/__init +//;
  1397. $prototype =~ s/__init_or_module +//;
  1398. $prototype =~ s/__meminit +//;
  1399. $prototype =~ s/__must_check +//;
  1400. $prototype =~ s/__weak +//;
  1401. $prototype =~ s/__sched +//;
  1402. my $define = $prototype =~ s/^#\s*define\s+//; #ak added
  1403. $prototype =~ s/__attribute__\s*\(\(
  1404. (?:
  1405. [\w\s]++ # attribute name
  1406. (?:\([^)]*+\))? # attribute arguments
  1407. \s*+,? # optional comma at the end
  1408. )+
  1409. \)\)\s+//x;
  1410. # Yes, this truly is vile. We are looking for:
  1411. # 1. Return type (may be nothing if we're looking at a macro)
  1412. # 2. Function name
  1413. # 3. Function parameters.
  1414. #
  1415. # All the while we have to watch out for function pointer parameters
  1416. # (which IIRC is what the two sections are for), C types (these
  1417. # regexps don't even start to express all the possibilities), and
  1418. # so on.
  1419. #
  1420. # If you mess with these regexps, it's a good idea to check that
  1421. # the following functions' documentation still comes out right:
  1422. # - parport_register_device (function pointer parameters)
  1423. # - atomic_set (macro)
  1424. # - pci_match_device, __copy_to_user (long return type)
  1425. if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
  1426. # This is an object-like macro, it has no return type and no parameter
  1427. # list.
  1428. # Function-like macros are not allowed to have spaces between
  1429. # declaration_name and opening parenthesis (notice the \s+).
  1430. $return_type = $1;
  1431. $declaration_name = $2;
  1432. $noret = 1;
  1433. } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1434. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1435. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1436. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1437. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1438. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1439. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1440. $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1441. $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1442. $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1443. $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1444. $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1445. $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1446. $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1447. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1448. $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1449. $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
  1450. $return_type = $1;
  1451. $declaration_name = $2;
  1452. my $args = $3;
  1453. create_parameterlist($args, ',', $file, $declaration_name);
  1454. } else {
  1455. print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
  1456. return;
  1457. }
  1458. my $prms = join " ", @parameterlist;
  1459. check_sections($file, $declaration_name, "function", $sectcheck, $prms);
  1460. # This check emits a lot of warnings at the moment, because many
  1461. # functions don't have a 'Return' doc section. So until the number
  1462. # of warnings goes sufficiently down, the check is only performed in
  1463. # verbose mode.
  1464. # TODO: always perform the check.
  1465. if ($verbose && !$noret) {
  1466. check_return_section($file, $declaration_name, $return_type);
  1467. }
  1468. output_declaration($declaration_name,
  1469. 'function',
  1470. {'function' => $declaration_name,
  1471. 'module' => $modulename,
  1472. 'functiontype' => $return_type,
  1473. 'parameterlist' => \@parameterlist,
  1474. 'parameterdescs' => \%parameterdescs,
  1475. 'parametertypes' => \%parametertypes,
  1476. 'sectionlist' => \@sectionlist,
  1477. 'sections' => \%sections,
  1478. 'purpose' => $declaration_purpose
  1479. });
  1480. }
  1481. sub reset_state {
  1482. $function = "";
  1483. %parameterdescs = ();
  1484. %parametertypes = ();
  1485. @parameterlist = ();
  1486. %sections = ();
  1487. @sectionlist = ();
  1488. $sectcheck = "";
  1489. $struct_actual = "";
  1490. $prototype = "";
  1491. $state = STATE_NORMAL;
  1492. $inline_doc_state = STATE_INLINE_NA;
  1493. }
  1494. sub tracepoint_munge($) {
  1495. my $file = shift;
  1496. my $tracepointname = 0;
  1497. my $tracepointargs = 0;
  1498. if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
  1499. $tracepointname = $1;
  1500. }
  1501. if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
  1502. $tracepointname = $1;
  1503. }
  1504. if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
  1505. $tracepointname = $2;
  1506. }
  1507. $tracepointname =~ s/^\s+//; #strip leading whitespace
  1508. if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
  1509. $tracepointargs = $1;
  1510. }
  1511. if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
  1512. print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
  1513. "$prototype\n";
  1514. } else {
  1515. $prototype = "static inline void trace_$tracepointname($tracepointargs)";
  1516. }
  1517. }
  1518. sub syscall_munge() {
  1519. my $void = 0;
  1520. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
  1521. ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
  1522. if ($prototype =~ m/SYSCALL_DEFINE0/) {
  1523. $void = 1;
  1524. ## $prototype = "long sys_$1(void)";
  1525. }
  1526. $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
  1527. if ($prototype =~ m/long (sys_.*?),/) {
  1528. $prototype =~ s/,/\(/;
  1529. } elsif ($void) {
  1530. $prototype =~ s/\)/\(void\)/;
  1531. }
  1532. # now delete all of the odd-number commas in $prototype
  1533. # so that arg types & arg names don't have a comma between them
  1534. my $count = 0;
  1535. my $len = length($prototype);
  1536. if ($void) {
  1537. $len = 0; # skip the for-loop
  1538. }
  1539. for (my $ix = 0; $ix < $len; $ix++) {
  1540. if (substr($prototype, $ix, 1) eq ',') {
  1541. $count++;
  1542. if ($count % 2 == 1) {
  1543. substr($prototype, $ix, 1) = ' ';
  1544. }
  1545. }
  1546. }
  1547. }
  1548. sub process_proto_function($$) {
  1549. my $x = shift;
  1550. my $file = shift;
  1551. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1552. if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
  1553. # do nothing
  1554. }
  1555. elsif ($x =~ /([^\{]*)/) {
  1556. $prototype .= $1;
  1557. }
  1558. if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
  1559. $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
  1560. $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1561. $prototype =~ s@^\s+@@gos; # strip leading spaces
  1562. if ($prototype =~ /SYSCALL_DEFINE/) {
  1563. syscall_munge();
  1564. }
  1565. if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
  1566. $prototype =~ /DEFINE_SINGLE_EVENT/)
  1567. {
  1568. tracepoint_munge($file);
  1569. }
  1570. dump_function($prototype, $file);
  1571. reset_state();
  1572. }
  1573. }
  1574. sub process_proto_type($$) {
  1575. my $x = shift;
  1576. my $file = shift;
  1577. $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1578. $x =~ s@^\s+@@gos; # strip leading spaces
  1579. $x =~ s@\s+$@@gos; # strip trailing spaces
  1580. $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1581. if ($x =~ /^#/) {
  1582. # To distinguish preprocessor directive from regular declaration later.
  1583. $x .= ";";
  1584. }
  1585. while (1) {
  1586. if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
  1587. if( length $prototype ) {
  1588. $prototype .= " "
  1589. }
  1590. $prototype .= $1 . $2;
  1591. ($2 eq '{') && $brcount++;
  1592. ($2 eq '}') && $brcount--;
  1593. if (($2 eq ';') && ($brcount == 0)) {
  1594. dump_declaration($prototype, $file);
  1595. reset_state();
  1596. last;
  1597. }
  1598. $x = $3;
  1599. } else {
  1600. $prototype .= $x;
  1601. last;
  1602. }
  1603. }
  1604. }
  1605. sub map_filename($) {
  1606. my $file;
  1607. my ($orig_file) = @_;
  1608. if (defined($ENV{'SRCTREE'})) {
  1609. $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
  1610. } else {
  1611. $file = $orig_file;
  1612. }
  1613. if (defined($source_map{$file})) {
  1614. $file = $source_map{$file};
  1615. }
  1616. return $file;
  1617. }
  1618. sub process_export_file($) {
  1619. my ($orig_file) = @_;
  1620. my $file = map_filename($orig_file);
  1621. if (!open(IN,"<$file")) {
  1622. print STDERR "Error: Cannot open file $file\n";
  1623. ++$errors;
  1624. return;
  1625. }
  1626. while (<IN>) {
  1627. if (/$export_symbol/) {
  1628. $function_table{$2} = 1;
  1629. }
  1630. }
  1631. close(IN);
  1632. }
  1633. #
  1634. # Parsers for the various processing states.
  1635. #
  1636. # STATE_NORMAL: looking for the /** to begin everything.
  1637. #
  1638. sub process_normal() {
  1639. if (/$doc_start/o) {
  1640. $state = STATE_NAME; # next line is always the function name
  1641. $in_doc_sect = 0;
  1642. $declaration_start_line = $. + 1;
  1643. }
  1644. }
  1645. #
  1646. # STATE_NAME: Looking for the "name - description" line
  1647. #
  1648. sub process_name($$) {
  1649. my $file = shift;
  1650. my $identifier;
  1651. my $descr;
  1652. if (/$doc_block/o) {
  1653. $state = STATE_DOCBLOCK;
  1654. $contents = "";
  1655. $new_start_line = $. + 1;
  1656. if ( $1 eq "" ) {
  1657. $section = $section_intro;
  1658. } else {
  1659. $section = $1;
  1660. }
  1661. }
  1662. elsif (/$doc_decl/o) {
  1663. $identifier = $1;
  1664. if (/\s*([\w\s]+?)(\(\))?\s*-/) {
  1665. $identifier = $1;
  1666. }
  1667. $state = STATE_BODY;
  1668. # if there's no @param blocks need to set up default section
  1669. # here
  1670. $contents = "";
  1671. $section = $section_default;
  1672. $new_start_line = $. + 1;
  1673. if (/-(.*)/) {
  1674. # strip leading/trailing/multiple spaces
  1675. $descr= $1;
  1676. $descr =~ s/^\s*//;
  1677. $descr =~ s/\s*$//;
  1678. $descr =~ s/\s+/ /g;
  1679. $declaration_purpose = $descr;
  1680. $state = STATE_BODY_MAYBE;
  1681. } else {
  1682. $declaration_purpose = "";
  1683. }
  1684. if (($declaration_purpose eq "") && $verbose) {
  1685. print STDERR "${file}:$.: warning: missing initial short description on line:\n";
  1686. print STDERR $_;
  1687. ++$warnings;
  1688. }
  1689. if ($identifier =~ m/^struct\b/) {
  1690. $decl_type = 'struct';
  1691. } elsif ($identifier =~ m/^union\b/) {
  1692. $decl_type = 'union';
  1693. } elsif ($identifier =~ m/^enum\b/) {
  1694. $decl_type = 'enum';
  1695. } elsif ($identifier =~ m/^typedef\b/) {
  1696. $decl_type = 'typedef';
  1697. } else {
  1698. $decl_type = 'function';
  1699. }
  1700. if ($verbose) {
  1701. print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
  1702. }
  1703. } else {
  1704. print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
  1705. " - I thought it was a doc line\n";
  1706. ++$warnings;
  1707. $state = STATE_NORMAL;
  1708. }
  1709. }
  1710. #
  1711. # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
  1712. #
  1713. sub process_body($$) {
  1714. my $file = shift;
  1715. if (/$doc_sect/i) { # case insensitive for supported section names
  1716. $newsection = $1;
  1717. $newcontents = $2;
  1718. # map the supported section names to the canonical names
  1719. if ($newsection =~ m/^description$/i) {
  1720. $newsection = $section_default;
  1721. } elsif ($newsection =~ m/^context$/i) {
  1722. $newsection = $section_context;
  1723. } elsif ($newsection =~ m/^returns?$/i) {
  1724. $newsection = $section_return;
  1725. } elsif ($newsection =~ m/^\@return$/) {
  1726. # special: @return is a section, not a param description
  1727. $newsection = $section_return;
  1728. }
  1729. if (($contents ne "") && ($contents ne "\n")) {
  1730. if (!$in_doc_sect && $verbose) {
  1731. print STDERR "${file}:$.: warning: contents before sections\n";
  1732. ++$warnings;
  1733. }
  1734. dump_section($file, $section, $contents);
  1735. $section = $section_default;
  1736. }
  1737. $in_doc_sect = 1;
  1738. $state = STATE_BODY;
  1739. $contents = $newcontents;
  1740. $new_start_line = $.;
  1741. while (substr($contents, 0, 1) eq " ") {
  1742. $contents = substr($contents, 1);
  1743. }
  1744. if ($contents ne "") {
  1745. $contents .= "\n";
  1746. }
  1747. $section = $newsection;
  1748. $leading_space = undef;
  1749. } elsif (/$doc_end/) {
  1750. if (($contents ne "") && ($contents ne "\n")) {
  1751. dump_section($file, $section, $contents);
  1752. $section = $section_default;
  1753. $contents = "";
  1754. }
  1755. # look for doc_com + <text> + doc_end:
  1756. if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
  1757. print STDERR "${file}:$.: warning: suspicious ending line: $_";
  1758. ++$warnings;
  1759. }
  1760. $prototype = "";
  1761. $state = STATE_PROTO;
  1762. $brcount = 0;
  1763. } elsif (/$doc_content/) {
  1764. # miguel-style comment kludge, look for blank lines after
  1765. # @parameter line to signify start of description
  1766. if ($1 eq "") {
  1767. if ($section =~ m/^@/ || $section eq $section_context) {
  1768. dump_section($file, $section, $contents);
  1769. $section = $section_default;
  1770. $contents = "";
  1771. $new_start_line = $.;
  1772. } else {
  1773. $contents .= "\n";
  1774. }
  1775. $state = STATE_BODY;
  1776. } elsif ($state == STATE_BODY_MAYBE) {
  1777. # Continued declaration purpose
  1778. chomp($declaration_purpose);
  1779. $declaration_purpose .= " " . $1;
  1780. $declaration_purpose =~ s/\s+/ /g;
  1781. } else {
  1782. my $cont = $1;
  1783. if ($section =~ m/^@/ || $section eq $section_context) {
  1784. if (!defined $leading_space) {
  1785. if ($cont =~ m/^(\s+)/) {
  1786. $leading_space = $1;
  1787. } else {
  1788. $leading_space = "";
  1789. }
  1790. }
  1791. $cont =~ s/^$leading_space//;
  1792. }
  1793. $contents .= $cont . "\n";
  1794. }
  1795. } else {
  1796. # i dont know - bad line? ignore.
  1797. print STDERR "${file}:$.: warning: bad line: $_";
  1798. ++$warnings;
  1799. }
  1800. }
  1801. #
  1802. # STATE_PROTO: reading a function/whatever prototype.
  1803. #
  1804. sub process_proto($$) {
  1805. my $file = shift;
  1806. if (/$doc_inline_oneline/) {
  1807. $section = $1;
  1808. $contents = $2;
  1809. if ($contents ne "") {
  1810. $contents .= "\n";
  1811. dump_section($file, $section, $contents);
  1812. $section = $section_default;
  1813. $contents = "";
  1814. }
  1815. } elsif (/$doc_inline_start/) {
  1816. $state = STATE_INLINE;
  1817. $inline_doc_state = STATE_INLINE_NAME;
  1818. } elsif ($decl_type eq 'function') {
  1819. process_proto_function($_, $file);
  1820. } else {
  1821. process_proto_type($_, $file);
  1822. }
  1823. }
  1824. #
  1825. # STATE_DOCBLOCK: within a DOC: block.
  1826. #
  1827. sub process_docblock($$) {
  1828. my $file = shift;
  1829. if (/$doc_end/) {
  1830. dump_doc_section($file, $section, $contents);
  1831. $section = $section_default;
  1832. $contents = "";
  1833. $function = "";
  1834. %parameterdescs = ();
  1835. %parametertypes = ();
  1836. @parameterlist = ();
  1837. %sections = ();
  1838. @sectionlist = ();
  1839. $prototype = "";
  1840. $state = STATE_NORMAL;
  1841. } elsif (/$doc_content/) {
  1842. if ( $1 eq "" ) {
  1843. $contents .= $blankline;
  1844. } else {
  1845. $contents .= $1 . "\n";
  1846. }
  1847. }
  1848. }
  1849. #
  1850. # STATE_INLINE: docbook comments within a prototype.
  1851. #
  1852. sub process_inline($$) {
  1853. my $file = shift;
  1854. # First line (state 1) needs to be a @parameter
  1855. if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
  1856. $section = $1;
  1857. $contents = $2;
  1858. $new_start_line = $.;
  1859. if ($contents ne "") {
  1860. while (substr($contents, 0, 1) eq " ") {
  1861. $contents = substr($contents, 1);
  1862. }
  1863. $contents .= "\n";
  1864. }
  1865. $inline_doc_state = STATE_INLINE_TEXT;
  1866. # Documentation block end */
  1867. } elsif (/$doc_inline_end/) {
  1868. if (($contents ne "") && ($contents ne "\n")) {
  1869. dump_section($file, $section, $contents);
  1870. $section = $section_default;
  1871. $contents = "";
  1872. }
  1873. $state = STATE_PROTO;
  1874. $inline_doc_state = STATE_INLINE_NA;
  1875. # Regular text
  1876. } elsif (/$doc_content/) {
  1877. if ($inline_doc_state == STATE_INLINE_TEXT) {
  1878. $contents .= $1 . "\n";
  1879. # nuke leading blank lines
  1880. if ($contents =~ /^\s*$/) {
  1881. $contents = "";
  1882. }
  1883. } elsif ($inline_doc_state == STATE_INLINE_NAME) {
  1884. $inline_doc_state = STATE_INLINE_ERROR;
  1885. print STDERR "${file}:$.: warning: ";
  1886. print STDERR "Incorrect use of kernel-doc format: $_";
  1887. ++$warnings;
  1888. }
  1889. }
  1890. }
  1891. sub process_file($) {
  1892. my $file;
  1893. my $initial_section_counter = $section_counter;
  1894. my ($orig_file) = @_;
  1895. $file = map_filename($orig_file);
  1896. if (!open(IN,"<$file")) {
  1897. print STDERR "Error: Cannot open file $file\n";
  1898. ++$errors;
  1899. return;
  1900. }
  1901. $. = 1;
  1902. $section_counter = 0;
  1903. while (<IN>) {
  1904. while (s/\\\s*$//) {
  1905. $_ .= <IN>;
  1906. }
  1907. # Replace tabs by spaces
  1908. while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
  1909. # Hand this line to the appropriate state handler
  1910. if ($state == STATE_NORMAL) {
  1911. process_normal();
  1912. } elsif ($state == STATE_NAME) {
  1913. process_name($file, $_);
  1914. } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
  1915. process_body($file, $_);
  1916. } elsif ($state == STATE_INLINE) { # scanning for inline parameters
  1917. process_inline($file, $_);
  1918. } elsif ($state == STATE_PROTO) {
  1919. process_proto($file, $_);
  1920. } elsif ($state == STATE_DOCBLOCK) {
  1921. process_docblock($file, $_);
  1922. }
  1923. }
  1924. # Make sure we got something interesting.
  1925. if ($initial_section_counter == $section_counter) {
  1926. if ($output_mode ne "none") {
  1927. print STDERR "${file}:1: warning: no structured comments found\n";
  1928. }
  1929. if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
  1930. print STDERR " Was looking for '$_'.\n" for keys %function_table;
  1931. }
  1932. }
  1933. }
  1934. $kernelversion = get_kernel_version();
  1935. # generate a sequence of code that will splice in highlighting information
  1936. # using the s// operator.
  1937. for (my $k = 0; $k < @highlights; $k++) {
  1938. my $pattern = $highlights[$k][0];
  1939. my $result = $highlights[$k][1];
  1940. # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
  1941. $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
  1942. }
  1943. # Read the file that maps relative names to absolute names for
  1944. # separate source and object directories and for shadow trees.
  1945. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  1946. my ($relname, $absname);
  1947. while(<SOURCE_MAP>) {
  1948. chop();
  1949. ($relname, $absname) = (split())[0..1];
  1950. $relname =~ s:^/+::;
  1951. $source_map{$relname} = $absname;
  1952. }
  1953. close(SOURCE_MAP);
  1954. }
  1955. if ($output_selection == OUTPUT_EXPORTED ||
  1956. $output_selection == OUTPUT_INTERNAL) {
  1957. push(@export_file_list, @ARGV);
  1958. foreach (@export_file_list) {
  1959. chomp;
  1960. process_export_file($_);
  1961. }
  1962. }
  1963. foreach (@ARGV) {
  1964. chomp;
  1965. process_file($_);
  1966. }
  1967. if ($verbose && $errors) {
  1968. print STDERR "$errors errors\n";
  1969. }
  1970. if ($verbose && $warnings) {
  1971. print STDERR "$warnings warnings\n";
  1972. }
  1973. exit($output_mode eq "none" ? 0 : $errors);