ublk_drv: add device parameter UBLK_PARAM_TYPE_DEVT
[linux-block.git] / scripts / kernel-doc
CommitLineData
cb77f0d6 1#!/usr/bin/env perl
38476378 2# SPDX-License-Identifier: GPL-2.0
1da177e4 3
cb77f0d6 4use warnings;
1da177e4
LT
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
9## Copyright (C) 2001 Simon Huggins ##
70c95b00 10## Copyright (C) 2005-2012 Randy Dunlap ##
1b40c194 11## Copyright (C) 2012 Dan Luedtke ##
1da177e4
LT
12## ##
13## #define enhancements by Armin Kuster <akuster@mvista.com> ##
14## Copyright (c) 2000 MontaVista Software, Inc. ##
2b306eca
TW
15#
16# Copyright (C) 2022 Tomasz Warniełło (POD)
1da177e4 17
43caf1a6
TW
18use Pod::Usage qw/pod2usage/;
19
a5cdaea5
TW
20=head1 NAME
21
22kernel-doc - Print formatted kernel documentation to stdout
23
24=head1 SYNOPSIS
25
26 kernel-doc [-h] [-v] [-Werror]
27 [ -man |
28 -rst [-sphinx-version VERSION] [-enable-lineno] |
29 -none
30 ]
31 [
32 -export |
33 -internal |
34 [-function NAME] ... |
35 [-nosymbol NAME] ...
36 ]
37 [-no-doc-sections]
38 [-export-file FILE] ...
39 FILE ...
40
41Run `kernel-doc -h` for details.
42
f1583922
TW
43=head1 DESCRIPTION
44
45Read C language source or header FILEs, extract embedded documentation comments,
46and print formatted documentation to standard output.
47
48The documentation comments are identified by the "/**" opening comment mark.
49
50See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
51
a5cdaea5
TW
52=cut
53
2875f787
TW
54# more perldoc at the end of the file
55
8484baaa
RD
56## init lots of data
57
1da177e4
LT
58my $errors = 0;
59my $warnings = 0;
5f8c7c98 60my $anon_struct_union = 0;
1da177e4
LT
61
62# match expressions used to find embedded type information
b97f193a
MCC
63my $type_constant = '\b``([^\`]+)``\b';
64my $type_constant2 = '\%([-_\w]+)';
1da177e4 65my $type_func = '(\w+)\(\)';
bfd228c7 66my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
ee2aa759 67my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
5219f18a 68my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params
346282db 69my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params
1da177e4 70my $type_env = '(\$\w+)';
df31175b
PB
71my $type_enum = '\&(enum\s*([_\w]+))';
72my $type_struct = '\&(struct\s*([_\w]+))';
73my $type_typedef = '\&(typedef\s*([_\w]+))';
74my $type_union = '\&(union\s*([_\w]+))';
5267dd35 75my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
df31175b 76my $type_fallback = '\&([_\w]+)';
f3341dcf 77my $type_member_func = $type_member . '\(\)';
1da177e4
LT
78
79# Output conversion substitutions.
80# One for each output format
81
1da177e4 82# these are pretty rough
4d732701
DCLP
83my @highlights_man = (
84 [$type_constant, "\$1"],
b97f193a 85 [$type_constant2, "\$1"],
4d732701 86 [$type_func, "\\\\fB\$1\\\\fP"],
df31175b 87 [$type_enum, "\\\\fI\$1\\\\fP"],
4d732701 88 [$type_struct, "\\\\fI\$1\\\\fP"],
df31175b
PB
89 [$type_typedef, "\\\\fI\$1\\\\fP"],
90 [$type_union, "\\\\fI\$1\\\\fP"],
5267dd35 91 [$type_param, "\\\\fI\$1\\\\fP"],
ee2aa759 92 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
df31175b
PB
93 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
94 [$type_fallback, "\\\\fI\$1\\\\fP"]
4d732701 95 );
1da177e4
LT
96my $blankline_man = "";
97
c0d1b6ee
JC
98# rst-mode
99my @highlights_rst = (
100 [$type_constant, "``\$1``"],
b97f193a 101 [$type_constant2, "``\$1``"],
f3341dcf 102 # Note: need to escape () to avoid func matching later
5267dd35
PB
103 [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
104 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
5219f18a 105 [$type_fp_param, "**\$1\\\\(\\\\)**"],
346282db 106 [$type_fp_param2, "**\$1\\\\(\\\\)**"],
344fdb28 107 [$type_func, "\$1()"],
df31175b
PB
108 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
109 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
110 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
111 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
a7291e7e 112 # in rst this can refer to any type
df31175b 113 [$type_fallback, "\\:c\\:type\\:`\$1`"],
ee2aa759 114 [$type_param_ref, "**\$1\$2**"]
c0d1b6ee
JC
115 );
116my $blankline_rst = "\n";
117
1da177e4 118# read arguments
b9d97328 119if ($#ARGV == -1) {
43caf1a6
TW
120 pod2usage(
121 -message => "No arguments!\n",
122 -exitval => 1,
123 -verbose => 99,
124 -sections => 'SYNOPSIS',
125 -output => \*STDERR,
126 );
1da177e4
LT
127}
128
8484baaa 129my $kernelversion;
93351d41 130my ($sphinx_major, $sphinx_minor, $sphinx_patch);
efa44475 131
8484baaa
RD
132my $dohighlight = "";
133
1da177e4 134my $verbose = 0;
2c12c810 135my $Werror = 0;
bdfe2be3 136my $output_mode = "rst";
e314ba31 137my $output_preformatted = 0;
4b44595a 138my $no_doc_sections = 0;
0b0f5f29 139my $enable_lineno = 0;
bdfe2be3
MCC
140my @highlights = @highlights_rst;
141my $blankline = $blankline_rst;
1da177e4 142my $modulename = "Kernel API";
b6c3f456
JN
143
144use constant {
145 OUTPUT_ALL => 0, # output all symbols and doc sections
146 OUTPUT_INCLUDE => 1, # output only specified symbols
eab795dd
MCC
147 OUTPUT_EXPORTED => 2, # output exported symbols
148 OUTPUT_INTERNAL => 3, # output non-exported symbols
b6c3f456
JN
149};
150my $output_selection = OUTPUT_ALL;
b0d60bfb 151my $show_not_found = 0; # No longer used
b2c4105b 152
88c2b57d
JN
153my @export_file_list;
154
b2c4105b
BH
155my @build_time;
156if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
157 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
158 @build_time = gmtime($seconds);
159} else {
160 @build_time = localtime;
161}
162
3c3b809e
RD
163my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
164 'July', 'August', 'September', 'October',
b2c4105b
BH
165 'November', 'December')[$build_time[4]] .
166 " " . ($build_time[5]+1900);
1da177e4 167
8484baaa 168# Essentially these are globals.
b9d97328
RD
169# They probably want to be tidied up, made more localised or something.
170# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
1da177e4 171# could cause "use of undefined value" or other bugs.
b9d97328 172my ($function, %function_table, %parametertypes, $declaration_purpose);
eab795dd 173my %nosymbol_table = ();
0b0f5f29 174my $declaration_start_line;
b9d97328 175my ($type, $declaration_name, $return_type);
1c32fd0c 176my ($newsection, $newcontents, $prototype, $brcount, %source_map);
1da177e4 177
bd0e88e5
RD
178if (defined($ENV{'KBUILD_VERBOSE'})) {
179 $verbose = "$ENV{'KBUILD_VERBOSE'}";
180}
181
2c12c810
PLB
182if (defined($ENV{'KCFLAGS'})) {
183 my $kcflags = "$ENV{'KCFLAGS'}";
184
185 if ($kcflags =~ /Werror/) {
186 $Werror = 1;
187 }
188}
189
bed4ed30
LP
190if (defined($ENV{'KDOC_WERROR'})) {
191 $Werror = "$ENV{'KDOC_WERROR'}";
192}
193
3c3b809e 194# Generated docbook code is inserted in a template at a point where
1da177e4 195# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
93431e06 196# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
1da177e4
LT
197# We keep track of number of generated entries and generate a dummy
198# if needs be to ensure the expanded template can be postprocessed
199# into html.
200my $section_counter = 0;
201
202my $lineprefix="";
203
48af606a
JN
204# Parser states
205use constant {
0d55d48b
MCC
206 STATE_NORMAL => 0, # normal code
207 STATE_NAME => 1, # looking for function name
208 STATE_BODY_MAYBE => 2, # body - or maybe more description
209 STATE_BODY => 3, # the body of the comment
210 STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
211 STATE_PROTO => 5, # scanning prototype
212 STATE_DOCBLOCK => 6, # documentation block
213 STATE_INLINE => 7, # gathering doc outside main block
48af606a 214};
1da177e4 215my $state;
850622df 216my $in_doc_sect;
d742f24d 217my $leading_space;
1da177e4 218
48af606a
JN
219# Inline documentation state
220use constant {
221 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
222 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
223 STATE_INLINE_TEXT => 2, # looking for member documentation
224 STATE_INLINE_END => 3, # done
225 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
226 # Spit a warning as it's not
227 # proper kernel-doc and ignore the rest.
228};
229my $inline_doc_state;
a4c6ebed 230
1da177e4
LT
231#declaration types: can be
232# 'function', 'struct', 'union', 'enum', 'typedef'
233my $decl_type;
234
52042e2d
MCC
235# Name of the kernel-doc identifier for non-DOC markups
236my $identifier;
237
1da177e4
LT
238my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
239my $doc_end = '\*/';
240my $doc_com = '\s*\*\s*';
12ae6779 241my $doc_com_body = '\s*\* ?';
b9d97328 242my $doc_decl = $doc_com . '(\w+)';
f624adef 243# @params and a strictly limited set of supported section names
212209cf
JC
244# Specifically:
245# Match @word:
246# @...:
247# @{section-name}:
248# while trying to not match literal block starts like "example::"
249#
76dd3e7b 250my $doc_sect = $doc_com .
212209cf 251 '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
12ae6779 252my $doc_content = $doc_com_body . '(.*)';
b9d97328 253my $doc_block = $doc_com . 'DOC:\s*(.*)?';
48af606a 254my $doc_inline_start = '^\s*/\*\*\s*$';
fe7bc493 255my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
48af606a 256my $doc_inline_end = '^\s*\*/\s*$';
0c9aa209 257my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
86ae2e38 258my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
632ce137 259my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';
e86bdb24
AS
260my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
261my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
1da177e4 262
1da177e4 263my %parameterdescs;
0b0f5f29 264my %parameterdesc_start_lines;
1da177e4
LT
265my @parameterlist;
266my %sections;
267my @sectionlist;
0b0f5f29 268my %section_start_lines;
a1d94aa5
RD
269my $sectcheck;
270my $struct_actual;
1da177e4
LT
271
272my $contents = "";
0b0f5f29 273my $new_start_line = 0;
f624adef
JN
274
275# the canonical section names. see also $doc_sect above.
1da177e4
LT
276my $section_default = "Description"; # default section
277my $section_intro = "Introduction";
278my $section = $section_default;
279my $section_context = "Context";
4092bac7 280my $section_return = "Return";
1da177e4
LT
281
282my $undescribed = "-- undescribed --";
283
284reset_state();
285
b031ac4e
MCC
286while ($ARGV[0] =~ m/^--?(.*)/) {
287 my $cmd = $1;
288 shift @ARGV;
289 if ($cmd eq "man") {
1da177e4 290 $output_mode = "man";
4d732701 291 @highlights = @highlights_man;
1da177e4 292 $blankline = $blankline_man;
b031ac4e 293 } elsif ($cmd eq "rst") {
c0d1b6ee
JC
294 $output_mode = "rst";
295 @highlights = @highlights_rst;
296 $blankline = $blankline_rst;
b031ac4e 297 } elsif ($cmd eq "none") {
3a025e1d 298 $output_mode = "none";
b031ac4e 299 } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
1da177e4 300 $modulename = shift @ARGV;
b031ac4e 301 } elsif ($cmd eq "function") { # to only output specific functions
b6c3f456 302 $output_selection = OUTPUT_INCLUDE;
1da177e4
LT
303 $function = shift @ARGV;
304 $function_table{$function} = 1;
eab795dd
MCC
305 } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
306 my $symbol = shift @ARGV;
307 $nosymbol_table{$symbol} = 1;
b031ac4e 308 } elsif ($cmd eq "export") { # only exported symbols
b6c3f456 309 $output_selection = OUTPUT_EXPORTED;
da9726ec 310 %function_table = ();
b031ac4e 311 } elsif ($cmd eq "internal") { # only non-exported symbols
b6c3f456 312 $output_selection = OUTPUT_INTERNAL;
da9726ec 313 %function_table = ();
b031ac4e 314 } elsif ($cmd eq "export-file") {
88c2b57d
JN
315 my $file = shift @ARGV;
316 push(@export_file_list, $file);
b031ac4e 317 } elsif ($cmd eq "v") {
1da177e4 318 $verbose = 1;
2c12c810
PLB
319 } elsif ($cmd eq "Werror") {
320 $Werror = 1;
b031ac4e 321 } elsif (($cmd eq "h") || ($cmd eq "help")) {
252b47da 322 pod2usage(-exitval => 0, -verbose => 2);
b031ac4e 323 } elsif ($cmd eq 'no-doc-sections') {
4b44595a 324 $no_doc_sections = 1;
b031ac4e 325 } elsif ($cmd eq 'enable-lineno') {
0b0f5f29 326 $enable_lineno = 1;
b031ac4e 327 } elsif ($cmd eq 'show-not-found') {
b0d60bfb 328 $show_not_found = 1; # A no-op but don't fail
93351d41
MCC
329 } elsif ($cmd eq "sphinx-version") {
330 my $ver_string = shift @ARGV;
331 if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
332 $sphinx_major = $1;
333 if (defined($2)) {
334 $sphinx_minor = substr($2,1);
335 } else {
336 $sphinx_minor = 0;
337 }
338 if (defined($3)) {
339 $sphinx_patch = substr($3,1)
340 } else {
341 $sphinx_patch = 0;
342 }
343 } else {
344 die "Sphinx version should either major.minor or major.minor.patch format\n";
345 }
b031ac4e 346 } else {
e334f873
AY
347 # Unknown argument
348 pod2usage(
349 -message => "Argument unknown!\n",
350 -exitval => 1,
351 -verbose => 99,
352 -sections => 'SYNOPSIS',
353 -output => \*STDERR,
354 );
355 }
356 if ($#ARGV < 0){
357 pod2usage(
358 -message => "FILE argument missing\n",
359 -exitval => 1,
360 -verbose => 99,
361 -sections => 'SYNOPSIS',
362 -output => \*STDERR,
363 );
1da177e4
LT
364 }
365}
366
8484baaa
RD
367# continue execution near EOF;
368
efa44475
MCC
369# The C domain dialect changed on Sphinx 3. So, we need to check the
370# version in order to produce the right tags.
371sub findprog($)
372{
373 foreach(split(/:/, $ENV{PATH})) {
374 return "$_/$_[0]" if(-x "$_/$_[0]");
375 }
376}
377
378sub get_sphinx_version()
379{
380 my $ver;
efa44475
MCC
381
382 my $cmd = "sphinx-build";
383 if (!findprog($cmd)) {
384 my $cmd = "sphinx-build3";
93351d41
MCC
385 if (!findprog($cmd)) {
386 $sphinx_major = 1;
387 $sphinx_minor = 2;
388 $sphinx_patch = 0;
389 printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
390 $sphinx_major, $sphinx_minor, $sphinx_patch;
391 return;
392 }
efa44475
MCC
393 }
394
395 open IN, "$cmd --version 2>&1 |";
396 while (<IN>) {
397 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
93351d41
MCC
398 $sphinx_major = $1;
399 $sphinx_minor = $2;
400 $sphinx_patch = $3;
efa44475
MCC
401 last;
402 }
403 # Sphinx 1.2.x uses a different format
404 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
93351d41
MCC
405 $sphinx_major = $1;
406 $sphinx_minor = $2;
407 $sphinx_patch = $3;
efa44475
MCC
408 last;
409 }
410 }
411 close IN;
efa44475
MCC
412}
413
53f049fa
BP
414# get kernel version from env
415sub get_kernel_version() {
1b9bc22d 416 my $version = 'unknown kernel version';
53f049fa
BP
417
418 if (defined($ENV{'KERNELVERSION'})) {
419 $version = $ENV{'KERNELVERSION'};
420 }
421 return $version;
422}
1da177e4 423
0b0f5f29
DV
424#
425sub print_lineno {
426 my $lineno = shift;
427 if ($enable_lineno && defined($lineno)) {
b79dfef0 428 print ".. LINENO " . $lineno . "\n";
0b0f5f29
DV
429 }
430}
df4bf98e
NS
431
432sub emit_warning {
433 my $location = shift;
434 my $msg = shift;
435 print STDERR "$location: warning: $msg";
436 ++$warnings;
437}
1da177e4
LT
438##
439# dumps section contents to arrays/hashes intended for that purpose.
440#
441sub dump_section {
94dc7ad5 442 my $file = shift;
1da177e4
LT
443 my $name = shift;
444 my $contents = join "\n", @_;
445
13901ef2 446 if ($name =~ m/$type_param/) {
1da177e4
LT
447 $name = $1;
448 $parameterdescs{$name} = $contents;
a1d94aa5 449 $sectcheck = $sectcheck . $name . " ";
0b0f5f29
DV
450 $parameterdesc_start_lines{$name} = $new_start_line;
451 $new_start_line = 0;
ced69090 452 } elsif ($name eq "@\.\.\.") {
ced69090
RD
453 $name = "...";
454 $parameterdescs{$name} = $contents;
a1d94aa5 455 $sectcheck = $sectcheck . $name . " ";
0b0f5f29
DV
456 $parameterdesc_start_lines{$name} = $new_start_line;
457 $new_start_line = 0;
1da177e4 458 } else {
94dc7ad5 459 if (defined($sections{$name}) && ($sections{$name} ne "")) {
95b6be9d
JN
460 # Only warn on user specified duplicate section names.
461 if ($name ne $section_default) {
df4bf98e 462 emit_warning("${file}:$.", "duplicate section name '$name'\n");
95b6be9d 463 }
32217761
JN
464 $sections{$name} .= $contents;
465 } else {
466 $sections{$name} = $contents;
467 push @sectionlist, $name;
0b0f5f29
DV
468 $section_start_lines{$name} = $new_start_line;
469 $new_start_line = 0;
94dc7ad5 470 }
1da177e4
LT
471 }
472}
473
b112e0f7
JB
474##
475# dump DOC: section after checking that it should go out
476#
477sub dump_doc_section {
94dc7ad5 478 my $file = shift;
b112e0f7
JB
479 my $name = shift;
480 my $contents = join "\n", @_;
481
4b44595a
JB
482 if ($no_doc_sections) {
483 return;
484 }
485
eab795dd
MCC
486 return if (defined($nosymbol_table{$name}));
487
b6c3f456 488 if (($output_selection == OUTPUT_ALL) ||
eab795dd
MCC
489 (($output_selection == OUTPUT_INCLUDE) &&
490 defined($function_table{$name})))
b112e0f7 491 {
94dc7ad5 492 dump_section($file, $name, $contents);
b112e0f7
JB
493 output_blockhead({'sectionlist' => \@sectionlist,
494 'sections' => \%sections,
495 'module' => $modulename,
b6c3f456 496 'content-only' => ($output_selection != OUTPUT_ALL), });
b112e0f7
JB
497 }
498}
499
1da177e4
LT
500##
501# output function
502#
503# parameterdescs, a hash.
504# function => "function name"
505# parameterlist => @list of parameters
506# parameterdescs => %parameter descriptions
507# sectionlist => @list of sections
a21217da 508# sections => %section descriptions
3c3b809e 509#
1da177e4
LT
510
511sub output_highlight {
512 my $contents = join "\n",@_;
513 my $line;
514
515# DEBUG
516# if (!defined $contents) {
517# use Carp;
518# confess "output_highlight got called with no args?\n";
519# }
520
3eb014a1 521# print STDERR "contents b4:$contents\n";
1da177e4
LT
522 eval $dohighlight;
523 die $@ if $@;
3eb014a1
RD
524# print STDERR "contents af:$contents\n";
525
1da177e4 526 foreach $line (split "\n", $contents) {
12ae6779
DS
527 if (! $output_preformatted) {
528 $line =~ s/^\s*//;
529 }
3c308798 530 if ($line eq ""){
e314ba31 531 if (! $output_preformatted) {
0bba924c 532 print $lineprefix, $blankline;
e314ba31 533 }
1da177e4 534 } else {
cdccb316
RD
535 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
536 print "\\&$line";
537 } else {
538 print $lineprefix, $line;
539 }
1da177e4
LT
540 }
541 print "\n";
542 }
543}
544
1da177e4
LT
545##
546# output function in man
547sub output_function_man(%) {
548 my %args = %{$_[0]};
549 my ($parameter, $section);
550 my $count;
551
552 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
553
554 print ".SH NAME\n";
b9d97328 555 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT
556
557 print ".SH SYNOPSIS\n";
a21217da 558 if ($args{'functiontype'} ne "") {
b9d97328 559 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
a21217da 560 } else {
b9d97328 561 print ".B \"" . $args{'function'} . "\n";
a21217da 562 }
1da177e4
LT
563 $count = 0;
564 my $parenth = "(";
565 my $post = ",";
566 foreach my $parameter (@{$args{'parameterlist'}}) {
567 if ($count == $#{$args{'parameterlist'}}) {
568 $post = ");";
569 }
570 $type = $args{'parametertypes'}{$parameter};
e86bdb24 571 if ($type =~ m/$function_pointer/) {
1da177e4 572 # pointer-to-function
ed8348e2 573 print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
1da177e4
LT
574 } else {
575 $type =~ s/([^\*])$/$1 /;
ed8348e2 576 print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
1da177e4
LT
577 }
578 $count++;
579 $parenth = "";
580 }
581
582 print ".SH ARGUMENTS\n";
583 foreach $parameter (@{$args{'parameterlist'}}) {
584 my $parameter_name = $parameter;
585 $parameter_name =~ s/\[.*//;
586
b9d97328 587 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT
588 output_highlight($args{'parameterdescs'}{$parameter_name});
589 }
590 foreach $section (@{$args{'sectionlist'}}) {
591 print ".SH \"", uc $section, "\"\n";
592 output_highlight($args{'sections'}{$section});
593 }
594}
595
596##
597# output enum in man
598sub output_enum_man(%) {
599 my %args = %{$_[0]};
600 my ($parameter, $section);
601 my $count;
602
603 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
604
605 print ".SH NAME\n";
b9d97328 606 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT
607
608 print ".SH SYNOPSIS\n";
b9d97328 609 print "enum " . $args{'enum'} . " {\n";
1da177e4
LT
610 $count = 0;
611 foreach my $parameter (@{$args{'parameterlist'}}) {
3c308798 612 print ".br\n.BI \" $parameter\"\n";
1da177e4
LT
613 if ($count == $#{$args{'parameterlist'}}) {
614 print "\n};\n";
615 last;
616 }
617 else {
618 print ", \n.br\n";
619 }
620 $count++;
621 }
622
623 print ".SH Constants\n";
624 foreach $parameter (@{$args{'parameterlist'}}) {
625 my $parameter_name = $parameter;
626 $parameter_name =~ s/\[.*//;
627
b9d97328 628 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT
629 output_highlight($args{'parameterdescs'}{$parameter_name});
630 }
631 foreach $section (@{$args{'sectionlist'}}) {
632 print ".SH \"$section\"\n";
633 output_highlight($args{'sections'}{$section});
634 }
635}
636
637##
638# output struct in man
639sub output_struct_man(%) {
640 my %args = %{$_[0]};
641 my ($parameter, $section);
642
b9d97328 643 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1da177e4
LT
644
645 print ".SH NAME\n";
b9d97328 646 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1da177e4 647
8ad72163
MCC
648 my $declaration = $args{'definition'};
649 $declaration =~ s/\t/ /g;
650 $declaration =~ s/\n/"\n.br\n.BI \"/g;
1da177e4 651 print ".SH SYNOPSIS\n";
b9d97328 652 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
8ad72163 653 print ".BI \"$declaration\n};\n.br\n\n";
1da177e4 654
c51d3dac 655 print ".SH Members\n";
1da177e4
LT
656 foreach $parameter (@{$args{'parameterlist'}}) {
657 ($parameter =~ /^#/) && next;
658
659 my $parameter_name = $parameter;
660 $parameter_name =~ s/\[.*//;
661
3c308798 662 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
b9d97328 663 print ".IP \"" . $parameter . "\" 12\n";
1da177e4
LT
664 output_highlight($args{'parameterdescs'}{$parameter_name});
665 }
666 foreach $section (@{$args{'sectionlist'}}) {
667 print ".SH \"$section\"\n";
668 output_highlight($args{'sections'}{$section});
669 }
670}
671
672##
673# output typedef in man
674sub output_typedef_man(%) {
675 my %args = %{$_[0]};
676 my ($parameter, $section);
677
678 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
679
680 print ".SH NAME\n";
b9d97328 681 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1da177e4
LT
682
683 foreach $section (@{$args{'sectionlist'}}) {
684 print ".SH \"$section\"\n";
685 output_highlight($args{'sections'}{$section});
686 }
687}
688
b112e0f7 689sub output_blockhead_man(%) {
1da177e4
LT
690 my %args = %{$_[0]};
691 my ($parameter, $section);
692 my $count;
693
694 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
695
696 foreach $section (@{$args{'sectionlist'}}) {
697 print ".SH \"$section\"\n";
698 output_highlight($args{'sections'}{$section});
699 }
700}
701
c0d1b6ee
JC
702##
703# output in restructured text
704#
705
706#
707# This could use some work; it's used to output the DOC: sections, and
708# starts by putting out the name of the doc section itself, but that tends
709# to duplicate a header already in the template file.
710#
711sub output_blockhead_rst(%) {
712 my %args = %{$_[0]};
713 my ($parameter, $section);
714
715 foreach $section (@{$args{'sectionlist'}}) {
eab795dd
MCC
716 next if (defined($nosymbol_table{$section}));
717
9e72184b 718 if ($output_selection != OUTPUT_INCLUDE) {
06a755d6 719 print ".. _$section:\n\n";
9e72184b
JN
720 print "**$section**\n\n";
721 }
0b0f5f29 722 print_lineno($section_start_lines{$section});
c0d1b6ee
JC
723 output_highlight_rst($args{'sections'}{$section});
724 print "\n";
725 }
726}
727
af250290
JC
728#
729# Apply the RST highlights to a sub-block of text.
76dd3e7b 730#
af250290
JC
731sub highlight_block($) {
732 # The dohighlight kludge requires the text be called $contents
733 my $contents = shift;
c0d1b6ee
JC
734 eval $dohighlight;
735 die $@ if $@;
af250290
JC
736 return $contents;
737}
c0d1b6ee 738
af250290
JC
739#
740# Regexes used only here.
741#
742my $sphinx_literal = '^[^.].*::$';
743my $sphinx_cblock = '^\.\.\ +code-block::';
744
745sub output_highlight_rst {
746 my $input = join "\n",@_;
747 my $output = "";
748 my $line;
749 my $in_literal = 0;
750 my $litprefix;
751 my $block = "";
752
753 foreach $line (split "\n",$input) {
754 #
755 # If we're in a literal block, see if we should drop out
756 # of it. Otherwise pass the line straight through unmunged.
757 #
758 if ($in_literal) {
759 if (! ($line =~ /^\s*$/)) {
760 #
761 # If this is the first non-blank line in a literal
762 # block we need to figure out what the proper indent is.
763 #
764 if ($litprefix eq "") {
765 $line =~ /^(\s*)/;
766 $litprefix = '^' . $1;
767 $output .= $line . "\n";
768 } elsif (! ($line =~ /$litprefix/)) {
769 $in_literal = 0;
770 } else {
771 $output .= $line . "\n";
772 }
773 } else {
774 $output .= $line . "\n";
775 }
776 }
777 #
778 # Not in a literal block (or just dropped out)
779 #
780 if (! $in_literal) {
781 $block .= $line . "\n";
782 if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
783 $in_literal = 1;
784 $litprefix = "";
785 $output .= highlight_block($block);
786 $block = ""
787 }
788 }
789 }
790
791 if ($block) {
792 $output .= highlight_block($block);
793 }
794 foreach $line (split "\n", $output) {
830066a7 795 print $lineprefix . $line . "\n";
c0d1b6ee
JC
796 }
797}
798
799sub output_function_rst(%) {
800 my %args = %{$_[0]};
801 my ($parameter, $section);
c099ff69 802 my $oldprefix = $lineprefix;
82801d06 803 my $start = "";
6e9e4158 804 my $is_macro = 0;
82801d06 805
e3ad05fe
MCC
806 if ($sphinx_major < 3) {
807 if ($args{'typedef'}) {
efa44475 808 print ".. c:type:: ". $args{'function'} . "\n\n";
e3ad05fe
MCC
809 print_lineno($declaration_start_line);
810 print " **Typedef**: ";
811 $lineprefix = "";
812 output_highlight_rst($args{'purpose'});
813 $start = "\n\n**Syntax**\n\n ``";
6e9e4158 814 $is_macro = 1;
efa44475 815 } else {
e3ad05fe 816 print ".. c:function:: ";
efa44475 817 }
82801d06 818 } else {
6e9e4158
MCC
819 if ($args{'typedef'} || $args{'functiontype'} eq "") {
820 $is_macro = 1;
821 print ".. c:macro:: ". $args{'function'} . "\n\n";
822 } else {
823 print ".. c:function:: ";
824 }
e3ad05fe
MCC
825
826 if ($args{'typedef'}) {
827 print_lineno($declaration_start_line);
828 print " **Typedef**: ";
829 $lineprefix = "";
830 output_highlight_rst($args{'purpose'});
831 $start = "\n\n**Syntax**\n\n ``";
832 } else {
6e9e4158 833 print "``" if ($is_macro);
e3ad05fe 834 }
82801d06 835 }
c0d1b6ee 836 if ($args{'functiontype'} ne "") {
82801d06 837 $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
c0d1b6ee 838 } else {
82801d06 839 $start .= $args{'function'} . " (";
c0d1b6ee
JC
840 }
841 print $start;
842
843 my $count = 0;
844 foreach my $parameter (@{$args{'parameterlist'}}) {
845 if ($count ne 0) {
846 print ", ";
847 }
848 $count++;
849 $type = $args{'parametertypes'}{$parameter};
a88b1672 850
e86bdb24 851 if ($type =~ m/$function_pointer/) {
c0d1b6ee 852 # pointer-to-function
e8f4ba83 853 print $1 . $parameter . ") (" . $2 . ")";
c0d1b6ee 854 } else {
ed8348e2 855 print $type;
c0d1b6ee
JC
856 }
857 }
6e9e4158
MCC
858 if ($is_macro) {
859 print ")``\n\n";
82801d06 860 } else {
6e9e4158
MCC
861 print ")\n\n";
862 }
863 if (!$args{'typedef'}) {
82801d06
MCC
864 print_lineno($declaration_start_line);
865 $lineprefix = " ";
866 output_highlight_rst($args{'purpose'});
867 print "\n";
868 }
c0d1b6ee 869
eaf710ce
JC
870 #
871 # Put our descriptive text into a container (thus an HTML <div>) to help
872 # set the function prototypes apart.
873 #
874 print ".. container:: kernelindent\n\n";
ecbcfba1 875 $lineprefix = " ";
eaf710ce 876 print $lineprefix . "**Parameters**\n\n";
c0d1b6ee
JC
877 foreach $parameter (@{$args{'parameterlist'}}) {
878 my $parameter_name = $parameter;
ada5f446 879 $parameter_name =~ s/\[.*//;
c0d1b6ee
JC
880 $type = $args{'parametertypes'}{$parameter};
881
882 if ($type ne "") {
eaf710ce 883 print $lineprefix . "``$type``\n";
c0d1b6ee 884 } else {
eaf710ce 885 print $lineprefix . "``$parameter``\n";
c0d1b6ee 886 }
0b0f5f29
DV
887
888 print_lineno($parameterdesc_start_lines{$parameter_name});
889
eaf710ce 890 $lineprefix = " ";
5e64fa9c
JN
891 if (defined($args{'parameterdescs'}{$parameter_name}) &&
892 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
c0d1b6ee 893 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
c0d1b6ee 894 } else {
eaf710ce 895 print $lineprefix . "*undescribed*\n";
c0d1b6ee 896 }
eaf710ce 897 $lineprefix = " ";
c0d1b6ee
JC
898 print "\n";
899 }
c099ff69 900
c0d1b6ee 901 output_section_rst(@_);
eaf710ce 902 $lineprefix = $oldprefix;
c0d1b6ee
JC
903}
904
905sub output_section_rst(%) {
906 my %args = %{$_[0]};
907 my $section;
908 my $oldprefix = $lineprefix;
c0d1b6ee
JC
909
910 foreach $section (@{$args{'sectionlist'}}) {
eaf710ce 911 print $lineprefix . "**$section**\n\n";
0b0f5f29 912 print_lineno($section_start_lines{$section});
c0d1b6ee
JC
913 output_highlight_rst($args{'sections'}{$section});
914 print "\n";
915 }
916 print "\n";
c0d1b6ee
JC
917}
918
919sub output_enum_rst(%) {
920 my %args = %{$_[0]};
921 my ($parameter);
c099ff69 922 my $oldprefix = $lineprefix;
c0d1b6ee 923 my $count;
eaf710ce 924 my $outer;
62850976 925
efa44475
MCC
926 if ($sphinx_major < 3) {
927 my $name = "enum " . $args{'enum'};
928 print "\n\n.. c:type:: " . $name . "\n\n";
929 } else {
930 my $name = $args{'enum'};
931 print "\n\n.. c:enum:: " . $name . "\n\n";
932 }
0b0f5f29 933 print_lineno($declaration_start_line);
eaf710ce 934 $lineprefix = " ";
c099ff69
JN
935 output_highlight_rst($args{'purpose'});
936 print "\n";
c0d1b6ee 937
eaf710ce
JC
938 print ".. container:: kernelindent\n\n";
939 $outer = $lineprefix . " ";
940 $lineprefix = $outer . " ";
941 print $outer . "**Constants**\n\n";
c0d1b6ee 942 foreach $parameter (@{$args{'parameterlist'}}) {
eaf710ce
JC
943 print $outer . "``$parameter``\n";
944
c0d1b6ee
JC
945 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
946 output_highlight_rst($args{'parameterdescs'}{$parameter});
947 } else {
eaf710ce 948 print $lineprefix . "*undescribed*\n";
c0d1b6ee
JC
949 }
950 print "\n";
951 }
eaf710ce 952 print "\n";
c0d1b6ee
JC
953 $lineprefix = $oldprefix;
954 output_section_rst(@_);
955}
956
957sub output_typedef_rst(%) {
958 my %args = %{$_[0]};
959 my ($parameter);
c099ff69 960 my $oldprefix = $lineprefix;
efa44475 961 my $name;
c0d1b6ee 962
efa44475
MCC
963 if ($sphinx_major < 3) {
964 $name = "typedef " . $args{'typedef'};
965 } else {
966 $name = $args{'typedef'};
967 }
62850976 968 print "\n\n.. c:type:: " . $name . "\n\n";
0b0f5f29 969 print_lineno($declaration_start_line);
c099ff69
JN
970 $lineprefix = " ";
971 output_highlight_rst($args{'purpose'});
972 print "\n";
c0d1b6ee 973
c099ff69 974 $lineprefix = $oldprefix;
c0d1b6ee
JC
975 output_section_rst(@_);
976}
977
978sub output_struct_rst(%) {
979 my %args = %{$_[0]};
980 my ($parameter);
c099ff69 981 my $oldprefix = $lineprefix;
c0d1b6ee 982
efa44475
MCC
983 if ($sphinx_major < 3) {
984 my $name = $args{'type'} . " " . $args{'struct'};
985 print "\n\n.. c:type:: " . $name . "\n\n";
986 } else {
987 my $name = $args{'struct'};
72b97d0b
MCC
988 if ($args{'type'} eq 'union') {
989 print "\n\n.. c:union:: " . $name . "\n\n";
990 } else {
991 print "\n\n.. c:struct:: " . $name . "\n\n";
992 }
efa44475 993 }
0b0f5f29 994 print_lineno($declaration_start_line);
eaf710ce 995 $lineprefix = " ";
c099ff69
JN
996 output_highlight_rst($args{'purpose'});
997 print "\n";
c0d1b6ee 998
eaf710ce
JC
999 print ".. container:: kernelindent\n\n";
1000 print $lineprefix . "**Definition**::\n\n";
8ad72163 1001 my $declaration = $args{'definition'};
eaf710ce
JC
1002 $lineprefix = $lineprefix . " ";
1003 $declaration =~ s/\t/$lineprefix/g;
1004 print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";
c0d1b6ee 1005
ecbcfba1 1006 $lineprefix = " ";
eaf710ce 1007 print $lineprefix . "**Members**\n\n";
c0d1b6ee
JC
1008 foreach $parameter (@{$args{'parameterlist'}}) {
1009 ($parameter =~ /^#/) && next;
1010
1011 my $parameter_name = $parameter;
1012 $parameter_name =~ s/\[.*//;
1013
1014 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1015 $type = $args{'parametertypes'}{$parameter};
0b0f5f29 1016 print_lineno($parameterdesc_start_lines{$parameter_name});
eaf710ce
JC
1017 print $lineprefix . "``" . $parameter . "``\n";
1018 $lineprefix = " ";
c0d1b6ee 1019 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
eaf710ce 1020 $lineprefix = " ";
c0d1b6ee
JC
1021 print "\n";
1022 }
1023 print "\n";
c099ff69
JN
1024
1025 $lineprefix = $oldprefix;
c0d1b6ee
JC
1026 output_section_rst(@_);
1027}
1028
3a025e1d
MW
1029## none mode output functions
1030
1031sub output_function_none(%) {
1032}
1033
1034sub output_enum_none(%) {
1035}
1036
1037sub output_typedef_none(%) {
1038}
1039
1040sub output_struct_none(%) {
1041}
1042
1043sub output_blockhead_none(%) {
1044}
1045
1da177e4 1046##
27205744
RD
1047# generic output function for all types (function, struct/union, typedef, enum);
1048# calls the generated, variable output_ function name based on
1049# functype and output_mode
1da177e4
LT
1050sub output_declaration {
1051 no strict 'refs';
1052 my $name = shift;
1053 my $functype = shift;
1054 my $func = "output_${functype}_$output_mode";
eab795dd
MCC
1055
1056 return if (defined($nosymbol_table{$name}));
1057
b6c3f456
JN
1058 if (($output_selection == OUTPUT_ALL) ||
1059 (($output_selection == OUTPUT_INCLUDE ||
1060 $output_selection == OUTPUT_EXPORTED) &&
1061 defined($function_table{$name})) ||
eab795dd 1062 ($output_selection == OUTPUT_INTERNAL &&
b6c3f456 1063 !($functype eq "function" && defined($function_table{$name}))))
1da177e4 1064 {
3c308798 1065 &$func(@_);
1da177e4
LT
1066 $section_counter++;
1067 }
1068}
1069
1070##
27205744 1071# generic output function - calls the right one based on current output mode.
b112e0f7 1072sub output_blockhead {
1da177e4 1073 no strict 'refs';
b9d97328 1074 my $func = "output_blockhead_" . $output_mode;
1da177e4
LT
1075 &$func(@_);
1076 $section_counter++;
1077}
1078
1079##
3c3b809e 1080# takes a declaration (struct, union, enum, typedef) and
1da177e4
LT
1081# invokes the right handler. NOT called for functions.
1082sub dump_declaration($$) {
1083 no strict 'refs';
1084 my ($prototype, $file) = @_;
b9d97328 1085 my $func = "dump_" . $decl_type;
1da177e4
LT
1086 &$func(@_);
1087}
1088
1089sub dump_union($$) {
1090 dump_struct(@_);
1091}
1092
1093sub dump_struct($$) {
1094 my $x = shift;
1095 my $file = shift;
a746fe32
AS
1096 my $decl_type;
1097 my $members;
1098 my $type = qr{struct|union};
1099 # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
e86bdb24
AS
1100 my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
1101 my $definition_body = qr{\{(.*)\}\s*$qualifiers*};
1102 my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
a746fe32
AS
1103
1104 if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1105 $decl_type = $1;
3c308798 1106 $declaration_name = $2;
a746fe32
AS
1107 $members = $3;
1108 } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1109 $decl_type = $1;
1110 $declaration_name = $3;
1111 $members = $2;
1112 }
1da177e4 1113
a746fe32 1114 if ($members) {
52042e2d 1115 if ($identifier ne $declaration_name) {
df4bf98e 1116 emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
52042e2d
MCC
1117 return;
1118 }
1119
aeec46b9 1120 # ignore members marked private:
0d8c39e6
MCC
1121 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1122 $members =~ s/\/\*\s*private:.*//gosi;
aeec46b9
MW
1123 # strip comments:
1124 $members =~ s/\/\*.*?\*\///gos;
ef5da59f 1125 # strip attributes
e86bdb24 1126 $members =~ s/\s*$attribute/ /gi;
2b5f78e5
AA
1127 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1128 $members =~ s/\s*__packed\s*/ /gos;
1129 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
f861537d 1130 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
a070991f 1131 $members =~ s/\s*____cacheline_aligned/ /gos;
50d7bd38
KC
1132 # unwrap struct_group():
1133 # - first eat non-declaration parameters and rewrite for final match
1134 # - then remove macro, outer parens, and trailing semicolon
1135 $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
1136 $members =~ s/\bstruct_group_(attr|tagged)\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
1137 $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
1138 $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
3556108e 1139
e86bdb24 1140 my $args = qr{([^,)]+)};
b22b5a9e 1141 # replace DECLARE_BITMAP
3556108e 1142 $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
603bdf5d 1143 $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
e86bdb24 1144 $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1cb566ba 1145 # replace DECLARE_HASHTABLE
e86bdb24 1146 $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
45005b27 1147 # replace DECLARE_KFIFO
e86bdb24 1148 $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos;
45005b27 1149 # replace DECLARE_KFIFO_PTR
e86bdb24 1150 $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
3080ea55
KC
1151 # replace DECLARE_FLEX_ARRAY
1152 $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
8ad72163
MCC
1153 my $declaration = $members;
1154
1155 # Split nested struct/union elements as newer ones
e86bdb24 1156 while ($members =~ m/$struct_members/) {
84ce5b98
MCC
1157 my $newmember;
1158 my $maintype = $1;
1159 my $ids = $4;
1160 my $content = $3;
1161 foreach my $id(split /,/, $ids) {
1162 $newmember .= "$maintype $id; ";
1163
8ad72163 1164 $id =~ s/[:\[].*//;
84ce5b98 1165 $id =~ s/^\s*\**(\S+)\s*/$1/;
8ad72163
MCC
1166 foreach my $arg (split /;/, $content) {
1167 next if ($arg =~ m/^\s*$/);
7c0d7e87
MCC
1168 if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
1169 # pointer-to-function
1170 my $type = $1;
1171 my $name = $2;
1172 my $extra = $3;
1173 next if (!$name);
1174 if ($id =~ m/^\s*$/) {
1175 # anonymous struct/union
84ce5b98 1176 $newmember .= "$type$name$extra; ";
7c0d7e87 1177 } else {
84ce5b98 1178 $newmember .= "$type$id.$name$extra; ";
7c0d7e87 1179 }
8ad72163 1180 } else {
84ce5b98
MCC
1181 my $type;
1182 my $names;
1183 $arg =~ s/^\s+//;
1184 $arg =~ s/\s+$//;
1185 # Handle bitmaps
1186 $arg =~ s/:\s*\d+\s*//g;
1187 # Handle arrays
d404d579 1188 $arg =~ s/\[.*\]//g;
84ce5b98
MCC
1189 # The type may have multiple words,
1190 # and multiple IDs can be defined, like:
1191 # const struct foo, *bar, foobar
1192 # So, we remove spaces when parsing the
1193 # names, in order to match just names
1194 # and commas for the names
1195 $arg =~ s/\s*,\s*/,/g;
1196 if ($arg =~ m/(.*)\s+([\S+,]+)/) {
1197 $type = $1;
1198 $names = $2;
7c0d7e87 1199 } else {
84ce5b98
MCC
1200 $newmember .= "$arg; ";
1201 next;
1202 }
1203 foreach my $name (split /,/, $names) {
1204 $name =~ s/^\s*\**(\S+)\s*/$1/;
1205 next if (($name =~ m/^\s*$/));
1206 if ($id =~ m/^\s*$/) {
1207 # anonymous struct/union
1208 $newmember .= "$type $name; ";
1209 } else {
1210 $newmember .= "$type $id.$name; ";
1211 }
7c0d7e87 1212 }
8ad72163
MCC
1213 }
1214 }
84ce5b98 1215 }
e86bdb24 1216 $members =~ s/$struct_members/$newmember/;
84ce5b98 1217 }
8ad72163
MCC
1218
1219 # Ignore other nested elements, like enums
673bb2df 1220 $members =~ s/(\{[^\{\}]*\})//g;
8ad72163 1221
151c468b 1222 create_parameterlist($members, ';', $file, $declaration_name);
1081de2d 1223 check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
1da177e4 1224
8ad72163 1225 # Adjust declaration for better display
673bb2df
BH
1226 $declaration =~ s/([\{;])/$1\n/g;
1227 $declaration =~ s/\}\s+;/};/g;
8ad72163 1228 # Better handle inlined enums
673bb2df 1229 do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
8ad72163
MCC
1230
1231 my @def_args = split /\n/, $declaration;
1232 my $level = 1;
1233 $declaration = "";
1234 foreach my $clause (@def_args) {
1235 $clause =~ s/^\s+//;
1236 $clause =~ s/\s+$//;
1237 $clause =~ s/\s+/ /;
1238 next if (!$clause);
673bb2df 1239 $level-- if ($clause =~ m/(\})/ && $level > 1);
8ad72163
MCC
1240 if (!($clause =~ m/^\s*#/)) {
1241 $declaration .= "\t" x $level;
1242 }
1243 $declaration .= "\t" . $clause . "\n";
673bb2df 1244 $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
8ad72163 1245 }
1da177e4
LT
1246 output_declaration($declaration_name,
1247 'struct',
1248 {'struct' => $declaration_name,
1249 'module' => $modulename,
8ad72163 1250 'definition' => $declaration,
1da177e4
LT
1251 'parameterlist' => \@parameterlist,
1252 'parameterdescs' => \%parameterdescs,
1253 'parametertypes' => \%parametertypes,
1254 'sectionlist' => \@sectionlist,
1255 'sections' => \%sections,
1256 'purpose' => $declaration_purpose,
1257 'type' => $decl_type
1258 });
1259 }
1260 else {
d40e1e65 1261 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1da177e4
LT
1262 ++$errors;
1263 }
1264}
1265
85afe608
MCC
1266
1267sub show_warnings($$) {
1268 my $functype = shift;
1269 my $name = shift;
1270
eab795dd
MCC
1271 return 0 if (defined($nosymbol_table{$name}));
1272
85afe608
MCC
1273 return 1 if ($output_selection == OUTPUT_ALL);
1274
1275 if ($output_selection == OUTPUT_EXPORTED) {
1276 if (defined($function_table{$name})) {
1277 return 1;
1278 } else {
1279 return 0;
1280 }
1281 }
1282 if ($output_selection == OUTPUT_INTERNAL) {
1283 if (!($functype eq "function" && defined($function_table{$name}))) {
1284 return 1;
1285 } else {
1286 return 0;
1287 }
1288 }
1289 if ($output_selection == OUTPUT_INCLUDE) {
1290 if (defined($function_table{$name})) {
1291 return 1;
1292 } else {
1293 return 0;
1294 }
1295 }
85afe608
MCC
1296 die("Please add the new output type at show_warnings()");
1297}
1298
1da177e4
LT
1299sub dump_enum($$) {
1300 my $x = shift;
1301 my $file = shift;
d38c8cfb
MCC
1302 my $members;
1303
1da177e4 1304
aeec46b9 1305 $x =~ s@/\*.*?\*/@@gos; # strip comments.
4468e21e
CN
1306 # strip #define macros inside enums
1307 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
b6d676db 1308
d38c8cfb
MCC
1309 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1310 $declaration_name = $2;
1311 $members = $1;
1312 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
3c308798 1313 $declaration_name = $1;
d38c8cfb
MCC
1314 $members = $2;
1315 }
1316
ae5b17e4 1317 if ($members) {
52042e2d 1318 if ($identifier ne $declaration_name) {
0b54c2e3 1319 if ($identifier eq "") {
df4bf98e 1320 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
0b54c2e3 1321 } else {
df4bf98e 1322 emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
0b54c2e3 1323 }
52042e2d
MCC
1324 return;
1325 }
0b54c2e3 1326 $declaration_name = "(anonymous)" if ($declaration_name eq "");
52042e2d 1327
5cb5c31c
JB
1328 my %_members;
1329
463a0fdc 1330 $members =~ s/\s+$//;
1da177e4
LT
1331
1332 foreach my $arg (split ',', $members) {
1333 $arg =~ s/^\s*(\w+).*/$1/;
1334 push @parameterlist, $arg;
1335 if (!$parameterdescs{$arg}) {
3c308798 1336 $parameterdescs{$arg} = $undescribed;
85afe608 1337 if (show_warnings("enum", $declaration_name)) {
df4bf98e 1338 emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
2defb272 1339 }
1da177e4 1340 }
5cb5c31c 1341 $_members{$arg} = 1;
1da177e4 1342 }
3c3b809e 1343
5cb5c31c
JB
1344 while (my ($k, $v) = each %parameterdescs) {
1345 if (!exists($_members{$k})) {
85afe608 1346 if (show_warnings("enum", $declaration_name)) {
df4bf98e 1347 emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
2defb272 1348 }
5cb5c31c
JB
1349 }
1350 }
1351
1da177e4
LT
1352 output_declaration($declaration_name,
1353 'enum',
1354 {'enum' => $declaration_name,
1355 'module' => $modulename,
1356 'parameterlist' => \@parameterlist,
1357 'parameterdescs' => \%parameterdescs,
1358 'sectionlist' => \@sectionlist,
1359 'sections' => \%sections,
1360 'purpose' => $declaration_purpose
1361 });
d38c8cfb 1362 } else {
d40e1e65 1363 print STDERR "${file}:$.: error: Cannot parse enum!\n";
1da177e4
LT
1364 ++$errors;
1365 }
1366}
1367
7d2c6b1e 1368my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
7efc6c42
MCC
1369my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
1370my $typedef_args = qr { \s*\((.*)\); }x;
1371
1372my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
1373my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
1374
1da177e4
LT
1375sub dump_typedef($$) {
1376 my $x = shift;
1377 my $file = shift;
1378
aeec46b9 1379 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4 1380
7efc6c42
MCC
1381 # Parse function typedef prototypes
1382 if ($x =~ $typedef1 || $x =~ $typedef2) {
83766452
MCC
1383 $return_type = $1;
1384 $declaration_name = $2;
1385 my $args = $3;
6b80975c 1386 $return_type =~ s/^\s+//;
83766452 1387
52042e2d 1388 if ($identifier ne $declaration_name) {
df4bf98e 1389 emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
52042e2d
MCC
1390 return;
1391 }
1392
151c468b 1393 create_parameterlist($args, ',', $file, $declaration_name);
1da177e4
LT
1394
1395 output_declaration($declaration_name,
83766452
MCC
1396 'function',
1397 {'function' => $declaration_name,
82801d06 1398 'typedef' => 1,
1da177e4 1399 'module' => $modulename,
83766452
MCC
1400 'functiontype' => $return_type,
1401 'parameterlist' => \@parameterlist,
1402 'parameterdescs' => \%parameterdescs,
1403 'parametertypes' => \%parametertypes,
1da177e4
LT
1404 'sectionlist' => \@sectionlist,
1405 'sections' => \%sections,
1406 'purpose' => $declaration_purpose
1407 });
83766452
MCC
1408 return;
1409 }
1410
1411 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1412 $x =~ s/\(*.\)\s*;$/;/;
1413 $x =~ s/\[*.\]\s*;$/;/;
1da177e4 1414 }
83766452
MCC
1415
1416 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
3a80a766
MCC
1417 $declaration_name = $1;
1418
52042e2d 1419 if ($identifier ne $declaration_name) {
df4bf98e 1420 emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
52042e2d
MCC
1421 return;
1422 }
1423
3a80a766
MCC
1424 output_declaration($declaration_name,
1425 'typedef',
1426 {'typedef' => $declaration_name,
1427 'module' => $modulename,
1428 'sectionlist' => \@sectionlist,
1429 'sections' => \%sections,
1430 'purpose' => $declaration_purpose
1431 });
1432 }
1da177e4 1433 else {
d40e1e65 1434 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
1da177e4
LT
1435 ++$errors;
1436 }
1437}
1438
a1d94aa5
RD
1439sub save_struct_actual($) {
1440 my $actual = shift;
1441
1442 # strip all spaces from the actual param so that it looks like one string item
1443 $actual =~ s/\s*//g;
1444 $struct_actual = $struct_actual . $actual . " ";
1445}
1446
151c468b 1447sub create_parameterlist($$$$) {
1da177e4
LT
1448 my $args = shift;
1449 my $splitter = shift;
1450 my $file = shift;
151c468b 1451 my $declaration_name = shift;
1da177e4
LT
1452 my $type;
1453 my $param;
1454
a6d3fe77 1455 # temporarily replace commas inside function pointer definition
e86bdb24
AS
1456 my $arg_expr = qr{\([^\),]+};
1457 while ($args =~ /$arg_expr,/) {
1458 $args =~ s/($arg_expr),/$1#/g;
1da177e4 1459 }
3c3b809e 1460
1da177e4
LT
1461 foreach my $arg (split($splitter, $args)) {
1462 # strip comments
1463 $arg =~ s/\/\*.*\*\///;
03699f27
KC
1464 # ignore argument attributes
1465 $arg =~ s/\sPOS0?\s/ /;
3c308798
RD
1466 # strip leading/trailing spaces
1467 $arg =~ s/^\s*//;
1da177e4
LT
1468 $arg =~ s/\s*$//;
1469 $arg =~ s/\s+/ /;
1470
1471 if ($arg =~ /^#/) {
1472 # Treat preprocessor directive as a typeless variable just to fill
1473 # corresponding data structures "correctly". Catch it later in
1474 # output_* subs.
ed8348e2 1475 push_parameter($arg, "", "", $file);
00d62961 1476 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1da177e4
LT
1477 # pointer-to-function
1478 $arg =~ tr/#/,/;
336ced2d 1479 $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
1da177e4
LT
1480 $param = $1;
1481 $type = $arg;
00d62961 1482 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
a1d94aa5 1483 save_struct_actual($param);
ed8348e2 1484 push_parameter($param, $type, $arg, $file, $declaration_name);
aeec46b9 1485 } elsif ($arg) {
1da177e4
LT
1486 $arg =~ s/\s*:\s*/:/g;
1487 $arg =~ s/\s*\[/\[/g;
1488
1489 my @args = split('\s*,\s*', $arg);
1490 if ($args[0] =~ m/\*/) {
1491 $args[0] =~ s/(\*+)\s*/ $1/;
1492 }
884f2810
BP
1493
1494 my @first_arg;
1495 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1496 shift @args;
1497 push(@first_arg, split('\s+', $1));
1498 push(@first_arg, $2);
1499 } else {
1500 @first_arg = split('\s+', shift @args);
1501 }
1502
1da177e4
LT
1503 unshift(@args, pop @first_arg);
1504 $type = join " ", @first_arg;
1505
1506 foreach $param (@args) {
1507 if ($param =~ m/^(\*+)\s*(.*)/) {
a1d94aa5 1508 save_struct_actual($2);
ed8348e2
MCC
1509
1510 push_parameter($2, "$type $1", $arg, $file, $declaration_name);
1da177e4
LT
1511 }
1512 elsif ($param =~ m/(.*?):(\d+)/) {
7b97887e 1513 if ($type ne "") { # skip unnamed bit-fields
a1d94aa5 1514 save_struct_actual($1);
ed8348e2 1515 push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
7b97887e 1516 }
1da177e4
LT
1517 }
1518 else {
a1d94aa5 1519 save_struct_actual($param);
ed8348e2 1520 push_parameter($param, $type, $arg, $file, $declaration_name);
1da177e4
LT
1521 }
1522 }
1523 }
1524 }
1525}
1526
ed8348e2 1527sub push_parameter($$$$$) {
1da177e4
LT
1528 my $param = shift;
1529 my $type = shift;
ed8348e2 1530 my $org_arg = shift;
1da177e4 1531 my $file = shift;
151c468b 1532 my $declaration_name = shift;
1da177e4 1533
5f8c7c98
RD
1534 if (($anon_struct_union == 1) && ($type eq "") &&
1535 ($param eq "}")) {
1536 return; # ignore the ending }; from anon. struct/union
1537 }
1538
1539 $anon_struct_union = 0;
f9b5c530 1540 $param =~ s/[\[\)].*//;
1da177e4 1541
a6d3fe77 1542 if ($type eq "" && $param =~ /\.\.\.$/)
1da177e4 1543 {
c950a173
SF
1544 if (!$param =~ /\w\.\.\.$/) {
1545 # handles unnamed variable parameters
1546 $param = "...";
1547 }
43756e34
JN
1548 elsif ($param =~ /\w\.\.\.$/) {
1549 # for named variable parameters of the form `x...`, remove the dots
1550 $param =~ s/\.\.\.$//;
1551 }
ced69090
RD
1552 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1553 $parameterdescs{$param} = "variable arguments";
1554 }
1da177e4
LT
1555 }
1556 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1557 {
1da177e4
LT
1558 $param="void";
1559 $parameterdescs{void} = "no arguments";
1560 }
134fe01b
RD
1561 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1562 # handle unnamed (anonymous) union or struct:
1563 {
1564 $type = $param;
5f8c7c98 1565 $param = "{unnamed_" . $param . "}";
134fe01b 1566 $parameterdescs{$param} = "anonymous\n";
5f8c7c98 1567 $anon_struct_union = 1;
134fe01b
RD
1568 }
1569
a6d3fe77 1570 # warn if parameter has no description
134fe01b
RD
1571 # (but ignore ones starting with # as these are not parameters
1572 # but inline preprocessor statements);
151c468b 1573 # Note: It will also ignore void params and unnamed structs/unions
f9b5c530 1574 if (!defined $parameterdescs{$param} && $param !~ /^#/) {
151c468b 1575 $parameterdescs{$param} = $undescribed;
a6d3fe77 1576
be5cd20c 1577 if (show_warnings($type, $declaration_name) && $param !~ /\./) {
df4bf98e 1578 emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
2defb272 1579 }
3c308798 1580 }
1da177e4 1581
25985edc 1582 # strip spaces from $param so that it is one continuous string
e34e7dbb
RD
1583 # on @parameterlist;
1584 # this fixes a problem where check_sections() cannot find
1585 # a parameter like "addr[6 + 2]" because it actually appears
1586 # as "addr[6", "+", "2]" on the parameter list;
1587 # but it's better to maintain the param string unchanged for output,
1588 # so just weaken the string compare in check_sections() to ignore
1589 # "[blah" in a parameter string;
1590 ###$param =~ s/\s*//g;
1da177e4 1591 push @parameterlist, $param;
ed8348e2
MCC
1592 $org_arg =~ s/\s\s+/ /g;
1593 $parametertypes{$param} = $org_arg;
1da177e4
LT
1594}
1595
1081de2d
MCC
1596sub check_sections($$$$$) {
1597 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
a1d94aa5
RD
1598 my @sects = split ' ', $sectcheck;
1599 my @prms = split ' ', $prmscheck;
1600 my $err;
1601 my ($px, $sx);
1602 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
1603
1604 foreach $sx (0 .. $#sects) {
1605 $err = 1;
1606 foreach $px (0 .. $#prms) {
1607 $prm_clean = $prms[$px];
1608 $prm_clean =~ s/\[.*\]//;
e86bdb24 1609 $prm_clean =~ s/$attribute//i;
e34e7dbb
RD
1610 # ignore array size in a parameter string;
1611 # however, the original param string may contain
1612 # spaces, e.g.: addr[6 + 2]
1613 # and this appears in @prms as "addr[6" since the
1614 # parameter list is split at spaces;
1615 # hence just ignore "[..." for the sections check;
1616 $prm_clean =~ s/\[.*//;
1617
a1d94aa5
RD
1618 ##$prm_clean =~ s/^\**//;
1619 if ($prm_clean eq $sects[$sx]) {
1620 $err = 0;
1621 last;
1622 }
1623 }
1624 if ($err) {
1625 if ($decl_type eq "function") {
df4bf98e 1626 emit_warning("${file}:$.",
a1d94aa5
RD
1627 "Excess function parameter " .
1628 "'$sects[$sx]' " .
df4bf98e 1629 "description in '$decl_name'\n");
a1d94aa5
RD
1630 }
1631 }
1632 }
1633}
1634
4092bac7
YB
1635##
1636# Checks the section describing the return value of a function.
1637sub check_return_section {
1638 my $file = shift;
1639 my $declaration_name = shift;
1640 my $return_type = shift;
1641
1642 # Ignore an empty return type (It's a macro)
1643 # Ignore functions with a "void" return type. (But don't ignore "void *")
1644 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1645 return;
1646 }
1647
1648 if (!defined($sections{$section_return}) ||
1649 $sections{$section_return} eq "") {
df4bf98e 1650 emit_warning("${file}:$.",
4092bac7 1651 "No description found for return value of " .
df4bf98e 1652 "'$declaration_name'\n");
4092bac7
YB
1653 }
1654}
1655
1da177e4
LT
1656##
1657# takes a function prototype and the name of the current file being
1658# processed and spits out all the details stored in the global
1659# arrays/hashes.
1660sub dump_function($$) {
1661 my $prototype = shift;
1662 my $file = shift;
cbb4d3e6 1663 my $noret = 0;
1da177e4 1664
5ef09c96 1665 print_lineno($new_start_line);
5eb6b4b3 1666
1da177e4
LT
1667 $prototype =~ s/^static +//;
1668 $prototype =~ s/^extern +//;
4dc3b16b 1669 $prototype =~ s/^asmlinkage +//;
1da177e4
LT
1670 $prototype =~ s/^inline +//;
1671 $prototype =~ s/^__inline__ +//;
32e79401
RD
1672 $prototype =~ s/^__inline +//;
1673 $prototype =~ s/^__always_inline +//;
1674 $prototype =~ s/^noinline +//;
03699f27 1675 $prototype =~ s/^__FORTIFY_INLINE +//;
74fc5c65 1676 $prototype =~ s/__init +//;
20072205 1677 $prototype =~ s/__init_or_module +//;
80342d48 1678 $prototype =~ s/__deprecated +//;
084aa001 1679 $prototype =~ s/__flatten +//;
270a0096 1680 $prototype =~ s/__meminit +//;
70c95b00 1681 $prototype =~ s/__must_check +//;
0df7c0e3 1682 $prototype =~ s/__weak +//;
0891f959 1683 $prototype =~ s/__sched +//;
95e760cb 1684 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
03699f27
KC
1685 $prototype =~ s/__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//;
1686 $prototype =~ s/__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +//;
cbb4d3e6 1687 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
084aa001 1688 $prototype =~ s/__attribute_const__ +//;
b1aaa546
PB
1689 $prototype =~ s/__attribute__\s*\(\(
1690 (?:
1691 [\w\s]++ # attribute name
1692 (?:\([^)]*+\))? # attribute arguments
1693 \s*+,? # optional comma at the end
1694 )+
1695 \)\)\s+//x;
1da177e4
LT
1696
1697 # Yes, this truly is vile. We are looking for:
1698 # 1. Return type (may be nothing if we're looking at a macro)
1699 # 2. Function name
1700 # 3. Function parameters.
1701 #
1702 # All the while we have to watch out for function pointer parameters
1703 # (which IIRC is what the two sections are for), C types (these
1704 # regexps don't even start to express all the possibilities), and
1705 # so on.
1706 #
1707 # If you mess with these regexps, it's a good idea to check that
1708 # the following functions' documentation still comes out right:
1709 # - parport_register_device (function pointer parameters)
1710 # - atomic_set (macro)
9598f91f 1711 # - pci_match_device, __copy_to_user (long return type)
e86bdb24
AS
1712 my $name = qr{[a-zA-Z0-9_~:]+};
1713 my $prototype_end1 = qr{[^\(]*};
1714 my $prototype_end2 = qr{[^\{]*};
1715 my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)};
1716 my $type1 = qr{[\w\s]+};
1717 my $type2 = qr{$type1\*+};
1718
1719 if ($define && $prototype =~ m/^()($name)\s+/) {
cbb4d3e6
HG
1720 # This is an object-like macro, it has no return type and no parameter
1721 # list.
1722 # Function-like macros are not allowed to have spaces between
1723 # declaration_name and opening parenthesis (notice the \s+).
1724 $return_type = $1;
1725 $declaration_name = $2;
1726 $noret = 1;
e86bdb24
AS
1727 } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
1728 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1729 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1da177e4
LT
1730 $return_type = $1;
1731 $declaration_name = $2;
1732 my $args = $3;
1733
151c468b 1734 create_parameterlist($args, ',', $file, $declaration_name);
1da177e4 1735 } else {
df4bf98e 1736 emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
1da177e4
LT
1737 return;
1738 }
1739
52042e2d 1740 if ($identifier ne $declaration_name) {
df4bf98e 1741 emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
52042e2d
MCC
1742 return;
1743 }
1744
47bcacfd
MCC
1745 my $prms = join " ", @parameterlist;
1746 check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1747
1748 # This check emits a lot of warnings at the moment, because many
1749 # functions don't have a 'Return' doc section. So until the number
1750 # of warnings goes sufficiently down, the check is only performed in
1751 # verbose mode.
1752 # TODO: always perform the check.
1753 if ($verbose && !$noret) {
1754 check_return_section($file, $declaration_name, $return_type);
1755 }
4092bac7 1756
47bcacfd
MCC
1757 # The function parser can be called with a typedef parameter.
1758 # Handle it.
1759 if ($return_type =~ /typedef/) {
1760 output_declaration($declaration_name,
1761 'function',
1762 {'function' => $declaration_name,
1763 'typedef' => 1,
1764 'module' => $modulename,
1765 'functiontype' => $return_type,
1766 'parameterlist' => \@parameterlist,
1767 'parameterdescs' => \%parameterdescs,
1768 'parametertypes' => \%parametertypes,
1769 'sectionlist' => \@sectionlist,
1770 'sections' => \%sections,
1771 'purpose' => $declaration_purpose
1772 });
1773 } else {
1774 output_declaration($declaration_name,
1775 'function',
1776 {'function' => $declaration_name,
1777 'module' => $modulename,
1778 'functiontype' => $return_type,
1779 'parameterlist' => \@parameterlist,
1780 'parameterdescs' => \%parameterdescs,
1781 'parametertypes' => \%parametertypes,
1782 'sectionlist' => \@sectionlist,
1783 'sections' => \%sections,
1784 'purpose' => $declaration_purpose
1785 });
1786 }
1da177e4
LT
1787}
1788
1da177e4
LT
1789sub reset_state {
1790 $function = "";
1da177e4
LT
1791 %parameterdescs = ();
1792 %parametertypes = ();
1793 @parameterlist = ();
1794 %sections = ();
1795 @sectionlist = ();
a1d94aa5
RD
1796 $sectcheck = "";
1797 $struct_actual = "";
1da177e4 1798 $prototype = "";
3c3b809e 1799
48af606a
JN
1800 $state = STATE_NORMAL;
1801 $inline_doc_state = STATE_INLINE_NA;
1da177e4
LT
1802}
1803
56afb0f8
JB
1804sub tracepoint_munge($) {
1805 my $file = shift;
1806 my $tracepointname = 0;
1807 my $tracepointargs = 0;
1808
3a9089fd 1809 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
56afb0f8
JB
1810 $tracepointname = $1;
1811 }
3a9089fd
JB
1812 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
1813 $tracepointname = $1;
1814 }
1815 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1816 $tracepointname = $2;
1817 }
1818 $tracepointname =~ s/^\s+//; #strip leading whitespace
1819 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
56afb0f8
JB
1820 $tracepointargs = $1;
1821 }
1822 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
df4bf98e
NS
1823 emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
1824 "$prototype\n");
56afb0f8
JB
1825 } else {
1826 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
52042e2d 1827 $identifier = "trace_$identifier";
56afb0f8
JB
1828 }
1829}
1830
b4870bc5
RD
1831sub syscall_munge() {
1832 my $void = 0;
1833
7c9aa015 1834 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
b4870bc5
RD
1835## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1836 if ($prototype =~ m/SYSCALL_DEFINE0/) {
1837 $void = 1;
1838## $prototype = "long sys_$1(void)";
1839 }
1840
1841 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1842 if ($prototype =~ m/long (sys_.*?),/) {
1843 $prototype =~ s/,/\(/;
1844 } elsif ($void) {
1845 $prototype =~ s/\)/\(void\)/;
1846 }
1847
1848 # now delete all of the odd-number commas in $prototype
1849 # so that arg types & arg names don't have a comma between them
1850 my $count = 0;
1851 my $len = length($prototype);
1852 if ($void) {
1853 $len = 0; # skip the for-loop
1854 }
1855 for (my $ix = 0; $ix < $len; $ix++) {
1856 if (substr($prototype, $ix, 1) eq ',') {
1857 $count++;
1858 if ($count % 2 == 1) {
1859 substr($prototype, $ix, 1) = ' ';
1860 }
1861 }
1862 }
1863}
1864
b7afa92b 1865sub process_proto_function($$) {
1da177e4
LT
1866 my $x = shift;
1867 my $file = shift;
1868
51f5a0c8
RD
1869 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1870
890c78c2 1871 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1da177e4
LT
1872 # do nothing
1873 }
1874 elsif ($x =~ /([^\{]*)/) {
3c308798 1875 $prototype .= $1;
1da177e4 1876 }
b4870bc5 1877
890c78c2 1878 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
3c308798 1879 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1da177e4
LT
1880 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1881 $prototype =~ s@^\s+@@gos; # strip leading spaces
7ae281b0
MCC
1882
1883 # Handle prototypes for function pointers like:
1884 # int (*pcs_config)(struct foo)
1885 $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
1886
b4870bc5
RD
1887 if ($prototype =~ /SYSCALL_DEFINE/) {
1888 syscall_munge();
1889 }
3a9089fd
JB
1890 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1891 $prototype =~ /DEFINE_SINGLE_EVENT/)
1892 {
56afb0f8
JB
1893 tracepoint_munge($file);
1894 }
b4870bc5 1895 dump_function($prototype, $file);
1da177e4
LT
1896 reset_state();
1897 }
1898}
1899
b7afa92b 1900sub process_proto_type($$) {
1da177e4
LT
1901 my $x = shift;
1902 my $file = shift;
1903
1da177e4
LT
1904 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1905 $x =~ s@^\s+@@gos; # strip leading spaces
1906 $x =~ s@\s+$@@gos; # strip trailing spaces
51f5a0c8
RD
1907 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1908
1da177e4
LT
1909 if ($x =~ /^#/) {
1910 # To distinguish preprocessor directive from regular declaration later.
1911 $x .= ";";
1912 }
1913
1914 while (1) {
673bb2df 1915 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
463a0fdc
MH
1916 if( length $prototype ) {
1917 $prototype .= " "
1918 }
1da177e4
LT
1919 $prototype .= $1 . $2;
1920 ($2 eq '{') && $brcount++;
1921 ($2 eq '}') && $brcount--;
1922 if (($2 eq ';') && ($brcount == 0)) {
b9d97328 1923 dump_declaration($prototype, $file);
1da177e4 1924 reset_state();
3c308798 1925 last;
1da177e4
LT
1926 }
1927 $x = $3;
3c308798 1928 } else {
1da177e4
LT
1929 $prototype .= $x;
1930 last;
1931 }
1932 }
1933}
1934
6b5b55f6 1935
1ad560e4 1936sub map_filename($) {
2283a117 1937 my $file;
68f86662 1938 my ($orig_file) = @_;
1da177e4 1939
2283a117 1940 if (defined($ENV{'SRCTREE'})) {
68f86662 1941 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1ad560e4 1942 } else {
68f86662 1943 $file = $orig_file;
2283a117 1944 }
1ad560e4 1945
1da177e4
LT
1946 if (defined($source_map{$file})) {
1947 $file = $source_map{$file};
1948 }
1949
1ad560e4
JN
1950 return $file;
1951}
1952
88c2b57d
JN
1953sub process_export_file($) {
1954 my ($orig_file) = @_;
1955 my $file = map_filename($orig_file);
1956
1957 if (!open(IN,"<$file")) {
1958 print STDERR "Error: Cannot open file $file\n";
1959 ++$errors;
1960 return;
1961 }
1962
1963 while (<IN>) {
1964 if (/$export_symbol/) {
eab795dd 1965 next if (defined($nosymbol_table{$2}));
88c2b57d
JN
1966 $function_table{$2} = 1;
1967 }
632ce137
JG
1968 if (/$export_symbol_ns/) {
1969 next if (defined($nosymbol_table{$2}));
1970 $function_table{$2} = 1;
1971 }
88c2b57d
JN
1972 }
1973
1974 close(IN);
1975}
1976
07048d13
JC
1977#
1978# Parsers for the various processing states.
1979#
1980# STATE_NORMAL: looking for the /** to begin everything.
1981#
1982sub process_normal() {
1983 if (/$doc_start/o) {
1984 $state = STATE_NAME; # next line is always the function name
1985 $in_doc_sect = 0;
1986 $declaration_start_line = $. + 1;
1987 }
1988}
1989
3cac2bc4
JC
1990#
1991# STATE_NAME: Looking for the "name - description" line
1992#
1993sub process_name($$) {
1994 my $file = shift;
1ad560e4 1995 my $descr;
3cac2bc4
JC
1996
1997 if (/$doc_block/o) {
1998 $state = STATE_DOCBLOCK;
1999 $contents = "";
5ef09c96 2000 $new_start_line = $.;
3cac2bc4
JC
2001
2002 if ( $1 eq "" ) {
2003 $section = $section_intro;
2004 } else {
2005 $section = $1;
2006 }
52042e2d 2007 } elsif (/$doc_decl/o) {
3cac2bc4 2008 $identifier = $1;
3e58e839 2009 my $is_kernel_comment = 0;
e86bdb24 2010 my $decl_start = qr{$doc_com};
f9bbc12c
AS
2011 # test for pointer declaration type, foo * bar() - desc
2012 my $fn_type = qr{\w+\s*\*\s*};
2013 my $parenthesis = qr{\(\w*\)};
2014 my $decl_end = qr{[-:].*};
e86bdb24 2015 if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
3cac2bc4
JC
2016 $identifier = $1;
2017 }
52042e2d
MCC
2018 if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
2019 $decl_type = $1;
2020 $identifier = $2;
3e58e839 2021 $is_kernel_comment = 1;
52042e2d 2022 }
f9bbc12c
AS
2023 # Look for foo() or static void foo() - description; or misspelt
2024 # identifier
e86bdb24
AS
2025 elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
2026 /^$decl_start$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) {
f9bbc12c
AS
2027 $identifier = $1;
2028 $decl_type = 'function';
2029 $identifier =~ s/^define\s+//;
2030 $is_kernel_comment = 1;
2031 }
52042e2d 2032 $identifier =~ s/\s+$//;
07048d13 2033
3cac2bc4
JC
2034 $state = STATE_BODY;
2035 # if there's no @param blocks need to set up default section
2036 # here
2037 $contents = "";
2038 $section = $section_default;
2039 $new_start_line = $. + 1;
52042e2d 2040 if (/[-:](.*)/) {
3cac2bc4
JC
2041 # strip leading/trailing/multiple spaces
2042 $descr= $1;
2043 $descr =~ s/^\s*//;
2044 $descr =~ s/\s*$//;
2045 $descr =~ s/\s+/ /g;
2046 $declaration_purpose = $descr;
2047 $state = STATE_BODY_MAYBE;
2048 } else {
2049 $declaration_purpose = "";
2050 }
2051
3e58e839 2052 if (!$is_kernel_comment) {
df4bf98e 2053 emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
3e58e839
AS
2054 $state = STATE_NORMAL;
2055 }
2056
3cac2bc4 2057 if (($declaration_purpose eq "") && $verbose) {
df4bf98e 2058 emit_warning("${file}:$.", "missing initial short description on line:\n$_");
3cac2bc4
JC
2059 }
2060
0b54c2e3 2061 if ($identifier eq "" && $decl_type ne "enum") {
df4bf98e 2062 emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
52042e2d 2063 $state = STATE_NORMAL;
3cac2bc4
JC
2064 }
2065
2066 if ($verbose) {
52042e2d 2067 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
3cac2bc4
JC
2068 }
2069 } else {
df4bf98e 2070 emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
3cac2bc4
JC
2071 $state = STATE_NORMAL;
2072 }
2073}
07048d13 2074
d742f24d
JC
2075
2076#
2077# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2078#
2079sub process_body($$) {
2080 my $file = shift;
2081
43756e34
JN
2082 # Until all named variable macro parameters are
2083 # documented using the bare name (`x`) rather than with
2084 # dots (`x...`), strip the dots:
2085 if ($section =~ /\w\.\.\.$/) {
2086 $section =~ s/\.\.\.$//;
2087
2088 if ($verbose) {
df4bf98e 2089 emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
43756e34
JN
2090 }
2091 }
2092
0d55d48b
MCC
2093 if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2094 dump_section($file, $section, $contents);
2095 $section = $section_default;
5ef09c96 2096 $new_start_line = $.;
0d55d48b
MCC
2097 $contents = "";
2098 }
2099
d742f24d
JC
2100 if (/$doc_sect/i) { # case insensitive for supported section names
2101 $newsection = $1;
2102 $newcontents = $2;
2103
2104 # map the supported section names to the canonical names
2105 if ($newsection =~ m/^description$/i) {
2106 $newsection = $section_default;
2107 } elsif ($newsection =~ m/^context$/i) {
2108 $newsection = $section_context;
2109 } elsif ($newsection =~ m/^returns?$/i) {
2110 $newsection = $section_return;
2111 } elsif ($newsection =~ m/^\@return$/) {
2112 # special: @return is a section, not a param description
2113 $newsection = $section_return;
2114 }
2115
2116 if (($contents ne "") && ($contents ne "\n")) {
2117 if (!$in_doc_sect && $verbose) {
df4bf98e 2118 emit_warning("${file}:$.", "contents before sections\n");
d742f24d
JC
2119 }
2120 dump_section($file, $section, $contents);
2121 $section = $section_default;
2122 }
2123
2124 $in_doc_sect = 1;
2125 $state = STATE_BODY;
2126 $contents = $newcontents;
2127 $new_start_line = $.;
2128 while (substr($contents, 0, 1) eq " ") {
2129 $contents = substr($contents, 1);
2130 }
2131 if ($contents ne "") {
2132 $contents .= "\n";
2133 }
2134 $section = $newsection;
2135 $leading_space = undef;
2136 } elsif (/$doc_end/) {
2137 if (($contents ne "") && ($contents ne "\n")) {
2138 dump_section($file, $section, $contents);
2139 $section = $section_default;
2140 $contents = "";
2141 }
2142 # look for doc_com + <text> + doc_end:
2143 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
df4bf98e 2144 emit_warning("${file}:$.", "suspicious ending line: $_");
d742f24d
JC
2145 }
2146
2147 $prototype = "";
2148 $state = STATE_PROTO;
2149 $brcount = 0;
5ef09c96 2150 $new_start_line = $. + 1;
d742f24d 2151 } elsif (/$doc_content/) {
d742f24d 2152 if ($1 eq "") {
0d55d48b 2153 if ($section eq $section_context) {
d742f24d
JC
2154 dump_section($file, $section, $contents);
2155 $section = $section_default;
2156 $contents = "";
2157 $new_start_line = $.;
0d55d48b 2158 $state = STATE_BODY;
d742f24d 2159 } else {
0d55d48b
MCC
2160 if ($section ne $section_default) {
2161 $state = STATE_BODY_WITH_BLANK_LINE;
2162 } else {
2163 $state = STATE_BODY;
2164 }
d742f24d
JC
2165 $contents .= "\n";
2166 }
d742f24d
JC
2167 } elsif ($state == STATE_BODY_MAYBE) {
2168 # Continued declaration purpose
2169 chomp($declaration_purpose);
2170 $declaration_purpose .= " " . $1;
2171 $declaration_purpose =~ s/\s+/ /g;
2172 } else {
2173 my $cont = $1;
2174 if ($section =~ m/^@/ || $section eq $section_context) {
2175 if (!defined $leading_space) {
2176 if ($cont =~ m/^(\s+)/) {
2177 $leading_space = $1;
2178 } else {
2179 $leading_space = "";
2180 }
2181 }
2182 $cont =~ s/^$leading_space//;
2183 }
2184 $contents .= $cont . "\n";
2185 }
2186 } else {
2187 # i dont know - bad line? ignore.
df4bf98e 2188 emit_warning("${file}:$.", "bad line: $_");
d742f24d
JC
2189 }
2190}
2191
2192
cc794812
JC
2193#
2194# STATE_PROTO: reading a function/whatever prototype.
2195#
2196sub process_proto($$) {
2197 my $file = shift;
2198
2199 if (/$doc_inline_oneline/) {
2200 $section = $1;
2201 $contents = $2;
2202 if ($contents ne "") {
2203 $contents .= "\n";
2204 dump_section($file, $section, $contents);
2205 $section = $section_default;
2206 $contents = "";
2207 }
2208 } elsif (/$doc_inline_start/) {
2209 $state = STATE_INLINE;
2210 $inline_doc_state = STATE_INLINE_NAME;
2211 } elsif ($decl_type eq 'function') {
2212 process_proto_function($_, $file);
2213 } else {
2214 process_proto_type($_, $file);
2215 }
2216}
2217
c17add56
JC
2218#
2219# STATE_DOCBLOCK: within a DOC: block.
2220#
2221sub process_docblock($$) {
2222 my $file = shift;
2223
2224 if (/$doc_end/) {
2225 dump_doc_section($file, $section, $contents);
2226 $section = $section_default;
2227 $contents = "";
2228 $function = "";
2229 %parameterdescs = ();
2230 %parametertypes = ();
2231 @parameterlist = ();
2232 %sections = ();
2233 @sectionlist = ();
2234 $prototype = "";
2235 $state = STATE_NORMAL;
2236 } elsif (/$doc_content/) {
2237 if ( $1 eq "" ) {
2238 $contents .= $blankline;
2239 } else {
2240 $contents .= $1 . "\n";
2241 }
2242 }
2243}
2244
2245#
2246# STATE_INLINE: docbook comments within a prototype.
2247#
2248sub process_inline($$) {
2249 my $file = shift;
2250
2251 # First line (state 1) needs to be a @parameter
2252 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2253 $section = $1;
2254 $contents = $2;
2255 $new_start_line = $.;
2256 if ($contents ne "") {
2257 while (substr($contents, 0, 1) eq " ") {
2258 $contents = substr($contents, 1);
2259 }
2260 $contents .= "\n";
2261 }
2262 $inline_doc_state = STATE_INLINE_TEXT;
2263 # Documentation block end */
2264 } elsif (/$doc_inline_end/) {
2265 if (($contents ne "") && ($contents ne "\n")) {
2266 dump_section($file, $section, $contents);
2267 $section = $section_default;
2268 $contents = "";
2269 }
2270 $state = STATE_PROTO;
2271 $inline_doc_state = STATE_INLINE_NA;
2272 # Regular text
2273 } elsif (/$doc_content/) {
2274 if ($inline_doc_state == STATE_INLINE_TEXT) {
2275 $contents .= $1 . "\n";
2276 # nuke leading blank lines
2277 if ($contents =~ /^\s*$/) {
2278 $contents = "";
2279 }
2280 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2281 $inline_doc_state = STATE_INLINE_ERROR;
df4bf98e 2282 emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
c17add56
JC
2283 }
2284 }
2285}
2286
cc794812 2287
1ad560e4
JN
2288sub process_file($) {
2289 my $file;
1ad560e4
JN
2290 my $initial_section_counter = $section_counter;
2291 my ($orig_file) = @_;
1ad560e4
JN
2292
2293 $file = map_filename($orig_file);
2294
dbe8ba00 2295 if (!open(IN_FILE,"<$file")) {
1da177e4
LT
2296 print STDERR "Error: Cannot open file $file\n";
2297 ++$errors;
2298 return;
2299 }
2300
a9e7314b
ID
2301 $. = 1;
2302
1da177e4 2303 $section_counter = 0;
dbe8ba00 2304 while (<IN_FILE>) {
65478428 2305 while (s/\\\s*$//) {
dbe8ba00 2306 $_ .= <IN_FILE>;
65478428 2307 }
7c9aa015
MCC
2308 # Replace tabs by spaces
2309 while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
c17add56 2310 # Hand this line to the appropriate state handler
48af606a 2311 if ($state == STATE_NORMAL) {
07048d13 2312 process_normal();
3cac2bc4
JC
2313 } elsif ($state == STATE_NAME) {
2314 process_name($file, $_);
0d55d48b
MCC
2315 } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
2316 $state == STATE_BODY_WITH_BLANK_LINE) {
d742f24d 2317 process_body($file, $_);
48af606a 2318 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
c17add56 2319 process_inline($file, $_);
cc794812
JC
2320 } elsif ($state == STATE_PROTO) {
2321 process_proto($file, $_);
48af606a 2322 } elsif ($state == STATE_DOCBLOCK) {
c17add56 2323 process_docblock($file, $_);
3c308798 2324 }
1da177e4 2325 }
c17add56
JC
2326
2327 # Make sure we got something interesting.
b0d60bfb
JC
2328 if ($initial_section_counter == $section_counter && $
2329 output_mode ne "none") {
2330 if ($output_selection == OUTPUT_INCLUDE) {
df4bf98e 2331 emit_warning("${file}:1", "'$_' not found\n")
b0d60bfb 2332 for keys %function_table;
3a025e1d 2333 }
b0d60bfb 2334 else {
df4bf98e 2335 emit_warning("${file}:1", "no structured comments found\n");
e946c43a 2336 }
1da177e4 2337 }
dbe8ba00 2338 close IN_FILE;
1da177e4 2339}
8484baaa
RD
2340
2341
93351d41
MCC
2342if ($output_mode eq "rst") {
2343 get_sphinx_version() if (!$sphinx_major);
2344}
2345
8484baaa
RD
2346$kernelversion = get_kernel_version();
2347
2348# generate a sequence of code that will splice in highlighting information
2349# using the s// operator.
1ef06233 2350for (my $k = 0; $k < @highlights; $k++) {
4d732701
DCLP
2351 my $pattern = $highlights[$k][0];
2352 my $result = $highlights[$k][1];
2353# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2354 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
8484baaa
RD
2355}
2356
2357# Read the file that maps relative names to absolute names for
2358# separate source and object directories and for shadow trees.
2359if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2360 my ($relname, $absname);
2361 while(<SOURCE_MAP>) {
2362 chop();
2363 ($relname, $absname) = (split())[0..1];
2364 $relname =~ s:^/+::;
2365 $source_map{$relname} = $absname;
2366 }
2367 close(SOURCE_MAP);
2368}
2369
88c2b57d
JN
2370if ($output_selection == OUTPUT_EXPORTED ||
2371 $output_selection == OUTPUT_INTERNAL) {
c9b2cfb3
JN
2372
2373 push(@export_file_list, @ARGV);
2374
88c2b57d
JN
2375 foreach (@export_file_list) {
2376 chomp;
2377 process_export_file($_);
2378 }
2379}
2380
8484baaa
RD
2381foreach (@ARGV) {
2382 chomp;
2383 process_file($_);
2384}
2385if ($verbose && $errors) {
2386 print STDERR "$errors errors\n";
2387}
2388if ($verbose && $warnings) {
2389 print STDERR "$warnings warnings\n";
2390}
2391
2c12c810
PLB
2392if ($Werror && $warnings) {
2393 print STDERR "$warnings warnings as Errors\n";
2394 exit($warnings);
2395} else {
2396 exit($output_mode eq "none" ? 0 : $errors)
2397}
2875f787
TW
2398
2399__END__
2400
2401=head1 OPTIONS
2402
2403=head2 Output format selection (mutually exclusive):
2404
2405=over 8
2406
2407=item -man
2408
2409Output troff manual page format.
2410
2411=item -rst
2412
2413Output reStructuredText format. This is the default.
2414
2415=item -none
2416
2417Do not output documentation, only warnings.
2418
2419=back
2420
dd803b04
TW
2421=head2 Output format modifiers
2422
2423=head3 reStructuredText only
2424
2425=over 8
2426
2427=item -sphinx-version VERSION
2428
2429Use the ReST C domain dialect compatible with a specific Sphinx Version.
2430
2431If not specified, kernel-doc will auto-detect using the sphinx-build version
2432found on PATH.
2433
2434=back
2435
9c77f108
TW
2436=head2 Output selection (mutually exclusive):
2437
2438=over 8
2439
2440=item -export
2441
2442Only output documentation for the symbols that have been exported using
632ce137 2443EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
9c77f108
TW
2444
2445=item -internal
2446
2447Only output documentation for the symbols that have NOT been exported using
632ce137 2448EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
9c77f108
TW
2449
2450=item -function NAME
2451
2452Only output documentation for the given function or DOC: section title.
2453All other functions and DOC: sections are ignored.
2454
2455May be specified multiple times.
2456
2457=item -nosymbol NAME
2458
2459Exclude the specified symbol from the output documentation.
2460
2461May be specified multiple times.
2462
2463=back
2464
c15de5a1
TW
2465=head2 Output selection modifiers:
2466
2467=over 8
2468
2469=item -no-doc-sections
2470
2471Do not output DOC: sections.
2472
2473=item -export-file FILE
2474
632ce137 2475Specify an additional FILE in which to look for EXPORT_SYMBOL information.
c15de5a1
TW
2476
2477To be used with -export or -internal.
2478
2479May be specified multiple times.
2480
2481=back
2482
2483=head3 reStructuredText only
2484
2485=over 8
2486
2487=item -enable-lineno
2488
b79dfef0 2489Enable output of .. LINENO lines.
c15de5a1
TW
2490
2491=back
2492
834cf6b9
TW
2493=head2 Other parameters:
2494
2495=over 8
2496
2497=item -h, -help
2498
2499Print this help.
2500
2501=item -v
2502
2503Verbose output, more warnings and other information.
2504
2505=item -Werror
2506
2507Treat warnings as errors.
2508
2509=back
2510
2875f787 2511=cut