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