xref: /linux/scripts/kernel-doc (revision 084aa00162bda02bcab501c2b0a0ea9252d291b2)
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.			 ##
151da177e4SLinus Torvalds## 								 ##
161da177e4SLinus Torvalds## This software falls under the GNU General Public License.     ##
171da177e4SLinus Torvalds## Please read the COPYING file for more information             ##
181da177e4SLinus Torvalds
191da177e4SLinus Torvalds# 18/01/2001 - 	Cleanups
201da177e4SLinus Torvalds# 		Functions prototyped as foo(void) same as foo()
211da177e4SLinus Torvalds# 		Stop eval'ing where we don't need to.
221da177e4SLinus Torvalds# -- huggie@earth.li
231da177e4SLinus Torvalds
241da177e4SLinus Torvalds# 27/06/2001 -  Allowed whitespace after initial "/**" and
251da177e4SLinus Torvalds#               allowed comments before function declarations.
261da177e4SLinus Torvalds# -- Christian Kreibich <ck@whoop.org>
271da177e4SLinus Torvalds
281da177e4SLinus Torvalds# Still to do:
291da177e4SLinus Torvalds# 	- add perldoc documentation
301da177e4SLinus Torvalds# 	- Look more closely at some of the scarier bits :)
311da177e4SLinus Torvalds
321da177e4SLinus Torvalds# 26/05/2001 - 	Support for separate source and object trees.
331da177e4SLinus Torvalds#		Return error code.
341da177e4SLinus Torvalds# 		Keith Owens <kaos@ocs.com.au>
351da177e4SLinus Torvalds
361da177e4SLinus Torvalds# 23/09/2001 - Added support for typedefs, structs, enums and unions
371da177e4SLinus Torvalds#              Support for Context section; can be terminated using empty line
381da177e4SLinus Torvalds#              Small fixes (like spaces vs. \s in regex)
391da177e4SLinus Torvalds# -- Tim Jansen <tim@tjansen.de>
401da177e4SLinus Torvalds
411b40c194SDan Luedtke# 25/07/2012 - Added support for HTML5
421b40c194SDan Luedtke# -- Dan Luedtke <mail@danrl.de>
431da177e4SLinus Torvalds
44fadc0b31SJani Nikulasub usage {
45fadc0b31SJani Nikula    my $message = <<"EOF";
46fadc0b31SJani NikulaUsage: $0 [OPTION ...] FILE ...
471da177e4SLinus Torvalds
48fadc0b31SJani NikulaRead C language source or header FILEs, extract embedded documentation comments,
49fadc0b31SJani Nikulaand print formatted documentation to standard output.
501da177e4SLinus Torvalds
51fadc0b31SJani NikulaThe documentation comments are identified by "/**" opening comment mark. See
52857af3b7SMauro Carvalho ChehabDocumentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
53fadc0b31SJani Nikula
54fadc0b31SJani NikulaOutput format selection (mutually exclusive):
55fadc0b31SJani Nikula  -man			Output troff manual page format. This is the default.
56c0d1b6eeSJonathan Corbet  -rst			Output reStructuredText format.
573a025e1dSMatthew Wilcox  -none			Do not output documentation, only warnings.
58fadc0b31SJani Nikula
5993351d41SMauro Carvalho ChehabOutput format selection modifier (affects only ReST output):
6093351d41SMauro Carvalho Chehab
6193351d41SMauro Carvalho Chehab  -sphinx-version	Use the ReST C domain dialect compatible with an
6293351d41SMauro Carvalho Chehab			specific Sphinx Version.
6393351d41SMauro Carvalho Chehab			If not specified, kernel-doc will auto-detect using
6493351d41SMauro Carvalho Chehab			the sphinx-build version found on PATH.
6593351d41SMauro Carvalho Chehab
66fadc0b31SJani NikulaOutput selection (mutually exclusive):
6786ae2e38SJani Nikula  -export		Only output documentation for symbols that have been
6886ae2e38SJani Nikula			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
69c9b2cfb3SJani Nikula                        in any input FILE or -export-file FILE.
7086ae2e38SJani Nikula  -internal		Only output documentation for symbols that have NOT been
7186ae2e38SJani Nikula			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
72c9b2cfb3SJani Nikula                        in any input FILE or -export-file FILE.
73fadc0b31SJani Nikula  -function NAME	Only output documentation for the given function(s)
74fadc0b31SJani Nikula			or DOC: section title(s). All other functions and DOC:
75fadc0b31SJani Nikula			sections are ignored. May be specified multiple times.
76eab795ddSMauro Carvalho Chehab  -nosymbol NAME	Exclude the specified symbols from the output
77eab795ddSMauro Carvalho Chehab		        documentation. May be specified multiple times.
78fadc0b31SJani Nikula
79fadc0b31SJani NikulaOutput selection modifiers:
80fadc0b31SJani Nikula  -no-doc-sections	Do not output DOC: sections.
810b0f5f29SDaniel Vetter  -enable-lineno        Enable output of #define LINENO lines. Only works with
820b0f5f29SDaniel Vetter                        reStructuredText format.
8388c2b57dSJani Nikula  -export-file FILE     Specify an additional FILE in which to look for
8488c2b57dSJani Nikula                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
8588c2b57dSJani Nikula                        -export or -internal. May be specified multiple times.
86fadc0b31SJani Nikula
87fadc0b31SJani NikulaOther parameters:
88fadc0b31SJani Nikula  -v			Verbose output, more warnings and other information.
89fadc0b31SJani Nikula  -h			Print this help.
902c12c810SPierre-Louis Bossart  -Werror		Treat warnings as errors.
91fadc0b31SJani Nikula
92fadc0b31SJani NikulaEOF
93fadc0b31SJani Nikula    print $message;
94fadc0b31SJani Nikula    exit 1;
95fadc0b31SJani Nikula}
961da177e4SLinus Torvalds
971da177e4SLinus Torvalds#
981da177e4SLinus Torvalds# format of comments.
991da177e4SLinus Torvalds# In the following table, (...)? signifies optional structure.
1001da177e4SLinus Torvalds#                         (...)* signifies 0 or more structure elements
1011da177e4SLinus Torvalds# /**
1021da177e4SLinus Torvalds#  * function_name(:)? (- short description)?
1031da177e4SLinus Torvalds# (* @parameterx: (description of parameter x)?)*
1041da177e4SLinus Torvalds# (* a blank line)?
1051da177e4SLinus Torvalds#  * (Description:)? (Description of function)?
1061da177e4SLinus Torvalds#  * (section header: (section description)? )*
1071da177e4SLinus Torvalds#  (*)?*/
1081da177e4SLinus Torvalds#
1091da177e4SLinus Torvalds# So .. the trivial example would be:
1101da177e4SLinus Torvalds#
1111da177e4SLinus Torvalds# /**
1121da177e4SLinus Torvalds#  * my_function
113b9d97328SRandy Dunlap#  */
1141da177e4SLinus Torvalds#
115891dcd2fSRandy Dunlap# If the Description: header tag is omitted, then there must be a blank line
1161da177e4SLinus Torvalds# after the last parameter specification.
1171da177e4SLinus Torvalds# e.g.
1181da177e4SLinus Torvalds# /**
1191da177e4SLinus Torvalds#  * my_function - does my stuff
1201da177e4SLinus Torvalds#  * @my_arg: its mine damnit
1211da177e4SLinus Torvalds#  *
1221da177e4SLinus Torvalds#  * Does my stuff explained.
1231da177e4SLinus Torvalds#  */
1241da177e4SLinus Torvalds#
1251da177e4SLinus Torvalds#  or, could also use:
1261da177e4SLinus Torvalds# /**
1271da177e4SLinus Torvalds#  * my_function - does my stuff
1281da177e4SLinus Torvalds#  * @my_arg: its mine damnit
1291da177e4SLinus Torvalds#  * Description: Does my stuff explained.
1301da177e4SLinus Torvalds#  */
1311da177e4SLinus Torvalds# etc.
1321da177e4SLinus Torvalds#
133b9d97328SRandy Dunlap# Besides functions you can also write documentation for structs, unions,
1341da177e4SLinus Torvalds# enums and typedefs. Instead of the function name you must write the name
1351da177e4SLinus Torvalds# of the declaration;  the struct/union/enum/typedef must always precede
1361da177e4SLinus Torvalds# the name. Nesting of declarations is not supported.
1371da177e4SLinus Torvalds# Use the argument mechanism to document members or constants.
1381da177e4SLinus Torvalds# e.g.
1391da177e4SLinus Torvalds# /**
1401da177e4SLinus Torvalds#  * struct my_struct - short description
1411da177e4SLinus Torvalds#  * @a: first member
1421da177e4SLinus Torvalds#  * @b: second member
1431da177e4SLinus Torvalds#  *
1441da177e4SLinus Torvalds#  * Longer description
1451da177e4SLinus Torvalds#  */
1461da177e4SLinus Torvalds# struct my_struct {
1471da177e4SLinus Torvalds#     int a;
1481da177e4SLinus Torvalds#     int b;
149aeec46b9SMartin Waitz# /* private: */
150aeec46b9SMartin Waitz#     int c;
1511da177e4SLinus Torvalds# };
1521da177e4SLinus Torvalds#
1531da177e4SLinus Torvalds# All descriptions can be multiline, except the short function description.
1541da177e4SLinus Torvalds#
155a4c6ebedSDanilo Cesar Lemes de Paula# For really longs structs, you can also describe arguments inside the
156a4c6ebedSDanilo Cesar Lemes de Paula# body of the struct.
157a4c6ebedSDanilo Cesar Lemes de Paula# eg.
158a4c6ebedSDanilo Cesar Lemes de Paula# /**
159a4c6ebedSDanilo Cesar Lemes de Paula#  * struct my_struct - short description
160a4c6ebedSDanilo Cesar Lemes de Paula#  * @a: first member
161a4c6ebedSDanilo Cesar Lemes de Paula#  * @b: second member
162a4c6ebedSDanilo Cesar Lemes de Paula#  *
163a4c6ebedSDanilo Cesar Lemes de Paula#  * Longer description
164a4c6ebedSDanilo Cesar Lemes de Paula#  */
165a4c6ebedSDanilo Cesar Lemes de Paula# struct my_struct {
166a4c6ebedSDanilo Cesar Lemes de Paula#     int a;
167a4c6ebedSDanilo Cesar Lemes de Paula#     int b;
168a4c6ebedSDanilo Cesar Lemes de Paula#     /**
169a4c6ebedSDanilo Cesar Lemes de Paula#      * @c: This is longer description of C
170a4c6ebedSDanilo Cesar Lemes de Paula#      *
171a4c6ebedSDanilo Cesar Lemes de Paula#      * You can use paragraphs to describe arguments
172a4c6ebedSDanilo Cesar Lemes de Paula#      * using this method.
173a4c6ebedSDanilo Cesar Lemes de Paula#      */
174a4c6ebedSDanilo Cesar Lemes de Paula#     int c;
175a4c6ebedSDanilo Cesar Lemes de Paula# };
176a4c6ebedSDanilo Cesar Lemes de Paula#
177a4c6ebedSDanilo Cesar Lemes de Paula# This should be use only for struct/enum members.
178a4c6ebedSDanilo Cesar Lemes de Paula#
1791da177e4SLinus Torvalds# You can also add additional sections. When documenting kernel functions you
1801da177e4SLinus Torvalds# should document the "Context:" of the function, e.g. whether the functions
1811da177e4SLinus Torvalds# can be called form interrupts. Unlike other sections you can end it with an
1821da177e4SLinus Torvalds# empty line.
1834092bac7SYacine Belkadi# A non-void function should have a "Return:" section describing the return
1844092bac7SYacine Belkadi# value(s).
1851da177e4SLinus Torvalds# Example-sections should contain the string EXAMPLE so that they are marked
1861da177e4SLinus Torvalds# appropriately in DocBook.
1871da177e4SLinus Torvalds#
1881da177e4SLinus Torvalds# Example:
1891da177e4SLinus Torvalds# /**
1901da177e4SLinus Torvalds#  * user_function - function that can only be called in user context
1911da177e4SLinus Torvalds#  * @a: some argument
1921da177e4SLinus Torvalds#  * Context: !in_interrupt()
1931da177e4SLinus Torvalds#  *
1941da177e4SLinus Torvalds#  * Some description
1951da177e4SLinus Torvalds#  * Example:
1961da177e4SLinus Torvalds#  *    user_function(22);
1971da177e4SLinus Torvalds#  */
1981da177e4SLinus Torvalds# ...
1991da177e4SLinus Torvalds#
2001da177e4SLinus Torvalds#
2011da177e4SLinus Torvalds# All descriptive text is further processed, scanning for the following special
2021da177e4SLinus Torvalds# patterns, which are highlighted appropriately.
2031da177e4SLinus Torvalds#
2041da177e4SLinus Torvalds# 'funcname()' - function
2051da177e4SLinus Torvalds# '$ENVVAR' - environmental variable
2061da177e4SLinus Torvalds# '&struct_name' - name of a structure (up to two words including 'struct')
2075267dd35SPaolo Bonzini# '&struct_name.member' - name of a structure member
2081da177e4SLinus Torvalds# '@parameter' - name of a parameter
2091da177e4SLinus Torvalds# '%CONST' - name of a constant.
210b97f193aSMauro Carvalho Chehab# '``LITERAL``' - literal string without any spaces on it.
2111da177e4SLinus Torvalds
2128484baaaSRandy Dunlap## init lots of data
2138484baaaSRandy Dunlap
2141da177e4SLinus Torvaldsmy $errors = 0;
2151da177e4SLinus Torvaldsmy $warnings = 0;
2165f8c7c98SRandy Dunlapmy $anon_struct_union = 0;
2171da177e4SLinus Torvalds
2181da177e4SLinus Torvalds# match expressions used to find embedded type information
219b97f193aSMauro Carvalho Chehabmy $type_constant = '\b``([^\`]+)``\b';
220b97f193aSMauro Carvalho Chehabmy $type_constant2 = '\%([-_\w]+)';
2211da177e4SLinus Torvaldsmy $type_func = '(\w+)\(\)';
222bfd228c7SMike Rapoportmy $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
223ee2aa759SMauro Carvalho Chehabmy $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
2245219f18aSJonathan Corbetmy $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
225346282dbSMauro Carvalho Chehabmy $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Special RST handling for structs with func ptr params
2261da177e4SLinus Torvaldsmy $type_env = '(\$\w+)';
227df31175bSPaolo Bonzinimy $type_enum = '\&(enum\s*([_\w]+))';
228df31175bSPaolo Bonzinimy $type_struct = '\&(struct\s*([_\w]+))';
229df31175bSPaolo Bonzinimy $type_typedef = '\&(typedef\s*([_\w]+))';
230df31175bSPaolo Bonzinimy $type_union = '\&(union\s*([_\w]+))';
2315267dd35SPaolo Bonzinimy $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
232df31175bSPaolo Bonzinimy $type_fallback = '\&([_\w]+)';
233f3341dcfSJani Nikulamy $type_member_func = $type_member . '\(\)';
2341da177e4SLinus Torvalds
2351da177e4SLinus Torvalds# Output conversion substitutions.
2361da177e4SLinus Torvalds#  One for each output format
2371da177e4SLinus Torvalds
2381da177e4SLinus Torvalds# these are pretty rough
2394d732701SDanilo Cesar Lemes de Paulamy @highlights_man = (
2404d732701SDanilo Cesar Lemes de Paula                      [$type_constant, "\$1"],
241b97f193aSMauro Carvalho Chehab                      [$type_constant2, "\$1"],
2424d732701SDanilo Cesar Lemes de Paula                      [$type_func, "\\\\fB\$1\\\\fP"],
243df31175bSPaolo Bonzini                      [$type_enum, "\\\\fI\$1\\\\fP"],
2444d732701SDanilo Cesar Lemes de Paula                      [$type_struct, "\\\\fI\$1\\\\fP"],
245df31175bSPaolo Bonzini                      [$type_typedef, "\\\\fI\$1\\\\fP"],
246df31175bSPaolo Bonzini                      [$type_union, "\\\\fI\$1\\\\fP"],
2475267dd35SPaolo Bonzini                      [$type_param, "\\\\fI\$1\\\\fP"],
248ee2aa759SMauro Carvalho Chehab                      [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
249df31175bSPaolo Bonzini                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
250df31175bSPaolo Bonzini                      [$type_fallback, "\\\\fI\$1\\\\fP"]
2514d732701SDanilo Cesar Lemes de Paula		     );
2521da177e4SLinus Torvaldsmy $blankline_man = "";
2531da177e4SLinus Torvalds
254c0d1b6eeSJonathan Corbet# rst-mode
255c0d1b6eeSJonathan Corbetmy @highlights_rst = (
256c0d1b6eeSJonathan Corbet                       [$type_constant, "``\$1``"],
257b97f193aSMauro Carvalho Chehab                       [$type_constant2, "``\$1``"],
258f3341dcfSJani Nikula                       # Note: need to escape () to avoid func matching later
2595267dd35SPaolo Bonzini                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
2605267dd35SPaolo Bonzini                       [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
2615219f18aSJonathan Corbet		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
262346282dbSMauro Carvalho Chehab		       [$type_fp_param2, "**\$1\\\\(\\\\)**"],
263344fdb28SJonathan Corbet                       [$type_func, "\$1()"],
264df31175bSPaolo Bonzini                       [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
265df31175bSPaolo Bonzini                       [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
266df31175bSPaolo Bonzini                       [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
267df31175bSPaolo Bonzini                       [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
268a7291e7eSJani Nikula                       # in rst this can refer to any type
269df31175bSPaolo Bonzini                       [$type_fallback, "\\:c\\:type\\:`\$1`"],
270ee2aa759SMauro Carvalho Chehab                       [$type_param_ref, "**\$1\$2**"]
271c0d1b6eeSJonathan Corbet		      );
272c0d1b6eeSJonathan Corbetmy $blankline_rst = "\n";
273c0d1b6eeSJonathan Corbet
2741da177e4SLinus Torvalds# read arguments
2751da177e4SLinus Torvaldsif ($#ARGV == -1) {
2761da177e4SLinus Torvalds    usage();
2771da177e4SLinus Torvalds}
2781da177e4SLinus Torvalds
2798484baaaSRandy Dunlapmy $kernelversion;
28093351d41SMauro Carvalho Chehabmy ($sphinx_major, $sphinx_minor, $sphinx_patch);
281efa44475SMauro Carvalho Chehab
2828484baaaSRandy Dunlapmy $dohighlight = "";
2838484baaaSRandy Dunlap
2841da177e4SLinus Torvaldsmy $verbose = 0;
2852c12c810SPierre-Louis Bossartmy $Werror = 0;
286bdfe2be3SMauro Carvalho Chehabmy $output_mode = "rst";
287e314ba31SDaniel Santosmy $output_preformatted = 0;
2884b44595aSJohannes Bergmy $no_doc_sections = 0;
2890b0f5f29SDaniel Vettermy $enable_lineno = 0;
290bdfe2be3SMauro Carvalho Chehabmy @highlights = @highlights_rst;
291bdfe2be3SMauro Carvalho Chehabmy $blankline = $blankline_rst;
2921da177e4SLinus Torvaldsmy $modulename = "Kernel API";
293b6c3f456SJani Nikula
294b6c3f456SJani Nikulause constant {
295b6c3f456SJani Nikula    OUTPUT_ALL          => 0, # output all symbols and doc sections
296b6c3f456SJani Nikula    OUTPUT_INCLUDE      => 1, # output only specified symbols
297eab795ddSMauro Carvalho Chehab    OUTPUT_EXPORTED     => 2, # output exported symbols
298eab795ddSMauro Carvalho Chehab    OUTPUT_INTERNAL     => 3, # output non-exported symbols
299b6c3f456SJani Nikula};
300b6c3f456SJani Nikulamy $output_selection = OUTPUT_ALL;
301b0d60bfbSJonathan Corbetmy $show_not_found = 0;	# No longer used
302b2c4105bSBen Hutchings
30388c2b57dSJani Nikulamy @export_file_list;
30488c2b57dSJani Nikula
305b2c4105bSBen Hutchingsmy @build_time;
306b2c4105bSBen Hutchingsif (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
307b2c4105bSBen Hutchings    (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
308b2c4105bSBen Hutchings    @build_time = gmtime($seconds);
309b2c4105bSBen Hutchings} else {
310b2c4105bSBen Hutchings    @build_time = localtime;
311b2c4105bSBen Hutchings}
312b2c4105bSBen Hutchings
3131da177e4SLinus Torvaldsmy $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
3141da177e4SLinus Torvalds		'July', 'August', 'September', 'October',
315b2c4105bSBen Hutchings		'November', 'December')[$build_time[4]] .
316b2c4105bSBen Hutchings  " " . ($build_time[5]+1900);
3171da177e4SLinus Torvalds
3188484baaaSRandy Dunlap# Essentially these are globals.
319b9d97328SRandy Dunlap# They probably want to be tidied up, made more localised or something.
320b9d97328SRandy Dunlap# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
3211da177e4SLinus Torvalds# could cause "use of undefined value" or other bugs.
3221da177e4SLinus Torvaldsmy ($function, %function_table, %parametertypes, $declaration_purpose);
323eab795ddSMauro Carvalho Chehabmy %nosymbol_table = ();
3240b0f5f29SDaniel Vettermy $declaration_start_line;
3251da177e4SLinus Torvaldsmy ($type, $declaration_name, $return_type);
3261c32fd0cSIlya Dryomovmy ($newsection, $newcontents, $prototype, $brcount, %source_map);
3271da177e4SLinus Torvalds
328bd0e88e5SRandy Dunlapif (defined($ENV{'KBUILD_VERBOSE'})) {
329bd0e88e5SRandy Dunlap	$verbose = "$ENV{'KBUILD_VERBOSE'}";
330bd0e88e5SRandy Dunlap}
331bd0e88e5SRandy Dunlap
3322c12c810SPierre-Louis Bossartif (defined($ENV{'KDOC_WERROR'})) {
3332c12c810SPierre-Louis Bossart	$Werror = "$ENV{'KDOC_WERROR'}";
3342c12c810SPierre-Louis Bossart}
3352c12c810SPierre-Louis Bossart
3362c12c810SPierre-Louis Bossartif (defined($ENV{'KCFLAGS'})) {
3372c12c810SPierre-Louis Bossart	my $kcflags = "$ENV{'KCFLAGS'}";
3382c12c810SPierre-Louis Bossart
3392c12c810SPierre-Louis Bossart	if ($kcflags =~ /Werror/) {
3402c12c810SPierre-Louis Bossart		$Werror = 1;
3412c12c810SPierre-Louis Bossart	}
3422c12c810SPierre-Louis Bossart}
3432c12c810SPierre-Louis Bossart
3441da177e4SLinus Torvalds# Generated docbook code is inserted in a template at a point where
3451da177e4SLinus Torvalds# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
34693431e06SAlexander A. Klimov# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
3471da177e4SLinus Torvalds# We keep track of number of generated entries and generate a dummy
3481da177e4SLinus Torvalds# if needs be to ensure the expanded template can be postprocessed
3491da177e4SLinus Torvalds# into html.
3501da177e4SLinus Torvaldsmy $section_counter = 0;
3511da177e4SLinus Torvalds
3521da177e4SLinus Torvaldsmy $lineprefix="";
3531da177e4SLinus Torvalds
35448af606aSJani Nikula# Parser states
35548af606aSJani Nikulause constant {
35648af606aSJani Nikula    STATE_NORMAL        => 0,        # normal code
35748af606aSJani Nikula    STATE_NAME          => 1,        # looking for function name
35817b78717SJonathan Corbet    STATE_BODY_MAYBE    => 2,        # body - or maybe more description
35917b78717SJonathan Corbet    STATE_BODY          => 3,        # the body of the comment
3600d55d48bSMauro Carvalho Chehab    STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
3610d55d48bSMauro Carvalho Chehab    STATE_PROTO         => 5,        # scanning prototype
3620d55d48bSMauro Carvalho Chehab    STATE_DOCBLOCK      => 6,        # documentation block
3630d55d48bSMauro Carvalho Chehab    STATE_INLINE        => 7,        # gathering doc outside main block
36448af606aSJani Nikula};
3651da177e4SLinus Torvaldsmy $state;
366850622dfSRandy Dunlapmy $in_doc_sect;
367d742f24dSJonathan Corbetmy $leading_space;
3681da177e4SLinus Torvalds
36948af606aSJani Nikula# Inline documentation state
37048af606aSJani Nikulause constant {
37148af606aSJani Nikula    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
37248af606aSJani Nikula    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
37348af606aSJani Nikula    STATE_INLINE_TEXT   => 2, # looking for member documentation
37448af606aSJani Nikula    STATE_INLINE_END    => 3, # done
37548af606aSJani Nikula    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
37648af606aSJani Nikula                              # Spit a warning as it's not
377a4c6ebedSDanilo Cesar Lemes de Paula                              # proper kernel-doc and ignore the rest.
37848af606aSJani Nikula};
37948af606aSJani Nikulamy $inline_doc_state;
380a4c6ebedSDanilo Cesar Lemes de Paula
3811da177e4SLinus Torvalds#declaration types: can be
3821da177e4SLinus Torvalds# 'function', 'struct', 'union', 'enum', 'typedef'
3831da177e4SLinus Torvaldsmy $decl_type;
3841da177e4SLinus Torvalds
38552042e2dSMauro Carvalho Chehab# Name of the kernel-doc identifier for non-DOC markups
38652042e2dSMauro Carvalho Chehabmy $identifier;
38752042e2dSMauro Carvalho Chehab
3881da177e4SLinus Torvaldsmy $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
3891da177e4SLinus Torvaldsmy $doc_end = '\*/';
3901da177e4SLinus Torvaldsmy $doc_com = '\s*\*\s*';
39112ae6779SDaniel Santosmy $doc_com_body = '\s*\* ?';
3921da177e4SLinus Torvaldsmy $doc_decl = $doc_com . '(\w+)';
393f624adefSJani Nikula# @params and a strictly limited set of supported section names
3948569de68SJonathan Corbetmy $doc_sect = $doc_com .
395ef00028bSJonathan Corbet    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
39612ae6779SDaniel Santosmy $doc_content = $doc_com_body . '(.*)';
3971da177e4SLinus Torvaldsmy $doc_block = $doc_com . 'DOC:\s*(.*)?';
39848af606aSJani Nikulamy $doc_inline_start = '^\s*/\*\*\s*$';
399fe7bc493SMauro Carvalho Chehabmy $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
40048af606aSJani Nikulamy $doc_inline_end = '^\s*\*/\s*$';
4010c9aa209SJani Nikulamy $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
40286ae2e38SJani Nikulamy $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
4031da177e4SLinus Torvalds
4041da177e4SLinus Torvaldsmy %parameterdescs;
4050b0f5f29SDaniel Vettermy %parameterdesc_start_lines;
4061da177e4SLinus Torvaldsmy @parameterlist;
4071da177e4SLinus Torvaldsmy %sections;
4081da177e4SLinus Torvaldsmy @sectionlist;
4090b0f5f29SDaniel Vettermy %section_start_lines;
410a1d94aa5SRandy Dunlapmy $sectcheck;
411a1d94aa5SRandy Dunlapmy $struct_actual;
4121da177e4SLinus Torvalds
4131da177e4SLinus Torvaldsmy $contents = "";
4140b0f5f29SDaniel Vettermy $new_start_line = 0;
415f624adefSJani Nikula
416f624adefSJani Nikula# the canonical section names. see also $doc_sect above.
4171da177e4SLinus Torvaldsmy $section_default = "Description";	# default section
4181da177e4SLinus Torvaldsmy $section_intro = "Introduction";
4191da177e4SLinus Torvaldsmy $section = $section_default;
4201da177e4SLinus Torvaldsmy $section_context = "Context";
4214092bac7SYacine Belkadimy $section_return = "Return";
4221da177e4SLinus Torvalds
4231da177e4SLinus Torvaldsmy $undescribed = "-- undescribed --";
4241da177e4SLinus Torvalds
4251da177e4SLinus Torvaldsreset_state();
4261da177e4SLinus Torvalds
427b031ac4eSMauro Carvalho Chehabwhile ($ARGV[0] =~ m/^--?(.*)/) {
428b031ac4eSMauro Carvalho Chehab    my $cmd = $1;
429b031ac4eSMauro Carvalho Chehab    shift @ARGV;
430b031ac4eSMauro Carvalho Chehab    if ($cmd eq "man") {
4311da177e4SLinus Torvalds	$output_mode = "man";
4324d732701SDanilo Cesar Lemes de Paula	@highlights = @highlights_man;
4331da177e4SLinus Torvalds	$blankline = $blankline_man;
434b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "rst") {
435c0d1b6eeSJonathan Corbet	$output_mode = "rst";
436c0d1b6eeSJonathan Corbet	@highlights = @highlights_rst;
437c0d1b6eeSJonathan Corbet	$blankline = $blankline_rst;
438b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "none") {
4393a025e1dSMatthew Wilcox	$output_mode = "none";
440b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
4411da177e4SLinus Torvalds	$modulename = shift @ARGV;
442b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "function") { # to only output specific functions
443b6c3f456SJani Nikula	$output_selection = OUTPUT_INCLUDE;
4441da177e4SLinus Torvalds	$function = shift @ARGV;
4451da177e4SLinus Torvalds	$function_table{$function} = 1;
446eab795ddSMauro Carvalho Chehab    } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
447eab795ddSMauro Carvalho Chehab	my $symbol = shift @ARGV;
448eab795ddSMauro Carvalho Chehab	$nosymbol_table{$symbol} = 1;
449b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export") { # only exported symbols
450b6c3f456SJani Nikula	$output_selection = OUTPUT_EXPORTED;
451da9726ecSJani Nikula	%function_table = ();
452b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "internal") { # only non-exported symbols
453b6c3f456SJani Nikula	$output_selection = OUTPUT_INTERNAL;
454da9726ecSJani Nikula	%function_table = ();
455b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export-file") {
45688c2b57dSJani Nikula	my $file = shift @ARGV;
45788c2b57dSJani Nikula	push(@export_file_list, $file);
458b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "v") {
4591da177e4SLinus Torvalds	$verbose = 1;
4602c12c810SPierre-Louis Bossart    } elsif ($cmd eq "Werror") {
4612c12c810SPierre-Louis Bossart	$Werror = 1;
462b031ac4eSMauro Carvalho Chehab    } elsif (($cmd eq "h") || ($cmd eq "help")) {
4631da177e4SLinus Torvalds	usage();
464b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'no-doc-sections') {
4654b44595aSJohannes Berg	    $no_doc_sections = 1;
466b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'enable-lineno') {
4670b0f5f29SDaniel Vetter	    $enable_lineno = 1;
468b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'show-not-found') {
469b0d60bfbSJonathan Corbet	$show_not_found = 1;  # A no-op but don't fail
47093351d41SMauro Carvalho Chehab    } elsif ($cmd eq "sphinx-version") {
47193351d41SMauro Carvalho Chehab	my $ver_string = shift @ARGV;
47293351d41SMauro Carvalho Chehab	if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
47393351d41SMauro Carvalho Chehab	    $sphinx_major = $1;
47493351d41SMauro Carvalho Chehab	    if (defined($2)) {
47593351d41SMauro Carvalho Chehab		$sphinx_minor = substr($2,1);
47693351d41SMauro Carvalho Chehab	    } else {
47793351d41SMauro Carvalho Chehab		$sphinx_minor = 0;
47893351d41SMauro Carvalho Chehab	    }
47993351d41SMauro Carvalho Chehab	    if (defined($3)) {
48093351d41SMauro Carvalho Chehab		$sphinx_patch = substr($3,1)
48193351d41SMauro Carvalho Chehab	    } else {
48293351d41SMauro Carvalho Chehab		$sphinx_patch = 0;
48393351d41SMauro Carvalho Chehab	    }
48493351d41SMauro Carvalho Chehab	} else {
48593351d41SMauro Carvalho Chehab	    die "Sphinx version should either major.minor or major.minor.patch format\n";
48693351d41SMauro Carvalho Chehab	}
487b031ac4eSMauro Carvalho Chehab    } else {
488b031ac4eSMauro Carvalho Chehab	# Unknown argument
489b031ac4eSMauro Carvalho Chehab        usage();
4901da177e4SLinus Torvalds    }
4911da177e4SLinus Torvalds}
4921da177e4SLinus Torvalds
4938484baaaSRandy Dunlap# continue execution near EOF;
4948484baaaSRandy Dunlap
495efa44475SMauro Carvalho Chehab# The C domain dialect changed on Sphinx 3. So, we need to check the
496efa44475SMauro Carvalho Chehab# version in order to produce the right tags.
497efa44475SMauro Carvalho Chehabsub findprog($)
498efa44475SMauro Carvalho Chehab{
499efa44475SMauro Carvalho Chehab	foreach(split(/:/, $ENV{PATH})) {
500efa44475SMauro Carvalho Chehab		return "$_/$_[0]" if(-x "$_/$_[0]");
501efa44475SMauro Carvalho Chehab	}
502efa44475SMauro Carvalho Chehab}
503efa44475SMauro Carvalho Chehab
504efa44475SMauro Carvalho Chehabsub get_sphinx_version()
505efa44475SMauro Carvalho Chehab{
506efa44475SMauro Carvalho Chehab	my $ver;
507efa44475SMauro Carvalho Chehab
508efa44475SMauro Carvalho Chehab	my $cmd = "sphinx-build";
509efa44475SMauro Carvalho Chehab	if (!findprog($cmd)) {
510efa44475SMauro Carvalho Chehab		my $cmd = "sphinx-build3";
51193351d41SMauro Carvalho Chehab		if (!findprog($cmd)) {
51293351d41SMauro Carvalho Chehab			$sphinx_major = 1;
51393351d41SMauro Carvalho Chehab			$sphinx_minor = 2;
51493351d41SMauro Carvalho Chehab			$sphinx_patch = 0;
51593351d41SMauro Carvalho Chehab			printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
51693351d41SMauro Carvalho Chehab			       $sphinx_major, $sphinx_minor, $sphinx_patch;
51793351d41SMauro Carvalho Chehab			return;
51893351d41SMauro Carvalho Chehab		}
519efa44475SMauro Carvalho Chehab	}
520efa44475SMauro Carvalho Chehab
521efa44475SMauro Carvalho Chehab	open IN, "$cmd --version 2>&1 |";
522efa44475SMauro Carvalho Chehab	while (<IN>) {
523efa44475SMauro Carvalho Chehab		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
52493351d41SMauro Carvalho Chehab			$sphinx_major = $1;
52593351d41SMauro Carvalho Chehab			$sphinx_minor = $2;
52693351d41SMauro Carvalho Chehab			$sphinx_patch = $3;
527efa44475SMauro Carvalho Chehab			last;
528efa44475SMauro Carvalho Chehab		}
529efa44475SMauro Carvalho Chehab		# Sphinx 1.2.x uses a different format
530efa44475SMauro Carvalho Chehab		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
53193351d41SMauro Carvalho Chehab			$sphinx_major = $1;
53293351d41SMauro Carvalho Chehab			$sphinx_minor = $2;
53393351d41SMauro Carvalho Chehab			$sphinx_patch = $3;
534efa44475SMauro Carvalho Chehab			last;
535efa44475SMauro Carvalho Chehab		}
536efa44475SMauro Carvalho Chehab	}
537efa44475SMauro Carvalho Chehab	close IN;
538efa44475SMauro Carvalho Chehab}
539efa44475SMauro Carvalho Chehab
54053f049faSBorislav Petkov# get kernel version from env
54153f049faSBorislav Petkovsub get_kernel_version() {
5421b9bc22dSJohannes Berg    my $version = 'unknown kernel version';
54353f049faSBorislav Petkov
54453f049faSBorislav Petkov    if (defined($ENV{'KERNELVERSION'})) {
54553f049faSBorislav Petkov	$version = $ENV{'KERNELVERSION'};
54653f049faSBorislav Petkov    }
54753f049faSBorislav Petkov    return $version;
54853f049faSBorislav Petkov}
5491da177e4SLinus Torvalds
5500b0f5f29SDaniel Vetter#
5510b0f5f29SDaniel Vettersub print_lineno {
5520b0f5f29SDaniel Vetter    my $lineno = shift;
5530b0f5f29SDaniel Vetter    if ($enable_lineno && defined($lineno)) {
5540b0f5f29SDaniel Vetter        print "#define LINENO " . $lineno . "\n";
5550b0f5f29SDaniel Vetter    }
5560b0f5f29SDaniel Vetter}
5571da177e4SLinus Torvalds##
5581da177e4SLinus Torvalds# dumps section contents to arrays/hashes intended for that purpose.
5591da177e4SLinus Torvalds#
5601da177e4SLinus Torvaldssub dump_section {
56194dc7ad5SRandy Dunlap    my $file = shift;
5621da177e4SLinus Torvalds    my $name = shift;
5631da177e4SLinus Torvalds    my $contents = join "\n", @_;
5641da177e4SLinus Torvalds
56513901ef2SJani Nikula    if ($name =~ m/$type_param/) {
5661da177e4SLinus Torvalds	$name = $1;
5671da177e4SLinus Torvalds	$parameterdescs{$name} = $contents;
568a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
5690b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
5700b0f5f29SDaniel Vetter        $new_start_line = 0;
571ced69090SRandy Dunlap    } elsif ($name eq "@\.\.\.") {
572ced69090SRandy Dunlap	$name = "...";
573ced69090SRandy Dunlap	$parameterdescs{$name} = $contents;
574a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
5750b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
5760b0f5f29SDaniel Vetter        $new_start_line = 0;
5771da177e4SLinus Torvalds    } else {
57894dc7ad5SRandy Dunlap	if (defined($sections{$name}) && ($sections{$name} ne "")) {
57995b6be9dSJani Nikula	    # Only warn on user specified duplicate section names.
58095b6be9dSJani Nikula	    if ($name ne $section_default) {
58132217761SJani Nikula		print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
58232217761SJani Nikula		++$warnings;
58395b6be9dSJani Nikula	    }
58432217761SJani Nikula	    $sections{$name} .= $contents;
58532217761SJani Nikula	} else {
5861da177e4SLinus Torvalds	    $sections{$name} = $contents;
5871da177e4SLinus Torvalds	    push @sectionlist, $name;
5880b0f5f29SDaniel Vetter            $section_start_lines{$name} = $new_start_line;
5890b0f5f29SDaniel Vetter            $new_start_line = 0;
5901da177e4SLinus Torvalds	}
5911da177e4SLinus Torvalds    }
59232217761SJani Nikula}
5931da177e4SLinus Torvalds
5941da177e4SLinus Torvalds##
595b112e0f7SJohannes Berg# dump DOC: section after checking that it should go out
596b112e0f7SJohannes Berg#
597b112e0f7SJohannes Bergsub dump_doc_section {
59894dc7ad5SRandy Dunlap    my $file = shift;
599b112e0f7SJohannes Berg    my $name = shift;
600b112e0f7SJohannes Berg    my $contents = join "\n", @_;
601b112e0f7SJohannes Berg
6024b44595aSJohannes Berg    if ($no_doc_sections) {
6034b44595aSJohannes Berg        return;
6044b44595aSJohannes Berg    }
6054b44595aSJohannes Berg
606eab795ddSMauro Carvalho Chehab    return if (defined($nosymbol_table{$name}));
607eab795ddSMauro Carvalho Chehab
608b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
609eab795ddSMauro Carvalho Chehab	(($output_selection == OUTPUT_INCLUDE) &&
610eab795ddSMauro Carvalho Chehab	 defined($function_table{$name})))
611b112e0f7SJohannes Berg    {
61294dc7ad5SRandy Dunlap	dump_section($file, $name, $contents);
613b112e0f7SJohannes Berg	output_blockhead({'sectionlist' => \@sectionlist,
614b112e0f7SJohannes Berg			  'sections' => \%sections,
615b112e0f7SJohannes Berg			  'module' => $modulename,
616b6c3f456SJani Nikula			  'content-only' => ($output_selection != OUTPUT_ALL), });
617b112e0f7SJohannes Berg    }
618b112e0f7SJohannes Berg}
619b112e0f7SJohannes Berg
620b112e0f7SJohannes Berg##
6211da177e4SLinus Torvalds# output function
6221da177e4SLinus Torvalds#
6231da177e4SLinus Torvalds# parameterdescs, a hash.
6241da177e4SLinus Torvalds#  function => "function name"
6251da177e4SLinus Torvalds#  parameterlist => @list of parameters
6261da177e4SLinus Torvalds#  parameterdescs => %parameter descriptions
6271da177e4SLinus Torvalds#  sectionlist => @list of sections
628a21217daSRandy Dunlap#  sections => %section descriptions
6291da177e4SLinus Torvalds#
6301da177e4SLinus Torvalds
6311da177e4SLinus Torvaldssub output_highlight {
6321da177e4SLinus Torvalds    my $contents = join "\n",@_;
6331da177e4SLinus Torvalds    my $line;
6341da177e4SLinus Torvalds
6351da177e4SLinus Torvalds#   DEBUG
6361da177e4SLinus Torvalds#   if (!defined $contents) {
6371da177e4SLinus Torvalds#	use Carp;
6381da177e4SLinus Torvalds#	confess "output_highlight got called with no args?\n";
6391da177e4SLinus Torvalds#   }
6401da177e4SLinus Torvalds
6413eb014a1SRandy Dunlap#   print STDERR "contents b4:$contents\n";
6421da177e4SLinus Torvalds    eval $dohighlight;
6431da177e4SLinus Torvalds    die $@ if $@;
6443eb014a1SRandy Dunlap#   print STDERR "contents af:$contents\n";
6453eb014a1SRandy Dunlap
6461da177e4SLinus Torvalds    foreach $line (split "\n", $contents) {
64712ae6779SDaniel Santos	if (! $output_preformatted) {
64812ae6779SDaniel Santos	    $line =~ s/^\s*//;
64912ae6779SDaniel Santos	}
6501da177e4SLinus Torvalds	if ($line eq ""){
651e314ba31SDaniel Santos	    if (! $output_preformatted) {
6520bba924cSJonathan Corbet		print $lineprefix, $blankline;
653e314ba31SDaniel Santos	    }
6541da177e4SLinus Torvalds	} else {
655cdccb316SRandy Dunlap	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
656cdccb316SRandy Dunlap		print "\\&$line";
657cdccb316SRandy Dunlap	    } else {
6581da177e4SLinus Torvalds		print $lineprefix, $line;
6591da177e4SLinus Torvalds	    }
660cdccb316SRandy Dunlap	}
6611da177e4SLinus Torvalds	print "\n";
6621da177e4SLinus Torvalds    }
6631da177e4SLinus Torvalds}
6641da177e4SLinus Torvalds
6651da177e4SLinus Torvalds##
6661da177e4SLinus Torvalds# output function in man
6671da177e4SLinus Torvaldssub output_function_man(%) {
6681da177e4SLinus Torvalds    my %args = %{$_[0]};
6691da177e4SLinus Torvalds    my ($parameter, $section);
6701da177e4SLinus Torvalds    my $count;
6711da177e4SLinus Torvalds
6721da177e4SLinus Torvalds    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
6731da177e4SLinus Torvalds
6741da177e4SLinus Torvalds    print ".SH NAME\n";
6751da177e4SLinus Torvalds    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
6761da177e4SLinus Torvalds
6771da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
678a21217daSRandy Dunlap    if ($args{'functiontype'} ne "") {
6791da177e4SLinus Torvalds	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
680a21217daSRandy Dunlap    } else {
681a21217daSRandy Dunlap	print ".B \"" . $args{'function'} . "\n";
682a21217daSRandy Dunlap    }
6831da177e4SLinus Torvalds    $count = 0;
6841da177e4SLinus Torvalds    my $parenth = "(";
6851da177e4SLinus Torvalds    my $post = ",";
6861da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
6871da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
6881da177e4SLinus Torvalds	    $post = ");";
6891da177e4SLinus Torvalds	}
6901da177e4SLinus Torvalds	$type = $args{'parametertypes'}{$parameter};
6911da177e4SLinus Torvalds	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
6921da177e4SLinus Torvalds	    # pointer-to-function
693ed8348e2SMauro Carvalho Chehab	    print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
6941da177e4SLinus Torvalds	} else {
6951da177e4SLinus Torvalds	    $type =~ s/([^\*])$/$1 /;
696ed8348e2SMauro Carvalho Chehab	    print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
6971da177e4SLinus Torvalds	}
6981da177e4SLinus Torvalds	$count++;
6991da177e4SLinus Torvalds	$parenth = "";
7001da177e4SLinus Torvalds    }
7011da177e4SLinus Torvalds
7021da177e4SLinus Torvalds    print ".SH ARGUMENTS\n";
7031da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
7041da177e4SLinus Torvalds	my $parameter_name = $parameter;
7051da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
7061da177e4SLinus Torvalds
7071da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
7081da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
7091da177e4SLinus Torvalds    }
7101da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
7111da177e4SLinus Torvalds	print ".SH \"", uc $section, "\"\n";
7121da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
7131da177e4SLinus Torvalds    }
7141da177e4SLinus Torvalds}
7151da177e4SLinus Torvalds
7161da177e4SLinus Torvalds##
7171da177e4SLinus Torvalds# output enum in man
7181da177e4SLinus Torvaldssub output_enum_man(%) {
7191da177e4SLinus Torvalds    my %args = %{$_[0]};
7201da177e4SLinus Torvalds    my ($parameter, $section);
7211da177e4SLinus Torvalds    my $count;
7221da177e4SLinus Torvalds
7231da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
7241da177e4SLinus Torvalds
7251da177e4SLinus Torvalds    print ".SH NAME\n";
7261da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
7271da177e4SLinus Torvalds
7281da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
7291da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " {\n";
7301da177e4SLinus Torvalds    $count = 0;
7311da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
7321da177e4SLinus Torvalds	print ".br\n.BI \"    $parameter\"\n";
7331da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
7341da177e4SLinus Torvalds	    print "\n};\n";
7351da177e4SLinus Torvalds	    last;
7361da177e4SLinus Torvalds	}
7371da177e4SLinus Torvalds	else {
7381da177e4SLinus Torvalds	    print ", \n.br\n";
7391da177e4SLinus Torvalds	}
7401da177e4SLinus Torvalds	$count++;
7411da177e4SLinus Torvalds    }
7421da177e4SLinus Torvalds
7431da177e4SLinus Torvalds    print ".SH Constants\n";
7441da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
7451da177e4SLinus Torvalds	my $parameter_name = $parameter;
7461da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
7471da177e4SLinus Torvalds
7481da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
7491da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
7501da177e4SLinus Torvalds    }
7511da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
7521da177e4SLinus Torvalds	print ".SH \"$section\"\n";
7531da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
7541da177e4SLinus Torvalds    }
7551da177e4SLinus Torvalds}
7561da177e4SLinus Torvalds
7571da177e4SLinus Torvalds##
7581da177e4SLinus Torvalds# output struct in man
7591da177e4SLinus Torvaldssub output_struct_man(%) {
7601da177e4SLinus Torvalds    my %args = %{$_[0]};
7611da177e4SLinus Torvalds    my ($parameter, $section);
7621da177e4SLinus Torvalds
7631da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
7641da177e4SLinus Torvalds
7651da177e4SLinus Torvalds    print ".SH NAME\n";
7661da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
7671da177e4SLinus Torvalds
7688ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
7698ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
7708ad72163SMauro Carvalho Chehab    $declaration =~ s/\n/"\n.br\n.BI \"/g;
7711da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
7721da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
7738ad72163SMauro Carvalho Chehab    print ".BI \"$declaration\n};\n.br\n\n";
7741da177e4SLinus Torvalds
775c51d3dacSRandy Dunlap    print ".SH Members\n";
7761da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
7771da177e4SLinus Torvalds	($parameter =~ /^#/) && next;
7781da177e4SLinus Torvalds
7791da177e4SLinus Torvalds	my $parameter_name = $parameter;
7801da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
7811da177e4SLinus Torvalds
7821da177e4SLinus Torvalds	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
7831da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
7841da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
7851da177e4SLinus Torvalds    }
7861da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
7871da177e4SLinus Torvalds	print ".SH \"$section\"\n";
7881da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
7891da177e4SLinus Torvalds    }
7901da177e4SLinus Torvalds}
7911da177e4SLinus Torvalds
7921da177e4SLinus Torvalds##
7931da177e4SLinus Torvalds# output typedef in man
7941da177e4SLinus Torvaldssub output_typedef_man(%) {
7951da177e4SLinus Torvalds    my %args = %{$_[0]};
7961da177e4SLinus Torvalds    my ($parameter, $section);
7971da177e4SLinus Torvalds
7981da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
7991da177e4SLinus Torvalds
8001da177e4SLinus Torvalds    print ".SH NAME\n";
8011da177e4SLinus Torvalds    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
8021da177e4SLinus Torvalds
8031da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
8041da177e4SLinus Torvalds	print ".SH \"$section\"\n";
8051da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
8061da177e4SLinus Torvalds    }
8071da177e4SLinus Torvalds}
8081da177e4SLinus Torvalds
809b112e0f7SJohannes Bergsub output_blockhead_man(%) {
8101da177e4SLinus Torvalds    my %args = %{$_[0]};
8111da177e4SLinus Torvalds    my ($parameter, $section);
8121da177e4SLinus Torvalds    my $count;
8131da177e4SLinus Torvalds
8141da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
8151da177e4SLinus Torvalds
8161da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
8171da177e4SLinus Torvalds	print ".SH \"$section\"\n";
8181da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
8191da177e4SLinus Torvalds    }
8201da177e4SLinus Torvalds}
8211da177e4SLinus Torvalds
8221da177e4SLinus Torvalds##
823c0d1b6eeSJonathan Corbet# output in restructured text
824c0d1b6eeSJonathan Corbet#
825c0d1b6eeSJonathan Corbet
826c0d1b6eeSJonathan Corbet#
827c0d1b6eeSJonathan Corbet# This could use some work; it's used to output the DOC: sections, and
828c0d1b6eeSJonathan Corbet# starts by putting out the name of the doc section itself, but that tends
829c0d1b6eeSJonathan Corbet# to duplicate a header already in the template file.
830c0d1b6eeSJonathan Corbet#
831c0d1b6eeSJonathan Corbetsub output_blockhead_rst(%) {
832c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
833c0d1b6eeSJonathan Corbet    my ($parameter, $section);
834c0d1b6eeSJonathan Corbet
835c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
836eab795ddSMauro Carvalho Chehab	next if (defined($nosymbol_table{$section}));
837eab795ddSMauro Carvalho Chehab
8389e72184bSJani Nikula	if ($output_selection != OUTPUT_INCLUDE) {
83906a755d6SMichal Wajdeczko	    print ".. _$section:\n\n";
840c0d1b6eeSJonathan Corbet	    print "**$section**\n\n";
8419e72184bSJani Nikula	}
8420b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
843c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
844c0d1b6eeSJonathan Corbet	print "\n";
845c0d1b6eeSJonathan Corbet    }
846c0d1b6eeSJonathan Corbet}
847c0d1b6eeSJonathan Corbet
848af250290SJonathan Corbet#
849af250290SJonathan Corbet# Apply the RST highlights to a sub-block of text.
850af250290SJonathan Corbet#
851af250290SJonathan Corbetsub highlight_block($) {
852af250290SJonathan Corbet    # The dohighlight kludge requires the text be called $contents
853af250290SJonathan Corbet    my $contents = shift;
854c0d1b6eeSJonathan Corbet    eval $dohighlight;
855c0d1b6eeSJonathan Corbet    die $@ if $@;
856af250290SJonathan Corbet    return $contents;
857af250290SJonathan Corbet}
858c0d1b6eeSJonathan Corbet
859af250290SJonathan Corbet#
860af250290SJonathan Corbet# Regexes used only here.
861af250290SJonathan Corbet#
862af250290SJonathan Corbetmy $sphinx_literal = '^[^.].*::$';
863af250290SJonathan Corbetmy $sphinx_cblock = '^\.\.\ +code-block::';
864af250290SJonathan Corbet
865af250290SJonathan Corbetsub output_highlight_rst {
866af250290SJonathan Corbet    my $input = join "\n",@_;
867af250290SJonathan Corbet    my $output = "";
868af250290SJonathan Corbet    my $line;
869af250290SJonathan Corbet    my $in_literal = 0;
870af250290SJonathan Corbet    my $litprefix;
871af250290SJonathan Corbet    my $block = "";
872af250290SJonathan Corbet
873af250290SJonathan Corbet    foreach $line (split "\n",$input) {
874af250290SJonathan Corbet	#
875af250290SJonathan Corbet	# If we're in a literal block, see if we should drop out
876af250290SJonathan Corbet	# of it.  Otherwise pass the line straight through unmunged.
877af250290SJonathan Corbet	#
878af250290SJonathan Corbet	if ($in_literal) {
879af250290SJonathan Corbet	    if (! ($line =~ /^\s*$/)) {
880af250290SJonathan Corbet		#
881af250290SJonathan Corbet		# If this is the first non-blank line in a literal
882af250290SJonathan Corbet		# block we need to figure out what the proper indent is.
883af250290SJonathan Corbet		#
884af250290SJonathan Corbet		if ($litprefix eq "") {
885af250290SJonathan Corbet		    $line =~ /^(\s*)/;
886af250290SJonathan Corbet		    $litprefix = '^' . $1;
887af250290SJonathan Corbet		    $output .= $line . "\n";
888af250290SJonathan Corbet		} elsif (! ($line =~ /$litprefix/)) {
889af250290SJonathan Corbet		    $in_literal = 0;
890af250290SJonathan Corbet		} else {
891af250290SJonathan Corbet		    $output .= $line . "\n";
892af250290SJonathan Corbet		}
893af250290SJonathan Corbet	    } else {
894af250290SJonathan Corbet		$output .= $line . "\n";
895af250290SJonathan Corbet	    }
896af250290SJonathan Corbet	}
897af250290SJonathan Corbet	#
898af250290SJonathan Corbet	# Not in a literal block (or just dropped out)
899af250290SJonathan Corbet	#
900af250290SJonathan Corbet	if (! $in_literal) {
901af250290SJonathan Corbet	    $block .= $line . "\n";
902af250290SJonathan Corbet	    if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
903af250290SJonathan Corbet		$in_literal = 1;
904af250290SJonathan Corbet		$litprefix = "";
905af250290SJonathan Corbet		$output .= highlight_block($block);
906af250290SJonathan Corbet		$block = ""
907af250290SJonathan Corbet	    }
908af250290SJonathan Corbet	}
909af250290SJonathan Corbet    }
910af250290SJonathan Corbet
911af250290SJonathan Corbet    if ($block) {
912af250290SJonathan Corbet	$output .= highlight_block($block);
913af250290SJonathan Corbet    }
914af250290SJonathan Corbet    foreach $line (split "\n", $output) {
915830066a7SJani Nikula	print $lineprefix . $line . "\n";
916c0d1b6eeSJonathan Corbet    }
917c0d1b6eeSJonathan Corbet}
918c0d1b6eeSJonathan Corbet
919c0d1b6eeSJonathan Corbetsub output_function_rst(%) {
920c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
921c0d1b6eeSJonathan Corbet    my ($parameter, $section);
922c099ff69SJani Nikula    my $oldprefix = $lineprefix;
92382801d06SMauro Carvalho Chehab    my $start = "";
9246e9e4158SMauro Carvalho Chehab    my $is_macro = 0;
925c0d1b6eeSJonathan Corbet
926efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
927e3ad05feSMauro Carvalho Chehab	if ($args{'typedef'}) {
92882801d06SMauro Carvalho Chehab	    print ".. c:type:: ". $args{'function'} . "\n\n";
92982801d06SMauro Carvalho Chehab	    print_lineno($declaration_start_line);
93082801d06SMauro Carvalho Chehab	    print "   **Typedef**: ";
93182801d06SMauro Carvalho Chehab	    $lineprefix = "";
93282801d06SMauro Carvalho Chehab	    output_highlight_rst($args{'purpose'});
93382801d06SMauro Carvalho Chehab	    $start = "\n\n**Syntax**\n\n  ``";
9346e9e4158SMauro Carvalho Chehab	    $is_macro = 1;
935c0d1b6eeSJonathan Corbet	} else {
93682801d06SMauro Carvalho Chehab	    print ".. c:function:: ";
93782801d06SMauro Carvalho Chehab	}
938e3ad05feSMauro Carvalho Chehab    } else {
9396e9e4158SMauro Carvalho Chehab	if ($args{'typedef'} || $args{'functiontype'} eq "") {
9406e9e4158SMauro Carvalho Chehab	    $is_macro = 1;
941e3ad05feSMauro Carvalho Chehab	    print ".. c:macro:: ". $args{'function'} . "\n\n";
9426e9e4158SMauro Carvalho Chehab	} else {
9436e9e4158SMauro Carvalho Chehab	    print ".. c:function:: ";
9446e9e4158SMauro Carvalho Chehab	}
945e3ad05feSMauro Carvalho Chehab
946e3ad05feSMauro Carvalho Chehab	if ($args{'typedef'}) {
947e3ad05feSMauro Carvalho Chehab	    print_lineno($declaration_start_line);
948e3ad05feSMauro Carvalho Chehab	    print "   **Typedef**: ";
949e3ad05feSMauro Carvalho Chehab	    $lineprefix = "";
950e3ad05feSMauro Carvalho Chehab	    output_highlight_rst($args{'purpose'});
951e3ad05feSMauro Carvalho Chehab	    $start = "\n\n**Syntax**\n\n  ``";
952e3ad05feSMauro Carvalho Chehab	} else {
9536e9e4158SMauro Carvalho Chehab	    print "``" if ($is_macro);
954e3ad05feSMauro Carvalho Chehab	}
955e3ad05feSMauro Carvalho Chehab    }
95682801d06SMauro Carvalho Chehab    if ($args{'functiontype'} ne "") {
95782801d06SMauro Carvalho Chehab	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
95882801d06SMauro Carvalho Chehab    } else {
95982801d06SMauro Carvalho Chehab	$start .= $args{'function'} . " (";
960c0d1b6eeSJonathan Corbet    }
961c0d1b6eeSJonathan Corbet    print $start;
962c0d1b6eeSJonathan Corbet
963c0d1b6eeSJonathan Corbet    my $count = 0;
964c0d1b6eeSJonathan Corbet    foreach my $parameter (@{$args{'parameterlist'}}) {
965c0d1b6eeSJonathan Corbet	if ($count ne 0) {
966c0d1b6eeSJonathan Corbet	    print ", ";
967c0d1b6eeSJonathan Corbet	}
968c0d1b6eeSJonathan Corbet	$count++;
969c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
970a88b1672SMauro Carvalho Chehab
971c0d1b6eeSJonathan Corbet	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
972c0d1b6eeSJonathan Corbet	    # pointer-to-function
973e8f4ba83SPeter Maydell	    print $1 . $parameter . ") (" . $2 . ")";
974c0d1b6eeSJonathan Corbet	} else {
975ed8348e2SMauro Carvalho Chehab	    print $type;
976c0d1b6eeSJonathan Corbet	}
977c0d1b6eeSJonathan Corbet    }
9786e9e4158SMauro Carvalho Chehab    if ($is_macro) {
9796e9e4158SMauro Carvalho Chehab	print ")``\n\n";
98082801d06SMauro Carvalho Chehab    } else {
981c099ff69SJani Nikula	print ")\n\n";
982e3ad05feSMauro Carvalho Chehab    }
9836e9e4158SMauro Carvalho Chehab    if (!$args{'typedef'}) {
9840b0f5f29SDaniel Vetter	print_lineno($declaration_start_line);
985c099ff69SJani Nikula	$lineprefix = "   ";
986c099ff69SJani Nikula	output_highlight_rst($args{'purpose'});
987c099ff69SJani Nikula	print "\n";
98882801d06SMauro Carvalho Chehab    }
989c0d1b6eeSJonathan Corbet
990ecbcfba1SJani Nikula    print "**Parameters**\n\n";
991c099ff69SJani Nikula    $lineprefix = "  ";
992c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
993c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
994ada5f446SGabriel Krisman Bertazi	$parameter_name =~ s/\[.*//;
995c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
996c0d1b6eeSJonathan Corbet
997c0d1b6eeSJonathan Corbet	if ($type ne "") {
998ed8348e2SMauro Carvalho Chehab	    print "``$type``\n";
999c0d1b6eeSJonathan Corbet	} else {
1000c0d1b6eeSJonathan Corbet	    print "``$parameter``\n";
1001c0d1b6eeSJonathan Corbet	}
10020b0f5f29SDaniel Vetter
10030b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
10040b0f5f29SDaniel Vetter
10055e64fa9cSJani Nikula	if (defined($args{'parameterdescs'}{$parameter_name}) &&
10065e64fa9cSJani Nikula	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1007c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1008c0d1b6eeSJonathan Corbet	} else {
1009d4b08e0cSJani Nikula	    print "  *undescribed*\n";
1010c0d1b6eeSJonathan Corbet	}
1011c0d1b6eeSJonathan Corbet	print "\n";
1012c0d1b6eeSJonathan Corbet    }
1013c099ff69SJani Nikula
1014c099ff69SJani Nikula    $lineprefix = $oldprefix;
1015c0d1b6eeSJonathan Corbet    output_section_rst(@_);
1016c0d1b6eeSJonathan Corbet}
1017c0d1b6eeSJonathan Corbet
1018c0d1b6eeSJonathan Corbetsub output_section_rst(%) {
1019c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
1020c0d1b6eeSJonathan Corbet    my $section;
1021c0d1b6eeSJonathan Corbet    my $oldprefix = $lineprefix;
1022c0d1b6eeSJonathan Corbet    $lineprefix = "";
1023c0d1b6eeSJonathan Corbet
1024c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
1025ecbcfba1SJani Nikula	print "**$section**\n\n";
10260b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
1027c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
1028c0d1b6eeSJonathan Corbet	print "\n";
1029c0d1b6eeSJonathan Corbet    }
1030c0d1b6eeSJonathan Corbet    print "\n";
1031c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
1032c0d1b6eeSJonathan Corbet}
1033c0d1b6eeSJonathan Corbet
1034c0d1b6eeSJonathan Corbetsub output_enum_rst(%) {
1035c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
1036c0d1b6eeSJonathan Corbet    my ($parameter);
1037c099ff69SJani Nikula    my $oldprefix = $lineprefix;
1038c0d1b6eeSJonathan Corbet    my $count;
103962850976SJani Nikula
1040efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
1041efa44475SMauro Carvalho Chehab	my $name = "enum " . $args{'enum'};
104262850976SJani Nikula	print "\n\n.. c:type:: " . $name . "\n\n";
1043efa44475SMauro Carvalho Chehab    } else {
1044efa44475SMauro Carvalho Chehab	my $name = $args{'enum'};
1045efa44475SMauro Carvalho Chehab	print "\n\n.. c:enum:: " . $name . "\n\n";
1046efa44475SMauro Carvalho Chehab    }
10470b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
1048c099ff69SJani Nikula    $lineprefix = "   ";
1049c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
1050c099ff69SJani Nikula    print "\n";
1051c0d1b6eeSJonathan Corbet
1052ecbcfba1SJani Nikula    print "**Constants**\n\n";
1053c0d1b6eeSJonathan Corbet    $lineprefix = "  ";
1054c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
1055ecbcfba1SJani Nikula	print "``$parameter``\n";
1056c0d1b6eeSJonathan Corbet	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1057c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter});
1058c0d1b6eeSJonathan Corbet	} else {
1059d4b08e0cSJani Nikula	    print "  *undescribed*\n";
1060c0d1b6eeSJonathan Corbet	}
1061c0d1b6eeSJonathan Corbet	print "\n";
1062c0d1b6eeSJonathan Corbet    }
1063c099ff69SJani Nikula
1064c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
1065c0d1b6eeSJonathan Corbet    output_section_rst(@_);
1066c0d1b6eeSJonathan Corbet}
1067c0d1b6eeSJonathan Corbet
1068c0d1b6eeSJonathan Corbetsub output_typedef_rst(%) {
1069c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
1070c0d1b6eeSJonathan Corbet    my ($parameter);
1071c099ff69SJani Nikula    my $oldprefix = $lineprefix;
1072efa44475SMauro Carvalho Chehab    my $name;
1073c0d1b6eeSJonathan Corbet
1074efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
1075efa44475SMauro Carvalho Chehab	$name = "typedef " . $args{'typedef'};
1076efa44475SMauro Carvalho Chehab    } else {
1077efa44475SMauro Carvalho Chehab	$name = $args{'typedef'};
1078efa44475SMauro Carvalho Chehab    }
107962850976SJani Nikula    print "\n\n.. c:type:: " . $name . "\n\n";
10800b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
1081c099ff69SJani Nikula    $lineprefix = "   ";
1082c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
1083c099ff69SJani Nikula    print "\n";
1084c0d1b6eeSJonathan Corbet
1085c099ff69SJani Nikula    $lineprefix = $oldprefix;
1086c0d1b6eeSJonathan Corbet    output_section_rst(@_);
1087c0d1b6eeSJonathan Corbet}
1088c0d1b6eeSJonathan Corbet
1089c0d1b6eeSJonathan Corbetsub output_struct_rst(%) {
1090c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
1091c0d1b6eeSJonathan Corbet    my ($parameter);
1092c099ff69SJani Nikula    my $oldprefix = $lineprefix;
1093c0d1b6eeSJonathan Corbet
1094efa44475SMauro Carvalho Chehab    if ($sphinx_major < 3) {
1095efa44475SMauro Carvalho Chehab	my $name = $args{'type'} . " " . $args{'struct'};
109662850976SJani Nikula	print "\n\n.. c:type:: " . $name . "\n\n";
1097efa44475SMauro Carvalho Chehab    } else {
1098efa44475SMauro Carvalho Chehab	my $name = $args{'struct'};
109972b97d0bSMauro Carvalho Chehab	if ($args{'type'} eq 'union') {
110072b97d0bSMauro Carvalho Chehab	    print "\n\n.. c:union:: " . $name . "\n\n";
110172b97d0bSMauro Carvalho Chehab	} else {
1102efa44475SMauro Carvalho Chehab	    print "\n\n.. c:struct:: " . $name . "\n\n";
1103efa44475SMauro Carvalho Chehab	}
110472b97d0bSMauro Carvalho Chehab    }
11050b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
1106c099ff69SJani Nikula    $lineprefix = "   ";
1107c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
1108c099ff69SJani Nikula    print "\n";
1109c0d1b6eeSJonathan Corbet
1110ecbcfba1SJani Nikula    print "**Definition**\n\n";
1111c0d1b6eeSJonathan Corbet    print "::\n\n";
11128ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
11138ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
11148ad72163SMauro Carvalho Chehab    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration  };\n\n";
1115c0d1b6eeSJonathan Corbet
1116ecbcfba1SJani Nikula    print "**Members**\n\n";
1117c099ff69SJani Nikula    $lineprefix = "  ";
1118c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
1119c0d1b6eeSJonathan Corbet	($parameter =~ /^#/) && next;
1120c0d1b6eeSJonathan Corbet
1121c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
1122c0d1b6eeSJonathan Corbet	$parameter_name =~ s/\[.*//;
1123c0d1b6eeSJonathan Corbet
1124c0d1b6eeSJonathan Corbet	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1125c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
11260b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
11276d232c80SMauro Carvalho Chehab	print "``" . $parameter . "``\n";
1128c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1129c0d1b6eeSJonathan Corbet	print "\n";
1130c0d1b6eeSJonathan Corbet    }
1131c0d1b6eeSJonathan Corbet    print "\n";
1132c099ff69SJani Nikula
1133c099ff69SJani Nikula    $lineprefix = $oldprefix;
1134c0d1b6eeSJonathan Corbet    output_section_rst(@_);
1135c0d1b6eeSJonathan Corbet}
1136c0d1b6eeSJonathan Corbet
11373a025e1dSMatthew Wilcox## none mode output functions
11383a025e1dSMatthew Wilcox
11393a025e1dSMatthew Wilcoxsub output_function_none(%) {
11403a025e1dSMatthew Wilcox}
11413a025e1dSMatthew Wilcox
11423a025e1dSMatthew Wilcoxsub output_enum_none(%) {
11433a025e1dSMatthew Wilcox}
11443a025e1dSMatthew Wilcox
11453a025e1dSMatthew Wilcoxsub output_typedef_none(%) {
11463a025e1dSMatthew Wilcox}
11473a025e1dSMatthew Wilcox
11483a025e1dSMatthew Wilcoxsub output_struct_none(%) {
11493a025e1dSMatthew Wilcox}
11503a025e1dSMatthew Wilcox
11513a025e1dSMatthew Wilcoxsub output_blockhead_none(%) {
11523a025e1dSMatthew Wilcox}
11533a025e1dSMatthew Wilcox
11541da177e4SLinus Torvalds##
115527205744SRandy Dunlap# generic output function for all types (function, struct/union, typedef, enum);
115627205744SRandy Dunlap# calls the generated, variable output_ function name based on
115727205744SRandy Dunlap# functype and output_mode
11581da177e4SLinus Torvaldssub output_declaration {
11591da177e4SLinus Torvalds    no strict 'refs';
11601da177e4SLinus Torvalds    my $name = shift;
11611da177e4SLinus Torvalds    my $functype = shift;
11621da177e4SLinus Torvalds    my $func = "output_${functype}_$output_mode";
1163eab795ddSMauro Carvalho Chehab
1164eab795ddSMauro Carvalho Chehab    return if (defined($nosymbol_table{$name}));
1165eab795ddSMauro Carvalho Chehab
1166b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
1167b6c3f456SJani Nikula	(($output_selection == OUTPUT_INCLUDE ||
1168b6c3f456SJani Nikula	  $output_selection == OUTPUT_EXPORTED) &&
116986ae2e38SJani Nikula	 defined($function_table{$name})) ||
1170eab795ddSMauro Carvalho Chehab	($output_selection == OUTPUT_INTERNAL &&
117186ae2e38SJani Nikula	 !($functype eq "function" && defined($function_table{$name}))))
11721da177e4SLinus Torvalds    {
11731da177e4SLinus Torvalds	&$func(@_);
11741da177e4SLinus Torvalds	$section_counter++;
11751da177e4SLinus Torvalds    }
11761da177e4SLinus Torvalds}
11771da177e4SLinus Torvalds
11781da177e4SLinus Torvalds##
117927205744SRandy Dunlap# generic output function - calls the right one based on current output mode.
1180b112e0f7SJohannes Bergsub output_blockhead {
11811da177e4SLinus Torvalds    no strict 'refs';
1182b112e0f7SJohannes Berg    my $func = "output_blockhead_" . $output_mode;
11831da177e4SLinus Torvalds    &$func(@_);
11841da177e4SLinus Torvalds    $section_counter++;
11851da177e4SLinus Torvalds}
11861da177e4SLinus Torvalds
11871da177e4SLinus Torvalds##
11881da177e4SLinus Torvalds# takes a declaration (struct, union, enum, typedef) and
11891da177e4SLinus Torvalds# invokes the right handler. NOT called for functions.
11901da177e4SLinus Torvaldssub dump_declaration($$) {
11911da177e4SLinus Torvalds    no strict 'refs';
11921da177e4SLinus Torvalds    my ($prototype, $file) = @_;
11931da177e4SLinus Torvalds    my $func = "dump_" . $decl_type;
11941da177e4SLinus Torvalds    &$func(@_);
11951da177e4SLinus Torvalds}
11961da177e4SLinus Torvalds
11971da177e4SLinus Torvaldssub dump_union($$) {
11981da177e4SLinus Torvalds    dump_struct(@_);
11991da177e4SLinus Torvalds}
12001da177e4SLinus Torvalds
12011da177e4SLinus Torvaldssub dump_struct($$) {
12021da177e4SLinus Torvalds    my $x = shift;
12031da177e4SLinus Torvalds    my $file = shift;
1204a746fe32SAditya Srivastava    my $decl_type;
1205a746fe32SAditya Srivastava    my $members;
1206a746fe32SAditya Srivastava    my $type = qr{struct|union};
1207a746fe32SAditya Srivastava    # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
1208a746fe32SAditya Srivastava    my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*};
12091da177e4SLinus Torvalds
1210a746fe32SAditya Srivastava    if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
1211a746fe32SAditya Srivastava	$decl_type = $1;
12121da177e4SLinus Torvalds	$declaration_name = $2;
1213a746fe32SAditya Srivastava	$members = $3;
1214a746fe32SAditya Srivastava    } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
1215a746fe32SAditya Srivastava	$decl_type = $1;
1216a746fe32SAditya Srivastava	$declaration_name = $3;
1217a746fe32SAditya Srivastava	$members = $2;
1218a746fe32SAditya Srivastava    }
12191da177e4SLinus Torvalds
1220a746fe32SAditya Srivastava    if ($members) {
122152042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
122252042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
122352042e2dSMauro Carvalho Chehab	    return;
122452042e2dSMauro Carvalho Chehab	}
122552042e2dSMauro Carvalho Chehab
1226aeec46b9SMartin Waitz	# ignore members marked private:
12270d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
12280d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*//gosi;
1229aeec46b9SMartin Waitz	# strip comments:
1230aeec46b9SMartin Waitz	$members =~ s/\/\*.*?\*\///gos;
1231ef5da59fSRandy Dunlap	# strip attributes
12323d9bfb19SSakari Ailus	$members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi;
12333d9bfb19SSakari Ailus	$members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
12343d9bfb19SSakari Ailus	$members =~ s/\s*__packed\s*/ /gos;
1235f0074929SJonathan Corbet	$members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1236f861537dSAndré Almeida	$members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1237a070991fSJonathan Cameron	$members =~ s/\s*____cacheline_aligned/ /gos;
12383556108eSMauro Carvalho Chehab
1239b22b5a9eSConchúr Navid	# replace DECLARE_BITMAP
12403556108eSMauro Carvalho Chehab	$members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
124145005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
12421cb566baSJakub Kicinski	# replace DECLARE_HASHTABLE
124345005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
124445005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO
124545005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
124645005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO_PTR
124745005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1248aeec46b9SMartin Waitz
12498ad72163SMauro Carvalho Chehab	my $declaration = $members;
12508ad72163SMauro Carvalho Chehab
12518ad72163SMauro Carvalho Chehab	# Split nested struct/union elements as newer ones
125284ce5b98SMauro Carvalho Chehab	while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
125384ce5b98SMauro Carvalho Chehab		my $newmember;
125484ce5b98SMauro Carvalho Chehab		my $maintype = $1;
125584ce5b98SMauro Carvalho Chehab		my $ids = $4;
12568ad72163SMauro Carvalho Chehab		my $content = $3;
125784ce5b98SMauro Carvalho Chehab		foreach my $id(split /,/, $ids) {
125884ce5b98SMauro Carvalho Chehab			$newmember .= "$maintype $id; ";
125984ce5b98SMauro Carvalho Chehab
12608ad72163SMauro Carvalho Chehab			$id =~ s/[:\[].*//;
126184ce5b98SMauro Carvalho Chehab			$id =~ s/^\s*\**(\S+)\s*/$1/;
12628ad72163SMauro Carvalho Chehab			foreach my $arg (split /;/, $content) {
12638ad72163SMauro Carvalho Chehab				next if ($arg =~ m/^\s*$/);
12647c0d7e87SMauro Carvalho Chehab				if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
12657c0d7e87SMauro Carvalho Chehab					# pointer-to-function
12667c0d7e87SMauro Carvalho Chehab					my $type = $1;
12677c0d7e87SMauro Carvalho Chehab					my $name = $2;
12687c0d7e87SMauro Carvalho Chehab					my $extra = $3;
12697c0d7e87SMauro Carvalho Chehab					next if (!$name);
12707c0d7e87SMauro Carvalho Chehab					if ($id =~ m/^\s*$/) {
12717c0d7e87SMauro Carvalho Chehab						# anonymous struct/union
12727c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$name$extra; ";
12737c0d7e87SMauro Carvalho Chehab					} else {
12747c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$id.$name$extra; ";
12757c0d7e87SMauro Carvalho Chehab					}
12767c0d7e87SMauro Carvalho Chehab				} else {
127784ce5b98SMauro Carvalho Chehab					my $type;
127884ce5b98SMauro Carvalho Chehab					my $names;
127984ce5b98SMauro Carvalho Chehab					$arg =~ s/^\s+//;
128084ce5b98SMauro Carvalho Chehab					$arg =~ s/\s+$//;
128184ce5b98SMauro Carvalho Chehab					# Handle bitmaps
128284ce5b98SMauro Carvalho Chehab					$arg =~ s/:\s*\d+\s*//g;
128384ce5b98SMauro Carvalho Chehab					# Handle arrays
1284d404d579SMauro Carvalho Chehab					$arg =~ s/\[.*\]//g;
128584ce5b98SMauro Carvalho Chehab					# The type may have multiple words,
128684ce5b98SMauro Carvalho Chehab					# and multiple IDs can be defined, like:
128784ce5b98SMauro Carvalho Chehab					#	const struct foo, *bar, foobar
128884ce5b98SMauro Carvalho Chehab					# So, we remove spaces when parsing the
128984ce5b98SMauro Carvalho Chehab					# names, in order to match just names
129084ce5b98SMauro Carvalho Chehab					# and commas for the names
129184ce5b98SMauro Carvalho Chehab					$arg =~ s/\s*,\s*/,/g;
129284ce5b98SMauro Carvalho Chehab					if ($arg =~ m/(.*)\s+([\S+,]+)/) {
129384ce5b98SMauro Carvalho Chehab						$type = $1;
129484ce5b98SMauro Carvalho Chehab						$names = $2;
129584ce5b98SMauro Carvalho Chehab					} else {
129684ce5b98SMauro Carvalho Chehab						$newmember .= "$arg; ";
129784ce5b98SMauro Carvalho Chehab						next;
129884ce5b98SMauro Carvalho Chehab					}
129984ce5b98SMauro Carvalho Chehab					foreach my $name (split /,/, $names) {
130084ce5b98SMauro Carvalho Chehab						$name =~ s/^\s*\**(\S+)\s*/$1/;
13018ad72163SMauro Carvalho Chehab						next if (($name =~ m/^\s*$/));
13028ad72163SMauro Carvalho Chehab						if ($id =~ m/^\s*$/) {
13038ad72163SMauro Carvalho Chehab							# anonymous struct/union
13048ad72163SMauro Carvalho Chehab							$newmember .= "$type $name; ";
13058ad72163SMauro Carvalho Chehab						} else {
13068ad72163SMauro Carvalho Chehab							$newmember .= "$type $id.$name; ";
13078ad72163SMauro Carvalho Chehab						}
13088ad72163SMauro Carvalho Chehab					}
13097c0d7e87SMauro Carvalho Chehab				}
131084ce5b98SMauro Carvalho Chehab			}
131184ce5b98SMauro Carvalho Chehab		}
1312673bb2dfSBen Hutchings		$members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/;
131384ce5b98SMauro Carvalho Chehab	}
13148ad72163SMauro Carvalho Chehab
13158ad72163SMauro Carvalho Chehab	# Ignore other nested elements, like enums
1316673bb2dfSBen Hutchings	$members =~ s/(\{[^\{\}]*\})//g;
13178ad72163SMauro Carvalho Chehab
1318151c468bSMauro Carvalho Chehab	create_parameterlist($members, ';', $file, $declaration_name);
13191081de2dSMauro Carvalho Chehab	check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
13201da177e4SLinus Torvalds
13218ad72163SMauro Carvalho Chehab	# Adjust declaration for better display
1322673bb2dfSBen Hutchings	$declaration =~ s/([\{;])/$1\n/g;
1323673bb2dfSBen Hutchings	$declaration =~ s/\}\s+;/};/g;
13248ad72163SMauro Carvalho Chehab	# Better handle inlined enums
1325673bb2dfSBen Hutchings	do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
13268ad72163SMauro Carvalho Chehab
13278ad72163SMauro Carvalho Chehab	my @def_args = split /\n/, $declaration;
13288ad72163SMauro Carvalho Chehab	my $level = 1;
13298ad72163SMauro Carvalho Chehab	$declaration = "";
13308ad72163SMauro Carvalho Chehab	foreach my $clause (@def_args) {
13318ad72163SMauro Carvalho Chehab		$clause =~ s/^\s+//;
13328ad72163SMauro Carvalho Chehab		$clause =~ s/\s+$//;
13338ad72163SMauro Carvalho Chehab		$clause =~ s/\s+/ /;
13348ad72163SMauro Carvalho Chehab		next if (!$clause);
1335673bb2dfSBen Hutchings		$level-- if ($clause =~ m/(\})/ && $level > 1);
13368ad72163SMauro Carvalho Chehab		if (!($clause =~ m/^\s*#/)) {
13378ad72163SMauro Carvalho Chehab			$declaration .= "\t" x $level;
13388ad72163SMauro Carvalho Chehab		}
13398ad72163SMauro Carvalho Chehab		$declaration .= "\t" . $clause . "\n";
1340673bb2dfSBen Hutchings		$level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
13418ad72163SMauro Carvalho Chehab	}
13421da177e4SLinus Torvalds	output_declaration($declaration_name,
13431da177e4SLinus Torvalds			   'struct',
13441da177e4SLinus Torvalds			   {'struct' => $declaration_name,
13451da177e4SLinus Torvalds			    'module' => $modulename,
13468ad72163SMauro Carvalho Chehab			    'definition' => $declaration,
13471da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
13481da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
13491da177e4SLinus Torvalds			    'parametertypes' => \%parametertypes,
13501da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
13511da177e4SLinus Torvalds			    'sections' => \%sections,
13521da177e4SLinus Torvalds			    'purpose' => $declaration_purpose,
13531da177e4SLinus Torvalds			    'type' => $decl_type
13541da177e4SLinus Torvalds			   });
13551da177e4SLinus Torvalds    }
13561da177e4SLinus Torvalds    else {
1357d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
13581da177e4SLinus Torvalds	++$errors;
13591da177e4SLinus Torvalds    }
13601da177e4SLinus Torvalds}
13611da177e4SLinus Torvalds
136285afe608SMauro Carvalho Chehab
136385afe608SMauro Carvalho Chehabsub show_warnings($$) {
136485afe608SMauro Carvalho Chehab	my $functype = shift;
136585afe608SMauro Carvalho Chehab	my $name = shift;
136685afe608SMauro Carvalho Chehab
1367eab795ddSMauro Carvalho Chehab	return 0 if (defined($nosymbol_table{$name}));
1368eab795ddSMauro Carvalho Chehab
136985afe608SMauro Carvalho Chehab	return 1 if ($output_selection == OUTPUT_ALL);
137085afe608SMauro Carvalho Chehab
137185afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_EXPORTED) {
137285afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
137385afe608SMauro Carvalho Chehab			return 1;
137485afe608SMauro Carvalho Chehab		} else {
137585afe608SMauro Carvalho Chehab			return 0;
137685afe608SMauro Carvalho Chehab		}
137785afe608SMauro Carvalho Chehab	}
137885afe608SMauro Carvalho Chehab        if ($output_selection == OUTPUT_INTERNAL) {
137985afe608SMauro Carvalho Chehab		if (!($functype eq "function" && defined($function_table{$name}))) {
138085afe608SMauro Carvalho Chehab			return 1;
138185afe608SMauro Carvalho Chehab		} else {
138285afe608SMauro Carvalho Chehab			return 0;
138385afe608SMauro Carvalho Chehab		}
138485afe608SMauro Carvalho Chehab	}
138585afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_INCLUDE) {
138685afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
138785afe608SMauro Carvalho Chehab			return 1;
138885afe608SMauro Carvalho Chehab		} else {
138985afe608SMauro Carvalho Chehab			return 0;
139085afe608SMauro Carvalho Chehab		}
139185afe608SMauro Carvalho Chehab	}
139285afe608SMauro Carvalho Chehab	die("Please add the new output type at show_warnings()");
139385afe608SMauro Carvalho Chehab}
139485afe608SMauro Carvalho Chehab
13951da177e4SLinus Torvaldssub dump_enum($$) {
13961da177e4SLinus Torvalds    my $x = shift;
13971da177e4SLinus Torvalds    my $file = shift;
1398d38c8cfbSMauro Carvalho Chehab    my $members;
1399d38c8cfbSMauro Carvalho Chehab
14001da177e4SLinus Torvalds
1401aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
14024468e21eSConchúr Navid    # strip #define macros inside enums
14034468e21eSConchúr Navid    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1404b6d676dbSRandy Dunlap
1405d38c8cfbSMauro Carvalho Chehab    if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1406d38c8cfbSMauro Carvalho Chehab	$declaration_name = $2;
1407d38c8cfbSMauro Carvalho Chehab	$members = $1;
1408d38c8cfbSMauro Carvalho Chehab    } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
14091da177e4SLinus Torvalds	$declaration_name = $1;
1410d38c8cfbSMauro Carvalho Chehab	$members = $2;
1411d38c8cfbSMauro Carvalho Chehab    }
1412d38c8cfbSMauro Carvalho Chehab
1413ae5b17e4SAndy Shevchenko    if ($members) {
141452042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
141552042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
141652042e2dSMauro Carvalho Chehab	    return;
141752042e2dSMauro Carvalho Chehab	}
141852042e2dSMauro Carvalho Chehab
14195cb5c31cSJohannes Berg	my %_members;
14205cb5c31cSJohannes Berg
1421463a0fdcSMarkus Heiser	$members =~ s/\s+$//;
14221da177e4SLinus Torvalds
14231da177e4SLinus Torvalds	foreach my $arg (split ',', $members) {
14241da177e4SLinus Torvalds	    $arg =~ s/^\s*(\w+).*/$1/;
14251da177e4SLinus Torvalds	    push @parameterlist, $arg;
14261da177e4SLinus Torvalds	    if (!$parameterdescs{$arg}) {
14271da177e4SLinus Torvalds		$parameterdescs{$arg} = $undescribed;
142885afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
14292defb272SMauro Carvalho Chehab			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
14302defb272SMauro Carvalho Chehab		}
14311da177e4SLinus Torvalds	    }
14325cb5c31cSJohannes Berg	    $_members{$arg} = 1;
14335cb5c31cSJohannes Berg	}
14341da177e4SLinus Torvalds
14355cb5c31cSJohannes Berg	while (my ($k, $v) = each %parameterdescs) {
14365cb5c31cSJohannes Berg	    if (!exists($_members{$k})) {
143785afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
14382defb272SMauro Carvalho Chehab		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
14392defb272SMauro Carvalho Chehab		}
14405cb5c31cSJohannes Berg	    }
14411da177e4SLinus Torvalds        }
14421da177e4SLinus Torvalds
14431da177e4SLinus Torvalds	output_declaration($declaration_name,
14441da177e4SLinus Torvalds			   'enum',
14451da177e4SLinus Torvalds			   {'enum' => $declaration_name,
14461da177e4SLinus Torvalds			    'module' => $modulename,
14471da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
14481da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
14491da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
14501da177e4SLinus Torvalds			    'sections' => \%sections,
14511da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
14521da177e4SLinus Torvalds			   });
1453d38c8cfbSMauro Carvalho Chehab    } else {
1454d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse enum!\n";
14551da177e4SLinus Torvalds	++$errors;
14561da177e4SLinus Torvalds    }
14571da177e4SLinus Torvalds}
14581da177e4SLinus Torvalds
14597d2c6b1eSMauro Carvalho Chehabmy $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x;
14607efc6c42SMauro Carvalho Chehabmy $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
14617efc6c42SMauro Carvalho Chehabmy $typedef_args = qr { \s*\((.*)\); }x;
14627efc6c42SMauro Carvalho Chehab
14637efc6c42SMauro Carvalho Chehabmy $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x;
14647efc6c42SMauro Carvalho Chehabmy $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;
14657efc6c42SMauro Carvalho Chehab
14661da177e4SLinus Torvaldssub dump_typedef($$) {
14671da177e4SLinus Torvalds    my $x = shift;
14681da177e4SLinus Torvalds    my $file = shift;
14691da177e4SLinus Torvalds
1470aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
147183766452SMauro Carvalho Chehab
14727efc6c42SMauro Carvalho Chehab    # Parse function typedef prototypes
14737efc6c42SMauro Carvalho Chehab    if ($x =~ $typedef1 || $x =~ $typedef2) {
147483766452SMauro Carvalho Chehab	$return_type = $1;
147583766452SMauro Carvalho Chehab	$declaration_name = $2;
147683766452SMauro Carvalho Chehab	my $args = $3;
14776b80975cSMauro Carvalho Chehab	$return_type =~ s/^\s+//;
147883766452SMauro Carvalho Chehab
147952042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
148052042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
148152042e2dSMauro Carvalho Chehab	    return;
148252042e2dSMauro Carvalho Chehab	}
148352042e2dSMauro Carvalho Chehab
1484151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
148583766452SMauro Carvalho Chehab
148683766452SMauro Carvalho Chehab	output_declaration($declaration_name,
148783766452SMauro Carvalho Chehab			   'function',
148883766452SMauro Carvalho Chehab			   {'function' => $declaration_name,
148982801d06SMauro Carvalho Chehab			    'typedef' => 1,
149083766452SMauro Carvalho Chehab			    'module' => $modulename,
149183766452SMauro Carvalho Chehab			    'functiontype' => $return_type,
149283766452SMauro Carvalho Chehab			    'parameterlist' => \@parameterlist,
149383766452SMauro Carvalho Chehab			    'parameterdescs' => \%parameterdescs,
149483766452SMauro Carvalho Chehab			    'parametertypes' => \%parametertypes,
149583766452SMauro Carvalho Chehab			    'sectionlist' => \@sectionlist,
149683766452SMauro Carvalho Chehab			    'sections' => \%sections,
149783766452SMauro Carvalho Chehab			    'purpose' => $declaration_purpose
149883766452SMauro Carvalho Chehab			   });
149983766452SMauro Carvalho Chehab	return;
150083766452SMauro Carvalho Chehab    }
150183766452SMauro Carvalho Chehab
15021da177e4SLinus Torvalds    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
15031da177e4SLinus Torvalds	$x =~ s/\(*.\)\s*;$/;/;
15041da177e4SLinus Torvalds	$x =~ s/\[*.\]\s*;$/;/;
15051da177e4SLinus Torvalds    }
15061da177e4SLinus Torvalds
15071da177e4SLinus Torvalds    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
15081da177e4SLinus Torvalds	$declaration_name = $1;
15091da177e4SLinus Torvalds
151052042e2dSMauro Carvalho Chehab	if ($identifier ne $declaration_name) {
151152042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
151252042e2dSMauro Carvalho Chehab	    return;
151352042e2dSMauro Carvalho Chehab	}
151452042e2dSMauro Carvalho Chehab
15151da177e4SLinus Torvalds	output_declaration($declaration_name,
15161da177e4SLinus Torvalds			   'typedef',
15171da177e4SLinus Torvalds			   {'typedef' => $declaration_name,
15181da177e4SLinus Torvalds			    'module' => $modulename,
15191da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
15201da177e4SLinus Torvalds			    'sections' => \%sections,
15211da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
15221da177e4SLinus Torvalds			   });
15231da177e4SLinus Torvalds    }
15241da177e4SLinus Torvalds    else {
1525d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
15261da177e4SLinus Torvalds	++$errors;
15271da177e4SLinus Torvalds    }
15281da177e4SLinus Torvalds}
15291da177e4SLinus Torvalds
1530a1d94aa5SRandy Dunlapsub save_struct_actual($) {
1531a1d94aa5SRandy Dunlap    my $actual = shift;
1532a1d94aa5SRandy Dunlap
1533a1d94aa5SRandy Dunlap    # strip all spaces from the actual param so that it looks like one string item
1534a1d94aa5SRandy Dunlap    $actual =~ s/\s*//g;
1535a1d94aa5SRandy Dunlap    $struct_actual = $struct_actual . $actual . " ";
1536a1d94aa5SRandy Dunlap}
1537a1d94aa5SRandy Dunlap
1538151c468bSMauro Carvalho Chehabsub create_parameterlist($$$$) {
15391da177e4SLinus Torvalds    my $args = shift;
15401da177e4SLinus Torvalds    my $splitter = shift;
15411da177e4SLinus Torvalds    my $file = shift;
1542151c468bSMauro Carvalho Chehab    my $declaration_name = shift;
15431da177e4SLinus Torvalds    my $type;
15441da177e4SLinus Torvalds    my $param;
15451da177e4SLinus Torvalds
1546a6d3fe77SMartin Waitz    # temporarily replace commas inside function pointer definition
15471da177e4SLinus Torvalds    while ($args =~ /(\([^\),]+),/) {
15481da177e4SLinus Torvalds	$args =~ s/(\([^\),]+),/$1#/g;
15491da177e4SLinus Torvalds    }
15501da177e4SLinus Torvalds
15511da177e4SLinus Torvalds    foreach my $arg (split($splitter, $args)) {
15521da177e4SLinus Torvalds	# strip comments
15531da177e4SLinus Torvalds	$arg =~ s/\/\*.*\*\///;
15541da177e4SLinus Torvalds	# strip leading/trailing spaces
15551da177e4SLinus Torvalds	$arg =~ s/^\s*//;
15561da177e4SLinus Torvalds	$arg =~ s/\s*$//;
15571da177e4SLinus Torvalds	$arg =~ s/\s+/ /;
15581da177e4SLinus Torvalds
15591da177e4SLinus Torvalds	if ($arg =~ /^#/) {
15601da177e4SLinus Torvalds	    # Treat preprocessor directive as a typeless variable just to fill
15611da177e4SLinus Torvalds	    # corresponding data structures "correctly". Catch it later in
15621da177e4SLinus Torvalds	    # output_* subs.
1563ed8348e2SMauro Carvalho Chehab	    push_parameter($arg, "", "", $file);
156400d62961SRichard Kennedy	} elsif ($arg =~ m/\(.+\)\s*\(/) {
15651da177e4SLinus Torvalds	    # pointer-to-function
15661da177e4SLinus Torvalds	    $arg =~ tr/#/,/;
1567336ced2dSAditya Srivastava	    $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
15681da177e4SLinus Torvalds	    $param = $1;
15691da177e4SLinus Torvalds	    $type = $arg;
157000d62961SRichard Kennedy	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1571a1d94aa5SRandy Dunlap	    save_struct_actual($param);
1572ed8348e2SMauro Carvalho Chehab	    push_parameter($param, $type, $arg, $file, $declaration_name);
1573aeec46b9SMartin Waitz	} elsif ($arg) {
15741da177e4SLinus Torvalds	    $arg =~ s/\s*:\s*/:/g;
15751da177e4SLinus Torvalds	    $arg =~ s/\s*\[/\[/g;
15761da177e4SLinus Torvalds
15771da177e4SLinus Torvalds	    my @args = split('\s*,\s*', $arg);
15781da177e4SLinus Torvalds	    if ($args[0] =~ m/\*/) {
15791da177e4SLinus Torvalds		$args[0] =~ s/(\*+)\s*/ $1/;
15801da177e4SLinus Torvalds	    }
1581884f2810SBorislav Petkov
1582884f2810SBorislav Petkov	    my @first_arg;
1583884f2810SBorislav Petkov	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1584884f2810SBorislav Petkov		    shift @args;
1585884f2810SBorislav Petkov		    push(@first_arg, split('\s+', $1));
1586884f2810SBorislav Petkov		    push(@first_arg, $2);
1587884f2810SBorislav Petkov	    } else {
1588884f2810SBorislav Petkov		    @first_arg = split('\s+', shift @args);
1589884f2810SBorislav Petkov	    }
1590884f2810SBorislav Petkov
15911da177e4SLinus Torvalds	    unshift(@args, pop @first_arg);
15921da177e4SLinus Torvalds	    $type = join " ", @first_arg;
15931da177e4SLinus Torvalds
15941da177e4SLinus Torvalds	    foreach $param (@args) {
15951da177e4SLinus Torvalds		if ($param =~ m/^(\*+)\s*(.*)/) {
1596a1d94aa5SRandy Dunlap		    save_struct_actual($2);
1597ed8348e2SMauro Carvalho Chehab
1598ed8348e2SMauro Carvalho Chehab		    push_parameter($2, "$type $1", $arg, $file, $declaration_name);
15991da177e4SLinus Torvalds		}
16001da177e4SLinus Torvalds		elsif ($param =~ m/(.*?):(\d+)/) {
16017b97887eSRandy Dunlap		    if ($type ne "") { # skip unnamed bit-fields
1602a1d94aa5SRandy Dunlap			save_struct_actual($1);
1603ed8348e2SMauro Carvalho Chehab			push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
16041da177e4SLinus Torvalds		    }
16057b97887eSRandy Dunlap		}
16061da177e4SLinus Torvalds		else {
1607a1d94aa5SRandy Dunlap		    save_struct_actual($param);
1608ed8348e2SMauro Carvalho Chehab		    push_parameter($param, $type, $arg, $file, $declaration_name);
16091da177e4SLinus Torvalds		}
16101da177e4SLinus Torvalds	    }
16111da177e4SLinus Torvalds	}
16121da177e4SLinus Torvalds    }
16131da177e4SLinus Torvalds}
16141da177e4SLinus Torvalds
1615ed8348e2SMauro Carvalho Chehabsub push_parameter($$$$$) {
16161da177e4SLinus Torvalds	my $param = shift;
16171da177e4SLinus Torvalds	my $type = shift;
1618ed8348e2SMauro Carvalho Chehab	my $org_arg = shift;
16191da177e4SLinus Torvalds	my $file = shift;
1620151c468bSMauro Carvalho Chehab	my $declaration_name = shift;
16211da177e4SLinus Torvalds
16225f8c7c98SRandy Dunlap	if (($anon_struct_union == 1) && ($type eq "") &&
16235f8c7c98SRandy Dunlap	    ($param eq "}")) {
16245f8c7c98SRandy Dunlap		return;		# ignore the ending }; from anon. struct/union
16255f8c7c98SRandy Dunlap	}
16265f8c7c98SRandy Dunlap
16275f8c7c98SRandy Dunlap	$anon_struct_union = 0;
1628f9b5c530SMauro Carvalho Chehab	$param =~ s/[\[\)].*//;
16291da177e4SLinus Torvalds
1630a6d3fe77SMartin Waitz	if ($type eq "" && $param =~ /\.\.\.$/)
16311da177e4SLinus Torvalds	{
1632c950a173SSilvio Fricke	    if (!$param =~ /\w\.\.\.$/) {
1633c950a173SSilvio Fricke	      # handles unnamed variable parameters
1634ef00028bSJonathan Corbet	      $param = "...";
1635c950a173SSilvio Fricke	    }
163643756e34SJonathan Neuschäfer	    elsif ($param =~ /\w\.\.\.$/) {
163743756e34SJonathan Neuschäfer	      # for named variable parameters of the form `x...`, remove the dots
163843756e34SJonathan Neuschäfer	      $param =~ s/\.\.\.$//;
163943756e34SJonathan Neuschäfer	    }
1640ced69090SRandy Dunlap	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1641a6d3fe77SMartin Waitz		$parameterdescs{$param} = "variable arguments";
16421da177e4SLinus Torvalds	    }
1643ced69090SRandy Dunlap	}
16441da177e4SLinus Torvalds	elsif ($type eq "" && ($param eq "" or $param eq "void"))
16451da177e4SLinus Torvalds	{
16461da177e4SLinus Torvalds	    $param="void";
16471da177e4SLinus Torvalds	    $parameterdescs{void} = "no arguments";
16481da177e4SLinus Torvalds	}
1649134fe01bSRandy Dunlap	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1650134fe01bSRandy Dunlap	# handle unnamed (anonymous) union or struct:
1651134fe01bSRandy Dunlap	{
1652134fe01bSRandy Dunlap		$type = $param;
1653134fe01bSRandy Dunlap		$param = "{unnamed_" . $param . "}";
1654134fe01bSRandy Dunlap		$parameterdescs{$param} = "anonymous\n";
16555f8c7c98SRandy Dunlap		$anon_struct_union = 1;
1656134fe01bSRandy Dunlap	}
1657134fe01bSRandy Dunlap
1658a6d3fe77SMartin Waitz	# warn if parameter has no description
1659134fe01bSRandy Dunlap	# (but ignore ones starting with # as these are not parameters
1660134fe01bSRandy Dunlap	# but inline preprocessor statements);
1661151c468bSMauro Carvalho Chehab	# Note: It will also ignore void params and unnamed structs/unions
1662f9b5c530SMauro Carvalho Chehab	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1663f9b5c530SMauro Carvalho Chehab		$parameterdescs{$param} = $undescribed;
16641da177e4SLinus Torvalds
1665be5cd20cSJonathan Corbet	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1666151c468bSMauro Carvalho Chehab			print STDERR
1667151c468bSMauro Carvalho Chehab			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
16681da177e4SLinus Torvalds			++$warnings;
16691da177e4SLinus Torvalds		}
16702defb272SMauro Carvalho Chehab	}
16711da177e4SLinus Torvalds
167225985edcSLucas De Marchi	# strip spaces from $param so that it is one continuous string
1673e34e7dbbSRandy Dunlap	# on @parameterlist;
1674e34e7dbbSRandy Dunlap	# this fixes a problem where check_sections() cannot find
1675e34e7dbbSRandy Dunlap	# a parameter like "addr[6 + 2]" because it actually appears
1676e34e7dbbSRandy Dunlap	# as "addr[6", "+", "2]" on the parameter list;
1677e34e7dbbSRandy Dunlap	# but it's better to maintain the param string unchanged for output,
1678e34e7dbbSRandy Dunlap	# so just weaken the string compare in check_sections() to ignore
1679e34e7dbbSRandy Dunlap	# "[blah" in a parameter string;
1680e34e7dbbSRandy Dunlap	###$param =~ s/\s*//g;
16811da177e4SLinus Torvalds	push @parameterlist, $param;
1682ed8348e2SMauro Carvalho Chehab	$org_arg =~ s/\s\s+/ /g;
1683ed8348e2SMauro Carvalho Chehab	$parametertypes{$param} = $org_arg;
16841da177e4SLinus Torvalds}
16851da177e4SLinus Torvalds
16861081de2dSMauro Carvalho Chehabsub check_sections($$$$$) {
16871081de2dSMauro Carvalho Chehab	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
1688a1d94aa5SRandy Dunlap	my @sects = split ' ', $sectcheck;
1689a1d94aa5SRandy Dunlap	my @prms = split ' ', $prmscheck;
1690a1d94aa5SRandy Dunlap	my $err;
1691a1d94aa5SRandy Dunlap	my ($px, $sx);
1692a1d94aa5SRandy Dunlap	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
1693a1d94aa5SRandy Dunlap
1694a1d94aa5SRandy Dunlap	foreach $sx (0 .. $#sects) {
1695a1d94aa5SRandy Dunlap		$err = 1;
1696a1d94aa5SRandy Dunlap		foreach $px (0 .. $#prms) {
1697a1d94aa5SRandy Dunlap			$prm_clean = $prms[$px];
1698a1d94aa5SRandy Dunlap			$prm_clean =~ s/\[.*\]//;
16991f3a6688SJohannes Berg			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1700e34e7dbbSRandy Dunlap			# ignore array size in a parameter string;
1701e34e7dbbSRandy Dunlap			# however, the original param string may contain
1702e34e7dbbSRandy Dunlap			# spaces, e.g.:  addr[6 + 2]
1703e34e7dbbSRandy Dunlap			# and this appears in @prms as "addr[6" since the
1704e34e7dbbSRandy Dunlap			# parameter list is split at spaces;
1705e34e7dbbSRandy Dunlap			# hence just ignore "[..." for the sections check;
1706e34e7dbbSRandy Dunlap			$prm_clean =~ s/\[.*//;
1707e34e7dbbSRandy Dunlap
1708a1d94aa5SRandy Dunlap			##$prm_clean =~ s/^\**//;
1709a1d94aa5SRandy Dunlap			if ($prm_clean eq $sects[$sx]) {
1710a1d94aa5SRandy Dunlap				$err = 0;
1711a1d94aa5SRandy Dunlap				last;
1712a1d94aa5SRandy Dunlap			}
1713a1d94aa5SRandy Dunlap		}
1714a1d94aa5SRandy Dunlap		if ($err) {
1715a1d94aa5SRandy Dunlap			if ($decl_type eq "function") {
1716d40e1e65SBart Van Assche				print STDERR "${file}:$.: warning: " .
1717a1d94aa5SRandy Dunlap					"Excess function parameter " .
1718a1d94aa5SRandy Dunlap					"'$sects[$sx]' " .
1719a1d94aa5SRandy Dunlap					"description in '$decl_name'\n";
1720a1d94aa5SRandy Dunlap				++$warnings;
1721a1d94aa5SRandy Dunlap			}
1722a1d94aa5SRandy Dunlap		}
1723a1d94aa5SRandy Dunlap	}
1724a1d94aa5SRandy Dunlap}
1725a1d94aa5SRandy Dunlap
17261da177e4SLinus Torvalds##
17274092bac7SYacine Belkadi# Checks the section describing the return value of a function.
17284092bac7SYacine Belkadisub check_return_section {
17294092bac7SYacine Belkadi        my $file = shift;
17304092bac7SYacine Belkadi        my $declaration_name = shift;
17314092bac7SYacine Belkadi        my $return_type = shift;
17324092bac7SYacine Belkadi
17334092bac7SYacine Belkadi        # Ignore an empty return type (It's a macro)
17344092bac7SYacine Belkadi        # Ignore functions with a "void" return type. (But don't ignore "void *")
17354092bac7SYacine Belkadi        if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
17364092bac7SYacine Belkadi                return;
17374092bac7SYacine Belkadi        }
17384092bac7SYacine Belkadi
17394092bac7SYacine Belkadi        if (!defined($sections{$section_return}) ||
17404092bac7SYacine Belkadi            $sections{$section_return} eq "") {
1741d40e1e65SBart Van Assche                print STDERR "${file}:$.: warning: " .
17424092bac7SYacine Belkadi                        "No description found for return value of " .
17434092bac7SYacine Belkadi                        "'$declaration_name'\n";
17444092bac7SYacine Belkadi                ++$warnings;
17454092bac7SYacine Belkadi        }
17464092bac7SYacine Belkadi}
17474092bac7SYacine Belkadi
17484092bac7SYacine Belkadi##
17491da177e4SLinus Torvalds# takes a function prototype and the name of the current file being
17501da177e4SLinus Torvalds# processed and spits out all the details stored in the global
17511da177e4SLinus Torvalds# arrays/hashes.
17521da177e4SLinus Torvaldssub dump_function($$) {
17531da177e4SLinus Torvalds    my $prototype = shift;
17541da177e4SLinus Torvalds    my $file = shift;
1755cbb4d3e6SHoria Geanta    my $noret = 0;
17561da177e4SLinus Torvalds
17575ef09c96SMauro Carvalho Chehab    print_lineno($new_start_line);
17585eb6b4b3SMauro Carvalho Chehab
17591da177e4SLinus Torvalds    $prototype =~ s/^static +//;
17601da177e4SLinus Torvalds    $prototype =~ s/^extern +//;
17614dc3b16bSPavel Pisa    $prototype =~ s/^asmlinkage +//;
17621da177e4SLinus Torvalds    $prototype =~ s/^inline +//;
17631da177e4SLinus Torvalds    $prototype =~ s/^__inline__ +//;
176432e79401SRandy Dunlap    $prototype =~ s/^__inline +//;
176532e79401SRandy Dunlap    $prototype =~ s/^__always_inline +//;
176632e79401SRandy Dunlap    $prototype =~ s/^noinline +//;
176774fc5c65SRandy Dunlap    $prototype =~ s/__init +//;
176820072205SRandy Dunlap    $prototype =~ s/__init_or_module +//;
1769*084aa001SAditya Srivastava    $prototype =~ s/__flatten +//;
1770270a0096SRandy Dunlap    $prototype =~ s/__meminit +//;
177170c95b00SRandy Dunlap    $prototype =~ s/__must_check +//;
17720df7c0e3SRandy Dunlap    $prototype =~ s/__weak +//;
17730891f959SMatthew Wilcox    $prototype =~ s/__sched +//;
177495e760cbSRandy Dunlap    $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1775cbb4d3e6SHoria Geanta    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1776*084aa001SAditya Srivastava    $prototype =~ s/__attribute_const__ +//;
1777b1aaa546SPaolo Bonzini    $prototype =~ s/__attribute__\s*\(\(
1778b1aaa546SPaolo Bonzini            (?:
1779b1aaa546SPaolo Bonzini                 [\w\s]++          # attribute name
1780b1aaa546SPaolo Bonzini                 (?:\([^)]*+\))?   # attribute arguments
1781b1aaa546SPaolo Bonzini                 \s*+,?            # optional comma at the end
1782b1aaa546SPaolo Bonzini            )+
1783b1aaa546SPaolo Bonzini          \)\)\s+//x;
17841da177e4SLinus Torvalds
17851da177e4SLinus Torvalds    # Yes, this truly is vile.  We are looking for:
17861da177e4SLinus Torvalds    # 1. Return type (may be nothing if we're looking at a macro)
17871da177e4SLinus Torvalds    # 2. Function name
17881da177e4SLinus Torvalds    # 3. Function parameters.
17891da177e4SLinus Torvalds    #
17901da177e4SLinus Torvalds    # All the while we have to watch out for function pointer parameters
17911da177e4SLinus Torvalds    # (which IIRC is what the two sections are for), C types (these
17921da177e4SLinus Torvalds    # regexps don't even start to express all the possibilities), and
17931da177e4SLinus Torvalds    # so on.
17941da177e4SLinus Torvalds    #
17951da177e4SLinus Torvalds    # If you mess with these regexps, it's a good idea to check that
17961da177e4SLinus Torvalds    # the following functions' documentation still comes out right:
17971da177e4SLinus Torvalds    # - parport_register_device (function pointer parameters)
17981da177e4SLinus Torvalds    # - atomic_set (macro)
17999598f91fSMartin Waitz    # - pci_match_device, __copy_to_user (long return type)
18001da177e4SLinus Torvalds
1801cbb4d3e6SHoria Geanta    if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1802cbb4d3e6SHoria Geanta        # This is an object-like macro, it has no return type and no parameter
1803cbb4d3e6SHoria Geanta        # list.
1804cbb4d3e6SHoria Geanta        # Function-like macros are not allowed to have spaces between
1805cbb4d3e6SHoria Geanta        # declaration_name and opening parenthesis (notice the \s+).
1806cbb4d3e6SHoria Geanta        $return_type = $1;
1807cbb4d3e6SHoria Geanta        $declaration_name = $2;
1808cbb4d3e6SHoria Geanta        $noret = 1;
1809cbb4d3e6SHoria Geanta    } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18101da177e4SLinus Torvalds	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18115a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18121da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
181394b3e03cSRandy Dunlap	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18141da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18155a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
18161da177e4SLinus Torvalds	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18171da177e4SLinus Torvalds	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18185a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18191da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18205a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18211da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18225a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18239598f91fSMartin Waitz	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18245a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
18255a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
18261da177e4SLinus Torvalds	$return_type = $1;
18271da177e4SLinus Torvalds	$declaration_name = $2;
18281da177e4SLinus Torvalds	my $args = $3;
18291da177e4SLinus Torvalds
1830151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
18311da177e4SLinus Torvalds    } else {
1832d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
18331da177e4SLinus Torvalds	return;
18341da177e4SLinus Torvalds    }
18351da177e4SLinus Torvalds
183652042e2dSMauro Carvalho Chehab    if ($identifier ne $declaration_name) {
183752042e2dSMauro Carvalho Chehab	print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
183852042e2dSMauro Carvalho Chehab	return;
183952042e2dSMauro Carvalho Chehab    }
184052042e2dSMauro Carvalho Chehab
1841a1d94aa5SRandy Dunlap    my $prms = join " ", @parameterlist;
18421081de2dSMauro Carvalho Chehab    check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1843a1d94aa5SRandy Dunlap
18444092bac7SYacine Belkadi    # This check emits a lot of warnings at the moment, because many
18454092bac7SYacine Belkadi    # functions don't have a 'Return' doc section. So until the number
18464092bac7SYacine Belkadi    # of warnings goes sufficiently down, the check is only performed in
18474092bac7SYacine Belkadi    # verbose mode.
18484092bac7SYacine Belkadi    # TODO: always perform the check.
1849cbb4d3e6SHoria Geanta    if ($verbose && !$noret) {
18504092bac7SYacine Belkadi	    check_return_section($file, $declaration_name, $return_type);
18514092bac7SYacine Belkadi    }
18524092bac7SYacine Belkadi
185347bcacfdSMauro Carvalho Chehab    # The function parser can be called with a typedef parameter.
185447bcacfdSMauro Carvalho Chehab    # Handle it.
185547bcacfdSMauro Carvalho Chehab    if ($return_type =~ /typedef/) {
185647bcacfdSMauro Carvalho Chehab	output_declaration($declaration_name,
185747bcacfdSMauro Carvalho Chehab			   'function',
185847bcacfdSMauro Carvalho Chehab			   {'function' => $declaration_name,
185947bcacfdSMauro Carvalho Chehab			    'typedef' => 1,
186047bcacfdSMauro Carvalho Chehab			    'module' => $modulename,
186147bcacfdSMauro Carvalho Chehab			    'functiontype' => $return_type,
186247bcacfdSMauro Carvalho Chehab			    'parameterlist' => \@parameterlist,
186347bcacfdSMauro Carvalho Chehab			    'parameterdescs' => \%parameterdescs,
186447bcacfdSMauro Carvalho Chehab			    'parametertypes' => \%parametertypes,
186547bcacfdSMauro Carvalho Chehab			    'sectionlist' => \@sectionlist,
186647bcacfdSMauro Carvalho Chehab			    'sections' => \%sections,
186747bcacfdSMauro Carvalho Chehab			    'purpose' => $declaration_purpose
186847bcacfdSMauro Carvalho Chehab			   });
186947bcacfdSMauro Carvalho Chehab    } else {
18701da177e4SLinus Torvalds	output_declaration($declaration_name,
18711da177e4SLinus Torvalds			   'function',
18721da177e4SLinus Torvalds			   {'function' => $declaration_name,
18731da177e4SLinus Torvalds			    'module' => $modulename,
18741da177e4SLinus Torvalds			    'functiontype' => $return_type,
18751da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
18761da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
18771da177e4SLinus Torvalds			    'parametertypes' => \%parametertypes,
18781da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
18791da177e4SLinus Torvalds			    'sections' => \%sections,
18801da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
18811da177e4SLinus Torvalds			   });
18821da177e4SLinus Torvalds    }
188347bcacfdSMauro Carvalho Chehab}
18841da177e4SLinus Torvalds
18851da177e4SLinus Torvaldssub reset_state {
18861da177e4SLinus Torvalds    $function = "";
18871da177e4SLinus Torvalds    %parameterdescs = ();
18881da177e4SLinus Torvalds    %parametertypes = ();
18891da177e4SLinus Torvalds    @parameterlist = ();
18901da177e4SLinus Torvalds    %sections = ();
18911da177e4SLinus Torvalds    @sectionlist = ();
1892a1d94aa5SRandy Dunlap    $sectcheck = "";
1893a1d94aa5SRandy Dunlap    $struct_actual = "";
18941da177e4SLinus Torvalds    $prototype = "";
18951da177e4SLinus Torvalds
189648af606aSJani Nikula    $state = STATE_NORMAL;
189748af606aSJani Nikula    $inline_doc_state = STATE_INLINE_NA;
18981da177e4SLinus Torvalds}
18991da177e4SLinus Torvalds
190056afb0f8SJason Baronsub tracepoint_munge($) {
190156afb0f8SJason Baron	my $file = shift;
190256afb0f8SJason Baron	my $tracepointname = 0;
190356afb0f8SJason Baron	my $tracepointargs = 0;
190456afb0f8SJason Baron
190556afb0f8SJason Baron	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
190656afb0f8SJason Baron		$tracepointname = $1;
190756afb0f8SJason Baron	}
19083a9089fdSJason Baron	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
19093a9089fdSJason Baron		$tracepointname = $1;
19103a9089fdSJason Baron	}
19113a9089fdSJason Baron	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
19123a9089fdSJason Baron		$tracepointname = $2;
19133a9089fdSJason Baron	}
19143a9089fdSJason Baron	$tracepointname =~ s/^\s+//; #strip leading whitespace
191556afb0f8SJason Baron	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
191656afb0f8SJason Baron		$tracepointargs = $1;
191756afb0f8SJason Baron	}
191856afb0f8SJason Baron	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1919d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
192056afb0f8SJason Baron			     "$prototype\n";
192156afb0f8SJason Baron	} else {
192256afb0f8SJason Baron		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
192352042e2dSMauro Carvalho Chehab		$identifier = "trace_$identifier";
192456afb0f8SJason Baron	}
192556afb0f8SJason Baron}
192656afb0f8SJason Baron
1927b4870bc5SRandy Dunlapsub syscall_munge() {
1928b4870bc5SRandy Dunlap	my $void = 0;
1929b4870bc5SRandy Dunlap
19307c9aa015SMauro Carvalho Chehab	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1931b4870bc5SRandy Dunlap##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1932b4870bc5SRandy Dunlap	if ($prototype =~ m/SYSCALL_DEFINE0/) {
1933b4870bc5SRandy Dunlap		$void = 1;
1934b4870bc5SRandy Dunlap##		$prototype = "long sys_$1(void)";
1935b4870bc5SRandy Dunlap	}
1936b4870bc5SRandy Dunlap
1937b4870bc5SRandy Dunlap	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1938b4870bc5SRandy Dunlap	if ($prototype =~ m/long (sys_.*?),/) {
1939b4870bc5SRandy Dunlap		$prototype =~ s/,/\(/;
1940b4870bc5SRandy Dunlap	} elsif ($void) {
1941b4870bc5SRandy Dunlap		$prototype =~ s/\)/\(void\)/;
1942b4870bc5SRandy Dunlap	}
1943b4870bc5SRandy Dunlap
1944b4870bc5SRandy Dunlap	# now delete all of the odd-number commas in $prototype
1945b4870bc5SRandy Dunlap	# so that arg types & arg names don't have a comma between them
1946b4870bc5SRandy Dunlap	my $count = 0;
1947b4870bc5SRandy Dunlap	my $len = length($prototype);
1948b4870bc5SRandy Dunlap	if ($void) {
1949b4870bc5SRandy Dunlap		$len = 0;	# skip the for-loop
1950b4870bc5SRandy Dunlap	}
1951b4870bc5SRandy Dunlap	for (my $ix = 0; $ix < $len; $ix++) {
1952b4870bc5SRandy Dunlap		if (substr($prototype, $ix, 1) eq ',') {
1953b4870bc5SRandy Dunlap			$count++;
1954b4870bc5SRandy Dunlap			if ($count % 2 == 1) {
1955b4870bc5SRandy Dunlap				substr($prototype, $ix, 1) = ' ';
1956b4870bc5SRandy Dunlap			}
1957b4870bc5SRandy Dunlap		}
1958b4870bc5SRandy Dunlap	}
1959b4870bc5SRandy Dunlap}
1960b4870bc5SRandy Dunlap
1961b7afa92bSDaniel Vettersub process_proto_function($$) {
19621da177e4SLinus Torvalds    my $x = shift;
19631da177e4SLinus Torvalds    my $file = shift;
19641da177e4SLinus Torvalds
196551f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
196651f5a0c8SRandy Dunlap
1967890c78c2SRandy Dunlap    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
19681da177e4SLinus Torvalds	# do nothing
19691da177e4SLinus Torvalds    }
19701da177e4SLinus Torvalds    elsif ($x =~ /([^\{]*)/) {
19711da177e4SLinus Torvalds	$prototype .= $1;
19721da177e4SLinus Torvalds    }
1973b4870bc5SRandy Dunlap
1974890c78c2SRandy Dunlap    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
19751da177e4SLinus Torvalds	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
19761da177e4SLinus Torvalds	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
19771da177e4SLinus Torvalds	$prototype =~ s@^\s+@@gos; # strip leading spaces
19787ae281b0SMauro Carvalho Chehab
19797ae281b0SMauro Carvalho Chehab	 # Handle prototypes for function pointers like:
19807ae281b0SMauro Carvalho Chehab	 # int (*pcs_config)(struct foo)
19817ae281b0SMauro Carvalho Chehab	$prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos;
19827ae281b0SMauro Carvalho Chehab
1983b4870bc5SRandy Dunlap	if ($prototype =~ /SYSCALL_DEFINE/) {
1984b4870bc5SRandy Dunlap		syscall_munge();
1985b4870bc5SRandy Dunlap	}
19863a9089fdSJason Baron	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
19873a9089fdSJason Baron	    $prototype =~ /DEFINE_SINGLE_EVENT/)
19883a9089fdSJason Baron	{
198956afb0f8SJason Baron		tracepoint_munge($file);
199056afb0f8SJason Baron	}
19911da177e4SLinus Torvalds	dump_function($prototype, $file);
19921da177e4SLinus Torvalds	reset_state();
19931da177e4SLinus Torvalds    }
19941da177e4SLinus Torvalds}
19951da177e4SLinus Torvalds
1996b7afa92bSDaniel Vettersub process_proto_type($$) {
19971da177e4SLinus Torvalds    my $x = shift;
19981da177e4SLinus Torvalds    my $file = shift;
19991da177e4SLinus Torvalds
20001da177e4SLinus Torvalds    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
20011da177e4SLinus Torvalds    $x =~ s@^\s+@@gos; # strip leading spaces
20021da177e4SLinus Torvalds    $x =~ s@\s+$@@gos; # strip trailing spaces
200351f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
200451f5a0c8SRandy Dunlap
20051da177e4SLinus Torvalds    if ($x =~ /^#/) {
20061da177e4SLinus Torvalds	# To distinguish preprocessor directive from regular declaration later.
20071da177e4SLinus Torvalds	$x .= ";";
20081da177e4SLinus Torvalds    }
20091da177e4SLinus Torvalds
20101da177e4SLinus Torvalds    while (1) {
2011673bb2dfSBen Hutchings	if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
2012463a0fdcSMarkus Heiser            if( length $prototype ) {
2013463a0fdcSMarkus Heiser                $prototype .= " "
2014463a0fdcSMarkus Heiser            }
20151da177e4SLinus Torvalds	    $prototype .= $1 . $2;
20161da177e4SLinus Torvalds	    ($2 eq '{') && $brcount++;
20171da177e4SLinus Torvalds	    ($2 eq '}') && $brcount--;
20181da177e4SLinus Torvalds	    if (($2 eq ';') && ($brcount == 0)) {
20191da177e4SLinus Torvalds		dump_declaration($prototype, $file);
20201da177e4SLinus Torvalds		reset_state();
20211da177e4SLinus Torvalds		last;
20221da177e4SLinus Torvalds	    }
20231da177e4SLinus Torvalds	    $x = $3;
20241da177e4SLinus Torvalds	} else {
20251da177e4SLinus Torvalds	    $prototype .= $x;
20261da177e4SLinus Torvalds	    last;
20271da177e4SLinus Torvalds	}
20281da177e4SLinus Torvalds    }
20291da177e4SLinus Torvalds}
20301da177e4SLinus Torvalds
20316b5b55f6SRandy Dunlap
20321ad560e4SJani Nikulasub map_filename($) {
20331ad560e4SJani Nikula    my $file;
20341ad560e4SJani Nikula    my ($orig_file) = @_;
20351ad560e4SJani Nikula
20361ad560e4SJani Nikula    if (defined($ENV{'SRCTREE'})) {
20371ad560e4SJani Nikula	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
20381ad560e4SJani Nikula    } else {
20391ad560e4SJani Nikula	$file = $orig_file;
20401ad560e4SJani Nikula    }
20411ad560e4SJani Nikula
20421ad560e4SJani Nikula    if (defined($source_map{$file})) {
20431ad560e4SJani Nikula	$file = $source_map{$file};
20441ad560e4SJani Nikula    }
20451ad560e4SJani Nikula
20461ad560e4SJani Nikula    return $file;
20471ad560e4SJani Nikula}
20481ad560e4SJani Nikula
204988c2b57dSJani Nikulasub process_export_file($) {
205088c2b57dSJani Nikula    my ($orig_file) = @_;
205188c2b57dSJani Nikula    my $file = map_filename($orig_file);
205288c2b57dSJani Nikula
205388c2b57dSJani Nikula    if (!open(IN,"<$file")) {
205488c2b57dSJani Nikula	print STDERR "Error: Cannot open file $file\n";
205588c2b57dSJani Nikula	++$errors;
205688c2b57dSJani Nikula	return;
205788c2b57dSJani Nikula    }
205888c2b57dSJani Nikula
205988c2b57dSJani Nikula    while (<IN>) {
206088c2b57dSJani Nikula	if (/$export_symbol/) {
2061eab795ddSMauro Carvalho Chehab	    next if (defined($nosymbol_table{$2}));
206288c2b57dSJani Nikula	    $function_table{$2} = 1;
206388c2b57dSJani Nikula	}
206488c2b57dSJani Nikula    }
206588c2b57dSJani Nikula
206688c2b57dSJani Nikula    close(IN);
206788c2b57dSJani Nikula}
206888c2b57dSJani Nikula
206907048d13SJonathan Corbet#
207007048d13SJonathan Corbet# Parsers for the various processing states.
207107048d13SJonathan Corbet#
207207048d13SJonathan Corbet# STATE_NORMAL: looking for the /** to begin everything.
207307048d13SJonathan Corbet#
207407048d13SJonathan Corbetsub process_normal() {
20751da177e4SLinus Torvalds    if (/$doc_start/o) {
207648af606aSJani Nikula	$state = STATE_NAME;	# next line is always the function name
2077850622dfSRandy Dunlap	$in_doc_sect = 0;
20780b0f5f29SDaniel Vetter	$declaration_start_line = $. + 1;
20791da177e4SLinus Torvalds    }
208007048d13SJonathan Corbet}
208107048d13SJonathan Corbet
20823cac2bc4SJonathan Corbet#
20833cac2bc4SJonathan Corbet# STATE_NAME: Looking for the "name - description" line
20843cac2bc4SJonathan Corbet#
20853cac2bc4SJonathan Corbetsub process_name($$) {
20863cac2bc4SJonathan Corbet    my $file = shift;
20871da177e4SLinus Torvalds    my $descr;
20881da177e4SLinus Torvalds
20891da177e4SLinus Torvalds    if (/$doc_block/o) {
209048af606aSJani Nikula	$state = STATE_DOCBLOCK;
20911da177e4SLinus Torvalds	$contents = "";
20925ef09c96SMauro Carvalho Chehab	$new_start_line = $.;
20930b0f5f29SDaniel Vetter
20941da177e4SLinus Torvalds	if ( $1 eq "" ) {
20951da177e4SLinus Torvalds	    $section = $section_intro;
20961da177e4SLinus Torvalds	} else {
20971da177e4SLinus Torvalds	    $section = $1;
20981da177e4SLinus Torvalds	}
209952042e2dSMauro Carvalho Chehab    } elsif (/$doc_decl/o) {
21001da177e4SLinus Torvalds	$identifier = $1;
210152042e2dSMauro Carvalho Chehab	if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
21021da177e4SLinus Torvalds	    $identifier = $1;
21031da177e4SLinus Torvalds	}
210452042e2dSMauro Carvalho Chehab	if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
210552042e2dSMauro Carvalho Chehab	    $decl_type = $1;
210652042e2dSMauro Carvalho Chehab	    $identifier = $2;
210752042e2dSMauro Carvalho Chehab	} else {
210852042e2dSMauro Carvalho Chehab	    $decl_type = 'function';
210952042e2dSMauro Carvalho Chehab	    $identifier =~ s/^define\s+//;
211052042e2dSMauro Carvalho Chehab	}
211152042e2dSMauro Carvalho Chehab	$identifier =~ s/\s+$//;
21121da177e4SLinus Torvalds
211317b78717SJonathan Corbet	$state = STATE_BODY;
21140b0f5f29SDaniel Vetter	# if there's no @param blocks need to set up default section
21150b0f5f29SDaniel Vetter	# here
21162f4ad40aSJani Nikula	$contents = "";
21172f4ad40aSJani Nikula	$section = $section_default;
21180b0f5f29SDaniel Vetter	$new_start_line = $. + 1;
211952042e2dSMauro Carvalho Chehab	if (/[-:](.*)/) {
212051f5a0c8SRandy Dunlap	    # strip leading/trailing/multiple spaces
2121a21217daSRandy Dunlap	    $descr= $1;
2122a21217daSRandy Dunlap	    $descr =~ s/^\s*//;
2123a21217daSRandy Dunlap	    $descr =~ s/\s*$//;
212412ae6779SDaniel Santos	    $descr =~ s/\s+/ /g;
21250bba924cSJonathan Corbet	    $declaration_purpose = $descr;
212617b78717SJonathan Corbet	    $state = STATE_BODY_MAYBE;
21271da177e4SLinus Torvalds	} else {
21281da177e4SLinus Torvalds	    $declaration_purpose = "";
21291da177e4SLinus Torvalds	}
213077cc23b8SRandy Dunlap
213177cc23b8SRandy Dunlap	if (($declaration_purpose eq "") && $verbose) {
2132d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
213377cc23b8SRandy Dunlap	    print STDERR $_;
213477cc23b8SRandy Dunlap	    ++$warnings;
213577cc23b8SRandy Dunlap	}
213677cc23b8SRandy Dunlap
213752042e2dSMauro Carvalho Chehab	if ($identifier eq "") {
213852042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
213952042e2dSMauro Carvalho Chehab	    print STDERR $_;
214052042e2dSMauro Carvalho Chehab	    ++$warnings;
214152042e2dSMauro Carvalho Chehab	    $state = STATE_NORMAL;
21421da177e4SLinus Torvalds	}
21431da177e4SLinus Torvalds
21441da177e4SLinus Torvalds	if ($verbose) {
214552042e2dSMauro Carvalho Chehab	    print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
21461da177e4SLinus Torvalds	}
21471da177e4SLinus Torvalds    } else {
2148d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
21491da177e4SLinus Torvalds	    " - I thought it was a doc line\n";
21501da177e4SLinus Torvalds	++$warnings;
215148af606aSJani Nikula	$state = STATE_NORMAL;
21521da177e4SLinus Torvalds    }
21533cac2bc4SJonathan Corbet}
21543cac2bc4SJonathan Corbet
21553cac2bc4SJonathan Corbet
2156d742f24dSJonathan Corbet#
2157d742f24dSJonathan Corbet# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2158d742f24dSJonathan Corbet#
2159d742f24dSJonathan Corbetsub process_body($$) {
2160d742f24dSJonathan Corbet    my $file = shift;
21613cac2bc4SJonathan Corbet
216243756e34SJonathan Neuschäfer    # Until all named variable macro parameters are
216343756e34SJonathan Neuschäfer    # documented using the bare name (`x`) rather than with
216443756e34SJonathan Neuschäfer    # dots (`x...`), strip the dots:
216543756e34SJonathan Neuschäfer    if ($section =~ /\w\.\.\.$/) {
216643756e34SJonathan Neuschäfer	$section =~ s/\.\.\.$//;
216743756e34SJonathan Neuschäfer
216843756e34SJonathan Neuschäfer	if ($verbose) {
216943756e34SJonathan Neuschäfer	    print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
217043756e34SJonathan Neuschäfer	    ++$warnings;
217143756e34SJonathan Neuschäfer	}
217243756e34SJonathan Neuschäfer    }
217343756e34SJonathan Neuschäfer
21740d55d48bSMauro Carvalho Chehab    if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
21750d55d48bSMauro Carvalho Chehab	dump_section($file, $section, $contents);
21760d55d48bSMauro Carvalho Chehab	$section = $section_default;
21775ef09c96SMauro Carvalho Chehab	$new_start_line = $.;
21780d55d48bSMauro Carvalho Chehab	$contents = "";
21790d55d48bSMauro Carvalho Chehab    }
21800d55d48bSMauro Carvalho Chehab
2181f624adefSJani Nikula    if (/$doc_sect/i) { # case insensitive for supported section names
21821da177e4SLinus Torvalds	$newsection = $1;
21831da177e4SLinus Torvalds	$newcontents = $2;
21841da177e4SLinus Torvalds
2185f624adefSJani Nikula	# map the supported section names to the canonical names
2186f624adefSJani Nikula	if ($newsection =~ m/^description$/i) {
2187f624adefSJani Nikula	    $newsection = $section_default;
2188f624adefSJani Nikula	} elsif ($newsection =~ m/^context$/i) {
2189f624adefSJani Nikula	    $newsection = $section_context;
2190f624adefSJani Nikula	} elsif ($newsection =~ m/^returns?$/i) {
2191f624adefSJani Nikula	    $newsection = $section_return;
2192f624adefSJani Nikula	} elsif ($newsection =~ m/^\@return$/) {
2193f624adefSJani Nikula	    # special: @return is a section, not a param description
2194f624adefSJani Nikula	    $newsection = $section_return;
2195f624adefSJani Nikula	}
2196f624adefSJani Nikula
2197792aa2f2SRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
2198850622dfSRandy Dunlap	    if (!$in_doc_sect && $verbose) {
2199d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: contents before sections\n";
2200850622dfSRandy Dunlap		++$warnings;
2201850622dfSRandy Dunlap	    }
22020bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
22031da177e4SLinus Torvalds	    $section = $section_default;
22041da177e4SLinus Torvalds	}
22051da177e4SLinus Torvalds
2206850622dfSRandy Dunlap	$in_doc_sect = 1;
220717b78717SJonathan Corbet	$state = STATE_BODY;
22081da177e4SLinus Torvalds	$contents = $newcontents;
22090b0f5f29SDaniel Vetter	$new_start_line = $.;
22107c9aa015SMauro Carvalho Chehab	while (substr($contents, 0, 1) eq " ") {
221105189497SRandy Dunlap	    $contents = substr($contents, 1);
221205189497SRandy Dunlap	}
22130a726301SJani Nikula	if ($contents ne "") {
22141da177e4SLinus Torvalds	    $contents .= "\n";
22151da177e4SLinus Torvalds	}
22161da177e4SLinus Torvalds	$section = $newsection;
2217b7886de4SJani Nikula	$leading_space = undef;
22181da177e4SLinus Torvalds    } elsif (/$doc_end/) {
22194c98ecafSRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
22200bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
22211da177e4SLinus Torvalds	    $section = $section_default;
22221da177e4SLinus Torvalds	    $contents = "";
22231da177e4SLinus Torvalds	}
222446b958ebSRandy Dunlap	# look for doc_com + <text> + doc_end:
222546b958ebSRandy Dunlap	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2226d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: suspicious ending line: $_";
222746b958ebSRandy Dunlap	    ++$warnings;
222846b958ebSRandy Dunlap	}
22291da177e4SLinus Torvalds
22301da177e4SLinus Torvalds	$prototype = "";
223148af606aSJani Nikula	$state = STATE_PROTO;
22321da177e4SLinus Torvalds	$brcount = 0;
22335ef09c96SMauro Carvalho Chehab        $new_start_line = $. + 1;
22341da177e4SLinus Torvalds    } elsif (/$doc_content/) {
22356423133bSJohannes Weiner	if ($1 eq "") {
22360d55d48bSMauro Carvalho Chehab	    if ($section eq $section_context) {
22370bba924cSJonathan Corbet		dump_section($file, $section, $contents);
22381da177e4SLinus Torvalds		$section = $section_default;
22391da177e4SLinus Torvalds		$contents = "";
22400b0f5f29SDaniel Vetter		$new_start_line = $.;
22410d55d48bSMauro Carvalho Chehab		$state = STATE_BODY;
22421da177e4SLinus Torvalds	    } else {
22430d55d48bSMauro Carvalho Chehab		if ($section ne $section_default) {
22440d55d48bSMauro Carvalho Chehab		    $state = STATE_BODY_WITH_BLANK_LINE;
22450d55d48bSMauro Carvalho Chehab		} else {
22460d55d48bSMauro Carvalho Chehab		    $state = STATE_BODY;
22470d55d48bSMauro Carvalho Chehab		}
22486423133bSJohannes Weiner		$contents .= "\n";
22496423133bSJohannes Weiner	    }
225017b78717SJonathan Corbet	} elsif ($state == STATE_BODY_MAYBE) {
22516423133bSJohannes Weiner	    # Continued declaration purpose
22526423133bSJohannes Weiner	    chomp($declaration_purpose);
22530bba924cSJonathan Corbet	    $declaration_purpose .= " " . $1;
225412ae6779SDaniel Santos	    $declaration_purpose =~ s/\s+/ /g;
22556423133bSJohannes Weiner	} else {
2256b7886de4SJani Nikula	    my $cont = $1;
2257b7886de4SJani Nikula	    if ($section =~ m/^@/ || $section eq $section_context) {
2258b7886de4SJani Nikula		if (!defined $leading_space) {
2259b7886de4SJani Nikula		    if ($cont =~ m/^(\s+)/) {
2260b7886de4SJani Nikula			$leading_space = $1;
2261b7886de4SJani Nikula		    } else {
2262b7886de4SJani Nikula			$leading_space = "";
2263b7886de4SJani Nikula		    }
2264b7886de4SJani Nikula		}
2265b7886de4SJani Nikula		$cont =~ s/^$leading_space//;
2266b7886de4SJani Nikula	    }
2267b7886de4SJani Nikula	    $contents .= $cont . "\n";
22681da177e4SLinus Torvalds	}
22691da177e4SLinus Torvalds    } else {
22701da177e4SLinus Torvalds	# i dont know - bad line?  ignore.
2271d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: bad line: $_";
22721da177e4SLinus Torvalds	++$warnings;
22731da177e4SLinus Torvalds    }
2274d742f24dSJonathan Corbet}
2275d742f24dSJonathan Corbet
2276d742f24dSJonathan Corbet
2277cc794812SJonathan Corbet#
2278cc794812SJonathan Corbet# STATE_PROTO: reading a function/whatever prototype.
2279cc794812SJonathan Corbet#
2280cc794812SJonathan Corbetsub process_proto($$) {
2281cc794812SJonathan Corbet    my $file = shift;
2282cc794812SJonathan Corbet
2283cc794812SJonathan Corbet    if (/$doc_inline_oneline/) {
2284cc794812SJonathan Corbet	$section = $1;
2285cc794812SJonathan Corbet	$contents = $2;
2286cc794812SJonathan Corbet	if ($contents ne "") {
2287cc794812SJonathan Corbet	    $contents .= "\n";
2288cc794812SJonathan Corbet	    dump_section($file, $section, $contents);
2289cc794812SJonathan Corbet	    $section = $section_default;
2290cc794812SJonathan Corbet	    $contents = "";
2291cc794812SJonathan Corbet	}
2292cc794812SJonathan Corbet    } elsif (/$doc_inline_start/) {
2293cc794812SJonathan Corbet	$state = STATE_INLINE;
2294cc794812SJonathan Corbet	$inline_doc_state = STATE_INLINE_NAME;
2295cc794812SJonathan Corbet    } elsif ($decl_type eq 'function') {
2296cc794812SJonathan Corbet	process_proto_function($_, $file);
2297cc794812SJonathan Corbet    } else {
2298cc794812SJonathan Corbet	process_proto_type($_, $file);
2299cc794812SJonathan Corbet    }
2300cc794812SJonathan Corbet}
2301cc794812SJonathan Corbet
2302c17add56SJonathan Corbet#
2303c17add56SJonathan Corbet# STATE_DOCBLOCK: within a DOC: block.
2304c17add56SJonathan Corbet#
2305c17add56SJonathan Corbetsub process_docblock($$) {
2306c17add56SJonathan Corbet    my $file = shift;
2307cc794812SJonathan Corbet
2308c17add56SJonathan Corbet    if (/$doc_end/) {
2309c17add56SJonathan Corbet	dump_doc_section($file, $section, $contents);
2310c17add56SJonathan Corbet	$section = $section_default;
2311c17add56SJonathan Corbet	$contents = "";
2312c17add56SJonathan Corbet	$function = "";
2313c17add56SJonathan Corbet	%parameterdescs = ();
2314c17add56SJonathan Corbet	%parametertypes = ();
2315c17add56SJonathan Corbet	@parameterlist = ();
2316c17add56SJonathan Corbet	%sections = ();
2317c17add56SJonathan Corbet	@sectionlist = ();
2318c17add56SJonathan Corbet	$prototype = "";
2319c17add56SJonathan Corbet	$state = STATE_NORMAL;
2320c17add56SJonathan Corbet    } elsif (/$doc_content/) {
2321c17add56SJonathan Corbet	if ( $1 eq "" )	{
2322c17add56SJonathan Corbet	    $contents .= $blankline;
2323c17add56SJonathan Corbet	} else {
2324c17add56SJonathan Corbet	    $contents .= $1 . "\n";
2325c17add56SJonathan Corbet	}
2326c17add56SJonathan Corbet    }
2327d742f24dSJonathan Corbet}
2328d742f24dSJonathan Corbet
2329c17add56SJonathan Corbet#
2330c17add56SJonathan Corbet# STATE_INLINE: docbook comments within a prototype.
2331c17add56SJonathan Corbet#
2332c17add56SJonathan Corbetsub process_inline($$) {
2333c17add56SJonathan Corbet    my $file = shift;
2334d742f24dSJonathan Corbet
2335a4c6ebedSDanilo Cesar Lemes de Paula    # First line (state 1) needs to be a @parameter
233648af606aSJani Nikula    if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2337a4c6ebedSDanilo Cesar Lemes de Paula	$section = $1;
2338a4c6ebedSDanilo Cesar Lemes de Paula	$contents = $2;
23390b0f5f29SDaniel Vetter	$new_start_line = $.;
2340a4c6ebedSDanilo Cesar Lemes de Paula	if ($contents ne "") {
23417c9aa015SMauro Carvalho Chehab	    while (substr($contents, 0, 1) eq " ") {
2342a4c6ebedSDanilo Cesar Lemes de Paula		$contents = substr($contents, 1);
2343a4c6ebedSDanilo Cesar Lemes de Paula	    }
2344a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= "\n";
2345a4c6ebedSDanilo Cesar Lemes de Paula	}
234648af606aSJani Nikula	$inline_doc_state = STATE_INLINE_TEXT;
2347a4c6ebedSDanilo Cesar Lemes de Paula	# Documentation block end */
234848af606aSJani Nikula    } elsif (/$doc_inline_end/) {
2349a4c6ebedSDanilo Cesar Lemes de Paula	if (($contents ne "") && ($contents ne "\n")) {
23500bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
2351a4c6ebedSDanilo Cesar Lemes de Paula	    $section = $section_default;
2352a4c6ebedSDanilo Cesar Lemes de Paula	    $contents = "";
2353a4c6ebedSDanilo Cesar Lemes de Paula	}
235448af606aSJani Nikula	$state = STATE_PROTO;
235548af606aSJani Nikula	$inline_doc_state = STATE_INLINE_NA;
2356a4c6ebedSDanilo Cesar Lemes de Paula	# Regular text
2357a4c6ebedSDanilo Cesar Lemes de Paula    } elsif (/$doc_content/) {
235848af606aSJani Nikula	if ($inline_doc_state == STATE_INLINE_TEXT) {
2359a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= $1 . "\n";
23606450c895SJani Nikula	    # nuke leading blank lines
23616450c895SJani Nikula	    if ($contents =~ /^\s*$/) {
23626450c895SJani Nikula		$contents = "";
23636450c895SJani Nikula	    }
236448af606aSJani Nikula	} elsif ($inline_doc_state == STATE_INLINE_NAME) {
236548af606aSJani Nikula	    $inline_doc_state = STATE_INLINE_ERROR;
2366e7ca311eSDaniel Vetter	    print STDERR "${file}:$.: warning: ";
2367a4c6ebedSDanilo Cesar Lemes de Paula	    print STDERR "Incorrect use of kernel-doc format: $_";
2368a4c6ebedSDanilo Cesar Lemes de Paula	    ++$warnings;
2369a4c6ebedSDanilo Cesar Lemes de Paula	}
2370a4c6ebedSDanilo Cesar Lemes de Paula    }
23710c9aa209SJani Nikula}
2372c17add56SJonathan Corbet
2373c17add56SJonathan Corbet
2374c17add56SJonathan Corbetsub process_file($) {
2375c17add56SJonathan Corbet    my $file;
2376c17add56SJonathan Corbet    my $initial_section_counter = $section_counter;
2377c17add56SJonathan Corbet    my ($orig_file) = @_;
2378c17add56SJonathan Corbet
2379c17add56SJonathan Corbet    $file = map_filename($orig_file);
2380c17add56SJonathan Corbet
2381dbe8ba00SMauro Carvalho Chehab    if (!open(IN_FILE,"<$file")) {
2382c17add56SJonathan Corbet	print STDERR "Error: Cannot open file $file\n";
2383c17add56SJonathan Corbet	++$errors;
2384c17add56SJonathan Corbet	return;
23851da177e4SLinus Torvalds    }
2386c17add56SJonathan Corbet
2387c17add56SJonathan Corbet    $. = 1;
2388c17add56SJonathan Corbet
2389c17add56SJonathan Corbet    $section_counter = 0;
2390dbe8ba00SMauro Carvalho Chehab    while (<IN_FILE>) {
2391c17add56SJonathan Corbet	while (s/\\\s*$//) {
2392dbe8ba00SMauro Carvalho Chehab	    $_ .= <IN_FILE>;
2393c17add56SJonathan Corbet	}
2394c17add56SJonathan Corbet	# Replace tabs by spaces
2395c17add56SJonathan Corbet        while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2396c17add56SJonathan Corbet	# Hand this line to the appropriate state handler
2397c17add56SJonathan Corbet	if ($state == STATE_NORMAL) {
2398c17add56SJonathan Corbet	    process_normal();
2399c17add56SJonathan Corbet	} elsif ($state == STATE_NAME) {
2400c17add56SJonathan Corbet	    process_name($file, $_);
24010d55d48bSMauro Carvalho Chehab	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE ||
24020d55d48bSMauro Carvalho Chehab		 $state == STATE_BODY_WITH_BLANK_LINE) {
2403c17add56SJonathan Corbet	    process_body($file, $_);
2404c17add56SJonathan Corbet	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
2405c17add56SJonathan Corbet	    process_inline($file, $_);
2406cc794812SJonathan Corbet	} elsif ($state == STATE_PROTO) {
2407cc794812SJonathan Corbet	    process_proto($file, $_);
240848af606aSJani Nikula	} elsif ($state == STATE_DOCBLOCK) {
2409c17add56SJonathan Corbet	    process_docblock($file, $_);
24101da177e4SLinus Torvalds	}
24111da177e4SLinus Torvalds    }
2412c17add56SJonathan Corbet
2413c17add56SJonathan Corbet    # Make sure we got something interesting.
2414b0d60bfbSJonathan Corbet    if ($initial_section_counter == $section_counter && $
2415b0d60bfbSJonathan Corbet	output_mode ne "none") {
2416b0d60bfbSJonathan Corbet	if ($output_selection == OUTPUT_INCLUDE) {
2417b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: '$_' not found\n"
2418b0d60bfbSJonathan Corbet		for keys %function_table;
24193a025e1dSMatthew Wilcox	}
2420b0d60bfbSJonathan Corbet	else {
2421b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: no structured comments found\n";
2422e946c43aSJohannes Berg	}
24231da177e4SLinus Torvalds    }
2424dbe8ba00SMauro Carvalho Chehab    close IN_FILE;
24251da177e4SLinus Torvalds}
24268484baaaSRandy Dunlap
24278484baaaSRandy Dunlap
242893351d41SMauro Carvalho Chehabif ($output_mode eq "rst") {
242993351d41SMauro Carvalho Chehab	get_sphinx_version() if (!$sphinx_major);
243093351d41SMauro Carvalho Chehab}
243193351d41SMauro Carvalho Chehab
24328484baaaSRandy Dunlap$kernelversion = get_kernel_version();
24338484baaaSRandy Dunlap
24348484baaaSRandy Dunlap# generate a sequence of code that will splice in highlighting information
24358484baaaSRandy Dunlap# using the s// operator.
24361ef06233SMauro Carvalho Chehabfor (my $k = 0; $k < @highlights; $k++) {
24374d732701SDanilo Cesar Lemes de Paula    my $pattern = $highlights[$k][0];
24384d732701SDanilo Cesar Lemes de Paula    my $result = $highlights[$k][1];
24394d732701SDanilo Cesar Lemes de Paula#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
24404d732701SDanilo Cesar Lemes de Paula    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
24418484baaaSRandy Dunlap}
24428484baaaSRandy Dunlap
24438484baaaSRandy Dunlap# Read the file that maps relative names to absolute names for
24448484baaaSRandy Dunlap# separate source and object directories and for shadow trees.
24458484baaaSRandy Dunlapif (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
24468484baaaSRandy Dunlap	my ($relname, $absname);
24478484baaaSRandy Dunlap	while(<SOURCE_MAP>) {
24488484baaaSRandy Dunlap		chop();
24498484baaaSRandy Dunlap		($relname, $absname) = (split())[0..1];
24508484baaaSRandy Dunlap		$relname =~ s:^/+::;
24518484baaaSRandy Dunlap		$source_map{$relname} = $absname;
24528484baaaSRandy Dunlap	}
24538484baaaSRandy Dunlap	close(SOURCE_MAP);
24548484baaaSRandy Dunlap}
24558484baaaSRandy Dunlap
245688c2b57dSJani Nikulaif ($output_selection == OUTPUT_EXPORTED ||
245788c2b57dSJani Nikula    $output_selection == OUTPUT_INTERNAL) {
2458c9b2cfb3SJani Nikula
2459c9b2cfb3SJani Nikula    push(@export_file_list, @ARGV);
2460c9b2cfb3SJani Nikula
246188c2b57dSJani Nikula    foreach (@export_file_list) {
246288c2b57dSJani Nikula	chomp;
246388c2b57dSJani Nikula	process_export_file($_);
246488c2b57dSJani Nikula    }
246588c2b57dSJani Nikula}
246688c2b57dSJani Nikula
24678484baaaSRandy Dunlapforeach (@ARGV) {
24688484baaaSRandy Dunlap    chomp;
24698484baaaSRandy Dunlap    process_file($_);
24708484baaaSRandy Dunlap}
24718484baaaSRandy Dunlapif ($verbose && $errors) {
24728484baaaSRandy Dunlap  print STDERR "$errors errors\n";
24738484baaaSRandy Dunlap}
24748484baaaSRandy Dunlapif ($verbose && $warnings) {
24758484baaaSRandy Dunlap  print STDERR "$warnings warnings\n";
24768484baaaSRandy Dunlap}
24778484baaaSRandy Dunlap
24782c12c810SPierre-Louis Bossartif ($Werror && $warnings) {
24792c12c810SPierre-Louis Bossart    print STDERR "$warnings warnings as Errors\n";
24802c12c810SPierre-Louis Bossart    exit($warnings);
24812c12c810SPierre-Louis Bossart} else {
24822c12c810SPierre-Louis Bossart    exit($output_mode eq "none" ? 0 : $errors)
24832c12c810SPierre-Louis Bossart}
2484