]> git.proxmox.com Git - mirror_ubuntu-bionic-kernel.git/blame - scripts/kernel-doc
projects / mirror_ubuntu-bionic-kernel.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Linux 4.12-rc1
[mirror_ubuntu-bionic-kernel.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;
aeec46b9 2192
1da177e4 2193 create_parameterlist($members, ';', $file);
a1d94aa5 2194 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
1da177e4
LT		 2195
2196 output_declaration($declaration_name,
2197 'struct',
2198 {'struct' => $declaration_name,
2199 'module' => $modulename,
2200 'parameterlist' => \@parameterlist,
2201 'parameterdescs' => \%parameterdescs,
2202 'parametertypes' => \%parametertypes,
2203 'sectionlist' => \@sectionlist,
2204 'sections' => \%sections,
2205 'purpose' => $declaration_purpose,
2206 'type' => $decl_type
2207 });
2208 }
2209 else {
d40e1e65 2210 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1da177e4
LT		 2211 ++$errors;
2212 }
2213}
2214
2215sub dump_enum($$) {
2216 my $x = shift;
2217 my $file = shift;
2218
aeec46b9 2219 $x =~ s@/\*.*?\*/@@gos; # strip comments.
4468e21e
CN		 2220 # strip #define macros inside enums
2221 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
b6d676db 2222
1da177e4 2223 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
3c308798
RD		 2224 $declaration_name = $1;
2225 my $members = $2;
1da177e4
LT		 2226
2227 foreach my $arg (split ',', $members) {
2228 $arg =~ s/^\s*(\w+).*/$1/;
2229 push @parameterlist, $arg;
2230 if (!$parameterdescs{$arg}) {
3c308798 2231 $parameterdescs{$arg} = $undescribed;
d40e1e65 2232 print STDERR "${file}:$.: warning: Enum value '$arg' ".
1da177e4
LT		 2233 "not described in enum '$declaration_name'\n";
2234 }
2235
2236 }
3c3b809e 2237
1da177e4
LT		 2238 output_declaration($declaration_name,
2239 'enum',
2240 {'enum' => $declaration_name,
2241 'module' => $modulename,
2242 'parameterlist' => \@parameterlist,
2243 'parameterdescs' => \%parameterdescs,
2244 'sectionlist' => \@sectionlist,
2245 'sections' => \%sections,
2246 'purpose' => $declaration_purpose
2247 });
2248 }
2249 else {
d40e1e65 2250 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1da177e4
LT		 2251 ++$errors;
2252 }
2253}
2254
2255sub dump_typedef($$) {
2256 my $x = shift;
2257 my $file = shift;
2258
aeec46b9 2259 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4 2260
83766452 2261 # Parse function prototypes
d37c43ce
MCC		 2262 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
2263 $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
2264
83766452
MCC		 2265 # Function typedefs
2266 $return_type = $1;
2267 $declaration_name = $2;
2268 my $args = $3;
2269
2270 create_parameterlist($args, ',', $file);
1da177e4
LT		 2271
2272 output_declaration($declaration_name,
83766452
MCC		 2273 'function',
2274 {'function' => $declaration_name,
82801d06 2275 'typedef' => 1,
1da177e4 2276 'module' => $modulename,
83766452
MCC		 2277 'functiontype' => $return_type,
2278 'parameterlist' => \@parameterlist,
2279 'parameterdescs' => \%parameterdescs,
2280 'parametertypes' => \%parametertypes,
1da177e4
LT		 2281 'sectionlist' => \@sectionlist,
2282 'sections' => \%sections,
2283 'purpose' => $declaration_purpose
2284 });
83766452
MCC		 2285 return;
2286 }
2287
2288 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2289 $x =~ s/\(*.\)\s*;$/;/;
2290 $x =~ s/\[*.\]\s*;$/;/;
1da177e4 2291 }
83766452
MCC		 2292
2293 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
3a80a766
MCC		 2294 $declaration_name = $1;
2295
2296 output_declaration($declaration_name,
2297 'typedef',
2298 {'typedef' => $declaration_name,
2299 'module' => $modulename,
2300 'sectionlist' => \@sectionlist,
2301 'sections' => \%sections,
2302 'purpose' => $declaration_purpose
2303 });
2304 }
1da177e4 2305 else {
d40e1e65 2306 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
1da177e4
LT		 2307 ++$errors;
2308 }
2309}
2310
a1d94aa5
RD		 2311sub save_struct_actual($) {
2312 my $actual = shift;
2313
2314 # strip all spaces from the actual param so that it looks like one string item
2315 $actual =~ s/\s*//g;
2316 $struct_actual = $struct_actual . $actual . " ";
2317}
2318
1da177e4
LT		 2319sub create_parameterlist($$$) {
2320 my $args = shift;
2321 my $splitter = shift;
2322 my $file = shift;
2323 my $type;
2324 my $param;
2325
a6d3fe77 2326 # temporarily replace commas inside function pointer definition
1da177e4 2327 while ($args =~ /(\([^\),]+),/) {
3c308798 2328 $args =~ s/(\([^\),]+),/$1#/g;
1da177e4 2329 }
3c3b809e 2330
1da177e4
LT		 2331 foreach my $arg (split($splitter, $args)) {
2332 # strip comments
2333 $arg =~ s/\/\*.*\*\///;
3c308798
RD		 2334 # strip leading/trailing spaces
2335 $arg =~ s/^\s*//;
1da177e4
LT		 2336 $arg =~ s/\s*$//;
2337 $arg =~ s/\s+/ /;
2338
2339 if ($arg =~ /^#/) {
2340 # Treat preprocessor directive as a typeless variable just to fill
2341 # corresponding data structures "correctly". Catch it later in
2342 # output_* subs.
2343 push_parameter($arg, "", $file);
00d62961 2344 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1da177e4
LT		 2345 # pointer-to-function
2346 $arg =~ tr/#/,/;
00d62961 2347 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
1da177e4
LT		 2348 $param = $1;
2349 $type = $arg;
00d62961 2350 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
a1d94aa5 2351 save_struct_actual($param);
1da177e4 2352 push_parameter($param, $type, $file);
aeec46b9 2353 } elsif ($arg) {
1da177e4
LT		 2354 $arg =~ s/\s*:\s*/:/g;
2355 $arg =~ s/\s*\[/\[/g;
2356
2357 my @args = split('\s*,\s*', $arg);
2358 if ($args[0] =~ m/\*/) {
2359 $args[0] =~ s/(\*+)\s*/ $1/;
2360 }
884f2810
BP		 2361
2362 my @first_arg;
2363 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2364 shift @args;
2365 push(@first_arg, split('\s+', $1));
2366 push(@first_arg, $2);
2367 } else {
2368 @first_arg = split('\s+', shift @args);
2369 }
2370
1da177e4
LT		 2371 unshift(@args, pop @first_arg);
2372 $type = join " ", @first_arg;
2373
2374 foreach $param (@args) {
2375 if ($param =~ m/^(\*+)\s*(.*)/) {
a1d94aa5 2376 save_struct_actual($2);
1da177e4
LT		 2377 push_parameter($2, "$type $1", $file);
2378 }
2379 elsif ($param =~ m/(.*?):(\d+)/) {
7b97887e 2380 if ($type ne "") { # skip unnamed bit-fields
a1d94aa5 2381 save_struct_actual($1);
7b97887e
RD		 2382 push_parameter($1, "$type:$2", $file)
2383 }
1da177e4
LT		 2384 }
2385 else {
a1d94aa5 2386 save_struct_actual($param);
1da177e4
LT		 2387 push_parameter($param, $type, $file);
2388 }
2389 }
2390 }
2391 }
2392}
2393
2394sub push_parameter($$$) {
2395 my $param = shift;
2396 my $type = shift;
2397 my $file = shift;
2398
5f8c7c98
RD		 2399 if (($anon_struct_union == 1) && ($type eq "") &&
2400 ($param eq "}")) {
2401 return; # ignore the ending }; from anon. struct/union
2402 }
2403
2404 $anon_struct_union = 0;
f9b5c530 2405 $param =~ s/[\[\)].*//;
1da177e4 2406
a6d3fe77 2407 if ($type eq "" && $param =~ /\.\.\.$/)
1da177e4 2408 {
c950a173
SF		 2409 if (!$param =~ /\w\.\.\.$/) {
2410 # handles unnamed variable parameters
2411 $param = "...";
2412 }
ced69090
RD		 2413 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2414 $parameterdescs{$param} = "variable arguments";
2415 }
1da177e4
LT		 2416 }
2417 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2418 {
1da177e4
LT		 2419 $param="void";
2420 $parameterdescs{void} = "no arguments";
2421 }
134fe01b
RD		 2422 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2423 # handle unnamed (anonymous) union or struct:
2424 {
2425 $type = $param;
5f8c7c98 2426 $param = "{unnamed_" . $param . "}";
134fe01b 2427 $parameterdescs{$param} = "anonymous\n";
5f8c7c98 2428 $anon_struct_union = 1;
134fe01b
RD		 2429 }
2430
a6d3fe77 2431 # warn if parameter has no description
134fe01b
RD		 2432 # (but ignore ones starting with # as these are not parameters
2433 # but inline preprocessor statements);
2434 # also ignore unnamed structs/unions;
5f8c7c98 2435 if (!$anon_struct_union) {
f9b5c530 2436 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
a6d3fe77 2437
f9b5c530 2438 $parameterdescs{$param} = $undescribed;
1da177e4
LT		 2439
2440 if (($type eq 'function') || ($type eq 'enum')) {
d40e1e65 2441 print STDERR "${file}:$.: warning: Function parameter ".
1da177e4
LT		 2442 "or member '$param' not " .
2443 "described in '$declaration_name'\n";
2444 }
d40e1e65 2445 print STDERR "${file}:$.: warning:" .
3c308798 2446 " No description found for parameter '$param'\n";
1da177e4 2447 ++$warnings;
3c308798
RD		 2448 }
2449 }
1da177e4 2450
2b35f4d9
RD		 2451 $param = xml_escape($param);
2452
25985edc 2453 # strip spaces from $param so that it is one continuous string
e34e7dbb
RD		 2454 # on @parameterlist;
2455 # this fixes a problem where check_sections() cannot find
2456 # a parameter like "addr[6 + 2]" because it actually appears
2457 # as "addr[6", "+", "2]" on the parameter list;
2458 # but it's better to maintain the param string unchanged for output,
2459 # so just weaken the string compare in check_sections() to ignore
2460 # "[blah" in a parameter string;
2461 ###$param =~ s/\s*//g;
1da177e4 2462 push @parameterlist, $param;
02a4f4fe 2463 $type =~ s/\s\s+/ /g;
1da177e4
LT		 2464 $parametertypes{$param} = $type;
2465}
2466
a1d94aa5
RD		 2467sub check_sections($$$$$$) {
2468 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2469 my @sects = split ' ', $sectcheck;
2470 my @prms = split ' ', $prmscheck;
2471 my $err;
2472 my ($px, $sx);
2473 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2474
2475 foreach $sx (0 .. $#sects) {
2476 $err = 1;
2477 foreach $px (0 .. $#prms) {
2478 $prm_clean = $prms[$px];
2479 $prm_clean =~ s/\[.*\]//;
1f3a6688 2480 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
e34e7dbb
RD		 2481 # ignore array size in a parameter string;
2482 # however, the original param string may contain
2483 # spaces, e.g.: addr[6 + 2]
2484 # and this appears in @prms as "addr[6" since the
2485 # parameter list is split at spaces;
2486 # hence just ignore "[..." for the sections check;
2487 $prm_clean =~ s/\[.*//;
2488
a1d94aa5
RD		 2489 ##$prm_clean =~ s/^\**//;
2490 if ($prm_clean eq $sects[$sx]) {
2491 $err = 0;
2492 last;
2493 }
2494 }
2495 if ($err) {
2496 if ($decl_type eq "function") {
d40e1e65 2497 print STDERR "${file}:$.: warning: " .
a1d94aa5
RD		 2498 "Excess function parameter " .
2499 "'$sects[$sx]' " .
2500 "description in '$decl_name'\n";
2501 ++$warnings;
2502 } else {
2503 if ($nested !~ m/\Q$sects[$sx]\E/) {
d40e1e65 2504 print STDERR "${file}:$.: warning: " .
a1d94aa5
RD		 2505 "Excess struct/union/enum/typedef member " .
2506 "'$sects[$sx]' " .
2507 "description in '$decl_name'\n";
2508 ++$warnings;
2509 }
2510 }
2511 }
2512 }
2513}
2514
4092bac7
YB		 2515##
2516# Checks the section describing the return value of a function.
2517sub check_return_section {
2518 my $file = shift;
2519 my $declaration_name = shift;
2520 my $return_type = shift;
2521
2522 # Ignore an empty return type (It's a macro)
2523 # Ignore functions with a "void" return type. (But don't ignore "void *")
2524 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2525 return;
2526 }
2527
2528 if (!defined($sections{$section_return}) ||
2529 $sections{$section_return} eq "") {
d40e1e65 2530 print STDERR "${file}:$.: warning: " .
4092bac7
YB		 2531 "No description found for return value of " .
2532 "'$declaration_name'\n";
2533 ++$warnings;
2534 }
2535}
2536
1da177e4
LT		 2537##
2538# takes a function prototype and the name of the current file being
2539# processed and spits out all the details stored in the global
2540# arrays/hashes.
2541sub dump_function($$) {
2542 my $prototype = shift;
2543 my $file = shift;
cbb4d3e6 2544 my $noret = 0;
1da177e4
LT		 2545
2546 $prototype =~ s/^static +//;
2547 $prototype =~ s/^extern +//;
4dc3b16b 2548 $prototype =~ s/^asmlinkage +//;
1da177e4
LT		 2549 $prototype =~ s/^inline +//;
2550 $prototype =~ s/^__inline__ +//;
32e79401
RD		 2551 $prototype =~ s/^__inline +//;
2552 $prototype =~ s/^__always_inline +//;
2553 $prototype =~ s/^noinline +//;
74fc5c65 2554 $prototype =~ s/__init +//;
20072205 2555 $prototype =~ s/__init_or_module +//;
270a0096 2556 $prototype =~ s/__meminit +//;
70c95b00 2557 $prototype =~ s/__must_check +//;
0df7c0e3 2558 $prototype =~ s/__weak +//;
cbb4d3e6 2559 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
b1aaa546
PB		 2560 $prototype =~ s/__attribute__\s*\(\(
2561 (?:
2562 [\w\s]++ # attribute name
2563 (?:\([^)]*+\))? # attribute arguments
2564 \s*+,? # optional comma at the end
2565 )+
2566 \)\)\s+//x;
1da177e4
LT		 2567
2568 # Yes, this truly is vile. We are looking for:
2569 # 1. Return type (may be nothing if we're looking at a macro)
2570 # 2. Function name
2571 # 3. Function parameters.
2572 #
2573 # All the while we have to watch out for function pointer parameters
2574 # (which IIRC is what the two sections are for), C types (these
2575 # regexps don't even start to express all the possibilities), and
2576 # so on.
2577 #
2578 # If you mess with these regexps, it's a good idea to check that
2579 # the following functions' documentation still comes out right:
2580 # - parport_register_device (function pointer parameters)
2581 # - atomic_set (macro)
9598f91f 2582 # - pci_match_device, __copy_to_user (long return type)
1da177e4 2583
cbb4d3e6
HG		 2584 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2585 # This is an object-like macro, it has no return type and no parameter
2586 # list.
2587 # Function-like macros are not allowed to have spaces between
2588 # declaration_name and opening parenthesis (notice the \s+).
2589 $return_type = $1;
2590 $declaration_name = $2;
2591 $noret = 1;
2592 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2593 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
5a0bc578 2594 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2595 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
94b3e03c 2596 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4 2597 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
5a0bc578 2598 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1da177e4
LT		 2599 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2600 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2601 $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1da177e4 2602 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2603 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1da177e4 2604 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578 2605 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
9598f91f 2606 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
5a0bc578
MW		 2607 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2608 $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1da177e4
LT		 2609 $return_type = $1;
2610 $declaration_name = $2;
2611 my $args = $3;
2612
2613 create_parameterlist($args, ',', $file);
2614 } else {
d40e1e65 2615 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1da177e4
LT		 2616 return;
2617 }
2618
a1d94aa5
RD		 2619 my $prms = join " ", @parameterlist;
2620 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2621
4092bac7
YB		 2622 # This check emits a lot of warnings at the moment, because many
2623 # functions don't have a 'Return' doc section. So until the number
2624 # of warnings goes sufficiently down, the check is only performed in
2625 # verbose mode.
2626 # TODO: always perform the check.
cbb4d3e6 2627 if ($verbose && !$noret) {
4092bac7
YB		 2628 check_return_section($file, $declaration_name, $return_type);
2629 }
2630
3c3b809e 2631 output_declaration($declaration_name,
1da177e4
LT		 2632 'function',
2633 {'function' => $declaration_name,
2634 'module' => $modulename,
2635 'functiontype' => $return_type,
2636 'parameterlist' => \@parameterlist,
2637 'parameterdescs' => \%parameterdescs,
2638 'parametertypes' => \%parametertypes,
2639 'sectionlist' => \@sectionlist,
2640 'sections' => \%sections,
2641 'purpose' => $declaration_purpose
2642 });
2643}
2644
1da177e4
LT		 2645sub reset_state {
2646 $function = "";
1da177e4
LT		 2647 %parameterdescs = ();
2648 %parametertypes = ();
2649 @parameterlist = ();
2650 %sections = ();
2651 @sectionlist = ();
a1d94aa5
RD		 2652 $sectcheck = "";
2653 $struct_actual = "";
1da177e4 2654 $prototype = "";
3c3b809e 2655
48af606a
JN		 2656 $state = STATE_NORMAL;
2657 $inline_doc_state = STATE_INLINE_NA;
1da177e4
LT		 2658}
2659
56afb0f8
JB		 2660sub tracepoint_munge($) {
2661 my $file = shift;
2662 my $tracepointname = 0;
2663 my $tracepointargs = 0;
2664
3a9089fd 2665 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
56afb0f8
JB		 2666 $tracepointname = $1;
2667 }
3a9089fd
JB		 2668 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2669 $tracepointname = $1;
2670 }
2671 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2672 $tracepointname = $2;
2673 }
2674 $tracepointname =~ s/^\s+//; #strip leading whitespace
2675 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
56afb0f8
JB		 2676 $tracepointargs = $1;
2677 }
2678 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
d40e1e65 2679 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
56afb0f8
JB		 2680 "$prototype\n";
2681 } else {
2682 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2683 }
2684}
2685
b4870bc5
RD		 2686sub syscall_munge() {
2687 my $void = 0;
2688
2689 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2690## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2691 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2692 $void = 1;
2693## $prototype = "long sys_$1(void)";
2694 }
2695
2696 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2697 if ($prototype =~ m/long (sys_.*?),/) {
2698 $prototype =~ s/,/\(/;
2699 } elsif ($void) {
2700 $prototype =~ s/\)/\(void\)/;
2701 }
2702
2703 # now delete all of the odd-number commas in $prototype
2704 # so that arg types & arg names don't have a comma between them
2705 my $count = 0;
2706 my $len = length($prototype);
2707 if ($void) {
2708 $len = 0; # skip the for-loop
2709 }
2710 for (my $ix = 0; $ix < $len; $ix++) {
2711 if (substr($prototype, $ix, 1) eq ',') {
2712 $count++;
2713 if ($count % 2 == 1) {
2714 substr($prototype, $ix, 1) = ' ';
2715 }
2716 }
2717 }
2718}
2719
b7afa92b 2720sub process_proto_function($$) {
1da177e4
LT		 2721 my $x = shift;
2722 my $file = shift;
2723
51f5a0c8
RD		 2724 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2725
890c78c2 2726 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1da177e4
LT		 2727 # do nothing
2728 }
2729 elsif ($x =~ /([^\{]*)/) {
3c308798 2730 $prototype .= $1;
1da177e4 2731 }
b4870bc5 2732
890c78c2 2733 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
3c308798 2734 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4
LT		 2735 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2736 $prototype =~ s@^\s+@@gos; # strip leading spaces
b4870bc5
RD		 2737 if ($prototype =~ /SYSCALL_DEFINE/) {
2738 syscall_munge();
2739 }
3a9089fd
JB		 2740 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2741 $prototype =~ /DEFINE_SINGLE_EVENT/)
2742 {
56afb0f8
JB		 2743 tracepoint_munge($file);
2744 }
b4870bc5 2745 dump_function($prototype, $file);
1da177e4
LT		 2746 reset_state();
2747 }
2748}
2749
b7afa92b 2750sub process_proto_type($$) {
1da177e4
LT		 2751 my $x = shift;
2752 my $file = shift;
2753
1da177e4
LT		 2754 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2755 $x =~ s@^\s+@@gos; # strip leading spaces
2756 $x =~ s@\s+$@@gos; # strip trailing spaces
51f5a0c8
RD		 2757 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2758
1da177e4
LT		 2759 if ($x =~ /^#/) {
2760 # To distinguish preprocessor directive from regular declaration later.
2761 $x .= ";";
2762 }
2763
2764 while (1) {
3c308798 2765 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1da177e4
LT		 2766 $prototype .= $1 . $2;
2767 ($2 eq '{') && $brcount++;
2768 ($2 eq '}') && $brcount--;
2769 if (($2 eq ';') && ($brcount == 0)) {
b9d97328 2770 dump_declaration($prototype, $file);
1da177e4 2771 reset_state();
3c308798 2772 last;
1da177e4
LT		 2773 }
2774 $x = $3;
3c308798 2775 } else {
1da177e4
LT		 2776 $prototype .= $x;
2777 last;
2778 }
2779 }
2780}
2781
6b5b55f6
RD		 2782# xml_escape: replace <, >, and & in the text stream;
2783#
2784# however, formatting controls that are generated internally/locally in the
2785# kernel-doc script are not escaped here; instead, they begin life like
2786# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2787# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2788# just before actual output; (this is done by local_unescape())
1da177e4
LT		 2789sub xml_escape($) {
2790 my $text = shift;
ecfb251a
RD		 2791 if (($output_mode eq "text") || ($output_mode eq "man")) {
2792 return $text;
2793 }
1da177e4
LT		 2794 $text =~ s/\&/\\\\\\amp;/g;
2795 $text =~ s/\</\\\\\\lt;/g;
2796 $text =~ s/\>/\\\\\\gt;/g;
2797 return $text;
2798}
2799
c0d1b6ee
JC		 2800# xml_unescape: reverse the effects of xml_escape
2801sub xml_unescape($) {
2802 my $text = shift;
2803 if (($output_mode eq "text") || ($output_mode eq "man")) {
2804 return $text;
2805 }
2806 $text =~ s/\\\\\\amp;/\&/g;
2807 $text =~ s/\\\\\\lt;/</g;
2808 $text =~ s/\\\\\\gt;/>/g;
2809 return $text;
2810}
2811
6b5b55f6
RD		 2812# convert local escape strings to html
2813# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2814sub local_unescape($) {
2815 my $text = shift;
2816 if (($output_mode eq "text") || ($output_mode eq "man")) {
2817 return $text;
2818 }
2819 $text =~ s/\\\\\\\\lt:/</g;
2820 $text =~ s/\\\\\\\\gt:/>/g;
2821 return $text;
2822}
2823
1ad560e4 2824sub map_filename($) {
2283a117 2825 my $file;
68f86662 2826 my ($orig_file) = @_;
1da177e4 2827
2283a117 2828 if (defined($ENV{'SRCTREE'})) {
68f86662 2829 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1ad560e4 2830 } else {
68f86662 2831 $file = $orig_file;
2283a117 2832 }
1ad560e4 2833
1da177e4
LT		 2834 if (defined($source_map{$file})) {
2835 $file = $source_map{$file};
2836 }
2837
1ad560e4
JN		 2838 return $file;
2839}
2840
88c2b57d
JN		 2841sub process_export_file($) {
2842 my ($orig_file) = @_;
2843 my $file = map_filename($orig_file);
2844
2845 if (!open(IN,"<$file")) {
2846 print STDERR "Error: Cannot open file $file\n";
2847 ++$errors;
2848 return;
2849 }
2850
2851 while (<IN>) {
2852 if (/$export_symbol/) {
2853 $function_table{$2} = 1;
2854 }
2855 }
2856
2857 close(IN);
2858}
2859
1ad560e4
JN		 2860sub process_file($) {
2861 my $file;
2862 my $identifier;
2863 my $func;
2864 my $descr;
2865 my $in_purpose = 0;
2866 my $initial_section_counter = $section_counter;
2867 my ($orig_file) = @_;
2868 my $leading_space;
2869
2870 $file = map_filename($orig_file);
2871
1da177e4
LT		 2872 if (!open(IN,"<$file")) {
2873 print STDERR "Error: Cannot open file $file\n";
2874 ++$errors;
2875 return;
2876 }
2877
a9e7314b
ID		 2878 $. = 1;
2879
1da177e4
LT		 2880 $section_counter = 0;
2881 while (<IN>) {
65478428
DS		 2882 while (s/\\\s*$//) {
2883 $_ .= <IN>;
2884 }
48af606a 2885 if ($state == STATE_NORMAL) {
1da177e4 2886 if (/$doc_start/o) {
48af606a 2887 $state = STATE_NAME; # next line is always the function name
850622df 2888 $in_doc_sect = 0;
0b0f5f29 2889 $declaration_start_line = $. + 1;
1da177e4 2890 }
48af606a 2891 } elsif ($state == STATE_NAME) {# this line is the function name (always)
1da177e4 2892 if (/$doc_block/o) {
48af606a 2893 $state = STATE_DOCBLOCK;
1da177e4 2894 $contents = "";
0b0f5f29
DV		 2895 $new_start_line = $. + 1;
2896
1da177e4
LT		 2897 if ( $1 eq "" ) {
2898 $section = $section_intro;
2899 } else {
2900 $section = $1;
2901 }
3c308798 2902 }
1da177e4
LT		 2903 elsif (/$doc_decl/o) {
2904 $identifier = $1;
2905 if (/\s*([\w\s]+?)\s*-/) {
2906 $identifier = $1;
2907 }
2908
48af606a 2909 $state = STATE_FIELD;
0b0f5f29
DV		 2910 # if there's no @param blocks need to set up default section
2911 # here
2f4ad40a
JN		 2912 $contents = "";
2913 $section = $section_default;
0b0f5f29 2914 $new_start_line = $. + 1;
1da177e4 2915 if (/-(.*)/) {
51f5a0c8 2916 # strip leading/trailing/multiple spaces
a21217da
RD		 2917 $descr= $1;
2918 $descr =~ s/^\s*//;
2919 $descr =~ s/\s*$//;
12ae6779 2920 $descr =~ s/\s+/ /g;
a21217da 2921 $declaration_purpose = xml_escape($descr);
6423133b 2922 $in_purpose = 1;
1da177e4
LT		 2923 } else {
2924 $declaration_purpose = "";
2925 }
77cc23b8
RD		 2926
2927 if (($declaration_purpose eq "") && $verbose) {
d40e1e65 2928 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
77cc23b8
RD		 2929 print STDERR $_;
2930 ++$warnings;
2931 }
2932
1da177e4
LT		 2933 if ($identifier =~ m/^struct/) {
2934 $decl_type = 'struct';
2935 } elsif ($identifier =~ m/^union/) {
2936 $decl_type = 'union';
2937 } elsif ($identifier =~ m/^enum/) {
2938 $decl_type = 'enum';
2939 } elsif ($identifier =~ m/^typedef/) {
2940 $decl_type = 'typedef';
2941 } else {
2942 $decl_type = 'function';
2943 }
2944
2945 if ($verbose) {
d40e1e65 2946 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
1da177e4
LT		 2947 }
2948 } else {
d40e1e65 2949 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1da177e4
LT		 2950 " - I thought it was a doc line\n";
2951 ++$warnings;
48af606a 2952 $state = STATE_NORMAL;
1da177e4 2953 }
48af606a 2954 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
f624adef 2955 if (/$doc_sect/i) { # case insensitive for supported section names
1da177e4
LT		 2956 $newsection = $1;
2957 $newcontents = $2;
2958
f624adef
JN		 2959 # map the supported section names to the canonical names
2960 if ($newsection =~ m/^description$/i) {
2961 $newsection = $section_default;
2962 } elsif ($newsection =~ m/^context$/i) {
2963 $newsection = $section_context;
2964 } elsif ($newsection =~ m/^returns?$/i) {
2965 $newsection = $section_return;
2966 } elsif ($newsection =~ m/^\@return$/) {
2967 # special: @return is a section, not a param description
2968 $newsection = $section_return;
2969 }
2970
792aa2f2 2971 if (($contents ne "") && ($contents ne "\n")) {
850622df 2972 if (!$in_doc_sect && $verbose) {
d40e1e65 2973 print STDERR "${file}:$.: warning: contents before sections\n";
850622df
RD		 2974 ++$warnings;
2975 }
94dc7ad5 2976 dump_section($file, $section, xml_escape($contents));
1da177e4
LT		 2977 $section = $section_default;
2978 }
2979
850622df 2980 $in_doc_sect = 1;
6423133b 2981 $in_purpose = 0;
1da177e4 2982 $contents = $newcontents;
0b0f5f29 2983 $new_start_line = $.;
0a726301
JN		 2984 while ((substr($contents, 0, 1) eq " ") ||
2985 substr($contents, 0, 1) eq "\t") {
2986 $contents = substr($contents, 1);
2987 }
1da177e4
LT		 2988 if ($contents ne "") {
2989 $contents .= "\n";
2990 }
2991 $section = $newsection;
b7886de4 2992 $leading_space = undef;
1da177e4 2993 } elsif (/$doc_end/) {
4c98ecaf 2994 if (($contents ne "") && ($contents ne "\n")) {
94dc7ad5 2995 dump_section($file, $section, xml_escape($contents));
1da177e4
LT		 2996 $section = $section_default;
2997 $contents = "";
2998 }
46b958eb
RD		 2999 # look for doc_com + <text> + doc_end:
3000 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
d40e1e65 3001 print STDERR "${file}:$.: warning: suspicious ending line: $_";
46b958eb
RD		 3002 ++$warnings;
3003 }
1da177e4
LT		 3004
3005 $prototype = "";
48af606a 3006 $state = STATE_PROTO;
1da177e4 3007 $brcount = 0;
232acbcf 3008# print STDERR "end of doc comment, looking for prototype\n";
1da177e4
LT		 3009 } elsif (/$doc_content/) {
3010 # miguel-style comment kludge, look for blank lines after
3011 # @parameter line to signify start of description
6423133b
JW		 3012 if ($1 eq "") {
3013 if ($section =~ m/^@/ || $section eq $section_context) {
3014 dump_section($file, $section, xml_escape($contents));
3015 $section = $section_default;
3016 $contents = "";
0b0f5f29 3017 $new_start_line = $.;
6423133b
JW		 3018 } else {
3019 $contents .= "\n";
3020 }
3021 $in_purpose = 0;
3022 } elsif ($in_purpose == 1) {
3023 # Continued declaration purpose
3024 chomp($declaration_purpose);
3025 $declaration_purpose .= " " . xml_escape($1);
12ae6779 3026 $declaration_purpose =~ s/\s+/ /g;
1da177e4 3027 } else {
b7886de4
JN		 3028 my $cont = $1;
3029 if ($section =~ m/^@/ || $section eq $section_context) {
3030 if (!defined $leading_space) {
3031 if ($cont =~ m/^(\s+)/) {
3032 $leading_space = $1;
3033 } else {
3034 $leading_space = "";
3035 }
3036 }
3037
3038 $cont =~ s/^$leading_space//;
3039 }
3040 $contents .= $cont . "\n";
1da177e4
LT		 3041 }
3042 } else {
3043 # i dont know - bad line? ignore.
d40e1e65 3044 print STDERR "${file}:$.: warning: bad line: $_";
1da177e4
LT		 3045 ++$warnings;
3046 }
48af606a 3047 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
a4c6ebed 3048 # First line (state 1) needs to be a @parameter
48af606a 3049 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
a4c6ebed
DCLP		 3050 $section = $1;
3051 $contents = $2;
0b0f5f29 3052 $new_start_line = $.;
a4c6ebed
DCLP		 3053 if ($contents ne "") {
3054 while ((substr($contents, 0, 1) eq " ") ||
3055 substr($contents, 0, 1) eq "\t") {
3056 $contents = substr($contents, 1);
3057 }
a0b96c2d 3058 $contents .= "\n";
a4c6ebed 3059 }
48af606a 3060 $inline_doc_state = STATE_INLINE_TEXT;
a4c6ebed 3061 # Documentation block end */
48af606a 3062 } elsif (/$doc_inline_end/) {
a4c6ebed
DCLP		 3063 if (($contents ne "") && ($contents ne "\n")) {
3064 dump_section($file, $section, xml_escape($contents));
3065 $section = $section_default;
3066 $contents = "";
3067 }
48af606a
JN		 3068 $state = STATE_PROTO;
3069 $inline_doc_state = STATE_INLINE_NA;
a4c6ebed
DCLP		 3070 # Regular text
3071 } elsif (/$doc_content/) {
48af606a 3072 if ($inline_doc_state == STATE_INLINE_TEXT) {
a4c6ebed 3073 $contents .= $1 . "\n";
6450c895
JN		 3074 # nuke leading blank lines
3075 if ($contents =~ /^\s*$/) {
3076 $contents = "";
3077 }
48af606a
JN		 3078 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
3079 $inline_doc_state = STATE_INLINE_ERROR;
e7ca311e 3080 print STDERR "${file}:$.: warning: ";
a4c6ebed
DCLP		 3081 print STDERR "Incorrect use of kernel-doc format: $_";
3082 ++$warnings;
3083 }
3084 }
48af606a 3085 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
0c9aa209
JN		 3086 if (/$doc_inline_oneline/) {
3087 $section = $1;
3088 $contents = $2;
3089 if ($contents ne "") {
3090 $contents .= "\n";
3091 dump_section($file, $section, xml_escape($contents));
3092 $section = $section_default;
3093 $contents = "";
3094 }
3095 } elsif (/$doc_inline_start/) {
48af606a
JN		 3096 $state = STATE_INLINE;
3097 $inline_doc_state = STATE_INLINE_NAME;
a4c6ebed 3098 } elsif ($decl_type eq 'function') {
b7afa92b 3099 process_proto_function($_, $file);
1da177e4 3100 } else {
b7afa92b 3101 process_proto_type($_, $file);
1da177e4 3102 }
48af606a 3103 } elsif ($state == STATE_DOCBLOCK) {
ebff7f92 3104 if (/$doc_end/)
1da177e4 3105 {
94dc7ad5 3106 dump_doc_section($file, $section, xml_escape($contents));
2f4ad40a 3107 $section = $section_default;
1da177e4
LT		 3108 $contents = "";
3109 $function = "";
1da177e4
LT		 3110 %parameterdescs = ();
3111 %parametertypes = ();
3112 @parameterlist = ();
3113 %sections = ();
3114 @sectionlist = ();
3115 $prototype = "";
48af606a 3116 $state = STATE_NORMAL;
1da177e4
LT		 3117 }
3118 elsif (/$doc_content/)
3119 {
3120 if ( $1 eq "" )
3121 {
3122 $contents .= $blankline;
3123 }
3124 else
3125 {
3126 $contents .= $1 . "\n";
3c3b809e 3127 }
3c308798
RD		 3128 }
3129 }
1da177e4
LT		 3130 }
3131 if ($initial_section_counter == $section_counter) {
d40e1e65 3132 print STDERR "${file}:1: warning: no structured comments found\n";
b6c3f456 3133 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
e946c43a
JB		 3134 print STDERR " Was looking for '$_'.\n" for keys %function_table;
3135 }
1da177e4
LT		 3136 if ($output_mode eq "xml") {
3137 # The template wants at least one RefEntry here; make one.
3138 print "<refentry>\n";
3139 print " <refnamediv>\n";
3140 print " <refname>\n";
68f86662 3141 print " ${orig_file}\n";
1da177e4
LT		 3142 print " </refname>\n";
3143 print " <refpurpose>\n";
3144 print " Document generation inconsistency\n";
3145 print " </refpurpose>\n";
3146 print " </refnamediv>\n";
3147 print " <refsect1>\n";
3148 print " <title>\n";
3149 print " Oops\n";
3150 print " </title>\n";
3151 print " <warning>\n";
3152 print " <para>\n";
3153 print " The template for this document tried to insert\n";
3154 print " the structured comment from the file\n";
68f86662 3155 print " <filename>${orig_file}</filename> at this point,\n";
1da177e4
LT		 3156 print " but none was found.\n";
3157 print " This dummy section is inserted to allow\n";
3158 print " generation to continue.\n";
3159 print " </para>\n";
3160 print " </warning>\n";
3161 print " </refsect1>\n";
3162 print "</refentry>\n";
3163 }
3164 }
3165}
8484baaa
RD		 3166
3167
3168$kernelversion = get_kernel_version();
3169
3170# generate a sequence of code that will splice in highlighting information
3171# using the s// operator.
1ef06233 3172for (my $k = 0; $k < @highlights; $k++) {
4d732701
DCLP		 3173 my $pattern = $highlights[$k][0];
3174 my $result = $highlights[$k][1];
3175# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3176 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
8484baaa
RD		 3177}
3178
3179# Read the file that maps relative names to absolute names for
3180# separate source and object directories and for shadow trees.
3181if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3182 my ($relname, $absname);
3183 while(<SOURCE_MAP>) {
3184 chop();
3185 ($relname, $absname) = (split())[0..1];
3186 $relname =~ s:^/+::;
3187 $source_map{$relname} = $absname;
3188 }
3189 close(SOURCE_MAP);
3190}
3191
88c2b57d
JN		 3192if ($output_selection == OUTPUT_EXPORTED ||
3193 $output_selection == OUTPUT_INTERNAL) {
c9b2cfb3
JN		 3194
3195 push(@export_file_list, @ARGV);
3196
88c2b57d
JN		 3197 foreach (@export_file_list) {
3198 chomp;
3199 process_export_file($_);
3200 }
3201}
3202
8484baaa
RD		 3203foreach (@ARGV) {
3204 chomp;
3205 process_file($_);
3206}
3207if ($verbose && $errors) {
3208 print STDERR "$errors errors\n";
3209}
3210if ($verbose && $warnings) {
3211 print STDERR "$warnings warnings\n";
3212}
3213
3214exit($errors);
ubuntu-bionic-kernel mirror