kernel-doc 72 KB

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