]> git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blame - scripts/kernel-doc
projects / mirror_ubuntu-bionic-kernel.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
PCI: PM: Skip devices in D0 for suspend-to-idle
[mirror_ubuntu-bionic-kernel.git] / scripts / kernel-doc
CommitLineData
cb77f0d6 1#!/usr/bin/env perl
1da177e4 2
cb77f0d6 3use warnings;
1da177e4
LT		 4use strict;
5
6## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
7## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
8## Copyright (C) 2001 Simon Huggins ##
70c95b00 9## Copyright (C) 2005-2012 Randy Dunlap ##
1b40c194 10## Copyright (C) 2012 Dan Luedtke ##
1da177e4
LT		 11## ##
12## #define enhancements by Armin Kuster <akuster@mvista.com> ##
13## Copyright (c) 2000 MontaVista Software, Inc. ##
14## ##
15## This software falls under the GNU General Public License. ##
16## Please read the COPYING file for more information ##
17
1da177e4
LT		 18# 18/01/2001 - Cleanups
19# Functions prototyped as foo(void) same as foo()
20# Stop eval'ing where we don't need to.
21# -- huggie@earth.li
22
23# 27/06/2001 - Allowed whitespace after initial "/**" and
24# allowed comments before function declarations.
25# -- Christian Kreibich <ck@whoop.org>
26
27# Still to do:
28# - add perldoc documentation
29# - Look more closely at some of the scarier bits :)
30
31# 26/05/2001 - Support for separate source and object trees.
32# Return error code.
33# Keith Owens <kaos@ocs.com.au>
34
35# 23/09/2001 - Added support for typedefs, structs, enums and unions
36# Support for Context section; can be terminated using empty line
37# Small fixes (like spaces vs. \s in regex)
38# -- Tim Jansen <tim@tjansen.de>
39
1b40c194
DL		 40# 25/07/2012 - Added support for HTML5
41# -- Dan Luedtke <mail@danrl.de>
1da177e4 42
fadc0b31
JN		 43sub usage {
44 my $message = <<"EOF";
45Usage: $0 [OPTION ...] FILE ...
46
47Read C language source or header FILEs, extract embedded documentation comments,
48and print formatted documentation to standard output.
49
50The documentation comments are identified by "/**" opening comment mark. See
51Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
52
53Output format selection (mutually exclusive):
54 -docbook Output DocBook format.
55 -html Output HTML format.
56 -html5 Output HTML5 format.
57 -list Output symbol list format. This is for use by docproc.
58 -man Output troff manual page format. This is the default.
c0d1b6ee 59 -rst Output reStructuredText format.
fadc0b31 60 -text Output plain text format.
3a025e1d 61 -none Do not output documentation, only warnings.
fadc0b31
JN		 62
63Output selection (mutually exclusive):
86ae2e38
JN		 64 -export Only output documentation for symbols that have been
65 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
c9b2cfb3 66 in any input FILE or -export-file FILE.
86ae2e38
JN		 67 -internal Only output documentation for symbols that have NOT been
68 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
c9b2cfb3 69 in any input FILE or -export-file FILE.
fadc0b31
JN		 70 -function NAME Only output documentation for the given function(s)
71 or DOC: section title(s). All other functions and DOC:
72 sections are ignored. May be specified multiple times.
73 -nofunction NAME Do NOT output documentation for the given function(s);
74 only output documentation for the other functions and
75 DOC: sections. May be specified multiple times.
76
77Output selection modifiers:
78 -no-doc-sections Do not output DOC: sections.
0b0f5f29
DV		 79 -enable-lineno Enable output of #define LINENO lines. Only works with
80 reStructuredText format.
88c2b57d
JN		 81 -export-file FILE Specify an additional FILE in which to look for
82 EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
83 -export or -internal. May be specified multiple times.
fadc0b31
JN		 84
85Other parameters:
86 -v Verbose output, more warnings and other information.
87 -h Print this help.
88
89EOF
90 print $message;
91 exit 1;
92}
1da177e4
LT		 93
94#
95# format of comments.
96# In the following table, (...)? signifies optional structure.
97# (...)* signifies 0 or more structure elements
98# /**
99# * function_name(:)? (- short description)?
100# (* @parameterx: (description of parameter x)?)*
101# (* a blank line)?
102# * (Description:)? (Description of function)?
103# * (section header: (section description)? )*
104# (*)?*/
105#
106# So .. the trivial example would be:
107#
108# /**
109# * my_function
b9d97328 110# */
1da177e4 111#
891dcd2f 112# If the Description: header tag is omitted, then there must be a blank line
1da177e4
LT		 113# after the last parameter specification.
114# e.g.
115# /**
116# * my_function - does my stuff
117# * @my_arg: its mine damnit
118# *
3c3b809e 119# * Does my stuff explained.
1da177e4
LT		 120# */
121#
122# or, could also use:
123# /**
124# * my_function - does my stuff
125# * @my_arg: its mine damnit
3c3b809e 126# * Description: Does my stuff explained.
1da177e4
LT		 127# */
128# etc.
129#
b9d97328 130# Besides functions you can also write documentation for structs, unions,
3c3b809e
RD		 131# enums and typedefs. Instead of the function name you must write the name
132# of the declaration; the struct/union/enum/typedef must always precede
133# the name. Nesting of declarations is not supported.
1da177e4
LT		 134# Use the argument mechanism to document members or constants.
135# e.g.
136# /**
137# * struct my_struct - short description
138# * @a: first member
139# * @b: second member
3c3b809e 140# *
1da177e4
LT		 141# * Longer description
142# */
143# struct my_struct {
144# int a;
145# int b;
aeec46b9
MW		 146# /* private: */
147# int c;
1da177e4
LT		 148# };
149#
150# All descriptions can be multiline, except the short function description.
3c3b809e 151#
a4c6ebed
DCLP		 152# For really longs structs, you can also describe arguments inside the
153# body of the struct.
154# eg.
155# /**
156# * struct my_struct - short description
157# * @a: first member
158# * @b: second member
159# *
160# * Longer description
161# */
162# struct my_struct {
163# int a;
164# int b;
165# /**
166# * @c: This is longer description of C
167# *
168# * You can use paragraphs to describe arguments
169# * using this method.
170# */
171# int c;
172# };
173#
174# This should be use only for struct/enum members.
175#
3c3b809e
RD		 176# You can also add additional sections. When documenting kernel functions you
177# should document the "Context:" of the function, e.g. whether the functions
1da177e4 178# can be called form interrupts. Unlike other sections you can end it with an
3c3b809e 179# empty line.
4092bac7
YB		 180# A non-void function should have a "Return:" section describing the return
181# value(s).
3c3b809e 182# Example-sections should contain the string EXAMPLE so that they are marked
1da177e4
LT		 183# appropriately in DocBook.
184#
185# Example:
186# /**
187# * user_function - function that can only be called in user context
188# * @a: some argument
189# * Context: !in_interrupt()
3c3b809e 190# *
1da177e4
LT		 191# * Some description
192# * Example:
193# * user_function(22);
194# */
195# ...
196#
197#
198# All descriptive text is further processed, scanning for the following special
199# patterns, which are highlighted appropriately.
200#
201# 'funcname()' - function
202# '$ENVVAR' - environmental variable
203# '&struct_name' - name of a structure (up to two words including 'struct')
5267dd35 204# '&struct_name.member' - name of a structure member
1da177e4
LT		 205# '@parameter' - name of a parameter
206# '%CONST' - name of a constant.
b97f193a 207# '``LITERAL``' - literal string without any spaces on it.
1da177e4 208
8484baaa
RD		 209## init lots of data
210
1da177e4
LT		 211my $errors = 0;
212my $warnings = 0;
5f8c7c98 213my $anon_struct_union = 0;
1da177e4
LT		 214
215# match expressions used to find embedded type information
b97f193a
MCC		 216my $type_constant = '\b``([^\`]+)``\b';
217my $type_constant2 = '\%([-_\w]+)';
1da177e4 218my $type_func = '(\w+)\(\)';
c950a173 219my $type_param = '\@(\w+(\.\.\.)?)';
5219f18a 220my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
1da177e4 221my $type_env = '(\$\w+)';
df31175b
PB		 222my $type_enum = '\&(enum\s*([_\w]+))';
223my $type_struct = '\&(struct\s*([_\w]+))';
224my $type_typedef = '\&(typedef\s*([_\w]+))';
225my $type_union = '\&(union\s*([_\w]+))';
5267dd35 226my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
df31175b
PB		 227my $type_fallback = '\&([_\w]+)';
228my $type_enum_xml = '\&amp;(enum\s*([_\w]+))';
229my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
230my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
231my $type_union_xml = '\&amp;(union\s*([_\w]+))';
5267dd35 232my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
df31175b 233my $type_fallback_xml = '\&amp([_\w]+)';
f3341dcf 234my $type_member_func = $type_member . '\(\)';
1da177e4
LT		 235
236# Output conversion substitutions.
237# One for each output format
238
239# these work fairly well
4d732701
DCLP		 240my @highlights_html = (
241 [$type_constant, "<i>\$1</i>"],
b97f193a 242 [$type_constant2, "<i>\$1</i>"],
4d732701 243 [$type_func, "<b>\$1</b>"],
df31175b 244 [$type_enum_xml, "<i>\$1</i>"],
4d732701 245 [$type_struct_xml, "<i>\$1</i>"],
df31175b
PB		 246 [$type_typedef_xml, "<i>\$1</i>"],
247 [$type_union_xml, "<i>\$1</i>"],
4d732701 248 [$type_env, "<b><i>\$1</i></b>"],
5267dd35 249 [$type_param, "<tt><b>\$1</b></tt>"],
df31175b
PB		 250 [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"],
251 [$type_fallback_xml, "<i>\$1</i>"]
4d732701 252 );
6b5b55f6
RD		 253my $local_lt = "\\\\\\\\lt:";
254my $local_gt = "\\\\\\\\gt:";
255my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
1da177e4 256
1b40c194 257# html version 5
4d732701
DCLP		 258my @highlights_html5 = (
259 [$type_constant, "<span class=\"const\">\$1</span>"],
b97f193a 260 [$type_constant2, "<span class=\"const\">\$1</span>"],
4d732701 261 [$type_func, "<span class=\"func\">\$1</span>"],
df31175b 262 [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
4d732701 263 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
df31175b
PB		 264 [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"],
265 [$type_union_xml, "<span class=\"union\">\$1</span>"],
4d732701 266 [$type_env, "<span class=\"env\">\$1</span>"],
5267dd35 267 [$type_param, "<span class=\"param\">\$1</span>]"],
df31175b
PB		 268 [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"],
269 [$type_fallback_xml, "<span class=\"struct\">\$1</span>"]
4d732701 270 );
1b40c194
DL		 271my $blankline_html5 = $local_lt . "br /" . $local_gt;
272
1da177e4 273# XML, docbook format
4d732701
DCLP		 274my @highlights_xml = (
275 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
276 [$type_constant, "<constant>\$1</constant>"],
b97f193a 277 [$type_constant2, "<constant>\$1</constant>"],
df31175b 278 [$type_enum_xml, "<type>\$1</type>"],
4d732701 279 [$type_struct_xml, "<structname>\$1</structname>"],
df31175b
PB		 280 [$type_typedef_xml, "<type>\$1</type>"],
281 [$type_union_xml, "<structname>\$1</structname>"],
4d732701
DCLP		 282 [$type_param, "<parameter>\$1</parameter>"],
283 [$type_func, "<function>\$1</function>"],
5267dd35 284 [$type_env, "<envar>\$1</envar>"],
df31175b
PB		 285 [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
286 [$type_fallback_xml, "<structname>\$1</structname>"]
4d732701 287 );
5c98fc03 288my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
1da177e4
LT		 289
290# gnome, docbook format
4d732701
DCLP		 291my @highlights_gnome = (
292 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
b97f193a 293 [$type_constant2, "<replaceable class=\"option\">\$1</replaceable>"],
4d732701 294 [$type_func, "<function>\$1</function>"],
df31175b 295 [$type_enum, "<type>\$1</type>"],
4d732701 296 [$type_struct, "<structname>\$1</structname>"],
df31175b
PB		 297 [$type_typedef, "<type>\$1</type>"],
298 [$type_union, "<structname>\$1</structname>"],
4d732701 299 [$type_env, "<envar>\$1</envar>"],
5267dd35 300 [$type_param, "<parameter>\$1</parameter>" ],
df31175b
PB		 301 [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
302 [$type_fallback, "<structname>\$1</structname>"]
4d732701 303 );
1da177e4
LT		 304my $blankline_gnome = "</para><para>\n";
305
306# these are pretty rough
4d732701
DCLP		 307my @highlights_man = (
308 [$type_constant, "\$1"],
b97f193a 309 [$type_constant2, "\$1"],
4d732701 310 [$type_func, "\\\\fB\$1\\\\fP"],
df31175b 311 [$type_enum, "\\\\fI\$1\\\\fP"],
4d732701 312 [$type_struct, "\\\\fI\$1\\\\fP"],
df31175b
PB		 313 [$type_typedef, "\\\\fI\$1\\\\fP"],
314 [$type_union, "\\\\fI\$1\\\\fP"],
5267dd35 315 [$type_param, "\\\\fI\$1\\\\fP"],
df31175b
PB		 316 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
317 [$type_fallback, "\\\\fI\$1\\\\fP"]
4d732701 318 );
1da177e4
LT		 319my $blankline_man = "";
320
321# text-mode
4d732701
DCLP		 322my @highlights_text = (
323 [$type_constant, "\$1"],
b97f193a 324 [$type_constant2, "\$1"],
4d732701 325 [$type_func, "\$1"],
df31175b 326 [$type_enum, "\$1"],
4d732701 327 [$type_struct, "\$1"],
df31175b
PB		 328 [$type_typedef, "\$1"],
329 [$type_union, "\$1"],
5267dd35 330 [$type_param, "\$1"],
df31175b
PB		 331 [$type_member, "\$1\$2\$3"],
332 [$type_fallback, "\$1"]
4d732701 333 );
1da177e4
LT		 334my $blankline_text = "";
335
c0d1b6ee
JC		 336# rst-mode
337my @highlights_rst = (
338 [$type_constant, "``\$1``"],
b97f193a 339 [$type_constant2, "``\$1``"],
f3341dcf 340 # Note: need to escape () to avoid func matching later
5267dd35
PB		 341 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
342 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
5219f18a 343 [$type_fp_param, "**\$1\\\\(\\\\)**"],
a19bce64 344 [$type_func, "\\:c\\:func\\:`\$1()`"],
df31175b
PB		 345 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
346 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
347 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
348 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
a7291e7e 349 # in rst this can refer to any type
df31175b 350 [$type_fallback, "\\:c\\:type\\:`\$1`"],
c0d1b6ee
JC		 351 [$type_param, "**\$1**"]
352 );
353my $blankline_rst = "\n";
354
eda603f6 355# list mode
4d732701
DCLP		 356my @highlights_list = (
357 [$type_constant, "\$1"],
b97f193a 358 [$type_constant2, "\$1"],
4d732701 359 [$type_func, "\$1"],
df31175b 360 [$type_enum, "\$1"],
4d732701 361 [$type_struct, "\$1"],
df31175b
PB		 362 [$type_typedef, "\$1"],
363 [$type_union, "\$1"],
5267dd35 364 [$type_param, "\$1"],
df31175b
PB		 365 [$type_member, "\$1"],
366 [$type_fallback, "\$1"]
4d732701 367 );
eda603f6 368my $blankline_list = "";
1da177e4 369
1da177e4 370# read arguments
b9d97328 371if ($#ARGV == -1) {
1da177e4
LT		 372 usage();
373}
374
8484baaa
RD		 375my $kernelversion;
376my $dohighlight = "";
377
1da177e4
LT		 378my $verbose = 0;
379my $output_mode = "man";
e314ba31 380my $output_preformatted = 0;
4b44595a 381my $no_doc_sections = 0;
0b0f5f29 382my $enable_lineno = 0;
4d732701 383my @highlights = @highlights_man;
1da177e4
LT		 384my $blankline = $blankline_man;
385my $modulename = "Kernel API";
b6c3f456
JN		 386
387use constant {
388 OUTPUT_ALL => 0, # output all symbols and doc sections
389 OUTPUT_INCLUDE => 1, # output only specified symbols
390 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
391 OUTPUT_EXPORTED => 3, # output exported symbols
392 OUTPUT_INTERNAL => 4, # output non-exported symbols
393};
394my $output_selection = OUTPUT_ALL;
b2c4105b
BH		 395my $show_not_found = 0;
396
88c2b57d
JN		 397my @export_file_list;
398
b2c4105b
BH		 399my @build_time;
400if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
401 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
402 @build_time = gmtime($seconds);
403} else {
404 @build_time = localtime;
405}
406
3c3b809e
RD		 407my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
408 'July', 'August', 'September', 'October',
b2c4105b
BH		 409 'November', 'December')[$build_time[4]] .
410 " " . ($build_time[5]+1900);
1da177e4 411
8484baaa 412# Essentially these are globals.
b9d97328
RD		 413# They probably want to be tidied up, made more localised or something.
414# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
1da177e4 415# could cause "use of undefined value" or other bugs.
b9d97328 416my ($function, %function_table, %parametertypes, $declaration_purpose);
0b0f5f29 417my $declaration_start_line;
b9d97328 418my ($type, $declaration_name, $return_type);
1c32fd0c 419my ($newsection, $newcontents, $prototype, $brcount, %source_map);
1da177e4 420
bd0e88e5
RD		 421if (defined($ENV{'KBUILD_VERBOSE'})) {
422 $verbose = "$ENV{'KBUILD_VERBOSE'}";
423}
424
3c3b809e 425# Generated docbook code is inserted in a template at a point where
1da177e4
LT		 426# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
427# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
428# We keep track of number of generated entries and generate a dummy
429# if needs be to ensure the expanded template can be postprocessed
430# into html.
431my $section_counter = 0;
432
433my $lineprefix="";
434
48af606a
JN		 435# Parser states
436use constant {
437 STATE_NORMAL => 0, # normal code
438 STATE_NAME => 1, # looking for function name
439 STATE_FIELD => 2, # scanning field start
440 STATE_PROTO => 3, # scanning prototype
441 STATE_DOCBLOCK => 4, # documentation block
442 STATE_INLINE => 5, # gathering documentation outside main block
443};
1da177e4 444my $state;
850622df 445my $in_doc_sect;
1da177e4 446
48af606a
JN		 447# Inline documentation state
448use constant {
449 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
450 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
451 STATE_INLINE_TEXT => 2, # looking for member documentation
452 STATE_INLINE_END => 3, # done
453 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
454 # Spit a warning as it's not
455 # proper kernel-doc and ignore the rest.
456};
457my $inline_doc_state;
a4c6ebed 458
1da177e4
LT		 459#declaration types: can be
460# 'function', 'struct', 'union', 'enum', 'typedef'
461my $decl_type;
462
1da177e4
LT		 463my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
464my $doc_end = '\*/';
465my $doc_com = '\s*\*\s*';
12ae6779 466my $doc_com_body = '\s*\* ?';
b9d97328 467my $doc_decl = $doc_com . '(\w+)';
f624adef 468# @params and a strictly limited set of supported section names
8569de68 469my $doc_sect = $doc_com .
ef00028b 470 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
12ae6779 471my $doc_content = $doc_com_body . '(.*)';
b9d97328 472my $doc_block = $doc_com . 'DOC:\s*(.*)?';
48af606a
JN		 473my $doc_inline_start = '^\s*/\*\*\s*$';
474my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
475my $doc_inline_end = '^\s*\*/\s*$';
0c9aa209 476my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
86ae2e38 477my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
1da177e4 478
1da177e4 479my %parameterdescs;
0b0f5f29 480my %parameterdesc_start_lines;
1da177e4
LT		 481my @parameterlist;
482my %sections;
483my @sectionlist;
0b0f5f29 484my %section_start_lines;
a1d94aa5
RD		 485my $sectcheck;
486my $struct_actual;
1da177e4
LT		 487
488my $contents = "";
0b0f5f29 489my $new_start_line = 0;
f624adef
JN		 490
491# the canonical section names. see also $doc_sect above.
1da177e4
LT		 492my $section_default = "Description"; # default section
493my $section_intro = "Introduction";
494my $section = $section_default;
495my $section_context = "Context";
4092bac7 496my $section_return = "Return";
1da177e4
LT		 497
498my $undescribed = "-- undescribed --";
499
500reset_state();
501
502while ($ARGV[0] =~ m/^-(.*)/) {
503 my $cmd = shift @ARGV;
504 if ($cmd eq "-html") {
505 $output_mode = "html";
4d732701 506 @highlights = @highlights_html;
1da177e4 507 $blankline = $blankline_html;
1b40c194
DL		 508 } elsif ($cmd eq "-html5") {
509 $output_mode = "html5";
4d732701 510 @highlights = @highlights_html5;
1b40c194 511 $blankline = $blankline_html5;
1da177e4
LT		 512 } elsif ($cmd eq "-man") {
513 $output_mode = "man";
4d732701 514 @highlights = @highlights_man;
1da177e4
LT		 515 $blankline = $blankline_man;
516 } elsif ($cmd eq "-text") {
517 $output_mode = "text";
4d732701 518 @highlights = @highlights_text;
1da177e4 519 $blankline = $blankline_text;
c0d1b6ee
JC		 520 } elsif ($cmd eq "-rst") {
521 $output_mode = "rst";
522 @highlights = @highlights_rst;
523 $blankline = $blankline_rst;
1da177e4
LT		 524 } elsif ($cmd eq "-docbook") {
525 $output_mode = "xml";
4d732701 526 @highlights = @highlights_xml;
1da177e4 527 $blankline = $blankline_xml;
eda603f6
JB		 528 } elsif ($cmd eq "-list") {
529 $output_mode = "list";
4d732701 530 @highlights = @highlights_list;
eda603f6 531 $blankline = $blankline_list;
1da177e4
LT		 532 } elsif ($cmd eq "-gnome") {
533 $output_mode = "gnome";
4d732701 534 @highlights = @highlights_gnome;
1da177e4 535 $blankline = $blankline_gnome;
3a025e1d
MW		 536 } elsif ($cmd eq "-none") {
537 $output_mode = "none";
1da177e4
LT		 538 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
539 $modulename = shift @ARGV;
540 } elsif ($cmd eq "-function") { # to only output specific functions
b6c3f456 541 $output_selection = OUTPUT_INCLUDE;
1da177e4
LT		 542 $function = shift @ARGV;
543 $function_table{$function} = 1;
b6c3f456
JN		 544 } elsif ($cmd eq "-nofunction") { # output all except specific functions
545 $output_selection = OUTPUT_EXCLUDE;
1da177e4
LT		 546 $function = shift @ARGV;
547 $function_table{$function} = 1;
86ae2e38 548 } elsif ($cmd eq "-export") { # only exported symbols
b6c3f456 549 $output_selection = OUTPUT_EXPORTED;
da9726ec 550 %function_table = ();
86ae2e38 551 } elsif ($cmd eq "-internal") { # only non-exported symbols
b6c3f456 552 $output_selection = OUTPUT_INTERNAL;
da9726ec 553 %function_table = ();
88c2b57d
JN		 554 } elsif ($cmd eq "-export-file") {
555 my $file = shift @ARGV;
556 push(@export_file_list, $file);
1da177e4
LT		 557 } elsif ($cmd eq "-v") {
558 $verbose = 1;
559 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
560 usage();
4b44595a
JB		 561 } elsif ($cmd eq '-no-doc-sections') {
562 $no_doc_sections = 1;
0b0f5f29
DV		 563 } elsif ($cmd eq '-enable-lineno') {
564 $enable_lineno = 1;
e946c43a
JB		 565 } elsif ($cmd eq '-show-not-found') {
566 $show_not_found = 1;
1da177e4
LT		 567 }
568}
569
8484baaa
RD		 570# continue execution near EOF;
571
53f049fa
BP		 572# get kernel version from env
573sub get_kernel_version() {
1b9bc22d 574 my $version = 'unknown kernel version';
53f049fa
BP		 575
576 if (defined($ENV{'KERNELVERSION'})) {
577 $version = $ENV{'KERNELVERSION'};
578 }
579 return $version;
580}
1da177e4 581
0b0f5f29
DV		 582#
583sub print_lineno {
584 my $lineno = shift;
585 if ($enable_lineno && defined($lineno)) {
586 print "#define LINENO " . $lineno . "\n";
587 }
588}
1da177e4
LT		 589##
590# dumps section contents to arrays/hashes intended for that purpose.
591#
592sub dump_section {
94dc7ad5 593 my $file = shift;
1da177e4
LT		 594 my $name = shift;
595 my $contents = join "\n", @_;
596
13901ef2 597 if ($name =~ m/$type_param/) {
1da177e4
LT		 598 $name = $1;
599 $parameterdescs{$name} = $contents;
a1d94aa5 600 $sectcheck = $sectcheck . $name . " ";
0b0f5f29
DV		 601 $parameterdesc_start_lines{$name} = $new_start_line;
602 $new_start_line = 0;
ced69090 603 } elsif ($name eq "@\.\.\.") {
ced69090
RD		 604 $name = "...";
605 $parameterdescs{$name} = $contents;
a1d94aa5 606 $sectcheck = $sectcheck . $name . " ";
0b0f5f29
DV		 607 $parameterdesc_start_lines{$name} = $new_start_line;
608 $new_start_line = 0;
1da177e4 609 } else {
94dc7ad5 610 if (defined($sections{$name}) && ($sections{$name} ne "")) {
95b6be9d
JN		 611 # Only warn on user specified duplicate section names.
612 if ($name ne $section_default) {
613 print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
614 ++$warnings;
615 }
32217761
JN		 616 $sections{$name} .= $contents;
617 } else {
618 $sections{$name} = $contents;
619 push @sectionlist, $name;
0b0f5f29
DV		 620 $section_start_lines{$name} = $new_start_line;
621 $new_start_line = 0;
94dc7ad5 622 }
1da177e4
LT		 623 }
624}
625
b112e0f7
JB		 626##
627# dump DOC: section after checking that it should go out
628#
629sub dump_doc_section {
94dc7ad5 630 my $file = shift;
b112e0f7
JB		 631 my $name = shift;
632 my $contents = join "\n", @_;
633
4b44595a
JB		 634 if ($no_doc_sections) {
635 return;
636 }
637
b6c3f456
JN		 638 if (($output_selection == OUTPUT_ALL) ||
639 ($output_selection == OUTPUT_INCLUDE &&
640 defined($function_table{$name})) ||
641 ($output_selection == OUTPUT_EXCLUDE &&
642 !defined($function_table{$name})))
b112e0f7 643 {
94dc7ad5 644 dump_section($file, $name, $contents);
b112e0f7
JB		 645 output_blockhead({'sectionlist' => \@sectionlist,
646 'sections' => \%sections,
647 'module' => $modulename,
b6c3f456 648 'content-only' => ($output_selection != OUTPUT_ALL), });
b112e0f7
JB		 649 }
650}
651
1da177e4
LT		 652##
653# output function
654#
655# parameterdescs, a hash.
656# function => "function name"
657# parameterlist => @list of parameters
658# parameterdescs => %parameter descriptions
659# sectionlist => @list of sections
a21217da 660# sections => %section descriptions
3c3b809e 661#
1da177e4
LT		 662
663sub output_highlight {
664 my $contents = join "\n",@_;
665 my $line;
666
667# DEBUG
668# if (!defined $contents) {
669# use Carp;
670# confess "output_highlight got called with no args?\n";
671# }
672
1b40c194
DL		 673 if ($output_mode eq "html" || $output_mode eq "html5" ||
674 $output_mode eq "xml") {
6b5b55f6
RD		 675 $contents = local_unescape($contents);
676 # convert data read & converted thru xml_escape() into &xyz; format:
2b35f4d9 677 $contents =~ s/\\\\\\/\&/g;
6b5b55f6 678 }
3eb014a1 679# print STDERR "contents b4:$contents\n";
1da177e4
LT		 680 eval $dohighlight;
681 die $@ if $@;
3eb014a1
RD		 682# print STDERR "contents af:$contents\n";
683
1b40c194
DL		 684# strip whitespaces when generating html5
685 if ($output_mode eq "html5") {
686 $contents =~ s/^\s+//;
687 $contents =~ s/\s+$//;
688 }
1da177e4 689 foreach $line (split "\n", $contents) {
12ae6779
DS		 690 if (! $output_preformatted) {
691 $line =~ s/^\s*//;
692 }
3c308798 693 if ($line eq ""){
e314ba31
DS		 694 if (! $output_preformatted) {
695 print $lineprefix, local_unescape($blankline);
696 }
1da177e4 697 } else {
3c308798 698 $line =~ s/\\\\\\/\&/g;
cdccb316
RD		 699 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
700 print "\\&$line";
701 } else {
702 print $lineprefix, $line;
703 }
1da177e4
LT		 704 }
705 print "\n";
706 }
707}
708
1b40c194 709# output sections in html
1da177e4
LT		 710sub output_section_html(%) {
711 my %args = %{$_[0]};
712 my $section;
713
714 foreach $section (@{$args{'sectionlist'}}) {
715 print "<h3>$section</h3>\n";
716 print "<blockquote>\n";
717 output_highlight($args{'sections'}{$section});
718 print "</blockquote>\n";
3c3b809e 719 }
1da177e4
LT		 720}
721
722# output enum in html
723sub output_enum_html(%) {
724 my %args = %{$_[0]};
725 my ($parameter);
726 my $count;
b9d97328 727 print "<h2>enum " . $args{'enum'} . "</h2>\n";
1da177e4 728
b9d97328 729 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
1da177e4
LT		 730 $count = 0;
731 foreach $parameter (@{$args{'parameterlist'}}) {
b9d97328 732 print " <b>" . $parameter . "</b>";
1da177e4
LT		 733 if ($count != $#{$args{'parameterlist'}}) {
734 $count++;
735 print ",\n";
736 }
737 print "<br>";
738 }
739 print "};<br>\n";
740
741 print "<h3>Constants</h3>\n";
742 print "<dl>\n";
743 foreach $parameter (@{$args{'parameterlist'}}) {
b9d97328 744 print "<dt><b>" . $parameter . "</b>\n";
1da177e4
LT		 745 print "<dd>";
746 output_highlight($args{'parameterdescs'}{$parameter});
747 }
748 print "</dl>\n";
749 output_section_html(@_);
750 print "<hr>\n";
751}
752
d28bee0c 753# output typedef in html
1da177e4
LT		 754sub output_typedef_html(%) {
755 my %args = %{$_[0]};
756 my ($parameter);
757 my $count;
b9d97328 758 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
1da177e4 759
b9d97328 760 print "<b>typedef " . $args{'typedef'} . "</b>\n";
1da177e4
LT		 761 output_section_html(@_);
762 print "<hr>\n";
763}
764
765# output struct in html
766sub output_struct_html(%) {
767 my %args = %{$_[0]};
768 my ($parameter);
769
b9d97328
RD		 770 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
771 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
1da177e4
LT		 772 foreach $parameter (@{$args{'parameterlist'}}) {
773 if ($parameter =~ /^#/) {
774 print "$parameter<br>\n";
775 next;
776 }
777 my $parameter_name = $parameter;
778 $parameter_name =~ s/\[.*//;
779
3c308798 780 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1da177e4
LT		 781 $type = $args{'parametertypes'}{$parameter};
782 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
783 # pointer-to-function
3eb014a1 784 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
1da177e4 785 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
3eb014a1
RD		 786 # bitfield
787 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
1da177e4 788 } else {
3eb014a1 789 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
1da177e4
LT		 790 }
791 }
792 print "};<br>\n";
793
794 print "<h3>Members</h3>\n";
795 print "<dl>\n";
796 foreach $parameter (@{$args{'parameterlist'}}) {
797 ($parameter =~ /^#/) && next;
798
799 my $parameter_name = $parameter;
800 $parameter_name =~ s/\[.*//;
801
3c308798 802 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
b9d97328 803 print "<dt><b>" . $parameter . "</b>\n";
1da177e4
LT		 804 print "<dd>";
805 output_highlight($args{'parameterdescs'}{$parameter_name});
806 }
807 print "</dl>\n";
808 output_section_html(@_);
809 print "<hr>\n";
810}
811
812# output function in html
813sub output_function_html(%) {
814 my %args = %{$_[0]};
815 my ($parameter, $section);
816 my $count;
1da177e4 817
b9d97328
RD		 818 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
819 print "<i>" . $args{'functiontype'} . "</i>\n";
820 print "<b>" . $args{'function'} . "</b>\n";
1da177e4
LT		 821 print "(";
822 $count = 0;
823 foreach $parameter (@{$args{'parameterlist'}}) {
824 $type = $args{'parametertypes'}{$parameter};
825 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
826 # pointer-to-function
827 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
828 } else {
b9d97328 829 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
1da177e4
LT		 830 }
831 if ($count != $#{$args{'parameterlist'}}) {
832 $count++;
833 print ",\n";
834 }
835 }
836 print ")\n";
837
838 print "<h3>Arguments</h3>\n";
839 print "<dl>\n";
840 foreach $parameter (@{$args{'parameterlist'}}) {
841 my $parameter_name = $parameter;
842 $parameter_name =~ s/\[.*//;
843
3c308798 844 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
b9d97328 845 print "<dt><b>" . $parameter . "</b>\n";
1da177e4
LT		 846 print "<dd>";
847 output_highlight($args{'parameterdescs'}{$parameter_name});
848 }
849 print "</dl>\n";
850 output_section_html(@_);
851 print "<hr>\n";
852}
853
b112e0f7
JB		 854# output DOC: block header in html
855sub output_blockhead_html(%) {
1da177e4
LT		 856 my %args = %{$_[0]};
857 my ($parameter, $section);
858 my $count;
859
860 foreach $section (@{$args{'sectionlist'}}) {
861 print "<h3>$section</h3>\n";
862 print "<ul>\n";
863 output_highlight($args{'sections'}{$section});
864 print "</ul>\n";
865 }
866 print "<hr>\n";
867}
868
1b40c194
DL		 869# output sections in html5
870sub output_section_html5(%) {
871 my %args = %{$_[0]};
872 my $section;
873
874 foreach $section (@{$args{'sectionlist'}}) {
875 print "<section>\n";
876 print "<h1>$section</h1>\n";
877 print "<p>\n";
878 output_highlight($args{'sections'}{$section});
879 print "</p>\n";
880 print "</section>\n";
881 }
882}
883
884# output enum in html5
885sub output_enum_html5(%) {
886 my %args = %{$_[0]};
887 my ($parameter);
888 my $count;
889 my $html5id;
890
891 $html5id = $args{'enum'};
892 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
893 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
894 print "<h1>enum " . $args{'enum'} . "</h1>\n";
895 print "<ol class=\"code\">\n";
896 print "<li>";
897 print "<span class=\"keyword\">enum</span> ";
898 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
899 print "</li>\n";
900 $count = 0;
901 foreach $parameter (@{$args{'parameterlist'}}) {
902 print "<li class=\"indent\">";
903 print "<span class=\"param\">" . $parameter . "</span>";
904 if ($count != $#{$args{'parameterlist'}}) {
905 $count++;
906 print ",";
907 }
908 print "</li>\n";
909 }
910 print "<li>};</li>\n";
911 print "</ol>\n";
912
913 print "<section>\n";
914 print "<h1>Constants</h1>\n";
915 print "<dl>\n";
916 foreach $parameter (@{$args{'parameterlist'}}) {
917 print "<dt>" . $parameter . "</dt>\n";
918 print "<dd>";
919 output_highlight($args{'parameterdescs'}{$parameter});
920 print "</dd>\n";
921 }
922 print "</dl>\n";
923 print "</section>\n";
924 output_section_html5(@_);
925 print "</article>\n";
926}
927
928# output typedef in html5
929sub output_typedef_html5(%) {
930 my %args = %{$_[0]};
931 my ($parameter);
932 my $count;
933 my $html5id;
934
935 $html5id = $args{'typedef'};
936 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
937 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
938 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
939
940 print "<ol class=\"code\">\n";
941 print "<li>";
942 print "<span class=\"keyword\">typedef</span> ";
943 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
944 print "</li>\n";
945 print "</ol>\n";
946 output_section_html5(@_);
947 print "</article>\n";
948}
949
950# output struct in html5
951sub output_struct_html5(%) {
952 my %args = %{$_[0]};
953 my ($parameter);
954 my $html5id;
955
956 $html5id = $args{'struct'};
957 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
958 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
959 print "<hgroup>\n";
960 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
961 print "<h2>". $args{'purpose'} . "</h2>\n";
962 print "</hgroup>\n";
963 print "<ol class=\"code\">\n";
964 print "<li>";
965 print "<span class=\"type\">" . $args{'type'} . "</span> ";
966 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
967 print "</li>\n";
968 foreach $parameter (@{$args{'parameterlist'}}) {
969 print "<li class=\"indent\">";
970 if ($parameter =~ /^#/) {
971 print "<span class=\"param\">" . $parameter ."</span>\n";
972 print "</li>\n";
973 next;
974 }
975 my $parameter_name = $parameter;
976 $parameter_name =~ s/\[.*//;
977
978 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
979 $type = $args{'parametertypes'}{$parameter};
980 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
981 # pointer-to-function
982 print "<span class=\"type\">$1</span> ";
983 print "<span class=\"param\">$parameter</span>";
984 print "<span class=\"type\">)</span> ";
985 print "(<span class=\"args\">$2</span>);";
986 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
987 # bitfield
988 print "<span class=\"type\">$1</span> ";
989 print "<span class=\"param\">$parameter</span>";
990 print "<span class=\"bits\">$2</span>;";
991 } else {
992 print "<span class=\"type\">$type</span> ";
993 print "<span class=\"param\">$parameter</span>;";
994 }
995 print "</li>\n";
996 }
997 print "<li>};</li>\n";
998 print "</ol>\n";
999
1000 print "<section>\n";
1001 print "<h1>Members</h1>\n";
1002 print "<dl>\n";
1003 foreach $parameter (@{$args{'parameterlist'}}) {
1004 ($parameter =~ /^#/) && next;
1005
1006 my $parameter_name = $parameter;
1007 $parameter_name =~ s/\[.*//;
1008
1009 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1010 print "<dt>" . $parameter . "</dt>\n";
1011 print "<dd>";
1012 output_highlight($args{'parameterdescs'}{$parameter_name});
1013 print "</dd>\n";
1014 }
1015 print "</dl>\n";
1016 print "</section>\n";
1017 output_section_html5(@_);
1018 print "</article>\n";
1019}
1020
1021# output function in html5
1022sub output_function_html5(%) {
1023 my %args = %{$_[0]};
1024 my ($parameter, $section);
1025 my $count;
1026 my $html5id;
1027
1028 $html5id = $args{'function'};
1029 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1030 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
1031 print "<hgroup>\n";
1032 print "<h1>" . $args{'function'} . "</h1>";
1033 print "<h2>" . $args{'purpose'} . "</h2>\n";
1034 print "</hgroup>\n";
1035 print "<ol class=\"code\">\n";
1036 print "<li>";
1037 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
1038 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
1039 print "</li>";
1040 $count = 0;
1041 foreach $parameter (@{$args{'parameterlist'}}) {
1042 print "<li class=\"indent\">";
1043 $type = $args{'parametertypes'}{$parameter};
1044 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1045 # pointer-to-function
1046 print "<span class=\"type\">$1</span> ";
1047 print "<span class=\"param\">$parameter</span>";
1048 print "<span class=\"type\">)</span> ";
1049 print "(<span class=\"args\">$2</span>)";
1050 } else {
1051 print "<span class=\"type\">$type</span> ";
1052 print "<span class=\"param\">$parameter</span>";
1053 }
1054 if ($count != $#{$args{'parameterlist'}}) {
1055 $count++;
1056 print ",";
1057 }
1058 print "</li>\n";
1059 }
1060 print "<li>)</li>\n";
1061 print "</ol>\n";
1062
1063 print "<section>\n";
1064 print "<h1>Arguments</h1>\n";
1065 print "<p>\n";
1066 print "<dl>\n";
1067 foreach $parameter (@{$args{'parameterlist'}}) {
1068 my $parameter_name = $parameter;
1069 $parameter_name =~ s/\[.*//;
1070
1071 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1072 print "<dt>" . $parameter . "</dt>\n";
1073 print "<dd>";
1074 output_highlight($args{'parameterdescs'}{$parameter_name});
1075 print "</dd>\n";
1076 }
1077 print "</dl>\n";
1078 print "</section>\n";
1079 output_section_html5(@_);
1080 print "</article>\n";
1081}
1082
1083# output DOC: block header in html5
1084sub output_blockhead_html5(%) {
1085 my %args = %{$_[0]};
1086 my ($parameter, $section);
1087 my $count;
1088 my $html5id;
1089
1090 foreach $section (@{$args{'sectionlist'}}) {
1091 $html5id = $section;
1092 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1093 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
1094 print "<h1>$section</h1>\n";
1095 print "<p>\n";
1096 output_highlight($args{'sections'}{$section});
1097 print "</p>\n";
1098 }
1099 print "</article>\n";
1100}
1101
1da177e4
LT		 1102sub output_section_xml(%) {
1103 my %args = %{$_[0]};
3c3b809e 1104 my $section;
1da177e4
LT		 1105 # print out each section
1106 $lineprefix=" ";
1107 foreach $section (@{$args{'sectionlist'}}) {
c73894c1
RW		 1108 print "<refsect1>\n";
1109 print "<title>$section</title>\n";
1da177e4 1110 if ($section =~ m/EXAMPLE/i) {
c73894c1 1111 print "<informalexample><programlisting>\n";
e314ba31 1112 $output_preformatted = 1;
c73894c1
RW		 1113 } else {
1114 print "<para>\n";
1da177e4
LT		 1115 }
1116 output_highlight($args{'sections'}{$section});
e314ba31 1117 $output_preformatted = 0;
1da177e4 1118 if ($section =~ m/EXAMPLE/i) {
c73894c1
RW		 1119 print "</programlisting></informalexample>\n";
1120 } else {
1121 print "</para>\n";
1da177e4 1122 }
c73894c1 1123 print "</refsect1>\n";
1da177e4
LT		 1124 }
1125}
1126
1127# output function in XML DocBook
1128sub output_function_xml(%) {
1129 my %args = %{$_[0]};
1130 my ($parameter, $section);
1131 my $count;
1132 my $id;
1133
b9d97328 1134 $id = "API-" . $args{'function'};
1da177e4
LT		 1135 $id =~ s/[^A-Za-z0-9]/-/g;
1136
5449bc94 1137 print "<refentry id=\"$id\">\n";
8b0c2d98
MW		 1138 print "<refentryinfo>\n";
1139 print " <title>LINUX</title>\n";
1140 print " <productname>Kernel Hackers Manual</productname>\n";
1141 print " <date>$man_date</date>\n";
1142 print "</refentryinfo>\n";
1da177e4 1143 print "<refmeta>\n";
b9d97328 1144 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
8b0c2d98 1145 print " <manvolnum>9</manvolnum>\n";
0366299b 1146 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1da177e4
LT		 1147 print "</refmeta>\n";
1148 print "<refnamediv>\n";
b9d97328 1149 print " <refname>" . $args{'function'} . "</refname>\n";
1da177e4
LT		 1150 print " <refpurpose>\n";
1151 print " ";
1152 output_highlight ($args{'purpose'});
1153 print " </refpurpose>\n";
1154 print "</refnamediv>\n";
1155
1156 print "<refsynopsisdiv>\n";
1157 print " <title>Synopsis</title>\n";
1158 print " <funcsynopsis><funcprototype>\n";
b9d97328
RD		 1159 print " <funcdef>" . $args{'functiontype'} . " ";
1160 print "<function>" . $args{'function'} . " </function></funcdef>\n";
1da177e4
LT		 1161
1162 $count = 0;
1163 if ($#{$args{'parameterlist'}} >= 0) {
1164 foreach $parameter (@{$args{'parameterlist'}}) {
1165 $type = $args{'parametertypes'}{$parameter};
1166 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1167 # pointer-to-function
1168 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
1169 print " <funcparams>$2</funcparams></paramdef>\n";
1170 } else {
b9d97328 1171 print " <paramdef>" . $type;
1da177e4
LT		 1172 print " <parameter>$parameter</parameter></paramdef>\n";
1173 }
1174 }
1175 } else {
6013d544 1176 print " <void/>\n";
1da177e4
LT		 1177 }
1178 print " </funcprototype></funcsynopsis>\n";
1179 print "</refsynopsisdiv>\n";
1180
1181 # print parameters
1182 print "<refsect1>\n <title>Arguments</title>\n";
1183 if ($#{$args{'parameterlist'}} >= 0) {
1184 print " <variablelist>\n";
1185 foreach $parameter (@{$args{'parameterlist'}}) {
1186 my $parameter_name = $parameter;
1187 $parameter_name =~ s/\[.*//;
fc6d7af8 1188 $type = $args{'parametertypes'}{$parameter};
1da177e4 1189
fc6d7af8 1190 print " <varlistentry>\n <term><parameter>$type $parameter</parameter></term>\n";
1da177e4
LT		 1191 print " <listitem>\n <para>\n";
1192 $lineprefix=" ";
1193 output_highlight($args{'parameterdescs'}{$parameter_name});
1194 print " </para>\n </listitem>\n </varlistentry>\n";
1195 }
1196 print " </variablelist>\n";
1197 } else {
1198 print " <para>\n None\n </para>\n";
1199 }
1200 print "</refsect1>\n";
1201
1202 output_section_xml(@_);
1203 print "</refentry>\n\n";
1204}
1205
1206# output struct in XML DocBook
1207sub output_struct_xml(%) {
1208 my %args = %{$_[0]};
1209 my ($parameter, $section);
1210 my $id;
1211
b9d97328 1212 $id = "API-struct-" . $args{'struct'};
1da177e4
LT		 1213 $id =~ s/[^A-Za-z0-9]/-/g;
1214
5449bc94 1215 print "<refentry id=\"$id\">\n";
8b0c2d98
MW		 1216 print "<refentryinfo>\n";
1217 print " <title>LINUX</title>\n";
1218 print " <productname>Kernel Hackers Manual</productname>\n";
1219 print " <date>$man_date</date>\n";
1220 print "</refentryinfo>\n";
1da177e4 1221 print "<refmeta>\n";
b9d97328 1222 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
8b0c2d98 1223 print " <manvolnum>9</manvolnum>\n";
0366299b 1224 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1da177e4
LT		 1225 print "</refmeta>\n";
1226 print "<refnamediv>\n";
b9d97328 1227 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1da177e4
LT		 1228 print " <refpurpose>\n";
1229 print " ";
1230 output_highlight ($args{'purpose'});
1231 print " </refpurpose>\n";
1232 print "</refnamediv>\n";
1233
1234 print "<refsynopsisdiv>\n";
1235 print " <title>Synopsis</title>\n";
1236 print " <programlisting>\n";
b9d97328 1237 print $args{'type'} . " " . $args{'struct'} . " {\n";
1da177e4
LT		 1238 foreach $parameter (@{$args{'parameterlist'}}) {
1239 if ($parameter =~ /^#/) {
2b35f4d9
RD		 1240 my $prm = $parameter;
1241 # convert data read & converted thru xml_escape() into &xyz; format:
1242 # This allows us to have #define macros interspersed in a struct.
1243 $prm =~ s/\\\\\\/\&/g;
1244 print "$prm\n";
1da177e4
LT		 1245 next;
1246 }
1247
1248 my $parameter_name = $parameter;
1249 $parameter_name =~ s/\[.*//;
1250
1251 defined($args{'parameterdescs'}{$parameter_name}) || next;
3c308798 1252 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1da177e4
LT		 1253 $type = $args{'parametertypes'}{$parameter};
1254 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1255 # pointer-to-function
1256 print " $1 $parameter) ($2);\n";
1257 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
51f5a0c8 1258 # bitfield
1da177e4
LT		 1259 print " $1 $parameter$2;\n";
1260 } else {
b9d97328 1261 print " " . $type . " " . $parameter . ";\n";
1da177e4
LT		 1262 }
1263 }
1264 print "};";
1265 print " </programlisting>\n";
1266 print "</refsynopsisdiv>\n";
1267
1268 print " <refsect1>\n";
1269 print " <title>Members</title>\n";
1270
39f00c08 1271 if ($#{$args{'parameterlist'}} >= 0) {
1da177e4
LT		 1272 print " <variablelist>\n";
1273 foreach $parameter (@{$args{'parameterlist'}}) {
1274 ($parameter =~ /^#/) && next;
1275
1276 my $parameter_name = $parameter;
1277 $parameter_name =~ s/\[.*//;
1278
1279 defined($args{'parameterdescs'}{$parameter_name}) || next;
1280 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
fc6d7af8 1281 $type = $args{'parametertypes'}{$parameter};
1da177e4 1282 print " <varlistentry>";
fc6d7af8 1283 print " <term><literal>$type $parameter</literal></term>\n";
1da177e4
LT		 1284 print " <listitem><para>\n";
1285 output_highlight($args{'parameterdescs'}{$parameter_name});
1286 print " </para></listitem>\n";
1287 print " </varlistentry>\n";
1288 }
1289 print " </variablelist>\n";
39f00c08
RD		 1290 } else {
1291 print " <para>\n None\n </para>\n";
1292 }
1da177e4
LT		 1293 print " </refsect1>\n";
1294
1295 output_section_xml(@_);
1296
1297 print "</refentry>\n\n";
1298}
1299
1300# output enum in XML DocBook
1301sub output_enum_xml(%) {
1302 my %args = %{$_[0]};
1303 my ($parameter, $section);
1304 my $count;
1305 my $id;
1306
b9d97328 1307 $id = "API-enum-" . $args{'enum'};
1da177e4
LT		 1308 $id =~ s/[^A-Za-z0-9]/-/g;
1309
5449bc94 1310 print "<refentry id=\"$id\">\n";
8b0c2d98
MW		 1311 print "<refentryinfo>\n";
1312 print " <title>LINUX</title>\n";
1313 print " <productname>Kernel Hackers Manual</productname>\n";
1314 print " <date>$man_date</date>\n";
1315 print "</refentryinfo>\n";
1da177e4 1316 print "<refmeta>\n";
b9d97328 1317 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
8b0c2d98 1318 print " <manvolnum>9</manvolnum>\n";
0366299b 1319 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1da177e4
LT		 1320 print "</refmeta>\n";
1321 print "<refnamediv>\n";
b9d97328 1322 print " <refname>enum " . $args{'enum'} . "</refname>\n";
1da177e4
LT		 1323 print " <refpurpose>\n";
1324 print " ";
1325 output_highlight ($args{'purpose'});
1326 print " </refpurpose>\n";
1327 print "</refnamediv>\n";
1328
1329 print "<refsynopsisdiv>\n";
1330 print " <title>Synopsis</title>\n";
1331 print " <programlisting>\n";
b9d97328 1332 print "enum " . $args{'enum'} . " {\n";
1da177e4
LT		 1333 $count = 0;
1334 foreach $parameter (@{$args{'parameterlist'}}) {
3c308798
RD		 1335 print " $parameter";
1336 if ($count != $#{$args{'parameterlist'}}) {
1da177e4
LT		 1337 $count++;
1338 print ",";
3c308798 1339 }
1da177e4
LT		 1340 print "\n";
1341 }
1342 print "};";
1343 print " </programlisting>\n";
1344 print "</refsynopsisdiv>\n";
1345
1346 print "<refsect1>\n";
3c3b809e 1347 print " <title>Constants</title>\n";
1da177e4
LT		 1348 print " <variablelist>\n";
1349 foreach $parameter (@{$args{'parameterlist'}}) {
1350 my $parameter_name = $parameter;
1351 $parameter_name =~ s/\[.*//;
1352
1353 print " <varlistentry>";
1354 print " <term>$parameter</term>\n";
1355 print " <listitem><para>\n";
1356 output_highlight($args{'parameterdescs'}{$parameter_name});
1357 print " </para></listitem>\n";
1358 print " </varlistentry>\n";
1359 }
1360 print " </variablelist>\n";
1361 print "</refsect1>\n";
1362
1363 output_section_xml(@_);
1364
1365 print "</refentry>\n\n";
1366}
1367
1368# output typedef in XML DocBook
1369sub output_typedef_xml(%) {
1370 my %args = %{$_[0]};
1371 my ($parameter, $section);
1372 my $id;
1373
b9d97328 1374 $id = "API-typedef-" . $args{'typedef'};
1da177e4
LT		 1375 $id =~ s/[^A-Za-z0-9]/-/g;
1376
5449bc94 1377 print "<refentry id=\"$id\">\n";
8b0c2d98
MW		 1378 print "<refentryinfo>\n";
1379 print " <title>LINUX</title>\n";
1380 print " <productname>Kernel Hackers Manual</productname>\n";
1381 print " <date>$man_date</date>\n";
1382 print "</refentryinfo>\n";
1da177e4 1383 print "<refmeta>\n";
b9d97328 1384 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
8b0c2d98 1385 print " <manvolnum>9</manvolnum>\n";
1da177e4
LT		 1386 print "</refmeta>\n";
1387 print "<refnamediv>\n";
b9d97328 1388 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1da177e4
LT		 1389 print " <refpurpose>\n";
1390 print " ";
1391 output_highlight ($args{'purpose'});
1392 print " </refpurpose>\n";
1393 print "</refnamediv>\n";
1394
1395 print "<refsynopsisdiv>\n";
1396 print " <title>Synopsis</title>\n";
b9d97328 1397 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1da177e4
LT		 1398 print "</refsynopsisdiv>\n";
1399
1400 output_section_xml(@_);
1401
1402 print "</refentry>\n\n";
1403}
1404
1405# output in XML DocBook
b112e0f7 1406sub output_blockhead_xml(%) {
1da177e4
LT		 1407 my %args = %{$_[0]};
1408 my ($parameter, $section);
1409 my $count;
1410
1411 my $id = $args{'module'};
1412 $id =~ s/[^A-Za-z0-9]/-/g;
1413
1414 # print out each section
1415 $lineprefix=" ";
1416 foreach $section (@{$args{'sectionlist'}}) {
b112e0f7
JB		 1417 if (!$args{'content-only'}) {
1418 print "<refsect1>\n <title>$section</title>\n";
1419 }
1da177e4
LT		 1420 if ($section =~ m/EXAMPLE/i) {
1421 print "<example><para>\n";
e314ba31 1422 $output_preformatted = 1;
b112e0f7
JB		 1423 } else {
1424 print "<para>\n";
1da177e4
LT		 1425 }
1426 output_highlight($args{'sections'}{$section});
e314ba31 1427 $output_preformatted = 0;
1da177e4
LT		 1428 if ($section =~ m/EXAMPLE/i) {
1429 print "</para></example>\n";
b112e0f7
JB		 1430 } else {
1431 print "</para>";
1432 }
1433 if (!$args{'content-only'}) {
1434 print "\n</refsect1>\n";
1da177e4 1435 }
1da177e4
LT		 1436 }
1437
1438 print "\n\n";
1439}
1440
1441# output in XML DocBook
1442sub output_function_gnome {
1443 my %args = %{$_[0]};
1444 my ($parameter, $section);
1445 my $count;
1446 my $id;
1447
b9d97328 1448 $id = $args{'module'} . "-" . $args{'function'};
1da177e4
LT		 1449 $id =~ s/[^A-Za-z0-9]/-/g;
1450
1451 print "<sect2>\n";
b9d97328 1452 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1da177e4
LT		 1453
1454 print " <funcsynopsis>\n";
b9d97328
RD		 1455 print " <funcdef>" . $args{'functiontype'} . " ";
1456 print "<function>" . $args{'function'} . " ";
1da177e4
LT		 1457 print "</function></funcdef>\n";
1458
1459 $count = 0;
1460 if ($#{$args{'parameterlist'}} >= 0) {
1461 foreach $parameter (@{$args{'parameterlist'}}) {
1462 $type = $args{'parametertypes'}{$parameter};
1463 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1464 # pointer-to-function
1465 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1466 print " <funcparams>$2</funcparams></paramdef>\n";
1467 } else {
b9d97328 1468 print " <paramdef>" . $type;
1da177e4
LT		 1469 print " <parameter>$parameter</parameter></paramdef>\n";
1470 }
1471 }
1472 } else {
1473 print " <void>\n";
1474 }
1475 print " </funcsynopsis>\n";
1476 if ($#{$args{'parameterlist'}} >= 0) {
1477 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1478 print "<tgroup cols=\"2\">\n";
1479 print "<colspec colwidth=\"2*\">\n";
1480 print "<colspec colwidth=\"8*\">\n";
1481 print "<tbody>\n";
1482 foreach $parameter (@{$args{'parameterlist'}}) {
1483 my $parameter_name = $parameter;
1484 $parameter_name =~ s/\[.*//;
1485
1486 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1487 print " <entry>\n";
1488 $lineprefix=" ";
1489 output_highlight($args{'parameterdescs'}{$parameter_name});
1490 print " </entry></row>\n";
1491 }
1492 print " </tbody></tgroup></informaltable>\n";
1493 } else {
1494 print " <para>\n None\n </para>\n";
1495 }
1496
1497 # print out each section
1498 $lineprefix=" ";
1499 foreach $section (@{$args{'sectionlist'}}) {
1500 print "<simplesect>\n <title>$section</title>\n";
1501 if ($section =~ m/EXAMPLE/i) {
1502 print "<example><programlisting>\n";
e314ba31 1503 $output_preformatted = 1;
1da177e4
LT		 1504 } else {
1505 }
1506 print "<para>\n";
1507 output_highlight($args{'sections'}{$section});
e314ba31 1508 $output_preformatted = 0;
1da177e4
LT		 1509 print "</para>\n";
1510 if ($section =~ m/EXAMPLE/i) {
1511 print "</programlisting></example>\n";
1512 } else {
1513 }
1514 print " </simplesect>\n";
1515 }
1516
1517 print "</sect2>\n\n";
1518}
1519
1520##
1521# output function in man
1522sub output_function_man(%) {
1523 my %args = %{$_[0]};
1524 my ($parameter, $section);
1525 my $count;
1526
1527 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1528
1529 print ".SH NAME\n";
b9d97328 1530 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT		 1531
1532 print ".SH SYNOPSIS\n";
a21217da 1533 if ($args{'functiontype'} ne "") {
b9d97328 1534 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
a21217da 1535 } else {
b9d97328 1536 print ".B \"" . $args{'function'} . "\n";
a21217da 1537 }
1da177e4
LT		 1538 $count = 0;
1539 my $parenth = "(";
1540 my $post = ",";
1541 foreach my $parameter (@{$args{'parameterlist'}}) {
1542 if ($count == $#{$args{'parameterlist'}}) {
1543 $post = ");";
1544 }
1545 $type = $args{'parametertypes'}{$parameter};
1546 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1547 # pointer-to-function
b9d97328 1548 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1da177e4
LT		 1549 } else {
1550 $type =~ s/([^\*])$/$1 /;
b9d97328 1551 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1da177e4
LT		 1552 }
1553 $count++;
1554 $parenth = "";
1555 }
1556
1557 print ".SH ARGUMENTS\n";
1558 foreach $parameter (@{$args{'parameterlist'}}) {
1559 my $parameter_name = $parameter;
1560 $parameter_name =~ s/\[.*//;
1561
b9d97328 1562 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT		 1563 output_highlight($args{'parameterdescs'}{$parameter_name});
1564 }
1565 foreach $section (@{$args{'sectionlist'}}) {
1566 print ".SH \"", uc $section, "\"\n";
1567 output_highlight($args{'sections'}{$section});
1568 }
1569}
1570
1571##
1572# output enum in man
1573sub output_enum_man(%) {
1574 my %args = %{$_[0]};
1575 my ($parameter, $section);
1576 my $count;
1577
1578 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1579
1580 print ".SH NAME\n";
b9d97328 1581 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT		 1582
1583 print ".SH SYNOPSIS\n";
b9d97328 1584 print "enum " . $args{'enum'} . " {\n";
1da177e4
LT		 1585 $count = 0;
1586 foreach my $parameter (@{$args{'parameterlist'}}) {
3c308798 1587 print ".br\n.BI \" $parameter\"\n";
1da177e4
LT		 1588 if ($count == $#{$args{'parameterlist'}}) {
1589 print "\n};\n";
1590 last;
1591 }
1592 else {
1593 print ", \n.br\n";
1594 }
1595 $count++;
1596 }
1597
1598 print ".SH Constants\n";
1599 foreach $parameter (@{$args{'parameterlist'}}) {
1600 my $parameter_name = $parameter;
1601 $parameter_name =~ s/\[.*//;
1602
b9d97328 1603 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT		 1604 output_highlight($args{'parameterdescs'}{$parameter_name});
1605 }
1606 foreach $section (@{$args{'sectionlist'}}) {
1607 print ".SH \"$section\"\n";
1608 output_highlight($args{'sections'}{$section});
1609 }
1610}
1611
1612##
1613# output struct in man
1614sub output_struct_man(%) {
1615 my %args = %{$_[0]};
1616 my ($parameter, $section);
1617
b9d97328 1618 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1da177e4
LT		 1619
1620 print ".SH NAME\n";
b9d97328 1621 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT		 1622
1623 print ".SH SYNOPSIS\n";
b9d97328 1624 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1da177e4
LT		 1625
1626 foreach my $parameter (@{$args{'parameterlist'}}) {
1627 if ($parameter =~ /^#/) {
1628 print ".BI \"$parameter\"\n.br\n";
1629 next;
1630 }
1631 my $parameter_name = $parameter;
1632 $parameter_name =~ s/\[.*//;
1633
3c308798 1634 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1da177e4
LT		 1635 $type = $args{'parametertypes'}{$parameter};
1636 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1637 # pointer-to-function
b9d97328 1638 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1da177e4 1639 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1d7e1d45 1640 # bitfield
b9d97328 1641 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1da177e4
LT		 1642 } else {
1643 $type =~ s/([^\*])$/$1 /;
b9d97328 1644 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1da177e4
LT		 1645 }
1646 print "\n.br\n";
1647 }
1648 print "};\n.br\n";
1649
c51d3dac 1650 print ".SH Members\n";
1da177e4
LT		 1651 foreach $parameter (@{$args{'parameterlist'}}) {
1652 ($parameter =~ /^#/) && next;
1653
1654 my $parameter_name = $parameter;
1655 $parameter_name =~ s/\[.*//;
1656
3c308798 1657 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
b9d97328 1658 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT		 1659 output_highlight($args{'parameterdescs'}{$parameter_name});
1660 }
1661 foreach $section (@{$args{'sectionlist'}}) {
1662 print ".SH \"$section\"\n";
1663 output_highlight($args{'sections'}{$section});
1664 }
1665}
1666
1667##
1668# output typedef in man
1669sub output_typedef_man(%) {
1670 my %args = %{$_[0]};
1671 my ($parameter, $section);
1672
1673 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1674
1675 print ".SH NAME\n";
b9d97328 1676 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT		 1677
1678 foreach $section (@{$args{'sectionlist'}}) {
1679 print ".SH \"$section\"\n";
1680 output_highlight($args{'sections'}{$section});
1681 }
1682}
1683
b112e0f7 1684sub output_blockhead_man(%) {
1da177e4
LT		 1685 my %args = %{$_[0]};
1686 my ($parameter, $section);
1687 my $count;
1688
1689 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1690
1691 foreach $section (@{$args{'sectionlist'}}) {
1692 print ".SH \"$section\"\n";
1693 output_highlight($args{'sections'}{$section});
1694 }
1695}
1696
1697##
1698# output in text
1699sub output_function_text(%) {
1700 my %args = %{$_[0]};
1701 my ($parameter, $section);
a21217da 1702 my $start;
1da177e4 1703
f47634b2 1704 print "Name:\n\n";
b9d97328 1705 print $args{'function'} . " - " . $args{'purpose'} . "\n";
f47634b2
RD		 1706
1707 print "\nSynopsis:\n\n";
a21217da 1708 if ($args{'functiontype'} ne "") {
b9d97328 1709 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
a21217da 1710 } else {
b9d97328 1711 $start = $args{'function'} . " (";
a21217da 1712 }
1da177e4 1713 print $start;
a21217da 1714
1da177e4
LT		 1715 my $count = 0;
1716 foreach my $parameter (@{$args{'parameterlist'}}) {
1717 $type = $args{'parametertypes'}{$parameter};
1718 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1719 # pointer-to-function
b9d97328 1720 print $1 . $parameter . ") (" . $2;
1da177e4 1721 } else {
b9d97328 1722 print $type . " " . $parameter;
1da177e4
LT		 1723 }
1724 if ($count != $#{$args{'parameterlist'}}) {
1725 $count++;
1726 print ",\n";
1727 print " " x length($start);
1728 } else {
1729 print ");\n\n";
1730 }
1731 }
1732
1733 print "Arguments:\n\n";
1734 foreach $parameter (@{$args{'parameterlist'}}) {
1735 my $parameter_name = $parameter;
1736 $parameter_name =~ s/\[.*//;
1737
b9d97328 1738 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1da177e4
LT		 1739 }
1740 output_section_text(@_);
1741}
1742
1743#output sections in text
1744sub output_section_text(%) {
1745 my %args = %{$_[0]};
1746 my $section;
1747
1748 print "\n";
1749 foreach $section (@{$args{'sectionlist'}}) {
1750 print "$section:\n\n";
1751 output_highlight($args{'sections'}{$section});
3c3b809e 1752 }
1da177e4
LT		 1753 print "\n\n";
1754}
1755
1756# output enum in text
1757sub output_enum_text(%) {
1758 my %args = %{$_[0]};
1759 my ($parameter);
1760 my $count;
1761 print "Enum:\n\n";
1762
b9d97328
RD		 1763 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1764 print "enum " . $args{'enum'} . " {\n";
1da177e4
LT		 1765 $count = 0;
1766 foreach $parameter (@{$args{'parameterlist'}}) {
3c308798 1767 print "\t$parameter";
1da177e4
LT		 1768 if ($count != $#{$args{'parameterlist'}}) {
1769 $count++;
1770 print ",";
1771 }
1772 print "\n";
1773 }
1774 print "};\n\n";
1775
1776 print "Constants:\n\n";
1777 foreach $parameter (@{$args{'parameterlist'}}) {
1778 print "$parameter\n\t";
b9d97328 1779 print $args{'parameterdescs'}{$parameter} . "\n";
1da177e4
LT		 1780 }
1781
1782 output_section_text(@_);
1783}
1784
1785# output typedef in text
1786sub output_typedef_text(%) {
1787 my %args = %{$_[0]};
1788 my ($parameter);
1789 my $count;
1790 print "Typedef:\n\n";
1791
b9d97328 1792 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1da177e4
LT		 1793 output_section_text(@_);
1794}
1795
1796# output struct as text
1797sub output_struct_text(%) {
1798 my %args = %{$_[0]};
1799 my ($parameter);
1800
b9d97328
RD		 1801 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1802 print $args{'type'} . " " . $args{'struct'} . " {\n";
1da177e4
LT		 1803 foreach $parameter (@{$args{'parameterlist'}}) {
1804 if ($parameter =~ /^#/) {
1805 print "$parameter\n";
1806 next;
1807 }
1808
1809 my $parameter_name = $parameter;
1810 $parameter_name =~ s/\[.*//;
1811
3c308798 1812 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1da177e4
LT		 1813 $type = $args{'parametertypes'}{$parameter};
1814 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1815 # pointer-to-function
1816 print "\t$1 $parameter) ($2);\n";
1817 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
51f5a0c8 1818 # bitfield
1da177e4
LT		 1819 print "\t$1 $parameter$2;\n";
1820 } else {
b9d97328 1821 print "\t" . $type . " " . $parameter . ";\n";
1da177e4
LT		 1822 }
1823 }
1824 print "};\n\n";
1825
1826 print "Members:\n\n";
1827 foreach $parameter (@{$args{'parameterlist'}}) {
1828 ($parameter =~ /^#/) && next;
1829
1830 my $parameter_name = $parameter;
1831 $parameter_name =~ s/\[.*//;
1832
3c308798 1833 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1da177e4 1834 print "$parameter\n\t";
b9d97328 1835 print $args{'parameterdescs'}{$parameter_name} . "\n";
1da177e4
LT		 1836 }
1837 print "\n";
1838 output_section_text(@_);
1839}
1840
b112e0f7 1841sub output_blockhead_text(%) {
1da177e4
LT		 1842 my %args = %{$_[0]};
1843 my ($parameter, $section);
1844
1845 foreach $section (@{$args{'sectionlist'}}) {
1846 print " $section:\n";
1847 print " -> ";
1848 output_highlight($args{'sections'}{$section});
1849 }
1850}
1851
c0d1b6ee
JC		 1852##
1853# output in restructured text
1854#
1855
1856#
1857# This could use some work; it's used to output the DOC: sections, and
1858# starts by putting out the name of the doc section itself, but that tends
1859# to duplicate a header already in the template file.
1860#
1861sub output_blockhead_rst(%) {
1862 my %args = %{$_[0]};
1863 my ($parameter, $section);
1864
1865 foreach $section (@{$args{'sectionlist'}}) {
9e72184b
JN		 1866 if ($output_selection != OUTPUT_INCLUDE) {
1867 print "**$section**\n\n";
1868 }
0b0f5f29 1869 print_lineno($section_start_lines{$section});
c0d1b6ee
JC		 1870 output_highlight_rst($args{'sections'}{$section});
1871 print "\n";
1872 }
1873}
1874
1875sub output_highlight_rst {
1876 my $contents = join "\n",@_;
1877 my $line;
1878
1879 # undo the evil effects of xml_escape() earlier
1880 $contents = xml_unescape($contents);
1881
1882 eval $dohighlight;
1883 die $@ if $@;
1884
1885 foreach $line (split "\n", $contents) {
830066a7 1886 print $lineprefix . $line . "\n";
c0d1b6ee
JC		 1887 }
1888}
1889
1890sub output_function_rst(%) {
1891 my %args = %{$_[0]};
1892 my ($parameter, $section);
c099ff69 1893 my $oldprefix = $lineprefix;
82801d06
MCC		 1894 my $start = "";
1895
1896 if ($args{'typedef'}) {
1897 print ".. c:type:: ". $args{'function'} . "\n\n";
1898 print_lineno($declaration_start_line);
1899 print " **Typedef**: ";
1900 $lineprefix = "";
1901 output_highlight_rst($args{'purpose'});
1902 $start = "\n\n**Syntax**\n\n ``";
1903 } else {
1904 print ".. c:function:: ";
1905 }
c0d1b6ee 1906 if ($args{'functiontype'} ne "") {
82801d06 1907 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
c0d1b6ee 1908 } else {
82801d06 1909 $start .= $args{'function'} . " (";
c0d1b6ee
JC		 1910 }
1911 print $start;
1912
1913 my $count = 0;
1914 foreach my $parameter (@{$args{'parameterlist'}}) {
1915 if ($count ne 0) {
1916 print ", ";
1917 }
1918 $count++;
1919 $type = $args{'parametertypes'}{$parameter};
a88b1672 1920
c0d1b6ee
JC		 1921 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1922 # pointer-to-function
1923 print $1 . $parameter . ") (" . $2;
1924 } else {
1925 print $type . " " . $parameter;
1926 }
1927 }
82801d06
MCC		 1928 if ($args{'typedef'}) {
1929 print ");``\n\n";
1930 } else {
1931 print ")\n\n";
1932 print_lineno($declaration_start_line);
1933 $lineprefix = " ";
1934 output_highlight_rst($args{'purpose'});
1935 print "\n";
1936 }
c0d1b6ee 1937
ecbcfba1
JN		 1938 print "**Parameters**\n\n";
1939 $lineprefix = " ";
c0d1b6ee
JC		 1940 foreach $parameter (@{$args{'parameterlist'}}) {
1941 my $parameter_name = $parameter;
ada5f446 1942 $parameter_name =~ s/\[.*//;
c0d1b6ee
JC		 1943 $type = $args{'parametertypes'}{$parameter};
1944
1945 if ($type ne "") {
ecbcfba1 1946 print "``$type $parameter``\n";
c0d1b6ee 1947 } else {
ecbcfba1 1948 print "``$parameter``\n";
c0d1b6ee 1949 }
0b0f5f29
DV		 1950
1951 print_lineno($parameterdesc_start_lines{$parameter_name});
1952
5e64fa9c
JN		 1953 if (defined($args{'parameterdescs'}{$parameter_name}) &&
1954 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
c0d1b6ee 1955 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
c0d1b6ee 1956 } else {
d4b08e0c 1957 print " *undescribed*\n";
c0d1b6ee
JC		 1958 }
1959 print "\n";
1960 }
c099ff69
JN		 1961
1962 $lineprefix = $oldprefix;
c0d1b6ee
JC		 1963 output_section_rst(@_);
1964}
1965
1966sub output_section_rst(%) {
1967 my %args = %{$_[0]};
1968 my $section;
1969 my $oldprefix = $lineprefix;
ecbcfba1 1970 $lineprefix = "";
c0d1b6ee
JC		 1971
1972 foreach $section (@{$args{'sectionlist'}}) {
ecbcfba1 1973 print "**$section**\n\n";
0b0f5f29 1974 print_lineno($section_start_lines{$section});
c0d1b6ee
JC		 1975 output_highlight_rst($args{'sections'}{$section});
1976 print "\n";
1977 }
1978 print "\n";
1979 $lineprefix = $oldprefix;
1980}
1981
1982sub output_enum_rst(%) {
1983 my %args = %{$_[0]};
1984 my ($parameter);
c099ff69 1985 my $oldprefix = $lineprefix;
c0d1b6ee 1986 my $count;
c0d1b6ee 1987 my $name = "enum " . $args{'enum'};
62850976
JN		 1988
1989 print "\n\n.. c:type:: " . $name . "\n\n";
0b0f5f29 1990 print_lineno($declaration_start_line);
c099ff69
JN		 1991 $lineprefix = " ";
1992 output_highlight_rst($args{'purpose'});
1993 print "\n";
c0d1b6ee 1994
ecbcfba1
JN		 1995 print "**Constants**\n\n";
1996 $lineprefix = " ";
c0d1b6ee 1997 foreach $parameter (@{$args{'parameterlist'}}) {
ecbcfba1 1998 print "``$parameter``\n";
c0d1b6ee
JC		 1999 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
2000 output_highlight_rst($args{'parameterdescs'}{$parameter});
2001 } else {
d4b08e0c 2002 print " *undescribed*\n";
c0d1b6ee
JC		 2003 }
2004 print "\n";
2005 }
c099ff69 2006
c0d1b6ee
JC		 2007 $lineprefix = $oldprefix;
2008 output_section_rst(@_);
2009}
2010
2011sub output_typedef_rst(%) {
2012 my %args = %{$_[0]};
2013 my ($parameter);
c099ff69 2014 my $oldprefix = $lineprefix;
c0d1b6ee
JC		 2015 my $name = "typedef " . $args{'typedef'};
2016
62850976 2017 print "\n\n.. c:type:: " . $name . "\n\n";
0b0f5f29 2018 print_lineno($declaration_start_line);
c099ff69
JN		 2019 $lineprefix = " ";
2020 output_highlight_rst($args{'purpose'});
2021 print "\n";
c0d1b6ee 2022
c099ff69 2023 $lineprefix = $oldprefix;
c0d1b6ee
JC		 2024 output_section_rst(@_);
2025}
2026
2027sub output_struct_rst(%) {
2028 my %args = %{$_[0]};
2029 my ($parameter);
c099ff69 2030 my $oldprefix = $lineprefix;
c0d1b6ee
JC		 2031 my $name = $args{'type'} . " " . $args{'struct'};
2032
62850976 2033 print "\n\n.. c:type:: " . $name . "\n\n";
0b0f5f29 2034 print_lineno($declaration_start_line);
c099ff69
JN		 2035 $lineprefix = " ";
2036 output_highlight_rst($args{'purpose'});
2037 print "\n";
c0d1b6ee 2038
ecbcfba1
JN		 2039 print "**Definition**\n\n";
2040 print "::\n\n";
c0d1b6ee
JC		 2041 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
2042 foreach $parameter (@{$args{'parameterlist'}}) {
2043 if ($parameter =~ /^#/) {
ecbcfba1 2044 print " " . "$parameter\n";
c0d1b6ee
JC		 2045 next;
2046 }
2047
2048 my $parameter_name = $parameter;
2049 $parameter_name =~ s/\[.*//;
2050
2051 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
2052 $type = $args{'parametertypes'}{$parameter};
2053 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
2054 # pointer-to-function
2055 print " $1 $parameter) ($2);\n";
2056 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
2057 # bitfield
2058 print " $1 $parameter$2;\n";
2059 } else {
2060 print " " . $type . " " . $parameter . ";\n";
2061 }
2062 }
2063 print " };\n\n";
2064
ecbcfba1
JN		 2065 print "**Members**\n\n";
2066 $lineprefix = " ";
c0d1b6ee
JC		 2067 foreach $parameter (@{$args{'parameterlist'}}) {
2068 ($parameter =~ /^#/) && next;
2069
2070 my $parameter_name = $parameter;
2071 $parameter_name =~ s/\[.*//;
2072
2073 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
2074 $type = $args{'parametertypes'}{$parameter};
0b0f5f29 2075 print_lineno($parameterdesc_start_lines{$parameter_name});
6d232c80 2076 print "``" . $parameter . "``\n";
c0d1b6ee 2077 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
c0d1b6ee
JC		 2078 print "\n";
2079 }
2080 print "\n";
c099ff69
JN		 2081
2082 $lineprefix = $oldprefix;
c0d1b6ee
JC		 2083 output_section_rst(@_);
2084}
2085
2086
eda603f6
JB		 2087## list mode output functions
2088
2089sub output_function_list(%) {
2090 my %args = %{$_[0]};
2091
2092 print $args{'function'} . "\n";
2093}
2094
2095# output enum in list
2096sub output_enum_list(%) {
2097 my %args = %{$_[0]};
2098 print $args{'enum'} . "\n";
2099}
2100
2101# output typedef in list
2102sub output_typedef_list(%) {
2103 my %args = %{$_[0]};
2104 print $args{'typedef'} . "\n";
2105}
2106
2107# output struct as list
2108sub output_struct_list(%) {
2109 my %args = %{$_[0]};
2110
2111 print $args{'struct'} . "\n";
2112}
2113
2114sub output_blockhead_list(%) {
2115 my %args = %{$_[0]};
2116 my ($parameter, $section);
2117
2118 foreach $section (@{$args{'sectionlist'}}) {
2119 print "DOC: $section\n";
2120 }
2121}
2122
3a025e1d
MW		 2123
2124## none mode output functions
2125
2126sub output_function_none(%) {
2127}
2128
2129sub output_enum_none(%) {
2130}
2131
2132sub output_typedef_none(%) {
2133}
2134
2135sub output_struct_none(%) {
2136}
2137
2138sub output_blockhead_none(%) {
2139}
2140
1da177e4 2141##
27205744
RD		 2142# generic output function for all types (function, struct/union, typedef, enum);
2143# calls the generated, variable output_ function name based on
2144# functype and output_mode
1da177e4
LT		 2145sub output_declaration {
2146 no strict 'refs';
2147 my $name = shift;
2148 my $functype = shift;
2149 my $func = "output_${functype}_$output_mode";
b6c3f456
JN		 2150 if (($output_selection == OUTPUT_ALL) ||
2151 (($output_selection == OUTPUT_INCLUDE ||
2152 $output_selection == OUTPUT_EXPORTED) &&
2153 defined($function_table{$name})) ||
2154 (($output_selection == OUTPUT_EXCLUDE ||
2155 $output_selection == OUTPUT_INTERNAL) &&
2156 !($functype eq "function" && defined($function_table{$name}))))
1da177e4 2157 {
3c308798 2158 &$func(@_);
1da177e4
LT		 2159 $section_counter++;
2160 }
2161}
2162
2163##
27205744 2164# generic output function - calls the right one based on current output mode.
b112e0f7 2165sub output_blockhead {
1da177e4 2166 no strict 'refs';
b9d97328 2167 my $func = "output_blockhead_" . $output_mode;
1da177e4
LT		 2168 &$func(@_);
2169 $section_counter++;
2170}
2171
2172##
3c3b809e 2173# takes a declaration (struct, union, enum, typedef) and
1da177e4
LT		 2174# invokes the right handler. NOT called for functions.
2175sub dump_declaration($$) {
2176 no strict 'refs';
2177 my ($prototype, $file) = @_;
b9d97328 2178 my $func = "dump_" . $decl_type;
1da177e4
LT		 2179 &$func(@_);
2180}
2181
2182sub dump_union($$) {
2183 dump_struct(@_);
2184}
2185
2186sub dump_struct($$) {
2187 my $x = shift;
2188 my $file = shift;
a1d94aa5 2189 my $nested;
1da177e4 2190
52dc5aec 2191 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
5cb5c31c 2192 my $decl_type = $1;
3c308798
RD		 2193 $declaration_name = $2;
2194 my $members = $3;
1da177e4
LT		 2195
2196 # ignore embedded structs or unions
a1d94aa5
RD		 2197 $members =~ s/({.*})//g;
2198 $nested = $1;
1da177e4 2199
aeec46b9 2200 # ignore members marked private:
0d8c39e6
MCC		 2201 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2202 $members =~ s/\/\*\s*private:.*//gosi;
aeec46b9
MW		 2203 # strip comments:
2204 $members =~ s/\/\*.*?\*\///gos;
a1d94aa5 2205 $nested =~ s/\/\*.*?\*\///gos;
ef5da59f 2206 # strip attributes
f0074929 2207 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
7b990789 2208 $members =~ s/__aligned\s*\([^;]*\)//gos;
f0074929 2209 $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
b22b5a9e
CN		 2210 # replace DECLARE_BITMAP
2211 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1cb566ba
JK		 2212 # replace DECLARE_HASHTABLE
2213 $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
aeec46b9 2214
1da177e4 2215 create_parameterlist($members, ';', $file);
5cb5c31c 2216 check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested);
1da177e4
LT		 2217
2218 output_declaration($declaration_name,
2219 'struct',
2220 {'struct' => $declaration_name,
2221 'module' => $modulename,
2222 'parameterlist' => \@parameterlist,
2223 'parameterdescs' => \%parameterdescs,
2224 'parametertypes' => \%parametertypes,
2225 'sectionlist' => \@sectionlist,
2226 'sections' => \%sections,
2227 'purpose' => $declaration_purpose,
2228 'type' => $decl_type
2229 });
2230 }
2231 else {
d40e1e65 2232 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1da177e4
LT		 2233 ++$errors;
2234 }
2235}
2236
2237sub dump_enum($$) {
2238 my $x = shift;
2239 my $file = shift;
2240
aeec46b9 2241 $x =~ s@/\*.*?\*/@@gos; # strip comments.
4468e21e
CN		 2242 # strip #define macros inside enums
2243 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
b6d676db 2244
1da177e4 2245 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
3c308798
RD		 2246 $declaration_name = $1;
2247 my $members = $2;
5cb5c31c
JB		 2248 my %_members;
2249
463a0fdc 2250 $members =~ s/\s+$//;
1da177e4
LT		 2251
2252 foreach my $arg (split ',', $members) {
2253 $arg =~ s/^\s*(\w+).*/$1/;
2254 push @parameterlist, $arg;
2255 if (!$parameterdescs{$arg}) {
3c308798 2256 $parameterdescs{$arg} = $undescribed;
d40e1e65 2257 print STDERR "${file}:$.: warning: Enum value '$arg' ".
1da177e4
LT		 2258 "not described in enum '$declaration_name'\n";
2259 }
5cb5c31c 2260 $_members{$arg} = 1;
1da177e4 2261 }
3c3b809e 2262
5cb5c31c
JB		 2263 while (my ($k, $v) = each %parameterdescs) {
2264 if (!exists($_members{$k})) {
2265 print STDERR "${file}:$.: warning: Excess enum value " .
2266 "'$k' description in '$declaration_name'\n";
2267 }
2268 }
2269
1da177e4
LT		 2270 output_declaration($declaration_name,
2271 'enum',
2272 {'enum' => $declaration_name,
2273 'module' => $modulename,
2274 'parameterlist' => \@parameterlist,
2275 'parameterdescs' => \%parameterdescs,
2276 'sectionlist' => \@sectionlist,
2277 'sections' => \%sections,
2278 'purpose' => $declaration_purpose
2279 });
2280 }
2281 else {
d40e1e65 2282 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1da177e4
LT		 2283 ++$errors;
2284 }
2285}
2286
2287sub dump_typedef($$) {
2288 my $x = shift;
2289 my $file = shift;
2290
aeec46b9 2291 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4 2292
83766452 2293 # Parse function prototypes
d37c43ce
MCC		 2294 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
2295 $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
2296
83766452
MCC		 2297 # Function typedefs
2298 $return_type = $1;
2299 $declaration_name = $2;
2300 my $args = $3;
2301
2302 create_parameterlist($args, ',', $file);
1da177e4
LT		 2303
2304 output_declaration($declaration_name,
83766452
MCC		 2305 'function',
2306 {'function' => $declaration_name,
82801d06 2307 'typedef' => 1,
1da177e4 2308 'module' => $modulename,
83766452
MCC		 2309 'functiontype' => $return_type,
2310 'parameterlist' => \@parameterlist,
2311 'parameterdescs' => \%parameterdescs,
2312 'parametertypes' => \%parametertypes,
1da177e4
LT		 2313 'sectionlist' => \@sectionlist,
2314 'sections' => \%sections,
2315 'purpose' => $declaration_purpose
2316 });
83766452
MCC		 2317 return;
2318 }
2319
2320 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2321 $x =~ s/\(*.\)\s*;$/;/;
2322 $x =~ s/\[*.\]\s*;$/;/;
1da177e4 2323 }
83766452
MCC		 2324
2325 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
3a80a766
MCC		 2326 $declaration_name = $1;
2327
2328 output_declaration($declaration_name,
2329 'typedef',
2330 {'typedef' => $declaration_name,
2331 'module' => $modulename,
2332 'sectionlist' => \@sectionlist,
2333 'sections' => \%sections,
2334 'purpose' => $declaration_purpose
2335 });
2336 }
1da177e4 2337 else {
d40e1e65 2338 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
1da177e4
LT		 2339 ++$errors;
2340 }
2341}
2342
a1d94aa5
RD		 2343sub save_struct_actual($) {
2344 my $actual = shift;
2345
2346 # strip all spaces from the actual param so that it looks like one string item
2347 $actual =~ s/\s*//g;
2348 $struct_actual = $struct_actual . $actual . " ";
2349}
2350
1da177e4
LT		 2351sub create_parameterlist($$$) {
2352 my $args = shift;
2353 my $splitter = shift;
2354 my $file = shift;
2355 my $type;
2356 my $param;
2357
a6d3fe77 2358 # temporarily replace commas inside function pointer definition
1da177e4 2359 while ($args =~ /(\([^\),]+),/) {
3c308798 2360 $args =~ s/(\([^\),]+),/$1#/g;
1da177e4 2361 }
3c3b809e 2362
1da177e4
LT		 2363 foreach my $arg (split($splitter, $args)) {
2364 # strip comments
2365 $arg =~ s/\/\*.*\*\///;
3c308798
RD		 2366 # strip leading/trailing spaces
2367 $arg =~ s/^\s*//;
1da177e4
LT		 2368 $arg =~ s/\s*$//;
2369 $arg =~ s/\s+/ /;
2370
2371 if ($arg =~ /^#/) {
2372 # Treat preprocessor directive as a typeless variable just to fill
2373 # corresponding data structures "correctly". Catch it later in
2374 # output_* subs.
2375 push_parameter($arg, "", $file);
00d62961 2376 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1da177e4
LT		 2377 # pointer-to-function
2378 $arg =~ tr/#/,/;
00d62961 2379 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
1da177e4
LT		 2380 $param = $1;
2381 $type = $arg;
00d62961 2382 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
a1d94aa5 2383 save_struct_actual($param);
1da177e4 2384 push_parameter($param, $type, $file);
aeec46b9 2385 } elsif ($arg) {
1da177e4
LT		 2386 $arg =~ s/\s*:\s*/:/g;
2387 $arg =~ s/\s*\[/\[/g;
2388
2389 my @args = split('\s*,\s*', $arg);
2390 if ($args[0] =~ m/\*/) {
2391 $args[0] =~ s/(\*+)\s*/ $1/;
2392 }
884f2810
BP		 2393
2394 my @first_arg;
2395 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2396 shift @args;
2397 push(@first_arg, split('\s+', $1));
2398 push(@first_arg, $2);
2399 } else {
2400 @first_arg = split('\s+', shift @args);
2401 }
2402
1da177e4
LT		 2403 unshift(@args, pop @first_arg);
2404 $type = join " ", @first_arg;
2405
2406 foreach $param (@args) {
2407 if ($param =~ m/^(\*+)\s*(.*)/) {
a1d94aa5 2408 save_struct_actual($2);
1da177e4
LT		 2409 push_parameter($2, "$type $1", $file);
2410 }
2411 elsif ($param =~ m/(.*?):(\d+)/) {
7b97887e 2412 if ($type ne "") { # skip unnamed bit-fields
a1d94aa5 2413 save_struct_actual($1);
7b97887e
RD		 2414 push_parameter($1, "$type:$2", $file)
2415 }
1da177e4
LT		 2416 }
2417 else {
a1d94aa5 2418 save_struct_actual($param);
1da177e4
LT		 2419 push_parameter($param, $type, $file);
2420 }
2421 }
2422 }
2423 }
2424}
2425
2426sub push_parameter($$$) {
2427 my $param = shift;
2428 my $type = shift;
2429 my $file = shift;
2430
5f8c7c98
RD		 2431 if (($anon_struct_union == 1) && ($type eq "") &&
2432 ($param eq "}")) {
2433 return; # ignore the ending }; from anon. struct/union
2434 }
2435
2436 $anon_struct_union = 0;
f9b5c530 2437 $param =~ s/[\[\)].*//;
1da177e4 2438
a6d3fe77 2439 if ($type eq "" && $param =~ /\.\.\.$/)
1da177e4 2440 {
c950a173
SF		 2441 if (!$param =~ /\w\.\.\.$/) {
2442 # handles unnamed variable parameters
2443 $param = "...";
2444 }
ced69090
RD		 2445 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2446 $parameterdescs{$param} = "variable arguments";
2447 }
1da177e4
LT		 2448 }
2449 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2450 {
1da177e4
LT		 2451 $param="void";
2452 $parameterdescs{void} = "no arguments";
2453 }
134fe01b
RD		 2454 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2455 # handle unnamed (anonymous) union or struct:
2456 {
2457 $type = $param;
5f8c7c98 2458 $param = "{unnamed_" . $param . "}";
134fe01b 2459 $parameterdescs{$param} = "anonymous\n";
5f8c7c98 2460 $anon_struct_union = 1;
134fe01b
RD		 2461 }
2462
a6d3fe77 2463 # warn if parameter has no description
134fe01b
RD		 2464 # (but ignore ones starting with # as these are not parameters
2465 # but inline preprocessor statements);
2466 # also ignore unnamed structs/unions;
5f8c7c98 2467 if (!$anon_struct_union) {
f9b5c530 2468 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
a6d3fe77 2469
f9b5c530 2470 $parameterdescs{$param} = $undescribed;
1da177e4
LT		 2471
2472 if (($type eq 'function') || ($type eq 'enum')) {
d40e1e65 2473 print STDERR "${file}:$.: warning: Function parameter ".
1da177e4
LT		 2474 "or member '$param' not " .
2475 "described in '$declaration_name'\n";
2476 }
d40e1e65 2477 print STDERR "${file}:$.: warning:" .
3c308798 2478 " No description found for parameter '$param'\n";
1da177e4 2479 ++$warnings;
3c308798
RD		 2480 }
2481 }
1da177e4 2482
2b35f4d9
RD		 2483 $param = xml_escape($param);
2484
25985edc 2485 # strip spaces from $param so that it is one continuous string
e34e7dbb
RD		 2486 # on @parameterlist;
2487 # this fixes a problem where check_sections() cannot find
2488 # a parameter like "addr[6 + 2]" because it actually appears
2489 # as "addr[6", "+", "2]" on the parameter list;
2490 # but it's better to maintain the param string unchanged for output,
2491 # so just weaken the string compare in check_sections() to ignore
2492 # "[blah" in a parameter string;
2493 ###$param =~ s/\s*//g;
1da177e4 2494 push @parameterlist, $param;
02a4f4fe 2495 $type =~ s/\s\s+/ /g;
1da177e4
LT		 2496 $parametertypes{$param} = $type;
2497}
2498
a1d94aa5
RD		 2499sub check_sections($$$$$$) {
2500 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2501 my @sects = split ' ', $sectcheck;
2502 my @prms = split ' ', $prmscheck;
2503 my $err;
2504 my ($px, $sx);
2505 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2506
2507 foreach $sx (0 .. $#sects) {
2508 $err = 1;
2509 foreach $px (0 .. $#prms) {
2510 $prm_clean = $prms[$px];
2511 $prm_clean =~ s/\[.*\]//;
1f3a6688 2512 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
e34e7dbb
RD		 2513 # ignore array size in a parameter string;
2514 # however, the original param string may contain
2515 # spaces, e.g.: addr[6 + 2]
2516 # and this appears in @prms as "addr[6" since the
2517 # parameter list is split at spaces;
2518 # hence just ignore "[..." for the sections check;
2519 $prm_clean =~ s/\[.*//;
2520
a1d94aa5
RD		 2521 ##$prm_clean =~ s/^\**//;
2522 if ($prm_clean eq $sects[$sx]) {
2523 $err = 0;
2524 last;
2525 }
2526 }
2527 if ($err) {
2528 if ($decl_type eq "function") {
d40e1e65 2529 print STDERR "${file}:$.: warning: " .
a1d94aa5
RD		 2530 "Excess function parameter " .
2531 "'$sects[$sx]' " .
2532 "description in '$decl_name'\n";
2533 ++$warnings;
2534 } else {
2535 if ($nested !~ m/\Q$sects[$sx]\E/) {
d40e1e65 2536 print STDERR "${file}:$.: warning: " .
5cb5c31c 2537 "Excess $decl_type member " .
a1d94aa5
RD		 2538 "'$sects[$sx]' " .
2539 "description in '$decl_name'\n";
2540 ++$warnings;
2541 }
2542 }
2543 }
2544 }
2545}
2546
4092bac7
YB		 2547##
2548# Checks the section describing the return value of a function.
2549sub check_return_section {
2550 my $file = shift;
2551 my $declaration_name = shift;
2552 my $return_type = shift;
2553
2554 # Ignore an empty return type (It's a macro)
2555 # Ignore functions with a "void" return type. (But don't ignore "void *")
2556 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2557 return;
2558 }
2559
2560 if (!defined($sections{$section_return}) ||
2561 $sections{$section_return} eq "") {
d40e1e65 2562 print STDERR "${file}:$.: warning: " .
4092bac7
YB		 2563 "No description found for return value of " .
2564 "'$declaration_name'\n";
2565 ++$warnings;
2566 }
2567}
2568
1da177e4
LT		 2569##
2570# takes a function prototype and the name of the current file being
2571# processed and spits out all the details stored in the global
2572# arrays/hashes.
2573sub dump_function($$) {
2574 my $prototype = shift;
2575 my $file = shift;
cbb4d3e6 2576 my $noret = 0;
1da177e4
LT		 2577
2578 $prototype =~ s/^static +//;
2579 $prototype =~ s/^extern +//;
4dc3b16b 2580 $prototype =~ s/^asmlinkage +//;
1da177e4
LT		 2581 $prototype =~ s/^inline +//;
2582 $prototype =~ s/^__inline__ +//;
32e79401
RD		 2583 $prototype =~ s/^__inline +//;
2584 $prototype =~ s/^__always_inline +//;
2585 $prototype =~ s/^noinline +//;
74fc5c65 2586 $prototype =~ s/__init +//;
20072205 2587 $prototype =~ s/__init_or_module +//;
270a0096 2588 $prototype =~ s/__meminit +//;
70c95b00 2589 $prototype =~ s/__must_check +//;
0df7c0e3 2590 $prototype =~ s/__weak +//;
cbb4d3e6 2591 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
b1aaa546
PB		 2592 $prototype =~ s/__attribute__\s*\(\(
2593 (?:
2594 [\w\s]++ # attribute name
2595 (?:\([^)]*+\))? # attribute arguments
2596 \s*+,? # optional comma at the end
2597 )+
2598 \)\)\s+//x;
1da177e4
LT		 2599
2600 # Yes, this truly is vile. We are looking for:
2601 # 1. Return type (may be nothing if we're looking at a macro)
2602 # 2. Function name
2603 # 3. Function parameters.
2604 #
2605 # All the while we have to watch out for function pointer parameters
2606 # (which IIRC is what the two sections are for), C types (these
2607 # regexps don't even start to express all the possibilities), and
2608 # so on.
2609 #
2610 # If you mess with these regexps, it's a good idea to check that
2611 # the following functions' documentation still comes out right:
2612 # - parport_register_device (function pointer parameters)
2613 # - atomic_set (macro)
9598f91f 2614 # - pci_match_device, __copy_to_user (long return type)
1da177e4 2615
cbb4d3e6
HG		 2616 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2617 # This is an object-like macro, it has no return type and no parameter
2618 # list.
2619 # Function-like macros are not allowed to have spaces between
2620 # declaration_name and opening parenthesis (notice the \s+).
2621 $return_type = $1;
2622 $declaration_name = $2;
2623 $noret = 1;
2624 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2625 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
5a0bc578 2626 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2627 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
94b3e03c 2628 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2629 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
5a0bc578 2630 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4
LT		 2631 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2632 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2633 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1da177e4 2634 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2635 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1da177e4 2636 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2637 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
9598f91f 2638 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578
MW		 2639 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2640 $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1da177e4
LT		 2641 $return_type = $1;
2642 $declaration_name = $2;
2643 my $args = $3;
2644
2645 create_parameterlist($args, ',', $file);
2646 } else {
d40e1e65 2647 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1da177e4
LT		 2648 return;
2649 }
2650
a1d94aa5
RD		 2651 my $prms = join " ", @parameterlist;
2652 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2653
4092bac7
YB		 2654 # This check emits a lot of warnings at the moment, because many
2655 # functions don't have a 'Return' doc section. So until the number
2656 # of warnings goes sufficiently down, the check is only performed in
2657 # verbose mode.
2658 # TODO: always perform the check.
cbb4d3e6 2659 if ($verbose && !$noret) {
4092bac7
YB		 2660 check_return_section($file, $declaration_name, $return_type);
2661 }
2662
3c3b809e 2663 output_declaration($declaration_name,
1da177e4
LT		 2664 'function',
2665 {'function' => $declaration_name,
2666 'module' => $modulename,
2667 'functiontype' => $return_type,
2668 'parameterlist' => \@parameterlist,
2669 'parameterdescs' => \%parameterdescs,
2670 'parametertypes' => \%parametertypes,
2671 'sectionlist' => \@sectionlist,
2672 'sections' => \%sections,
2673 'purpose' => $declaration_purpose
2674 });
2675}
2676
1da177e4
LT		 2677sub reset_state {
2678 $function = "";
1da177e4
LT		 2679 %parameterdescs = ();
2680 %parametertypes = ();
2681 @parameterlist = ();
2682 %sections = ();
2683 @sectionlist = ();
a1d94aa5
RD		 2684 $sectcheck = "";
2685 $struct_actual = "";
1da177e4 2686 $prototype = "";
3c3b809e 2687
48af606a
JN		 2688 $state = STATE_NORMAL;
2689 $inline_doc_state = STATE_INLINE_NA;
1da177e4
LT		 2690}
2691
56afb0f8
JB		 2692sub tracepoint_munge($) {
2693 my $file = shift;
2694 my $tracepointname = 0;
2695 my $tracepointargs = 0;
2696
3a9089fd 2697 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
56afb0f8
JB		 2698 $tracepointname = $1;
2699 }
3a9089fd
JB		 2700 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2701 $tracepointname = $1;
2702 }
2703 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2704 $tracepointname = $2;
2705 }
2706 $tracepointname =~ s/^\s+//; #strip leading whitespace
2707 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
56afb0f8
JB		 2708 $tracepointargs = $1;
2709 }
2710 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
d40e1e65 2711 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
56afb0f8
JB		 2712 "$prototype\n";
2713 } else {
2714 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2715 }
2716}
2717
b4870bc5
RD		 2718sub syscall_munge() {
2719 my $void = 0;
2720
2721 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2722## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2723 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2724 $void = 1;
2725## $prototype = "long sys_$1(void)";
2726 }
2727
2728 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2729 if ($prototype =~ m/long (sys_.*?),/) {
2730 $prototype =~ s/,/\(/;
2731 } elsif ($void) {
2732 $prototype =~ s/\)/\(void\)/;
2733 }
2734
2735 # now delete all of the odd-number commas in $prototype
2736 # so that arg types & arg names don't have a comma between them
2737 my $count = 0;
2738 my $len = length($prototype);
2739 if ($void) {
2740 $len = 0; # skip the for-loop
2741 }
2742 for (my $ix = 0; $ix < $len; $ix++) {
2743 if (substr($prototype, $ix, 1) eq ',') {
2744 $count++;
2745 if ($count % 2 == 1) {
2746 substr($prototype, $ix, 1) = ' ';
2747 }
2748 }
2749 }
2750}
2751
b7afa92b 2752sub process_proto_function($$) {
1da177e4
LT		 2753 my $x = shift;
2754 my $file = shift;
2755
51f5a0c8
RD		 2756 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2757
890c78c2 2758 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1da177e4
LT		 2759 # do nothing
2760 }
2761 elsif ($x =~ /([^\{]*)/) {
3c308798 2762 $prototype .= $1;
1da177e4 2763 }
b4870bc5 2764
890c78c2 2765 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
3c308798 2766 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4
LT		 2767 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2768 $prototype =~ s@^\s+@@gos; # strip leading spaces
b4870bc5
RD		 2769 if ($prototype =~ /SYSCALL_DEFINE/) {
2770 syscall_munge();
2771 }
3a9089fd
JB		 2772 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2773 $prototype =~ /DEFINE_SINGLE_EVENT/)
2774 {
56afb0f8
JB		 2775 tracepoint_munge($file);
2776 }
b4870bc5 2777 dump_function($prototype, $file);
1da177e4
LT		 2778 reset_state();
2779 }
2780}
2781
b7afa92b 2782sub process_proto_type($$) {
1da177e4
LT		 2783 my $x = shift;
2784 my $file = shift;
2785
1da177e4
LT		 2786 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2787 $x =~ s@^\s+@@gos; # strip leading spaces
2788 $x =~ s@\s+$@@gos; # strip trailing spaces
51f5a0c8
RD		 2789 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2790
1da177e4
LT		 2791 if ($x =~ /^#/) {
2792 # To distinguish preprocessor directive from regular declaration later.
2793 $x .= ";";
2794 }
2795
2796 while (1) {
3c308798 2797 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
463a0fdc
MH		 2798 if( length $prototype ) {
2799 $prototype .= " "
2800 }
1da177e4
LT		 2801 $prototype .= $1 . $2;
2802 ($2 eq '{') && $brcount++;
2803 ($2 eq '}') && $brcount--;
2804 if (($2 eq ';') && ($brcount == 0)) {
b9d97328 2805 dump_declaration($prototype, $file);
1da177e4 2806 reset_state();
3c308798 2807 last;
1da177e4
LT		 2808 }
2809 $x = $3;
3c308798 2810 } else {
1da177e4
LT		 2811 $prototype .= $x;
2812 last;
2813 }
2814 }
2815}
2816
6b5b55f6
RD		 2817# xml_escape: replace <, >, and & in the text stream;
2818#
2819# however, formatting controls that are generated internally/locally in the
2820# kernel-doc script are not escaped here; instead, they begin life like
2821# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2822# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2823# just before actual output; (this is done by local_unescape())
1da177e4
LT		 2824sub xml_escape($) {
2825 my $text = shift;
ecfb251a
RD		 2826 if (($output_mode eq "text") || ($output_mode eq "man")) {
2827 return $text;
2828 }
1da177e4
LT		 2829 $text =~ s/\&/\\\\\\amp;/g;
2830 $text =~ s/\</\\\\\\lt;/g;
2831 $text =~ s/\>/\\\\\\gt;/g;
2832 return $text;
2833}
2834
c0d1b6ee
JC		 2835# xml_unescape: reverse the effects of xml_escape
2836sub xml_unescape($) {
2837 my $text = shift;
2838 if (($output_mode eq "text") || ($output_mode eq "man")) {
2839 return $text;
2840 }
2841 $text =~ s/\\\\\\amp;/\&/g;
2842 $text =~ s/\\\\\\lt;/</g;
2843 $text =~ s/\\\\\\gt;/>/g;
2844 return $text;
2845}
2846
6b5b55f6
RD		 2847# convert local escape strings to html
2848# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2849sub local_unescape($) {
2850 my $text = shift;
2851 if (($output_mode eq "text") || ($output_mode eq "man")) {
2852 return $text;
2853 }
2854 $text =~ s/\\\\\\\\lt:/</g;
2855 $text =~ s/\\\\\\\\gt:/>/g;
2856 return $text;
2857}
2858
1ad560e4 2859sub map_filename($) {
2283a117 2860 my $file;
68f86662 2861 my ($orig_file) = @_;
1da177e4 2862
2283a117 2863 if (defined($ENV{'SRCTREE'})) {
68f86662 2864 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1ad560e4 2865 } else {
68f86662 2866 $file = $orig_file;
2283a117 2867 }
1ad560e4 2868
1da177e4
LT		 2869 if (defined($source_map{$file})) {
2870 $file = $source_map{$file};
2871 }
2872
1ad560e4
JN		 2873 return $file;
2874}
2875
88c2b57d
JN		 2876sub process_export_file($) {
2877 my ($orig_file) = @_;
2878 my $file = map_filename($orig_file);
2879
2880 if (!open(IN,"<$file")) {
2881 print STDERR "Error: Cannot open file $file\n";
2882 ++$errors;
2883 return;
2884 }
2885
2886 while (<IN>) {
2887 if (/$export_symbol/) {
2888 $function_table{$2} = 1;
2889 }
2890 }
2891
2892 close(IN);
2893}
2894
1ad560e4
JN		 2895sub process_file($) {
2896 my $file;
2897 my $identifier;
2898 my $func;
2899 my $descr;
2900 my $in_purpose = 0;
2901 my $initial_section_counter = $section_counter;
2902 my ($orig_file) = @_;
2903 my $leading_space;
2904
2905 $file = map_filename($orig_file);
2906
1da177e4
LT		 2907 if (!open(IN,"<$file")) {
2908 print STDERR "Error: Cannot open file $file\n";
2909 ++$errors;
2910 return;
2911 }
2912
a9e7314b
ID		 2913 $. = 1;
2914
1da177e4
LT		 2915 $section_counter = 0;
2916 while (<IN>) {
65478428
DS		 2917 while (s/\\\s*$//) {
2918 $_ .= <IN>;
2919 }
48af606a 2920 if ($state == STATE_NORMAL) {
1da177e4 2921 if (/$doc_start/o) {
48af606a 2922 $state = STATE_NAME; # next line is always the function name
850622df 2923 $in_doc_sect = 0;
0b0f5f29 2924 $declaration_start_line = $. + 1;
1da177e4 2925 }
48af606a 2926 } elsif ($state == STATE_NAME) {# this line is the function name (always)
1da177e4 2927 if (/$doc_block/o) {
48af606a 2928 $state = STATE_DOCBLOCK;
1da177e4 2929 $contents = "";
0b0f5f29
DV		 2930 $new_start_line = $. + 1;
2931
1da177e4
LT		 2932 if ( $1 eq "" ) {
2933 $section = $section_intro;
2934 } else {
2935 $section = $1;
2936 }
3c308798 2937 }
1da177e4
LT		 2938 elsif (/$doc_decl/o) {
2939 $identifier = $1;
2940 if (/\s*([\w\s]+?)\s*-/) {
2941 $identifier = $1;
2942 }
2943
48af606a 2944 $state = STATE_FIELD;
0b0f5f29
DV		 2945 # if there's no @param blocks need to set up default section
2946 # here
2f4ad40a
JN		 2947 $contents = "";
2948 $section = $section_default;
0b0f5f29 2949 $new_start_line = $. + 1;
1da177e4 2950 if (/-(.*)/) {
51f5a0c8 2951 # strip leading/trailing/multiple spaces
a21217da
RD		 2952 $descr= $1;
2953 $descr =~ s/^\s*//;
2954 $descr =~ s/\s*$//;
12ae6779 2955 $descr =~ s/\s+/ /g;
a21217da 2956 $declaration_purpose = xml_escape($descr);
6423133b 2957 $in_purpose = 1;
1da177e4
LT		 2958 } else {
2959 $declaration_purpose = "";
2960 }
77cc23b8
RD		 2961
2962 if (($declaration_purpose eq "") && $verbose) {
d40e1e65 2963 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
77cc23b8
RD		 2964 print STDERR $_;
2965 ++$warnings;
2966 }
2967
1da177e4
LT		 2968 if ($identifier =~ m/^struct/) {
2969 $decl_type = 'struct';
2970 } elsif ($identifier =~ m/^union/) {
2971 $decl_type = 'union';
2972 } elsif ($identifier =~ m/^enum/) {
2973 $decl_type = 'enum';
2974 } elsif ($identifier =~ m/^typedef/) {
2975 $decl_type = 'typedef';
2976 } else {
2977 $decl_type = 'function';
2978 }
2979
2980 if ($verbose) {
d40e1e65 2981 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
1da177e4
LT		 2982 }
2983 } else {
d40e1e65 2984 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1da177e4
LT		 2985 " - I thought it was a doc line\n";
2986 ++$warnings;
48af606a 2987 $state = STATE_NORMAL;
1da177e4 2988 }
48af606a 2989 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
f624adef 2990 if (/$doc_sect/i) { # case insensitive for supported section names
1da177e4
LT		 2991 $newsection = $1;
2992 $newcontents = $2;
2993
f624adef
JN		 2994 # map the supported section names to the canonical names
2995 if ($newsection =~ m/^description$/i) {
2996 $newsection = $section_default;
2997 } elsif ($newsection =~ m/^context$/i) {
2998 $newsection = $section_context;
2999 } elsif ($newsection =~ m/^returns?$/i) {
3000 $newsection = $section_return;
3001 } elsif ($newsection =~ m/^\@return$/) {
3002 # special: @return is a section, not a param description
3003 $newsection = $section_return;
3004 }
3005
792aa2f2 3006 if (($contents ne "") && ($contents ne "\n")) {
850622df 3007 if (!$in_doc_sect && $verbose) {
d40e1e65 3008 print STDERR "${file}:$.: warning: contents before sections\n";
850622df
RD		 3009 ++$warnings;
3010 }
94dc7ad5 3011 dump_section($file, $section, xml_escape($contents));
1da177e4
LT		 3012 $section = $section_default;
3013 }
3014
850622df 3015 $in_doc_sect = 1;
6423133b 3016 $in_purpose = 0;
1da177e4 3017 $contents = $newcontents;
0b0f5f29 3018 $new_start_line = $.;
0a726301
JN		 3019 while ((substr($contents, 0, 1) eq " ") ||
3020 substr($contents, 0, 1) eq "\t") {
3021 $contents = substr($contents, 1);
3022 }
1da177e4
LT		 3023 if ($contents ne "") {
3024 $contents .= "\n";
3025 }
3026 $section = $newsection;
b7886de4 3027 $leading_space = undef;
1da177e4 3028 } elsif (/$doc_end/) {
4c98ecaf 3029 if (($contents ne "") && ($contents ne "\n")) {
94dc7ad5 3030 dump_section($file, $section, xml_escape($contents));
1da177e4
LT		 3031 $section = $section_default;
3032 $contents = "";
3033 }
46b958eb
RD		 3034 # look for doc_com + <text> + doc_end:
3035 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
d40e1e65 3036 print STDERR "${file}:$.: warning: suspicious ending line: $_";
46b958eb
RD		 3037 ++$warnings;
3038 }
1da177e4
LT		 3039
3040 $prototype = "";
48af606a 3041 $state = STATE_PROTO;
1da177e4 3042 $brcount = 0;
232acbcf 3043# print STDERR "end of doc comment, looking for prototype\n";
1da177e4
LT		 3044 } elsif (/$doc_content/) {
3045 # miguel-style comment kludge, look for blank lines after
3046 # @parameter line to signify start of description
6423133b
JW		 3047 if ($1 eq "") {
3048 if ($section =~ m/^@/ || $section eq $section_context) {
3049 dump_section($file, $section, xml_escape($contents));
3050 $section = $section_default;
3051 $contents = "";
0b0f5f29 3052 $new_start_line = $.;
6423133b
JW		 3053 } else {
3054 $contents .= "\n";
3055 }
3056 $in_purpose = 0;
3057 } elsif ($in_purpose == 1) {
3058 # Continued declaration purpose
3059 chomp($declaration_purpose);
3060 $declaration_purpose .= " " . xml_escape($1);
12ae6779 3061 $declaration_purpose =~ s/\s+/ /g;
1da177e4 3062 } else {
b7886de4
JN		 3063 my $cont = $1;
3064 if ($section =~ m/^@/ || $section eq $section_context) {
3065 if (!defined $leading_space) {
3066 if ($cont =~ m/^(\s+)/) {
3067 $leading_space = $1;
3068 } else {
3069 $leading_space = "";
3070 }
3071 }
3072
3073 $cont =~ s/^$leading_space//;
3074 }
3075 $contents .= $cont . "\n";
1da177e4
LT		 3076 }
3077 } else {
3078 # i dont know - bad line? ignore.
d40e1e65 3079 print STDERR "${file}:$.: warning: bad line: $_";
1da177e4
LT		 3080 ++$warnings;
3081 }
48af606a 3082 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
a4c6ebed 3083 # First line (state 1) needs to be a @parameter
48af606a 3084 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
a4c6ebed
DCLP		 3085 $section = $1;
3086 $contents = $2;
0b0f5f29 3087 $new_start_line = $.;
a4c6ebed
DCLP		 3088 if ($contents ne "") {
3089 while ((substr($contents, 0, 1) eq " ") ||
3090 substr($contents, 0, 1) eq "\t") {
3091 $contents = substr($contents, 1);
3092 }
a0b96c2d 3093 $contents .= "\n";
a4c6ebed 3094 }
48af606a 3095 $inline_doc_state = STATE_INLINE_TEXT;
a4c6ebed 3096 # Documentation block end */
48af606a 3097 } elsif (/$doc_inline_end/) {
a4c6ebed
DCLP		 3098 if (($contents ne "") && ($contents ne "\n")) {
3099 dump_section($file, $section, xml_escape($contents));
3100 $section = $section_default;
3101 $contents = "";
3102 }
48af606a
JN		 3103 $state = STATE_PROTO;
3104 $inline_doc_state = STATE_INLINE_NA;
a4c6ebed
DCLP		 3105 # Regular text
3106 } elsif (/$doc_content/) {
48af606a 3107 if ($inline_doc_state == STATE_INLINE_TEXT) {
a4c6ebed 3108 $contents .= $1 . "\n";
6450c895
JN		 3109 # nuke leading blank lines
3110 if ($contents =~ /^\s*$/) {
3111 $contents = "";
3112 }
48af606a
JN		 3113 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
3114 $inline_doc_state = STATE_INLINE_ERROR;
e7ca311e 3115 print STDERR "${file}:$.: warning: ";
a4c6ebed
DCLP		 3116 print STDERR "Incorrect use of kernel-doc format: $_";
3117 ++$warnings;
3118 }
3119 }
48af606a 3120 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
0c9aa209
JN		 3121 if (/$doc_inline_oneline/) {
3122 $section = $1;
3123 $contents = $2;
3124 if ($contents ne "") {
3125 $contents .= "\n";
3126 dump_section($file, $section, xml_escape($contents));
3127 $section = $section_default;
3128 $contents = "";
3129 }
3130 } elsif (/$doc_inline_start/) {
48af606a
JN		 3131 $state = STATE_INLINE;
3132 $inline_doc_state = STATE_INLINE_NAME;
a4c6ebed 3133 } elsif ($decl_type eq 'function') {
b7afa92b 3134 process_proto_function($_, $file);
1da177e4 3135 } else {
b7afa92b 3136 process_proto_type($_, $file);
1da177e4 3137 }
48af606a 3138 } elsif ($state == STATE_DOCBLOCK) {
ebff7f92 3139 if (/$doc_end/)
1da177e4 3140 {
94dc7ad5 3141 dump_doc_section($file, $section, xml_escape($contents));
2f4ad40a 3142 $section = $section_default;
1da177e4
LT		 3143 $contents = "";
3144 $function = "";
1da177e4
LT		 3145 %parameterdescs = ();
3146 %parametertypes = ();
3147 @parameterlist = ();
3148 %sections = ();
3149 @sectionlist = ();
3150 $prototype = "";
48af606a 3151 $state = STATE_NORMAL;
1da177e4
LT		 3152 }
3153 elsif (/$doc_content/)
3154 {
3155 if ( $1 eq "" )
3156 {
3157 $contents .= $blankline;
3158 }
3159 else
3160 {
3161 $contents .= $1 . "\n";
3c3b809e 3162 }
3c308798
RD		 3163 }
3164 }
1da177e4
LT		 3165 }
3166 if ($initial_section_counter == $section_counter) {
3a025e1d
MW		 3167 if ($output_mode ne "none") {
3168 print STDERR "${file}:1: warning: no structured comments found\n";
3169 }
b6c3f456 3170 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
e946c43a
JB		 3171 print STDERR " Was looking for '$_'.\n" for keys %function_table;
3172 }
1da177e4
LT		 3173 if ($output_mode eq "xml") {
3174 # The template wants at least one RefEntry here; make one.
3175 print "<refentry>\n";
3176 print " <refnamediv>\n";
3177 print " <refname>\n";
68f86662 3178 print " ${orig_file}\n";
1da177e4
LT		 3179 print " </refname>\n";
3180 print " <refpurpose>\n";
3181 print " Document generation inconsistency\n";
3182 print " </refpurpose>\n";
3183 print " </refnamediv>\n";
3184 print " <refsect1>\n";
3185 print " <title>\n";
3186 print " Oops\n";
3187 print " </title>\n";
3188 print " <warning>\n";
3189 print " <para>\n";
3190 print " The template for this document tried to insert\n";
3191 print " the structured comment from the file\n";
68f86662 3192 print " <filename>${orig_file}</filename> at this point,\n";
1da177e4
LT		 3193 print " but none was found.\n";
3194 print " This dummy section is inserted to allow\n";
3195 print " generation to continue.\n";
3196 print " </para>\n";
3197 print " </warning>\n";
3198 print " </refsect1>\n";
3199 print "</refentry>\n";
3200 }
3201 }
3202}
8484baaa
RD		 3203
3204
3205$kernelversion = get_kernel_version();
3206
3207# generate a sequence of code that will splice in highlighting information
3208# using the s// operator.
1ef06233 3209for (my $k = 0; $k < @highlights; $k++) {
4d732701
DCLP		 3210 my $pattern = $highlights[$k][0];
3211 my $result = $highlights[$k][1];
3212# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3213 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
8484baaa
RD		 3214}
3215
3216# Read the file that maps relative names to absolute names for
3217# separate source and object directories and for shadow trees.
3218if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3219 my ($relname, $absname);
3220 while(<SOURCE_MAP>) {
3221 chop();
3222 ($relname, $absname) = (split())[0..1];
3223 $relname =~ s:^/+::;
3224 $source_map{$relname} = $absname;
3225 }
3226 close(SOURCE_MAP);
3227}
3228
88c2b57d
JN		 3229if ($output_selection == OUTPUT_EXPORTED ||
3230 $output_selection == OUTPUT_INTERNAL) {
c9b2cfb3
JN		 3231
3232 push(@export_file_list, @ARGV);
3233
88c2b57d
JN		 3234 foreach (@export_file_list) {
3235 chomp;
3236 process_export_file($_);
3237 }
3238}
3239
8484baaa
RD		 3240foreach (@ARGV) {
3241 chomp;
3242 process_file($_);
3243}
3244if ($verbose && $errors) {
3245 print STDERR "$errors errors\n";
3246}
3247if ($verbose && $warnings) {
3248 print STDERR "$warnings warnings\n";
3249}
3250
e814bccb 3251exit($output_mode eq "none" ? 0 : $errors);
ubuntu-bionic-kernel mirror