blob: 0ad1fb0e30313be0d7ba718fa9d9aa7bb6bfedf1 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
Randy Dunlap70c95b02012-01-21 10:31:54 -08008## Copyright (C) 2005-2012 Randy Dunlap ##
Dan Luedtke1b40c192012-08-12 10:46:15 +02009## Copyright (C) 2012 Dan Luedtke ##
Linus Torvalds1da177e2005-04-16 15:20:36 -070010## ##
11## #define enhancements by Armin Kuster <akuster@mvista.com> ##
12## Copyright (c) 2000 MontaVista Software, Inc. ##
13## ##
14## This software falls under the GNU General Public License. ##
15## Please read the COPYING file for more information ##
16
Linus Torvalds1da177e2005-04-16 15:20:36 -070017# 18/01/2001 - Cleanups
18# Functions prototyped as foo(void) same as foo()
19# Stop eval'ing where we don't need to.
20# -- huggie@earth.li
21
22# 27/06/2001 - Allowed whitespace after initial "/**" and
23# allowed comments before function declarations.
24# -- Christian Kreibich <ck@whoop.org>
25
26# Still to do:
27# - add perldoc documentation
28# - Look more closely at some of the scarier bits :)
29
30# 26/05/2001 - Support for separate source and object trees.
31# Return error code.
32# Keith Owens <kaos@ocs.com.au>
33
34# 23/09/2001 - Added support for typedefs, structs, enums and unions
35# Support for Context section; can be terminated using empty line
36# Small fixes (like spaces vs. \s in regex)
37# -- Tim Jansen <tim@tjansen.de>
38
Dan Luedtke1b40c192012-08-12 10:46:15 +020039# 25/07/2012 - Added support for HTML5
40# -- Dan Luedtke <mail@danrl.de>
Linus Torvalds1da177e2005-04-16 15:20:36 -070041
Jani Nikulafadc0b32016-05-12 16:15:36 +030042sub usage {
43 my $message = <<"EOF";
44Usage: $0 [OPTION ...] FILE ...
Linus Torvalds1da177e2005-04-16 15:20:36 -070045
Jani Nikulafadc0b32016-05-12 16:15:36 +030046Read C language source or header FILEs, extract embedded documentation comments,
47and print formatted documentation to standard output.
Linus Torvalds1da177e2005-04-16 15:20:36 -070048
Jani Nikulafadc0b32016-05-12 16:15:36 +030049The documentation comments are identified by "/**" opening comment mark. See
50Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
51
52Output format selection (mutually exclusive):
53 -docbook Output DocBook format.
54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +030058 -rst Output reStructuredText format.
Jani Nikulafadc0b32016-05-12 16:15:36 +030059 -text Output plain text format.
60
61Output selection (mutually exclusive):
62 -function NAME Only output documentation for the given function(s)
63 or DOC: section title(s). All other functions and DOC:
64 sections are ignored. May be specified multiple times.
65 -nofunction NAME Do NOT output documentation for the given function(s);
66 only output documentation for the other functions and
67 DOC: sections. May be specified multiple times.
68
69Output selection modifiers:
70 -no-doc-sections Do not output DOC: sections.
71
72Other parameters:
73 -v Verbose output, more warnings and other information.
74 -h Print this help.
75
76EOF
77 print $message;
78 exit 1;
79}
Linus Torvalds1da177e2005-04-16 15:20:36 -070080
81#
82# format of comments.
83# In the following table, (...)? signifies optional structure.
84# (...)* signifies 0 or more structure elements
85# /**
86# * function_name(:)? (- short description)?
87# (* @parameterx: (description of parameter x)?)*
88# (* a blank line)?
89# * (Description:)? (Description of function)?
90# * (section header: (section description)? )*
91# (*)?*/
92#
93# So .. the trivial example would be:
94#
95# /**
96# * my_function
Randy Dunlapb9d973282009-06-09 08:50:38 -070097# */
Linus Torvalds1da177e2005-04-16 15:20:36 -070098#
Randy Dunlap891dcd22007-02-10 01:45:53 -080099# If the Description: header tag is omitted, then there must be a blank line
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100# after the last parameter specification.
101# e.g.
102# /**
103# * my_function - does my stuff
104# * @my_arg: its mine damnit
105# *
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800106# * Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700107# */
108#
109# or, could also use:
110# /**
111# * my_function - does my stuff
112# * @my_arg: its mine damnit
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800113# * Description: Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700114# */
115# etc.
116#
Randy Dunlapb9d973282009-06-09 08:50:38 -0700117# Besides functions you can also write documentation for structs, unions,
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800118# enums and typedefs. Instead of the function name you must write the name
119# of the declaration; the struct/union/enum/typedef must always precede
120# the name. Nesting of declarations is not supported.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700121# Use the argument mechanism to document members or constants.
122# e.g.
123# /**
124# * struct my_struct - short description
125# * @a: first member
126# * @b: second member
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800127# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700128# * Longer description
129# */
130# struct my_struct {
131# int a;
132# int b;
Martin Waitzaeec46b2005-11-13 16:08:13 -0800133# /* private: */
134# int c;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700135# };
136#
137# All descriptions can be multiline, except the short function description.
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800138#
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300139# For really longs structs, you can also describe arguments inside the
140# body of the struct.
141# eg.
142# /**
143# * struct my_struct - short description
144# * @a: first member
145# * @b: second member
146# *
147# * Longer description
148# */
149# struct my_struct {
150# int a;
151# int b;
152# /**
153# * @c: This is longer description of C
154# *
155# * You can use paragraphs to describe arguments
156# * using this method.
157# */
158# int c;
159# };
160#
161# This should be use only for struct/enum members.
162#
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800163# You can also add additional sections. When documenting kernel functions you
164# should document the "Context:" of the function, e.g. whether the functions
Linus Torvalds1da177e2005-04-16 15:20:36 -0700165# can be called form interrupts. Unlike other sections you can end it with an
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800166# empty line.
Yacine Belkadi4092bac2012-11-26 22:22:27 +0100167# A non-void function should have a "Return:" section describing the return
168# value(s).
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800169# Example-sections should contain the string EXAMPLE so that they are marked
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170# appropriately in DocBook.
171#
172# Example:
173# /**
174# * user_function - function that can only be called in user context
175# * @a: some argument
176# * Context: !in_interrupt()
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800177# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700178# * Some description
179# * Example:
180# * user_function(22);
181# */
182# ...
183#
184#
185# All descriptive text is further processed, scanning for the following special
186# patterns, which are highlighted appropriately.
187#
188# 'funcname()' - function
189# '$ENVVAR' - environmental variable
190# '&struct_name' - name of a structure (up to two words including 'struct')
191# '@parameter' - name of a parameter
192# '%CONST' - name of a constant.
193
Randy Dunlap8484baa2011-01-05 16:28:43 -0800194## init lots of data
195
Linus Torvalds1da177e2005-04-16 15:20:36 -0700196my $errors = 0;
197my $warnings = 0;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -0700198my $anon_struct_union = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700199
200# match expressions used to find embedded type information
201my $type_constant = '\%([-_\w]+)';
202my $type_func = '(\w+)\(\)';
203my $type_param = '\@(\w+)';
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700204my $type_struct = '\&((struct\s*)*[_\w]+)';
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700205my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700206my $type_env = '(\$\w+)';
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300207my $type_enum_full = '\&(enum)\s*([_\w]+)';
208my $type_struct_full = '\&(struct)\s*([_\w]+)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700209
210# Output conversion substitutions.
211# One for each output format
212
213# these work fairly well
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300214my @highlights_html = (
215 [$type_constant, "<i>\$1</i>"],
216 [$type_func, "<b>\$1</b>"],
217 [$type_struct_xml, "<i>\$1</i>"],
218 [$type_env, "<b><i>\$1</i></b>"],
219 [$type_param, "<tt><b>\$1</b></tt>"]
220 );
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700221my $local_lt = "\\\\\\\\lt:";
222my $local_gt = "\\\\\\\\gt:";
223my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
Linus Torvalds1da177e2005-04-16 15:20:36 -0700224
Dan Luedtke1b40c192012-08-12 10:46:15 +0200225# html version 5
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300226my @highlights_html5 = (
227 [$type_constant, "<span class=\"const\">\$1</span>"],
228 [$type_func, "<span class=\"func\">\$1</span>"],
229 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
230 [$type_env, "<span class=\"env\">\$1</span>"],
231 [$type_param, "<span class=\"param\">\$1</span>]"]
232 );
Dan Luedtke1b40c192012-08-12 10:46:15 +0200233my $blankline_html5 = $local_lt . "br /" . $local_gt;
234
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235# XML, docbook format
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300236my @highlights_xml = (
237 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
238 [$type_constant, "<constant>\$1</constant>"],
239 [$type_struct_xml, "<structname>\$1</structname>"],
240 [$type_param, "<parameter>\$1</parameter>"],
241 [$type_func, "<function>\$1</function>"],
242 [$type_env, "<envar>\$1</envar>"]
243 );
Johannes Berg5c98fc02007-10-24 15:08:48 -0700244my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700245
246# gnome, docbook format
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300247my @highlights_gnome = (
248 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
249 [$type_func, "<function>\$1</function>"],
250 [$type_struct, "<structname>\$1</structname>"],
251 [$type_env, "<envar>\$1</envar>"],
252 [$type_param, "<parameter>\$1</parameter>" ]
253 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700254my $blankline_gnome = "</para><para>\n";
255
256# these are pretty rough
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300257my @highlights_man = (
258 [$type_constant, "\$1"],
259 [$type_func, "\\\\fB\$1\\\\fP"],
260 [$type_struct, "\\\\fI\$1\\\\fP"],
261 [$type_param, "\\\\fI\$1\\\\fP"]
262 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700263my $blankline_man = "";
264
265# text-mode
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300266my @highlights_text = (
267 [$type_constant, "\$1"],
268 [$type_func, "\$1"],
269 [$type_struct, "\$1"],
270 [$type_param, "\$1"]
271 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700272my $blankline_text = "";
273
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300274# rst-mode
275my @highlights_rst = (
276 [$type_constant, "``\$1``"],
277 [$type_func, "\\:c\\:func\\:`\$1`"],
278 [$type_struct_full, "\\:ref\\:`\$1 \$2`"],
279 [$type_enum_full, "\\:ref\\:`\$1 \$2`"],
280 [$type_struct, "\\:ref\\:`struct \$1`"],
281 [$type_param, "**\$1**"]
282 );
283my $blankline_rst = "\n";
284
Johannes Bergeda603f2010-09-11 15:55:22 -0700285# list mode
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300286my @highlights_list = (
287 [$type_constant, "\$1"],
288 [$type_func, "\$1"],
289 [$type_struct, "\$1"],
290 [$type_param, "\$1"]
291 );
Johannes Bergeda603f2010-09-11 15:55:22 -0700292my $blankline_list = "";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700293
Linus Torvalds1da177e2005-04-16 15:20:36 -0700294# read arguments
Randy Dunlapb9d973282009-06-09 08:50:38 -0700295if ($#ARGV == -1) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700296 usage();
297}
298
Randy Dunlap8484baa2011-01-05 16:28:43 -0800299my $kernelversion;
300my $dohighlight = "";
301
Linus Torvalds1da177e2005-04-16 15:20:36 -0700302my $verbose = 0;
303my $output_mode = "man";
Daniel Santose314ba32012-10-04 17:15:08 -0700304my $output_preformatted = 0;
Johannes Berg4b445952007-10-24 15:08:48 -0700305my $no_doc_sections = 0;
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300306my @highlights = @highlights_man;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700307my $blankline = $blankline_man;
308my $modulename = "Kernel API";
309my $function_only = 0;
Ben Hutchingsb2c41052015-07-08 20:07:16 +0100310my $show_not_found = 0;
311
312my @build_time;
313if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
314 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
315 @build_time = gmtime($seconds);
316} else {
317 @build_time = localtime;
318}
319
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800320my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
321 'July', 'August', 'September', 'October',
Ben Hutchingsb2c41052015-07-08 20:07:16 +0100322 'November', 'December')[$build_time[4]] .
323 " " . ($build_time[5]+1900);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700324
Randy Dunlap8484baa2011-01-05 16:28:43 -0800325# Essentially these are globals.
Randy Dunlapb9d973282009-06-09 08:50:38 -0700326# They probably want to be tidied up, made more localised or something.
327# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
Linus Torvalds1da177e2005-04-16 15:20:36 -0700328# could cause "use of undefined value" or other bugs.
Randy Dunlapb9d973282009-06-09 08:50:38 -0700329my ($function, %function_table, %parametertypes, $declaration_purpose);
330my ($type, $declaration_name, $return_type);
Ilya Dryomov1c32fd02010-02-26 13:06:03 -0800331my ($newsection, $newcontents, $prototype, $brcount, %source_map);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700332
Randy Dunlapbd0e88e2008-03-13 12:32:43 -0700333if (defined($ENV{'KBUILD_VERBOSE'})) {
334 $verbose = "$ENV{'KBUILD_VERBOSE'}";
335}
336
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800337# Generated docbook code is inserted in a template at a point where
Linus Torvalds1da177e2005-04-16 15:20:36 -0700338# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
339# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
340# We keep track of number of generated entries and generate a dummy
341# if needs be to ensure the expanded template can be postprocessed
342# into html.
343my $section_counter = 0;
344
345my $lineprefix="";
346
347# states
348# 0 - normal code
349# 1 - looking for function name
350# 2 - scanning field start.
351# 3 - scanning prototype.
352# 4 - documentation block
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300353# 5 - gathering documentation outside main block
Linus Torvalds1da177e2005-04-16 15:20:36 -0700354my $state;
Randy Dunlap850622d2006-06-25 05:48:55 -0700355my $in_doc_sect;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700356
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300357# Split Doc State
358# 0 - Invalid (Before start or after finish)
359# 1 - Is started (the /** was found inside a struct)
360# 2 - The @parameter header was found, start accepting multi paragraph text.
361# 3 - Finished (the */ was found)
362# 4 - Error - Comment without header was found. Spit a warning as it's not
363# proper kernel-doc and ignore the rest.
364my $split_doc_state;
365
Linus Torvalds1da177e2005-04-16 15:20:36 -0700366#declaration types: can be
367# 'function', 'struct', 'union', 'enum', 'typedef'
368my $decl_type;
369
370my $doc_special = "\@\%\$\&";
371
372my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
373my $doc_end = '\*/';
374my $doc_com = '\s*\*\s*';
Daniel Santos12ae6772012-10-04 17:15:10 -0700375my $doc_com_body = '\s*\* ?';
Randy Dunlapb9d973282009-06-09 08:50:38 -0700376my $doc_decl = $doc_com . '(\w+)';
377my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
Daniel Santos12ae6772012-10-04 17:15:10 -0700378my $doc_content = $doc_com_body . '(.*)';
Randy Dunlapb9d973282009-06-09 08:50:38 -0700379my $doc_block = $doc_com . 'DOC:\s*(.*)?';
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300380my $doc_split_start = '^\s*/\*\*\s*$';
381my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
382my $doc_split_end = '^\s*\*/\s*$';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700383
384my %constants;
385my %parameterdescs;
386my @parameterlist;
387my %sections;
388my @sectionlist;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800389my $sectcheck;
390my $struct_actual;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700391
392my $contents = "";
393my $section_default = "Description"; # default section
394my $section_intro = "Introduction";
395my $section = $section_default;
396my $section_context = "Context";
Yacine Belkadi4092bac2012-11-26 22:22:27 +0100397my $section_return = "Return";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700398
399my $undescribed = "-- undescribed --";
400
401reset_state();
402
403while ($ARGV[0] =~ m/^-(.*)/) {
404 my $cmd = shift @ARGV;
405 if ($cmd eq "-html") {
406 $output_mode = "html";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300407 @highlights = @highlights_html;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700408 $blankline = $blankline_html;
Dan Luedtke1b40c192012-08-12 10:46:15 +0200409 } elsif ($cmd eq "-html5") {
410 $output_mode = "html5";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300411 @highlights = @highlights_html5;
Dan Luedtke1b40c192012-08-12 10:46:15 +0200412 $blankline = $blankline_html5;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700413 } elsif ($cmd eq "-man") {
414 $output_mode = "man";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300415 @highlights = @highlights_man;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700416 $blankline = $blankline_man;
417 } elsif ($cmd eq "-text") {
418 $output_mode = "text";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300419 @highlights = @highlights_text;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700420 $blankline = $blankline_text;
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300421 } elsif ($cmd eq "-rst") {
422 $output_mode = "rst";
423 @highlights = @highlights_rst;
424 $blankline = $blankline_rst;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700425 } elsif ($cmd eq "-docbook") {
426 $output_mode = "xml";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300427 @highlights = @highlights_xml;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700428 $blankline = $blankline_xml;
Johannes Bergeda603f2010-09-11 15:55:22 -0700429 } elsif ($cmd eq "-list") {
430 $output_mode = "list";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300431 @highlights = @highlights_list;
Johannes Bergeda603f2010-09-11 15:55:22 -0700432 $blankline = $blankline_list;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700433 } elsif ($cmd eq "-gnome") {
434 $output_mode = "gnome";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300435 @highlights = @highlights_gnome;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700436 $blankline = $blankline_gnome;
437 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
438 $modulename = shift @ARGV;
439 } elsif ($cmd eq "-function") { # to only output specific functions
440 $function_only = 1;
441 $function = shift @ARGV;
442 $function_table{$function} = 1;
443 } elsif ($cmd eq "-nofunction") { # to only output specific functions
444 $function_only = 2;
445 $function = shift @ARGV;
446 $function_table{$function} = 1;
447 } elsif ($cmd eq "-v") {
448 $verbose = 1;
449 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
450 usage();
Johannes Berg4b445952007-10-24 15:08:48 -0700451 } elsif ($cmd eq '-no-doc-sections') {
452 $no_doc_sections = 1;
Johannes Berge946c43a2013-11-12 15:11:12 -0800453 } elsif ($cmd eq '-show-not-found') {
454 $show_not_found = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700455 }
456}
457
Randy Dunlap8484baa2011-01-05 16:28:43 -0800458# continue execution near EOF;
459
Borislav Petkov53f049f2007-05-08 00:30:54 -0700460# get kernel version from env
461sub get_kernel_version() {
Johannes Berg1b9bc222007-10-24 15:08:48 -0700462 my $version = 'unknown kernel version';
Borislav Petkov53f049f2007-05-08 00:30:54 -0700463
464 if (defined($ENV{'KERNELVERSION'})) {
465 $version = $ENV{'KERNELVERSION'};
466 }
467 return $version;
468}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700469
470##
471# dumps section contents to arrays/hashes intended for that purpose.
472#
473sub dump_section {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700474 my $file = shift;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700475 my $name = shift;
476 my $contents = join "\n", @_;
477
478 if ($name =~ m/$type_constant/) {
479 $name = $1;
480# print STDERR "constant section '$1' = '$contents'\n";
481 $constants{$name} = $contents;
482 } elsif ($name =~ m/$type_param/) {
483# print STDERR "parameter def '$1' = '$contents'\n";
484 $name = $1;
485 $parameterdescs{$name} = $contents;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800486 $sectcheck = $sectcheck . $name . " ";
Randy Dunlapced69092008-12-01 13:14:03 -0800487 } elsif ($name eq "@\.\.\.") {
488# print STDERR "parameter def '...' = '$contents'\n";
489 $name = "...";
490 $parameterdescs{$name} = $contents;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800491 $sectcheck = $sectcheck . $name . " ";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700492 } else {
493# print STDERR "other section '$name' = '$contents'\n";
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700494 if (defined($sections{$name}) && ($sections{$name} ne "")) {
Bart Van Assched40e1e62015-09-04 15:43:21 -0700495 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700496 ++$errors;
497 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700498 $sections{$name} = $contents;
499 push @sectionlist, $name;
500 }
501}
502
503##
Johannes Bergb112e0f2007-10-24 15:08:48 -0700504# dump DOC: section after checking that it should go out
505#
506sub dump_doc_section {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700507 my $file = shift;
Johannes Bergb112e0f2007-10-24 15:08:48 -0700508 my $name = shift;
509 my $contents = join "\n", @_;
510
Johannes Berg4b445952007-10-24 15:08:48 -0700511 if ($no_doc_sections) {
512 return;
513 }
514
Johannes Bergb112e0f2007-10-24 15:08:48 -0700515 if (($function_only == 0) ||
516 ( $function_only == 1 && defined($function_table{$name})) ||
517 ( $function_only == 2 && !defined($function_table{$name})))
518 {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700519 dump_section($file, $name, $contents);
Johannes Bergb112e0f2007-10-24 15:08:48 -0700520 output_blockhead({'sectionlist' => \@sectionlist,
521 'sections' => \%sections,
522 'module' => $modulename,
523 'content-only' => ($function_only != 0), });
524 }
525}
526
527##
Linus Torvalds1da177e2005-04-16 15:20:36 -0700528# output function
529#
530# parameterdescs, a hash.
531# function => "function name"
532# parameterlist => @list of parameters
533# parameterdescs => %parameter descriptions
534# sectionlist => @list of sections
Randy Dunlapa21217d2007-02-10 01:46:04 -0800535# sections => %section descriptions
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800536#
Linus Torvalds1da177e2005-04-16 15:20:36 -0700537
538sub output_highlight {
539 my $contents = join "\n",@_;
540 my $line;
541
542# DEBUG
543# if (!defined $contents) {
544# use Carp;
545# confess "output_highlight got called with no args?\n";
546# }
547
Dan Luedtke1b40c192012-08-12 10:46:15 +0200548 if ($output_mode eq "html" || $output_mode eq "html5" ||
549 $output_mode eq "xml") {
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700550 $contents = local_unescape($contents);
551 # convert data read & converted thru xml_escape() into &xyz; format:
Randy Dunlap2b35f4d2010-11-18 12:27:31 -0800552 $contents =~ s/\\\\\\/\&/g;
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700553 }
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700554# print STDERR "contents b4:$contents\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700555 eval $dohighlight;
556 die $@ if $@;
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700557# print STDERR "contents af:$contents\n";
558
Dan Luedtke1b40c192012-08-12 10:46:15 +0200559# strip whitespaces when generating html5
560 if ($output_mode eq "html5") {
561 $contents =~ s/^\s+//;
562 $contents =~ s/\s+$//;
563 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700564 foreach $line (split "\n", $contents) {
Daniel Santos12ae6772012-10-04 17:15:10 -0700565 if (! $output_preformatted) {
566 $line =~ s/^\s*//;
567 }
Randy Dunlap3c308792007-05-08 00:24:39 -0700568 if ($line eq ""){
Daniel Santose314ba32012-10-04 17:15:08 -0700569 if (! $output_preformatted) {
570 print $lineprefix, local_unescape($blankline);
571 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700572 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -0700573 $line =~ s/\\\\\\/\&/g;
Randy Dunlapcdccb312007-07-19 01:48:25 -0700574 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
575 print "\\&$line";
576 } else {
577 print $lineprefix, $line;
578 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700579 }
580 print "\n";
581 }
582}
583
Dan Luedtke1b40c192012-08-12 10:46:15 +0200584# output sections in html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700585sub output_section_html(%) {
586 my %args = %{$_[0]};
587 my $section;
588
589 foreach $section (@{$args{'sectionlist'}}) {
590 print "<h3>$section</h3>\n";
591 print "<blockquote>\n";
592 output_highlight($args{'sections'}{$section});
593 print "</blockquote>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800594 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700595}
596
597# output enum in html
598sub output_enum_html(%) {
599 my %args = %{$_[0]};
600 my ($parameter);
601 my $count;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700602 print "<h2>enum " . $args{'enum'} . "</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700603
Randy Dunlapb9d973282009-06-09 08:50:38 -0700604 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700605 $count = 0;
606 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700607 print " <b>" . $parameter . "</b>";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700608 if ($count != $#{$args{'parameterlist'}}) {
609 $count++;
610 print ",\n";
611 }
612 print "<br>";
613 }
614 print "};<br>\n";
615
616 print "<h3>Constants</h3>\n";
617 print "<dl>\n";
618 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700619 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700620 print "<dd>";
621 output_highlight($args{'parameterdescs'}{$parameter});
622 }
623 print "</dl>\n";
624 output_section_html(@_);
625 print "<hr>\n";
626}
627
Randy Dunlapd28bee02006-02-01 03:06:57 -0800628# output typedef in html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700629sub output_typedef_html(%) {
630 my %args = %{$_[0]};
631 my ($parameter);
632 my $count;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700633 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700634
Randy Dunlapb9d973282009-06-09 08:50:38 -0700635 print "<b>typedef " . $args{'typedef'} . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700636 output_section_html(@_);
637 print "<hr>\n";
638}
639
640# output struct in html
641sub output_struct_html(%) {
642 my %args = %{$_[0]};
643 my ($parameter);
644
Randy Dunlapb9d973282009-06-09 08:50:38 -0700645 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
646 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700647 foreach $parameter (@{$args{'parameterlist'}}) {
648 if ($parameter =~ /^#/) {
649 print "$parameter<br>\n";
650 next;
651 }
652 my $parameter_name = $parameter;
653 $parameter_name =~ s/\[.*//;
654
Randy Dunlap3c308792007-05-08 00:24:39 -0700655 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700656 $type = $args{'parametertypes'}{$parameter};
657 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
658 # pointer-to-function
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700659 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700660 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700661 # bitfield
662 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700663 } else {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700664 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700665 }
666 }
667 print "};<br>\n";
668
669 print "<h3>Members</h3>\n";
670 print "<dl>\n";
671 foreach $parameter (@{$args{'parameterlist'}}) {
672 ($parameter =~ /^#/) && next;
673
674 my $parameter_name = $parameter;
675 $parameter_name =~ s/\[.*//;
676
Randy Dunlap3c308792007-05-08 00:24:39 -0700677 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700678 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700679 print "<dd>";
680 output_highlight($args{'parameterdescs'}{$parameter_name});
681 }
682 print "</dl>\n";
683 output_section_html(@_);
684 print "<hr>\n";
685}
686
687# output function in html
688sub output_function_html(%) {
689 my %args = %{$_[0]};
690 my ($parameter, $section);
691 my $count;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700692
Randy Dunlapb9d973282009-06-09 08:50:38 -0700693 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
694 print "<i>" . $args{'functiontype'} . "</i>\n";
695 print "<b>" . $args{'function'} . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700696 print "(";
697 $count = 0;
698 foreach $parameter (@{$args{'parameterlist'}}) {
699 $type = $args{'parametertypes'}{$parameter};
700 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
701 # pointer-to-function
702 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
703 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700704 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700705 }
706 if ($count != $#{$args{'parameterlist'}}) {
707 $count++;
708 print ",\n";
709 }
710 }
711 print ")\n";
712
713 print "<h3>Arguments</h3>\n";
714 print "<dl>\n";
715 foreach $parameter (@{$args{'parameterlist'}}) {
716 my $parameter_name = $parameter;
717 $parameter_name =~ s/\[.*//;
718
Randy Dunlap3c308792007-05-08 00:24:39 -0700719 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700720 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700721 print "<dd>";
722 output_highlight($args{'parameterdescs'}{$parameter_name});
723 }
724 print "</dl>\n";
725 output_section_html(@_);
726 print "<hr>\n";
727}
728
Johannes Bergb112e0f2007-10-24 15:08:48 -0700729# output DOC: block header in html
730sub output_blockhead_html(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700731 my %args = %{$_[0]};
732 my ($parameter, $section);
733 my $count;
734
735 foreach $section (@{$args{'sectionlist'}}) {
736 print "<h3>$section</h3>\n";
737 print "<ul>\n";
738 output_highlight($args{'sections'}{$section});
739 print "</ul>\n";
740 }
741 print "<hr>\n";
742}
743
Dan Luedtke1b40c192012-08-12 10:46:15 +0200744# output sections in html5
745sub output_section_html5(%) {
746 my %args = %{$_[0]};
747 my $section;
748
749 foreach $section (@{$args{'sectionlist'}}) {
750 print "<section>\n";
751 print "<h1>$section</h1>\n";
752 print "<p>\n";
753 output_highlight($args{'sections'}{$section});
754 print "</p>\n";
755 print "</section>\n";
756 }
757}
758
759# output enum in html5
760sub output_enum_html5(%) {
761 my %args = %{$_[0]};
762 my ($parameter);
763 my $count;
764 my $html5id;
765
766 $html5id = $args{'enum'};
767 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
768 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
769 print "<h1>enum " . $args{'enum'} . "</h1>\n";
770 print "<ol class=\"code\">\n";
771 print "<li>";
772 print "<span class=\"keyword\">enum</span> ";
773 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
774 print "</li>\n";
775 $count = 0;
776 foreach $parameter (@{$args{'parameterlist'}}) {
777 print "<li class=\"indent\">";
778 print "<span class=\"param\">" . $parameter . "</span>";
779 if ($count != $#{$args{'parameterlist'}}) {
780 $count++;
781 print ",";
782 }
783 print "</li>\n";
784 }
785 print "<li>};</li>\n";
786 print "</ol>\n";
787
788 print "<section>\n";
789 print "<h1>Constants</h1>\n";
790 print "<dl>\n";
791 foreach $parameter (@{$args{'parameterlist'}}) {
792 print "<dt>" . $parameter . "</dt>\n";
793 print "<dd>";
794 output_highlight($args{'parameterdescs'}{$parameter});
795 print "</dd>\n";
796 }
797 print "</dl>\n";
798 print "</section>\n";
799 output_section_html5(@_);
800 print "</article>\n";
801}
802
803# output typedef in html5
804sub output_typedef_html5(%) {
805 my %args = %{$_[0]};
806 my ($parameter);
807 my $count;
808 my $html5id;
809
810 $html5id = $args{'typedef'};
811 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
812 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
813 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
814
815 print "<ol class=\"code\">\n";
816 print "<li>";
817 print "<span class=\"keyword\">typedef</span> ";
818 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
819 print "</li>\n";
820 print "</ol>\n";
821 output_section_html5(@_);
822 print "</article>\n";
823}
824
825# output struct in html5
826sub output_struct_html5(%) {
827 my %args = %{$_[0]};
828 my ($parameter);
829 my $html5id;
830
831 $html5id = $args{'struct'};
832 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
833 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
834 print "<hgroup>\n";
835 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
836 print "<h2>". $args{'purpose'} . "</h2>\n";
837 print "</hgroup>\n";
838 print "<ol class=\"code\">\n";
839 print "<li>";
840 print "<span class=\"type\">" . $args{'type'} . "</span> ";
841 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
842 print "</li>\n";
843 foreach $parameter (@{$args{'parameterlist'}}) {
844 print "<li class=\"indent\">";
845 if ($parameter =~ /^#/) {
846 print "<span class=\"param\">" . $parameter ."</span>\n";
847 print "</li>\n";
848 next;
849 }
850 my $parameter_name = $parameter;
851 $parameter_name =~ s/\[.*//;
852
853 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
854 $type = $args{'parametertypes'}{$parameter};
855 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
856 # pointer-to-function
857 print "<span class=\"type\">$1</span> ";
858 print "<span class=\"param\">$parameter</span>";
859 print "<span class=\"type\">)</span> ";
860 print "(<span class=\"args\">$2</span>);";
861 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
862 # bitfield
863 print "<span class=\"type\">$1</span> ";
864 print "<span class=\"param\">$parameter</span>";
865 print "<span class=\"bits\">$2</span>;";
866 } else {
867 print "<span class=\"type\">$type</span> ";
868 print "<span class=\"param\">$parameter</span>;";
869 }
870 print "</li>\n";
871 }
872 print "<li>};</li>\n";
873 print "</ol>\n";
874
875 print "<section>\n";
876 print "<h1>Members</h1>\n";
877 print "<dl>\n";
878 foreach $parameter (@{$args{'parameterlist'}}) {
879 ($parameter =~ /^#/) && next;
880
881 my $parameter_name = $parameter;
882 $parameter_name =~ s/\[.*//;
883
884 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
885 print "<dt>" . $parameter . "</dt>\n";
886 print "<dd>";
887 output_highlight($args{'parameterdescs'}{$parameter_name});
888 print "</dd>\n";
889 }
890 print "</dl>\n";
891 print "</section>\n";
892 output_section_html5(@_);
893 print "</article>\n";
894}
895
896# output function in html5
897sub output_function_html5(%) {
898 my %args = %{$_[0]};
899 my ($parameter, $section);
900 my $count;
901 my $html5id;
902
903 $html5id = $args{'function'};
904 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
905 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
906 print "<hgroup>\n";
907 print "<h1>" . $args{'function'} . "</h1>";
908 print "<h2>" . $args{'purpose'} . "</h2>\n";
909 print "</hgroup>\n";
910 print "<ol class=\"code\">\n";
911 print "<li>";
912 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
913 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
914 print "</li>";
915 $count = 0;
916 foreach $parameter (@{$args{'parameterlist'}}) {
917 print "<li class=\"indent\">";
918 $type = $args{'parametertypes'}{$parameter};
919 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
920 # pointer-to-function
921 print "<span class=\"type\">$1</span> ";
922 print "<span class=\"param\">$parameter</span>";
923 print "<span class=\"type\">)</span> ";
924 print "(<span class=\"args\">$2</span>)";
925 } else {
926 print "<span class=\"type\">$type</span> ";
927 print "<span class=\"param\">$parameter</span>";
928 }
929 if ($count != $#{$args{'parameterlist'}}) {
930 $count++;
931 print ",";
932 }
933 print "</li>\n";
934 }
935 print "<li>)</li>\n";
936 print "</ol>\n";
937
938 print "<section>\n";
939 print "<h1>Arguments</h1>\n";
940 print "<p>\n";
941 print "<dl>\n";
942 foreach $parameter (@{$args{'parameterlist'}}) {
943 my $parameter_name = $parameter;
944 $parameter_name =~ s/\[.*//;
945
946 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
947 print "<dt>" . $parameter . "</dt>\n";
948 print "<dd>";
949 output_highlight($args{'parameterdescs'}{$parameter_name});
950 print "</dd>\n";
951 }
952 print "</dl>\n";
953 print "</section>\n";
954 output_section_html5(@_);
955 print "</article>\n";
956}
957
958# output DOC: block header in html5
959sub output_blockhead_html5(%) {
960 my %args = %{$_[0]};
961 my ($parameter, $section);
962 my $count;
963 my $html5id;
964
965 foreach $section (@{$args{'sectionlist'}}) {
966 $html5id = $section;
967 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
968 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
969 print "<h1>$section</h1>\n";
970 print "<p>\n";
971 output_highlight($args{'sections'}{$section});
972 print "</p>\n";
973 }
974 print "</article>\n";
975}
976
Linus Torvalds1da177e2005-04-16 15:20:36 -0700977sub output_section_xml(%) {
978 my %args = %{$_[0]};
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800979 my $section;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700980 # print out each section
981 $lineprefix=" ";
982 foreach $section (@{$args{'sectionlist'}}) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700983 print "<refsect1>\n";
984 print "<title>$section</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700985 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700986 print "<informalexample><programlisting>\n";
Daniel Santose314ba32012-10-04 17:15:08 -0700987 $output_preformatted = 1;
Rich Walkerc73894c2005-05-01 08:59:26 -0700988 } else {
989 print "<para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700990 }
991 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -0700992 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700993 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700994 print "</programlisting></informalexample>\n";
995 } else {
996 print "</para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700997 }
Rich Walkerc73894c2005-05-01 08:59:26 -0700998 print "</refsect1>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700999 }
1000}
1001
1002# output function in XML DocBook
1003sub output_function_xml(%) {
1004 my %args = %{$_[0]};
1005 my ($parameter, $section);
1006 my $count;
1007 my $id;
1008
Randy Dunlapb9d973282009-06-09 08:50:38 -07001009 $id = "API-" . $args{'function'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001010 $id =~ s/[^A-Za-z0-9]/-/g;
1011
Pavel Pisa5449bc92007-02-10 01:45:37 -08001012 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001013 print "<refentryinfo>\n";
1014 print " <title>LINUX</title>\n";
1015 print " <productname>Kernel Hackers Manual</productname>\n";
1016 print " <date>$man_date</date>\n";
1017 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001018 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001019 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001020 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001021 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001022 print "</refmeta>\n";
1023 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001024 print " <refname>" . $args{'function'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001025 print " <refpurpose>\n";
1026 print " ";
1027 output_highlight ($args{'purpose'});
1028 print " </refpurpose>\n";
1029 print "</refnamediv>\n";
1030
1031 print "<refsynopsisdiv>\n";
1032 print " <title>Synopsis</title>\n";
1033 print " <funcsynopsis><funcprototype>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001034 print " <funcdef>" . $args{'functiontype'} . " ";
1035 print "<function>" . $args{'function'} . " </function></funcdef>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001036
1037 $count = 0;
1038 if ($#{$args{'parameterlist'}} >= 0) {
1039 foreach $parameter (@{$args{'parameterlist'}}) {
1040 $type = $args{'parametertypes'}{$parameter};
1041 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1042 # pointer-to-function
1043 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
1044 print " <funcparams>$2</funcparams></paramdef>\n";
1045 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001046 print " <paramdef>" . $type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001047 print " <parameter>$parameter</parameter></paramdef>\n";
1048 }
1049 }
1050 } else {
Martin Waitz6013d542005-05-01 08:59:25 -07001051 print " <void/>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001052 }
1053 print " </funcprototype></funcsynopsis>\n";
1054 print "</refsynopsisdiv>\n";
1055
1056 # print parameters
1057 print "<refsect1>\n <title>Arguments</title>\n";
1058 if ($#{$args{'parameterlist'}} >= 0) {
1059 print " <variablelist>\n";
1060 foreach $parameter (@{$args{'parameterlist'}}) {
1061 my $parameter_name = $parameter;
1062 $parameter_name =~ s/\[.*//;
1063
1064 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1065 print " <listitem>\n <para>\n";
1066 $lineprefix=" ";
1067 output_highlight($args{'parameterdescs'}{$parameter_name});
1068 print " </para>\n </listitem>\n </varlistentry>\n";
1069 }
1070 print " </variablelist>\n";
1071 } else {
1072 print " <para>\n None\n </para>\n";
1073 }
1074 print "</refsect1>\n";
1075
1076 output_section_xml(@_);
1077 print "</refentry>\n\n";
1078}
1079
1080# output struct in XML DocBook
1081sub output_struct_xml(%) {
1082 my %args = %{$_[0]};
1083 my ($parameter, $section);
1084 my $id;
1085
Randy Dunlapb9d973282009-06-09 08:50:38 -07001086 $id = "API-struct-" . $args{'struct'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001087 $id =~ s/[^A-Za-z0-9]/-/g;
1088
Pavel Pisa5449bc92007-02-10 01:45:37 -08001089 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001090 print "<refentryinfo>\n";
1091 print " <title>LINUX</title>\n";
1092 print " <productname>Kernel Hackers Manual</productname>\n";
1093 print " <date>$man_date</date>\n";
1094 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001095 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001096 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001097 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001098 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001099 print "</refmeta>\n";
1100 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001101 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001102 print " <refpurpose>\n";
1103 print " ";
1104 output_highlight ($args{'purpose'});
1105 print " </refpurpose>\n";
1106 print "</refnamediv>\n";
1107
1108 print "<refsynopsisdiv>\n";
1109 print " <title>Synopsis</title>\n";
1110 print " <programlisting>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001111 print $args{'type'} . " " . $args{'struct'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001112 foreach $parameter (@{$args{'parameterlist'}}) {
1113 if ($parameter =~ /^#/) {
Randy Dunlap2b35f4d2010-11-18 12:27:31 -08001114 my $prm = $parameter;
1115 # convert data read & converted thru xml_escape() into &xyz; format:
1116 # This allows us to have #define macros interspersed in a struct.
1117 $prm =~ s/\\\\\\/\&/g;
1118 print "$prm\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001119 next;
1120 }
1121
1122 my $parameter_name = $parameter;
1123 $parameter_name =~ s/\[.*//;
1124
1125 defined($args{'parameterdescs'}{$parameter_name}) || next;
Randy Dunlap3c308792007-05-08 00:24:39 -07001126 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001127 $type = $args{'parametertypes'}{$parameter};
1128 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1129 # pointer-to-function
1130 print " $1 $parameter) ($2);\n";
1131 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07001132 # bitfield
Linus Torvalds1da177e2005-04-16 15:20:36 -07001133 print " $1 $parameter$2;\n";
1134 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001135 print " " . $type . " " . $parameter . ";\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001136 }
1137 }
1138 print "};";
1139 print " </programlisting>\n";
1140 print "</refsynopsisdiv>\n";
1141
1142 print " <refsect1>\n";
1143 print " <title>Members</title>\n";
1144
Randy Dunlap39f00c02008-09-22 13:57:44 -07001145 if ($#{$args{'parameterlist'}} >= 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001146 print " <variablelist>\n";
1147 foreach $parameter (@{$args{'parameterlist'}}) {
1148 ($parameter =~ /^#/) && next;
1149
1150 my $parameter_name = $parameter;
1151 $parameter_name =~ s/\[.*//;
1152
1153 defined($args{'parameterdescs'}{$parameter_name}) || next;
1154 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1155 print " <varlistentry>";
1156 print " <term>$parameter</term>\n";
1157 print " <listitem><para>\n";
1158 output_highlight($args{'parameterdescs'}{$parameter_name});
1159 print " </para></listitem>\n";
1160 print " </varlistentry>\n";
1161 }
1162 print " </variablelist>\n";
Randy Dunlap39f00c02008-09-22 13:57:44 -07001163 } else {
1164 print " <para>\n None\n </para>\n";
1165 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001166 print " </refsect1>\n";
1167
1168 output_section_xml(@_);
1169
1170 print "</refentry>\n\n";
1171}
1172
1173# output enum in XML DocBook
1174sub output_enum_xml(%) {
1175 my %args = %{$_[0]};
1176 my ($parameter, $section);
1177 my $count;
1178 my $id;
1179
Randy Dunlapb9d973282009-06-09 08:50:38 -07001180 $id = "API-enum-" . $args{'enum'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001181 $id =~ s/[^A-Za-z0-9]/-/g;
1182
Pavel Pisa5449bc92007-02-10 01:45:37 -08001183 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001184 print "<refentryinfo>\n";
1185 print " <title>LINUX</title>\n";
1186 print " <productname>Kernel Hackers Manual</productname>\n";
1187 print " <date>$man_date</date>\n";
1188 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001189 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001190 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001191 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001192 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001193 print "</refmeta>\n";
1194 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001195 print " <refname>enum " . $args{'enum'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001196 print " <refpurpose>\n";
1197 print " ";
1198 output_highlight ($args{'purpose'});
1199 print " </refpurpose>\n";
1200 print "</refnamediv>\n";
1201
1202 print "<refsynopsisdiv>\n";
1203 print " <title>Synopsis</title>\n";
1204 print " <programlisting>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001205 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001206 $count = 0;
1207 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001208 print " $parameter";
1209 if ($count != $#{$args{'parameterlist'}}) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001210 $count++;
1211 print ",";
Randy Dunlap3c308792007-05-08 00:24:39 -07001212 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001213 print "\n";
1214 }
1215 print "};";
1216 print " </programlisting>\n";
1217 print "</refsynopsisdiv>\n";
1218
1219 print "<refsect1>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001220 print " <title>Constants</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001221 print " <variablelist>\n";
1222 foreach $parameter (@{$args{'parameterlist'}}) {
1223 my $parameter_name = $parameter;
1224 $parameter_name =~ s/\[.*//;
1225
1226 print " <varlistentry>";
1227 print " <term>$parameter</term>\n";
1228 print " <listitem><para>\n";
1229 output_highlight($args{'parameterdescs'}{$parameter_name});
1230 print " </para></listitem>\n";
1231 print " </varlistentry>\n";
1232 }
1233 print " </variablelist>\n";
1234 print "</refsect1>\n";
1235
1236 output_section_xml(@_);
1237
1238 print "</refentry>\n\n";
1239}
1240
1241# output typedef in XML DocBook
1242sub output_typedef_xml(%) {
1243 my %args = %{$_[0]};
1244 my ($parameter, $section);
1245 my $id;
1246
Randy Dunlapb9d973282009-06-09 08:50:38 -07001247 $id = "API-typedef-" . $args{'typedef'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001248 $id =~ s/[^A-Za-z0-9]/-/g;
1249
Pavel Pisa5449bc92007-02-10 01:45:37 -08001250 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001251 print "<refentryinfo>\n";
1252 print " <title>LINUX</title>\n";
1253 print " <productname>Kernel Hackers Manual</productname>\n";
1254 print " <date>$man_date</date>\n";
1255 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001256 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001257 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001258 print " <manvolnum>9</manvolnum>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001259 print "</refmeta>\n";
1260 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001261 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001262 print " <refpurpose>\n";
1263 print " ";
1264 output_highlight ($args{'purpose'});
1265 print " </refpurpose>\n";
1266 print "</refnamediv>\n";
1267
1268 print "<refsynopsisdiv>\n";
1269 print " <title>Synopsis</title>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001270 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001271 print "</refsynopsisdiv>\n";
1272
1273 output_section_xml(@_);
1274
1275 print "</refentry>\n\n";
1276}
1277
1278# output in XML DocBook
Johannes Bergb112e0f2007-10-24 15:08:48 -07001279sub output_blockhead_xml(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001280 my %args = %{$_[0]};
1281 my ($parameter, $section);
1282 my $count;
1283
1284 my $id = $args{'module'};
1285 $id =~ s/[^A-Za-z0-9]/-/g;
1286
1287 # print out each section
1288 $lineprefix=" ";
1289 foreach $section (@{$args{'sectionlist'}}) {
Johannes Bergb112e0f2007-10-24 15:08:48 -07001290 if (!$args{'content-only'}) {
1291 print "<refsect1>\n <title>$section</title>\n";
1292 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001293 if ($section =~ m/EXAMPLE/i) {
1294 print "<example><para>\n";
Daniel Santose314ba32012-10-04 17:15:08 -07001295 $output_preformatted = 1;
Johannes Bergb112e0f2007-10-24 15:08:48 -07001296 } else {
1297 print "<para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001298 }
1299 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -07001300 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001301 if ($section =~ m/EXAMPLE/i) {
1302 print "</para></example>\n";
Johannes Bergb112e0f2007-10-24 15:08:48 -07001303 } else {
1304 print "</para>";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001305 }
Johannes Bergb112e0f2007-10-24 15:08:48 -07001306 if (!$args{'content-only'}) {
1307 print "\n</refsect1>\n";
1308 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001309 }
1310
1311 print "\n\n";
1312}
1313
1314# output in XML DocBook
1315sub output_function_gnome {
1316 my %args = %{$_[0]};
1317 my ($parameter, $section);
1318 my $count;
1319 my $id;
1320
Randy Dunlapb9d973282009-06-09 08:50:38 -07001321 $id = $args{'module'} . "-" . $args{'function'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001322 $id =~ s/[^A-Za-z0-9]/-/g;
1323
1324 print "<sect2>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001325 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001326
1327 print " <funcsynopsis>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001328 print " <funcdef>" . $args{'functiontype'} . " ";
1329 print "<function>" . $args{'function'} . " ";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001330 print "</function></funcdef>\n";
1331
1332 $count = 0;
1333 if ($#{$args{'parameterlist'}} >= 0) {
1334 foreach $parameter (@{$args{'parameterlist'}}) {
1335 $type = $args{'parametertypes'}{$parameter};
1336 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1337 # pointer-to-function
1338 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1339 print " <funcparams>$2</funcparams></paramdef>\n";
1340 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001341 print " <paramdef>" . $type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001342 print " <parameter>$parameter</parameter></paramdef>\n";
1343 }
1344 }
1345 } else {
1346 print " <void>\n";
1347 }
1348 print " </funcsynopsis>\n";
1349 if ($#{$args{'parameterlist'}} >= 0) {
1350 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1351 print "<tgroup cols=\"2\">\n";
1352 print "<colspec colwidth=\"2*\">\n";
1353 print "<colspec colwidth=\"8*\">\n";
1354 print "<tbody>\n";
1355 foreach $parameter (@{$args{'parameterlist'}}) {
1356 my $parameter_name = $parameter;
1357 $parameter_name =~ s/\[.*//;
1358
1359 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1360 print " <entry>\n";
1361 $lineprefix=" ";
1362 output_highlight($args{'parameterdescs'}{$parameter_name});
1363 print " </entry></row>\n";
1364 }
1365 print " </tbody></tgroup></informaltable>\n";
1366 } else {
1367 print " <para>\n None\n </para>\n";
1368 }
1369
1370 # print out each section
1371 $lineprefix=" ";
1372 foreach $section (@{$args{'sectionlist'}}) {
1373 print "<simplesect>\n <title>$section</title>\n";
1374 if ($section =~ m/EXAMPLE/i) {
1375 print "<example><programlisting>\n";
Daniel Santose314ba32012-10-04 17:15:08 -07001376 $output_preformatted = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001377 } else {
1378 }
1379 print "<para>\n";
1380 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -07001381 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001382 print "</para>\n";
1383 if ($section =~ m/EXAMPLE/i) {
1384 print "</programlisting></example>\n";
1385 } else {
1386 }
1387 print " </simplesect>\n";
1388 }
1389
1390 print "</sect2>\n\n";
1391}
1392
1393##
1394# output function in man
1395sub output_function_man(%) {
1396 my %args = %{$_[0]};
1397 my ($parameter, $section);
1398 my $count;
1399
1400 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1401
1402 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001403 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001404
1405 print ".SH SYNOPSIS\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001406 if ($args{'functiontype'} ne "") {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001407 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001408 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001409 print ".B \"" . $args{'function'} . "\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001410 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001411 $count = 0;
1412 my $parenth = "(";
1413 my $post = ",";
1414 foreach my $parameter (@{$args{'parameterlist'}}) {
1415 if ($count == $#{$args{'parameterlist'}}) {
1416 $post = ");";
1417 }
1418 $type = $args{'parametertypes'}{$parameter};
1419 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1420 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001421 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001422 } else {
1423 $type =~ s/([^\*])$/$1 /;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001424 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001425 }
1426 $count++;
1427 $parenth = "";
1428 }
1429
1430 print ".SH ARGUMENTS\n";
1431 foreach $parameter (@{$args{'parameterlist'}}) {
1432 my $parameter_name = $parameter;
1433 $parameter_name =~ s/\[.*//;
1434
Randy Dunlapb9d973282009-06-09 08:50:38 -07001435 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001436 output_highlight($args{'parameterdescs'}{$parameter_name});
1437 }
1438 foreach $section (@{$args{'sectionlist'}}) {
1439 print ".SH \"", uc $section, "\"\n";
1440 output_highlight($args{'sections'}{$section});
1441 }
1442}
1443
1444##
1445# output enum in man
1446sub output_enum_man(%) {
1447 my %args = %{$_[0]};
1448 my ($parameter, $section);
1449 my $count;
1450
1451 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1452
1453 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001454 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001455
1456 print ".SH SYNOPSIS\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001457 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001458 $count = 0;
1459 foreach my $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001460 print ".br\n.BI \" $parameter\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001461 if ($count == $#{$args{'parameterlist'}}) {
1462 print "\n};\n";
1463 last;
1464 }
1465 else {
1466 print ", \n.br\n";
1467 }
1468 $count++;
1469 }
1470
1471 print ".SH Constants\n";
1472 foreach $parameter (@{$args{'parameterlist'}}) {
1473 my $parameter_name = $parameter;
1474 $parameter_name =~ s/\[.*//;
1475
Randy Dunlapb9d973282009-06-09 08:50:38 -07001476 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001477 output_highlight($args{'parameterdescs'}{$parameter_name});
1478 }
1479 foreach $section (@{$args{'sectionlist'}}) {
1480 print ".SH \"$section\"\n";
1481 output_highlight($args{'sections'}{$section});
1482 }
1483}
1484
1485##
1486# output struct in man
1487sub output_struct_man(%) {
1488 my %args = %{$_[0]};
1489 my ($parameter, $section);
1490
Randy Dunlapb9d973282009-06-09 08:50:38 -07001491 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001492
1493 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001494 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001495
1496 print ".SH SYNOPSIS\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001497 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001498
1499 foreach my $parameter (@{$args{'parameterlist'}}) {
1500 if ($parameter =~ /^#/) {
1501 print ".BI \"$parameter\"\n.br\n";
1502 next;
1503 }
1504 my $parameter_name = $parameter;
1505 $parameter_name =~ s/\[.*//;
1506
Randy Dunlap3c308792007-05-08 00:24:39 -07001507 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001508 $type = $args{'parametertypes'}{$parameter};
1509 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1510 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001511 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001512 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001513 # bitfield
Randy Dunlapb9d973282009-06-09 08:50:38 -07001514 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001515 } else {
1516 $type =~ s/([^\*])$/$1 /;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001517 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001518 }
1519 print "\n.br\n";
1520 }
1521 print "};\n.br\n";
1522
Randy Dunlapc51d3da2006-06-25 05:49:14 -07001523 print ".SH Members\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001524 foreach $parameter (@{$args{'parameterlist'}}) {
1525 ($parameter =~ /^#/) && next;
1526
1527 my $parameter_name = $parameter;
1528 $parameter_name =~ s/\[.*//;
1529
Randy Dunlap3c308792007-05-08 00:24:39 -07001530 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001531 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001532 output_highlight($args{'parameterdescs'}{$parameter_name});
1533 }
1534 foreach $section (@{$args{'sectionlist'}}) {
1535 print ".SH \"$section\"\n";
1536 output_highlight($args{'sections'}{$section});
1537 }
1538}
1539
1540##
1541# output typedef in man
1542sub output_typedef_man(%) {
1543 my %args = %{$_[0]};
1544 my ($parameter, $section);
1545
1546 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1547
1548 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001549 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001550
1551 foreach $section (@{$args{'sectionlist'}}) {
1552 print ".SH \"$section\"\n";
1553 output_highlight($args{'sections'}{$section});
1554 }
1555}
1556
Johannes Bergb112e0f2007-10-24 15:08:48 -07001557sub output_blockhead_man(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001558 my %args = %{$_[0]};
1559 my ($parameter, $section);
1560 my $count;
1561
1562 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1563
1564 foreach $section (@{$args{'sectionlist'}}) {
1565 print ".SH \"$section\"\n";
1566 output_highlight($args{'sections'}{$section});
1567 }
1568}
1569
1570##
1571# output in text
1572sub output_function_text(%) {
1573 my %args = %{$_[0]};
1574 my ($parameter, $section);
Randy Dunlapa21217d2007-02-10 01:46:04 -08001575 my $start;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001576
Randy Dunlapf47634b2006-07-01 04:36:36 -07001577 print "Name:\n\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001578 print $args{'function'} . " - " . $args{'purpose'} . "\n";
Randy Dunlapf47634b2006-07-01 04:36:36 -07001579
1580 print "\nSynopsis:\n\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001581 if ($args{'functiontype'} ne "") {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001582 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001583 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001584 $start = $args{'function'} . " (";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001585 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001586 print $start;
Randy Dunlapa21217d2007-02-10 01:46:04 -08001587
Linus Torvalds1da177e2005-04-16 15:20:36 -07001588 my $count = 0;
1589 foreach my $parameter (@{$args{'parameterlist'}}) {
1590 $type = $args{'parametertypes'}{$parameter};
1591 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1592 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001593 print $1 . $parameter . ") (" . $2;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001594 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001595 print $type . " " . $parameter;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001596 }
1597 if ($count != $#{$args{'parameterlist'}}) {
1598 $count++;
1599 print ",\n";
1600 print " " x length($start);
1601 } else {
1602 print ");\n\n";
1603 }
1604 }
1605
1606 print "Arguments:\n\n";
1607 foreach $parameter (@{$args{'parameterlist'}}) {
1608 my $parameter_name = $parameter;
1609 $parameter_name =~ s/\[.*//;
1610
Randy Dunlapb9d973282009-06-09 08:50:38 -07001611 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001612 }
1613 output_section_text(@_);
1614}
1615
1616#output sections in text
1617sub output_section_text(%) {
1618 my %args = %{$_[0]};
1619 my $section;
1620
1621 print "\n";
1622 foreach $section (@{$args{'sectionlist'}}) {
1623 print "$section:\n\n";
1624 output_highlight($args{'sections'}{$section});
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001625 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001626 print "\n\n";
1627}
1628
1629# output enum in text
1630sub output_enum_text(%) {
1631 my %args = %{$_[0]};
1632 my ($parameter);
1633 my $count;
1634 print "Enum:\n\n";
1635
Randy Dunlapb9d973282009-06-09 08:50:38 -07001636 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1637 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001638 $count = 0;
1639 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001640 print "\t$parameter";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001641 if ($count != $#{$args{'parameterlist'}}) {
1642 $count++;
1643 print ",";
1644 }
1645 print "\n";
1646 }
1647 print "};\n\n";
1648
1649 print "Constants:\n\n";
1650 foreach $parameter (@{$args{'parameterlist'}}) {
1651 print "$parameter\n\t";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001652 print $args{'parameterdescs'}{$parameter} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001653 }
1654
1655 output_section_text(@_);
1656}
1657
1658# output typedef in text
1659sub output_typedef_text(%) {
1660 my %args = %{$_[0]};
1661 my ($parameter);
1662 my $count;
1663 print "Typedef:\n\n";
1664
Randy Dunlapb9d973282009-06-09 08:50:38 -07001665 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001666 output_section_text(@_);
1667}
1668
1669# output struct as text
1670sub output_struct_text(%) {
1671 my %args = %{$_[0]};
1672 my ($parameter);
1673
Randy Dunlapb9d973282009-06-09 08:50:38 -07001674 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1675 print $args{'type'} . " " . $args{'struct'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001676 foreach $parameter (@{$args{'parameterlist'}}) {
1677 if ($parameter =~ /^#/) {
1678 print "$parameter\n";
1679 next;
1680 }
1681
1682 my $parameter_name = $parameter;
1683 $parameter_name =~ s/\[.*//;
1684
Randy Dunlap3c308792007-05-08 00:24:39 -07001685 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001686 $type = $args{'parametertypes'}{$parameter};
1687 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1688 # pointer-to-function
1689 print "\t$1 $parameter) ($2);\n";
1690 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07001691 # bitfield
Linus Torvalds1da177e2005-04-16 15:20:36 -07001692 print "\t$1 $parameter$2;\n";
1693 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001694 print "\t" . $type . " " . $parameter . ";\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001695 }
1696 }
1697 print "};\n\n";
1698
1699 print "Members:\n\n";
1700 foreach $parameter (@{$args{'parameterlist'}}) {
1701 ($parameter =~ /^#/) && next;
1702
1703 my $parameter_name = $parameter;
1704 $parameter_name =~ s/\[.*//;
1705
Randy Dunlap3c308792007-05-08 00:24:39 -07001706 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001707 print "$parameter\n\t";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001708 print $args{'parameterdescs'}{$parameter_name} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001709 }
1710 print "\n";
1711 output_section_text(@_);
1712}
1713
Johannes Bergb112e0f2007-10-24 15:08:48 -07001714sub output_blockhead_text(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001715 my %args = %{$_[0]};
1716 my ($parameter, $section);
1717
1718 foreach $section (@{$args{'sectionlist'}}) {
1719 print " $section:\n";
1720 print " -> ";
1721 output_highlight($args{'sections'}{$section});
1722 }
1723}
1724
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001725##
1726# output in restructured text
1727#
1728
1729#
1730# This could use some work; it's used to output the DOC: sections, and
1731# starts by putting out the name of the doc section itself, but that tends
1732# to duplicate a header already in the template file.
1733#
1734sub output_blockhead_rst(%) {
1735 my %args = %{$_[0]};
1736 my ($parameter, $section);
1737
1738 foreach $section (@{$args{'sectionlist'}}) {
1739 print "**$section**\n\n";
1740 output_highlight_rst($args{'sections'}{$section});
1741 print "\n";
1742 }
1743}
1744
1745sub output_highlight_rst {
1746 my $contents = join "\n",@_;
1747 my $line;
1748
1749 # undo the evil effects of xml_escape() earlier
1750 $contents = xml_unescape($contents);
1751
1752 eval $dohighlight;
1753 die $@ if $@;
1754
1755 foreach $line (split "\n", $contents) {
1756 if ($line eq "") {
1757 print $lineprefix, $blankline;
1758 } else {
1759 $line =~ s/\\\\\\/\&/g;
1760 print $lineprefix, $line;
1761 }
1762 print "\n";
1763 }
1764}
1765
1766sub output_function_rst(%) {
1767 my %args = %{$_[0]};
1768 my ($parameter, $section);
1769 my $start;
1770
1771 print ".. c:function:: ";
1772 if ($args{'functiontype'} ne "") {
1773 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1774 } else {
1775 $start = $args{'function'} . " (";
1776 }
1777 print $start;
1778
1779 my $count = 0;
1780 foreach my $parameter (@{$args{'parameterlist'}}) {
1781 if ($count ne 0) {
1782 print ", ";
1783 }
1784 $count++;
1785 $type = $args{'parametertypes'}{$parameter};
1786 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1787 # pointer-to-function
1788 print $1 . $parameter . ") (" . $2;
1789 } else {
1790 print $type . " " . $parameter;
1791 }
1792 }
1793 print ")\n\n " . $args{'purpose'} . "\n\n";
1794
1795 print ":Parameters:\n\n";
1796 foreach $parameter (@{$args{'parameterlist'}}) {
1797 my $parameter_name = $parameter;
1798 #$parameter_name =~ s/\[.*//;
1799 $type = $args{'parametertypes'}{$parameter};
1800
1801 if ($type ne "") {
1802 print " ``$type $parameter``\n";
1803 } else {
1804 print " ``$parameter``\n";
1805 }
1806 if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1807 my $oldprefix = $lineprefix;
1808 $lineprefix = " ";
1809 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1810 $lineprefix = $oldprefix;
1811 } else {
1812 print "\n _undescribed_\n";
1813 }
1814 print "\n";
1815 }
1816 output_section_rst(@_);
1817}
1818
1819sub output_section_rst(%) {
1820 my %args = %{$_[0]};
1821 my $section;
1822 my $oldprefix = $lineprefix;
1823 $lineprefix = " ";
1824
1825 foreach $section (@{$args{'sectionlist'}}) {
1826 print ":$section:\n\n";
1827 output_highlight_rst($args{'sections'}{$section});
1828 print "\n";
1829 }
1830 print "\n";
1831 $lineprefix = $oldprefix;
1832}
1833
1834sub output_enum_rst(%) {
1835 my %args = %{$_[0]};
1836 my ($parameter);
1837 my $count;
1838
1839 my $name = "enum " . $args{'enum'};
1840 print ".. _" . $name . ":\n\n";
1841 print "**$name**\n\n";
1842 print " " . $args{'purpose'} . "\n\n";
1843
1844 print "..\n\n:Constants:\n\n";
1845 my $oldprefix = $lineprefix;
1846 $lineprefix = " ";
1847 foreach $parameter (@{$args{'parameterlist'}}) {
1848 print " `$parameter`\n";
1849 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1850 output_highlight_rst($args{'parameterdescs'}{$parameter});
1851 } else {
1852 print " undescribed\n";
1853 }
1854 print "\n";
1855 }
1856 $lineprefix = $oldprefix;
1857 output_section_rst(@_);
1858}
1859
1860sub output_typedef_rst(%) {
1861 my %args = %{$_[0]};
1862 my ($parameter);
1863 my $count;
1864 my $name = "typedef " . $args{'typedef'};
1865
1866 print "**$name**\n\n";
1867 print $args{'purpose'} . "\n\n";
1868
1869 output_section_rst(@_);
1870}
1871
1872sub output_struct_rst(%) {
1873 my %args = %{$_[0]};
1874 my ($parameter);
1875 my $name = $args{'type'} . " " . $args{'struct'};
1876
1877 print ".. _" . $name . ":\n\n";
1878 print "**$name**\n\n";
1879 print " " . $args{'purpose'} . "\n\n";
1880
1881 print ":Definition:\n\n";
1882 print " ::\n\n";
1883 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1884 foreach $parameter (@{$args{'parameterlist'}}) {
1885 if ($parameter =~ /^#/) {
1886 print " " . "$parameter\n";
1887 next;
1888 }
1889
1890 my $parameter_name = $parameter;
1891 $parameter_name =~ s/\[.*//;
1892
1893 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1894 $type = $args{'parametertypes'}{$parameter};
1895 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1896 # pointer-to-function
1897 print " $1 $parameter) ($2);\n";
1898 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1899 # bitfield
1900 print " $1 $parameter$2;\n";
1901 } else {
1902 print " " . $type . " " . $parameter . ";\n";
1903 }
1904 }
1905 print " };\n\n";
1906
1907 print ":Members:\n\n";
1908 foreach $parameter (@{$args{'parameterlist'}}) {
1909 ($parameter =~ /^#/) && next;
1910
1911 my $parameter_name = $parameter;
1912 $parameter_name =~ s/\[.*//;
1913
1914 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1915 $type = $args{'parametertypes'}{$parameter};
1916 print " `$type $parameter`" . "\n";
1917 my $oldprefix = $lineprefix;
1918 $lineprefix = " ";
1919 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1920 $lineprefix = $oldprefix;
1921 print "\n";
1922 }
1923 print "\n";
1924 output_section_rst(@_);
1925}
1926
1927
Johannes Bergeda603f2010-09-11 15:55:22 -07001928## list mode output functions
1929
1930sub output_function_list(%) {
1931 my %args = %{$_[0]};
1932
1933 print $args{'function'} . "\n";
1934}
1935
1936# output enum in list
1937sub output_enum_list(%) {
1938 my %args = %{$_[0]};
1939 print $args{'enum'} . "\n";
1940}
1941
1942# output typedef in list
1943sub output_typedef_list(%) {
1944 my %args = %{$_[0]};
1945 print $args{'typedef'} . "\n";
1946}
1947
1948# output struct as list
1949sub output_struct_list(%) {
1950 my %args = %{$_[0]};
1951
1952 print $args{'struct'} . "\n";
1953}
1954
1955sub output_blockhead_list(%) {
1956 my %args = %{$_[0]};
1957 my ($parameter, $section);
1958
1959 foreach $section (@{$args{'sectionlist'}}) {
1960 print "DOC: $section\n";
1961 }
1962}
1963
Linus Torvalds1da177e2005-04-16 15:20:36 -07001964##
Randy Dunlap27205742006-10-11 01:22:12 -07001965# generic output function for all types (function, struct/union, typedef, enum);
1966# calls the generated, variable output_ function name based on
1967# functype and output_mode
Linus Torvalds1da177e2005-04-16 15:20:36 -07001968sub output_declaration {
1969 no strict 'refs';
1970 my $name = shift;
1971 my $functype = shift;
1972 my $func = "output_${functype}_$output_mode";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001973 if (($function_only==0) ||
1974 ( $function_only == 1 && defined($function_table{$name})) ||
Danilo Cesar Lemes de Paula23aebb32015-09-01 14:44:14 -03001975 ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
Linus Torvalds1da177e2005-04-16 15:20:36 -07001976 {
Randy Dunlap3c308792007-05-08 00:24:39 -07001977 &$func(@_);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001978 $section_counter++;
1979 }
1980}
1981
1982##
Randy Dunlap27205742006-10-11 01:22:12 -07001983# generic output function - calls the right one based on current output mode.
Johannes Bergb112e0f2007-10-24 15:08:48 -07001984sub output_blockhead {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001985 no strict 'refs';
Randy Dunlapb9d973282009-06-09 08:50:38 -07001986 my $func = "output_blockhead_" . $output_mode;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001987 &$func(@_);
1988 $section_counter++;
1989}
1990
1991##
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001992# takes a declaration (struct, union, enum, typedef) and
Linus Torvalds1da177e2005-04-16 15:20:36 -07001993# invokes the right handler. NOT called for functions.
1994sub dump_declaration($$) {
1995 no strict 'refs';
1996 my ($prototype, $file) = @_;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001997 my $func = "dump_" . $decl_type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001998 &$func(@_);
1999}
2000
2001sub dump_union($$) {
2002 dump_struct(@_);
2003}
2004
2005sub dump_struct($$) {
2006 my $x = shift;
2007 my $file = shift;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002008 my $nested;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002009
Randy Dunlap52dc5ae2009-04-30 15:08:53 -07002010 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2011 #my $decl_type = $1;
Randy Dunlap3c308792007-05-08 00:24:39 -07002012 $declaration_name = $2;
2013 my $members = $3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002014
2015 # ignore embedded structs or unions
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002016 $members =~ s/({.*})//g;
2017 $nested = $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002018
Martin Waitzaeec46b2005-11-13 16:08:13 -08002019 # ignore members marked private:
Mauro Carvalho Chehab0d8c39e2015-10-05 09:03:48 -03002020 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2021 $members =~ s/\/\*\s*private:.*//gosi;
Martin Waitzaeec46b2005-11-13 16:08:13 -08002022 # strip comments:
2023 $members =~ s/\/\*.*?\*\///gos;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002024 $nested =~ s/\/\*.*?\*\///gos;
Randy Dunlapd960eea2009-06-29 14:54:11 -07002025 # strip kmemcheck_bitfield_{begin,end}.*;
2026 $members =~ s/kmemcheck_bitfield_.*?;//gos;
Randy Dunlapef5da592010-03-23 13:35:14 -07002027 # strip attributes
Jonathan Corbetf0074922015-08-23 13:35:23 -06002028 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
Johannes Berg7b990782014-12-10 15:41:28 -08002029 $members =~ s/__aligned\s*\([^;]*\)//gos;
Jonathan Corbetf0074922015-08-23 13:35:23 -06002030 $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
Conchúr Navidb22b5a92015-11-08 10:52:00 +01002031 # replace DECLARE_BITMAP
2032 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
Martin Waitzaeec46b2005-11-13 16:08:13 -08002033
Linus Torvalds1da177e2005-04-16 15:20:36 -07002034 create_parameterlist($members, ';', $file);
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002035 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002036
2037 output_declaration($declaration_name,
2038 'struct',
2039 {'struct' => $declaration_name,
2040 'module' => $modulename,
2041 'parameterlist' => \@parameterlist,
2042 'parameterdescs' => \%parameterdescs,
2043 'parametertypes' => \%parametertypes,
2044 'sectionlist' => \@sectionlist,
2045 'sections' => \%sections,
2046 'purpose' => $declaration_purpose,
2047 'type' => $decl_type
2048 });
2049 }
2050 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002051 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002052 ++$errors;
2053 }
2054}
2055
2056sub dump_enum($$) {
2057 my $x = shift;
2058 my $file = shift;
2059
Martin Waitzaeec46b2005-11-13 16:08:13 -08002060 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Conchúr Navid4468e212015-11-08 10:48:05 +01002061 # strip #define macros inside enums
2062 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
Randy Dunlapb6d676d2010-08-10 18:02:50 -07002063
Linus Torvalds1da177e2005-04-16 15:20:36 -07002064 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002065 $declaration_name = $1;
2066 my $members = $2;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002067
2068 foreach my $arg (split ',', $members) {
2069 $arg =~ s/^\s*(\w+).*/$1/;
2070 push @parameterlist, $arg;
2071 if (!$parameterdescs{$arg}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002072 $parameterdescs{$arg} = $undescribed;
Bart Van Assched40e1e62015-09-04 15:43:21 -07002073 print STDERR "${file}:$.: warning: Enum value '$arg' ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07002074 "not described in enum '$declaration_name'\n";
2075 }
2076
2077 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002078
Linus Torvalds1da177e2005-04-16 15:20:36 -07002079 output_declaration($declaration_name,
2080 'enum',
2081 {'enum' => $declaration_name,
2082 'module' => $modulename,
2083 'parameterlist' => \@parameterlist,
2084 'parameterdescs' => \%parameterdescs,
2085 'sectionlist' => \@sectionlist,
2086 'sections' => \%sections,
2087 'purpose' => $declaration_purpose
2088 });
2089 }
2090 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002091 print STDERR "${file}:$.: error: Cannot parse enum!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002092 ++$errors;
2093 }
2094}
2095
2096sub dump_typedef($$) {
2097 my $x = shift;
2098 my $file = shift;
2099
Martin Waitzaeec46b2005-11-13 16:08:13 -08002100 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Mauro Carvalho Chehab83766452015-10-08 16:14:45 -03002101
2102 # Parse function prototypes
2103 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2104 # Function typedefs
2105 $return_type = $1;
2106 $declaration_name = $2;
2107 my $args = $3;
2108
2109 create_parameterlist($args, ',', $file);
2110
2111 output_declaration($declaration_name,
2112 'function',
2113 {'function' => $declaration_name,
2114 'module' => $modulename,
2115 'functiontype' => $return_type,
2116 'parameterlist' => \@parameterlist,
2117 'parameterdescs' => \%parameterdescs,
2118 'parametertypes' => \%parametertypes,
2119 'sectionlist' => \@sectionlist,
2120 'sections' => \%sections,
2121 'purpose' => $declaration_purpose
2122 });
2123 return;
2124 }
2125
Linus Torvalds1da177e2005-04-16 15:20:36 -07002126 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002127 $x =~ s/\(*.\)\s*;$/;/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002128 $x =~ s/\[*.\]\s*;$/;/;
2129 }
2130
2131 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002132 $declaration_name = $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002133
2134 output_declaration($declaration_name,
2135 'typedef',
2136 {'typedef' => $declaration_name,
2137 'module' => $modulename,
2138 'sectionlist' => \@sectionlist,
2139 'sections' => \%sections,
2140 'purpose' => $declaration_purpose
2141 });
2142 }
2143 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002144 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002145 ++$errors;
2146 }
2147}
2148
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002149sub save_struct_actual($) {
2150 my $actual = shift;
2151
2152 # strip all spaces from the actual param so that it looks like one string item
2153 $actual =~ s/\s*//g;
2154 $struct_actual = $struct_actual . $actual . " ";
2155}
2156
Linus Torvalds1da177e2005-04-16 15:20:36 -07002157sub create_parameterlist($$$) {
2158 my $args = shift;
2159 my $splitter = shift;
2160 my $file = shift;
2161 my $type;
2162 my $param;
2163
Martin Waitza6d3fe72006-01-09 20:53:55 -08002164 # temporarily replace commas inside function pointer definition
Linus Torvalds1da177e2005-04-16 15:20:36 -07002165 while ($args =~ /(\([^\),]+),/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002166 $args =~ s/(\([^\),]+),/$1#/g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002167 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002168
Linus Torvalds1da177e2005-04-16 15:20:36 -07002169 foreach my $arg (split($splitter, $args)) {
2170 # strip comments
2171 $arg =~ s/\/\*.*\*\///;
Randy Dunlap3c308792007-05-08 00:24:39 -07002172 # strip leading/trailing spaces
2173 $arg =~ s/^\s*//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002174 $arg =~ s/\s*$//;
2175 $arg =~ s/\s+/ /;
2176
2177 if ($arg =~ /^#/) {
2178 # Treat preprocessor directive as a typeless variable just to fill
2179 # corresponding data structures "correctly". Catch it later in
2180 # output_* subs.
2181 push_parameter($arg, "", $file);
Richard Kennedy00d62962008-02-23 15:24:01 -08002182 } elsif ($arg =~ m/\(.+\)\s*\(/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002183 # pointer-to-function
2184 $arg =~ tr/#/,/;
Richard Kennedy00d62962008-02-23 15:24:01 -08002185 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002186 $param = $1;
2187 $type = $arg;
Richard Kennedy00d62962008-02-23 15:24:01 -08002188 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002189 save_struct_actual($param);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002190 push_parameter($param, $type, $file);
Martin Waitzaeec46b2005-11-13 16:08:13 -08002191 } elsif ($arg) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002192 $arg =~ s/\s*:\s*/:/g;
2193 $arg =~ s/\s*\[/\[/g;
2194
2195 my @args = split('\s*,\s*', $arg);
2196 if ($args[0] =~ m/\*/) {
2197 $args[0] =~ s/(\*+)\s*/ $1/;
2198 }
Borislav Petkov884f2812007-05-08 00:29:05 -07002199
2200 my @first_arg;
2201 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2202 shift @args;
2203 push(@first_arg, split('\s+', $1));
2204 push(@first_arg, $2);
2205 } else {
2206 @first_arg = split('\s+', shift @args);
2207 }
2208
Linus Torvalds1da177e2005-04-16 15:20:36 -07002209 unshift(@args, pop @first_arg);
2210 $type = join " ", @first_arg;
2211
2212 foreach $param (@args) {
2213 if ($param =~ m/^(\*+)\s*(.*)/) {
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002214 save_struct_actual($2);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002215 push_parameter($2, "$type $1", $file);
2216 }
2217 elsif ($param =~ m/(.*?):(\d+)/) {
Randy Dunlap7b978872008-05-16 15:45:52 -07002218 if ($type ne "") { # skip unnamed bit-fields
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002219 save_struct_actual($1);
Randy Dunlap7b978872008-05-16 15:45:52 -07002220 push_parameter($1, "$type:$2", $file)
2221 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002222 }
2223 else {
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002224 save_struct_actual($param);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002225 push_parameter($param, $type, $file);
2226 }
2227 }
2228 }
2229 }
2230}
2231
2232sub push_parameter($$$) {
2233 my $param = shift;
2234 my $type = shift;
2235 my $file = shift;
2236
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002237 if (($anon_struct_union == 1) && ($type eq "") &&
2238 ($param eq "}")) {
2239 return; # ignore the ending }; from anon. struct/union
2240 }
2241
2242 $anon_struct_union = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002243 my $param_name = $param;
2244 $param_name =~ s/\[.*//;
2245
Martin Waitza6d3fe72006-01-09 20:53:55 -08002246 if ($type eq "" && $param =~ /\.\.\.$/)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002247 {
Randy Dunlapced69092008-12-01 13:14:03 -08002248 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2249 $parameterdescs{$param} = "variable arguments";
2250 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002251 }
2252 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2253 {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002254 $param="void";
2255 $parameterdescs{void} = "no arguments";
2256 }
Randy Dunlap134fe012006-12-22 01:10:50 -08002257 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2258 # handle unnamed (anonymous) union or struct:
2259 {
2260 $type = $param;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002261 $param = "{unnamed_" . $param . "}";
Randy Dunlap134fe012006-12-22 01:10:50 -08002262 $parameterdescs{$param} = "anonymous\n";
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002263 $anon_struct_union = 1;
Randy Dunlap134fe012006-12-22 01:10:50 -08002264 }
2265
Martin Waitza6d3fe72006-01-09 20:53:55 -08002266 # warn if parameter has no description
Randy Dunlap134fe012006-12-22 01:10:50 -08002267 # (but ignore ones starting with # as these are not parameters
2268 # but inline preprocessor statements);
2269 # also ignore unnamed structs/unions;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002270 if (!$anon_struct_union) {
Martin Waitza6d3fe72006-01-09 20:53:55 -08002271 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2272
Linus Torvalds1da177e2005-04-16 15:20:36 -07002273 $parameterdescs{$param_name} = $undescribed;
2274
2275 if (($type eq 'function') || ($type eq 'enum')) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002276 print STDERR "${file}:$.: warning: Function parameter ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07002277 "or member '$param' not " .
2278 "described in '$declaration_name'\n";
2279 }
Bart Van Assched40e1e62015-09-04 15:43:21 -07002280 print STDERR "${file}:$.: warning:" .
Randy Dunlap3c308792007-05-08 00:24:39 -07002281 " No description found for parameter '$param'\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002282 ++$warnings;
Randy Dunlap3c308792007-05-08 00:24:39 -07002283 }
2284 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002285
Randy Dunlap2b35f4d2010-11-18 12:27:31 -08002286 $param = xml_escape($param);
2287
Lucas De Marchi25985ed2011-03-30 22:57:33 -03002288 # strip spaces from $param so that it is one continuous string
Randy Dunlape34e7db2009-06-17 17:37:47 -07002289 # on @parameterlist;
2290 # this fixes a problem where check_sections() cannot find
2291 # a parameter like "addr[6 + 2]" because it actually appears
2292 # as "addr[6", "+", "2]" on the parameter list;
2293 # but it's better to maintain the param string unchanged for output,
2294 # so just weaken the string compare in check_sections() to ignore
2295 # "[blah" in a parameter string;
2296 ###$param =~ s/\s*//g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002297 push @parameterlist, $param;
2298 $parametertypes{$param} = $type;
2299}
2300
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002301sub check_sections($$$$$$) {
2302 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2303 my @sects = split ' ', $sectcheck;
2304 my @prms = split ' ', $prmscheck;
2305 my $err;
2306 my ($px, $sx);
2307 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2308
2309 foreach $sx (0 .. $#sects) {
2310 $err = 1;
2311 foreach $px (0 .. $#prms) {
2312 $prm_clean = $prms[$px];
2313 $prm_clean =~ s/\[.*\]//;
Johannes Berg1f3a6682010-09-11 15:55:12 -07002314 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
Randy Dunlape34e7db2009-06-17 17:37:47 -07002315 # ignore array size in a parameter string;
2316 # however, the original param string may contain
2317 # spaces, e.g.: addr[6 + 2]
2318 # and this appears in @prms as "addr[6" since the
2319 # parameter list is split at spaces;
2320 # hence just ignore "[..." for the sections check;
2321 $prm_clean =~ s/\[.*//;
2322
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002323 ##$prm_clean =~ s/^\**//;
2324 if ($prm_clean eq $sects[$sx]) {
2325 $err = 0;
2326 last;
2327 }
2328 }
2329 if ($err) {
2330 if ($decl_type eq "function") {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002331 print STDERR "${file}:$.: warning: " .
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002332 "Excess function parameter " .
2333 "'$sects[$sx]' " .
2334 "description in '$decl_name'\n";
2335 ++$warnings;
2336 } else {
2337 if ($nested !~ m/\Q$sects[$sx]\E/) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002338 print STDERR "${file}:$.: warning: " .
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002339 "Excess struct/union/enum/typedef member " .
2340 "'$sects[$sx]' " .
2341 "description in '$decl_name'\n";
2342 ++$warnings;
2343 }
2344 }
2345 }
2346 }
2347}
2348
Linus Torvalds1da177e2005-04-16 15:20:36 -07002349##
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002350# Checks the section describing the return value of a function.
2351sub check_return_section {
2352 my $file = shift;
2353 my $declaration_name = shift;
2354 my $return_type = shift;
2355
2356 # Ignore an empty return type (It's a macro)
2357 # Ignore functions with a "void" return type. (But don't ignore "void *")
2358 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2359 return;
2360 }
2361
2362 if (!defined($sections{$section_return}) ||
2363 $sections{$section_return} eq "") {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002364 print STDERR "${file}:$.: warning: " .
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002365 "No description found for return value of " .
2366 "'$declaration_name'\n";
2367 ++$warnings;
2368 }
2369}
2370
2371##
Linus Torvalds1da177e2005-04-16 15:20:36 -07002372# takes a function prototype and the name of the current file being
2373# processed and spits out all the details stored in the global
2374# arrays/hashes.
2375sub dump_function($$) {
2376 my $prototype = shift;
2377 my $file = shift;
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002378 my $noret = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002379
2380 $prototype =~ s/^static +//;
2381 $prototype =~ s/^extern +//;
Pavel Pisa4dc3b162005-05-01 08:59:25 -07002382 $prototype =~ s/^asmlinkage +//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002383 $prototype =~ s/^inline +//;
2384 $prototype =~ s/^__inline__ +//;
Randy Dunlap32e79402006-10-11 01:22:10 -07002385 $prototype =~ s/^__inline +//;
2386 $prototype =~ s/^__always_inline +//;
2387 $prototype =~ s/^noinline +//;
Randy Dunlap74fc5c62008-06-19 16:03:29 -07002388 $prototype =~ s/__init +//;
Randy Dunlap20072202010-03-23 13:35:24 -07002389 $prototype =~ s/__init_or_module +//;
Randy Dunlap270a0092014-08-24 18:17:17 -07002390 $prototype =~ s/__meminit +//;
Randy Dunlap70c95b02012-01-21 10:31:54 -08002391 $prototype =~ s/__must_check +//;
Randy Dunlap0df7c0e2012-08-16 16:23:20 -07002392 $prototype =~ s/__weak +//;
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002393 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
Randy Dunlap328d2442007-02-28 20:12:10 -08002394 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002395
2396 # Yes, this truly is vile. We are looking for:
2397 # 1. Return type (may be nothing if we're looking at a macro)
2398 # 2. Function name
2399 # 3. Function parameters.
2400 #
2401 # All the while we have to watch out for function pointer parameters
2402 # (which IIRC is what the two sections are for), C types (these
2403 # regexps don't even start to express all the possibilities), and
2404 # so on.
2405 #
2406 # If you mess with these regexps, it's a good idea to check that
2407 # the following functions' documentation still comes out right:
2408 # - parport_register_device (function pointer parameters)
2409 # - atomic_set (macro)
Martin Waitz9598f912006-02-01 03:06:55 -08002410 # - pci_match_device, __copy_to_user (long return type)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002411
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002412 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2413 # This is an object-like macro, it has no return type and no parameter
2414 # list.
2415 # Function-like macros are not allowed to have spaces between
2416 # declaration_name and opening parenthesis (notice the \s+).
2417 $return_type = $1;
2418 $declaration_name = $2;
2419 $noret = 1;
2420 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Linus Torvalds1da177e2005-04-16 15:20:36 -07002421 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2422 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2423 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Randy Dunlap94b3e032008-02-07 00:13:26 -08002424 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Linus Torvalds1da177e2005-04-16 15:20:36 -07002425 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2426 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2427 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2428 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2429 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2430 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2431 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2432 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Martin Waitz9598f912006-02-01 03:06:55 -08002433 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2434 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Randy Dunlap412ecd772007-02-10 22:47:33 -08002435 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2436 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002437 $return_type = $1;
2438 $declaration_name = $2;
2439 my $args = $3;
2440
2441 create_parameterlist($args, ',', $file);
2442 } else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002443 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002444 return;
2445 }
2446
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002447 my $prms = join " ", @parameterlist;
2448 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2449
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002450 # This check emits a lot of warnings at the moment, because many
2451 # functions don't have a 'Return' doc section. So until the number
2452 # of warnings goes sufficiently down, the check is only performed in
2453 # verbose mode.
2454 # TODO: always perform the check.
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002455 if ($verbose && !$noret) {
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002456 check_return_section($file, $declaration_name, $return_type);
2457 }
2458
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002459 output_declaration($declaration_name,
Linus Torvalds1da177e2005-04-16 15:20:36 -07002460 'function',
2461 {'function' => $declaration_name,
2462 'module' => $modulename,
2463 'functiontype' => $return_type,
2464 'parameterlist' => \@parameterlist,
2465 'parameterdescs' => \%parameterdescs,
2466 'parametertypes' => \%parametertypes,
2467 'sectionlist' => \@sectionlist,
2468 'sections' => \%sections,
2469 'purpose' => $declaration_purpose
2470 });
2471}
2472
Linus Torvalds1da177e2005-04-16 15:20:36 -07002473sub reset_state {
2474 $function = "";
2475 %constants = ();
2476 %parameterdescs = ();
2477 %parametertypes = ();
2478 @parameterlist = ();
2479 %sections = ();
2480 @sectionlist = ();
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002481 $sectcheck = "";
2482 $struct_actual = "";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002483 $prototype = "";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002484
Linus Torvalds1da177e2005-04-16 15:20:36 -07002485 $state = 0;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002486 $split_doc_state = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002487}
2488
Jason Baron56afb0f2009-04-30 13:29:36 -04002489sub tracepoint_munge($) {
2490 my $file = shift;
2491 my $tracepointname = 0;
2492 my $tracepointargs = 0;
2493
Jason Baron3a9089f2009-12-01 12:18:49 -05002494 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
Jason Baron56afb0f2009-04-30 13:29:36 -04002495 $tracepointname = $1;
2496 }
Jason Baron3a9089f2009-12-01 12:18:49 -05002497 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2498 $tracepointname = $1;
2499 }
2500 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2501 $tracepointname = $2;
2502 }
2503 $tracepointname =~ s/^\s+//; #strip leading whitespace
2504 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
Jason Baron56afb0f2009-04-30 13:29:36 -04002505 $tracepointargs = $1;
2506 }
2507 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002508 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
Jason Baron56afb0f2009-04-30 13:29:36 -04002509 "$prototype\n";
2510 } else {
2511 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2512 }
2513}
2514
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002515sub syscall_munge() {
2516 my $void = 0;
2517
2518 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2519## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2520 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2521 $void = 1;
2522## $prototype = "long sys_$1(void)";
2523 }
2524
2525 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2526 if ($prototype =~ m/long (sys_.*?),/) {
2527 $prototype =~ s/,/\(/;
2528 } elsif ($void) {
2529 $prototype =~ s/\)/\(void\)/;
2530 }
2531
2532 # now delete all of the odd-number commas in $prototype
2533 # so that arg types & arg names don't have a comma between them
2534 my $count = 0;
2535 my $len = length($prototype);
2536 if ($void) {
2537 $len = 0; # skip the for-loop
2538 }
2539 for (my $ix = 0; $ix < $len; $ix++) {
2540 if (substr($prototype, $ix, 1) eq ',') {
2541 $count++;
2542 if ($count % 2 == 1) {
2543 substr($prototype, $ix, 1) = ' ';
2544 }
2545 }
2546 }
2547}
2548
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002549sub process_state3_function($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002550 my $x = shift;
2551 my $file = shift;
2552
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002553 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2554
Randy Dunlap890c78c2008-10-25 17:06:43 -07002555 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002556 # do nothing
2557 }
2558 elsif ($x =~ /([^\{]*)/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002559 $prototype .= $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002560 }
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002561
Randy Dunlap890c78c2008-10-25 17:06:43 -07002562 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002563 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002564 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2565 $prototype =~ s@^\s+@@gos; # strip leading spaces
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002566 if ($prototype =~ /SYSCALL_DEFINE/) {
2567 syscall_munge();
2568 }
Jason Baron3a9089f2009-12-01 12:18:49 -05002569 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2570 $prototype =~ /DEFINE_SINGLE_EVENT/)
2571 {
Jason Baron56afb0f2009-04-30 13:29:36 -04002572 tracepoint_munge($file);
2573 }
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002574 dump_function($prototype, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002575 reset_state();
2576 }
2577}
2578
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002579sub process_state3_type($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002580 my $x = shift;
2581 my $file = shift;
2582
Linus Torvalds1da177e2005-04-16 15:20:36 -07002583 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2584 $x =~ s@^\s+@@gos; # strip leading spaces
2585 $x =~ s@\s+$@@gos; # strip trailing spaces
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002586 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2587
Linus Torvalds1da177e2005-04-16 15:20:36 -07002588 if ($x =~ /^#/) {
2589 # To distinguish preprocessor directive from regular declaration later.
2590 $x .= ";";
2591 }
2592
2593 while (1) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002594 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002595 $prototype .= $1 . $2;
2596 ($2 eq '{') && $brcount++;
2597 ($2 eq '}') && $brcount--;
2598 if (($2 eq ';') && ($brcount == 0)) {
Randy Dunlapb9d973282009-06-09 08:50:38 -07002599 dump_declaration($prototype, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002600 reset_state();
Randy Dunlap3c308792007-05-08 00:24:39 -07002601 last;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002602 }
2603 $x = $3;
Randy Dunlap3c308792007-05-08 00:24:39 -07002604 } else {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002605 $prototype .= $x;
2606 last;
2607 }
2608 }
2609}
2610
Randy Dunlap6b5b55f2007-10-16 23:31:20 -07002611# xml_escape: replace <, >, and & in the text stream;
2612#
2613# however, formatting controls that are generated internally/locally in the
2614# kernel-doc script are not escaped here; instead, they begin life like
2615# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2616# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2617# just before actual output; (this is done by local_unescape())
Linus Torvalds1da177e2005-04-16 15:20:36 -07002618sub xml_escape($) {
2619 my $text = shift;
Randy Dunlapecfb2512006-06-25 05:49:13 -07002620 if (($output_mode eq "text") || ($output_mode eq "man")) {
2621 return $text;
2622 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002623 $text =~ s/\&/\\\\\\amp;/g;
2624 $text =~ s/\</\\\\\\lt;/g;
2625 $text =~ s/\>/\\\\\\gt;/g;
2626 return $text;
2627}
2628
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03002629# xml_unescape: reverse the effects of xml_escape
2630sub xml_unescape($) {
2631 my $text = shift;
2632 if (($output_mode eq "text") || ($output_mode eq "man")) {
2633 return $text;
2634 }
2635 $text =~ s/\\\\\\amp;/\&/g;
2636 $text =~ s/\\\\\\lt;/</g;
2637 $text =~ s/\\\\\\gt;/>/g;
2638 return $text;
2639}
2640
Randy Dunlap6b5b55f2007-10-16 23:31:20 -07002641# convert local escape strings to html
2642# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2643sub local_unescape($) {
2644 my $text = shift;
2645 if (($output_mode eq "text") || ($output_mode eq "man")) {
2646 return $text;
2647 }
2648 $text =~ s/\\\\\\\\lt:/</g;
2649 $text =~ s/\\\\\\\\gt:/>/g;
2650 return $text;
2651}
2652
Linus Torvalds1da177e2005-04-16 15:20:36 -07002653sub process_file($) {
Randy Dunlap2283a112005-07-07 15:39:26 -07002654 my $file;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002655 my $identifier;
2656 my $func;
Randy Dunlapa21217d2007-02-10 01:46:04 -08002657 my $descr;
Johannes Weiner64231332009-09-17 19:26:53 -07002658 my $in_purpose = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002659 my $initial_section_counter = $section_counter;
Ben Hutchings68f86662015-09-01 23:48:49 +01002660 my ($orig_file) = @_;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002661
Randy Dunlap2283a112005-07-07 15:39:26 -07002662 if (defined($ENV{'SRCTREE'})) {
Ben Hutchings68f86662015-09-01 23:48:49 +01002663 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
Randy Dunlap2283a112005-07-07 15:39:26 -07002664 }
2665 else {
Ben Hutchings68f86662015-09-01 23:48:49 +01002666 $file = $orig_file;
Randy Dunlap2283a112005-07-07 15:39:26 -07002667 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002668 if (defined($source_map{$file})) {
2669 $file = $source_map{$file};
2670 }
2671
2672 if (!open(IN,"<$file")) {
2673 print STDERR "Error: Cannot open file $file\n";
2674 ++$errors;
2675 return;
2676 }
2677
Ilya Dryomova9e73142010-02-26 13:05:47 -08002678 $. = 1;
2679
Linus Torvalds1da177e2005-04-16 15:20:36 -07002680 $section_counter = 0;
2681 while (<IN>) {
Daniel Santos65478422012-10-04 17:15:05 -07002682 while (s/\\\s*$//) {
2683 $_ .= <IN>;
2684 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002685 if ($state == 0) {
2686 if (/$doc_start/o) {
2687 $state = 1; # next line is always the function name
Randy Dunlap850622d2006-06-25 05:48:55 -07002688 $in_doc_sect = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002689 }
2690 } elsif ($state == 1) { # this line is the function name (always)
2691 if (/$doc_block/o) {
2692 $state = 4;
2693 $contents = "";
2694 if ( $1 eq "" ) {
2695 $section = $section_intro;
2696 } else {
2697 $section = $1;
2698 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002699 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002700 elsif (/$doc_decl/o) {
2701 $identifier = $1;
2702 if (/\s*([\w\s]+?)\s*-/) {
2703 $identifier = $1;
2704 }
2705
2706 $state = 2;
2707 if (/-(.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002708 # strip leading/trailing/multiple spaces
Randy Dunlapa21217d2007-02-10 01:46:04 -08002709 $descr= $1;
2710 $descr =~ s/^\s*//;
2711 $descr =~ s/\s*$//;
Daniel Santos12ae6772012-10-04 17:15:10 -07002712 $descr =~ s/\s+/ /g;
Randy Dunlapa21217d2007-02-10 01:46:04 -08002713 $declaration_purpose = xml_escape($descr);
Johannes Weiner64231332009-09-17 19:26:53 -07002714 $in_purpose = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002715 } else {
2716 $declaration_purpose = "";
2717 }
Randy Dunlap77cc23b2008-02-07 00:13:42 -08002718
2719 if (($declaration_purpose eq "") && $verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002720 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
Randy Dunlap77cc23b2008-02-07 00:13:42 -08002721 print STDERR $_;
2722 ++$warnings;
2723 }
2724
Linus Torvalds1da177e2005-04-16 15:20:36 -07002725 if ($identifier =~ m/^struct/) {
2726 $decl_type = 'struct';
2727 } elsif ($identifier =~ m/^union/) {
2728 $decl_type = 'union';
2729 } elsif ($identifier =~ m/^enum/) {
2730 $decl_type = 'enum';
2731 } elsif ($identifier =~ m/^typedef/) {
2732 $decl_type = 'typedef';
2733 } else {
2734 $decl_type = 'function';
2735 }
2736
2737 if ($verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002738 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002739 }
2740 } else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002741 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
Linus Torvalds1da177e2005-04-16 15:20:36 -07002742 " - I thought it was a doc line\n";
2743 ++$warnings;
2744 $state = 0;
2745 }
2746 } elsif ($state == 2) { # look for head: lines, and include content
2747 if (/$doc_sect/o) {
2748 $newsection = $1;
2749 $newcontents = $2;
2750
Randy Dunlap792aa2f2008-02-07 00:13:41 -08002751 if (($contents ne "") && ($contents ne "\n")) {
Randy Dunlap850622d2006-06-25 05:48:55 -07002752 if (!$in_doc_sect && $verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002753 print STDERR "${file}:$.: warning: contents before sections\n";
Randy Dunlap850622d2006-06-25 05:48:55 -07002754 ++$warnings;
2755 }
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002756 dump_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002757 $section = $section_default;
2758 }
2759
Randy Dunlap850622d2006-06-25 05:48:55 -07002760 $in_doc_sect = 1;
Johannes Weiner64231332009-09-17 19:26:53 -07002761 $in_purpose = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002762 $contents = $newcontents;
2763 if ($contents ne "") {
Randy Dunlap27205742006-10-11 01:22:12 -07002764 while ((substr($contents, 0, 1) eq " ") ||
2765 substr($contents, 0, 1) eq "\t") {
2766 $contents = substr($contents, 1);
Randy Dunlap05189492006-06-25 05:47:47 -07002767 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002768 $contents .= "\n";
2769 }
2770 $section = $newsection;
2771 } elsif (/$doc_end/) {
Randy Dunlap4c98eca2010-03-10 15:22:02 -08002772 if (($contents ne "") && ($contents ne "\n")) {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002773 dump_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002774 $section = $section_default;
2775 $contents = "";
2776 }
Randy Dunlap46b958e2008-04-28 02:16:35 -07002777 # look for doc_com + <text> + doc_end:
2778 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002779 print STDERR "${file}:$.: warning: suspicious ending line: $_";
Randy Dunlap46b958e2008-04-28 02:16:35 -07002780 ++$warnings;
2781 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002782
2783 $prototype = "";
2784 $state = 3;
2785 $brcount = 0;
Randy Dunlap232acbc2006-06-25 05:47:48 -07002786# print STDERR "end of doc comment, looking for prototype\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002787 } elsif (/$doc_content/) {
2788 # miguel-style comment kludge, look for blank lines after
2789 # @parameter line to signify start of description
Johannes Weiner64231332009-09-17 19:26:53 -07002790 if ($1 eq "") {
2791 if ($section =~ m/^@/ || $section eq $section_context) {
2792 dump_section($file, $section, xml_escape($contents));
2793 $section = $section_default;
2794 $contents = "";
2795 } else {
2796 $contents .= "\n";
2797 }
2798 $in_purpose = 0;
2799 } elsif ($in_purpose == 1) {
2800 # Continued declaration purpose
2801 chomp($declaration_purpose);
2802 $declaration_purpose .= " " . xml_escape($1);
Daniel Santos12ae6772012-10-04 17:15:10 -07002803 $declaration_purpose =~ s/\s+/ /g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002804 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07002805 $contents .= $1 . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002806 }
2807 } else {
2808 # i dont know - bad line? ignore.
Bart Van Assched40e1e62015-09-04 15:43:21 -07002809 print STDERR "${file}:$.: warning: bad line: $_";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002810 ++$warnings;
2811 }
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002812 } elsif ($state == 5) { # scanning for split parameters
2813 # First line (state 1) needs to be a @parameter
2814 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2815 $section = $1;
2816 $contents = $2;
2817 if ($contents ne "") {
2818 while ((substr($contents, 0, 1) eq " ") ||
2819 substr($contents, 0, 1) eq "\t") {
2820 $contents = substr($contents, 1);
2821 }
2822 $contents .= "\n";
2823 }
2824 $split_doc_state = 2;
2825 # Documentation block end */
2826 } elsif (/$doc_split_end/) {
2827 if (($contents ne "") && ($contents ne "\n")) {
2828 dump_section($file, $section, xml_escape($contents));
2829 $section = $section_default;
2830 $contents = "";
2831 }
2832 $state = 3;
2833 $split_doc_state = 0;
2834 # Regular text
2835 } elsif (/$doc_content/) {
2836 if ($split_doc_state == 2) {
2837 $contents .= $1 . "\n";
2838 } elsif ($split_doc_state == 1) {
2839 $split_doc_state = 4;
2840 print STDERR "Warning(${file}:$.): ";
2841 print STDERR "Incorrect use of kernel-doc format: $_";
2842 ++$warnings;
2843 }
2844 }
Randy Dunlap232acbc2006-06-25 05:47:48 -07002845 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002846 if (/$doc_split_start/) {
2847 $state = 5;
2848 $split_doc_state = 1;
2849 } elsif ($decl_type eq 'function') {
Randy Dunlap3c308792007-05-08 00:24:39 -07002850 process_state3_function($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002851 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -07002852 process_state3_type($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002853 }
2854 } elsif ($state == 4) {
2855 # Documentation block
Randy Dunlap3c308792007-05-08 00:24:39 -07002856 if (/$doc_block/) {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002857 dump_doc_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002858 $contents = "";
2859 $function = "";
2860 %constants = ();
2861 %parameterdescs = ();
2862 %parametertypes = ();
2863 @parameterlist = ();
2864 %sections = ();
2865 @sectionlist = ();
2866 $prototype = "";
2867 if ( $1 eq "" ) {
2868 $section = $section_intro;
2869 } else {
2870 $section = $1;
2871 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002872 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002873 elsif (/$doc_end/)
2874 {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002875 dump_doc_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002876 $contents = "";
2877 $function = "";
2878 %constants = ();
2879 %parameterdescs = ();
2880 %parametertypes = ();
2881 @parameterlist = ();
2882 %sections = ();
2883 @sectionlist = ();
2884 $prototype = "";
2885 $state = 0;
2886 }
2887 elsif (/$doc_content/)
2888 {
2889 if ( $1 eq "" )
2890 {
2891 $contents .= $blankline;
2892 }
2893 else
2894 {
2895 $contents .= $1 . "\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002896 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002897 }
2898 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002899 }
2900 if ($initial_section_counter == $section_counter) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002901 print STDERR "${file}:1: warning: no structured comments found\n";
Johannes Berge946c43a2013-11-12 15:11:12 -08002902 if (($function_only == 1) && ($show_not_found == 1)) {
2903 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2904 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002905 if ($output_mode eq "xml") {
2906 # The template wants at least one RefEntry here; make one.
2907 print "<refentry>\n";
2908 print " <refnamediv>\n";
2909 print " <refname>\n";
Ben Hutchings68f86662015-09-01 23:48:49 +01002910 print " ${orig_file}\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002911 print " </refname>\n";
2912 print " <refpurpose>\n";
2913 print " Document generation inconsistency\n";
2914 print " </refpurpose>\n";
2915 print " </refnamediv>\n";
2916 print " <refsect1>\n";
2917 print " <title>\n";
2918 print " Oops\n";
2919 print " </title>\n";
2920 print " <warning>\n";
2921 print " <para>\n";
2922 print " The template for this document tried to insert\n";
2923 print " the structured comment from the file\n";
Ben Hutchings68f86662015-09-01 23:48:49 +01002924 print " <filename>${orig_file}</filename> at this point,\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002925 print " but none was found.\n";
2926 print " This dummy section is inserted to allow\n";
2927 print " generation to continue.\n";
2928 print " </para>\n";
2929 print " </warning>\n";
2930 print " </refsect1>\n";
2931 print "</refentry>\n";
2932 }
2933 }
2934}
Randy Dunlap8484baa2011-01-05 16:28:43 -08002935
2936
2937$kernelversion = get_kernel_version();
2938
2939# generate a sequence of code that will splice in highlighting information
2940# using the s// operator.
Mauro Carvalho Chehab1ef06232015-11-17 13:29:49 -02002941for (my $k = 0; $k < @highlights; $k++) {
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -03002942 my $pattern = $highlights[$k][0];
2943 my $result = $highlights[$k][1];
2944# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2945 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
Randy Dunlap8484baa2011-01-05 16:28:43 -08002946}
2947
2948# Read the file that maps relative names to absolute names for
2949# separate source and object directories and for shadow trees.
2950if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2951 my ($relname, $absname);
2952 while(<SOURCE_MAP>) {
2953 chop();
2954 ($relname, $absname) = (split())[0..1];
2955 $relname =~ s:^/+::;
2956 $source_map{$relname} = $absname;
2957 }
2958 close(SOURCE_MAP);
2959}
2960
2961foreach (@ARGV) {
2962 chomp;
2963 process_file($_);
2964}
2965if ($verbose && $errors) {
2966 print STDERR "$errors errors\n";
2967}
2968if ($verbose && $warnings) {
2969 print STDERR "$warnings warnings\n";
2970}
2971
2972exit($errors);