xref: /linux/scripts/kernel-doc (revision b79dfef0e2fcf41c736e7012c59d1260aa60f075)
1cb77f0d6SKamil Rytarowski#!/usr/bin/env perl
238476378SJonathan Corbet# SPDX-License-Identifier: GPL-2.0
31da177e4SLinus Torvalds
4cb77f0d6SKamil Rytarowskiuse warnings;
51da177e4SLinus Torvaldsuse strict;
61da177e4SLinus Torvalds
71da177e4SLinus Torvalds## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
81da177e4SLinus Torvalds## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
91da177e4SLinus Torvalds## Copyright (C) 2001  Simon Huggins                             ##
1070c95b00SRandy Dunlap## Copyright (C) 2005-2012  Randy Dunlap                         ##
111b40c194SDan Luedtke## Copyright (C) 2012  Dan Luedtke                               ##
121da177e4SLinus Torvalds## 								 ##
131da177e4SLinus Torvalds## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
141da177e4SLinus Torvalds## Copyright (c) 2000 MontaVista Software, Inc.			 ##
152b306ecaSTomasz Warniełło#
162b306ecaSTomasz Warniełło# Copyright (C) 2022 Tomasz Warniełło (POD)
171da177e4SLinus Torvalds
1843caf1a6STomasz Warniełłouse Pod::Usage qw/pod2usage/;
1943caf1a6STomasz Warniełło
20a5cdaea5STomasz Warniełło=head1 NAME
21a5cdaea5STomasz Warniełło
22a5cdaea5STomasz Warniełłokernel-doc - Print formatted kernel documentation to stdout
23a5cdaea5STomasz Warniełło
24a5cdaea5STomasz Warniełło=head1 SYNOPSIS
25a5cdaea5STomasz Warniełło
26a5cdaea5STomasz Warniełło kernel-doc [-h] [-v] [-Werror]
27a5cdaea5STomasz Warniełło   [ -man |
28a5cdaea5STomasz Warniełło     -rst [-sphinx-version VERSION] [-enable-lineno] |
29a5cdaea5STomasz Warniełło     -none
30a5cdaea5STomasz Warniełło   ]
31a5cdaea5STomasz Warniełło   [
32a5cdaea5STomasz Warniełło     -export |
33a5cdaea5STomasz Warniełło     -internal |
34a5cdaea5STomasz Warniełło     [-function NAME] ... |
35a5cdaea5STomasz Warniełło     [-nosymbol NAME] ...
36a5cdaea5STomasz Warniełło   ]
37a5cdaea5STomasz Warniełło   [-no-doc-sections]
38a5cdaea5STomasz Warniełło   [-export-file FILE] ...
39a5cdaea5STomasz Warniełło   FILE ...
40a5cdaea5STomasz Warniełło
41a5cdaea5STomasz WarniełłoRun `kernel-doc -h` for details.
42a5cdaea5STomasz Warniełło
43f1583922STomasz Warniełło=head1 DESCRIPTION
44f1583922STomasz Warniełło
45f1583922STomasz WarniełłoRead C language source or header FILEs, extract embedded documentation comments,
46f1583922STomasz Warniełłoand print formatted documentation to standard output.
47f1583922STomasz Warniełło
48f1583922STomasz WarniełłoThe documentation comments are identified by the "/**" opening comment mark.
49f1583922STomasz Warniełło
50f1583922STomasz WarniełłoSee Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
51f1583922STomasz Warniełło
52a5cdaea5STomasz Warniełło=cut
53a5cdaea5STomasz Warniełło
542875f787STomasz Warniełło# more perldoc at the end of the file
552875f787STomasz Warniełło
568484baaaSRandy Dunlap## init lots of data
578484baaaSRandy Dunlap
581da177e4SLinus Torvaldsmy $errors = 0;
591da177e4SLinus Torvaldsmy $warnings = 0;
605f8c7c98SRandy Dunlapmy $anon_struct_union = 0;
611da177e4SLinus Torvalds
621da177e4SLinus Torvalds# match expressions used to find embedded type information
63b97f193aSMauro Carvalho Chehabmy $type_constant = '\b``([^\`]+)``\b';
64b97f193aSMauro Carvalho Chehabmy $type_constant2 = '\%([-_\w]+)';
651da177e4SLinus Torvaldsmy $type_func = '(\w+)\(\)';
66bfd228c7SMike Rapoportmy $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
67ee2aa759SMauro Carvalho Chehabmy $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
685219f18aSJonathan Corbetmy $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
69346282dbSMauro Carvalho Chehabmy $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
701da177e4SLinus Torvaldsmy $type_env = '(\$\w+)';
71df31175bSPaolo Bonzinimy $type_enum = '\&(enum\s*([_\w]+))';
72df31175bSPaolo Bonzinimy $type_struct = '\&(struct\s*([_\w]+))';
73df31175bSPaolo Bonzinimy $type_typedef = '\&(typedef\s*([_\w]+))';
74df31175bSPaolo Bonzinimy $type_union = '\&(union\s*([_\w]+))';
755267dd35SPaolo Bonzinimy $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
76df31175bSPaolo Bonzinimy $type_fallback = '\&([_\w]+)';
77f3341dcfSJani Nikulamy $type_member_func = $type_member . '\(\)';
781da177e4SLinus Torvalds
791da177e4SLinus Torvalds# Output conversion substitutions.
801da177e4SLinus Torvalds#  One for each output format
811da177e4SLinus Torvalds
821da177e4SLinus Torvalds# these are pretty rough
834d732701SDanilo Cesar Lemes de Paulamy @highlights_man = (
844d732701SDanilo Cesar Lemes de Paula                      [$type_constant, "\$1"],
85b97f193aSMauro Carvalho Chehab                      [$type_constant2, "\$1"],
864d732701SDanilo Cesar Lemes de Paula                      [$type_func, "\\\\fB\$1\\\\fP"],
87df31175bSPaolo Bonzini                      [$type_enum, "\\\\fI\$1\\\\fP"],
884d732701SDanilo Cesar Lemes de Paula                      [$type_struct, "\\\\fI\$1\\\\fP"],
89df31175bSPaolo Bonzini                      [$type_typedef, "\\\\fI\$1\\\\fP"],
90df31175bSPaolo Bonzini                      [$type_union, "\\\\fI\$1\\\\fP"],
915267dd35SPaolo Bonzini                      [$type_param, "\\\\fI\$1\\\\fP"],
92ee2aa759SMauro Carvalho Chehab                      [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
93df31175bSPaolo Bonzini                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
94df31175bSPaolo Bonzini                      [$type_fallback, "\\\\fI\$1\\\\fP"]
954d732701SDanilo Cesar Lemes de Paula		     );
961da177e4SLinus Torvaldsmy $blankline_man = "";
971da177e4SLinus Torvalds
98c0d1b6eeSJonathan Corbet# rst-mode
99c0d1b6eeSJonathan Corbetmy @highlights_rst = (
100c0d1b6eeSJonathan Corbet                       [$type_constant, "``\$1``"],
101b97f193aSMauro Carvalho Chehab                       [$type_constant2, "``\$1``"],
102f3341dcfSJani Nikula                       # Note: need to escape () to avoid func matching later
1035267dd35SPaolo Bonzini                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
1045267dd35SPaolo Bonzini                       [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
1055219f18aSJonathan Corbet		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
106346282dbSMauro Carvalho Chehab		       [$type_fp_param2, "**\$1\\\\(\\\\)**"],
107344fdb28SJonathan Corbet                       [$type_func, "\$1()"],
108df31175bSPaolo Bonzini                       [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
109df31175bSPaolo Bonzini                       [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
110df31175bSPaolo Bonzini                       [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
111df31175bSPaolo Bonzini                       [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
112a7291e7eSJani Nikula                       # in rst this can refer to any type
113df31175bSPaolo Bonzini                       [$type_fallback, "\\:c\\:type\\:`\$1`"],
114ee2aa759SMauro Carvalho Chehab                       [$type_param_ref, "**\$1\$2**"]
115c0d1b6eeSJonathan Corbet		      );
116c0d1b6eeSJonathan Corbetmy $blankline_rst = "\n";
117c0d1b6eeSJonathan Corbet
1181da177e4SLinus Torvalds# read arguments
1191da177e4SLinus Torvaldsif ($#ARGV == -1) {
12043caf1a6STomasz Warniełło	pod2usage(
12143caf1a6STomasz Warniełło		-message => "No arguments!\n",
12243caf1a6STomasz Warniełło		-exitval => 1,
12343caf1a6STomasz Warniełło		-verbose => 99,
12443caf1a6STomasz Warniełło		-sections => 'SYNOPSIS',
12543caf1a6STomasz Warniełło		-output => \*STDERR,
12643caf1a6STomasz Warniełło	);
1271da177e4SLinus Torvalds}
1281da177e4SLinus Torvalds
1298484baaaSRandy Dunlapmy $kernelversion;
13093351d41SMauro Carvalho Chehabmy ($sphinx_major, $sphinx_minor, $sphinx_patch);
131efa44475SMauro Carvalho Chehab
1328484baaaSRandy Dunlapmy $dohighlight = "";
1338484baaaSRandy Dunlap
1341da177e4SLinus Torvaldsmy $verbose = 0;
1352c12c810SPierre-Louis Bossartmy $Werror = 0;
136bdfe2be3SMauro Carvalho Chehabmy $output_mode = "rst";
137e314ba31SDaniel Santosmy $output_preformatted = 0;
1384b44595aSJohannes Bergmy $no_doc_sections = 0;
1390b0f5f29SDaniel Vettermy $enable_lineno = 0;
140bdfe2be3SMauro Carvalho Chehabmy @highlights = @highlights_rst;
141bdfe2be3SMauro Carvalho Chehabmy $blankline = $blankline_rst;
1421da177e4SLinus Torvaldsmy $modulename = "Kernel API";
143b6c3f456SJani Nikula
144b6c3f456SJani Nikulause constant {
145b6c3f456SJani Nikula    OUTPUT_ALL          => 0, # output all symbols and doc sections
146b6c3f456SJani Nikula    OUTPUT_INCLUDE      => 1, # output only specified symbols
147eab795ddSMauro Carvalho Chehab    OUTPUT_EXPORTED     => 2, # output exported symbols
148eab795ddSMauro Carvalho Chehab    OUTPUT_INTERNAL     => 3, # output non-exported symbols
149b6c3f456SJani Nikula};
150b6c3f456SJani Nikulamy $output_selection = OUTPUT_ALL;
151b0d60bfbSJonathan Corbetmy $show_not_found = 0;	# No longer used
152b2c4105bSBen Hutchings
15388c2b57dSJani Nikulamy @export_file_list;
15488c2b57dSJani Nikula
155b2c4105bSBen Hutchingsmy @build_time;
156b2c4105bSBen Hutchingsif (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
157b2c4105bSBen Hutchings    (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
158b2c4105bSBen Hutchings    @build_time = gmtime($seconds);
159b2c4105bSBen Hutchings} else {
160b2c4105bSBen Hutchings    @build_time = localtime;
161b2c4105bSBen Hutchings}
162b2c4105bSBen Hutchings
1631da177e4SLinus Torvaldsmy $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
1641da177e4SLinus Torvalds		'July', 'August', 'September', 'October',
165b2c4105bSBen Hutchings		'November', 'December')[$build_time[4]] .
166b2c4105bSBen Hutchings  " " . ($build_time[5]+1900);
1671da177e4SLinus Torvalds
1688484baaaSRandy Dunlap# Essentially these are globals.
169b9d97328SRandy Dunlap# They probably want to be tidied up, made more localised or something.
170b9d97328SRandy Dunlap# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
1711da177e4SLinus Torvalds# could cause "use of undefined value" or other bugs.
1721da177e4SLinus Torvaldsmy ($function, %function_table, %parametertypes, $declaration_purpose);
173eab795ddSMauro Carvalho Chehabmy %nosymbol_table = ();
1740b0f5f29SDaniel Vettermy $declaration_start_line;
1751da177e4SLinus Torvaldsmy ($type, $declaration_name, $return_type);
1761c32fd0cSIlya Dryomovmy ($newsection, $newcontents, $prototype, $brcount, %source_map);
1771da177e4SLinus Torvalds
178bd0e88e5SRandy Dunlapif (defined($ENV{'KBUILD_VERBOSE'})) {
179bd0e88e5SRandy Dunlap	$verbose = "$ENV{'KBUILD_VERBOSE'}";
180bd0e88e5SRandy Dunlap}
181bd0e88e5SRandy Dunlap
1822c12c810SPierre-Louis Bossartif (defined($ENV{'KCFLAGS'})) {
1832c12c810SPierre-Louis Bossart	my $kcflags = "$ENV{'KCFLAGS'}";
1842c12c810SPierre-Louis Bossart
1852c12c810SPierre-Louis Bossart	if ($kcflags =~ /Werror/) {
1862c12c810SPierre-Louis Bossart		$Werror = 1;
1872c12c810SPierre-Louis Bossart	}
1882c12c810SPierre-Louis Bossart}
1892c12c810SPierre-Louis Bossart
190bed4ed30SLaurent Pinchartif (defined($ENV{'KDOC_WERROR'})) {
191bed4ed30SLaurent Pinchart	$Werror = "$ENV{'KDOC_WERROR'}";
192bed4ed30SLaurent Pinchart}
193bed4ed30SLaurent Pinchart
1941da177e4SLinus Torvalds# Generated docbook code is inserted in a template at a point where
1951da177e4SLinus Torvalds# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
19693431e06SAlexander A. Klimov# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
1971da177e4SLinus Torvalds# We keep track of number of generated entries and generate a dummy
1981da177e4SLinus Torvalds# if needs be to ensure the expanded template can be postprocessed
1991da177e4SLinus Torvalds# into html.
2001da177e4SLinus Torvaldsmy $section_counter = 0;
2011da177e4SLinus Torvalds
2021da177e4SLinus Torvaldsmy $lineprefix="";
2031da177e4SLinus Torvalds
20448af606aSJani Nikula# Parser states
20548af606aSJani Nikulause constant {
20648af606aSJani Nikula    STATE_NORMAL        => 0,        # normal code
20748af606aSJani Nikula    STATE_NAME          => 1,        # looking for function name
20817b78717SJonathan Corbet    STATE_BODY_MAYBE    => 2,        # body - or maybe more description
20917b78717SJonathan Corbet    STATE_BODY          => 3,        # the body of the comment
2100d55d48bSMauro Carvalho Chehab    STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
2110d55d48bSMauro Carvalho Chehab    STATE_PROTO         => 5,        # scanning prototype
2120d55d48bSMauro Carvalho Chehab    STATE_DOCBLOCK      => 6,        # documentation block
2130d55d48bSMauro Carvalho Chehab    STATE_INLINE        => 7,        # gathering doc outside main block
21448af606aSJani Nikula};
2151da177e4SLinus Torvaldsmy $state;
216850622dfSRandy Dunlapmy $in_doc_sect;
217d742f24dSJonathan Corbetmy $leading_space;
2181da177e4SLinus Torvalds
21948af606aSJani Nikula# Inline documentation state
22048af606aSJani Nikulause constant {
22148af606aSJani Nikula    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
22248af606aSJani Nikula    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
22348af606aSJani Nikula    STATE_INLINE_TEXT   => 2, # looking for member documentation
22448af606aSJani Nikula    STATE_INLINE_END    => 3, # done
22548af606aSJani Nikula    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
22648af606aSJani Nikula                              # Spit a warning as it's not
227a4c6ebedSDanilo Cesar Lemes de Paula                              # proper kernel-doc and ignore the rest.
22848af606aSJani Nikula};
22948af606aSJani Nikulamy $inline_doc_state;
230a4c6ebedSDanilo Cesar Lemes de Paula
2311da177e4SLinus Torvalds#declaration types: can be
2321da177e4SLinus Torvalds# 'function', 'struct', 'union', 'enum', 'typedef'
2331da177e4SLinus Torvaldsmy $decl_type;
2341da177e4SLinus Torvalds
23552042e2dSMauro Carvalho Chehab# Name of the kernel-doc identifier for non-DOC markups
23652042e2dSMauro Carvalho Chehabmy $identifier;
23752042e2dSMauro Carvalho Chehab
2381da177e4SLinus Torvaldsmy $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
2391da177e4SLinus Torvaldsmy $doc_end = '\*/';
2401da177e4SLinus Torvaldsmy $doc_com = '\s*\*\s*';
24112ae6779SDaniel Santosmy $doc_com_body = '\s*\* ?';
2421da177e4SLinus Torvaldsmy $doc_decl = $doc_com . '(\w+)';
243f624adefSJani Nikula# @params and a strictly limited set of supported section names
244212209cfSJonathan Corbet# Specifically:
245212209cfSJonathan Corbet#   Match @word:
246212209cfSJonathan Corbet#	  @...:
247212209cfSJonathan Corbet#         @{section-name}:
248212209cfSJonathan Corbet# while trying to not match literal block starts like "example::"
249212209cfSJonathan Corbet#
2508569de68SJonathan Corbetmy $doc_sect = $doc_com .
251212209cfSJonathan Corbet    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
25212ae6779SDaniel Santosmy $doc_content = $doc_com_body . '(.*)';
2531da177e4SLinus Torvaldsmy $doc_block = $doc_com . 'DOC:\s*(.*)?';
25448af606aSJani Nikulamy $doc_inline_start = '^\s*/\*\*\s*$';
255fe7bc493SMauro Carvalho Chehabmy $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
25648af606aSJani Nikulamy $doc_inline_end = '^\s*\*/\s*$';
2570c9aa209SJani Nikulamy $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
25886ae2e38SJani Nikulamy $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
259e86bdb24SAditya Srivastavamy $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
260e86bdb24SAditya Srivastavamy $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
2611da177e4SLinus Torvalds
2621da177e4SLinus Torvaldsmy %parameterdescs;
2630b0f5f29SDaniel Vettermy %parameterdesc_start_lines;
2641da177e4SLinus Torvaldsmy @parameterlist;
2651da177e4SLinus Torvaldsmy %sections;
2661da177e4SLinus Torvaldsmy @sectionlist;
2670b0f5f29SDaniel Vettermy %section_start_lines;
268a1d94aa5SRandy Dunlapmy $sectcheck;
269a1d94aa5SRandy Dunlapmy $struct_actual;
2701da177e4SLinus Torvalds
2711da177e4SLinus Torvaldsmy $contents = "";
2720b0f5f29SDaniel Vettermy $new_start_line = 0;
273f624adefSJani Nikula
274f624adefSJani Nikula# the canonical section names. see also $doc_sect above.
2751da177e4SLinus Torvaldsmy $section_default = "Description";	# default section
2761da177e4SLinus Torvaldsmy $section_intro = "Introduction";
2771da177e4SLinus Torvaldsmy $section = $section_default;
2781da177e4SLinus Torvaldsmy $section_context = "Context";
2794092bac7SYacine Belkadimy $section_return = "Return";
2801da177e4SLinus Torvalds
2811da177e4SLinus Torvaldsmy $undescribed = "-- undescribed --";
2821da177e4SLinus Torvalds
2831da177e4SLinus Torvaldsreset_state();
2841da177e4SLinus Torvalds
285b031ac4eSMauro Carvalho Chehabwhile ($ARGV[0] =~ m/^--?(.*)/) {
286b031ac4eSMauro Carvalho Chehab    my $cmd = $1;
287b031ac4eSMauro Carvalho Chehab    shift @ARGV;
288b031ac4eSMauro Carvalho Chehab    if ($cmd eq "man") {
2891da177e4SLinus Torvalds	$output_mode = "man";
2904d732701SDanilo Cesar Lemes de Paula	@highlights = @highlights_man;
2911da177e4SLinus Torvalds	$blankline = $blankline_man;
292b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "rst") {
293c0d1b6eeSJonathan Corbet	$output_mode = "rst";
294c0d1b6eeSJonathan Corbet	@highlights = @highlights_rst;
295c0d1b6eeSJonathan Corbet	$blankline = $blankline_rst;
296b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "none") {
2973a025e1dSMatthew Wilcox	$output_mode = "none";
298b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
2991da177e4SLinus Torvalds	$modulename = shift @ARGV;
300b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "function") { # to only output specific functions
301b6c3f456SJani Nikula	$output_selection = OUTPUT_INCLUDE;
3021da177e4SLinus Torvalds	$function = shift @ARGV;
3031da177e4SLinus Torvalds	$function_table{$function} = 1;
304eab795ddSMauro Carvalho Chehab    } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
305eab795ddSMauro Carvalho Chehab	my $symbol = shift @ARGV;
306eab795ddSMauro Carvalho Chehab	$nosymbol_table{$symbol} = 1;
307b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export") { # only exported symbols
308b6c3f456SJani Nikula	$output_selection = OUTPUT_EXPORTED;
309da9726ecSJani Nikula	%function_table = ();
310b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "internal") { # only non-exported symbols
311b6c3f456SJani Nikula	$output_selection = OUTPUT_INTERNAL;
312da9726ecSJani Nikula	%function_table = ();
313b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export-file") {
31488c2b57dSJani Nikula	my $file = shift @ARGV;
31588c2b57dSJani Nikula	push(@export_file_list, $file);
316b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "v") {
3171da177e4SLinus Torvalds	$verbose = 1;
3182c12c810SPierre-Louis Bossart    } elsif ($cmd eq "Werror") {
3192c12c810SPierre-Louis Bossart	$Werror = 1;
320b031ac4eSMauro Carvalho Chehab    } elsif (($cmd eq "h") || ($cmd eq "help")) {
321252b47daSTomasz Warniełło		pod2usage(-exitval => 0, -verbose => 2);
322b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'no-doc-sections') {
3234b44595aSJohannes Berg	    $no_doc_sections = 1;
324b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'enable-lineno') {
3250b0f5f29SDaniel Vetter	    $enable_lineno = 1;
326b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'show-not-found') {
327b0d60bfbSJonathan Corbet	$show_not_found = 1;  # A no-op but don't fail
32893351d41SMauro Carvalho Chehab    } elsif ($cmd eq "sphinx-version") {
32993351d41SMauro Carvalho Chehab	my $ver_string = shift @ARGV;
33093351d41SMauro Carvalho Chehab	if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
33193351d41SMauro Carvalho Chehab	    $sphinx_major = $1;
33293351d41SMauro Carvalho Chehab	    if (defined($2)) {
33393351d41SMauro Carvalho Chehab		$sphinx_minor = substr($2,1);
33493351d41SMauro Carvalho Chehab	    } else {
33593351d41SMauro Carvalho Chehab		$sphinx_minor = 0;
33693351d41SMauro Carvalho Chehab	    }
33793351d41SMauro Carvalho Chehab	    if (defined($3)) {
33893351d41SMauro Carvalho Chehab		$sphinx_patch = substr($3,1)
33993351d41SMauro Carvalho Chehab	    } else {
34093351d41SMauro Carvalho Chehab		$sphinx_patch = 0;
34193351d41SMauro Carvalho Chehab	    }
34293351d41SMauro Carvalho Chehab	} else {
34393351d41SMauro Carvalho Chehab	    die "Sphinx version should either major.minor or major.minor.patch format\n";
34493351d41SMauro Carvalho Chehab	}
345b031ac4eSMauro Carvalho Chehab    } else {
346b031ac4eSMauro Carvalho Chehab	# Unknown argument
34743caf1a6STomasz Warniełło	pod2usage(
34843caf1a6STomasz Warniełło	    -message => "Argument unknown!\n",
34943caf1a6STomasz Warniełło	    -exitval => 1,
35043caf1a6STomasz Warniełło	    -verbose => 99,
35143caf1a6STomasz Warniełło	    -sections => 'SYNOPSIS',
35243caf1a6STomasz Warniełło	    -output => \*STDERR,
35343caf1a6STomasz Warniełło	    );
354e334f873SAkira Yokosawa    }
355e334f873SAkira Yokosawa    if ($#ARGV < 0){
356e334f873SAkira Yokosawa	pod2usage(
357e334f873SAkira Yokosawa	    -message => "FILE argument missing\n",
358e334f873SAkira Yokosawa	    -exitval => 1,
359e334f873SAkira Yokosawa	    -verbose => 99,
360e334f873SAkira Yokosawa	    -sections => 'SYNOPSIS',
361e334f873SAkira Yokosawa	    -output => \*STDERR,
362e334f873SAkira Yokosawa	    );
3631da177e4SLinus Torvalds    }
3641da177e4SLinus Torvalds}
3651da177e4SLinus Torvalds
3668484baaaSRandy Dunlap# continue execution near EOF;
3678484baaaSRandy Dunlap
368efa44475SMauro Carvalho Chehab# The C domain dialect changed on Sphinx 3. So, we need to check the
369efa44475SMauro Carvalho Chehab# version in order to produce the right tags.
370efa44475SMauro Carvalho Chehabsub findprog($)
371efa44475SMauro Carvalho Chehab{
372efa44475SMauro Carvalho Chehab	foreach(split(/:/, $ENV{PATH})) {
373efa44475SMauro Carvalho Chehab		return "$_/$_[0]" if(-x "$_/$_[0]");
374efa44475SMauro Carvalho Chehab	}
375efa44475SMauro Carvalho Chehab}
376efa44475SMauro Carvalho Chehab
377efa44475SMauro Carvalho Chehabsub get_sphinx_version()
378efa44475SMauro Carvalho Chehab{
379efa44475SMauro Carvalho Chehab	my $ver;
380efa44475SMauro Carvalho Chehab
381efa44475SMauro Carvalho Chehab	my $cmd = "sphinx-build";
382efa44475SMauro Carvalho Chehab	if (!findprog($cmd)) {
383efa44475SMauro Carvalho Chehab		my $cmd = "sphinx-build3";
38493351d41SMauro Carvalho Chehab		if (!findprog($cmd)) {
38593351d41SMauro Carvalho Chehab			$sphinx_major = 1;
38693351d41SMauro Carvalho Chehab			$sphinx_minor = 2;
38793351d41SMauro Carvalho Chehab			$sphinx_patch = 0;
38893351d41SMauro Carvalho Chehab			printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
38993351d41SMauro Carvalho Chehab			       $sphinx_major, $sphinx_minor, $sphinx_patch;
39093351d41SMauro Carvalho Chehab			return;
39193351d41SMauro Carvalho Chehab		}
392efa44475SMauro Carvalho Chehab	}
393efa44475SMauro Carvalho Chehab
394efa44475SMauro Carvalho Chehab	open IN, "$cmd --version 2>&1 |";
395efa44475SMauro Carvalho Chehab	while (<IN>) {
396efa44475SMauro Carvalho Chehab		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
39793351d41SMauro Carvalho Chehab			$sphinx_major = $1;
39893351d41SMauro Carvalho Chehab			$sphinx_minor = $2;
39993351d41SMauro Carvalho Chehab			$sphinx_patch = $3;
400efa44475SMauro Carvalho Chehab			last;
401efa44475SMauro Carvalho Chehab		}
402efa44475SMauro Carvalho Chehab		# Sphinx 1.2.x uses a different format
403efa44475SMauro Carvalho Chehab		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
40493351d41SMauro Carvalho Chehab			$sphinx_major = $1;
40593351d41SMauro Carvalho Chehab			$sphinx_minor = $2;
40693351d41SMauro Carvalho Chehab			$sphinx_patch = $3;
407efa44475SMauro Carvalho Chehab			last;
408efa44475SMauro Carvalho Chehab		}
409efa44475SMauro Carvalho Chehab	}
410efa44475SMauro Carvalho Chehab	close IN;
411efa44475SMauro Carvalho Chehab}
412efa44475SMauro Carvalho Chehab
41353f049faSBorislav Petkov# get kernel version from env
41453f049faSBorislav Petkovsub get_kernel_version() {
4151b9bc22dSJohannes Berg    my $version = 'unknown kernel version';
41653f049faSBorislav Petkov
41753f049faSBorislav Petkov    if (defined($ENV{'KERNELVERSION'})) {
41853f049faSBorislav Petkov	$version = $ENV{'KERNELVERSION'};
41953f049faSBorislav Petkov    }
42053f049faSBorislav Petkov    return $version;
42153f049faSBorislav Petkov}
4221da177e4SLinus Torvalds
4230b0f5f29SDaniel Vetter#
4240b0f5f29SDaniel Vettersub print_lineno {
4250b0f5f29SDaniel Vetter    my $lineno = shift;
4260b0f5f29SDaniel Vetter    if ($enable_lineno && defined($lineno)) {
427*b79dfef0SMauro Carvalho Chehab        print ".. LINENO " . $lineno . "\n";
4280b0f5f29SDaniel Vetter    }
4290b0f5f29SDaniel Vetter}
4301da177e4SLinus Torvalds##
4311da177e4SLinus Torvalds# dumps section contents to arrays/hashes intended for that purpose.
4321da177e4SLinus Torvalds#
4331da177e4SLinus Torvaldssub dump_section {
43494dc7ad5SRandy Dunlap    my $file = shift;
4351da177e4SLinus Torvalds    my $name = shift;
4361da177e4SLinus Torvalds    my $contents = join "\n", @_;
4371da177e4SLinus Torvalds
43813901ef2SJani Nikula    if ($name =~ m/$type_param/) {
4391da177e4SLinus Torvalds	$name = $1;
4401da177e4SLinus Torvalds	$parameterdescs{$name} = $contents;
441a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
4420b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
4430b0f5f29SDaniel Vetter        $new_start_line = 0;
444ced69090SRandy Dunlap    } elsif ($name eq "@\.\.\.") {
445ced69090SRandy Dunlap	$name = "...";
446ced69090SRandy Dunlap	$parameterdescs{$name} = $contents;
447a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
4480b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
4490b0f5f29SDaniel Vetter        $new_start_line = 0;
4501da177e4SLinus Torvalds    } else {
45194dc7ad5SRandy Dunlap	if (defined($sections{$name}) && ($sections{$name} ne "")) {
45295b6be9dSJani Nikula	    # Only warn on user specified duplicate section names.
45395b6be9dSJani Nikula	    if ($name ne $section_default) {
45432217761SJani Nikula		print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
45532217761SJani Nikula		++$warnings;
45695b6be9dSJani Nikula	    }
45732217761SJani Nikula	    $sections{$name} .= $contents;
45832217761SJani Nikula	} else {
4591da177e4SLinus Torvalds	    $sections{$name} = $contents;
4601da177e4SLinus Torvalds	    push @sectionlist, $name;
4610b0f5f29SDaniel Vetter            $section_start_lines{$name} = $new_start_line;
4620b0f5f29SDaniel Vetter            $new_start_line = 0;
4631da177e4SLinus Torvalds	}
4641da177e4SLinus Torvalds    }
46532217761SJani Nikula}
4661da177e4SLinus Torvalds
4671da177e4SLinus Torvalds##
468b112e0f7SJohannes Berg# dump DOC: section after checking that it should go out
469b112e0f7SJohannes Berg#
470b112e0f7SJohannes Bergsub dump_doc_section {
47194dc7ad5SRandy Dunlap    my $file = shift;
472b112e0f7SJohannes Berg    my $name = shift;
473b112e0f7SJohannes Berg    my $contents = join "\n", @_;
474b112e0f7SJohannes Berg
4754b44595aSJohannes Berg    if ($no_doc_sections) {
4764b44595aSJohannes Berg        return;
4774b44595aSJohannes Berg    }
4784b44595aSJohannes Berg
479eab795ddSMauro Carvalho Chehab    return if (defined($nosymbol_table{$name}));
480eab795ddSMauro Carvalho Chehab
481b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
482eab795ddSMauro Carvalho Chehab	(($output_selection == OUTPUT_INCLUDE) &&
483eab795ddSMauro Carvalho Chehab	 defined($function_table{$name})))
484b112e0f7SJohannes Berg    {
48594dc7ad5SRandy Dunlap	dump_section($file, $name, $contents);
486b112e0f7SJohannes Berg	output_blockhead({'sectionlist' => \@sectionlist,
487b112e0f7SJohannes Berg			  'sections' => \%sections,
488b112e0f7SJohannes Berg			  'module' => $modulename,
489b6c3f456SJani Nikula			  'content-only' => ($output_selection != OUTPUT_ALL), });
490b112e0f7SJohannes Berg    }
491b112e0f7SJohannes Berg}
492b112e0f7SJohannes Berg
493b112e0f7SJohannes Berg##
4941da177e4SLinus Torvalds# output function
4951da177e4SLinus Torvalds#
4961da177e4SLinus Torvalds# parameterdescs, a hash.
4971da177e4SLinus Torvalds#  function => "function name"
4981da177e4SLinus Torvalds#  parameterlist => @list of parameters
4991da177e4SLinus Torvalds#  parameterdescs => %parameter descriptions
5001da177e4SLinus Torvalds#  sectionlist => @list of sections
501a21217daSRandy Dunlap#  sections => %section descriptions
5021da177e4SLinus Torvalds#
5031da177e4SLinus Torvalds
5041da177e4SLinus Torvaldssub output_highlight {
5051da177e4SLinus Torvalds    my $contents = join "\n",@_;
5061da177e4SLinus Torvalds    my $line;
5071da177e4SLinus Torvalds
5081da177e4SLinus Torvalds#   DEBUG
5091da177e4SLinus Torvalds#   if (!defined $contents) {
5101da177e4SLinus Torvalds#	use Carp;
5111da177e4SLinus Torvalds#	confess "output_highlight got called with no args?\n";
5121da177e4SLinus Torvalds#   }
5131da177e4SLinus Torvalds
5143eb014a1SRandy Dunlap#   print STDERR "contents b4:$contents\n";
5151da177e4SLinus Torvalds    eval $dohighlight;
5161da177e4SLinus Torvalds    die $@ if $@;
5173eb014a1SRandy Dunlap#   print STDERR "contents af:$contents\n";
5183eb014a1SRandy Dunlap
5191da177e4SLinus Torvalds    foreach $line (split "\n", $contents) {
52012ae6779SDaniel Santos	if (! $output_preformatted) {
52112ae6779SDaniel Santos	    $line =~ s/^\s*//;
52212ae6779SDaniel Santos	}
5231da177e4SLinus Torvalds	if ($line eq ""){
524e314ba31SDaniel Santos	    if (! $output_preformatted) {
5250bba924cSJonathan Corbet		print $lineprefix, $blankline;
526e314ba31SDaniel Santos	    }
5271da177e4SLinus Torvalds	} else {
528cdccb316SRandy Dunlap	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
529cdccb316SRandy Dunlap		print "\\&$line";
530cdccb316SRandy Dunlap	    } else {
5311da177e4SLinus Torvalds		print $lineprefix, $line;
5321da177e4SLinus Torvalds	    }
533cdccb316SRandy Dunlap	}
5341da177e4SLinus Torvalds	print "\n";
5351da177e4SLinus Torvalds    }
5361da177e4SLinus Torvalds}
5371da177e4SLinus Torvalds
5381da177e4SLinus Torvalds##
5391da177e4SLinus Torvalds# output function in man
5401da177e4SLinus Torvaldssub output_function_man(%) {
5411da177e4SLinus Torvalds    my %args = %{$_[0]};
5421da177e4SLinus Torvalds    my ($parameter, $section);
5431da177e4SLinus Torvalds    my $count;
5441da177e4SLinus Torvalds
5451da177e4SLinus Torvalds    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
5461da177e4SLinus Torvalds
5471da177e4SLinus Torvalds    print ".SH NAME\n";
5481da177e4SLinus Torvalds    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
5491da177e4SLinus Torvalds
5501da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
551a21217daSRandy Dunlap    if ($args{'functiontype'} ne "") {
5521da177e4SLinus Torvalds	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
553a21217daSRandy Dunlap    } else {
554a21217daSRandy Dunlap	print ".B \"" . $args{'function'} . "\n";
555a21217daSRandy Dunlap    }
5561da177e4SLinus Torvalds    $count = 0;
5571da177e4SLinus Torvalds    my $parenth = "(";
5581da177e4SLinus Torvalds    my $post = ",";
5591da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
5601da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
5611da177e4SLinus Torvalds	    $post = ");";
5621da177e4SLinus Torvalds	}
5631da177e4SLinus Torvalds	$type = $args{'parametertypes'}{$parameter};
564e86bdb24SAditya Srivastava	if ($type =~ m/$function_pointer/) {
5651da177e4SLinus Torvalds	    # pointer-to-function
566ed8348e2SMauro Carvalho Chehab	    print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
5671da177e4SLinus Torvalds	} else {
5681da177e4SLinus Torvalds	    $type =~ s/([^\*])$/$1 /;
569ed8348e2SMauro Carvalho Chehab	    print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
5701da177e4SLinus Torvalds	}
5711da177e4SLinus Torvalds	$count++;
5721da177e4SLinus Torvalds	$parenth = "";
5731da177e4SLinus Torvalds    }
5741da177e4SLinus Torvalds
5751da177e4SLinus Torvalds    print ".SH ARGUMENTS\n";
5761da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
5771da177e4SLinus Torvalds	my $parameter_name = $parameter;
5781da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
5791da177e4SLinus Torvalds
5801da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
5811da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
5821da177e4SLinus Torvalds    }
5831da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
5841da177e4SLinus Torvalds	print ".SH \"", uc $section, "\"\n";
5851da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
5861da177e4SLinus Torvalds    }
5871da177e4SLinus Torvalds}
5881da177e4SLinus Torvalds
5891da177e4SLinus Torvalds##
5901da177e4SLinus Torvalds# output enum in man
5911da177e4SLinus Torvaldssub output_enum_man(%) {
5921da177e4SLinus Torvalds    my %args = %{$_[0]};
5931da177e4SLinus Torvalds    my ($parameter, $section);
5941da177e4SLinus Torvalds    my $count;
5951da177e4SLinus Torvalds
5961da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
5971da177e4SLinus Torvalds
5981da177e4SLinus Torvalds    print ".SH NAME\n";
5991da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
6001da177e4SLinus Torvalds
6011da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
6021da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " {\n";
6031da177e4SLinus Torvalds    $count = 0;
6041da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
6051da177e4SLinus Torvalds	print ".br\n.BI \"    $parameter\"\n";
6061da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
6071da177e4SLinus Torvalds	    print "\n};\n";
6081da177e4SLinus Torvalds	    last;
6091da177e4SLinus Torvalds	}
6101da177e4SLinus Torvalds	else {
6111da177e4SLinus Torvalds	    print ", \n.br\n";
6121da177e4SLinus Torvalds	}
6131da177e4SLinus Torvalds	$count++;
6141da177e4SLinus Torvalds    }
6151da177e4SLinus Torvalds
6161da177e4SLinus Torvalds    print ".SH Constants\n";
6171da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
6181da177e4SLinus Torvalds	my $parameter_name = $parameter;
6191da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
6201da177e4SLinus Torvalds
6211da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
6221da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
6231da177e4SLinus Torvalds    }
6241da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6251da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6261da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6271da177e4SLinus Torvalds    }
6281da177e4SLinus Torvalds}
6291da177e4SLinus Torvalds
6301da177e4SLinus Torvalds##
6311da177e4SLinus Torvalds# output struct in man
6321da177e4SLinus Torvaldssub output_struct_man(%) {
6331da177e4SLinus Torvalds    my %args = %{$_[0]};
6341da177e4SLinus Torvalds    my ($parameter, $section);
6351da177e4SLinus Torvalds
6361da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
6371da177e4SLinus Torvalds
6381da177e4SLinus Torvalds    print ".SH NAME\n";
6391da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
6401da177e4SLinus Torvalds
6418ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
6428ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
6438ad72163SMauro Carvalho Chehab    $declaration =~ s/\n/"\n.br\n.BI \"/g;
6441da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
6451da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
6468ad72163SMauro Carvalho Chehab    print ".BI \"$declaration\n};\n.br\n\n";
6471da177e4SLinus Torvalds
648c51d3dacSRandy Dunlap    print ".SH Members\n";
6491da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
6501da177e4SLinus Torvalds	($parameter =~ /^#/) && next;
6511da177e4SLinus Torvalds
6521da177e4SLinus Torvalds	my $parameter_name = $parameter;
6531da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
6541da177e4SLinus Torvalds
6551da177e4SLinus Torvalds	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
6561da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
6571da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
6581da177e4SLinus Torvalds    }
6591da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6601da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6611da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6621da177e4SLinus Torvalds    }
6631da177e4SLinus Torvalds}
6641da177e4SLinus Torvalds
6651da177e4SLinus Torvalds##
6661da177e4SLinus Torvalds# output typedef in man
6671da177e4SLinus Torvaldssub output_typedef_man(%) {
6681da177e4SLinus Torvalds    my %args = %{$_[0]};
6691da177e4SLinus Torvalds    my ($parameter, $section);
6701da177e4SLinus Torvalds
6711da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
6721da177e4SLinus Torvalds
6731da177e4SLinus Torvalds    print ".SH NAME\n";
6741da177e4SLinus Torvalds    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
6751da177e4SLinus Torvalds
6761da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6771da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6781da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6791da177e4SLinus Torvalds    }
6801da177e4SLinus Torvalds}
6811da177e4SLinus Torvalds
682b112e0f7SJohannes Bergsub output_blockhead_man(%) {
6831da177e4SLinus Torvalds    my %args = %{$_[0]};
6841da177e4SLinus Torvalds    my ($parameter, $section);
6851da177e4SLinus Torvalds    my $count;
6861da177e4SLinus Torvalds
6871da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
6881da177e4SLinus Torvalds
6891da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6901da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6911da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6921da177e4SLinus Torvalds    }
6931da177e4SLinus Torvalds}
6941da177e4SLinus Torvalds
6951da177e4SLinus Torvalds##
696c0d1b6eeSJonathan Corbet# output in restructured text
697c0d1b6eeSJonathan Corbet#
698c0d1b6eeSJonathan Corbet
699c0d1b6eeSJonathan Corbet#
700c0d1b6eeSJonathan Corbet# This could use some work; it's used to output the DOC: sections, and
701c0d1b6eeSJonathan Corbet# starts by putting out the name of the doc section itself, but that tends
702c0d1b6eeSJonathan Corbet# to duplicate a header already in the template file.
703c0d1b6eeSJonathan Corbet#
704c0d1b6eeSJonathan Corbetsub output_blockhead_rst(%) {
705c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
706c0d1b6eeSJonathan Corbet    my ($parameter, $section);
707c0d1b6eeSJonathan Corbet
708c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
709eab795ddSMauro Carvalho Chehab	next if (defined($nosymbol_table{$section}));
710eab795ddSMauro Carvalho Chehab
7119e72184bSJani Nikula	if ($output_selection != OUTPUT_INCLUDE) {
71206a755d6SMichal Wajdeczko	    print ".. _$section:\n\n";
713c0d1b6eeSJonathan Corbet	    print "**$section**\n\n";
7149e72184bSJani Nikula	}
7150b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
716c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
717c0d1b6eeSJonathan Corbet	print "\n";
718c0d1b6eeSJonathan Corbet    }
719c0d1b6eeSJonathan Corbet}
720c0d1b6eeSJonathan Corbet
721af250290SJonathan Corbet#
722af250290SJonathan Corbet# Apply the RST highlights to a sub-block of text.
723af250290SJonathan Corbet#
724af250290SJonathan Corbetsub highlight_block($) {
725af250290SJonathan Corbet    # The dohighlight kludge requires the text be called $contents
726af250290SJonathan Corbet    my $contents = shift;
727c0d1b6eeSJonathan Corbet    eval $dohighlight;
728c0d1b6eeSJonathan Corbet    die $@ if $@;
729af250290SJonathan Corbet    return $contents;
730af250290SJonathan Corbet}
731c0d1b6eeSJonathan Corbet
732af250290SJonathan Corbet#
733af250290SJonathan Corbet# Regexes used only here.
734af250290SJonathan Corbet#
735af250290SJonathan Corbetmy $sphinx_literal = '^[^.].*::$';
736af250290SJonathan Corbetmy $sphinx_cblock = '^\.\.\ +code-block::';
737af250290SJonathan Corbet
738af250290SJonathan Corbetsub output_highlight_rst {
739af250290SJonathan Corbet    my $input = join "\n",@_;
740af250290SJonathan Corbet    my $output = "";
741af250290SJonathan Corbet    my $line;
742af250290SJonathan Corbet    my $in_literal = 0;
743af250290SJonathan Corbet    my $litprefix;
744af250290SJonathan Corbet    my $block = "";
745af250290SJonathan Corbet
746af250290SJonathan Corbet    foreach $line (split "\n",$input) {
747af250290SJonathan Corbet	#
748af250290SJonathan Corbet	# If we're in a literal block, see if we should drop out
749af250290SJonathan Corbet	# of it.  Otherwise pass the line straight through unmunged.
750af250290SJonathan Corbet	#
751af250290SJonathan Corbet	if ($in_literal) {
752af250290SJonathan Corbet	    if (! ($line =~ /^\s*$/)) {
753af250290SJonathan Corbet		#
754af250290SJonathan Corbet		# If this is the first non-blank line in a literal
755af250290SJonathan Corbet		# block we need to figure out what the proper indent is.
756af250290SJonathan Corbet		#
757af250290SJonathan Corbet		if ($litprefix eq "") {
758af250290SJonathan Corbet		    $line =~ /^(\s*)/;
759af250290SJonathan Corbet		    $litprefix = '^' . $1;
760af250290SJonathan Corbet		    $output .= $line . "\n";
761af250290SJonathan Corbet		} elsif (! ($line =~ /$litprefix/)) {
762af250290SJonathan Corbet		    $in_literal = 0;
763af250290SJonathan Corbet		} else {
764af250290SJonathan Corbet		    $output .= $line . "\n";
765af250290SJonathan Corbet		}
766af250290SJonathan Corbet	    } else {
767af250290SJonathan Corbet		$output .= $line . "\n";
768af250290SJonathan Corbet	    }
769af250290SJonathan Corbet	}
770af250290SJonathan Corbet	#
771af250290SJonathan Corbet	# Not in a literal block (or just dropped out)
772af250290SJonathan Corbet	#
773af250290SJonathan Corbet	if (! $in_literal) {
774af250290SJonathan Corbet	    $block .= $line . "\n";
775af250290SJonathan Corbet	    if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
776af250290SJonathan Corbet		$in_literal = 1;
777af250290SJonathan Corbet		$litprefix = "";
778af250290SJonathan Corbet		$output .= highlight_block($block);
779af250290SJonathan Corbet		$block = ""
780af250290SJonathan Corbet	    }
781af250290SJonathan Corbet	}
782af250290SJonathan Corbet    }
783af250290SJonathan Corbet
784af250290SJonathan Corbet    if ($block) {
785af250290SJonathan Corbet	$output .= highlight_block($block);
786af250290SJonathan Corbet    }
787af250290SJonathan Corbet    foreach $line (split "\n", $output) {
788830066a7SJani Nikula	print $lineprefix . $line . "\n";
789c0d1b6eeSJonathan Corbet    }
790c0d1b6eeSJonathan Corbet}
791c0d1b6eeSJonathan Corbet
792c0d1b6eeSJonathan Corbetsub output_function_rst(%) {
793c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
794c0d1b6eeSJonathan Corbet    my ($parameter, $section);
795c099ff69SJani Nikula    my $oldprefix = $lineprefix;
79682801d06SMauro Carvalho Chehab    my $start = "";
7976e9e4158SMauro Carvalho Chehab    my $is_macro = 0;
798c0d1b6eeSJonathan Corbet
799efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
800e3ad05feSMauro Carvalho Chehab	if ($args{'typedef'}) {
80182801d06SMauro Carvalho Chehab	    print ".. c:type:: ". $args{'function'} . "\n\n";
80282801d06SMauro Carvalho Chehab	    print_lineno($declaration_start_line);
80382801d06SMauro Carvalho Chehab	    print "   **Typedef**: ";
80482801d06SMauro Carvalho Chehab	    $lineprefix = "";
80582801d06SMauro Carvalho Chehab	    output_highlight_rst($args{'purpose'});
80682801d06SMauro Carvalho Chehab	    $start = "\n\n**Syntax**\n\n  ``";
8076e9e4158SMauro Carvalho Chehab	    $is_macro = 1;
808c0d1b6eeSJonathan Corbet	} else {
80982801d06SMauro Carvalho Chehab	    print ".. c:function:: ";
81082801d06SMauro Carvalho Chehab	}
811e3ad05feSMauro Carvalho Chehab    } else {
8126e9e4158SMauro Carvalho Chehab	if ($args{'typedef'} || $args{'functiontype'} eq "") {
8136e9e4158SMauro Carvalho Chehab	    $is_macro = 1;
814e3ad05feSMauro Carvalho Chehab	    print ".. c:macro:: ". $args{'function'} . "\n\n";
8156e9e4158SMauro Carvalho Chehab	} else {
8166e9e4158SMauro Carvalho Chehab	    print ".. c:function:: ";
8176e9e4158SMauro Carvalho Chehab	}
818e3ad05feSMauro Carvalho Chehab
819e3ad05feSMauro Carvalho Chehab	if ($args{'typedef'}) {
820e3ad05feSMauro Carvalho Chehab	    print_lineno($declaration_start_line);
821e3ad05feSMauro Carvalho Chehab	    print "   **Typedef**: ";
822e3ad05feSMauro Carvalho Chehab	    $lineprefix = "";
823e3ad05feSMauro Carvalho Chehab	    output_highlight_rst($args{'purpose'});
824e3ad05feSMauro Carvalho Chehab	    $start = "\n\n**Syntax**\n\n  ``";
825e3ad05feSMauro Carvalho Chehab	} else {
8266e9e4158SMauro Carvalho Chehab	    print "``" if ($is_macro);
827e3ad05feSMauro Carvalho Chehab	}
828e3ad05feSMauro Carvalho Chehab    }
82982801d06SMauro Carvalho Chehab    if ($args{'functiontype'} ne "") {
83082801d06SMauro Carvalho Chehab	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
83182801d06SMauro Carvalho Chehab    } else {
83282801d06SMauro Carvalho Chehab	$start .= $args{'function'} . " (";
833c0d1b6eeSJonathan Corbet    }
834c0d1b6eeSJonathan Corbet    print $start;
835c0d1b6eeSJonathan Corbet
836c0d1b6eeSJonathan Corbet    my $count = 0;
837c0d1b6eeSJonathan Corbet    foreach my $parameter (@{$args{'parameterlist'}}) {
838c0d1b6eeSJonathan Corbet	if ($count ne 0) {
839c0d1b6eeSJonathan Corbet	    print ", ";
840c0d1b6eeSJonathan Corbet	}
841c0d1b6eeSJonathan Corbet	$count++;
842c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
843a88b1672SMauro Carvalho Chehab
844e86bdb24SAditya Srivastava	if ($type =~ m/$function_pointer/) {
845c0d1b6eeSJonathan Corbet	    # pointer-to-function
846e8f4ba83SPeter Maydell	    print $1 . $parameter . ") (" . $2 . ")";
847c0d1b6eeSJonathan Corbet	} else {
848ed8348e2SMauro Carvalho Chehab	    print $type;
849c0d1b6eeSJonathan Corbet	}
850c0d1b6eeSJonathan Corbet    }
8516e9e4158SMauro Carvalho Chehab    if ($is_macro) {
8526e9e4158SMauro Carvalho Chehab	print ")``\n\n";
85382801d06SMauro Carvalho Chehab    } else {
854c099ff69SJani Nikula	print ")\n\n";
855e3ad05feSMauro Carvalho Chehab    }
8566e9e4158SMauro Carvalho Chehab    if (!$args{'typedef'}) {
8570b0f5f29SDaniel Vetter	print_lineno($declaration_start_line);
858c099ff69SJani Nikula	$lineprefix = "   ";
859c099ff69SJani Nikula	output_highlight_rst($args{'purpose'});
860c099ff69SJani Nikula	print "\n";
86182801d06SMauro Carvalho Chehab    }
862c0d1b6eeSJonathan Corbet
863ecbcfba1SJani Nikula    print "**Parameters**\n\n";
864c099ff69SJani Nikula    $lineprefix = "  ";
865c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
866c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
867ada5f446SGabriel Krisman Bertazi	$parameter_name =~ s/\[.*//;
868c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
869c0d1b6eeSJonathan Corbet
870c0d1b6eeSJonathan Corbet	if ($type ne "") {
871ed8348e2SMauro Carvalho Chehab	    print "``$type``\n";
872c0d1b6eeSJonathan Corbet	} else {
873c0d1b6eeSJonathan Corbet	    print "``$parameter``\n";
874c0d1b6eeSJonathan Corbet	}
8750b0f5f29SDaniel Vetter
8760b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
8770b0f5f29SDaniel Vetter
8785e64fa9cSJani Nikula	if (defined($args{'parameterdescs'}{$parameter_name}) &&
8795e64fa9cSJani Nikula	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
880c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});
881c0d1b6eeSJonathan Corbet	} else {
882d4b08e0cSJani Nikula	    print "  *undescribed*\n";
883c0d1b6eeSJonathan Corbet	}
884c0d1b6eeSJonathan Corbet	print "\n";
885c0d1b6eeSJonathan Corbet    }
886c099ff69SJani Nikula
887c099ff69SJani Nikula    $lineprefix = $oldprefix;
888c0d1b6eeSJonathan Corbet    output_section_rst(@_);
889c0d1b6eeSJonathan Corbet}
890c0d1b6eeSJonathan Corbet
891c0d1b6eeSJonathan Corbetsub output_section_rst(%) {
892c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
893c0d1b6eeSJonathan Corbet    my $section;
894c0d1b6eeSJonathan Corbet    my $oldprefix = $lineprefix;
895c0d1b6eeSJonathan Corbet    $lineprefix = "";
896c0d1b6eeSJonathan Corbet
897c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
898ecbcfba1SJani Nikula	print "**$section**\n\n";
8990b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
900c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
901c0d1b6eeSJonathan Corbet	print "\n";
902c0d1b6eeSJonathan Corbet    }
903c0d1b6eeSJonathan Corbet    print "\n";
904c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
905c0d1b6eeSJonathan Corbet}
906c0d1b6eeSJonathan Corbet
907c0d1b6eeSJonathan Corbetsub output_enum_rst(%) {
908c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
909c0d1b6eeSJonathan Corbet    my ($parameter);
910c099ff69SJani Nikula    my $oldprefix = $lineprefix;
911c0d1b6eeSJonathan Corbet    my $count;
91262850976SJani Nikula
913efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
914efa44475SMauro Carvalho Chehab	my $name = "enum " . $args{'enum'};
91562850976SJani Nikula	print "\n\n.. c:type:: " . $name . "\n\n";
916efa44475SMauro Carvalho Chehab    } else {
917efa44475SMauro Carvalho Chehab	my $name = $args{'enum'};
918efa44475SMauro Carvalho Chehab	print "\n\n.. c:enum:: " . $name . "\n\n";
919efa44475SMauro Carvalho Chehab    }
9200b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
921c099ff69SJani Nikula    $lineprefix = "   ";
922c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
923c099ff69SJani Nikula    print "\n";
924c0d1b6eeSJonathan Corbet
925ecbcfba1SJani Nikula    print "**Constants**\n\n";
926c0d1b6eeSJonathan Corbet    $lineprefix = "  ";
927c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
928ecbcfba1SJani Nikula	print "``$parameter``\n";
929c0d1b6eeSJonathan Corbet	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
930c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter});
931c0d1b6eeSJonathan Corbet	} else {
932d4b08e0cSJani Nikula	    print "  *undescribed*\n";
933c0d1b6eeSJonathan Corbet	}
934c0d1b6eeSJonathan Corbet	print "\n";
935c0d1b6eeSJonathan Corbet    }
936c099ff69SJani Nikula
937c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
938c0d1b6eeSJonathan Corbet    output_section_rst(@_);
939c0d1b6eeSJonathan Corbet}
940c0d1b6eeSJonathan Corbet
941c0d1b6eeSJonathan Corbetsub output_typedef_rst(%) {
942c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
943c0d1b6eeSJonathan Corbet    my ($parameter);
944c099ff69SJani Nikula    my $oldprefix = $lineprefix;
945efa44475SMauro Carvalho Chehab    my $name;
946c0d1b6eeSJonathan Corbet
947efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
948efa44475SMauro Carvalho Chehab	$name = "typedef " . $args{'typedef'};
949efa44475SMauro Carvalho Chehab    } else {
950efa44475SMauro Carvalho Chehab	$name = $args{'typedef'};
951efa44475SMauro Carvalho Chehab    }
95262850976SJani Nikula    print "\n\n.. c:type:: " . $name . "\n\n";
9530b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
954c099ff69SJani Nikula    $lineprefix = "   ";
955c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
956c099ff69SJani Nikula    print "\n";
957c0d1b6eeSJonathan Corbet
958c099ff69SJani Nikula    $lineprefix = $oldprefix;
959c0d1b6eeSJonathan Corbet    output_section_rst(@_);
960c0d1b6eeSJonathan Corbet}
961c0d1b6eeSJonathan Corbet
962c0d1b6eeSJonathan Corbetsub output_struct_rst(%) {
963c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
964c0d1b6eeSJonathan Corbet    my ($parameter);
965c099ff69SJani Nikula    my $oldprefix = $lineprefix;
966c0d1b6eeSJonathan Corbet
967efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
968efa44475SMauro Carvalho Chehab	my $name = $args{'type'} . " " . $args{'struct'};
96962850976SJani Nikula	print "\n\n.. c:type:: " . $name . "\n\n";
970efa44475SMauro Carvalho Chehab    } else {
971efa44475SMauro Carvalho Chehab	my $name = $args{'struct'};
97272b97d0bSMauro Carvalho Chehab	if ($args{'type'} eq 'union') {
97372b97d0bSMauro Carvalho Chehab	    print "\n\n.. c:union:: " . $name . "\n\n";
97472b97d0bSMauro Carvalho Chehab	} else {
975efa44475SMauro Carvalho Chehab	    print "\n\n.. c:struct:: " . $name . "\n\n";
976efa44475SMauro Carvalho Chehab	}
97772b97d0bSMauro Carvalho Chehab    }
9780b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
979c099ff69SJani Nikula    $lineprefix = "   ";
980c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
981c099ff69SJani Nikula    print "\n";
982c0d1b6eeSJonathan Corbet
983ecbcfba1SJani Nikula    print "**Definition**\n\n";
984c0d1b6eeSJonathan Corbet    print "::\n\n";
9858ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
9868ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
9878ad72163SMauro Carvalho Chehab    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration  };\n\n";
988c0d1b6eeSJonathan Corbet
989ecbcfba1SJani Nikula    print "**Members**\n\n";
990c099ff69SJani Nikula    $lineprefix = "  ";
991c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
992c0d1b6eeSJonathan Corbet	($parameter =~ /^#/) && next;
993c0d1b6eeSJonathan Corbet
994c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
995c0d1b6eeSJonathan Corbet	$parameter_name =~ s/\[.*//;
996c0d1b6eeSJonathan Corbet
997c0d1b6eeSJonathan Corbet	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
998c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
9990b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
10006d232c80SMauro Carvalho Chehab	print "``" . $parameter . "``\n";
1001c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1002c0d1b6eeSJonathan Corbet	print "\n";
1003c0d1b6eeSJonathan Corbet    }
1004c0d1b6eeSJonathan Corbet    print "\n";
1005c099ff69SJani Nikula
1006c099ff69SJani Nikula    $lineprefix = $oldprefix;
1007c0d1b6eeSJonathan Corbet    output_section_rst(@_);
1008c0d1b6eeSJonathan Corbet}
1009c0d1b6eeSJonathan Corbet
10103a025e1dSMatthew Wilcox## none mode output functions
10113a025e1dSMatthew Wilcox
10123a025e1dSMatthew Wilcoxsub output_function_none(%) {
10133a025e1dSMatthew Wilcox}
10143a025e1dSMatthew Wilcox
10153a025e1dSMatthew Wilcoxsub output_enum_none(%) {
10163a025e1dSMatthew Wilcox}
10173a025e1dSMatthew Wilcox
10183a025e1dSMatthew Wilcoxsub output_typedef_none(%) {
10193a025e1dSMatthew Wilcox}
10203a025e1dSMatthew Wilcox
10213a025e1dSMatthew Wilcoxsub output_struct_none(%) {
10223a025e1dSMatthew Wilcox}
10233a025e1dSMatthew Wilcox
10243a025e1dSMatthew Wilcoxsub output_blockhead_none(%) {
10253a025e1dSMatthew Wilcox}
10263a025e1dSMatthew Wilcox
10271da177e4SLinus Torvalds##
102827205744SRandy Dunlap# generic output function for all types (function, struct/union, typedef, enum);
102927205744SRandy Dunlap# calls the generated, variable output_ function name based on
103027205744SRandy Dunlap# functype and output_mode
10311da177e4SLinus Torvaldssub output_declaration {
10321da177e4SLinus Torvalds    no strict 'refs';
10331da177e4SLinus Torvalds    my $name = shift;
10341da177e4SLinus Torvalds    my $functype = shift;
10351da177e4SLinus Torvalds    my $func = "output_${functype}_$output_mode";
1036eab795ddSMauro Carvalho Chehab
1037eab795ddSMauro Carvalho Chehab    return if (defined($nosymbol_table{$name}));
1038eab795ddSMauro Carvalho Chehab
1039b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
1040b6c3f456SJani Nikula	(($output_selection == OUTPUT_INCLUDE ||
1041b6c3f456SJani Nikula	  $output_selection == OUTPUT_EXPORTED) &&
104286ae2e38SJani Nikula	 defined($function_table{$name})) ||
1043eab795ddSMauro Carvalho Chehab	($output_selection == OUTPUT_INTERNAL &&
104486ae2e38SJani Nikula	 !($functype eq "function" && defined($function_table{$name}))))
10451da177e4SLinus Torvalds    {
10461da177e4SLinus Torvalds	&$func(@_);
10471da177e4SLinus Torvalds	$section_counter++;
10481da177e4SLinus Torvalds    }
10491da177e4SLinus Torvalds}
10501da177e4SLinus Torvalds
10511da177e4SLinus Torvalds##
105227205744SRandy Dunlap# generic output function - calls the right one based on current output mode.
1053b112e0f7SJohannes Bergsub output_blockhead {
10541da177e4SLinus Torvalds    no strict 'refs';
1055b112e0f7SJohannes Berg    my $func = "output_blockhead_" . $output_mode;
10561da177e4SLinus Torvalds    &$func(@_);
10571da177e4SLinus Torvalds    $section_counter++;
10581da177e4SLinus Torvalds}
10591da177e4SLinus Torvalds
10601da177e4SLinus Torvalds##
10611da177e4SLinus Torvalds# takes a declaration (struct, union, enum, typedef) and
10621da177e4SLinus Torvalds# invokes the right handler. NOT called for functions.
10631da177e4SLinus Torvaldssub dump_declaration($$) {
10641da177e4SLinus Torvalds    no strict 'refs';
10651da177e4SLinus Torvalds    my ($prototype, $file) = @_;
10661da177e4SLinus Torvalds    my $func = "dump_" . $decl_type;
10671da177e4SLinus Torvalds    &$func(@_);
10681da177e4SLinus Torvalds}
10691da177e4SLinus Torvalds
10701da177e4SLinus Torvaldssub dump_union($$) {
10711da177e4SLinus Torvalds    dump_struct(@_);
10721da177e4SLinus Torvalds}
10731da177e4SLinus Torvalds
10741da177e4SLinus Torvaldssub dump_struct($$) {
10751da177e4SLinus Torvalds    my $x = shift;
10761da177e4SLinus Torvalds    my $file = shift;
1077a746fe32SAditya Srivastava    my $decl_type;
1078a746fe32SAditya Srivastava    my $members;
1079a746fe32SAditya Srivastava    my $type = qr{struct|union};
1080a746fe32SAditya Srivastava    # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
1081e86bdb24SAditya Srivastava    my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
1082e86bdb24SAditya Srivastava    my $definition_body = qr{\{(.*)\}\s*$qualifiers*};
1083e86bdb24SAditya Srivastava    my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
10841da177e4SLinus Torvalds
1085a746fe32SAditya Srivastava    if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1086a746fe32SAditya Srivastava	$decl_type = $1;
10871da177e4SLinus Torvalds	$declaration_name = $2;
1088a746fe32SAditya Srivastava	$members = $3;
1089a746fe32SAditya Srivastava    } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1090a746fe32SAditya Srivastava	$decl_type = $1;
1091a746fe32SAditya Srivastava	$declaration_name = $3;
1092a746fe32SAditya Srivastava	$members = $2;
1093a746fe32SAditya Srivastava    }
10941da177e4SLinus Torvalds
1095a746fe32SAditya Srivastava    if ($members) {
109652042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
109752042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
109852042e2dSMauro Carvalho Chehab	    return;
109952042e2dSMauro Carvalho Chehab	}
110052042e2dSMauro Carvalho Chehab
1101aeec46b9SMartin Waitz	# ignore members marked private:
11020d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
11030d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*//gosi;
1104aeec46b9SMartin Waitz	# strip comments:
1105aeec46b9SMartin Waitz	$members =~ s/\/\*.*?\*\///gos;
1106ef5da59fSRandy Dunlap	# strip attributes
1107e86bdb24SAditya Srivastava	$members =~ s/\s*$attribute/ /gi;
11083d9bfb19SSakari Ailus	$members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
11093d9bfb19SSakari Ailus	$members =~ s/\s*__packed\s*/ /gos;
1110f0074929SJonathan Corbet	$members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1111f861537dSAndré Almeida	$members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1112a070991fSJonathan Cameron	$members =~ s/\s*____cacheline_aligned/ /gos;
111350d7bd38SKees Cook	# unwrap struct_group():
111450d7bd38SKees Cook	# - first eat non-declaration parameters and rewrite for final match
111550d7bd38SKees Cook	# - then remove macro, outer parens, and trailing semicolon
111650d7bd38SKees Cook	$members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
111750d7bd38SKees Cook	$members =~ s/\bstruct_group_(attr|tagged)\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
111850d7bd38SKees Cook	$members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
111950d7bd38SKees Cook	$members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
11203556108eSMauro Carvalho Chehab
1121e86bdb24SAditya Srivastava	my $args = qr{([^,)]+)};
1122b22b5a9eSConchúr Navid	# replace DECLARE_BITMAP
11233556108eSMauro Carvalho Chehab	$members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
1124603bdf5dSRandy Dunlap	$members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
1125e86bdb24SAditya Srivastava	$members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
11261cb566baSJakub Kicinski	# replace DECLARE_HASHTABLE
1127e86bdb24SAditya Srivastava	$members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
112845005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO
1129e86bdb24SAditya Srivastava	$members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos;
113045005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO_PTR
1131e86bdb24SAditya Srivastava	$members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
11323080ea55SKees Cook	# replace DECLARE_FLEX_ARRAY
11333080ea55SKees Cook	$members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
11348ad72163SMauro Carvalho Chehab	my $declaration = $members;
11358ad72163SMauro Carvalho Chehab
11368ad72163SMauro Carvalho Chehab	# Split nested struct/union elements as newer ones
1137e86bdb24SAditya Srivastava	while ($members =~ m/$struct_members/) {
113884ce5b98SMauro Carvalho Chehab		my $newmember;
113984ce5b98SMauro Carvalho Chehab		my $maintype = $1;
114084ce5b98SMauro Carvalho Chehab		my $ids = $4;
11418ad72163SMauro Carvalho Chehab		my $content = $3;
114284ce5b98SMauro Carvalho Chehab		foreach my $id(split /,/, $ids) {
114384ce5b98SMauro Carvalho Chehab			$newmember .= "$maintype $id; ";
114484ce5b98SMauro Carvalho Chehab
11458ad72163SMauro Carvalho Chehab			$id =~ s/[:\[].*//;
114684ce5b98SMauro Carvalho Chehab			$id =~ s/^\s*\**(\S+)\s*/$1/;
11478ad72163SMauro Carvalho Chehab			foreach my $arg (split /;/, $content) {
11488ad72163SMauro Carvalho Chehab				next if ($arg =~ m/^\s*$/);
11497c0d7e87SMauro Carvalho Chehab				if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
11507c0d7e87SMauro Carvalho Chehab					# pointer-to-function
11517c0d7e87SMauro Carvalho Chehab					my $type = $1;
11527c0d7e87SMauro Carvalho Chehab					my $name = $2;
11537c0d7e87SMauro Carvalho Chehab					my $extra = $3;
11547c0d7e87SMauro Carvalho Chehab					next if (!$name);
11557c0d7e87SMauro Carvalho Chehab					if ($id =~ m/^\s*$/) {
11567c0d7e87SMauro Carvalho Chehab						# anonymous struct/union
11577c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$name$extra; ";
11587c0d7e87SMauro Carvalho Chehab					} else {
11597c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$id.$name$extra; ";
11607c0d7e87SMauro Carvalho Chehab					}
11617c0d7e87SMauro Carvalho Chehab				} else {
116284ce5b98SMauro Carvalho Chehab					my $type;
116384ce5b98SMauro Carvalho Chehab					my $names;
116484ce5b98SMauro Carvalho Chehab					$arg =~ s/^\s+//;
116584ce5b98SMauro Carvalho Chehab					$arg =~ s/\s+$//;
116684ce5b98SMauro Carvalho Chehab					# Handle bitmaps
116784ce5b98SMauro Carvalho Chehab					$arg =~ s/:\s*\d+\s*//g;
116884ce5b98SMauro Carvalho Chehab					# Handle arrays
1169d404d579SMauro Carvalho Chehab					$arg =~ s/\[.*\]//g;
117084ce5b98SMauro Carvalho Chehab					# The type may have multiple words,
117184ce5b98SMauro Carvalho Chehab					# and multiple IDs can be defined, like:
117284ce5b98SMauro Carvalho Chehab					#	const struct foo, *bar, foobar
117384ce5b98SMauro Carvalho Chehab					# So, we remove spaces when parsing the
117484ce5b98SMauro Carvalho Chehab					# names, in order to match just names
117584ce5b98SMauro Carvalho Chehab					# and commas for the names
117684ce5b98SMauro Carvalho Chehab					$arg =~ s/\s*,\s*/,/g;
117784ce5b98SMauro Carvalho Chehab					if ($arg =~ m/(.*)\s+([\S+,]+)/) {
117884ce5b98SMauro Carvalho Chehab						$type = $1;
117984ce5b98SMauro Carvalho Chehab						$names = $2;
118084ce5b98SMauro Carvalho Chehab					} else {
118184ce5b98SMauro Carvalho Chehab						$newmember .= "$arg; ";
118284ce5b98SMauro Carvalho Chehab						next;
118384ce5b98SMauro Carvalho Chehab					}
118484ce5b98SMauro Carvalho Chehab					foreach my $name (split /,/, $names) {
118584ce5b98SMauro Carvalho Chehab						$name =~ s/^\s*\**(\S+)\s*/$1/;
11868ad72163SMauro Carvalho Chehab						next if (($name =~ m/^\s*$/));
11878ad72163SMauro Carvalho Chehab						if ($id =~ m/^\s*$/) {
11888ad72163SMauro Carvalho Chehab							# anonymous struct/union
11898ad72163SMauro Carvalho Chehab							$newmember .= "$type $name; ";
11908ad72163SMauro Carvalho Chehab						} else {
11918ad72163SMauro Carvalho Chehab							$newmember .= "$type $id.$name; ";
11928ad72163SMauro Carvalho Chehab						}
11938ad72163SMauro Carvalho Chehab					}
11947c0d7e87SMauro Carvalho Chehab				}
119584ce5b98SMauro Carvalho Chehab			}
119684ce5b98SMauro Carvalho Chehab		}
1197e86bdb24SAditya Srivastava		$members =~ s/$struct_members/$newmember/;
119884ce5b98SMauro Carvalho Chehab	}
11998ad72163SMauro Carvalho Chehab
12008ad72163SMauro Carvalho Chehab	# Ignore other nested elements, like enums
1201673bb2dfSBen Hutchings	$members =~ s/(\{[^\{\}]*\})//g;
12028ad72163SMauro Carvalho Chehab
1203151c468bSMauro Carvalho Chehab	create_parameterlist($members, ';', $file, $declaration_name);
12041081de2dSMauro Carvalho Chehab	check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
12051da177e4SLinus Torvalds
12068ad72163SMauro Carvalho Chehab	# Adjust declaration for better display
1207673bb2dfSBen Hutchings	$declaration =~ s/([\{;])/$1\n/g;
1208673bb2dfSBen Hutchings	$declaration =~ s/\}\s+;/};/g;
12098ad72163SMauro Carvalho Chehab	# Better handle inlined enums
1210673bb2dfSBen Hutchings	do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
12118ad72163SMauro Carvalho Chehab
12128ad72163SMauro Carvalho Chehab	my @def_args = split /\n/, $declaration;
12138ad72163SMauro Carvalho Chehab	my $level = 1;
12148ad72163SMauro Carvalho Chehab	$declaration = "";
12158ad72163SMauro Carvalho Chehab	foreach my $clause (@def_args) {
12168ad72163SMauro Carvalho Chehab		$clause =~ s/^\s+//;
12178ad72163SMauro Carvalho Chehab		$clause =~ s/\s+$//;
12188ad72163SMauro Carvalho Chehab		$clause =~ s/\s+/ /;
12198ad72163SMauro Carvalho Chehab		next if (!$clause);
1220673bb2dfSBen Hutchings		$level-- if ($clause =~ m/(\})/ && $level > 1);
12218ad72163SMauro Carvalho Chehab		if (!($clause =~ m/^\s*#/)) {
12228ad72163SMauro Carvalho Chehab			$declaration .= "\t" x $level;
12238ad72163SMauro Carvalho Chehab		}
12248ad72163SMauro Carvalho Chehab		$declaration .= "\t" . $clause . "\n";
1225673bb2dfSBen Hutchings		$level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
12268ad72163SMauro Carvalho Chehab	}
12271da177e4SLinus Torvalds	output_declaration($declaration_name,
12281da177e4SLinus Torvalds			   'struct',
12291da177e4SLinus Torvalds			   {'struct' => $declaration_name,
12301da177e4SLinus Torvalds			    'module' => $modulename,
12318ad72163SMauro Carvalho Chehab			    'definition' => $declaration,
12321da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
12331da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
12341da177e4SLinus Torvalds			    'parametertypes' => \%parametertypes,
12351da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
12361da177e4SLinus Torvalds			    'sections' => \%sections,
12371da177e4SLinus Torvalds			    'purpose' => $declaration_purpose,
12381da177e4SLinus Torvalds			    'type' => $decl_type
12391da177e4SLinus Torvalds			   });
12401da177e4SLinus Torvalds    }
12411da177e4SLinus Torvalds    else {
1242d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
12431da177e4SLinus Torvalds	++$errors;
12441da177e4SLinus Torvalds    }
12451da177e4SLinus Torvalds}
12461da177e4SLinus Torvalds
124785afe608SMauro Carvalho Chehab
124885afe608SMauro Carvalho Chehabsub show_warnings($$) {
124985afe608SMauro Carvalho Chehab	my $functype = shift;
125085afe608SMauro Carvalho Chehab	my $name = shift;
125185afe608SMauro Carvalho Chehab
1252eab795ddSMauro Carvalho Chehab	return 0 if (defined($nosymbol_table{$name}));
1253eab795ddSMauro Carvalho Chehab
125485afe608SMauro Carvalho Chehab	return 1 if ($output_selection == OUTPUT_ALL);
125585afe608SMauro Carvalho Chehab
125685afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_EXPORTED) {
125785afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
125885afe608SMauro Carvalho Chehab			return 1;
125985afe608SMauro Carvalho Chehab		} else {
126085afe608SMauro Carvalho Chehab			return 0;
126185afe608SMauro Carvalho Chehab		}
126285afe608SMauro Carvalho Chehab	}
126385afe608SMauro Carvalho Chehab        if ($output_selection == OUTPUT_INTERNAL) {
126485afe608SMauro Carvalho Chehab		if (!($functype eq "function" && defined($function_table{$name}))) {
126585afe608SMauro Carvalho Chehab			return 1;
126685afe608SMauro Carvalho Chehab		} else {
126785afe608SMauro Carvalho Chehab			return 0;
126885afe608SMauro Carvalho Chehab		}
126985afe608SMauro Carvalho Chehab	}
127085afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_INCLUDE) {
127185afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
127285afe608SMauro Carvalho Chehab			return 1;
127385afe608SMauro Carvalho Chehab		} else {
127485afe608SMauro Carvalho Chehab			return 0;
127585afe608SMauro Carvalho Chehab		}
127685afe608SMauro Carvalho Chehab	}
127785afe608SMauro Carvalho Chehab	die("Please add the new output type at show_warnings()");
127885afe608SMauro Carvalho Chehab}
127985afe608SMauro Carvalho Chehab
12801da177e4SLinus Torvaldssub dump_enum($$) {
12811da177e4SLinus Torvalds    my $x = shift;
12821da177e4SLinus Torvalds    my $file = shift;
1283d38c8cfbSMauro Carvalho Chehab    my $members;
1284d38c8cfbSMauro Carvalho Chehab
12851da177e4SLinus Torvalds
1286aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
12874468e21eSConchúr Navid    # strip #define macros inside enums
12884468e21eSConchúr Navid    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1289b6d676dbSRandy Dunlap
1290d38c8cfbSMauro Carvalho Chehab    if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1291d38c8cfbSMauro Carvalho Chehab	$declaration_name = $2;
1292d38c8cfbSMauro Carvalho Chehab	$members = $1;
1293d38c8cfbSMauro Carvalho Chehab    } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
12941da177e4SLinus Torvalds	$declaration_name = $1;
1295d38c8cfbSMauro Carvalho Chehab	$members = $2;
1296d38c8cfbSMauro Carvalho Chehab    }
1297d38c8cfbSMauro Carvalho Chehab
1298ae5b17e4SAndy Shevchenko    if ($members) {
129952042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
13000b54c2e3SMauro Carvalho Chehab	    if ($identifier eq "") {
13010b54c2e3SMauro Carvalho Chehab		print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
13020b54c2e3SMauro Carvalho Chehab	    } else {
130352042e2dSMauro Carvalho Chehab		print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
13040b54c2e3SMauro Carvalho Chehab	    }
130552042e2dSMauro Carvalho Chehab	    return;
130652042e2dSMauro Carvalho Chehab	}
13070b54c2e3SMauro Carvalho Chehab	$declaration_name = "(anonymous)" if ($declaration_name eq "");
130852042e2dSMauro Carvalho Chehab
13095cb5c31cSJohannes Berg	my %_members;
13105cb5c31cSJohannes Berg
1311463a0fdcSMarkus Heiser	$members =~ s/\s+$//;
13121da177e4SLinus Torvalds
13131da177e4SLinus Torvalds	foreach my $arg (split ',', $members) {
13141da177e4SLinus Torvalds	    $arg =~ s/^\s*(\w+).*/$1/;
13151da177e4SLinus Torvalds	    push @parameterlist, $arg;
13161da177e4SLinus Torvalds	    if (!$parameterdescs{$arg}) {
13171da177e4SLinus Torvalds		$parameterdescs{$arg} = $undescribed;
131885afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
13192defb272SMauro Carvalho Chehab			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
13202defb272SMauro Carvalho Chehab		}
13211da177e4SLinus Torvalds	    }
13225cb5c31cSJohannes Berg	    $_members{$arg} = 1;
13235cb5c31cSJohannes Berg	}
13241da177e4SLinus Torvalds
13255cb5c31cSJohannes Berg	while (my ($k, $v) = each %parameterdescs) {
13265cb5c31cSJohannes Berg	    if (!exists($_members{$k})) {
132785afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
13282defb272SMauro Carvalho Chehab		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
13292defb272SMauro Carvalho Chehab		}
13305cb5c31cSJohannes Berg	    }
13311da177e4SLinus Torvalds        }
13321da177e4SLinus Torvalds
13331da177e4SLinus Torvalds	output_declaration($declaration_name,
13341da177e4SLinus Torvalds			   'enum',
13351da177e4SLinus Torvalds			   {'enum' => $declaration_name,
13361da177e4SLinus Torvalds			    'module' => $modulename,
13371da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
13381da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
13391da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
13401da177e4SLinus Torvalds			    'sections' => \%sections,
13411da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
13421da177e4SLinus Torvalds			   });
1343d38c8cfbSMauro Carvalho Chehab    } else {
1344d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse enum!\n";
13451da177e4SLinus Torvalds	++$errors;
13461da177e4SLinus Torvalds    }
13471da177e4SLinus Torvalds}
13481da177e4SLinus Torvalds
13497d2c6b1eSMauro Carvalho Chehabmy $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
13507efc6c42SMauro Carvalho Chehabmy $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
13517efc6c42SMauro Carvalho Chehabmy $typedef_args = qr { \s*\((.*)\); }x;
13527efc6c42SMauro Carvalho Chehab
13537efc6c42SMauro Carvalho Chehabmy $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
13547efc6c42SMauro Carvalho Chehabmy $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
13557efc6c42SMauro Carvalho Chehab
13561da177e4SLinus Torvaldssub dump_typedef($$) {
13571da177e4SLinus Torvalds    my $x = shift;
13581da177e4SLinus Torvalds    my $file = shift;
13591da177e4SLinus Torvalds
1360aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
136183766452SMauro Carvalho Chehab
13627efc6c42SMauro Carvalho Chehab    # Parse function typedef prototypes
13637efc6c42SMauro Carvalho Chehab    if ($x =~ $typedef1 || $x =~ $typedef2) {
136483766452SMauro Carvalho Chehab	$return_type = $1;
136583766452SMauro Carvalho Chehab	$declaration_name = $2;
136683766452SMauro Carvalho Chehab	my $args = $3;
13676b80975cSMauro Carvalho Chehab	$return_type =~ s/^\s+//;
136883766452SMauro Carvalho Chehab
136952042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
137052042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
137152042e2dSMauro Carvalho Chehab	    return;
137252042e2dSMauro Carvalho Chehab	}
137352042e2dSMauro Carvalho Chehab
1374151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
137583766452SMauro Carvalho Chehab
137683766452SMauro Carvalho Chehab	output_declaration($declaration_name,
137783766452SMauro Carvalho Chehab			   'function',
137883766452SMauro Carvalho Chehab			   {'function' => $declaration_name,
137982801d06SMauro Carvalho Chehab			    'typedef' => 1,
138083766452SMauro Carvalho Chehab			    'module' => $modulename,
138183766452SMauro Carvalho Chehab			    'functiontype' => $return_type,
138283766452SMauro Carvalho Chehab			    'parameterlist' => \@parameterlist,
138383766452SMauro Carvalho Chehab			    'parameterdescs' => \%parameterdescs,
138483766452SMauro Carvalho Chehab			    'parametertypes' => \%parametertypes,
138583766452SMauro Carvalho Chehab			    'sectionlist' => \@sectionlist,
138683766452SMauro Carvalho Chehab			    'sections' => \%sections,
138783766452SMauro Carvalho Chehab			    'purpose' => $declaration_purpose
138883766452SMauro Carvalho Chehab			   });
138983766452SMauro Carvalho Chehab	return;
139083766452SMauro Carvalho Chehab    }
139183766452SMauro Carvalho Chehab
13921da177e4SLinus Torvalds    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
13931da177e4SLinus Torvalds	$x =~ s/\(*.\)\s*;$/;/;
13941da177e4SLinus Torvalds	$x =~ s/\[*.\]\s*;$/;/;
13951da177e4SLinus Torvalds    }
13961da177e4SLinus Torvalds
13971da177e4SLinus Torvalds    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
13981da177e4SLinus Torvalds	$declaration_name = $1;
13991da177e4SLinus Torvalds
140052042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
140152042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
140252042e2dSMauro Carvalho Chehab	    return;
140352042e2dSMauro Carvalho Chehab	}
140452042e2dSMauro Carvalho Chehab
14051da177e4SLinus Torvalds	output_declaration($declaration_name,
14061da177e4SLinus Torvalds			   'typedef',
14071da177e4SLinus Torvalds			   {'typedef' => $declaration_name,
14081da177e4SLinus Torvalds			    'module' => $modulename,
14091da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
14101da177e4SLinus Torvalds			    'sections' => \%sections,
14111da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
14121da177e4SLinus Torvalds			   });
14131da177e4SLinus Torvalds    }
14141da177e4SLinus Torvalds    else {
1415d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
14161da177e4SLinus Torvalds	++$errors;
14171da177e4SLinus Torvalds    }
14181da177e4SLinus Torvalds}
14191da177e4SLinus Torvalds
1420a1d94aa5SRandy Dunlapsub save_struct_actual($) {
1421a1d94aa5SRandy Dunlap    my $actual = shift;
1422a1d94aa5SRandy Dunlap
1423a1d94aa5SRandy Dunlap    # strip all spaces from the actual param so that it looks like one string item
1424a1d94aa5SRandy Dunlap    $actual =~ s/\s*//g;
1425a1d94aa5SRandy Dunlap    $struct_actual = $struct_actual . $actual . " ";
1426a1d94aa5SRandy Dunlap}
1427a1d94aa5SRandy Dunlap
1428151c468bSMauro Carvalho Chehabsub create_parameterlist($$$$) {
14291da177e4SLinus Torvalds    my $args = shift;
14301da177e4SLinus Torvalds    my $splitter = shift;
14311da177e4SLinus Torvalds    my $file = shift;
1432151c468bSMauro Carvalho Chehab    my $declaration_name = shift;
14331da177e4SLinus Torvalds    my $type;
14341da177e4SLinus Torvalds    my $param;
14351da177e4SLinus Torvalds
1436a6d3fe77SMartin Waitz    # temporarily replace commas inside function pointer definition
1437e86bdb24SAditya Srivastava    my $arg_expr = qr{\([^\),]+};
1438e86bdb24SAditya Srivastava    while ($args =~ /$arg_expr,/) {
1439e86bdb24SAditya Srivastava	$args =~ s/($arg_expr),/$1#/g;
14401da177e4SLinus Torvalds    }
14411da177e4SLinus Torvalds
14421da177e4SLinus Torvalds    foreach my $arg (split($splitter, $args)) {
14431da177e4SLinus Torvalds	# strip comments
14441da177e4SLinus Torvalds	$arg =~ s/\/\*.*\*\///;
14451da177e4SLinus Torvalds	# strip leading/trailing spaces
14461da177e4SLinus Torvalds	$arg =~ s/^\s*//;
14471da177e4SLinus Torvalds	$arg =~ s/\s*$//;
14481da177e4SLinus Torvalds	$arg =~ s/\s+/ /;
14491da177e4SLinus Torvalds
14501da177e4SLinus Torvalds	if ($arg =~ /^#/) {
14511da177e4SLinus Torvalds	    # Treat preprocessor directive as a typeless variable just to fill
14521da177e4SLinus Torvalds	    # corresponding data structures "correctly". Catch it later in
14531da177e4SLinus Torvalds	    # output_* subs.
1454ed8348e2SMauro Carvalho Chehab	    push_parameter($arg, "", "", $file);
145500d62961SRichard Kennedy	} elsif ($arg =~ m/\(.+\)\s*\(/) {
14561da177e4SLinus Torvalds	    # pointer-to-function
14571da177e4SLinus Torvalds	    $arg =~ tr/#/,/;
1458336ced2dSAditya Srivastava	    $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
14591da177e4SLinus Torvalds	    $param = $1;
14601da177e4SLinus Torvalds	    $type = $arg;
146100d62961SRichard Kennedy	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1462a1d94aa5SRandy Dunlap	    save_struct_actual($param);
1463ed8348e2SMauro Carvalho Chehab	    push_parameter($param, $type, $arg, $file, $declaration_name);
1464aeec46b9SMartin Waitz	} elsif ($arg) {
14651da177e4SLinus Torvalds	    $arg =~ s/\s*:\s*/:/g;
14661da177e4SLinus Torvalds	    $arg =~ s/\s*\[/\[/g;
14671da177e4SLinus Torvalds
14681da177e4SLinus Torvalds	    my @args = split('\s*,\s*', $arg);
14691da177e4SLinus Torvalds	    if ($args[0] =~ m/\*/) {
14701da177e4SLinus Torvalds		$args[0] =~ s/(\*+)\s*/ $1/;
14711da177e4SLinus Torvalds	    }
1472884f2810SBorislav Petkov
1473884f2810SBorislav Petkov	    my @first_arg;
1474884f2810SBorislav Petkov	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1475884f2810SBorislav Petkov		    shift @args;
1476884f2810SBorislav Petkov		    push(@first_arg, split('\s+', $1));
1477884f2810SBorislav Petkov		    push(@first_arg, $2);
1478884f2810SBorislav Petkov	    } else {
1479884f2810SBorislav Petkov		    @first_arg = split('\s+', shift @args);
1480884f2810SBorislav Petkov	    }
1481884f2810SBorislav Petkov
14821da177e4SLinus Torvalds	    unshift(@args, pop @first_arg);
14831da177e4SLinus Torvalds	    $type = join " ", @first_arg;
14841da177e4SLinus Torvalds
14851da177e4SLinus Torvalds	    foreach $param (@args) {
14861da177e4SLinus Torvalds		if ($param =~ m/^(\*+)\s*(.*)/) {
1487a1d94aa5SRandy Dunlap		    save_struct_actual($2);
1488ed8348e2SMauro Carvalho Chehab
1489ed8348e2SMauro Carvalho Chehab		    push_parameter($2, "$type $1", $arg, $file, $declaration_name);
14901da177e4SLinus Torvalds		}
14911da177e4SLinus Torvalds		elsif ($param =~ m/(.*?):(\d+)/) {
14927b97887eSRandy Dunlap		    if ($type ne "") { # skip unnamed bit-fields
1493a1d94aa5SRandy Dunlap			save_struct_actual($1);
1494ed8348e2SMauro Carvalho Chehab			push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
14951da177e4SLinus Torvalds		    }
14967b97887eSRandy Dunlap		}
14971da177e4SLinus Torvalds		else {
1498a1d94aa5SRandy Dunlap		    save_struct_actual($param);
1499ed8348e2SMauro Carvalho Chehab		    push_parameter($param, $type, $arg, $file, $declaration_name);
15001da177e4SLinus Torvalds		}
15011da177e4SLinus Torvalds	    }
15021da177e4SLinus Torvalds	}
15031da177e4SLinus Torvalds    }
15041da177e4SLinus Torvalds}
15051da177e4SLinus Torvalds
1506ed8348e2SMauro Carvalho Chehabsub push_parameter($$$$$) {
15071da177e4SLinus Torvalds	my $param = shift;
15081da177e4SLinus Torvalds	my $type = shift;
1509ed8348e2SMauro Carvalho Chehab	my $org_arg = shift;
15101da177e4SLinus Torvalds	my $file = shift;
1511151c468bSMauro Carvalho Chehab	my $declaration_name = shift;
15121da177e4SLinus Torvalds
15135f8c7c98SRandy Dunlap	if (($anon_struct_union == 1) && ($type eq "") &&
15145f8c7c98SRandy Dunlap	    ($param eq "}")) {
15155f8c7c98SRandy Dunlap		return;		# ignore the ending }; from anon. struct/union
15165f8c7c98SRandy Dunlap	}
15175f8c7c98SRandy Dunlap
15185f8c7c98SRandy Dunlap	$anon_struct_union = 0;
1519f9b5c530SMauro Carvalho Chehab	$param =~ s/[\[\)].*//;
15201da177e4SLinus Torvalds
1521a6d3fe77SMartin Waitz	if ($type eq "" && $param =~ /\.\.\.$/)
15221da177e4SLinus Torvalds	{
1523c950a173SSilvio Fricke	    if (!$param =~ /\w\.\.\.$/) {
1524c950a173SSilvio Fricke	      # handles unnamed variable parameters
1525ef00028bSJonathan Corbet	      $param = "...";
1526c950a173SSilvio Fricke	    }
152743756e34SJonathan Neuschäfer	    elsif ($param =~ /\w\.\.\.$/) {
152843756e34SJonathan Neuschäfer	      # for named variable parameters of the form `x...`, remove the dots
152943756e34SJonathan Neuschäfer	      $param =~ s/\.\.\.$//;
153043756e34SJonathan Neuschäfer	    }
1531ced69090SRandy Dunlap	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1532a6d3fe77SMartin Waitz		$parameterdescs{$param} = "variable arguments";
15331da177e4SLinus Torvalds	    }
1534ced69090SRandy Dunlap	}
15351da177e4SLinus Torvalds	elsif ($type eq "" && ($param eq "" or $param eq "void"))
15361da177e4SLinus Torvalds	{
15371da177e4SLinus Torvalds	    $param="void";
15381da177e4SLinus Torvalds	    $parameterdescs{void} = "no arguments";
15391da177e4SLinus Torvalds	}
1540134fe01bSRandy Dunlap	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1541134fe01bSRandy Dunlap	# handle unnamed (anonymous) union or struct:
1542134fe01bSRandy Dunlap	{
1543134fe01bSRandy Dunlap		$type = $param;
1544134fe01bSRandy Dunlap		$param = "{unnamed_" . $param . "}";
1545134fe01bSRandy Dunlap		$parameterdescs{$param} = "anonymous\n";
15465f8c7c98SRandy Dunlap		$anon_struct_union = 1;
1547134fe01bSRandy Dunlap	}
1548134fe01bSRandy Dunlap
1549a6d3fe77SMartin Waitz	# warn if parameter has no description
1550134fe01bSRandy Dunlap	# (but ignore ones starting with # as these are not parameters
1551134fe01bSRandy Dunlap	# but inline preprocessor statements);
1552151c468bSMauro Carvalho Chehab	# Note: It will also ignore void params and unnamed structs/unions
1553f9b5c530SMauro Carvalho Chehab	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1554f9b5c530SMauro Carvalho Chehab		$parameterdescs{$param} = $undescribed;
15551da177e4SLinus Torvalds
1556be5cd20cSJonathan Corbet	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1557151c468bSMauro Carvalho Chehab			print STDERR
1558151c468bSMauro Carvalho Chehab			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
15591da177e4SLinus Torvalds			++$warnings;
15601da177e4SLinus Torvalds		}
15612defb272SMauro Carvalho Chehab	}
15621da177e4SLinus Torvalds
156325985edcSLucas De Marchi	# strip spaces from $param so that it is one continuous string
1564e34e7dbbSRandy Dunlap	# on @parameterlist;
1565e34e7dbbSRandy Dunlap	# this fixes a problem where check_sections() cannot find
1566e34e7dbbSRandy Dunlap	# a parameter like "addr[6 + 2]" because it actually appears
1567e34e7dbbSRandy Dunlap	# as "addr[6", "+", "2]" on the parameter list;
1568e34e7dbbSRandy Dunlap	# but it's better to maintain the param string unchanged for output,
1569e34e7dbbSRandy Dunlap	# so just weaken the string compare in check_sections() to ignore
1570e34e7dbbSRandy Dunlap	# "[blah" in a parameter string;
1571e34e7dbbSRandy Dunlap	###$param =~ s/\s*//g;
15721da177e4SLinus Torvalds	push @parameterlist, $param;
1573ed8348e2SMauro Carvalho Chehab	$org_arg =~ s/\s\s+/ /g;
1574ed8348e2SMauro Carvalho Chehab	$parametertypes{$param} = $org_arg;
15751da177e4SLinus Torvalds}
15761da177e4SLinus Torvalds
15771081de2dSMauro Carvalho Chehabsub check_sections($$$$$) {
15781081de2dSMauro Carvalho Chehab	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
1579a1d94aa5SRandy Dunlap	my @sects = split ' ', $sectcheck;
1580a1d94aa5SRandy Dunlap	my @prms = split ' ', $prmscheck;
1581a1d94aa5SRandy Dunlap	my $err;
1582a1d94aa5SRandy Dunlap	my ($px, $sx);
1583a1d94aa5SRandy Dunlap	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
1584a1d94aa5SRandy Dunlap
1585a1d94aa5SRandy Dunlap	foreach $sx (0 .. $#sects) {
1586a1d94aa5SRandy Dunlap		$err = 1;
1587a1d94aa5SRandy Dunlap		foreach $px (0 .. $#prms) {
1588a1d94aa5SRandy Dunlap			$prm_clean = $prms[$px];
1589a1d94aa5SRandy Dunlap			$prm_clean =~ s/\[.*\]//;
1590e86bdb24SAditya Srivastava			$prm_clean =~ s/$attribute//i;
1591e34e7dbbSRandy Dunlap			# ignore array size in a parameter string;
1592e34e7dbbSRandy Dunlap			# however, the original param string may contain
1593e34e7dbbSRandy Dunlap			# spaces, e.g.:  addr[6 + 2]
1594e34e7dbbSRandy Dunlap			# and this appears in @prms as "addr[6" since the
1595e34e7dbbSRandy Dunlap			# parameter list is split at spaces;
1596e34e7dbbSRandy Dunlap			# hence just ignore "[..." for the sections check;
1597e34e7dbbSRandy Dunlap			$prm_clean =~ s/\[.*//;
1598e34e7dbbSRandy Dunlap
1599a1d94aa5SRandy Dunlap			##$prm_clean =~ s/^\**//;
1600a1d94aa5SRandy Dunlap			if ($prm_clean eq $sects[$sx]) {
1601a1d94aa5SRandy Dunlap				$err = 0;
1602a1d94aa5SRandy Dunlap				last;
1603a1d94aa5SRandy Dunlap			}
1604a1d94aa5SRandy Dunlap		}
1605a1d94aa5SRandy Dunlap		if ($err) {
1606a1d94aa5SRandy Dunlap			if ($decl_type eq "function") {
1607d40e1e65SBart Van Assche				print STDERR "${file}:$.: warning: " .
1608a1d94aa5SRandy Dunlap					"Excess function parameter " .
1609a1d94aa5SRandy Dunlap					"'$sects[$sx]' " .
1610a1d94aa5SRandy Dunlap					"description in '$decl_name'\n";
1611a1d94aa5SRandy Dunlap				++$warnings;
1612a1d94aa5SRandy Dunlap			}
1613a1d94aa5SRandy Dunlap		}
1614a1d94aa5SRandy Dunlap	}
1615a1d94aa5SRandy Dunlap}
1616a1d94aa5SRandy Dunlap
16171da177e4SLinus Torvalds##
16184092bac7SYacine Belkadi# Checks the section describing the return value of a function.
16194092bac7SYacine Belkadisub check_return_section {
16204092bac7SYacine Belkadi        my $file = shift;
16214092bac7SYacine Belkadi        my $declaration_name = shift;
16224092bac7SYacine Belkadi        my $return_type = shift;
16234092bac7SYacine Belkadi
16244092bac7SYacine Belkadi        # Ignore an empty return type (It's a macro)
16254092bac7SYacine Belkadi        # Ignore functions with a "void" return type. (But don't ignore "void *")
16264092bac7SYacine Belkadi        if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
16274092bac7SYacine Belkadi                return;
16284092bac7SYacine Belkadi        }
16294092bac7SYacine Belkadi
16304092bac7SYacine Belkadi        if (!defined($sections{$section_return}) ||
16314092bac7SYacine Belkadi            $sections{$section_return} eq "") {
1632d40e1e65SBart Van Assche                print STDERR "${file}:$.: warning: " .
16334092bac7SYacine Belkadi                        "No description found for return value of " .
16344092bac7SYacine Belkadi                        "'$declaration_name'\n";
16354092bac7SYacine Belkadi                ++$warnings;
16364092bac7SYacine Belkadi        }
16374092bac7SYacine Belkadi}
16384092bac7SYacine Belkadi
16394092bac7SYacine Belkadi##
16401da177e4SLinus Torvalds# takes a function prototype and the name of the current file being
16411da177e4SLinus Torvalds# processed and spits out all the details stored in the global
16421da177e4SLinus Torvalds# arrays/hashes.
16431da177e4SLinus Torvaldssub dump_function($$) {
16441da177e4SLinus Torvalds    my $prototype = shift;
16451da177e4SLinus Torvalds    my $file = shift;
1646cbb4d3e6SHoria Geanta    my $noret = 0;
16471da177e4SLinus Torvalds
16485ef09c96SMauro Carvalho Chehab    print_lineno($new_start_line);
16495eb6b4b3SMauro Carvalho Chehab
16501da177e4SLinus Torvalds    $prototype =~ s/^static +//;
16511da177e4SLinus Torvalds    $prototype =~ s/^extern +//;
16524dc3b16bSPavel Pisa    $prototype =~ s/^asmlinkage +//;
16531da177e4SLinus Torvalds    $prototype =~ s/^inline +//;
16541da177e4SLinus Torvalds    $prototype =~ s/^__inline__ +//;
165532e79401SRandy Dunlap    $prototype =~ s/^__inline +//;
165632e79401SRandy Dunlap    $prototype =~ s/^__always_inline +//;
165732e79401SRandy Dunlap    $prototype =~ s/^noinline +//;
165874fc5c65SRandy Dunlap    $prototype =~ s/__init +//;
165920072205SRandy Dunlap    $prototype =~ s/__init_or_module +//;
166080342d48SMatthew Wilcox    $prototype =~ s/__deprecated +//;
1661084aa001SAditya Srivastava    $prototype =~ s/__flatten +//;
1662270a0096SRandy Dunlap    $prototype =~ s/__meminit +//;
166370c95b00SRandy Dunlap    $prototype =~ s/__must_check +//;
16640df7c0e3SRandy Dunlap    $prototype =~ s/__weak +//;
16650891f959SMatthew Wilcox    $prototype =~ s/__sched +//;
166695e760cbSRandy Dunlap    $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1667a40a8a11SKees Cook    $prototype =~ s/__alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//;
1668cbb4d3e6SHoria Geanta    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1669084aa001SAditya Srivastava    $prototype =~ s/__attribute_const__ +//;
1670b1aaa546SPaolo Bonzini    $prototype =~ s/__attribute__\s*\(\(
1671b1aaa546SPaolo Bonzini            (?:
1672b1aaa546SPaolo Bonzini                 [\w\s]++          # attribute name
1673b1aaa546SPaolo Bonzini                 (?:\([^)]*+\))?   # attribute arguments
1674b1aaa546SPaolo Bonzini                 \s*+,?            # optional comma at the end
1675b1aaa546SPaolo Bonzini            )+
1676b1aaa546SPaolo Bonzini          \)\)\s+//x;
16771da177e4SLinus Torvalds
16781da177e4SLinus Torvalds    # Yes, this truly is vile.  We are looking for:
16791da177e4SLinus Torvalds    # 1. Return type (may be nothing if we're looking at a macro)
16801da177e4SLinus Torvalds    # 2. Function name
16811da177e4SLinus Torvalds    # 3. Function parameters.
16821da177e4SLinus Torvalds    #
16831da177e4SLinus Torvalds    # All the while we have to watch out for function pointer parameters
16841da177e4SLinus Torvalds    # (which IIRC is what the two sections are for), C types (these
16851da177e4SLinus Torvalds    # regexps don't even start to express all the possibilities), and
16861da177e4SLinus Torvalds    # so on.
16871da177e4SLinus Torvalds    #
16881da177e4SLinus Torvalds    # If you mess with these regexps, it's a good idea to check that
16891da177e4SLinus Torvalds    # the following functions' documentation still comes out right:
16901da177e4SLinus Torvalds    # - parport_register_device (function pointer parameters)
16911da177e4SLinus Torvalds    # - atomic_set (macro)
16929598f91fSMartin Waitz    # - pci_match_device, __copy_to_user (long return type)
1693e86bdb24SAditya Srivastava    my $name = qr{[a-zA-Z0-9_~:]+};
1694e86bdb24SAditya Srivastava    my $prototype_end1 = qr{[^\(]*};
1695e86bdb24SAditya Srivastava    my $prototype_end2 = qr{[^\{]*};
1696e86bdb24SAditya Srivastava    my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)};
1697e86bdb24SAditya Srivastava    my $type1 = qr{[\w\s]+};
1698e86bdb24SAditya Srivastava    my $type2 = qr{$type1\*+};
16991da177e4SLinus Torvalds
1700e86bdb24SAditya Srivastava    if ($define && $prototype =~ m/^()($name)\s+/) {
1701cbb4d3e6SHoria Geanta        # This is an object-like macro, it has no return type and no parameter
1702cbb4d3e6SHoria Geanta        # list.
1703cbb4d3e6SHoria Geanta        # Function-like macros are not allowed to have spaces between
1704cbb4d3e6SHoria Geanta        # declaration_name and opening parenthesis (notice the \s+).
1705cbb4d3e6SHoria Geanta        $return_type = $1;
1706cbb4d3e6SHoria Geanta        $declaration_name = $2;
1707cbb4d3e6SHoria Geanta        $noret = 1;
1708e86bdb24SAditya Srivastava    } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
1709e86bdb24SAditya Srivastava	$prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1710e86bdb24SAditya Srivastava	$prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/)  {
17111da177e4SLinus Torvalds	$return_type = $1;
17121da177e4SLinus Torvalds	$declaration_name = $2;
17131da177e4SLinus Torvalds	my $args = $3;
17141da177e4SLinus Torvalds
1715151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
17161da177e4SLinus Torvalds    } else {
1717d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
17181da177e4SLinus Torvalds	return;
17191da177e4SLinus Torvalds    }
17201da177e4SLinus Torvalds
172152042e2dSMauro Carvalho Chehab    if ($identifier ne $declaration_name) {
172252042e2dSMauro Carvalho Chehab	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
172352042e2dSMauro Carvalho Chehab	return;
172452042e2dSMauro Carvalho Chehab    }
172552042e2dSMauro Carvalho Chehab
1726a1d94aa5SRandy Dunlap    my $prms = join " ", @parameterlist;
17271081de2dSMauro Carvalho Chehab    check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1728a1d94aa5SRandy Dunlap
17294092bac7SYacine Belkadi    # This check emits a lot of warnings at the moment, because many
17304092bac7SYacine Belkadi    # functions don't have a 'Return' doc section. So until the number
17314092bac7SYacine Belkadi    # of warnings goes sufficiently down, the check is only performed in
17324092bac7SYacine Belkadi    # verbose mode.
17334092bac7SYacine Belkadi    # TODO: always perform the check.
1734cbb4d3e6SHoria Geanta    if ($verbose && !$noret) {
17354092bac7SYacine Belkadi	    check_return_section($file, $declaration_name, $return_type);
17364092bac7SYacine Belkadi    }
17374092bac7SYacine Belkadi
173847bcacfdSMauro Carvalho Chehab    # The function parser can be called with a typedef parameter.
173947bcacfdSMauro Carvalho Chehab    # Handle it.
174047bcacfdSMauro Carvalho Chehab    if ($return_type =~ /typedef/) {
174147bcacfdSMauro Carvalho Chehab	output_declaration($declaration_name,
174247bcacfdSMauro Carvalho Chehab			   'function',
174347bcacfdSMauro Carvalho Chehab			   {'function' => $declaration_name,
174447bcacfdSMauro Carvalho Chehab			    'typedef' => 1,
174547bcacfdSMauro Carvalho Chehab			    'module' => $modulename,
174647bcacfdSMauro Carvalho Chehab			    'functiontype' => $return_type,
174747bcacfdSMauro Carvalho Chehab			    'parameterlist' => \@parameterlist,
174847bcacfdSMauro Carvalho Chehab			    'parameterdescs' => \%parameterdescs,
174947bcacfdSMauro Carvalho Chehab			    'parametertypes' => \%parametertypes,
175047bcacfdSMauro Carvalho Chehab			    'sectionlist' => \@sectionlist,
175147bcacfdSMauro Carvalho Chehab			    'sections' => \%sections,
175247bcacfdSMauro Carvalho Chehab			    'purpose' => $declaration_purpose
175347bcacfdSMauro Carvalho Chehab			   });
175447bcacfdSMauro Carvalho Chehab    } else {
17551da177e4SLinus Torvalds	output_declaration($declaration_name,
17561da177e4SLinus Torvalds			   'function',
17571da177e4SLinus Torvalds			   {'function' => $declaration_name,
17581da177e4SLinus Torvalds			    'module' => $modulename,
17591da177e4SLinus Torvalds			    'functiontype' => $return_type,
17601da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
17611da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
17621da177e4SLinus Torvalds			    'parametertypes' => \%parametertypes,
17631da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
17641da177e4SLinus Torvalds			    'sections' => \%sections,
17651da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
17661da177e4SLinus Torvalds			   });
17671da177e4SLinus Torvalds    }
176847bcacfdSMauro Carvalho Chehab}
17691da177e4SLinus Torvalds
17701da177e4SLinus Torvaldssub reset_state {
17711da177e4SLinus Torvalds    $function = "";
17721da177e4SLinus Torvalds    %parameterdescs = ();
17731da177e4SLinus Torvalds    %parametertypes = ();
17741da177e4SLinus Torvalds    @parameterlist = ();
17751da177e4SLinus Torvalds    %sections = ();
17761da177e4SLinus Torvalds    @sectionlist = ();
1777a1d94aa5SRandy Dunlap    $sectcheck = "";
1778a1d94aa5SRandy Dunlap    $struct_actual = "";
17791da177e4SLinus Torvalds    $prototype = "";
17801da177e4SLinus Torvalds
178148af606aSJani Nikula    $state = STATE_NORMAL;
178248af606aSJani Nikula    $inline_doc_state = STATE_INLINE_NA;
17831da177e4SLinus Torvalds}
17841da177e4SLinus Torvalds
178556afb0f8SJason Baronsub tracepoint_munge($) {
178656afb0f8SJason Baron	my $file = shift;
178756afb0f8SJason Baron	my $tracepointname = 0;
178856afb0f8SJason Baron	my $tracepointargs = 0;
178956afb0f8SJason Baron
179056afb0f8SJason Baron	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
179156afb0f8SJason Baron		$tracepointname = $1;
179256afb0f8SJason Baron	}
17933a9089fdSJason Baron	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
17943a9089fdSJason Baron		$tracepointname = $1;
17953a9089fdSJason Baron	}
17963a9089fdSJason Baron	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
17973a9089fdSJason Baron		$tracepointname = $2;
17983a9089fdSJason Baron	}
17993a9089fdSJason Baron	$tracepointname =~ s/^\s+//; #strip leading whitespace
180056afb0f8SJason Baron	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
180156afb0f8SJason Baron		$tracepointargs = $1;
180256afb0f8SJason Baron	}
180356afb0f8SJason Baron	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1804d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
180556afb0f8SJason Baron			     "$prototype\n";
180656afb0f8SJason Baron	} else {
180756afb0f8SJason Baron		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
180852042e2dSMauro Carvalho Chehab		$identifier = "trace_$identifier";
180956afb0f8SJason Baron	}
181056afb0f8SJason Baron}
181156afb0f8SJason Baron
1812b4870bc5SRandy Dunlapsub syscall_munge() {
1813b4870bc5SRandy Dunlap	my $void = 0;
1814b4870bc5SRandy Dunlap
18157c9aa015SMauro Carvalho Chehab	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1816b4870bc5SRandy Dunlap##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1817b4870bc5SRandy Dunlap	if ($prototype =~ m/SYSCALL_DEFINE0/) {
1818b4870bc5SRandy Dunlap		$void = 1;
1819b4870bc5SRandy Dunlap##		$prototype = "long sys_$1(void)";
1820b4870bc5SRandy Dunlap	}
1821b4870bc5SRandy Dunlap
1822b4870bc5SRandy Dunlap	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1823b4870bc5SRandy Dunlap	if ($prototype =~ m/long (sys_.*?),/) {
1824b4870bc5SRandy Dunlap		$prototype =~ s/,/\(/;
1825b4870bc5SRandy Dunlap	} elsif ($void) {
1826b4870bc5SRandy Dunlap		$prototype =~ s/\)/\(void\)/;
1827b4870bc5SRandy Dunlap	}
1828b4870bc5SRandy Dunlap
1829b4870bc5SRandy Dunlap	# now delete all of the odd-number commas in $prototype
1830b4870bc5SRandy Dunlap	# so that arg types & arg names don't have a comma between them
1831b4870bc5SRandy Dunlap	my $count = 0;
1832b4870bc5SRandy Dunlap	my $len = length($prototype);
1833b4870bc5SRandy Dunlap	if ($void) {
1834b4870bc5SRandy Dunlap		$len = 0;	# skip the for-loop
1835b4870bc5SRandy Dunlap	}
1836b4870bc5SRandy Dunlap	for (my $ix = 0; $ix < $len; $ix++) {
1837b4870bc5SRandy Dunlap		if (substr($prototype, $ix, 1) eq ',') {
1838b4870bc5SRandy Dunlap			$count++;
1839b4870bc5SRandy Dunlap			if ($count % 2 == 1) {
1840b4870bc5SRandy Dunlap				substr($prototype, $ix, 1) = ' ';
1841b4870bc5SRandy Dunlap			}
1842b4870bc5SRandy Dunlap		}
1843b4870bc5SRandy Dunlap	}
1844b4870bc5SRandy Dunlap}
1845b4870bc5SRandy Dunlap
1846b7afa92bSDaniel Vettersub process_proto_function($$) {
18471da177e4SLinus Torvalds    my $x = shift;
18481da177e4SLinus Torvalds    my $file = shift;
18491da177e4SLinus Torvalds
185051f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
185151f5a0c8SRandy Dunlap
1852890c78c2SRandy Dunlap    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
18531da177e4SLinus Torvalds	# do nothing
18541da177e4SLinus Torvalds    }
18551da177e4SLinus Torvalds    elsif ($x =~ /([^\{]*)/) {
18561da177e4SLinus Torvalds	$prototype .= $1;
18571da177e4SLinus Torvalds    }
1858b4870bc5SRandy Dunlap
1859890c78c2SRandy Dunlap    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
18601da177e4SLinus Torvalds	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
18611da177e4SLinus Torvalds	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
18621da177e4SLinus Torvalds	$prototype =~ s@^\s+@@gos; # strip leading spaces
18637ae281b0SMauro Carvalho Chehab
18647ae281b0SMauro Carvalho Chehab	 # Handle prototypes for function pointers like:
18657ae281b0SMauro Carvalho Chehab	 # int (*pcs_config)(struct foo)
18667ae281b0SMauro Carvalho Chehab	$prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
18677ae281b0SMauro Carvalho Chehab
1868b4870bc5SRandy Dunlap	if ($prototype =~ /SYSCALL_DEFINE/) {
1869b4870bc5SRandy Dunlap		syscall_munge();
1870b4870bc5SRandy Dunlap	}
18713a9089fdSJason Baron	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
18723a9089fdSJason Baron	    $prototype =~ /DEFINE_SINGLE_EVENT/)
18733a9089fdSJason Baron	{
187456afb0f8SJason Baron		tracepoint_munge($file);
187556afb0f8SJason Baron	}
18761da177e4SLinus Torvalds	dump_function($prototype, $file);
18771da177e4SLinus Torvalds	reset_state();
18781da177e4SLinus Torvalds    }
18791da177e4SLinus Torvalds}
18801da177e4SLinus Torvalds
1881b7afa92bSDaniel Vettersub process_proto_type($$) {
18821da177e4SLinus Torvalds    my $x = shift;
18831da177e4SLinus Torvalds    my $file = shift;
18841da177e4SLinus Torvalds
18851da177e4SLinus Torvalds    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
18861da177e4SLinus Torvalds    $x =~ s@^\s+@@gos; # strip leading spaces
18871da177e4SLinus Torvalds    $x =~ s@\s+$@@gos; # strip trailing spaces
188851f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
188951f5a0c8SRandy Dunlap
18901da177e4SLinus Torvalds    if ($x =~ /^#/) {
18911da177e4SLinus Torvalds	# To distinguish preprocessor directive from regular declaration later.
18921da177e4SLinus Torvalds	$x .= ";";
18931da177e4SLinus Torvalds    }
18941da177e4SLinus Torvalds
18951da177e4SLinus Torvalds    while (1) {
1896673bb2dfSBen Hutchings	if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
1897463a0fdcSMarkus Heiser            if( length $prototype ) {
1898463a0fdcSMarkus Heiser                $prototype .= " "
1899463a0fdcSMarkus Heiser            }
19001da177e4SLinus Torvalds	    $prototype .= $1 . $2;
19011da177e4SLinus Torvalds	    ($2 eq '{') && $brcount++;
19021da177e4SLinus Torvalds	    ($2 eq '}') && $brcount--;
19031da177e4SLinus Torvalds	    if (($2 eq ';') && ($brcount == 0)) {
19041da177e4SLinus Torvalds		dump_declaration($prototype, $file);
19051da177e4SLinus Torvalds		reset_state();
19061da177e4SLinus Torvalds		last;
19071da177e4SLinus Torvalds	    }
19081da177e4SLinus Torvalds	    $x = $3;
19091da177e4SLinus Torvalds	} else {
19101da177e4SLinus Torvalds	    $prototype .= $x;
19111da177e4SLinus Torvalds	    last;
19121da177e4SLinus Torvalds	}
19131da177e4SLinus Torvalds    }
19141da177e4SLinus Torvalds}
19151da177e4SLinus Torvalds
19166b5b55f6SRandy Dunlap
19171ad560e4SJani Nikulasub map_filename($) {
19181ad560e4SJani Nikula    my $file;
19191ad560e4SJani Nikula    my ($orig_file) = @_;
19201ad560e4SJani Nikula
19211ad560e4SJani Nikula    if (defined($ENV{'SRCTREE'})) {
19221ad560e4SJani Nikula	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
19231ad560e4SJani Nikula    } else {
19241ad560e4SJani Nikula	$file = $orig_file;
19251ad560e4SJani Nikula    }
19261ad560e4SJani Nikula
19271ad560e4SJani Nikula    if (defined($source_map{$file})) {
19281ad560e4SJani Nikula	$file = $source_map{$file};
19291ad560e4SJani Nikula    }
19301ad560e4SJani Nikula
19311ad560e4SJani Nikula    return $file;
19321ad560e4SJani Nikula}
19331ad560e4SJani Nikula
193488c2b57dSJani Nikulasub process_export_file($) {
193588c2b57dSJani Nikula    my ($orig_file) = @_;
193688c2b57dSJani Nikula    my $file = map_filename($orig_file);
193788c2b57dSJani Nikula
193888c2b57dSJani Nikula    if (!open(IN,"<$file")) {
193988c2b57dSJani Nikula	print STDERR "Error: Cannot open file $file\n";
194088c2b57dSJani Nikula	++$errors;
194188c2b57dSJani Nikula	return;
194288c2b57dSJani Nikula    }
194388c2b57dSJani Nikula
194488c2b57dSJani Nikula    while (<IN>) {
194588c2b57dSJani Nikula	if (/$export_symbol/) {
1946eab795ddSMauro Carvalho Chehab	    next if (defined($nosymbol_table{$2}));
194788c2b57dSJani Nikula	    $function_table{$2} = 1;
194888c2b57dSJani Nikula	}
194988c2b57dSJani Nikula    }
195088c2b57dSJani Nikula
195188c2b57dSJani Nikula    close(IN);
195288c2b57dSJani Nikula}
195388c2b57dSJani Nikula
195407048d13SJonathan Corbet#
195507048d13SJonathan Corbet# Parsers for the various processing states.
195607048d13SJonathan Corbet#
195707048d13SJonathan Corbet# STATE_NORMAL: looking for the /** to begin everything.
195807048d13SJonathan Corbet#
195907048d13SJonathan Corbetsub process_normal() {
19601da177e4SLinus Torvalds    if (/$doc_start/o) {
196148af606aSJani Nikula	$state = STATE_NAME;	# next line is always the function name
1962850622dfSRandy Dunlap	$in_doc_sect = 0;
19630b0f5f29SDaniel Vetter	$declaration_start_line = $. + 1;
19641da177e4SLinus Torvalds    }
196507048d13SJonathan Corbet}
196607048d13SJonathan Corbet
19673cac2bc4SJonathan Corbet#
19683cac2bc4SJonathan Corbet# STATE_NAME: Looking for the "name - description" line
19693cac2bc4SJonathan Corbet#
19703cac2bc4SJonathan Corbetsub process_name($$) {
19713cac2bc4SJonathan Corbet    my $file = shift;
19721da177e4SLinus Torvalds    my $descr;
19731da177e4SLinus Torvalds
19741da177e4SLinus Torvalds    if (/$doc_block/o) {
197548af606aSJani Nikula	$state = STATE_DOCBLOCK;
19761da177e4SLinus Torvalds	$contents = "";
19775ef09c96SMauro Carvalho Chehab	$new_start_line = $.;
19780b0f5f29SDaniel Vetter
19791da177e4SLinus Torvalds	if ( $1 eq "" ) {
19801da177e4SLinus Torvalds	    $section = $section_intro;
19811da177e4SLinus Torvalds	} else {
19821da177e4SLinus Torvalds	    $section = $1;
19831da177e4SLinus Torvalds	}
198452042e2dSMauro Carvalho Chehab    } elsif (/$doc_decl/o) {
19851da177e4SLinus Torvalds	$identifier = $1;
19863e58e839SAditya Srivastava	my $is_kernel_comment = 0;
1987e86bdb24SAditya Srivastava	my $decl_start = qr{$doc_com};
1988f9bbc12cSAditya Srivastava	# test for pointer declaration type, foo * bar() - desc
1989f9bbc12cSAditya Srivastava	my $fn_type = qr{\w+\s*\*\s*};
1990f9bbc12cSAditya Srivastava	my $parenthesis = qr{\(\w*\)};
1991f9bbc12cSAditya Srivastava	my $decl_end = qr{[-:].*};
1992e86bdb24SAditya Srivastava	if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
19931da177e4SLinus Torvalds	    $identifier = $1;
19941da177e4SLinus Torvalds	}
199552042e2dSMauro Carvalho Chehab	if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
199652042e2dSMauro Carvalho Chehab	    $decl_type = $1;
199752042e2dSMauro Carvalho Chehab	    $identifier = $2;
19983e58e839SAditya Srivastava	    $is_kernel_comment = 1;
199952042e2dSMauro Carvalho Chehab	}
2000f9bbc12cSAditya Srivastava	# Look for foo() or static void foo() - description; or misspelt
2001f9bbc12cSAditya Srivastava	# identifier
2002e86bdb24SAditya Srivastava	elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
2003e86bdb24SAditya Srivastava	    /^$decl_start$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) {
2004f9bbc12cSAditya Srivastava	    $identifier = $1;
2005f9bbc12cSAditya Srivastava	    $decl_type = 'function';
2006f9bbc12cSAditya Srivastava	    $identifier =~ s/^define\s+//;
2007f9bbc12cSAditya Srivastava	    $is_kernel_comment = 1;
2008f9bbc12cSAditya Srivastava	}
200952042e2dSMauro Carvalho Chehab	$identifier =~ s/\s+$//;
20101da177e4SLinus Torvalds
201117b78717SJonathan Corbet	$state = STATE_BODY;
20120b0f5f29SDaniel Vetter	# if there's no @param blocks need to set up default section
20130b0f5f29SDaniel Vetter	# here
20142f4ad40aSJani Nikula	$contents = "";
20152f4ad40aSJani Nikula	$section = $section_default;
20160b0f5f29SDaniel Vetter	$new_start_line = $. + 1;
201752042e2dSMauro Carvalho Chehab	if (/[-:](.*)/) {
201851f5a0c8SRandy Dunlap	    # strip leading/trailing/multiple spaces
2019a21217daSRandy Dunlap	    $descr= $1;
2020a21217daSRandy Dunlap	    $descr =~ s/^\s*//;
2021a21217daSRandy Dunlap	    $descr =~ s/\s*$//;
202212ae6779SDaniel Santos	    $descr =~ s/\s+/ /g;
20230bba924cSJonathan Corbet	    $declaration_purpose = $descr;
202417b78717SJonathan Corbet	    $state = STATE_BODY_MAYBE;
20251da177e4SLinus Torvalds	} else {
20261da177e4SLinus Torvalds	    $declaration_purpose = "";
20271da177e4SLinus Torvalds	}
202877cc23b8SRandy Dunlap
20293e58e839SAditya Srivastava	if (!$is_kernel_comment) {
20303e58e839SAditya Srivastava	    print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
20313e58e839SAditya Srivastava	    print STDERR $_;
20323e58e839SAditya Srivastava	    ++$warnings;
20333e58e839SAditya Srivastava	    $state = STATE_NORMAL;
20343e58e839SAditya Srivastava	}
20353e58e839SAditya Srivastava
203677cc23b8SRandy Dunlap	if (($declaration_purpose eq "") && $verbose) {
2037d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
203877cc23b8SRandy Dunlap	    print STDERR $_;
203977cc23b8SRandy Dunlap	    ++$warnings;
204077cc23b8SRandy Dunlap	}
204177cc23b8SRandy Dunlap
20420b54c2e3SMauro Carvalho Chehab	if ($identifier eq "" && $decl_type ne "enum") {
204352042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
204452042e2dSMauro Carvalho Chehab	    print STDERR $_;
204552042e2dSMauro Carvalho Chehab	    ++$warnings;
204652042e2dSMauro Carvalho Chehab	    $state = STATE_NORMAL;
20471da177e4SLinus Torvalds	}
20481da177e4SLinus Torvalds
20491da177e4SLinus Torvalds	if ($verbose) {
205052042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
20511da177e4SLinus Torvalds	}
20521da177e4SLinus Torvalds    } else {
2053d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
20541da177e4SLinus Torvalds	    " - I thought it was a doc line\n";
20551da177e4SLinus Torvalds	++$warnings;
205648af606aSJani Nikula	$state = STATE_NORMAL;
20571da177e4SLinus Torvalds    }
20583cac2bc4SJonathan Corbet}
20593cac2bc4SJonathan Corbet
20603cac2bc4SJonathan Corbet
2061d742f24dSJonathan Corbet#
2062d742f24dSJonathan Corbet# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2063d742f24dSJonathan Corbet#
2064d742f24dSJonathan Corbetsub process_body($$) {
2065d742f24dSJonathan Corbet    my $file = shift;
20663cac2bc4SJonathan Corbet
206743756e34SJonathan Neuschäfer    # Until all named variable macro parameters are
206843756e34SJonathan Neuschäfer    # documented using the bare name (`x`) rather than with
206943756e34SJonathan Neuschäfer    # dots (`x...`), strip the dots:
207043756e34SJonathan Neuschäfer    if ($section =~ /\w\.\.\.$/) {
207143756e34SJonathan Neuschäfer	$section =~ s/\.\.\.$//;
207243756e34SJonathan Neuschäfer
207343756e34SJonathan Neuschäfer	if ($verbose) {
207443756e34SJonathan Neuschäfer	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
207543756e34SJonathan Neuschäfer	    ++$warnings;
207643756e34SJonathan Neuschäfer	}
207743756e34SJonathan Neuschäfer    }
207843756e34SJonathan Neuschäfer
20790d55d48bSMauro Carvalho Chehab    if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
20800d55d48bSMauro Carvalho Chehab	dump_section($file, $section, $contents);
20810d55d48bSMauro Carvalho Chehab	$section = $section_default;
20825ef09c96SMauro Carvalho Chehab	$new_start_line = $.;
20830d55d48bSMauro Carvalho Chehab	$contents = "";
20840d55d48bSMauro Carvalho Chehab    }
20850d55d48bSMauro Carvalho Chehab
2086f624adefSJani Nikula    if (/$doc_sect/i) { # case insensitive for supported section names
20871da177e4SLinus Torvalds	$newsection = $1;
20881da177e4SLinus Torvalds	$newcontents = $2;
20891da177e4SLinus Torvalds
2090f624adefSJani Nikula	# map the supported section names to the canonical names
2091f624adefSJani Nikula	if ($newsection =~ m/^description$/i) {
2092f624adefSJani Nikula	    $newsection = $section_default;
2093f624adefSJani Nikula	} elsif ($newsection =~ m/^context$/i) {
2094f624adefSJani Nikula	    $newsection = $section_context;
2095f624adefSJani Nikula	} elsif ($newsection =~ m/^returns?$/i) {
2096f624adefSJani Nikula	    $newsection = $section_return;
2097f624adefSJani Nikula	} elsif ($newsection =~ m/^\@return$/) {
2098f624adefSJani Nikula	    # special: @return is a section, not a param description
2099f624adefSJani Nikula	    $newsection = $section_return;
2100f624adefSJani Nikula	}
2101f624adefSJani Nikula
2102792aa2f2SRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
2103850622dfSRandy Dunlap	    if (!$in_doc_sect && $verbose) {
2104d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: contents before sections\n";
2105850622dfSRandy Dunlap		++$warnings;
2106850622dfSRandy Dunlap	    }
21070bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
21081da177e4SLinus Torvalds	    $section = $section_default;
21091da177e4SLinus Torvalds	}
21101da177e4SLinus Torvalds
2111850622dfSRandy Dunlap	$in_doc_sect = 1;
211217b78717SJonathan Corbet	$state = STATE_BODY;
21131da177e4SLinus Torvalds	$contents = $newcontents;
21140b0f5f29SDaniel Vetter	$new_start_line = $.;
21157c9aa015SMauro Carvalho Chehab	while (substr($contents, 0, 1) eq " ") {
211605189497SRandy Dunlap	    $contents = substr($contents, 1);
211705189497SRandy Dunlap	}
21180a726301SJani Nikula	if ($contents ne "") {
21191da177e4SLinus Torvalds	    $contents .= "\n";
21201da177e4SLinus Torvalds	}
21211da177e4SLinus Torvalds	$section = $newsection;
2122b7886de4SJani Nikula	$leading_space = undef;
21231da177e4SLinus Torvalds    } elsif (/$doc_end/) {
21244c98ecafSRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
21250bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
21261da177e4SLinus Torvalds	    $section = $section_default;
21271da177e4SLinus Torvalds	    $contents = "";
21281da177e4SLinus Torvalds	}
212946b958ebSRandy Dunlap	# look for doc_com + <text> + doc_end:
213046b958ebSRandy Dunlap	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2131d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: suspicious ending line: $_";
213246b958ebSRandy Dunlap	    ++$warnings;
213346b958ebSRandy Dunlap	}
21341da177e4SLinus Torvalds
21351da177e4SLinus Torvalds	$prototype = "";
213648af606aSJani Nikula	$state = STATE_PROTO;
21371da177e4SLinus Torvalds	$brcount = 0;
21385ef09c96SMauro Carvalho Chehab        $new_start_line = $. + 1;
21391da177e4SLinus Torvalds    } elsif (/$doc_content/) {
21406423133bSJohannes Weiner	if ($1 eq "") {
21410d55d48bSMauro Carvalho Chehab	    if ($section eq $section_context) {
21420bba924cSJonathan Corbet		dump_section($file, $section, $contents);
21431da177e4SLinus Torvalds		$section = $section_default;
21441da177e4SLinus Torvalds		$contents = "";
21450b0f5f29SDaniel Vetter		$new_start_line = $.;
21460d55d48bSMauro Carvalho Chehab		$state = STATE_BODY;
21471da177e4SLinus Torvalds	    } else {
21480d55d48bSMauro Carvalho Chehab		if ($section ne $section_default) {
21490d55d48bSMauro Carvalho Chehab		    $state = STATE_BODY_WITH_BLANK_LINE;
21500d55d48bSMauro Carvalho Chehab		} else {
21510d55d48bSMauro Carvalho Chehab		    $state = STATE_BODY;
21520d55d48bSMauro Carvalho Chehab		}
21536423133bSJohannes Weiner		$contents .= "\n";
21546423133bSJohannes Weiner	    }
215517b78717SJonathan Corbet	} elsif ($state == STATE_BODY_MAYBE) {
21566423133bSJohannes Weiner	    # Continued declaration purpose
21576423133bSJohannes Weiner	    chomp($declaration_purpose);
21580bba924cSJonathan Corbet	    $declaration_purpose .= " " . $1;
215912ae6779SDaniel Santos	    $declaration_purpose =~ s/\s+/ /g;
21606423133bSJohannes Weiner	} else {
2161b7886de4SJani Nikula	    my $cont = $1;
2162b7886de4SJani Nikula	    if ($section =~ m/^@/ || $section eq $section_context) {
2163b7886de4SJani Nikula		if (!defined $leading_space) {
2164b7886de4SJani Nikula		    if ($cont =~ m/^(\s+)/) {
2165b7886de4SJani Nikula			$leading_space = $1;
2166b7886de4SJani Nikula		    } else {
2167b7886de4SJani Nikula			$leading_space = "";
2168b7886de4SJani Nikula		    }
2169b7886de4SJani Nikula		}
2170b7886de4SJani Nikula		$cont =~ s/^$leading_space//;
2171b7886de4SJani Nikula	    }
2172b7886de4SJani Nikula	    $contents .= $cont . "\n";
21731da177e4SLinus Torvalds	}
21741da177e4SLinus Torvalds    } else {
21751da177e4SLinus Torvalds	# i dont know - bad line?  ignore.
2176d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: bad line: $_";
21771da177e4SLinus Torvalds	++$warnings;
21781da177e4SLinus Torvalds    }
2179d742f24dSJonathan Corbet}
2180d742f24dSJonathan Corbet
2181d742f24dSJonathan Corbet
2182cc794812SJonathan Corbet#
2183cc794812SJonathan Corbet# STATE_PROTO: reading a function/whatever prototype.
2184cc794812SJonathan Corbet#
2185cc794812SJonathan Corbetsub process_proto($$) {
2186cc794812SJonathan Corbet    my $file = shift;
2187cc794812SJonathan Corbet
2188cc794812SJonathan Corbet    if (/$doc_inline_oneline/) {
2189cc794812SJonathan Corbet	$section = $1;
2190cc794812SJonathan Corbet	$contents = $2;
2191cc794812SJonathan Corbet	if ($contents ne "") {
2192cc794812SJonathan Corbet	    $contents .= "\n";
2193cc794812SJonathan Corbet	    dump_section($file, $section, $contents);
2194cc794812SJonathan Corbet	    $section = $section_default;
2195cc794812SJonathan Corbet	    $contents = "";
2196cc794812SJonathan Corbet	}
2197cc794812SJonathan Corbet    } elsif (/$doc_inline_start/) {
2198cc794812SJonathan Corbet	$state = STATE_INLINE;
2199cc794812SJonathan Corbet	$inline_doc_state = STATE_INLINE_NAME;
2200cc794812SJonathan Corbet    } elsif ($decl_type eq 'function') {
2201cc794812SJonathan Corbet	process_proto_function($_, $file);
2202cc794812SJonathan Corbet    } else {
2203cc794812SJonathan Corbet	process_proto_type($_, $file);
2204cc794812SJonathan Corbet    }
2205cc794812SJonathan Corbet}
2206cc794812SJonathan Corbet
2207c17add56SJonathan Corbet#
2208c17add56SJonathan Corbet# STATE_DOCBLOCK: within a DOC: block.
2209c17add56SJonathan Corbet#
2210c17add56SJonathan Corbetsub process_docblock($$) {
2211c17add56SJonathan Corbet    my $file = shift;
2212cc794812SJonathan Corbet
2213c17add56SJonathan Corbet    if (/$doc_end/) {
2214c17add56SJonathan Corbet	dump_doc_section($file, $section, $contents);
2215c17add56SJonathan Corbet	$section = $section_default;
2216c17add56SJonathan Corbet	$contents = "";
2217c17add56SJonathan Corbet	$function = "";
2218c17add56SJonathan Corbet	%parameterdescs = ();
2219c17add56SJonathan Corbet	%parametertypes = ();
2220c17add56SJonathan Corbet	@parameterlist = ();
2221c17add56SJonathan Corbet	%sections = ();
2222c17add56SJonathan Corbet	@sectionlist = ();
2223c17add56SJonathan Corbet	$prototype = "";
2224c17add56SJonathan Corbet	$state = STATE_NORMAL;
2225c17add56SJonathan Corbet    } elsif (/$doc_content/) {
2226c17add56SJonathan Corbet	if ( $1 eq "" )	{
2227c17add56SJonathan Corbet	    $contents .= $blankline;
2228c17add56SJonathan Corbet	} else {
2229c17add56SJonathan Corbet	    $contents .= $1 . "\n";
2230c17add56SJonathan Corbet	}
2231c17add56SJonathan Corbet    }
2232d742f24dSJonathan Corbet}
2233d742f24dSJonathan Corbet
2234c17add56SJonathan Corbet#
2235c17add56SJonathan Corbet# STATE_INLINE: docbook comments within a prototype.
2236c17add56SJonathan Corbet#
2237c17add56SJonathan Corbetsub process_inline($$) {
2238c17add56SJonathan Corbet    my $file = shift;
2239d742f24dSJonathan Corbet
2240a4c6ebedSDanilo Cesar Lemes de Paula    # First line (state 1) needs to be a @parameter
224148af606aSJani Nikula    if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2242a4c6ebedSDanilo Cesar Lemes de Paula	$section = $1;
2243a4c6ebedSDanilo Cesar Lemes de Paula	$contents = $2;
22440b0f5f29SDaniel Vetter	$new_start_line = $.;
2245a4c6ebedSDanilo Cesar Lemes de Paula	if ($contents ne "") {
22467c9aa015SMauro Carvalho Chehab	    while (substr($contents, 0, 1) eq " ") {
2247a4c6ebedSDanilo Cesar Lemes de Paula		$contents = substr($contents, 1);
2248a4c6ebedSDanilo Cesar Lemes de Paula	    }
2249a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= "\n";
2250a4c6ebedSDanilo Cesar Lemes de Paula	}
225148af606aSJani Nikula	$inline_doc_state = STATE_INLINE_TEXT;
2252a4c6ebedSDanilo Cesar Lemes de Paula	# Documentation block end */
225348af606aSJani Nikula    } elsif (/$doc_inline_end/) {
2254a4c6ebedSDanilo Cesar Lemes de Paula	if (($contents ne "") && ($contents ne "\n")) {
22550bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
2256a4c6ebedSDanilo Cesar Lemes de Paula	    $section = $section_default;
2257a4c6ebedSDanilo Cesar Lemes de Paula	    $contents = "";
2258a4c6ebedSDanilo Cesar Lemes de Paula	}
225948af606aSJani Nikula	$state = STATE_PROTO;
226048af606aSJani Nikula	$inline_doc_state = STATE_INLINE_NA;
2261a4c6ebedSDanilo Cesar Lemes de Paula	# Regular text
2262a4c6ebedSDanilo Cesar Lemes de Paula    } elsif (/$doc_content/) {
226348af606aSJani Nikula	if ($inline_doc_state == STATE_INLINE_TEXT) {
2264a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= $1 . "\n";
22656450c895SJani Nikula	    # nuke leading blank lines
22666450c895SJani Nikula	    if ($contents =~ /^\s*$/) {
22676450c895SJani Nikula		$contents = "";
22686450c895SJani Nikula	    }
226948af606aSJani Nikula	} elsif ($inline_doc_state == STATE_INLINE_NAME) {
227048af606aSJani Nikula	    $inline_doc_state = STATE_INLINE_ERROR;
2271e7ca311eSDaniel Vetter	    print STDERR "${file}:$.: warning: ";
2272a4c6ebedSDanilo Cesar Lemes de Paula	    print STDERR "Incorrect use of kernel-doc format: $_";
2273a4c6ebedSDanilo Cesar Lemes de Paula	    ++$warnings;
2274a4c6ebedSDanilo Cesar Lemes de Paula	}
2275a4c6ebedSDanilo Cesar Lemes de Paula    }
22760c9aa209SJani Nikula}
2277c17add56SJonathan Corbet
2278c17add56SJonathan Corbet
2279c17add56SJonathan Corbetsub process_file($) {
2280c17add56SJonathan Corbet    my $file;
2281c17add56SJonathan Corbet    my $initial_section_counter = $section_counter;
2282c17add56SJonathan Corbet    my ($orig_file) = @_;
2283c17add56SJonathan Corbet
2284c17add56SJonathan Corbet    $file = map_filename($orig_file);
2285c17add56SJonathan Corbet
2286dbe8ba00SMauro Carvalho Chehab    if (!open(IN_FILE,"<$file")) {
2287c17add56SJonathan Corbet	print STDERR "Error: Cannot open file $file\n";
2288c17add56SJonathan Corbet	++$errors;
2289c17add56SJonathan Corbet	return;
22901da177e4SLinus Torvalds    }
2291c17add56SJonathan Corbet
2292c17add56SJonathan Corbet    $. = 1;
2293c17add56SJonathan Corbet
2294c17add56SJonathan Corbet    $section_counter = 0;
2295dbe8ba00SMauro Carvalho Chehab    while (<IN_FILE>) {
2296c17add56SJonathan Corbet	while (s/\\\s*$//) {
2297dbe8ba00SMauro Carvalho Chehab	    $_ .= <IN_FILE>;
2298c17add56SJonathan Corbet	}
2299c17add56SJonathan Corbet	# Replace tabs by spaces
2300c17add56SJonathan Corbet        while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2301c17add56SJonathan Corbet	# Hand this line to the appropriate state handler
2302c17add56SJonathan Corbet	if ($state == STATE_NORMAL) {
2303c17add56SJonathan Corbet	    process_normal();
2304c17add56SJonathan Corbet	} elsif ($state == STATE_NAME) {
2305c17add56SJonathan Corbet	    process_name($file, $_);
23060d55d48bSMauro Carvalho Chehab	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
23070d55d48bSMauro Carvalho Chehab		 $state == STATE_BODY_WITH_BLANK_LINE) {
2308c17add56SJonathan Corbet	    process_body($file, $_);
2309c17add56SJonathan Corbet	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
2310c17add56SJonathan Corbet	    process_inline($file, $_);
2311cc794812SJonathan Corbet	} elsif ($state == STATE_PROTO) {
2312cc794812SJonathan Corbet	    process_proto($file, $_);
231348af606aSJani Nikula	} elsif ($state == STATE_DOCBLOCK) {
2314c17add56SJonathan Corbet	    process_docblock($file, $_);
23151da177e4SLinus Torvalds	}
23161da177e4SLinus Torvalds    }
2317c17add56SJonathan Corbet
2318c17add56SJonathan Corbet    # Make sure we got something interesting.
2319b0d60bfbSJonathan Corbet    if ($initial_section_counter == $section_counter && $
2320b0d60bfbSJonathan Corbet	output_mode ne "none") {
2321b0d60bfbSJonathan Corbet	if ($output_selection == OUTPUT_INCLUDE) {
2322b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: '$_' not found\n"
2323b0d60bfbSJonathan Corbet		for keys %function_table;
23243a025e1dSMatthew Wilcox	}
2325b0d60bfbSJonathan Corbet	else {
2326b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: no structured comments found\n";
2327e946c43aSJohannes Berg	}
23281da177e4SLinus Torvalds    }
2329dbe8ba00SMauro Carvalho Chehab    close IN_FILE;
23301da177e4SLinus Torvalds}
23318484baaaSRandy Dunlap
23328484baaaSRandy Dunlap
233393351d41SMauro Carvalho Chehabif ($output_mode eq "rst") {
233493351d41SMauro Carvalho Chehab	get_sphinx_version() if (!$sphinx_major);
233593351d41SMauro Carvalho Chehab}
233693351d41SMauro Carvalho Chehab
23378484baaaSRandy Dunlap$kernelversion = get_kernel_version();
23388484baaaSRandy Dunlap
23398484baaaSRandy Dunlap# generate a sequence of code that will splice in highlighting information
23408484baaaSRandy Dunlap# using the s// operator.
23411ef06233SMauro Carvalho Chehabfor (my $k = 0; $k < @highlights; $k++) {
23424d732701SDanilo Cesar Lemes de Paula    my $pattern = $highlights[$k][0];
23434d732701SDanilo Cesar Lemes de Paula    my $result = $highlights[$k][1];
23444d732701SDanilo Cesar Lemes de Paula#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
23454d732701SDanilo Cesar Lemes de Paula    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
23468484baaaSRandy Dunlap}
23478484baaaSRandy Dunlap
23488484baaaSRandy Dunlap# Read the file that maps relative names to absolute names for
23498484baaaSRandy Dunlap# separate source and object directories and for shadow trees.
23508484baaaSRandy Dunlapif (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
23518484baaaSRandy Dunlap	my ($relname, $absname);
23528484baaaSRandy Dunlap	while(<SOURCE_MAP>) {
23538484baaaSRandy Dunlap		chop();
23548484baaaSRandy Dunlap		($relname, $absname) = (split())[0..1];
23558484baaaSRandy Dunlap		$relname =~ s:^/+::;
23568484baaaSRandy Dunlap		$source_map{$relname} = $absname;
23578484baaaSRandy Dunlap	}
23588484baaaSRandy Dunlap	close(SOURCE_MAP);
23598484baaaSRandy Dunlap}
23608484baaaSRandy Dunlap
236188c2b57dSJani Nikulaif ($output_selection == OUTPUT_EXPORTED ||
236288c2b57dSJani Nikula    $output_selection == OUTPUT_INTERNAL) {
2363c9b2cfb3SJani Nikula
2364c9b2cfb3SJani Nikula    push(@export_file_list, @ARGV);
2365c9b2cfb3SJani Nikula
236688c2b57dSJani Nikula    foreach (@export_file_list) {
236788c2b57dSJani Nikula	chomp;
236888c2b57dSJani Nikula	process_export_file($_);
236988c2b57dSJani Nikula    }
237088c2b57dSJani Nikula}
237188c2b57dSJani Nikula
23728484baaaSRandy Dunlapforeach (@ARGV) {
23738484baaaSRandy Dunlap    chomp;
23748484baaaSRandy Dunlap    process_file($_);
23758484baaaSRandy Dunlap}
23768484baaaSRandy Dunlapif ($verbose && $errors) {
23778484baaaSRandy Dunlap  print STDERR "$errors errors\n";
23788484baaaSRandy Dunlap}
23798484baaaSRandy Dunlapif ($verbose && $warnings) {
23808484baaaSRandy Dunlap  print STDERR "$warnings warnings\n";
23818484baaaSRandy Dunlap}
23828484baaaSRandy Dunlap
23832c12c810SPierre-Louis Bossartif ($Werror && $warnings) {
23842c12c810SPierre-Louis Bossart    print STDERR "$warnings warnings as Errors\n";
23852c12c810SPierre-Louis Bossart    exit($warnings);
23862c12c810SPierre-Louis Bossart} else {
23872c12c810SPierre-Louis Bossart    exit($output_mode eq "none" ? 0 : $errors)
23882c12c810SPierre-Louis Bossart}
23892875f787STomasz Warniełło
23902875f787STomasz Warniełło__END__
23912875f787STomasz Warniełło
23922875f787STomasz Warniełło=head1 OPTIONS
23932875f787STomasz Warniełło
23942875f787STomasz Warniełło=head2 Output format selection (mutually exclusive):
23952875f787STomasz Warniełło
23962875f787STomasz Warniełło=over 8
23972875f787STomasz Warniełło
23982875f787STomasz Warniełło=item -man
23992875f787STomasz Warniełło
24002875f787STomasz WarniełłoOutput troff manual page format.
24012875f787STomasz Warniełło
24022875f787STomasz Warniełło=item -rst
24032875f787STomasz Warniełło
24042875f787STomasz WarniełłoOutput reStructuredText format. This is the default.
24052875f787STomasz Warniełło
24062875f787STomasz Warniełło=item -none
24072875f787STomasz Warniełło
24082875f787STomasz WarniełłoDo not output documentation, only warnings.
24092875f787STomasz Warniełło
24102875f787STomasz Warniełło=back
24112875f787STomasz Warniełło
2412dd803b04STomasz Warniełło=head2 Output format modifiers
2413dd803b04STomasz Warniełło
2414dd803b04STomasz Warniełło=head3 reStructuredText only
2415dd803b04STomasz Warniełło
2416dd803b04STomasz Warniełło=over 8
2417dd803b04STomasz Warniełło
2418dd803b04STomasz Warniełło=item -sphinx-version VERSION
2419dd803b04STomasz Warniełło
2420dd803b04STomasz WarniełłoUse the ReST C domain dialect compatible with a specific Sphinx Version.
2421dd803b04STomasz Warniełło
2422dd803b04STomasz WarniełłoIf not specified, kernel-doc will auto-detect using the sphinx-build version
2423dd803b04STomasz Warniełłofound on PATH.
2424dd803b04STomasz Warniełło
2425dd803b04STomasz Warniełło=back
2426dd803b04STomasz Warniełło
24279c77f108STomasz Warniełło=head2 Output selection (mutually exclusive):
24289c77f108STomasz Warniełło
24299c77f108STomasz Warniełło=over 8
24309c77f108STomasz Warniełło
24319c77f108STomasz Warniełło=item -export
24329c77f108STomasz Warniełło
24339c77f108STomasz WarniełłoOnly output documentation for the symbols that have been exported using
24349c77f108STomasz WarniełłoEXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
24359c77f108STomasz Warniełło
24369c77f108STomasz Warniełło=item -internal
24379c77f108STomasz Warniełło
24389c77f108STomasz WarniełłoOnly output documentation for the symbols that have NOT been exported using
24399c77f108STomasz WarniełłoEXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
24409c77f108STomasz Warniełło
24419c77f108STomasz Warniełło=item -function NAME
24429c77f108STomasz Warniełło
24439c77f108STomasz WarniełłoOnly output documentation for the given function or DOC: section title.
24449c77f108STomasz WarniełłoAll other functions and DOC: sections are ignored.
24459c77f108STomasz Warniełło
24469c77f108STomasz WarniełłoMay be specified multiple times.
24479c77f108STomasz Warniełło
24489c77f108STomasz Warniełło=item -nosymbol NAME
24499c77f108STomasz Warniełło
24509c77f108STomasz WarniełłoExclude the specified symbol from the output documentation.
24519c77f108STomasz Warniełło
24529c77f108STomasz WarniełłoMay be specified multiple times.
24539c77f108STomasz Warniełło
24549c77f108STomasz Warniełło=back
24559c77f108STomasz Warniełło
2456c15de5a1STomasz Warniełło=head2 Output selection modifiers:
2457c15de5a1STomasz Warniełło
2458c15de5a1STomasz Warniełło=over 8
2459c15de5a1STomasz Warniełło
2460c15de5a1STomasz Warniełło=item -no-doc-sections
2461c15de5a1STomasz Warniełło
2462c15de5a1STomasz WarniełłoDo not output DOC: sections.
2463c15de5a1STomasz Warniełło
2464c15de5a1STomasz Warniełło=item -export-file FILE
2465c15de5a1STomasz Warniełło
2466c15de5a1STomasz WarniełłoSpecify an additional FILE in which to look for EXPORT_SYMBOL() and
2467c15de5a1STomasz WarniełłoEXPORT_SYMBOL_GPL().
2468c15de5a1STomasz Warniełło
2469c15de5a1STomasz WarniełłoTo be used with -export or -internal.
2470c15de5a1STomasz Warniełło
2471c15de5a1STomasz WarniełłoMay be specified multiple times.
2472c15de5a1STomasz Warniełło
2473c15de5a1STomasz Warniełło=back
2474c15de5a1STomasz Warniełło
2475c15de5a1STomasz Warniełło=head3 reStructuredText only
2476c15de5a1STomasz Warniełło
2477c15de5a1STomasz Warniełło=over 8
2478c15de5a1STomasz Warniełło
2479c15de5a1STomasz Warniełło=item -enable-lineno
2480c15de5a1STomasz Warniełło
2481*b79dfef0SMauro Carvalho ChehabEnable output of .. LINENO lines.
2482c15de5a1STomasz Warniełło
2483c15de5a1STomasz Warniełło=back
2484c15de5a1STomasz Warniełło
2485834cf6b9STomasz Warniełło=head2 Other parameters:
2486834cf6b9STomasz Warniełło
2487834cf6b9STomasz Warniełło=over 8
2488834cf6b9STomasz Warniełło
2489834cf6b9STomasz Warniełło=item -h, -help
2490834cf6b9STomasz Warniełło
2491834cf6b9STomasz WarniełłoPrint this help.
2492834cf6b9STomasz Warniełło
2493834cf6b9STomasz Warniełło=item -v
2494834cf6b9STomasz Warniełło
2495834cf6b9STomasz WarniełłoVerbose output, more warnings and other information.
2496834cf6b9STomasz Warniełło
2497834cf6b9STomasz Warniełło=item -Werror
2498834cf6b9STomasz Warniełło
2499834cf6b9STomasz WarniełłoTreat warnings as errors.
2500834cf6b9STomasz Warniełło
2501834cf6b9STomasz Warniełło=back
2502834cf6b9STomasz Warniełło
25032875f787STomasz Warniełło=cut
2504