xref: /openbmc/linux/scripts/kernel-doc (revision b0d60bfb)
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
59fadc0b31SJani NikulaOutput selection (mutually exclusive):
6086ae2e38SJani Nikula  -export		Only output documentation for symbols that have been
6186ae2e38SJani Nikula			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
62c9b2cfb3SJani Nikula                        in any input FILE or -export-file FILE.
6386ae2e38SJani Nikula  -internal		Only output documentation for symbols that have NOT been
6486ae2e38SJani Nikula			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
65c9b2cfb3SJani Nikula                        in any input FILE or -export-file FILE.
66fadc0b31SJani Nikula  -function NAME	Only output documentation for the given function(s)
67fadc0b31SJani Nikula			or DOC: section title(s). All other functions and DOC:
68fadc0b31SJani Nikula			sections are ignored. May be specified multiple times.
69fadc0b31SJani Nikula  -nofunction NAME	Do NOT output documentation for the given function(s);
70fadc0b31SJani Nikula			only output documentation for the other functions and
71fadc0b31SJani Nikula			DOC: sections. May be specified multiple times.
72fadc0b31SJani Nikula
73fadc0b31SJani NikulaOutput selection modifiers:
74fadc0b31SJani Nikula  -no-doc-sections	Do not output DOC: sections.
750b0f5f29SDaniel Vetter  -enable-lineno        Enable output of #define LINENO lines. Only works with
760b0f5f29SDaniel Vetter                        reStructuredText format.
7788c2b57dSJani Nikula  -export-file FILE     Specify an additional FILE in which to look for
7888c2b57dSJani Nikula                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
7988c2b57dSJani Nikula                        -export or -internal. May be specified multiple times.
80fadc0b31SJani Nikula
81fadc0b31SJani NikulaOther parameters:
82fadc0b31SJani Nikula  -v			Verbose output, more warnings and other information.
83fadc0b31SJani Nikula  -h			Print this help.
84fadc0b31SJani Nikula
85fadc0b31SJani NikulaEOF
86fadc0b31SJani Nikula    print $message;
87fadc0b31SJani Nikula    exit 1;
88fadc0b31SJani Nikula}
891da177e4SLinus Torvalds
901da177e4SLinus Torvalds#
911da177e4SLinus Torvalds# format of comments.
921da177e4SLinus Torvalds# In the following table, (...)? signifies optional structure.
931da177e4SLinus Torvalds#                         (...)* signifies 0 or more structure elements
941da177e4SLinus Torvalds# /**
951da177e4SLinus Torvalds#  * function_name(:)? (- short description)?
961da177e4SLinus Torvalds# (* @parameterx: (description of parameter x)?)*
971da177e4SLinus Torvalds# (* a blank line)?
981da177e4SLinus Torvalds#  * (Description:)? (Description of function)?
991da177e4SLinus Torvalds#  * (section header: (section description)? )*
1001da177e4SLinus Torvalds#  (*)?*/
1011da177e4SLinus Torvalds#
1021da177e4SLinus Torvalds# So .. the trivial example would be:
1031da177e4SLinus Torvalds#
1041da177e4SLinus Torvalds# /**
1051da177e4SLinus Torvalds#  * my_function
106b9d97328SRandy Dunlap#  */
1071da177e4SLinus Torvalds#
108891dcd2fSRandy Dunlap# If the Description: header tag is omitted, then there must be a blank line
1091da177e4SLinus Torvalds# after the last parameter specification.
1101da177e4SLinus Torvalds# e.g.
1111da177e4SLinus Torvalds# /**
1121da177e4SLinus Torvalds#  * my_function - does my stuff
1131da177e4SLinus Torvalds#  * @my_arg: its mine damnit
1141da177e4SLinus Torvalds#  *
1151da177e4SLinus Torvalds#  * Does my stuff explained.
1161da177e4SLinus Torvalds#  */
1171da177e4SLinus Torvalds#
1181da177e4SLinus Torvalds#  or, could also use:
1191da177e4SLinus Torvalds# /**
1201da177e4SLinus Torvalds#  * my_function - does my stuff
1211da177e4SLinus Torvalds#  * @my_arg: its mine damnit
1221da177e4SLinus Torvalds#  * Description: Does my stuff explained.
1231da177e4SLinus Torvalds#  */
1241da177e4SLinus Torvalds# etc.
1251da177e4SLinus Torvalds#
126b9d97328SRandy Dunlap# Besides functions you can also write documentation for structs, unions,
1271da177e4SLinus Torvalds# enums and typedefs. Instead of the function name you must write the name
1281da177e4SLinus Torvalds# of the declaration;  the struct/union/enum/typedef must always precede
1291da177e4SLinus Torvalds# the name. Nesting of declarations is not supported.
1301da177e4SLinus Torvalds# Use the argument mechanism to document members or constants.
1311da177e4SLinus Torvalds# e.g.
1321da177e4SLinus Torvalds# /**
1331da177e4SLinus Torvalds#  * struct my_struct - short description
1341da177e4SLinus Torvalds#  * @a: first member
1351da177e4SLinus Torvalds#  * @b: second member
1361da177e4SLinus Torvalds#  *
1371da177e4SLinus Torvalds#  * Longer description
1381da177e4SLinus Torvalds#  */
1391da177e4SLinus Torvalds# struct my_struct {
1401da177e4SLinus Torvalds#     int a;
1411da177e4SLinus Torvalds#     int b;
142aeec46b9SMartin Waitz# /* private: */
143aeec46b9SMartin Waitz#     int c;
1441da177e4SLinus Torvalds# };
1451da177e4SLinus Torvalds#
1461da177e4SLinus Torvalds# All descriptions can be multiline, except the short function description.
1471da177e4SLinus Torvalds#
148a4c6ebedSDanilo Cesar Lemes de Paula# For really longs structs, you can also describe arguments inside the
149a4c6ebedSDanilo Cesar Lemes de Paula# body of the struct.
150a4c6ebedSDanilo Cesar Lemes de Paula# eg.
151a4c6ebedSDanilo Cesar Lemes de Paula# /**
152a4c6ebedSDanilo Cesar Lemes de Paula#  * struct my_struct - short description
153a4c6ebedSDanilo Cesar Lemes de Paula#  * @a: first member
154a4c6ebedSDanilo Cesar Lemes de Paula#  * @b: second member
155a4c6ebedSDanilo Cesar Lemes de Paula#  *
156a4c6ebedSDanilo Cesar Lemes de Paula#  * Longer description
157a4c6ebedSDanilo Cesar Lemes de Paula#  */
158a4c6ebedSDanilo Cesar Lemes de Paula# struct my_struct {
159a4c6ebedSDanilo Cesar Lemes de Paula#     int a;
160a4c6ebedSDanilo Cesar Lemes de Paula#     int b;
161a4c6ebedSDanilo Cesar Lemes de Paula#     /**
162a4c6ebedSDanilo Cesar Lemes de Paula#      * @c: This is longer description of C
163a4c6ebedSDanilo Cesar Lemes de Paula#      *
164a4c6ebedSDanilo Cesar Lemes de Paula#      * You can use paragraphs to describe arguments
165a4c6ebedSDanilo Cesar Lemes de Paula#      * using this method.
166a4c6ebedSDanilo Cesar Lemes de Paula#      */
167a4c6ebedSDanilo Cesar Lemes de Paula#     int c;
168a4c6ebedSDanilo Cesar Lemes de Paula# };
169a4c6ebedSDanilo Cesar Lemes de Paula#
170a4c6ebedSDanilo Cesar Lemes de Paula# This should be use only for struct/enum members.
171a4c6ebedSDanilo Cesar Lemes de Paula#
1721da177e4SLinus Torvalds# You can also add additional sections. When documenting kernel functions you
1731da177e4SLinus Torvalds# should document the "Context:" of the function, e.g. whether the functions
1741da177e4SLinus Torvalds# can be called form interrupts. Unlike other sections you can end it with an
1751da177e4SLinus Torvalds# empty line.
1764092bac7SYacine Belkadi# A non-void function should have a "Return:" section describing the return
1774092bac7SYacine Belkadi# value(s).
1781da177e4SLinus Torvalds# Example-sections should contain the string EXAMPLE so that they are marked
1791da177e4SLinus Torvalds# appropriately in DocBook.
1801da177e4SLinus Torvalds#
1811da177e4SLinus Torvalds# Example:
1821da177e4SLinus Torvalds# /**
1831da177e4SLinus Torvalds#  * user_function - function that can only be called in user context
1841da177e4SLinus Torvalds#  * @a: some argument
1851da177e4SLinus Torvalds#  * Context: !in_interrupt()
1861da177e4SLinus Torvalds#  *
1871da177e4SLinus Torvalds#  * Some description
1881da177e4SLinus Torvalds#  * Example:
1891da177e4SLinus Torvalds#  *    user_function(22);
1901da177e4SLinus Torvalds#  */
1911da177e4SLinus Torvalds# ...
1921da177e4SLinus Torvalds#
1931da177e4SLinus Torvalds#
1941da177e4SLinus Torvalds# All descriptive text is further processed, scanning for the following special
1951da177e4SLinus Torvalds# patterns, which are highlighted appropriately.
1961da177e4SLinus Torvalds#
1971da177e4SLinus Torvalds# 'funcname()' - function
1981da177e4SLinus Torvalds# '$ENVVAR' - environmental variable
1991da177e4SLinus Torvalds# '&struct_name' - name of a structure (up to two words including 'struct')
2005267dd35SPaolo Bonzini# '&struct_name.member' - name of a structure member
2011da177e4SLinus Torvalds# '@parameter' - name of a parameter
2021da177e4SLinus Torvalds# '%CONST' - name of a constant.
203b97f193aSMauro Carvalho Chehab# '``LITERAL``' - literal string without any spaces on it.
2041da177e4SLinus Torvalds
2058484baaaSRandy Dunlap## init lots of data
2068484baaaSRandy Dunlap
2071da177e4SLinus Torvaldsmy $errors = 0;
2081da177e4SLinus Torvaldsmy $warnings = 0;
2095f8c7c98SRandy Dunlapmy $anon_struct_union = 0;
2101da177e4SLinus Torvalds
2111da177e4SLinus Torvalds# match expressions used to find embedded type information
212b97f193aSMauro Carvalho Chehabmy $type_constant = '\b``([^\`]+)``\b';
213b97f193aSMauro Carvalho Chehabmy $type_constant2 = '\%([-_\w]+)';
2141da177e4SLinus Torvaldsmy $type_func = '(\w+)\(\)';
215bfd228c7SMike Rapoportmy $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
2165219f18aSJonathan Corbetmy $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
2171da177e4SLinus Torvaldsmy $type_env = '(\$\w+)';
218df31175bSPaolo Bonzinimy $type_enum = '\&(enum\s*([_\w]+))';
219df31175bSPaolo Bonzinimy $type_struct = '\&(struct\s*([_\w]+))';
220df31175bSPaolo Bonzinimy $type_typedef = '\&(typedef\s*([_\w]+))';
221df31175bSPaolo Bonzinimy $type_union = '\&(union\s*([_\w]+))';
2225267dd35SPaolo Bonzinimy $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
223df31175bSPaolo Bonzinimy $type_fallback = '\&([_\w]+)';
224f3341dcfSJani Nikulamy $type_member_func = $type_member . '\(\)';
2251da177e4SLinus Torvalds
2261da177e4SLinus Torvalds# Output conversion substitutions.
2271da177e4SLinus Torvalds#  One for each output format
2281da177e4SLinus Torvalds
2291da177e4SLinus Torvalds# these are pretty rough
2304d732701SDanilo Cesar Lemes de Paulamy @highlights_man = (
2314d732701SDanilo Cesar Lemes de Paula                      [$type_constant, "\$1"],
232b97f193aSMauro Carvalho Chehab                      [$type_constant2, "\$1"],
2334d732701SDanilo Cesar Lemes de Paula                      [$type_func, "\\\\fB\$1\\\\fP"],
234df31175bSPaolo Bonzini                      [$type_enum, "\\\\fI\$1\\\\fP"],
2354d732701SDanilo Cesar Lemes de Paula                      [$type_struct, "\\\\fI\$1\\\\fP"],
236df31175bSPaolo Bonzini                      [$type_typedef, "\\\\fI\$1\\\\fP"],
237df31175bSPaolo Bonzini                      [$type_union, "\\\\fI\$1\\\\fP"],
2385267dd35SPaolo Bonzini                      [$type_param, "\\\\fI\$1\\\\fP"],
239df31175bSPaolo Bonzini                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
240df31175bSPaolo Bonzini                      [$type_fallback, "\\\\fI\$1\\\\fP"]
2414d732701SDanilo Cesar Lemes de Paula		     );
2421da177e4SLinus Torvaldsmy $blankline_man = "";
2431da177e4SLinus Torvalds
244c0d1b6eeSJonathan Corbet# rst-mode
245c0d1b6eeSJonathan Corbetmy @highlights_rst = (
246c0d1b6eeSJonathan Corbet                       [$type_constant, "``\$1``"],
247b97f193aSMauro Carvalho Chehab                       [$type_constant2, "``\$1``"],
248f3341dcfSJani Nikula                       # Note: need to escape () to avoid func matching later
2495267dd35SPaolo Bonzini                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
2505267dd35SPaolo Bonzini                       [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
2515219f18aSJonathan Corbet		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
252a19bce64SJani Nikula                       [$type_func, "\\:c\\:func\\:`\$1()`"],
253df31175bSPaolo Bonzini                       [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
254df31175bSPaolo Bonzini                       [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
255df31175bSPaolo Bonzini                       [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
256df31175bSPaolo Bonzini                       [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
257a7291e7eSJani Nikula                       # in rst this can refer to any type
258df31175bSPaolo Bonzini                       [$type_fallback, "\\:c\\:type\\:`\$1`"],
259c0d1b6eeSJonathan Corbet                       [$type_param, "**\$1**"]
260c0d1b6eeSJonathan Corbet		      );
261c0d1b6eeSJonathan Corbetmy $blankline_rst = "\n";
262c0d1b6eeSJonathan Corbet
2631da177e4SLinus Torvalds# read arguments
2641da177e4SLinus Torvaldsif ($#ARGV == -1) {
2651da177e4SLinus Torvalds    usage();
2661da177e4SLinus Torvalds}
2671da177e4SLinus Torvalds
2688484baaaSRandy Dunlapmy $kernelversion;
2698484baaaSRandy Dunlapmy $dohighlight = "";
2708484baaaSRandy Dunlap
2711da177e4SLinus Torvaldsmy $verbose = 0;
272bdfe2be3SMauro Carvalho Chehabmy $output_mode = "rst";
273e314ba31SDaniel Santosmy $output_preformatted = 0;
2744b44595aSJohannes Bergmy $no_doc_sections = 0;
2750b0f5f29SDaniel Vettermy $enable_lineno = 0;
276bdfe2be3SMauro Carvalho Chehabmy @highlights = @highlights_rst;
277bdfe2be3SMauro Carvalho Chehabmy $blankline = $blankline_rst;
2781da177e4SLinus Torvaldsmy $modulename = "Kernel API";
279b6c3f456SJani Nikula
280b6c3f456SJani Nikulause constant {
281b6c3f456SJani Nikula    OUTPUT_ALL          => 0, # output all symbols and doc sections
282b6c3f456SJani Nikula    OUTPUT_INCLUDE      => 1, # output only specified symbols
283b6c3f456SJani Nikula    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
284b6c3f456SJani Nikula    OUTPUT_EXPORTED     => 3, # output exported symbols
285b6c3f456SJani Nikula    OUTPUT_INTERNAL     => 4, # output non-exported symbols
286b6c3f456SJani Nikula};
287b6c3f456SJani Nikulamy $output_selection = OUTPUT_ALL;
288b0d60bfbSJonathan Corbetmy $show_not_found = 0;	# No longer used
289b2c4105bSBen Hutchings
29088c2b57dSJani Nikulamy @export_file_list;
29188c2b57dSJani Nikula
292b2c4105bSBen Hutchingsmy @build_time;
293b2c4105bSBen Hutchingsif (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
294b2c4105bSBen Hutchings    (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
295b2c4105bSBen Hutchings    @build_time = gmtime($seconds);
296b2c4105bSBen Hutchings} else {
297b2c4105bSBen Hutchings    @build_time = localtime;
298b2c4105bSBen Hutchings}
299b2c4105bSBen Hutchings
3001da177e4SLinus Torvaldsmy $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
3011da177e4SLinus Torvalds		'July', 'August', 'September', 'October',
302b2c4105bSBen Hutchings		'November', 'December')[$build_time[4]] .
303b2c4105bSBen Hutchings  " " . ($build_time[5]+1900);
3041da177e4SLinus Torvalds
3058484baaaSRandy Dunlap# Essentially these are globals.
306b9d97328SRandy Dunlap# They probably want to be tidied up, made more localised or something.
307b9d97328SRandy Dunlap# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
3081da177e4SLinus Torvalds# could cause "use of undefined value" or other bugs.
3091da177e4SLinus Torvaldsmy ($function, %function_table, %parametertypes, $declaration_purpose);
3100b0f5f29SDaniel Vettermy $declaration_start_line;
3111da177e4SLinus Torvaldsmy ($type, $declaration_name, $return_type);
3121c32fd0cSIlya Dryomovmy ($newsection, $newcontents, $prototype, $brcount, %source_map);
3131da177e4SLinus Torvalds
314bd0e88e5SRandy Dunlapif (defined($ENV{'KBUILD_VERBOSE'})) {
315bd0e88e5SRandy Dunlap	$verbose = "$ENV{'KBUILD_VERBOSE'}";
316bd0e88e5SRandy Dunlap}
317bd0e88e5SRandy Dunlap
3181da177e4SLinus Torvalds# Generated docbook code is inserted in a template at a point where
3191da177e4SLinus Torvalds# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
3201da177e4SLinus Torvalds# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
3211da177e4SLinus Torvalds# We keep track of number of generated entries and generate a dummy
3221da177e4SLinus Torvalds# if needs be to ensure the expanded template can be postprocessed
3231da177e4SLinus Torvalds# into html.
3241da177e4SLinus Torvaldsmy $section_counter = 0;
3251da177e4SLinus Torvalds
3261da177e4SLinus Torvaldsmy $lineprefix="";
3271da177e4SLinus Torvalds
32848af606aSJani Nikula# Parser states
32948af606aSJani Nikulause constant {
33048af606aSJani Nikula    STATE_NORMAL        => 0, # normal code
33148af606aSJani Nikula    STATE_NAME          => 1, # looking for function name
33217b78717SJonathan Corbet    STATE_BODY_MAYBE    => 2, # body - or maybe more description
33317b78717SJonathan Corbet    STATE_BODY          => 3, # the body of the comment
33417b78717SJonathan Corbet    STATE_PROTO         => 4, # scanning prototype
33517b78717SJonathan Corbet    STATE_DOCBLOCK      => 5, # documentation block
33617b78717SJonathan Corbet    STATE_INLINE        => 6, # gathering documentation outside main block
33748af606aSJani Nikula};
3381da177e4SLinus Torvaldsmy $state;
339850622dfSRandy Dunlapmy $in_doc_sect;
340d742f24dSJonathan Corbetmy $leading_space;
3411da177e4SLinus Torvalds
34248af606aSJani Nikula# Inline documentation state
34348af606aSJani Nikulause constant {
34448af606aSJani Nikula    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
34548af606aSJani Nikula    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
34648af606aSJani Nikula    STATE_INLINE_TEXT   => 2, # looking for member documentation
34748af606aSJani Nikula    STATE_INLINE_END    => 3, # done
34848af606aSJani Nikula    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
34948af606aSJani Nikula                              # Spit a warning as it's not
350a4c6ebedSDanilo Cesar Lemes de Paula                              # proper kernel-doc and ignore the rest.
35148af606aSJani Nikula};
35248af606aSJani Nikulamy $inline_doc_state;
353a4c6ebedSDanilo Cesar Lemes de Paula
3541da177e4SLinus Torvalds#declaration types: can be
3551da177e4SLinus Torvalds# 'function', 'struct', 'union', 'enum', 'typedef'
3561da177e4SLinus Torvaldsmy $decl_type;
3571da177e4SLinus Torvalds
3581da177e4SLinus Torvaldsmy $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
3591da177e4SLinus Torvaldsmy $doc_end = '\*/';
3601da177e4SLinus Torvaldsmy $doc_com = '\s*\*\s*';
36112ae6779SDaniel Santosmy $doc_com_body = '\s*\* ?';
3621da177e4SLinus Torvaldsmy $doc_decl = $doc_com . '(\w+)';
363f624adefSJani Nikula# @params and a strictly limited set of supported section names
3648569de68SJonathan Corbetmy $doc_sect = $doc_com .
365ef00028bSJonathan Corbet    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
36612ae6779SDaniel Santosmy $doc_content = $doc_com_body . '(.*)';
3671da177e4SLinus Torvaldsmy $doc_block = $doc_com . 'DOC:\s*(.*)?';
36848af606aSJani Nikulamy $doc_inline_start = '^\s*/\*\*\s*$';
369fe7bc493SMauro Carvalho Chehabmy $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
37048af606aSJani Nikulamy $doc_inline_end = '^\s*\*/\s*$';
3710c9aa209SJani Nikulamy $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
37286ae2e38SJani Nikulamy $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
3731da177e4SLinus Torvalds
3741da177e4SLinus Torvaldsmy %parameterdescs;
3750b0f5f29SDaniel Vettermy %parameterdesc_start_lines;
3761da177e4SLinus Torvaldsmy @parameterlist;
3771da177e4SLinus Torvaldsmy %sections;
3781da177e4SLinus Torvaldsmy @sectionlist;
3790b0f5f29SDaniel Vettermy %section_start_lines;
380a1d94aa5SRandy Dunlapmy $sectcheck;
381a1d94aa5SRandy Dunlapmy $struct_actual;
3821da177e4SLinus Torvalds
3831da177e4SLinus Torvaldsmy $contents = "";
3840b0f5f29SDaniel Vettermy $new_start_line = 0;
385f624adefSJani Nikula
386f624adefSJani Nikula# the canonical section names. see also $doc_sect above.
3871da177e4SLinus Torvaldsmy $section_default = "Description";	# default section
3881da177e4SLinus Torvaldsmy $section_intro = "Introduction";
3891da177e4SLinus Torvaldsmy $section = $section_default;
3901da177e4SLinus Torvaldsmy $section_context = "Context";
3914092bac7SYacine Belkadimy $section_return = "Return";
3921da177e4SLinus Torvalds
3931da177e4SLinus Torvaldsmy $undescribed = "-- undescribed --";
3941da177e4SLinus Torvalds
3951da177e4SLinus Torvaldsreset_state();
3961da177e4SLinus Torvalds
397b031ac4eSMauro Carvalho Chehabwhile ($ARGV[0] =~ m/^--?(.*)/) {
398b031ac4eSMauro Carvalho Chehab    my $cmd = $1;
399b031ac4eSMauro Carvalho Chehab    shift @ARGV;
400b031ac4eSMauro Carvalho Chehab    if ($cmd eq "man") {
4011da177e4SLinus Torvalds	$output_mode = "man";
4024d732701SDanilo Cesar Lemes de Paula	@highlights = @highlights_man;
4031da177e4SLinus Torvalds	$blankline = $blankline_man;
404b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "rst") {
405c0d1b6eeSJonathan Corbet	$output_mode = "rst";
406c0d1b6eeSJonathan Corbet	@highlights = @highlights_rst;
407c0d1b6eeSJonathan Corbet	$blankline = $blankline_rst;
408b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "none") {
4093a025e1dSMatthew Wilcox	$output_mode = "none";
410b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
4111da177e4SLinus Torvalds	$modulename = shift @ARGV;
412b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "function") { # to only output specific functions
413b6c3f456SJani Nikula	$output_selection = OUTPUT_INCLUDE;
4141da177e4SLinus Torvalds	$function = shift @ARGV;
4151da177e4SLinus Torvalds	$function_table{$function} = 1;
416b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "nofunction") { # output all except specific functions
417b6c3f456SJani Nikula	$output_selection = OUTPUT_EXCLUDE;
4181da177e4SLinus Torvalds	$function = shift @ARGV;
4191da177e4SLinus Torvalds	$function_table{$function} = 1;
420b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export") { # only exported symbols
421b6c3f456SJani Nikula	$output_selection = OUTPUT_EXPORTED;
422da9726ecSJani Nikula	%function_table = ();
423b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "internal") { # only non-exported symbols
424b6c3f456SJani Nikula	$output_selection = OUTPUT_INTERNAL;
425da9726ecSJani Nikula	%function_table = ();
426b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "export-file") {
42788c2b57dSJani Nikula	my $file = shift @ARGV;
42888c2b57dSJani Nikula	push(@export_file_list, $file);
429b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq "v") {
4301da177e4SLinus Torvalds	$verbose = 1;
431b031ac4eSMauro Carvalho Chehab    } elsif (($cmd eq "h") || ($cmd eq "help")) {
4321da177e4SLinus Torvalds	usage();
433b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'no-doc-sections') {
4344b44595aSJohannes Berg	    $no_doc_sections = 1;
435b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'enable-lineno') {
4360b0f5f29SDaniel Vetter	    $enable_lineno = 1;
437b031ac4eSMauro Carvalho Chehab    } elsif ($cmd eq 'show-not-found') {
438b0d60bfbSJonathan Corbet	$show_not_found = 1;  # A no-op but don't fail
439b031ac4eSMauro Carvalho Chehab    } else {
440b031ac4eSMauro Carvalho Chehab	# Unknown argument
441b031ac4eSMauro Carvalho Chehab        usage();
4421da177e4SLinus Torvalds    }
4431da177e4SLinus Torvalds}
4441da177e4SLinus Torvalds
4458484baaaSRandy Dunlap# continue execution near EOF;
4468484baaaSRandy Dunlap
44753f049faSBorislav Petkov# get kernel version from env
44853f049faSBorislav Petkovsub get_kernel_version() {
4491b9bc22dSJohannes Berg    my $version = 'unknown kernel version';
45053f049faSBorislav Petkov
45153f049faSBorislav Petkov    if (defined($ENV{'KERNELVERSION'})) {
45253f049faSBorislav Petkov	$version = $ENV{'KERNELVERSION'};
45353f049faSBorislav Petkov    }
45453f049faSBorislav Petkov    return $version;
45553f049faSBorislav Petkov}
4561da177e4SLinus Torvalds
4570b0f5f29SDaniel Vetter#
4580b0f5f29SDaniel Vettersub print_lineno {
4590b0f5f29SDaniel Vetter    my $lineno = shift;
4600b0f5f29SDaniel Vetter    if ($enable_lineno && defined($lineno)) {
4610b0f5f29SDaniel Vetter        print "#define LINENO " . $lineno . "\n";
4620b0f5f29SDaniel Vetter    }
4630b0f5f29SDaniel Vetter}
4641da177e4SLinus Torvalds##
4651da177e4SLinus Torvalds# dumps section contents to arrays/hashes intended for that purpose.
4661da177e4SLinus Torvalds#
4671da177e4SLinus Torvaldssub dump_section {
46894dc7ad5SRandy Dunlap    my $file = shift;
4691da177e4SLinus Torvalds    my $name = shift;
4701da177e4SLinus Torvalds    my $contents = join "\n", @_;
4711da177e4SLinus Torvalds
47213901ef2SJani Nikula    if ($name =~ m/$type_param/) {
4731da177e4SLinus Torvalds	$name = $1;
4741da177e4SLinus Torvalds	$parameterdescs{$name} = $contents;
475a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
4760b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
4770b0f5f29SDaniel Vetter        $new_start_line = 0;
478ced69090SRandy Dunlap    } elsif ($name eq "@\.\.\.") {
479ced69090SRandy Dunlap	$name = "...";
480ced69090SRandy Dunlap	$parameterdescs{$name} = $contents;
481a1d94aa5SRandy Dunlap	$sectcheck = $sectcheck . $name . " ";
4820b0f5f29SDaniel Vetter        $parameterdesc_start_lines{$name} = $new_start_line;
4830b0f5f29SDaniel Vetter        $new_start_line = 0;
4841da177e4SLinus Torvalds    } else {
48594dc7ad5SRandy Dunlap	if (defined($sections{$name}) && ($sections{$name} ne "")) {
48695b6be9dSJani Nikula	    # Only warn on user specified duplicate section names.
48795b6be9dSJani Nikula	    if ($name ne $section_default) {
48832217761SJani Nikula		print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
48932217761SJani Nikula		++$warnings;
49095b6be9dSJani Nikula	    }
49132217761SJani Nikula	    $sections{$name} .= $contents;
49232217761SJani Nikula	} else {
4931da177e4SLinus Torvalds	    $sections{$name} = $contents;
4941da177e4SLinus Torvalds	    push @sectionlist, $name;
4950b0f5f29SDaniel Vetter            $section_start_lines{$name} = $new_start_line;
4960b0f5f29SDaniel Vetter            $new_start_line = 0;
4971da177e4SLinus Torvalds	}
4981da177e4SLinus Torvalds    }
49932217761SJani Nikula}
5001da177e4SLinus Torvalds
5011da177e4SLinus Torvalds##
502b112e0f7SJohannes Berg# dump DOC: section after checking that it should go out
503b112e0f7SJohannes Berg#
504b112e0f7SJohannes Bergsub dump_doc_section {
50594dc7ad5SRandy Dunlap    my $file = shift;
506b112e0f7SJohannes Berg    my $name = shift;
507b112e0f7SJohannes Berg    my $contents = join "\n", @_;
508b112e0f7SJohannes Berg
5094b44595aSJohannes Berg    if ($no_doc_sections) {
5104b44595aSJohannes Berg        return;
5114b44595aSJohannes Berg    }
5124b44595aSJohannes Berg
513b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
514b6c3f456SJani Nikula	($output_selection == OUTPUT_INCLUDE &&
515b6c3f456SJani Nikula	 defined($function_table{$name})) ||
516b6c3f456SJani Nikula	($output_selection == OUTPUT_EXCLUDE &&
517b6c3f456SJani Nikula	 !defined($function_table{$name})))
518b112e0f7SJohannes Berg    {
51994dc7ad5SRandy Dunlap	dump_section($file, $name, $contents);
520b112e0f7SJohannes Berg	output_blockhead({'sectionlist' => \@sectionlist,
521b112e0f7SJohannes Berg			  'sections' => \%sections,
522b112e0f7SJohannes Berg			  'module' => $modulename,
523b6c3f456SJani Nikula			  'content-only' => ($output_selection != OUTPUT_ALL), });
524b112e0f7SJohannes Berg    }
525b112e0f7SJohannes Berg}
526b112e0f7SJohannes Berg
527b112e0f7SJohannes Berg##
5281da177e4SLinus Torvalds# output function
5291da177e4SLinus Torvalds#
5301da177e4SLinus Torvalds# parameterdescs, a hash.
5311da177e4SLinus Torvalds#  function => "function name"
5321da177e4SLinus Torvalds#  parameterlist => @list of parameters
5331da177e4SLinus Torvalds#  parameterdescs => %parameter descriptions
5341da177e4SLinus Torvalds#  sectionlist => @list of sections
535a21217daSRandy Dunlap#  sections => %section descriptions
5361da177e4SLinus Torvalds#
5371da177e4SLinus Torvalds
5381da177e4SLinus Torvaldssub output_highlight {
5391da177e4SLinus Torvalds    my $contents = join "\n",@_;
5401da177e4SLinus Torvalds    my $line;
5411da177e4SLinus Torvalds
5421da177e4SLinus Torvalds#   DEBUG
5431da177e4SLinus Torvalds#   if (!defined $contents) {
5441da177e4SLinus Torvalds#	use Carp;
5451da177e4SLinus Torvalds#	confess "output_highlight got called with no args?\n";
5461da177e4SLinus Torvalds#   }
5471da177e4SLinus Torvalds
5483eb014a1SRandy Dunlap#   print STDERR "contents b4:$contents\n";
5491da177e4SLinus Torvalds    eval $dohighlight;
5501da177e4SLinus Torvalds    die $@ if $@;
5513eb014a1SRandy Dunlap#   print STDERR "contents af:$contents\n";
5523eb014a1SRandy Dunlap
5531da177e4SLinus Torvalds    foreach $line (split "\n", $contents) {
55412ae6779SDaniel Santos	if (! $output_preformatted) {
55512ae6779SDaniel Santos	    $line =~ s/^\s*//;
55612ae6779SDaniel Santos	}
5571da177e4SLinus Torvalds	if ($line eq ""){
558e314ba31SDaniel Santos	    if (! $output_preformatted) {
5590bba924cSJonathan Corbet		print $lineprefix, $blankline;
560e314ba31SDaniel Santos	    }
5611da177e4SLinus Torvalds	} else {
562cdccb316SRandy Dunlap	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
563cdccb316SRandy Dunlap		print "\\&$line";
564cdccb316SRandy Dunlap	    } else {
5651da177e4SLinus Torvalds		print $lineprefix, $line;
5661da177e4SLinus Torvalds	    }
567cdccb316SRandy Dunlap	}
5681da177e4SLinus Torvalds	print "\n";
5691da177e4SLinus Torvalds    }
5701da177e4SLinus Torvalds}
5711da177e4SLinus Torvalds
5721da177e4SLinus Torvalds##
5731da177e4SLinus Torvalds# output function in man
5741da177e4SLinus Torvaldssub output_function_man(%) {
5751da177e4SLinus Torvalds    my %args = %{$_[0]};
5761da177e4SLinus Torvalds    my ($parameter, $section);
5771da177e4SLinus Torvalds    my $count;
5781da177e4SLinus Torvalds
5791da177e4SLinus Torvalds    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
5801da177e4SLinus Torvalds
5811da177e4SLinus Torvalds    print ".SH NAME\n";
5821da177e4SLinus Torvalds    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
5831da177e4SLinus Torvalds
5841da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
585a21217daSRandy Dunlap    if ($args{'functiontype'} ne "") {
5861da177e4SLinus Torvalds	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
587a21217daSRandy Dunlap    } else {
588a21217daSRandy Dunlap	print ".B \"" . $args{'function'} . "\n";
589a21217daSRandy Dunlap    }
5901da177e4SLinus Torvalds    $count = 0;
5911da177e4SLinus Torvalds    my $parenth = "(";
5921da177e4SLinus Torvalds    my $post = ",";
5931da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
5941da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
5951da177e4SLinus Torvalds	    $post = ");";
5961da177e4SLinus Torvalds	}
5971da177e4SLinus Torvalds	$type = $args{'parametertypes'}{$parameter};
5981da177e4SLinus Torvalds	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
5991da177e4SLinus Torvalds	    # pointer-to-function
6001da177e4SLinus Torvalds	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
6011da177e4SLinus Torvalds	} else {
6021da177e4SLinus Torvalds	    $type =~ s/([^\*])$/$1 /;
6031da177e4SLinus Torvalds	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
6041da177e4SLinus Torvalds	}
6051da177e4SLinus Torvalds	$count++;
6061da177e4SLinus Torvalds	$parenth = "";
6071da177e4SLinus Torvalds    }
6081da177e4SLinus Torvalds
6091da177e4SLinus Torvalds    print ".SH ARGUMENTS\n";
6101da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
6111da177e4SLinus Torvalds	my $parameter_name = $parameter;
6121da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
6131da177e4SLinus Torvalds
6141da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
6151da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
6161da177e4SLinus Torvalds    }
6171da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6181da177e4SLinus Torvalds	print ".SH \"", uc $section, "\"\n";
6191da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6201da177e4SLinus Torvalds    }
6211da177e4SLinus Torvalds}
6221da177e4SLinus Torvalds
6231da177e4SLinus Torvalds##
6241da177e4SLinus Torvalds# output enum in man
6251da177e4SLinus Torvaldssub output_enum_man(%) {
6261da177e4SLinus Torvalds    my %args = %{$_[0]};
6271da177e4SLinus Torvalds    my ($parameter, $section);
6281da177e4SLinus Torvalds    my $count;
6291da177e4SLinus Torvalds
6301da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
6311da177e4SLinus Torvalds
6321da177e4SLinus Torvalds    print ".SH NAME\n";
6331da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
6341da177e4SLinus Torvalds
6351da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
6361da177e4SLinus Torvalds    print "enum " . $args{'enum'} . " {\n";
6371da177e4SLinus Torvalds    $count = 0;
6381da177e4SLinus Torvalds    foreach my $parameter (@{$args{'parameterlist'}}) {
6391da177e4SLinus Torvalds	print ".br\n.BI \"    $parameter\"\n";
6401da177e4SLinus Torvalds	if ($count == $#{$args{'parameterlist'}}) {
6411da177e4SLinus Torvalds	    print "\n};\n";
6421da177e4SLinus Torvalds	    last;
6431da177e4SLinus Torvalds	}
6441da177e4SLinus Torvalds	else {
6451da177e4SLinus Torvalds	    print ", \n.br\n";
6461da177e4SLinus Torvalds	}
6471da177e4SLinus Torvalds	$count++;
6481da177e4SLinus Torvalds    }
6491da177e4SLinus Torvalds
6501da177e4SLinus Torvalds    print ".SH Constants\n";
6511da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
6521da177e4SLinus Torvalds	my $parameter_name = $parameter;
6531da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
6541da177e4SLinus Torvalds
6551da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
6561da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
6571da177e4SLinus Torvalds    }
6581da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6591da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6601da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6611da177e4SLinus Torvalds    }
6621da177e4SLinus Torvalds}
6631da177e4SLinus Torvalds
6641da177e4SLinus Torvalds##
6651da177e4SLinus Torvalds# output struct in man
6661da177e4SLinus Torvaldssub output_struct_man(%) {
6671da177e4SLinus Torvalds    my %args = %{$_[0]};
6681da177e4SLinus Torvalds    my ($parameter, $section);
6691da177e4SLinus Torvalds
6701da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
6711da177e4SLinus Torvalds
6721da177e4SLinus Torvalds    print ".SH NAME\n";
6731da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
6741da177e4SLinus Torvalds
6758ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
6768ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
6778ad72163SMauro Carvalho Chehab    $declaration =~ s/\n/"\n.br\n.BI \"/g;
6781da177e4SLinus Torvalds    print ".SH SYNOPSIS\n";
6791da177e4SLinus Torvalds    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
6808ad72163SMauro Carvalho Chehab    print ".BI \"$declaration\n};\n.br\n\n";
6811da177e4SLinus Torvalds
682c51d3dacSRandy Dunlap    print ".SH Members\n";
6831da177e4SLinus Torvalds    foreach $parameter (@{$args{'parameterlist'}}) {
6841da177e4SLinus Torvalds	($parameter =~ /^#/) && next;
6851da177e4SLinus Torvalds
6861da177e4SLinus Torvalds	my $parameter_name = $parameter;
6871da177e4SLinus Torvalds	$parameter_name =~ s/\[.*//;
6881da177e4SLinus Torvalds
6891da177e4SLinus Torvalds	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
6901da177e4SLinus Torvalds	print ".IP \"" . $parameter . "\" 12\n";
6911da177e4SLinus Torvalds	output_highlight($args{'parameterdescs'}{$parameter_name});
6921da177e4SLinus Torvalds    }
6931da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
6941da177e4SLinus Torvalds	print ".SH \"$section\"\n";
6951da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
6961da177e4SLinus Torvalds    }
6971da177e4SLinus Torvalds}
6981da177e4SLinus Torvalds
6991da177e4SLinus Torvalds##
7001da177e4SLinus Torvalds# output typedef in man
7011da177e4SLinus Torvaldssub output_typedef_man(%) {
7021da177e4SLinus Torvalds    my %args = %{$_[0]};
7031da177e4SLinus Torvalds    my ($parameter, $section);
7041da177e4SLinus Torvalds
7051da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
7061da177e4SLinus Torvalds
7071da177e4SLinus Torvalds    print ".SH NAME\n";
7081da177e4SLinus Torvalds    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
7091da177e4SLinus Torvalds
7101da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
7111da177e4SLinus Torvalds	print ".SH \"$section\"\n";
7121da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
7131da177e4SLinus Torvalds    }
7141da177e4SLinus Torvalds}
7151da177e4SLinus Torvalds
716b112e0f7SJohannes Bergsub output_blockhead_man(%) {
7171da177e4SLinus Torvalds    my %args = %{$_[0]};
7181da177e4SLinus Torvalds    my ($parameter, $section);
7191da177e4SLinus Torvalds    my $count;
7201da177e4SLinus Torvalds
7211da177e4SLinus Torvalds    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
7221da177e4SLinus Torvalds
7231da177e4SLinus Torvalds    foreach $section (@{$args{'sectionlist'}}) {
7241da177e4SLinus Torvalds	print ".SH \"$section\"\n";
7251da177e4SLinus Torvalds	output_highlight($args{'sections'}{$section});
7261da177e4SLinus Torvalds    }
7271da177e4SLinus Torvalds}
7281da177e4SLinus Torvalds
7291da177e4SLinus Torvalds##
730c0d1b6eeSJonathan Corbet# output in restructured text
731c0d1b6eeSJonathan Corbet#
732c0d1b6eeSJonathan Corbet
733c0d1b6eeSJonathan Corbet#
734c0d1b6eeSJonathan Corbet# This could use some work; it's used to output the DOC: sections, and
735c0d1b6eeSJonathan Corbet# starts by putting out the name of the doc section itself, but that tends
736c0d1b6eeSJonathan Corbet# to duplicate a header already in the template file.
737c0d1b6eeSJonathan Corbet#
738c0d1b6eeSJonathan Corbetsub output_blockhead_rst(%) {
739c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
740c0d1b6eeSJonathan Corbet    my ($parameter, $section);
741c0d1b6eeSJonathan Corbet
742c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
7439e72184bSJani Nikula	if ($output_selection != OUTPUT_INCLUDE) {
744c0d1b6eeSJonathan Corbet	    print "**$section**\n\n";
7459e72184bSJani Nikula	}
7460b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
747c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
748c0d1b6eeSJonathan Corbet	print "\n";
749c0d1b6eeSJonathan Corbet    }
750c0d1b6eeSJonathan Corbet}
751c0d1b6eeSJonathan Corbet
752af250290SJonathan Corbet#
753af250290SJonathan Corbet# Apply the RST highlights to a sub-block of text.
754af250290SJonathan Corbet#
755af250290SJonathan Corbetsub highlight_block($) {
756af250290SJonathan Corbet    # The dohighlight kludge requires the text be called $contents
757af250290SJonathan Corbet    my $contents = shift;
758c0d1b6eeSJonathan Corbet    eval $dohighlight;
759c0d1b6eeSJonathan Corbet    die $@ if $@;
760af250290SJonathan Corbet    return $contents;
761af250290SJonathan Corbet}
762c0d1b6eeSJonathan Corbet
763af250290SJonathan Corbet#
764af250290SJonathan Corbet# Regexes used only here.
765af250290SJonathan Corbet#
766af250290SJonathan Corbetmy $sphinx_literal = '^[^.].*::$';
767af250290SJonathan Corbetmy $sphinx_cblock = '^\.\.\ +code-block::';
768af250290SJonathan Corbet
769af250290SJonathan Corbetsub output_highlight_rst {
770af250290SJonathan Corbet    my $input = join "\n",@_;
771af250290SJonathan Corbet    my $output = "";
772af250290SJonathan Corbet    my $line;
773af250290SJonathan Corbet    my $in_literal = 0;
774af250290SJonathan Corbet    my $litprefix;
775af250290SJonathan Corbet    my $block = "";
776af250290SJonathan Corbet
777af250290SJonathan Corbet    foreach $line (split "\n",$input) {
778af250290SJonathan Corbet	#
779af250290SJonathan Corbet	# If we're in a literal block, see if we should drop out
780af250290SJonathan Corbet	# of it.  Otherwise pass the line straight through unmunged.
781af250290SJonathan Corbet	#
782af250290SJonathan Corbet	if ($in_literal) {
783af250290SJonathan Corbet	    if (! ($line =~ /^\s*$/)) {
784af250290SJonathan Corbet		#
785af250290SJonathan Corbet		# If this is the first non-blank line in a literal
786af250290SJonathan Corbet		# block we need to figure out what the proper indent is.
787af250290SJonathan Corbet		#
788af250290SJonathan Corbet		if ($litprefix eq "") {
789af250290SJonathan Corbet		    $line =~ /^(\s*)/;
790af250290SJonathan Corbet		    $litprefix = '^' . $1;
791af250290SJonathan Corbet		    $output .= $line . "\n";
792af250290SJonathan Corbet		} elsif (! ($line =~ /$litprefix/)) {
793af250290SJonathan Corbet		    $in_literal = 0;
794af250290SJonathan Corbet		} else {
795af250290SJonathan Corbet		    $output .= $line . "\n";
796af250290SJonathan Corbet		}
797af250290SJonathan Corbet	    } else {
798af250290SJonathan Corbet		$output .= $line . "\n";
799af250290SJonathan Corbet	    }
800af250290SJonathan Corbet	}
801af250290SJonathan Corbet	#
802af250290SJonathan Corbet	# Not in a literal block (or just dropped out)
803af250290SJonathan Corbet	#
804af250290SJonathan Corbet	if (! $in_literal) {
805af250290SJonathan Corbet	    $block .= $line . "\n";
806af250290SJonathan Corbet	    if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
807af250290SJonathan Corbet		$in_literal = 1;
808af250290SJonathan Corbet		$litprefix = "";
809af250290SJonathan Corbet		$output .= highlight_block($block);
810af250290SJonathan Corbet		$block = ""
811af250290SJonathan Corbet	    }
812af250290SJonathan Corbet	}
813af250290SJonathan Corbet    }
814af250290SJonathan Corbet
815af250290SJonathan Corbet    if ($block) {
816af250290SJonathan Corbet	$output .= highlight_block($block);
817af250290SJonathan Corbet    }
818af250290SJonathan Corbet    foreach $line (split "\n", $output) {
819830066a7SJani Nikula	print $lineprefix . $line . "\n";
820c0d1b6eeSJonathan Corbet    }
821c0d1b6eeSJonathan Corbet}
822c0d1b6eeSJonathan Corbet
823c0d1b6eeSJonathan Corbetsub output_function_rst(%) {
824c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
825c0d1b6eeSJonathan Corbet    my ($parameter, $section);
826c099ff69SJani Nikula    my $oldprefix = $lineprefix;
82782801d06SMauro Carvalho Chehab    my $start = "";
828c0d1b6eeSJonathan Corbet
82982801d06SMauro Carvalho Chehab    if ($args{'typedef'}) {
83082801d06SMauro Carvalho Chehab	print ".. c:type:: ". $args{'function'} . "\n\n";
83182801d06SMauro Carvalho Chehab	print_lineno($declaration_start_line);
83282801d06SMauro Carvalho Chehab	print "   **Typedef**: ";
83382801d06SMauro Carvalho Chehab	$lineprefix = "";
83482801d06SMauro Carvalho Chehab	output_highlight_rst($args{'purpose'});
83582801d06SMauro Carvalho Chehab	$start = "\n\n**Syntax**\n\n  ``";
836c0d1b6eeSJonathan Corbet    } else {
83782801d06SMauro Carvalho Chehab	print ".. c:function:: ";
83882801d06SMauro Carvalho Chehab    }
83982801d06SMauro Carvalho Chehab    if ($args{'functiontype'} ne "") {
84082801d06SMauro Carvalho Chehab	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
84182801d06SMauro Carvalho Chehab    } else {
84282801d06SMauro Carvalho Chehab	$start .= $args{'function'} . " (";
843c0d1b6eeSJonathan Corbet    }
844c0d1b6eeSJonathan Corbet    print $start;
845c0d1b6eeSJonathan Corbet
846c0d1b6eeSJonathan Corbet    my $count = 0;
847c0d1b6eeSJonathan Corbet    foreach my $parameter (@{$args{'parameterlist'}}) {
848c0d1b6eeSJonathan Corbet	if ($count ne 0) {
849c0d1b6eeSJonathan Corbet	    print ", ";
850c0d1b6eeSJonathan Corbet	}
851c0d1b6eeSJonathan Corbet	$count++;
852c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
853a88b1672SMauro Carvalho Chehab
854c0d1b6eeSJonathan Corbet	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
855c0d1b6eeSJonathan Corbet	    # pointer-to-function
856c0d1b6eeSJonathan Corbet	    print $1 . $parameter . ") (" . $2;
857c0d1b6eeSJonathan Corbet	} else {
858c0d1b6eeSJonathan Corbet	    print $type . " " . $parameter;
859c0d1b6eeSJonathan Corbet	}
860c0d1b6eeSJonathan Corbet    }
86182801d06SMauro Carvalho Chehab    if ($args{'typedef'}) {
86282801d06SMauro Carvalho Chehab	print ");``\n\n";
86382801d06SMauro Carvalho Chehab    } else {
864c099ff69SJani Nikula	print ")\n\n";
8650b0f5f29SDaniel Vetter	print_lineno($declaration_start_line);
866c099ff69SJani Nikula	$lineprefix = "   ";
867c099ff69SJani Nikula	output_highlight_rst($args{'purpose'});
868c099ff69SJani Nikula	print "\n";
86982801d06SMauro Carvalho Chehab    }
870c0d1b6eeSJonathan Corbet
871ecbcfba1SJani Nikula    print "**Parameters**\n\n";
872c099ff69SJani Nikula    $lineprefix = "  ";
873c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
874c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
875ada5f446SGabriel Krisman Bertazi	$parameter_name =~ s/\[.*//;
876c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
877c0d1b6eeSJonathan Corbet
878c0d1b6eeSJonathan Corbet	if ($type ne "") {
879c0d1b6eeSJonathan Corbet	    print "``$type $parameter``\n";
880c0d1b6eeSJonathan Corbet	} else {
881c0d1b6eeSJonathan Corbet	    print "``$parameter``\n";
882c0d1b6eeSJonathan Corbet	}
8830b0f5f29SDaniel Vetter
8840b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
8850b0f5f29SDaniel Vetter
8865e64fa9cSJani Nikula	if (defined($args{'parameterdescs'}{$parameter_name}) &&
8875e64fa9cSJani Nikula	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
888c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});
889c0d1b6eeSJonathan Corbet	} else {
890d4b08e0cSJani Nikula	    print "  *undescribed*\n";
891c0d1b6eeSJonathan Corbet	}
892c0d1b6eeSJonathan Corbet	print "\n";
893c0d1b6eeSJonathan Corbet    }
894c099ff69SJani Nikula
895c099ff69SJani Nikula    $lineprefix = $oldprefix;
896c0d1b6eeSJonathan Corbet    output_section_rst(@_);
897c0d1b6eeSJonathan Corbet}
898c0d1b6eeSJonathan Corbet
899c0d1b6eeSJonathan Corbetsub output_section_rst(%) {
900c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
901c0d1b6eeSJonathan Corbet    my $section;
902c0d1b6eeSJonathan Corbet    my $oldprefix = $lineprefix;
903c0d1b6eeSJonathan Corbet    $lineprefix = "";
904c0d1b6eeSJonathan Corbet
905c0d1b6eeSJonathan Corbet    foreach $section (@{$args{'sectionlist'}}) {
906ecbcfba1SJani Nikula	print "**$section**\n\n";
9070b0f5f29SDaniel Vetter        print_lineno($section_start_lines{$section});
908c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'sections'}{$section});
909c0d1b6eeSJonathan Corbet	print "\n";
910c0d1b6eeSJonathan Corbet    }
911c0d1b6eeSJonathan Corbet    print "\n";
912c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
913c0d1b6eeSJonathan Corbet}
914c0d1b6eeSJonathan Corbet
915c0d1b6eeSJonathan Corbetsub output_enum_rst(%) {
916c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
917c0d1b6eeSJonathan Corbet    my ($parameter);
918c099ff69SJani Nikula    my $oldprefix = $lineprefix;
919c0d1b6eeSJonathan Corbet    my $count;
920c0d1b6eeSJonathan Corbet    my $name = "enum " . $args{'enum'};
92162850976SJani Nikula
92262850976SJani Nikula    print "\n\n.. c:type:: " . $name . "\n\n";
9230b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
924c099ff69SJani Nikula    $lineprefix = "   ";
925c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
926c099ff69SJani Nikula    print "\n";
927c0d1b6eeSJonathan Corbet
928ecbcfba1SJani Nikula    print "**Constants**\n\n";
929c0d1b6eeSJonathan Corbet    $lineprefix = "  ";
930c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
931ecbcfba1SJani Nikula	print "``$parameter``\n";
932c0d1b6eeSJonathan Corbet	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
933c0d1b6eeSJonathan Corbet	    output_highlight_rst($args{'parameterdescs'}{$parameter});
934c0d1b6eeSJonathan Corbet	} else {
935d4b08e0cSJani Nikula	    print "  *undescribed*\n";
936c0d1b6eeSJonathan Corbet	}
937c0d1b6eeSJonathan Corbet	print "\n";
938c0d1b6eeSJonathan Corbet    }
939c099ff69SJani Nikula
940c0d1b6eeSJonathan Corbet    $lineprefix = $oldprefix;
941c0d1b6eeSJonathan Corbet    output_section_rst(@_);
942c0d1b6eeSJonathan Corbet}
943c0d1b6eeSJonathan Corbet
944c0d1b6eeSJonathan Corbetsub output_typedef_rst(%) {
945c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
946c0d1b6eeSJonathan Corbet    my ($parameter);
947c099ff69SJani Nikula    my $oldprefix = $lineprefix;
948c0d1b6eeSJonathan Corbet    my $name = "typedef " . $args{'typedef'};
949c0d1b6eeSJonathan Corbet
95062850976SJani Nikula    print "\n\n.. c:type:: " . $name . "\n\n";
9510b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
952c099ff69SJani Nikula    $lineprefix = "   ";
953c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
954c099ff69SJani Nikula    print "\n";
955c0d1b6eeSJonathan Corbet
956c099ff69SJani Nikula    $lineprefix = $oldprefix;
957c0d1b6eeSJonathan Corbet    output_section_rst(@_);
958c0d1b6eeSJonathan Corbet}
959c0d1b6eeSJonathan Corbet
960c0d1b6eeSJonathan Corbetsub output_struct_rst(%) {
961c0d1b6eeSJonathan Corbet    my %args = %{$_[0]};
962c0d1b6eeSJonathan Corbet    my ($parameter);
963c099ff69SJani Nikula    my $oldprefix = $lineprefix;
964c0d1b6eeSJonathan Corbet    my $name = $args{'type'} . " " . $args{'struct'};
965c0d1b6eeSJonathan Corbet
96662850976SJani Nikula    print "\n\n.. c:type:: " . $name . "\n\n";
9670b0f5f29SDaniel Vetter    print_lineno($declaration_start_line);
968c099ff69SJani Nikula    $lineprefix = "   ";
969c099ff69SJani Nikula    output_highlight_rst($args{'purpose'});
970c099ff69SJani Nikula    print "\n";
971c0d1b6eeSJonathan Corbet
972ecbcfba1SJani Nikula    print "**Definition**\n\n";
973c0d1b6eeSJonathan Corbet    print "::\n\n";
9748ad72163SMauro Carvalho Chehab    my $declaration = $args{'definition'};
9758ad72163SMauro Carvalho Chehab    $declaration =~ s/\t/  /g;
9768ad72163SMauro Carvalho Chehab    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration  };\n\n";
977c0d1b6eeSJonathan Corbet
978ecbcfba1SJani Nikula    print "**Members**\n\n";
979c099ff69SJani Nikula    $lineprefix = "  ";
980c0d1b6eeSJonathan Corbet    foreach $parameter (@{$args{'parameterlist'}}) {
981c0d1b6eeSJonathan Corbet	($parameter =~ /^#/) && next;
982c0d1b6eeSJonathan Corbet
983c0d1b6eeSJonathan Corbet	my $parameter_name = $parameter;
984c0d1b6eeSJonathan Corbet	$parameter_name =~ s/\[.*//;
985c0d1b6eeSJonathan Corbet
986c0d1b6eeSJonathan Corbet	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
987c0d1b6eeSJonathan Corbet	$type = $args{'parametertypes'}{$parameter};
9880b0f5f29SDaniel Vetter        print_lineno($parameterdesc_start_lines{$parameter_name});
9896d232c80SMauro Carvalho Chehab	print "``" . $parameter . "``\n";
990c0d1b6eeSJonathan Corbet	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
991c0d1b6eeSJonathan Corbet	print "\n";
992c0d1b6eeSJonathan Corbet    }
993c0d1b6eeSJonathan Corbet    print "\n";
994c099ff69SJani Nikula
995c099ff69SJani Nikula    $lineprefix = $oldprefix;
996c0d1b6eeSJonathan Corbet    output_section_rst(@_);
997c0d1b6eeSJonathan Corbet}
998c0d1b6eeSJonathan Corbet
9993a025e1dSMatthew Wilcox## none mode output functions
10003a025e1dSMatthew Wilcox
10013a025e1dSMatthew Wilcoxsub output_function_none(%) {
10023a025e1dSMatthew Wilcox}
10033a025e1dSMatthew Wilcox
10043a025e1dSMatthew Wilcoxsub output_enum_none(%) {
10053a025e1dSMatthew Wilcox}
10063a025e1dSMatthew Wilcox
10073a025e1dSMatthew Wilcoxsub output_typedef_none(%) {
10083a025e1dSMatthew Wilcox}
10093a025e1dSMatthew Wilcox
10103a025e1dSMatthew Wilcoxsub output_struct_none(%) {
10113a025e1dSMatthew Wilcox}
10123a025e1dSMatthew Wilcox
10133a025e1dSMatthew Wilcoxsub output_blockhead_none(%) {
10143a025e1dSMatthew Wilcox}
10153a025e1dSMatthew Wilcox
10161da177e4SLinus Torvalds##
101727205744SRandy Dunlap# generic output function for all types (function, struct/union, typedef, enum);
101827205744SRandy Dunlap# calls the generated, variable output_ function name based on
101927205744SRandy Dunlap# functype and output_mode
10201da177e4SLinus Torvaldssub output_declaration {
10211da177e4SLinus Torvalds    no strict 'refs';
10221da177e4SLinus Torvalds    my $name = shift;
10231da177e4SLinus Torvalds    my $functype = shift;
10241da177e4SLinus Torvalds    my $func = "output_${functype}_$output_mode";
1025b6c3f456SJani Nikula    if (($output_selection == OUTPUT_ALL) ||
1026b6c3f456SJani Nikula	(($output_selection == OUTPUT_INCLUDE ||
1027b6c3f456SJani Nikula	  $output_selection == OUTPUT_EXPORTED) &&
102886ae2e38SJani Nikula	 defined($function_table{$name})) ||
1029b6c3f456SJani Nikula	(($output_selection == OUTPUT_EXCLUDE ||
1030b6c3f456SJani Nikula	  $output_selection == OUTPUT_INTERNAL) &&
103186ae2e38SJani Nikula	 !($functype eq "function" && defined($function_table{$name}))))
10321da177e4SLinus Torvalds    {
10331da177e4SLinus Torvalds	&$func(@_);
10341da177e4SLinus Torvalds	$section_counter++;
10351da177e4SLinus Torvalds    }
10361da177e4SLinus Torvalds}
10371da177e4SLinus Torvalds
10381da177e4SLinus Torvalds##
103927205744SRandy Dunlap# generic output function - calls the right one based on current output mode.
1040b112e0f7SJohannes Bergsub output_blockhead {
10411da177e4SLinus Torvalds    no strict 'refs';
1042b112e0f7SJohannes Berg    my $func = "output_blockhead_" . $output_mode;
10431da177e4SLinus Torvalds    &$func(@_);
10441da177e4SLinus Torvalds    $section_counter++;
10451da177e4SLinus Torvalds}
10461da177e4SLinus Torvalds
10471da177e4SLinus Torvalds##
10481da177e4SLinus Torvalds# takes a declaration (struct, union, enum, typedef) and
10491da177e4SLinus Torvalds# invokes the right handler. NOT called for functions.
10501da177e4SLinus Torvaldssub dump_declaration($$) {
10511da177e4SLinus Torvalds    no strict 'refs';
10521da177e4SLinus Torvalds    my ($prototype, $file) = @_;
10531da177e4SLinus Torvalds    my $func = "dump_" . $decl_type;
10541da177e4SLinus Torvalds    &$func(@_);
10551da177e4SLinus Torvalds}
10561da177e4SLinus Torvalds
10571da177e4SLinus Torvaldssub dump_union($$) {
10581da177e4SLinus Torvalds    dump_struct(@_);
10591da177e4SLinus Torvalds}
10601da177e4SLinus Torvalds
10611da177e4SLinus Torvaldssub dump_struct($$) {
10621da177e4SLinus Torvalds    my $x = shift;
10631da177e4SLinus Torvalds    my $file = shift;
10641da177e4SLinus Torvalds
10653d9bfb19SSakari Ailus    if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
10665cb5c31cSJohannes Berg	my $decl_type = $1;
10671da177e4SLinus Torvalds	$declaration_name = $2;
10681da177e4SLinus Torvalds	my $members = $3;
10691da177e4SLinus Torvalds
1070aeec46b9SMartin Waitz	# ignore members marked private:
10710d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
10720d8c39e6SMauro Carvalho Chehab	$members =~ s/\/\*\s*private:.*//gosi;
1073aeec46b9SMartin Waitz	# strip comments:
1074aeec46b9SMartin Waitz	$members =~ s/\/\*.*?\*\///gos;
1075ef5da59fSRandy Dunlap	# strip attributes
10763d9bfb19SSakari Ailus	$members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
10773d9bfb19SSakari Ailus	$members =~ s/\s*__aligned\s*\([^;]*\)//gos;
10783d9bfb19SSakari Ailus	$members =~ s/\s*__packed\s*//gos;
1079f0074929SJonathan Corbet	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
1080b22b5a9eSConchúr Navid	# replace DECLARE_BITMAP
108145005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
10821cb566baSJakub Kicinski	# replace DECLARE_HASHTABLE
108345005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
108445005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO
108545005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
108645005b27SMauro Carvalho Chehab	# replace DECLARE_KFIFO_PTR
108745005b27SMauro Carvalho Chehab	$members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1088aeec46b9SMartin Waitz
10898ad72163SMauro Carvalho Chehab	my $declaration = $members;
10908ad72163SMauro Carvalho Chehab
10918ad72163SMauro Carvalho Chehab	# Split nested struct/union elements as newer ones
109284ce5b98SMauro Carvalho Chehab	while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
109384ce5b98SMauro Carvalho Chehab		my $newmember;
109484ce5b98SMauro Carvalho Chehab		my $maintype = $1;
109584ce5b98SMauro Carvalho Chehab		my $ids = $4;
10968ad72163SMauro Carvalho Chehab		my $content = $3;
109784ce5b98SMauro Carvalho Chehab		foreach my $id(split /,/, $ids) {
109884ce5b98SMauro Carvalho Chehab			$newmember .= "$maintype $id; ";
109984ce5b98SMauro Carvalho Chehab
11008ad72163SMauro Carvalho Chehab			$id =~ s/[:\[].*//;
110184ce5b98SMauro Carvalho Chehab			$id =~ s/^\s*\**(\S+)\s*/$1/;
11028ad72163SMauro Carvalho Chehab			foreach my $arg (split /;/, $content) {
11038ad72163SMauro Carvalho Chehab				next if ($arg =~ m/^\s*$/);
11047c0d7e87SMauro Carvalho Chehab				if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
11057c0d7e87SMauro Carvalho Chehab					# pointer-to-function
11067c0d7e87SMauro Carvalho Chehab					my $type = $1;
11077c0d7e87SMauro Carvalho Chehab					my $name = $2;
11087c0d7e87SMauro Carvalho Chehab					my $extra = $3;
11097c0d7e87SMauro Carvalho Chehab					next if (!$name);
11107c0d7e87SMauro Carvalho Chehab					if ($id =~ m/^\s*$/) {
11117c0d7e87SMauro Carvalho Chehab						# anonymous struct/union
11127c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$name$extra; ";
11137c0d7e87SMauro Carvalho Chehab					} else {
11147c0d7e87SMauro Carvalho Chehab						$newmember .= "$type$id.$name$extra; ";
11157c0d7e87SMauro Carvalho Chehab					}
11167c0d7e87SMauro Carvalho Chehab				} else {
111784ce5b98SMauro Carvalho Chehab					my $type;
111884ce5b98SMauro Carvalho Chehab					my $names;
111984ce5b98SMauro Carvalho Chehab					$arg =~ s/^\s+//;
112084ce5b98SMauro Carvalho Chehab					$arg =~ s/\s+$//;
112184ce5b98SMauro Carvalho Chehab					# Handle bitmaps
112284ce5b98SMauro Carvalho Chehab					$arg =~ s/:\s*\d+\s*//g;
112384ce5b98SMauro Carvalho Chehab					# Handle arrays
1124d404d579SMauro Carvalho Chehab					$arg =~ s/\[.*\]//g;
112584ce5b98SMauro Carvalho Chehab					# The type may have multiple words,
112684ce5b98SMauro Carvalho Chehab					# and multiple IDs can be defined, like:
112784ce5b98SMauro Carvalho Chehab					#	const struct foo, *bar, foobar
112884ce5b98SMauro Carvalho Chehab					# So, we remove spaces when parsing the
112984ce5b98SMauro Carvalho Chehab					# names, in order to match just names
113084ce5b98SMauro Carvalho Chehab					# and commas for the names
113184ce5b98SMauro Carvalho Chehab					$arg =~ s/\s*,\s*/,/g;
113284ce5b98SMauro Carvalho Chehab					if ($arg =~ m/(.*)\s+([\S+,]+)/) {
113384ce5b98SMauro Carvalho Chehab						$type = $1;
113484ce5b98SMauro Carvalho Chehab						$names = $2;
113584ce5b98SMauro Carvalho Chehab					} else {
113684ce5b98SMauro Carvalho Chehab						$newmember .= "$arg; ";
113784ce5b98SMauro Carvalho Chehab						next;
113884ce5b98SMauro Carvalho Chehab					}
113984ce5b98SMauro Carvalho Chehab					foreach my $name (split /,/, $names) {
114084ce5b98SMauro Carvalho Chehab						$name =~ s/^\s*\**(\S+)\s*/$1/;
11418ad72163SMauro Carvalho Chehab						next if (($name =~ m/^\s*$/));
11428ad72163SMauro Carvalho Chehab						if ($id =~ m/^\s*$/) {
11438ad72163SMauro Carvalho Chehab							# anonymous struct/union
11448ad72163SMauro Carvalho Chehab							$newmember .= "$type $name; ";
11458ad72163SMauro Carvalho Chehab						} else {
11468ad72163SMauro Carvalho Chehab							$newmember .= "$type $id.$name; ";
11478ad72163SMauro Carvalho Chehab						}
11488ad72163SMauro Carvalho Chehab					}
11497c0d7e87SMauro Carvalho Chehab				}
115084ce5b98SMauro Carvalho Chehab			}
115184ce5b98SMauro Carvalho Chehab		}
1152673bb2dfSBen Hutchings		$members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/;
115384ce5b98SMauro Carvalho Chehab	}
11548ad72163SMauro Carvalho Chehab
11558ad72163SMauro Carvalho Chehab	# Ignore other nested elements, like enums
1156673bb2dfSBen Hutchings	$members =~ s/(\{[^\{\}]*\})//g;
11578ad72163SMauro Carvalho Chehab
1158151c468bSMauro Carvalho Chehab	create_parameterlist($members, ';', $file, $declaration_name);
11591081de2dSMauro Carvalho Chehab	check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
11601da177e4SLinus Torvalds
11618ad72163SMauro Carvalho Chehab	# Adjust declaration for better display
1162673bb2dfSBen Hutchings	$declaration =~ s/([\{;])/$1\n/g;
1163673bb2dfSBen Hutchings	$declaration =~ s/\}\s+;/};/g;
11648ad72163SMauro Carvalho Chehab	# Better handle inlined enums
1165673bb2dfSBen Hutchings	do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
11668ad72163SMauro Carvalho Chehab
11678ad72163SMauro Carvalho Chehab	my @def_args = split /\n/, $declaration;
11688ad72163SMauro Carvalho Chehab	my $level = 1;
11698ad72163SMauro Carvalho Chehab	$declaration = "";
11708ad72163SMauro Carvalho Chehab	foreach my $clause (@def_args) {
11718ad72163SMauro Carvalho Chehab		$clause =~ s/^\s+//;
11728ad72163SMauro Carvalho Chehab		$clause =~ s/\s+$//;
11738ad72163SMauro Carvalho Chehab		$clause =~ s/\s+/ /;
11748ad72163SMauro Carvalho Chehab		next if (!$clause);
1175673bb2dfSBen Hutchings		$level-- if ($clause =~ m/(\})/ && $level > 1);
11768ad72163SMauro Carvalho Chehab		if (!($clause =~ m/^\s*#/)) {
11778ad72163SMauro Carvalho Chehab			$declaration .= "\t" x $level;
11788ad72163SMauro Carvalho Chehab		}
11798ad72163SMauro Carvalho Chehab		$declaration .= "\t" . $clause . "\n";
1180673bb2dfSBen Hutchings		$level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
11818ad72163SMauro Carvalho Chehab	}
11821da177e4SLinus Torvalds	output_declaration($declaration_name,
11831da177e4SLinus Torvalds			   'struct',
11841da177e4SLinus Torvalds			   {'struct' => $declaration_name,
11851da177e4SLinus Torvalds			    'module' => $modulename,
11868ad72163SMauro Carvalho Chehab			    'definition' => $declaration,
11871da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
11881da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
11891da177e4SLinus Torvalds			    'parametertypes' => \%parametertypes,
11901da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
11911da177e4SLinus Torvalds			    'sections' => \%sections,
11921da177e4SLinus Torvalds			    'purpose' => $declaration_purpose,
11931da177e4SLinus Torvalds			    'type' => $decl_type
11941da177e4SLinus Torvalds			   });
11951da177e4SLinus Torvalds    }
11961da177e4SLinus Torvalds    else {
1197d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
11981da177e4SLinus Torvalds	++$errors;
11991da177e4SLinus Torvalds    }
12001da177e4SLinus Torvalds}
12011da177e4SLinus Torvalds
120285afe608SMauro Carvalho Chehab
120385afe608SMauro Carvalho Chehabsub show_warnings($$) {
120485afe608SMauro Carvalho Chehab	my $functype = shift;
120585afe608SMauro Carvalho Chehab	my $name = shift;
120685afe608SMauro Carvalho Chehab
120785afe608SMauro Carvalho Chehab	return 1 if ($output_selection == OUTPUT_ALL);
120885afe608SMauro Carvalho Chehab
120985afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_EXPORTED) {
121085afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
121185afe608SMauro Carvalho Chehab			return 1;
121285afe608SMauro Carvalho Chehab		} else {
121385afe608SMauro Carvalho Chehab			return 0;
121485afe608SMauro Carvalho Chehab		}
121585afe608SMauro Carvalho Chehab	}
121685afe608SMauro Carvalho Chehab        if ($output_selection == OUTPUT_INTERNAL) {
121785afe608SMauro Carvalho Chehab		if (!($functype eq "function" && defined($function_table{$name}))) {
121885afe608SMauro Carvalho Chehab			return 1;
121985afe608SMauro Carvalho Chehab		} else {
122085afe608SMauro Carvalho Chehab			return 0;
122185afe608SMauro Carvalho Chehab		}
122285afe608SMauro Carvalho Chehab	}
122385afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_INCLUDE) {
122485afe608SMauro Carvalho Chehab		if (defined($function_table{$name})) {
122585afe608SMauro Carvalho Chehab			return 1;
122685afe608SMauro Carvalho Chehab		} else {
122785afe608SMauro Carvalho Chehab			return 0;
122885afe608SMauro Carvalho Chehab		}
122985afe608SMauro Carvalho Chehab	}
123085afe608SMauro Carvalho Chehab	if ($output_selection == OUTPUT_EXCLUDE) {
123185afe608SMauro Carvalho Chehab		if (!defined($function_table{$name})) {
123285afe608SMauro Carvalho Chehab			return 1;
123385afe608SMauro Carvalho Chehab		} else {
123485afe608SMauro Carvalho Chehab			return 0;
123585afe608SMauro Carvalho Chehab		}
123685afe608SMauro Carvalho Chehab	}
123785afe608SMauro Carvalho Chehab	die("Please add the new output type at show_warnings()");
123885afe608SMauro Carvalho Chehab}
123985afe608SMauro Carvalho Chehab
12401da177e4SLinus Torvaldssub dump_enum($$) {
12411da177e4SLinus Torvalds    my $x = shift;
12421da177e4SLinus Torvalds    my $file = shift;
12431da177e4SLinus Torvalds
1244aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
12454468e21eSConchúr Navid    # strip #define macros inside enums
12464468e21eSConchúr Navid    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1247b6d676dbSRandy Dunlap
1248673bb2dfSBen Hutchings    if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) {
12491da177e4SLinus Torvalds	$declaration_name = $1;
12501da177e4SLinus Torvalds	my $members = $2;
12515cb5c31cSJohannes Berg	my %_members;
12525cb5c31cSJohannes Berg
1253463a0fdcSMarkus Heiser	$members =~ s/\s+$//;
12541da177e4SLinus Torvalds
12551da177e4SLinus Torvalds	foreach my $arg (split ',', $members) {
12561da177e4SLinus Torvalds	    $arg =~ s/^\s*(\w+).*/$1/;
12571da177e4SLinus Torvalds	    push @parameterlist, $arg;
12581da177e4SLinus Torvalds	    if (!$parameterdescs{$arg}) {
12591da177e4SLinus Torvalds		$parameterdescs{$arg} = $undescribed;
126085afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
12612defb272SMauro Carvalho Chehab			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
12622defb272SMauro Carvalho Chehab		}
12631da177e4SLinus Torvalds	    }
12645cb5c31cSJohannes Berg	    $_members{$arg} = 1;
12655cb5c31cSJohannes Berg	}
12661da177e4SLinus Torvalds
12675cb5c31cSJohannes Berg	while (my ($k, $v) = each %parameterdescs) {
12685cb5c31cSJohannes Berg	    if (!exists($_members{$k})) {
126985afe608SMauro Carvalho Chehab	        if (show_warnings("enum", $declaration_name)) {
12702defb272SMauro Carvalho Chehab		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
12712defb272SMauro Carvalho Chehab		}
12725cb5c31cSJohannes Berg	    }
12731da177e4SLinus Torvalds        }
12741da177e4SLinus Torvalds
12751da177e4SLinus Torvalds	output_declaration($declaration_name,
12761da177e4SLinus Torvalds			   'enum',
12771da177e4SLinus Torvalds			   {'enum' => $declaration_name,
12781da177e4SLinus Torvalds			    'module' => $modulename,
12791da177e4SLinus Torvalds			    'parameterlist' => \@parameterlist,
12801da177e4SLinus Torvalds			    'parameterdescs' => \%parameterdescs,
12811da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
12821da177e4SLinus Torvalds			    'sections' => \%sections,
12831da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
12841da177e4SLinus Torvalds			   });
12851da177e4SLinus Torvalds    }
12861da177e4SLinus Torvalds    else {
1287d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse enum!\n";
12881da177e4SLinus Torvalds	++$errors;
12891da177e4SLinus Torvalds    }
12901da177e4SLinus Torvalds}
12911da177e4SLinus Torvalds
12921da177e4SLinus Torvaldssub dump_typedef($$) {
12931da177e4SLinus Torvalds    my $x = shift;
12941da177e4SLinus Torvalds    my $file = shift;
12951da177e4SLinus Torvalds
1296aeec46b9SMartin Waitz    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
129783766452SMauro Carvalho Chehab
129883766452SMauro Carvalho Chehab    # Parse function prototypes
1299d37c43ceSMauro Carvalho Chehab    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
1300d37c43ceSMauro Carvalho Chehab	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
1301d37c43ceSMauro Carvalho Chehab
130283766452SMauro Carvalho Chehab	# Function typedefs
130383766452SMauro Carvalho Chehab	$return_type = $1;
130483766452SMauro Carvalho Chehab	$declaration_name = $2;
130583766452SMauro Carvalho Chehab	my $args = $3;
130683766452SMauro Carvalho Chehab
1307151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
130883766452SMauro Carvalho Chehab
130983766452SMauro Carvalho Chehab	output_declaration($declaration_name,
131083766452SMauro Carvalho Chehab			   'function',
131183766452SMauro Carvalho Chehab			   {'function' => $declaration_name,
131282801d06SMauro Carvalho Chehab			    'typedef' => 1,
131383766452SMauro Carvalho Chehab			    'module' => $modulename,
131483766452SMauro Carvalho Chehab			    'functiontype' => $return_type,
131583766452SMauro Carvalho Chehab			    'parameterlist' => \@parameterlist,
131683766452SMauro Carvalho Chehab			    'parameterdescs' => \%parameterdescs,
131783766452SMauro Carvalho Chehab			    'parametertypes' => \%parametertypes,
131883766452SMauro Carvalho Chehab			    'sectionlist' => \@sectionlist,
131983766452SMauro Carvalho Chehab			    'sections' => \%sections,
132083766452SMauro Carvalho Chehab			    'purpose' => $declaration_purpose
132183766452SMauro Carvalho Chehab			   });
132283766452SMauro Carvalho Chehab	return;
132383766452SMauro Carvalho Chehab    }
132483766452SMauro Carvalho Chehab
13251da177e4SLinus Torvalds    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
13261da177e4SLinus Torvalds	$x =~ s/\(*.\)\s*;$/;/;
13271da177e4SLinus Torvalds	$x =~ s/\[*.\]\s*;$/;/;
13281da177e4SLinus Torvalds    }
13291da177e4SLinus Torvalds
13301da177e4SLinus Torvalds    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
13311da177e4SLinus Torvalds	$declaration_name = $1;
13321da177e4SLinus Torvalds
13331da177e4SLinus Torvalds	output_declaration($declaration_name,
13341da177e4SLinus Torvalds			   'typedef',
13351da177e4SLinus Torvalds			   {'typedef' => $declaration_name,
13361da177e4SLinus Torvalds			    'module' => $modulename,
13371da177e4SLinus Torvalds			    'sectionlist' => \@sectionlist,
13381da177e4SLinus Torvalds			    'sections' => \%sections,
13391da177e4SLinus Torvalds			    'purpose' => $declaration_purpose
13401da177e4SLinus Torvalds			   });
13411da177e4SLinus Torvalds    }
13421da177e4SLinus Torvalds    else {
1343d40e1e65SBart Van Assche	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
13441da177e4SLinus Torvalds	++$errors;
13451da177e4SLinus Torvalds    }
13461da177e4SLinus Torvalds}
13471da177e4SLinus Torvalds
1348a1d94aa5SRandy Dunlapsub save_struct_actual($) {
1349a1d94aa5SRandy Dunlap    my $actual = shift;
1350a1d94aa5SRandy Dunlap
1351a1d94aa5SRandy Dunlap    # strip all spaces from the actual param so that it looks like one string item
1352a1d94aa5SRandy Dunlap    $actual =~ s/\s*//g;
1353a1d94aa5SRandy Dunlap    $struct_actual = $struct_actual . $actual . " ";
1354a1d94aa5SRandy Dunlap}
1355a1d94aa5SRandy Dunlap
1356151c468bSMauro Carvalho Chehabsub create_parameterlist($$$$) {
13571da177e4SLinus Torvalds    my $args = shift;
13581da177e4SLinus Torvalds    my $splitter = shift;
13591da177e4SLinus Torvalds    my $file = shift;
1360151c468bSMauro Carvalho Chehab    my $declaration_name = shift;
13611da177e4SLinus Torvalds    my $type;
13621da177e4SLinus Torvalds    my $param;
13631da177e4SLinus Torvalds
1364a6d3fe77SMartin Waitz    # temporarily replace commas inside function pointer definition
13651da177e4SLinus Torvalds    while ($args =~ /(\([^\),]+),/) {
13661da177e4SLinus Torvalds	$args =~ s/(\([^\),]+),/$1#/g;
13671da177e4SLinus Torvalds    }
13681da177e4SLinus Torvalds
13691da177e4SLinus Torvalds    foreach my $arg (split($splitter, $args)) {
13701da177e4SLinus Torvalds	# strip comments
13711da177e4SLinus Torvalds	$arg =~ s/\/\*.*\*\///;
13721da177e4SLinus Torvalds	# strip leading/trailing spaces
13731da177e4SLinus Torvalds	$arg =~ s/^\s*//;
13741da177e4SLinus Torvalds	$arg =~ s/\s*$//;
13751da177e4SLinus Torvalds	$arg =~ s/\s+/ /;
13761da177e4SLinus Torvalds
13771da177e4SLinus Torvalds	if ($arg =~ /^#/) {
13781da177e4SLinus Torvalds	    # Treat preprocessor directive as a typeless variable just to fill
13791da177e4SLinus Torvalds	    # corresponding data structures "correctly". Catch it later in
13801da177e4SLinus Torvalds	    # output_* subs.
13811da177e4SLinus Torvalds	    push_parameter($arg, "", $file);
138200d62961SRichard Kennedy	} elsif ($arg =~ m/\(.+\)\s*\(/) {
13831da177e4SLinus Torvalds	    # pointer-to-function
13841da177e4SLinus Torvalds	    $arg =~ tr/#/,/;
13857c0d7e87SMauro Carvalho Chehab	    $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
13861da177e4SLinus Torvalds	    $param = $1;
13871da177e4SLinus Torvalds	    $type = $arg;
138800d62961SRichard Kennedy	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1389a1d94aa5SRandy Dunlap	    save_struct_actual($param);
1390151c468bSMauro Carvalho Chehab	    push_parameter($param, $type, $file, $declaration_name);
1391aeec46b9SMartin Waitz	} elsif ($arg) {
13921da177e4SLinus Torvalds	    $arg =~ s/\s*:\s*/:/g;
13931da177e4SLinus Torvalds	    $arg =~ s/\s*\[/\[/g;
13941da177e4SLinus Torvalds
13951da177e4SLinus Torvalds	    my @args = split('\s*,\s*', $arg);
13961da177e4SLinus Torvalds	    if ($args[0] =~ m/\*/) {
13971da177e4SLinus Torvalds		$args[0] =~ s/(\*+)\s*/ $1/;
13981da177e4SLinus Torvalds	    }
1399884f2810SBorislav Petkov
1400884f2810SBorislav Petkov	    my @first_arg;
1401884f2810SBorislav Petkov	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1402884f2810SBorislav Petkov		    shift @args;
1403884f2810SBorislav Petkov		    push(@first_arg, split('\s+', $1));
1404884f2810SBorislav Petkov		    push(@first_arg, $2);
1405884f2810SBorislav Petkov	    } else {
1406884f2810SBorislav Petkov		    @first_arg = split('\s+', shift @args);
1407884f2810SBorislav Petkov	    }
1408884f2810SBorislav Petkov
14091da177e4SLinus Torvalds	    unshift(@args, pop @first_arg);
14101da177e4SLinus Torvalds	    $type = join " ", @first_arg;
14111da177e4SLinus Torvalds
14121da177e4SLinus Torvalds	    foreach $param (@args) {
14131da177e4SLinus Torvalds		if ($param =~ m/^(\*+)\s*(.*)/) {
1414a1d94aa5SRandy Dunlap		    save_struct_actual($2);
1415151c468bSMauro Carvalho Chehab		    push_parameter($2, "$type $1", $file, $declaration_name);
14161da177e4SLinus Torvalds		}
14171da177e4SLinus Torvalds		elsif ($param =~ m/(.*?):(\d+)/) {
14187b97887eSRandy Dunlap		    if ($type ne "") { # skip unnamed bit-fields
1419a1d94aa5SRandy Dunlap			save_struct_actual($1);
1420151c468bSMauro Carvalho Chehab			push_parameter($1, "$type:$2", $file, $declaration_name)
14211da177e4SLinus Torvalds		    }
14227b97887eSRandy Dunlap		}
14231da177e4SLinus Torvalds		else {
1424a1d94aa5SRandy Dunlap		    save_struct_actual($param);
1425151c468bSMauro Carvalho Chehab		    push_parameter($param, $type, $file, $declaration_name);
14261da177e4SLinus Torvalds		}
14271da177e4SLinus Torvalds	    }
14281da177e4SLinus Torvalds	}
14291da177e4SLinus Torvalds    }
14301da177e4SLinus Torvalds}
14311da177e4SLinus Torvalds
1432151c468bSMauro Carvalho Chehabsub push_parameter($$$$) {
14331da177e4SLinus Torvalds	my $param = shift;
14341da177e4SLinus Torvalds	my $type = shift;
14351da177e4SLinus Torvalds	my $file = shift;
1436151c468bSMauro Carvalho Chehab	my $declaration_name = shift;
14371da177e4SLinus Torvalds
14385f8c7c98SRandy Dunlap	if (($anon_struct_union == 1) && ($type eq "") &&
14395f8c7c98SRandy Dunlap	    ($param eq "}")) {
14405f8c7c98SRandy Dunlap		return;		# ignore the ending }; from anon. struct/union
14415f8c7c98SRandy Dunlap	}
14425f8c7c98SRandy Dunlap
14435f8c7c98SRandy Dunlap	$anon_struct_union = 0;
1444f9b5c530SMauro Carvalho Chehab	$param =~ s/[\[\)].*//;
14451da177e4SLinus Torvalds
1446a6d3fe77SMartin Waitz	if ($type eq "" && $param =~ /\.\.\.$/)
14471da177e4SLinus Torvalds	{
1448c950a173SSilvio Fricke	    if (!$param =~ /\w\.\.\.$/) {
1449c950a173SSilvio Fricke	      # handles unnamed variable parameters
1450ef00028bSJonathan Corbet	      $param = "...";
1451c950a173SSilvio Fricke	    }
1452ced69090SRandy Dunlap	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1453a6d3fe77SMartin Waitz		$parameterdescs{$param} = "variable arguments";
14541da177e4SLinus Torvalds	    }
1455ced69090SRandy Dunlap	}
14561da177e4SLinus Torvalds	elsif ($type eq "" && ($param eq "" or $param eq "void"))
14571da177e4SLinus Torvalds	{
14581da177e4SLinus Torvalds	    $param="void";
14591da177e4SLinus Torvalds	    $parameterdescs{void} = "no arguments";
14601da177e4SLinus Torvalds	}
1461134fe01bSRandy Dunlap	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1462134fe01bSRandy Dunlap	# handle unnamed (anonymous) union or struct:
1463134fe01bSRandy Dunlap	{
1464134fe01bSRandy Dunlap		$type = $param;
1465134fe01bSRandy Dunlap		$param = "{unnamed_" . $param . "}";
1466134fe01bSRandy Dunlap		$parameterdescs{$param} = "anonymous\n";
14675f8c7c98SRandy Dunlap		$anon_struct_union = 1;
1468134fe01bSRandy Dunlap	}
1469134fe01bSRandy Dunlap
1470a6d3fe77SMartin Waitz	# warn if parameter has no description
1471134fe01bSRandy Dunlap	# (but ignore ones starting with # as these are not parameters
1472134fe01bSRandy Dunlap	# but inline preprocessor statements);
1473151c468bSMauro Carvalho Chehab	# Note: It will also ignore void params and unnamed structs/unions
1474f9b5c530SMauro Carvalho Chehab	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1475f9b5c530SMauro Carvalho Chehab		$parameterdescs{$param} = $undescribed;
14761da177e4SLinus Torvalds
1477be5cd20cSJonathan Corbet	        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
1478151c468bSMauro Carvalho Chehab			print STDERR
1479151c468bSMauro Carvalho Chehab			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
14801da177e4SLinus Torvalds			++$warnings;
14811da177e4SLinus Torvalds		}
14822defb272SMauro Carvalho Chehab	}
14831da177e4SLinus Torvalds
148425985edcSLucas De Marchi	# strip spaces from $param so that it is one continuous string
1485e34e7dbbSRandy Dunlap	# on @parameterlist;
1486e34e7dbbSRandy Dunlap	# this fixes a problem where check_sections() cannot find
1487e34e7dbbSRandy Dunlap	# a parameter like "addr[6 + 2]" because it actually appears
1488e34e7dbbSRandy Dunlap	# as "addr[6", "+", "2]" on the parameter list;
1489e34e7dbbSRandy Dunlap	# but it's better to maintain the param string unchanged for output,
1490e34e7dbbSRandy Dunlap	# so just weaken the string compare in check_sections() to ignore
1491e34e7dbbSRandy Dunlap	# "[blah" in a parameter string;
1492e34e7dbbSRandy Dunlap	###$param =~ s/\s*//g;
14931da177e4SLinus Torvalds	push @parameterlist, $param;
149402a4f4feSPaolo Bonzini	$type =~ s/\s\s+/ /g;
14951da177e4SLinus Torvalds	$parametertypes{$param} = $type;
14961da177e4SLinus Torvalds}
14971da177e4SLinus Torvalds
14981081de2dSMauro Carvalho Chehabsub check_sections($$$$$) {
14991081de2dSMauro Carvalho Chehab	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
1500a1d94aa5SRandy Dunlap	my @sects = split ' ', $sectcheck;
1501a1d94aa5SRandy Dunlap	my @prms = split ' ', $prmscheck;
1502a1d94aa5SRandy Dunlap	my $err;
1503a1d94aa5SRandy Dunlap	my ($px, $sx);
1504a1d94aa5SRandy Dunlap	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
1505a1d94aa5SRandy Dunlap
1506a1d94aa5SRandy Dunlap	foreach $sx (0 .. $#sects) {
1507a1d94aa5SRandy Dunlap		$err = 1;
1508a1d94aa5SRandy Dunlap		foreach $px (0 .. $#prms) {
1509a1d94aa5SRandy Dunlap			$prm_clean = $prms[$px];
1510a1d94aa5SRandy Dunlap			$prm_clean =~ s/\[.*\]//;
15111f3a6688SJohannes Berg			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1512e34e7dbbSRandy Dunlap			# ignore array size in a parameter string;
1513e34e7dbbSRandy Dunlap			# however, the original param string may contain
1514e34e7dbbSRandy Dunlap			# spaces, e.g.:  addr[6 + 2]
1515e34e7dbbSRandy Dunlap			# and this appears in @prms as "addr[6" since the
1516e34e7dbbSRandy Dunlap			# parameter list is split at spaces;
1517e34e7dbbSRandy Dunlap			# hence just ignore "[..." for the sections check;
1518e34e7dbbSRandy Dunlap			$prm_clean =~ s/\[.*//;
1519e34e7dbbSRandy Dunlap
1520a1d94aa5SRandy Dunlap			##$prm_clean =~ s/^\**//;
1521a1d94aa5SRandy Dunlap			if ($prm_clean eq $sects[$sx]) {
1522a1d94aa5SRandy Dunlap				$err = 0;
1523a1d94aa5SRandy Dunlap				last;
1524a1d94aa5SRandy Dunlap			}
1525a1d94aa5SRandy Dunlap		}
1526a1d94aa5SRandy Dunlap		if ($err) {
1527a1d94aa5SRandy Dunlap			if ($decl_type eq "function") {
1528d40e1e65SBart Van Assche				print STDERR "${file}:$.: warning: " .
1529a1d94aa5SRandy Dunlap					"Excess function parameter " .
1530a1d94aa5SRandy Dunlap					"'$sects[$sx]' " .
1531a1d94aa5SRandy Dunlap					"description in '$decl_name'\n";
1532a1d94aa5SRandy Dunlap				++$warnings;
1533a1d94aa5SRandy Dunlap			}
1534a1d94aa5SRandy Dunlap		}
1535a1d94aa5SRandy Dunlap	}
1536a1d94aa5SRandy Dunlap}
1537a1d94aa5SRandy Dunlap
15381da177e4SLinus Torvalds##
15394092bac7SYacine Belkadi# Checks the section describing the return value of a function.
15404092bac7SYacine Belkadisub check_return_section {
15414092bac7SYacine Belkadi        my $file = shift;
15424092bac7SYacine Belkadi        my $declaration_name = shift;
15434092bac7SYacine Belkadi        my $return_type = shift;
15444092bac7SYacine Belkadi
15454092bac7SYacine Belkadi        # Ignore an empty return type (It's a macro)
15464092bac7SYacine Belkadi        # Ignore functions with a "void" return type. (But don't ignore "void *")
15474092bac7SYacine Belkadi        if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
15484092bac7SYacine Belkadi                return;
15494092bac7SYacine Belkadi        }
15504092bac7SYacine Belkadi
15514092bac7SYacine Belkadi        if (!defined($sections{$section_return}) ||
15524092bac7SYacine Belkadi            $sections{$section_return} eq "") {
1553d40e1e65SBart Van Assche                print STDERR "${file}:$.: warning: " .
15544092bac7SYacine Belkadi                        "No description found for return value of " .
15554092bac7SYacine Belkadi                        "'$declaration_name'\n";
15564092bac7SYacine Belkadi                ++$warnings;
15574092bac7SYacine Belkadi        }
15584092bac7SYacine Belkadi}
15594092bac7SYacine Belkadi
15604092bac7SYacine Belkadi##
15611da177e4SLinus Torvalds# takes a function prototype and the name of the current file being
15621da177e4SLinus Torvalds# processed and spits out all the details stored in the global
15631da177e4SLinus Torvalds# arrays/hashes.
15641da177e4SLinus Torvaldssub dump_function($$) {
15651da177e4SLinus Torvalds    my $prototype = shift;
15661da177e4SLinus Torvalds    my $file = shift;
1567cbb4d3e6SHoria Geanta    my $noret = 0;
15681da177e4SLinus Torvalds
15691da177e4SLinus Torvalds    $prototype =~ s/^static +//;
15701da177e4SLinus Torvalds    $prototype =~ s/^extern +//;
15714dc3b16bSPavel Pisa    $prototype =~ s/^asmlinkage +//;
15721da177e4SLinus Torvalds    $prototype =~ s/^inline +//;
15731da177e4SLinus Torvalds    $prototype =~ s/^__inline__ +//;
157432e79401SRandy Dunlap    $prototype =~ s/^__inline +//;
157532e79401SRandy Dunlap    $prototype =~ s/^__always_inline +//;
157632e79401SRandy Dunlap    $prototype =~ s/^noinline +//;
157774fc5c65SRandy Dunlap    $prototype =~ s/__init +//;
157820072205SRandy Dunlap    $prototype =~ s/__init_or_module +//;
1579270a0096SRandy Dunlap    $prototype =~ s/__meminit +//;
158070c95b00SRandy Dunlap    $prototype =~ s/__must_check +//;
15810df7c0e3SRandy Dunlap    $prototype =~ s/__weak +//;
15820891f959SMatthew Wilcox    $prototype =~ s/__sched +//;
1583cbb4d3e6SHoria Geanta    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1584b1aaa546SPaolo Bonzini    $prototype =~ s/__attribute__\s*\(\(
1585b1aaa546SPaolo Bonzini            (?:
1586b1aaa546SPaolo Bonzini                 [\w\s]++          # attribute name
1587b1aaa546SPaolo Bonzini                 (?:\([^)]*+\))?   # attribute arguments
1588b1aaa546SPaolo Bonzini                 \s*+,?            # optional comma at the end
1589b1aaa546SPaolo Bonzini            )+
1590b1aaa546SPaolo Bonzini          \)\)\s+//x;
15911da177e4SLinus Torvalds
15921da177e4SLinus Torvalds    # Yes, this truly is vile.  We are looking for:
15931da177e4SLinus Torvalds    # 1. Return type (may be nothing if we're looking at a macro)
15941da177e4SLinus Torvalds    # 2. Function name
15951da177e4SLinus Torvalds    # 3. Function parameters.
15961da177e4SLinus Torvalds    #
15971da177e4SLinus Torvalds    # All the while we have to watch out for function pointer parameters
15981da177e4SLinus Torvalds    # (which IIRC is what the two sections are for), C types (these
15991da177e4SLinus Torvalds    # regexps don't even start to express all the possibilities), and
16001da177e4SLinus Torvalds    # so on.
16011da177e4SLinus Torvalds    #
16021da177e4SLinus Torvalds    # If you mess with these regexps, it's a good idea to check that
16031da177e4SLinus Torvalds    # the following functions' documentation still comes out right:
16041da177e4SLinus Torvalds    # - parport_register_device (function pointer parameters)
16051da177e4SLinus Torvalds    # - atomic_set (macro)
16069598f91fSMartin Waitz    # - pci_match_device, __copy_to_user (long return type)
16071da177e4SLinus Torvalds
1608cbb4d3e6SHoria Geanta    if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1609cbb4d3e6SHoria Geanta        # This is an object-like macro, it has no return type and no parameter
1610cbb4d3e6SHoria Geanta        # list.
1611cbb4d3e6SHoria Geanta        # Function-like macros are not allowed to have spaces between
1612cbb4d3e6SHoria Geanta        # declaration_name and opening parenthesis (notice the \s+).
1613cbb4d3e6SHoria Geanta        $return_type = $1;
1614cbb4d3e6SHoria Geanta        $declaration_name = $2;
1615cbb4d3e6SHoria Geanta        $noret = 1;
1616cbb4d3e6SHoria Geanta    } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16171da177e4SLinus Torvalds	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16185a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16191da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
162094b3e03cSRandy Dunlap	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16211da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16225a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
16231da177e4SLinus Torvalds	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16241da177e4SLinus Torvalds	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16255a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16261da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16275a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16281da177e4SLinus Torvalds	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16295a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16309598f91fSMartin Waitz	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16315a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
16325a0bc578SMatthew Wilcox	$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
16331da177e4SLinus Torvalds	$return_type = $1;
16341da177e4SLinus Torvalds	$declaration_name = $2;
16351da177e4SLinus Torvalds	my $args = $3;
16361da177e4SLinus Torvalds
1637151c468bSMauro Carvalho Chehab	create_parameterlist($args, ',', $file, $declaration_name);
16381da177e4SLinus Torvalds    } else {
1639d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
16401da177e4SLinus Torvalds	return;
16411da177e4SLinus Torvalds    }
16421da177e4SLinus Torvalds
1643a1d94aa5SRandy Dunlap	my $prms = join " ", @parameterlist;
16441081de2dSMauro Carvalho Chehab	check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1645a1d94aa5SRandy Dunlap
16464092bac7SYacine Belkadi        # This check emits a lot of warnings at the moment, because many
16474092bac7SYacine Belkadi        # functions don't have a 'Return' doc section. So until the number
16484092bac7SYacine Belkadi        # of warnings goes sufficiently down, the check is only performed in
16494092bac7SYacine Belkadi        # verbose mode.
16504092bac7SYacine Belkadi        # TODO: always perform the check.
1651cbb4d3e6SHoria Geanta        if ($verbose && !$noret) {
16524092bac7SYacine Belkadi                check_return_section($file, $declaration_name, $return_type);
16534092bac7SYacine Belkadi        }
16544092bac7SYacine Belkadi
16551da177e4SLinus Torvalds    output_declaration($declaration_name,
16561da177e4SLinus Torvalds		       'function',
16571da177e4SLinus Torvalds		       {'function' => $declaration_name,
16581da177e4SLinus Torvalds			'module' => $modulename,
16591da177e4SLinus Torvalds			'functiontype' => $return_type,
16601da177e4SLinus Torvalds			'parameterlist' => \@parameterlist,
16611da177e4SLinus Torvalds			'parameterdescs' => \%parameterdescs,
16621da177e4SLinus Torvalds			'parametertypes' => \%parametertypes,
16631da177e4SLinus Torvalds			'sectionlist' => \@sectionlist,
16641da177e4SLinus Torvalds			'sections' => \%sections,
16651da177e4SLinus Torvalds			'purpose' => $declaration_purpose
16661da177e4SLinus Torvalds		       });
16671da177e4SLinus Torvalds}
16681da177e4SLinus Torvalds
16691da177e4SLinus Torvaldssub reset_state {
16701da177e4SLinus Torvalds    $function = "";
16711da177e4SLinus Torvalds    %parameterdescs = ();
16721da177e4SLinus Torvalds    %parametertypes = ();
16731da177e4SLinus Torvalds    @parameterlist = ();
16741da177e4SLinus Torvalds    %sections = ();
16751da177e4SLinus Torvalds    @sectionlist = ();
1676a1d94aa5SRandy Dunlap    $sectcheck = "";
1677a1d94aa5SRandy Dunlap    $struct_actual = "";
16781da177e4SLinus Torvalds    $prototype = "";
16791da177e4SLinus Torvalds
168048af606aSJani Nikula    $state = STATE_NORMAL;
168148af606aSJani Nikula    $inline_doc_state = STATE_INLINE_NA;
16821da177e4SLinus Torvalds}
16831da177e4SLinus Torvalds
168456afb0f8SJason Baronsub tracepoint_munge($) {
168556afb0f8SJason Baron	my $file = shift;
168656afb0f8SJason Baron	my $tracepointname = 0;
168756afb0f8SJason Baron	my $tracepointargs = 0;
168856afb0f8SJason Baron
168956afb0f8SJason Baron	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
169056afb0f8SJason Baron		$tracepointname = $1;
169156afb0f8SJason Baron	}
16923a9089fdSJason Baron	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
16933a9089fdSJason Baron		$tracepointname = $1;
16943a9089fdSJason Baron	}
16953a9089fdSJason Baron	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
16963a9089fdSJason Baron		$tracepointname = $2;
16973a9089fdSJason Baron	}
16983a9089fdSJason Baron	$tracepointname =~ s/^\s+//; #strip leading whitespace
169956afb0f8SJason Baron	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
170056afb0f8SJason Baron		$tracepointargs = $1;
170156afb0f8SJason Baron	}
170256afb0f8SJason Baron	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1703d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
170456afb0f8SJason Baron			     "$prototype\n";
170556afb0f8SJason Baron	} else {
170656afb0f8SJason Baron		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
170756afb0f8SJason Baron	}
170856afb0f8SJason Baron}
170956afb0f8SJason Baron
1710b4870bc5SRandy Dunlapsub syscall_munge() {
1711b4870bc5SRandy Dunlap	my $void = 0;
1712b4870bc5SRandy Dunlap
17137c9aa015SMauro Carvalho Chehab	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1714b4870bc5SRandy Dunlap##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1715b4870bc5SRandy Dunlap	if ($prototype =~ m/SYSCALL_DEFINE0/) {
1716b4870bc5SRandy Dunlap		$void = 1;
1717b4870bc5SRandy Dunlap##		$prototype = "long sys_$1(void)";
1718b4870bc5SRandy Dunlap	}
1719b4870bc5SRandy Dunlap
1720b4870bc5SRandy Dunlap	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1721b4870bc5SRandy Dunlap	if ($prototype =~ m/long (sys_.*?),/) {
1722b4870bc5SRandy Dunlap		$prototype =~ s/,/\(/;
1723b4870bc5SRandy Dunlap	} elsif ($void) {
1724b4870bc5SRandy Dunlap		$prototype =~ s/\)/\(void\)/;
1725b4870bc5SRandy Dunlap	}
1726b4870bc5SRandy Dunlap
1727b4870bc5SRandy Dunlap	# now delete all of the odd-number commas in $prototype
1728b4870bc5SRandy Dunlap	# so that arg types & arg names don't have a comma between them
1729b4870bc5SRandy Dunlap	my $count = 0;
1730b4870bc5SRandy Dunlap	my $len = length($prototype);
1731b4870bc5SRandy Dunlap	if ($void) {
1732b4870bc5SRandy Dunlap		$len = 0;	# skip the for-loop
1733b4870bc5SRandy Dunlap	}
1734b4870bc5SRandy Dunlap	for (my $ix = 0; $ix < $len; $ix++) {
1735b4870bc5SRandy Dunlap		if (substr($prototype, $ix, 1) eq ',') {
1736b4870bc5SRandy Dunlap			$count++;
1737b4870bc5SRandy Dunlap			if ($count % 2 == 1) {
1738b4870bc5SRandy Dunlap				substr($prototype, $ix, 1) = ' ';
1739b4870bc5SRandy Dunlap			}
1740b4870bc5SRandy Dunlap		}
1741b4870bc5SRandy Dunlap	}
1742b4870bc5SRandy Dunlap}
1743b4870bc5SRandy Dunlap
1744b7afa92bSDaniel Vettersub process_proto_function($$) {
17451da177e4SLinus Torvalds    my $x = shift;
17461da177e4SLinus Torvalds    my $file = shift;
17471da177e4SLinus Torvalds
174851f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
174951f5a0c8SRandy Dunlap
1750890c78c2SRandy Dunlap    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
17511da177e4SLinus Torvalds	# do nothing
17521da177e4SLinus Torvalds    }
17531da177e4SLinus Torvalds    elsif ($x =~ /([^\{]*)/) {
17541da177e4SLinus Torvalds	$prototype .= $1;
17551da177e4SLinus Torvalds    }
1756b4870bc5SRandy Dunlap
1757890c78c2SRandy Dunlap    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
17581da177e4SLinus Torvalds	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
17591da177e4SLinus Torvalds	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
17601da177e4SLinus Torvalds	$prototype =~ s@^\s+@@gos; # strip leading spaces
1761b4870bc5SRandy Dunlap	if ($prototype =~ /SYSCALL_DEFINE/) {
1762b4870bc5SRandy Dunlap		syscall_munge();
1763b4870bc5SRandy Dunlap	}
17643a9089fdSJason Baron	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
17653a9089fdSJason Baron	    $prototype =~ /DEFINE_SINGLE_EVENT/)
17663a9089fdSJason Baron	{
176756afb0f8SJason Baron		tracepoint_munge($file);
176856afb0f8SJason Baron	}
17691da177e4SLinus Torvalds	dump_function($prototype, $file);
17701da177e4SLinus Torvalds	reset_state();
17711da177e4SLinus Torvalds    }
17721da177e4SLinus Torvalds}
17731da177e4SLinus Torvalds
1774b7afa92bSDaniel Vettersub process_proto_type($$) {
17751da177e4SLinus Torvalds    my $x = shift;
17761da177e4SLinus Torvalds    my $file = shift;
17771da177e4SLinus Torvalds
17781da177e4SLinus Torvalds    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
17791da177e4SLinus Torvalds    $x =~ s@^\s+@@gos; # strip leading spaces
17801da177e4SLinus Torvalds    $x =~ s@\s+$@@gos; # strip trailing spaces
178151f5a0c8SRandy Dunlap    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
178251f5a0c8SRandy Dunlap
17831da177e4SLinus Torvalds    if ($x =~ /^#/) {
17841da177e4SLinus Torvalds	# To distinguish preprocessor directive from regular declaration later.
17851da177e4SLinus Torvalds	$x .= ";";
17861da177e4SLinus Torvalds    }
17871da177e4SLinus Torvalds
17881da177e4SLinus Torvalds    while (1) {
1789673bb2dfSBen Hutchings	if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
1790463a0fdcSMarkus Heiser            if( length $prototype ) {
1791463a0fdcSMarkus Heiser                $prototype .= " "
1792463a0fdcSMarkus Heiser            }
17931da177e4SLinus Torvalds	    $prototype .= $1 . $2;
17941da177e4SLinus Torvalds	    ($2 eq '{') && $brcount++;
17951da177e4SLinus Torvalds	    ($2 eq '}') && $brcount--;
17961da177e4SLinus Torvalds	    if (($2 eq ';') && ($brcount == 0)) {
17971da177e4SLinus Torvalds		dump_declaration($prototype, $file);
17981da177e4SLinus Torvalds		reset_state();
17991da177e4SLinus Torvalds		last;
18001da177e4SLinus Torvalds	    }
18011da177e4SLinus Torvalds	    $x = $3;
18021da177e4SLinus Torvalds	} else {
18031da177e4SLinus Torvalds	    $prototype .= $x;
18041da177e4SLinus Torvalds	    last;
18051da177e4SLinus Torvalds	}
18061da177e4SLinus Torvalds    }
18071da177e4SLinus Torvalds}
18081da177e4SLinus Torvalds
18096b5b55f6SRandy Dunlap
18101ad560e4SJani Nikulasub map_filename($) {
18111ad560e4SJani Nikula    my $file;
18121ad560e4SJani Nikula    my ($orig_file) = @_;
18131ad560e4SJani Nikula
18141ad560e4SJani Nikula    if (defined($ENV{'SRCTREE'})) {
18151ad560e4SJani Nikula	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
18161ad560e4SJani Nikula    } else {
18171ad560e4SJani Nikula	$file = $orig_file;
18181ad560e4SJani Nikula    }
18191ad560e4SJani Nikula
18201ad560e4SJani Nikula    if (defined($source_map{$file})) {
18211ad560e4SJani Nikula	$file = $source_map{$file};
18221ad560e4SJani Nikula    }
18231ad560e4SJani Nikula
18241ad560e4SJani Nikula    return $file;
18251ad560e4SJani Nikula}
18261ad560e4SJani Nikula
182788c2b57dSJani Nikulasub process_export_file($) {
182888c2b57dSJani Nikula    my ($orig_file) = @_;
182988c2b57dSJani Nikula    my $file = map_filename($orig_file);
183088c2b57dSJani Nikula
183188c2b57dSJani Nikula    if (!open(IN,"<$file")) {
183288c2b57dSJani Nikula	print STDERR "Error: Cannot open file $file\n";
183388c2b57dSJani Nikula	++$errors;
183488c2b57dSJani Nikula	return;
183588c2b57dSJani Nikula    }
183688c2b57dSJani Nikula
183788c2b57dSJani Nikula    while (<IN>) {
183888c2b57dSJani Nikula	if (/$export_symbol/) {
183988c2b57dSJani Nikula	    $function_table{$2} = 1;
184088c2b57dSJani Nikula	}
184188c2b57dSJani Nikula    }
184288c2b57dSJani Nikula
184388c2b57dSJani Nikula    close(IN);
184488c2b57dSJani Nikula}
184588c2b57dSJani Nikula
184607048d13SJonathan Corbet#
184707048d13SJonathan Corbet# Parsers for the various processing states.
184807048d13SJonathan Corbet#
184907048d13SJonathan Corbet# STATE_NORMAL: looking for the /** to begin everything.
185007048d13SJonathan Corbet#
185107048d13SJonathan Corbetsub process_normal() {
18521da177e4SLinus Torvalds    if (/$doc_start/o) {
185348af606aSJani Nikula	$state = STATE_NAME;	# next line is always the function name
1854850622dfSRandy Dunlap	$in_doc_sect = 0;
18550b0f5f29SDaniel Vetter	$declaration_start_line = $. + 1;
18561da177e4SLinus Torvalds    }
185707048d13SJonathan Corbet}
185807048d13SJonathan Corbet
18593cac2bc4SJonathan Corbet#
18603cac2bc4SJonathan Corbet# STATE_NAME: Looking for the "name - description" line
18613cac2bc4SJonathan Corbet#
18623cac2bc4SJonathan Corbetsub process_name($$) {
18633cac2bc4SJonathan Corbet    my $file = shift;
18641da177e4SLinus Torvalds    my $identifier;
18651da177e4SLinus Torvalds    my $descr;
18661da177e4SLinus Torvalds
18671da177e4SLinus Torvalds    if (/$doc_block/o) {
186848af606aSJani Nikula	$state = STATE_DOCBLOCK;
18691da177e4SLinus Torvalds	$contents = "";
18700b0f5f29SDaniel Vetter	$new_start_line = $. + 1;
18710b0f5f29SDaniel Vetter
18721da177e4SLinus Torvalds	if ( $1 eq "" ) {
18731da177e4SLinus Torvalds	    $section = $section_intro;
18741da177e4SLinus Torvalds	} else {
18751da177e4SLinus Torvalds	    $section = $1;
18761da177e4SLinus Torvalds	}
18771da177e4SLinus Torvalds    }
18781da177e4SLinus Torvalds    elsif (/$doc_decl/o) {
18791da177e4SLinus Torvalds	$identifier = $1;
1880a8dae20bSMike Rapoport	if (/\s*([\w\s]+?)(\(\))?\s*-/) {
18811da177e4SLinus Torvalds	    $identifier = $1;
18821da177e4SLinus Torvalds	}
18831da177e4SLinus Torvalds
188417b78717SJonathan Corbet	$state = STATE_BODY;
18850b0f5f29SDaniel Vetter	# if there's no @param blocks need to set up default section
18860b0f5f29SDaniel Vetter	# here
18872f4ad40aSJani Nikula	$contents = "";
18882f4ad40aSJani Nikula	$section = $section_default;
18890b0f5f29SDaniel Vetter	$new_start_line = $. + 1;
18901da177e4SLinus Torvalds	if (/-(.*)/) {
189151f5a0c8SRandy Dunlap	    # strip leading/trailing/multiple spaces
1892a21217daSRandy Dunlap	    $descr= $1;
1893a21217daSRandy Dunlap	    $descr =~ s/^\s*//;
1894a21217daSRandy Dunlap	    $descr =~ s/\s*$//;
189512ae6779SDaniel Santos	    $descr =~ s/\s+/ /g;
18960bba924cSJonathan Corbet	    $declaration_purpose = $descr;
189717b78717SJonathan Corbet	    $state = STATE_BODY_MAYBE;
18981da177e4SLinus Torvalds	} else {
18991da177e4SLinus Torvalds	    $declaration_purpose = "";
19001da177e4SLinus Torvalds	}
190177cc23b8SRandy Dunlap
190277cc23b8SRandy Dunlap	if (($declaration_purpose eq "") && $verbose) {
1903d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: missing initial short description on line:\n";
190477cc23b8SRandy Dunlap	    print STDERR $_;
190577cc23b8SRandy Dunlap	    ++$warnings;
190677cc23b8SRandy Dunlap	}
190777cc23b8SRandy Dunlap
1908cf419d54SRandy Dunlap	if ($identifier =~ m/^struct\b/) {
19091da177e4SLinus Torvalds	    $decl_type = 'struct';
1910cf419d54SRandy Dunlap	} elsif ($identifier =~ m/^union\b/) {
19111da177e4SLinus Torvalds	    $decl_type = 'union';
1912cf419d54SRandy Dunlap	} elsif ($identifier =~ m/^enum\b/) {
19131da177e4SLinus Torvalds	    $decl_type = 'enum';
1914cf419d54SRandy Dunlap	} elsif ($identifier =~ m/^typedef\b/) {
19151da177e4SLinus Torvalds	    $decl_type = 'typedef';
19161da177e4SLinus Torvalds	} else {
19171da177e4SLinus Torvalds	    $decl_type = 'function';
19181da177e4SLinus Torvalds	}
19191da177e4SLinus Torvalds
19201da177e4SLinus Torvalds	if ($verbose) {
1921d40e1e65SBart Van Assche	    print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
19221da177e4SLinus Torvalds	}
19231da177e4SLinus Torvalds    } else {
1924d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
19251da177e4SLinus Torvalds	    " - I thought it was a doc line\n";
19261da177e4SLinus Torvalds	++$warnings;
192748af606aSJani Nikula	$state = STATE_NORMAL;
19281da177e4SLinus Torvalds    }
19293cac2bc4SJonathan Corbet}
19303cac2bc4SJonathan Corbet
19313cac2bc4SJonathan Corbet
1932d742f24dSJonathan Corbet#
1933d742f24dSJonathan Corbet# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
1934d742f24dSJonathan Corbet#
1935d742f24dSJonathan Corbetsub process_body($$) {
1936d742f24dSJonathan Corbet    my $file = shift;
19373cac2bc4SJonathan Corbet
1938f624adefSJani Nikula    if (/$doc_sect/i) { # case insensitive for supported section names
19391da177e4SLinus Torvalds	$newsection = $1;
19401da177e4SLinus Torvalds	$newcontents = $2;
19411da177e4SLinus Torvalds
1942f624adefSJani Nikula	# map the supported section names to the canonical names
1943f624adefSJani Nikula	if ($newsection =~ m/^description$/i) {
1944f624adefSJani Nikula	    $newsection = $section_default;
1945f624adefSJani Nikula	} elsif ($newsection =~ m/^context$/i) {
1946f624adefSJani Nikula	    $newsection = $section_context;
1947f624adefSJani Nikula	} elsif ($newsection =~ m/^returns?$/i) {
1948f624adefSJani Nikula	    $newsection = $section_return;
1949f624adefSJani Nikula	} elsif ($newsection =~ m/^\@return$/) {
1950f624adefSJani Nikula	    # special: @return is a section, not a param description
1951f624adefSJani Nikula	    $newsection = $section_return;
1952f624adefSJani Nikula	}
1953f624adefSJani Nikula
1954792aa2f2SRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
1955850622dfSRandy Dunlap	    if (!$in_doc_sect && $verbose) {
1956d40e1e65SBart Van Assche		print STDERR "${file}:$.: warning: contents before sections\n";
1957850622dfSRandy Dunlap		++$warnings;
1958850622dfSRandy Dunlap	    }
19590bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
19601da177e4SLinus Torvalds	    $section = $section_default;
19611da177e4SLinus Torvalds	}
19621da177e4SLinus Torvalds
1963850622dfSRandy Dunlap	$in_doc_sect = 1;
196417b78717SJonathan Corbet	$state = STATE_BODY;
19651da177e4SLinus Torvalds	$contents = $newcontents;
19660b0f5f29SDaniel Vetter	$new_start_line = $.;
19677c9aa015SMauro Carvalho Chehab	while (substr($contents, 0, 1) eq " ") {
196805189497SRandy Dunlap	    $contents = substr($contents, 1);
196905189497SRandy Dunlap	}
19700a726301SJani Nikula	if ($contents ne "") {
19711da177e4SLinus Torvalds	    $contents .= "\n";
19721da177e4SLinus Torvalds	}
19731da177e4SLinus Torvalds	$section = $newsection;
1974b7886de4SJani Nikula	$leading_space = undef;
19751da177e4SLinus Torvalds    } elsif (/$doc_end/) {
19764c98ecafSRandy Dunlap	if (($contents ne "") && ($contents ne "\n")) {
19770bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
19781da177e4SLinus Torvalds	    $section = $section_default;
19791da177e4SLinus Torvalds	    $contents = "";
19801da177e4SLinus Torvalds	}
198146b958ebSRandy Dunlap	# look for doc_com + <text> + doc_end:
198246b958ebSRandy Dunlap	if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1983d40e1e65SBart Van Assche	    print STDERR "${file}:$.: warning: suspicious ending line: $_";
198446b958ebSRandy Dunlap	    ++$warnings;
198546b958ebSRandy Dunlap	}
19861da177e4SLinus Torvalds
19871da177e4SLinus Torvalds	$prototype = "";
198848af606aSJani Nikula	$state = STATE_PROTO;
19891da177e4SLinus Torvalds	$brcount = 0;
19901da177e4SLinus Torvalds    } elsif (/$doc_content/) {
19911da177e4SLinus Torvalds	# miguel-style comment kludge, look for blank lines after
19921da177e4SLinus Torvalds	# @parameter line to signify start of description
19936423133bSJohannes Weiner	if ($1 eq "") {
19946423133bSJohannes Weiner	    if ($section =~ m/^@/ || $section eq $section_context) {
19950bba924cSJonathan Corbet		dump_section($file, $section, $contents);
19961da177e4SLinus Torvalds		$section = $section_default;
19971da177e4SLinus Torvalds		$contents = "";
19980b0f5f29SDaniel Vetter		$new_start_line = $.;
19991da177e4SLinus Torvalds	    } else {
20006423133bSJohannes Weiner		$contents .= "\n";
20016423133bSJohannes Weiner	    }
200217b78717SJonathan Corbet	    $state = STATE_BODY;
200317b78717SJonathan Corbet	} elsif ($state == STATE_BODY_MAYBE) {
20046423133bSJohannes Weiner	    # Continued declaration purpose
20056423133bSJohannes Weiner	    chomp($declaration_purpose);
20060bba924cSJonathan Corbet	    $declaration_purpose .= " " . $1;
200712ae6779SDaniel Santos	    $declaration_purpose =~ s/\s+/ /g;
20086423133bSJohannes Weiner	} else {
2009b7886de4SJani Nikula	    my $cont = $1;
2010b7886de4SJani Nikula	    if ($section =~ m/^@/ || $section eq $section_context) {
2011b7886de4SJani Nikula		if (!defined $leading_space) {
2012b7886de4SJani Nikula		    if ($cont =~ m/^(\s+)/) {
2013b7886de4SJani Nikula			$leading_space = $1;
2014b7886de4SJani Nikula		    } else {
2015b7886de4SJani Nikula			$leading_space = "";
2016b7886de4SJani Nikula		    }
2017b7886de4SJani Nikula		}
2018b7886de4SJani Nikula		$cont =~ s/^$leading_space//;
2019b7886de4SJani Nikula	    }
2020b7886de4SJani Nikula	    $contents .= $cont . "\n";
20211da177e4SLinus Torvalds	}
20221da177e4SLinus Torvalds    } else {
20231da177e4SLinus Torvalds	# i dont know - bad line?  ignore.
2024d40e1e65SBart Van Assche	print STDERR "${file}:$.: warning: bad line: $_";
20251da177e4SLinus Torvalds	++$warnings;
20261da177e4SLinus Torvalds    }
2027d742f24dSJonathan Corbet}
2028d742f24dSJonathan Corbet
2029d742f24dSJonathan Corbet
2030cc794812SJonathan Corbet#
2031cc794812SJonathan Corbet# STATE_PROTO: reading a function/whatever prototype.
2032cc794812SJonathan Corbet#
2033cc794812SJonathan Corbetsub process_proto($$) {
2034cc794812SJonathan Corbet    my $file = shift;
2035cc794812SJonathan Corbet
2036cc794812SJonathan Corbet    if (/$doc_inline_oneline/) {
2037cc794812SJonathan Corbet	$section = $1;
2038cc794812SJonathan Corbet	$contents = $2;
2039cc794812SJonathan Corbet	if ($contents ne "") {
2040cc794812SJonathan Corbet	    $contents .= "\n";
2041cc794812SJonathan Corbet	    dump_section($file, $section, $contents);
2042cc794812SJonathan Corbet	    $section = $section_default;
2043cc794812SJonathan Corbet	    $contents = "";
2044cc794812SJonathan Corbet	}
2045cc794812SJonathan Corbet    } elsif (/$doc_inline_start/) {
2046cc794812SJonathan Corbet	$state = STATE_INLINE;
2047cc794812SJonathan Corbet	$inline_doc_state = STATE_INLINE_NAME;
2048cc794812SJonathan Corbet    } elsif ($decl_type eq 'function') {
2049cc794812SJonathan Corbet	process_proto_function($_, $file);
2050cc794812SJonathan Corbet    } else {
2051cc794812SJonathan Corbet	process_proto_type($_, $file);
2052cc794812SJonathan Corbet    }
2053cc794812SJonathan Corbet}
2054cc794812SJonathan Corbet
2055c17add56SJonathan Corbet#
2056c17add56SJonathan Corbet# STATE_DOCBLOCK: within a DOC: block.
2057c17add56SJonathan Corbet#
2058c17add56SJonathan Corbetsub process_docblock($$) {
2059c17add56SJonathan Corbet    my $file = shift;
2060cc794812SJonathan Corbet
2061c17add56SJonathan Corbet    if (/$doc_end/) {
2062c17add56SJonathan Corbet	dump_doc_section($file, $section, $contents);
2063c17add56SJonathan Corbet	$section = $section_default;
2064c17add56SJonathan Corbet	$contents = "";
2065c17add56SJonathan Corbet	$function = "";
2066c17add56SJonathan Corbet	%parameterdescs = ();
2067c17add56SJonathan Corbet	%parametertypes = ();
2068c17add56SJonathan Corbet	@parameterlist = ();
2069c17add56SJonathan Corbet	%sections = ();
2070c17add56SJonathan Corbet	@sectionlist = ();
2071c17add56SJonathan Corbet	$prototype = "";
2072c17add56SJonathan Corbet	$state = STATE_NORMAL;
2073c17add56SJonathan Corbet    } elsif (/$doc_content/) {
2074c17add56SJonathan Corbet	if ( $1 eq "" )	{
2075c17add56SJonathan Corbet	    $contents .= $blankline;
2076c17add56SJonathan Corbet	} else {
2077c17add56SJonathan Corbet	    $contents .= $1 . "\n";
2078c17add56SJonathan Corbet	}
2079c17add56SJonathan Corbet    }
2080d742f24dSJonathan Corbet}
2081d742f24dSJonathan Corbet
2082c17add56SJonathan Corbet#
2083c17add56SJonathan Corbet# STATE_INLINE: docbook comments within a prototype.
2084c17add56SJonathan Corbet#
2085c17add56SJonathan Corbetsub process_inline($$) {
2086c17add56SJonathan Corbet    my $file = shift;
2087d742f24dSJonathan Corbet
2088a4c6ebedSDanilo Cesar Lemes de Paula    # First line (state 1) needs to be a @parameter
208948af606aSJani Nikula    if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2090a4c6ebedSDanilo Cesar Lemes de Paula	$section = $1;
2091a4c6ebedSDanilo Cesar Lemes de Paula	$contents = $2;
20920b0f5f29SDaniel Vetter	$new_start_line = $.;
2093a4c6ebedSDanilo Cesar Lemes de Paula	if ($contents ne "") {
20947c9aa015SMauro Carvalho Chehab	    while (substr($contents, 0, 1) eq " ") {
2095a4c6ebedSDanilo Cesar Lemes de Paula		$contents = substr($contents, 1);
2096a4c6ebedSDanilo Cesar Lemes de Paula	    }
2097a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= "\n";
2098a4c6ebedSDanilo Cesar Lemes de Paula	}
209948af606aSJani Nikula	$inline_doc_state = STATE_INLINE_TEXT;
2100a4c6ebedSDanilo Cesar Lemes de Paula	# Documentation block end */
210148af606aSJani Nikula    } elsif (/$doc_inline_end/) {
2102a4c6ebedSDanilo Cesar Lemes de Paula	if (($contents ne "") && ($contents ne "\n")) {
21030bba924cSJonathan Corbet	    dump_section($file, $section, $contents);
2104a4c6ebedSDanilo Cesar Lemes de Paula	    $section = $section_default;
2105a4c6ebedSDanilo Cesar Lemes de Paula	    $contents = "";
2106a4c6ebedSDanilo Cesar Lemes de Paula	}
210748af606aSJani Nikula	$state = STATE_PROTO;
210848af606aSJani Nikula	$inline_doc_state = STATE_INLINE_NA;
2109a4c6ebedSDanilo Cesar Lemes de Paula	# Regular text
2110a4c6ebedSDanilo Cesar Lemes de Paula    } elsif (/$doc_content/) {
211148af606aSJani Nikula	if ($inline_doc_state == STATE_INLINE_TEXT) {
2112a4c6ebedSDanilo Cesar Lemes de Paula	    $contents .= $1 . "\n";
21136450c895SJani Nikula	    # nuke leading blank lines
21146450c895SJani Nikula	    if ($contents =~ /^\s*$/) {
21156450c895SJani Nikula		$contents = "";
21166450c895SJani Nikula	    }
211748af606aSJani Nikula	} elsif ($inline_doc_state == STATE_INLINE_NAME) {
211848af606aSJani Nikula	    $inline_doc_state = STATE_INLINE_ERROR;
2119e7ca311eSDaniel Vetter	    print STDERR "${file}:$.: warning: ";
2120a4c6ebedSDanilo Cesar Lemes de Paula	    print STDERR "Incorrect use of kernel-doc format: $_";
2121a4c6ebedSDanilo Cesar Lemes de Paula	    ++$warnings;
2122a4c6ebedSDanilo Cesar Lemes de Paula	}
2123a4c6ebedSDanilo Cesar Lemes de Paula    }
21240c9aa209SJani Nikula}
2125c17add56SJonathan Corbet
2126c17add56SJonathan Corbet
2127c17add56SJonathan Corbetsub process_file($) {
2128c17add56SJonathan Corbet    my $file;
2129c17add56SJonathan Corbet    my $initial_section_counter = $section_counter;
2130c17add56SJonathan Corbet    my ($orig_file) = @_;
2131c17add56SJonathan Corbet
2132c17add56SJonathan Corbet    $file = map_filename($orig_file);
2133c17add56SJonathan Corbet
2134c17add56SJonathan Corbet    if (!open(IN,"<$file")) {
2135c17add56SJonathan Corbet	print STDERR "Error: Cannot open file $file\n";
2136c17add56SJonathan Corbet	++$errors;
2137c17add56SJonathan Corbet	return;
21381da177e4SLinus Torvalds    }
2139c17add56SJonathan Corbet
2140c17add56SJonathan Corbet    $. = 1;
2141c17add56SJonathan Corbet
2142c17add56SJonathan Corbet    $section_counter = 0;
2143c17add56SJonathan Corbet    while (<IN>) {
2144c17add56SJonathan Corbet	while (s/\\\s*$//) {
2145c17add56SJonathan Corbet	    $_ .= <IN>;
2146c17add56SJonathan Corbet	}
2147c17add56SJonathan Corbet	# Replace tabs by spaces
2148c17add56SJonathan Corbet        while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2149c17add56SJonathan Corbet	# Hand this line to the appropriate state handler
2150c17add56SJonathan Corbet	if ($state == STATE_NORMAL) {
2151c17add56SJonathan Corbet	    process_normal();
2152c17add56SJonathan Corbet	} elsif ($state == STATE_NAME) {
2153c17add56SJonathan Corbet	    process_name($file, $_);
2154c17add56SJonathan Corbet	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
2155c17add56SJonathan Corbet	    process_body($file, $_);
2156c17add56SJonathan Corbet	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
2157c17add56SJonathan Corbet	    process_inline($file, $_);
2158cc794812SJonathan Corbet	} elsif ($state == STATE_PROTO) {
2159cc794812SJonathan Corbet	    process_proto($file, $_);
216048af606aSJani Nikula	} elsif ($state == STATE_DOCBLOCK) {
2161c17add56SJonathan Corbet	    process_docblock($file, $_);
21621da177e4SLinus Torvalds	}
21631da177e4SLinus Torvalds    }
2164c17add56SJonathan Corbet
2165c17add56SJonathan Corbet    # Make sure we got something interesting.
2166b0d60bfbSJonathan Corbet    if ($initial_section_counter == $section_counter && $
2167b0d60bfbSJonathan Corbet	output_mode ne "none") {
2168b0d60bfbSJonathan Corbet	if ($output_selection == OUTPUT_INCLUDE) {
2169b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: '$_' not found\n"
2170b0d60bfbSJonathan Corbet		for keys %function_table;
21713a025e1dSMatthew Wilcox	}
2172b0d60bfbSJonathan Corbet	else {
2173b0d60bfbSJonathan Corbet	    print STDERR "${file}:1: warning: no structured comments found\n";
2174e946c43aSJohannes Berg	}
21751da177e4SLinus Torvalds    }
21761da177e4SLinus Torvalds}
21778484baaaSRandy Dunlap
21788484baaaSRandy Dunlap
21798484baaaSRandy Dunlap$kernelversion = get_kernel_version();
21808484baaaSRandy Dunlap
21818484baaaSRandy Dunlap# generate a sequence of code that will splice in highlighting information
21828484baaaSRandy Dunlap# using the s// operator.
21831ef06233SMauro Carvalho Chehabfor (my $k = 0; $k < @highlights; $k++) {
21844d732701SDanilo Cesar Lemes de Paula    my $pattern = $highlights[$k][0];
21854d732701SDanilo Cesar Lemes de Paula    my $result = $highlights[$k][1];
21864d732701SDanilo Cesar Lemes de Paula#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
21874d732701SDanilo Cesar Lemes de Paula    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
21888484baaaSRandy Dunlap}
21898484baaaSRandy Dunlap
21908484baaaSRandy Dunlap# Read the file that maps relative names to absolute names for
21918484baaaSRandy Dunlap# separate source and object directories and for shadow trees.
21928484baaaSRandy Dunlapif (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
21938484baaaSRandy Dunlap	my ($relname, $absname);
21948484baaaSRandy Dunlap	while(<SOURCE_MAP>) {
21958484baaaSRandy Dunlap		chop();
21968484baaaSRandy Dunlap		($relname, $absname) = (split())[0..1];
21978484baaaSRandy Dunlap		$relname =~ s:^/+::;
21988484baaaSRandy Dunlap		$source_map{$relname} = $absname;
21998484baaaSRandy Dunlap	}
22008484baaaSRandy Dunlap	close(SOURCE_MAP);
22018484baaaSRandy Dunlap}
22028484baaaSRandy Dunlap
220388c2b57dSJani Nikulaif ($output_selection == OUTPUT_EXPORTED ||
220488c2b57dSJani Nikula    $output_selection == OUTPUT_INTERNAL) {
2205c9b2cfb3SJani Nikula
2206c9b2cfb3SJani Nikula    push(@export_file_list, @ARGV);
2207c9b2cfb3SJani Nikula
220888c2b57dSJani Nikula    foreach (@export_file_list) {
220988c2b57dSJani Nikula	chomp;
221088c2b57dSJani Nikula	process_export_file($_);
221188c2b57dSJani Nikula    }
221288c2b57dSJani Nikula}
221388c2b57dSJani Nikula
22148484baaaSRandy Dunlapforeach (@ARGV) {
22158484baaaSRandy Dunlap    chomp;
22168484baaaSRandy Dunlap    process_file($_);
22178484baaaSRandy Dunlap}
22188484baaaSRandy Dunlapif ($verbose && $errors) {
22198484baaaSRandy Dunlap  print STDERR "$errors errors\n";
22208484baaaSRandy Dunlap}
22218484baaaSRandy Dunlapif ($verbose && $warnings) {
22228484baaaSRandy Dunlap  print STDERR "$warnings warnings\n";
22238484baaaSRandy Dunlap}
22248484baaaSRandy Dunlap
2225e814bccbSWill Deaconexit($output_mode eq "none" ? 0 : $errors);
2226