blob: cb5fd248ac57e3b39c2d88c6c744ebd092d07790 [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):
Jani Nikula86ae2e32016-01-21 13:05:22 +020062 -export Only output documentation for symbols that have been
63 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
64 in the same FILE.
65 -internal Only output documentation for symbols that have NOT been
66 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
67 in the same FILE.
Jani Nikulafadc0b32016-05-12 16:15:36 +030068 -function NAME Only output documentation for the given function(s)
69 or DOC: section title(s). All other functions and DOC:
70 sections are ignored. May be specified multiple times.
71 -nofunction NAME Do NOT output documentation for the given function(s);
72 only output documentation for the other functions and
73 DOC: sections. May be specified multiple times.
74
75Output selection modifiers:
76 -no-doc-sections Do not output DOC: sections.
77
78Other parameters:
79 -v Verbose output, more warnings and other information.
80 -h Print this help.
81
82EOF
83 print $message;
84 exit 1;
85}
Linus Torvalds1da177e2005-04-16 15:20:36 -070086
87#
88# format of comments.
89# In the following table, (...)? signifies optional structure.
90# (...)* signifies 0 or more structure elements
91# /**
92# * function_name(:)? (- short description)?
93# (* @parameterx: (description of parameter x)?)*
94# (* a blank line)?
95# * (Description:)? (Description of function)?
96# * (section header: (section description)? )*
97# (*)?*/
98#
99# So .. the trivial example would be:
100#
101# /**
102# * my_function
Randy Dunlapb9d973282009-06-09 08:50:38 -0700103# */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700104#
Randy Dunlap891dcd22007-02-10 01:45:53 -0800105# If the Description: header tag is omitted, then there must be a blank line
Linus Torvalds1da177e2005-04-16 15:20:36 -0700106# after the last parameter specification.
107# e.g.
108# /**
109# * my_function - does my stuff
110# * @my_arg: its mine damnit
111# *
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800112# * Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700113# */
114#
115# or, could also use:
116# /**
117# * my_function - does my stuff
118# * @my_arg: its mine damnit
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800119# * Description: Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700120# */
121# etc.
122#
Randy Dunlapb9d973282009-06-09 08:50:38 -0700123# Besides functions you can also write documentation for structs, unions,
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800124# enums and typedefs. Instead of the function name you must write the name
125# of the declaration; the struct/union/enum/typedef must always precede
126# the name. Nesting of declarations is not supported.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700127# Use the argument mechanism to document members or constants.
128# e.g.
129# /**
130# * struct my_struct - short description
131# * @a: first member
132# * @b: second member
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800133# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700134# * Longer description
135# */
136# struct my_struct {
137# int a;
138# int b;
Martin Waitzaeec46b2005-11-13 16:08:13 -0800139# /* private: */
140# int c;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141# };
142#
143# All descriptions can be multiline, except the short function description.
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800144#
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300145# For really longs structs, you can also describe arguments inside the
146# body of the struct.
147# eg.
148# /**
149# * struct my_struct - short description
150# * @a: first member
151# * @b: second member
152# *
153# * Longer description
154# */
155# struct my_struct {
156# int a;
157# int b;
158# /**
159# * @c: This is longer description of C
160# *
161# * You can use paragraphs to describe arguments
162# * using this method.
163# */
164# int c;
165# };
166#
167# This should be use only for struct/enum members.
168#
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800169# You can also add additional sections. When documenting kernel functions you
170# should document the "Context:" of the function, e.g. whether the functions
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171# can be called form interrupts. Unlike other sections you can end it with an
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800172# empty line.
Yacine Belkadi4092bac2012-11-26 22:22:27 +0100173# A non-void function should have a "Return:" section describing the return
174# value(s).
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800175# Example-sections should contain the string EXAMPLE so that they are marked
Linus Torvalds1da177e2005-04-16 15:20:36 -0700176# appropriately in DocBook.
177#
178# Example:
179# /**
180# * user_function - function that can only be called in user context
181# * @a: some argument
182# * Context: !in_interrupt()
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800183# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700184# * Some description
185# * Example:
186# * user_function(22);
187# */
188# ...
189#
190#
191# All descriptive text is further processed, scanning for the following special
192# patterns, which are highlighted appropriately.
193#
194# 'funcname()' - function
195# '$ENVVAR' - environmental variable
196# '&struct_name' - name of a structure (up to two words including 'struct')
197# '@parameter' - name of a parameter
198# '%CONST' - name of a constant.
199
Randy Dunlap8484baa2011-01-05 16:28:43 -0800200## init lots of data
201
Linus Torvalds1da177e2005-04-16 15:20:36 -0700202my $errors = 0;
203my $warnings = 0;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -0700204my $anon_struct_union = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700205
206# match expressions used to find embedded type information
207my $type_constant = '\%([-_\w]+)';
208my $type_func = '(\w+)\(\)';
209my $type_param = '\@(\w+)';
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700210my $type_struct = '\&((struct\s*)*[_\w]+)';
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700211my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700212my $type_env = '(\$\w+)';
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300213my $type_enum_full = '\&(enum)\s*([_\w]+)';
214my $type_struct_full = '\&(struct)\s*([_\w]+)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700215
216# Output conversion substitutions.
217# One for each output format
218
219# these work fairly well
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300220my @highlights_html = (
221 [$type_constant, "<i>\$1</i>"],
222 [$type_func, "<b>\$1</b>"],
223 [$type_struct_xml, "<i>\$1</i>"],
224 [$type_env, "<b><i>\$1</i></b>"],
225 [$type_param, "<tt><b>\$1</b></tt>"]
226 );
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700227my $local_lt = "\\\\\\\\lt:";
228my $local_gt = "\\\\\\\\gt:";
229my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
Linus Torvalds1da177e2005-04-16 15:20:36 -0700230
Dan Luedtke1b40c192012-08-12 10:46:15 +0200231# html version 5
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300232my @highlights_html5 = (
233 [$type_constant, "<span class=\"const\">\$1</span>"],
234 [$type_func, "<span class=\"func\">\$1</span>"],
235 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
236 [$type_env, "<span class=\"env\">\$1</span>"],
237 [$type_param, "<span class=\"param\">\$1</span>]"]
238 );
Dan Luedtke1b40c192012-08-12 10:46:15 +0200239my $blankline_html5 = $local_lt . "br /" . $local_gt;
240
Linus Torvalds1da177e2005-04-16 15:20:36 -0700241# XML, docbook format
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300242my @highlights_xml = (
243 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
244 [$type_constant, "<constant>\$1</constant>"],
245 [$type_struct_xml, "<structname>\$1</structname>"],
246 [$type_param, "<parameter>\$1</parameter>"],
247 [$type_func, "<function>\$1</function>"],
248 [$type_env, "<envar>\$1</envar>"]
249 );
Johannes Berg5c98fc02007-10-24 15:08:48 -0700250my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700251
252# gnome, docbook format
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300253my @highlights_gnome = (
254 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
255 [$type_func, "<function>\$1</function>"],
256 [$type_struct, "<structname>\$1</structname>"],
257 [$type_env, "<envar>\$1</envar>"],
258 [$type_param, "<parameter>\$1</parameter>" ]
259 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700260my $blankline_gnome = "</para><para>\n";
261
262# these are pretty rough
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300263my @highlights_man = (
264 [$type_constant, "\$1"],
265 [$type_func, "\\\\fB\$1\\\\fP"],
266 [$type_struct, "\\\\fI\$1\\\\fP"],
267 [$type_param, "\\\\fI\$1\\\\fP"]
268 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269my $blankline_man = "";
270
271# text-mode
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300272my @highlights_text = (
273 [$type_constant, "\$1"],
274 [$type_func, "\$1"],
275 [$type_struct, "\$1"],
276 [$type_param, "\$1"]
277 );
Linus Torvalds1da177e2005-04-16 15:20:36 -0700278my $blankline_text = "";
279
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300280# rst-mode
281my @highlights_rst = (
282 [$type_constant, "``\$1``"],
283 [$type_func, "\\:c\\:func\\:`\$1`"],
Jani Nikula62850972016-05-12 16:15:38 +0300284 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
285 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
286 [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300287 [$type_param, "**\$1**"]
288 );
289my $blankline_rst = "\n";
290
Johannes Bergeda603f2010-09-11 15:55:22 -0700291# list mode
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300292my @highlights_list = (
293 [$type_constant, "\$1"],
294 [$type_func, "\$1"],
295 [$type_struct, "\$1"],
296 [$type_param, "\$1"]
297 );
Johannes Bergeda603f2010-09-11 15:55:22 -0700298my $blankline_list = "";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700299
Linus Torvalds1da177e2005-04-16 15:20:36 -0700300# read arguments
Randy Dunlapb9d973282009-06-09 08:50:38 -0700301if ($#ARGV == -1) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700302 usage();
303}
304
Randy Dunlap8484baa2011-01-05 16:28:43 -0800305my $kernelversion;
306my $dohighlight = "";
307
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308my $verbose = 0;
309my $output_mode = "man";
Daniel Santose314ba32012-10-04 17:15:08 -0700310my $output_preformatted = 0;
Johannes Berg4b445952007-10-24 15:08:48 -0700311my $no_doc_sections = 0;
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300312my @highlights = @highlights_man;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700313my $blankline = $blankline_man;
314my $modulename = "Kernel API";
315my $function_only = 0;
Ben Hutchingsb2c41052015-07-08 20:07:16 +0100316my $show_not_found = 0;
317
318my @build_time;
319if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
320 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
321 @build_time = gmtime($seconds);
322} else {
323 @build_time = localtime;
324}
325
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800326my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
327 'July', 'August', 'September', 'October',
Ben Hutchingsb2c41052015-07-08 20:07:16 +0100328 'November', 'December')[$build_time[4]] .
329 " " . ($build_time[5]+1900);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700330
Randy Dunlap8484baa2011-01-05 16:28:43 -0800331# Essentially these are globals.
Randy Dunlapb9d973282009-06-09 08:50:38 -0700332# They probably want to be tidied up, made more localised or something.
333# CAVEAT EMPTOR! Some of the others I localised may not want to be, which
Linus Torvalds1da177e2005-04-16 15:20:36 -0700334# could cause "use of undefined value" or other bugs.
Randy Dunlapb9d973282009-06-09 08:50:38 -0700335my ($function, %function_table, %parametertypes, $declaration_purpose);
336my ($type, $declaration_name, $return_type);
Ilya Dryomov1c32fd02010-02-26 13:06:03 -0800337my ($newsection, $newcontents, $prototype, $brcount, %source_map);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700338
Randy Dunlapbd0e88e2008-03-13 12:32:43 -0700339if (defined($ENV{'KBUILD_VERBOSE'})) {
340 $verbose = "$ENV{'KBUILD_VERBOSE'}";
341}
342
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800343# Generated docbook code is inserted in a template at a point where
Linus Torvalds1da177e2005-04-16 15:20:36 -0700344# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
345# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
346# We keep track of number of generated entries and generate a dummy
347# if needs be to ensure the expanded template can be postprocessed
348# into html.
349my $section_counter = 0;
350
351my $lineprefix="";
352
Jani Nikula48af6062016-05-26 14:56:05 +0300353# Parser states
354use constant {
355 STATE_NORMAL => 0, # normal code
356 STATE_NAME => 1, # looking for function name
357 STATE_FIELD => 2, # scanning field start
358 STATE_PROTO => 3, # scanning prototype
359 STATE_DOCBLOCK => 4, # documentation block
360 STATE_INLINE => 5, # gathering documentation outside main block
361};
Linus Torvalds1da177e2005-04-16 15:20:36 -0700362my $state;
Randy Dunlap850622d2006-06-25 05:48:55 -0700363my $in_doc_sect;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700364
Jani Nikula48af6062016-05-26 14:56:05 +0300365# Inline documentation state
366use constant {
367 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
368 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
369 STATE_INLINE_TEXT => 2, # looking for member documentation
370 STATE_INLINE_END => 3, # done
371 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
372 # Spit a warning as it's not
373 # proper kernel-doc and ignore the rest.
374};
375my $inline_doc_state;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -0300376
Linus Torvalds1da177e2005-04-16 15:20:36 -0700377#declaration types: can be
378# 'function', 'struct', 'union', 'enum', 'typedef'
379my $decl_type;
380
381my $doc_special = "\@\%\$\&";
382
383my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
384my $doc_end = '\*/';
385my $doc_com = '\s*\*\s*';
Daniel Santos12ae6772012-10-04 17:15:10 -0700386my $doc_com_body = '\s*\* ?';
Randy Dunlapb9d973282009-06-09 08:50:38 -0700387my $doc_decl = $doc_com . '(\w+)';
388my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
Daniel Santos12ae6772012-10-04 17:15:10 -0700389my $doc_content = $doc_com_body . '(.*)';
Randy Dunlapb9d973282009-06-09 08:50:38 -0700390my $doc_block = $doc_com . 'DOC:\s*(.*)?';
Jani Nikula48af6062016-05-26 14:56:05 +0300391my $doc_inline_start = '^\s*/\*\*\s*$';
392my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
393my $doc_inline_end = '^\s*\*/\s*$';
Jani Nikula86ae2e32016-01-21 13:05:22 +0200394my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700395
396my %constants;
397my %parameterdescs;
398my @parameterlist;
399my %sections;
400my @sectionlist;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800401my $sectcheck;
402my $struct_actual;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700403
404my $contents = "";
405my $section_default = "Description"; # default section
406my $section_intro = "Introduction";
407my $section = $section_default;
408my $section_context = "Context";
Yacine Belkadi4092bac2012-11-26 22:22:27 +0100409my $section_return = "Return";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700410
411my $undescribed = "-- undescribed --";
412
413reset_state();
414
415while ($ARGV[0] =~ m/^-(.*)/) {
416 my $cmd = shift @ARGV;
417 if ($cmd eq "-html") {
418 $output_mode = "html";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300419 @highlights = @highlights_html;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700420 $blankline = $blankline_html;
Dan Luedtke1b40c192012-08-12 10:46:15 +0200421 } elsif ($cmd eq "-html5") {
422 $output_mode = "html5";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300423 @highlights = @highlights_html5;
Dan Luedtke1b40c192012-08-12 10:46:15 +0200424 $blankline = $blankline_html5;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700425 } elsif ($cmd eq "-man") {
426 $output_mode = "man";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300427 @highlights = @highlights_man;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700428 $blankline = $blankline_man;
429 } elsif ($cmd eq "-text") {
430 $output_mode = "text";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300431 @highlights = @highlights_text;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700432 $blankline = $blankline_text;
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +0300433 } elsif ($cmd eq "-rst") {
434 $output_mode = "rst";
435 @highlights = @highlights_rst;
436 $blankline = $blankline_rst;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700437 } elsif ($cmd eq "-docbook") {
438 $output_mode = "xml";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300439 @highlights = @highlights_xml;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700440 $blankline = $blankline_xml;
Johannes Bergeda603f2010-09-11 15:55:22 -0700441 } elsif ($cmd eq "-list") {
442 $output_mode = "list";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300443 @highlights = @highlights_list;
Johannes Bergeda603f2010-09-11 15:55:22 -0700444 $blankline = $blankline_list;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700445 } elsif ($cmd eq "-gnome") {
446 $output_mode = "gnome";
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -0300447 @highlights = @highlights_gnome;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700448 $blankline = $blankline_gnome;
449 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
450 $modulename = shift @ARGV;
451 } elsif ($cmd eq "-function") { # to only output specific functions
452 $function_only = 1;
453 $function = shift @ARGV;
454 $function_table{$function} = 1;
455 } elsif ($cmd eq "-nofunction") { # to only output specific functions
456 $function_only = 2;
457 $function = shift @ARGV;
458 $function_table{$function} = 1;
Jani Nikula86ae2e32016-01-21 13:05:22 +0200459 } elsif ($cmd eq "-export") { # only exported symbols
460 $function_only = 3;
461 %function_table = ()
462 } elsif ($cmd eq "-internal") { # only non-exported symbols
463 $function_only = 4;
464 %function_table = ()
Linus Torvalds1da177e2005-04-16 15:20:36 -0700465 } elsif ($cmd eq "-v") {
466 $verbose = 1;
467 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
468 usage();
Johannes Berg4b445952007-10-24 15:08:48 -0700469 } elsif ($cmd eq '-no-doc-sections') {
470 $no_doc_sections = 1;
Johannes Berge946c43a2013-11-12 15:11:12 -0800471 } elsif ($cmd eq '-show-not-found') {
472 $show_not_found = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700473 }
474}
475
Randy Dunlap8484baa2011-01-05 16:28:43 -0800476# continue execution near EOF;
477
Borislav Petkov53f049f2007-05-08 00:30:54 -0700478# get kernel version from env
479sub get_kernel_version() {
Johannes Berg1b9bc222007-10-24 15:08:48 -0700480 my $version = 'unknown kernel version';
Borislav Petkov53f049f2007-05-08 00:30:54 -0700481
482 if (defined($ENV{'KERNELVERSION'})) {
483 $version = $ENV{'KERNELVERSION'};
484 }
485 return $version;
486}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700487
488##
489# dumps section contents to arrays/hashes intended for that purpose.
490#
491sub dump_section {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700492 my $file = shift;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700493 my $name = shift;
494 my $contents = join "\n", @_;
495
496 if ($name =~ m/$type_constant/) {
497 $name = $1;
498# print STDERR "constant section '$1' = '$contents'\n";
499 $constants{$name} = $contents;
500 } elsif ($name =~ m/$type_param/) {
501# print STDERR "parameter def '$1' = '$contents'\n";
502 $name = $1;
503 $parameterdescs{$name} = $contents;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800504 $sectcheck = $sectcheck . $name . " ";
Randy Dunlapced69092008-12-01 13:14:03 -0800505 } elsif ($name eq "@\.\.\.") {
506# print STDERR "parameter def '...' = '$contents'\n";
507 $name = "...";
508 $parameterdescs{$name} = $contents;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -0800509 $sectcheck = $sectcheck . $name . " ";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700510 } else {
511# print STDERR "other section '$name' = '$contents'\n";
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700512 if (defined($sections{$name}) && ($sections{$name} ne "")) {
Bart Van Assched40e1e62015-09-04 15:43:21 -0700513 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700514 ++$errors;
515 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700516 $sections{$name} = $contents;
517 push @sectionlist, $name;
518 }
519}
520
521##
Johannes Bergb112e0f2007-10-24 15:08:48 -0700522# dump DOC: section after checking that it should go out
523#
524sub dump_doc_section {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700525 my $file = shift;
Johannes Bergb112e0f2007-10-24 15:08:48 -0700526 my $name = shift;
527 my $contents = join "\n", @_;
528
Johannes Berg4b445952007-10-24 15:08:48 -0700529 if ($no_doc_sections) {
530 return;
531 }
532
Johannes Bergb112e0f2007-10-24 15:08:48 -0700533 if (($function_only == 0) ||
534 ( $function_only == 1 && defined($function_table{$name})) ||
535 ( $function_only == 2 && !defined($function_table{$name})))
536 {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -0700537 dump_section($file, $name, $contents);
Johannes Bergb112e0f2007-10-24 15:08:48 -0700538 output_blockhead({'sectionlist' => \@sectionlist,
539 'sections' => \%sections,
540 'module' => $modulename,
541 'content-only' => ($function_only != 0), });
542 }
543}
544
545##
Linus Torvalds1da177e2005-04-16 15:20:36 -0700546# output function
547#
548# parameterdescs, a hash.
549# function => "function name"
550# parameterlist => @list of parameters
551# parameterdescs => %parameter descriptions
552# sectionlist => @list of sections
Randy Dunlapa21217d2007-02-10 01:46:04 -0800553# sections => %section descriptions
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800554#
Linus Torvalds1da177e2005-04-16 15:20:36 -0700555
556sub output_highlight {
557 my $contents = join "\n",@_;
558 my $line;
559
560# DEBUG
561# if (!defined $contents) {
562# use Carp;
563# confess "output_highlight got called with no args?\n";
564# }
565
Dan Luedtke1b40c192012-08-12 10:46:15 +0200566 if ($output_mode eq "html" || $output_mode eq "html5" ||
567 $output_mode eq "xml") {
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700568 $contents = local_unescape($contents);
569 # convert data read & converted thru xml_escape() into &xyz; format:
Randy Dunlap2b35f4d2010-11-18 12:27:31 -0800570 $contents =~ s/\\\\\\/\&/g;
Randy Dunlap6b5b55f2007-10-16 23:31:20 -0700571 }
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700572# print STDERR "contents b4:$contents\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700573 eval $dohighlight;
574 die $@ if $@;
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700575# print STDERR "contents af:$contents\n";
576
Dan Luedtke1b40c192012-08-12 10:46:15 +0200577# strip whitespaces when generating html5
578 if ($output_mode eq "html5") {
579 $contents =~ s/^\s+//;
580 $contents =~ s/\s+$//;
581 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700582 foreach $line (split "\n", $contents) {
Daniel Santos12ae6772012-10-04 17:15:10 -0700583 if (! $output_preformatted) {
584 $line =~ s/^\s*//;
585 }
Randy Dunlap3c308792007-05-08 00:24:39 -0700586 if ($line eq ""){
Daniel Santose314ba32012-10-04 17:15:08 -0700587 if (! $output_preformatted) {
588 print $lineprefix, local_unescape($blankline);
589 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700590 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -0700591 $line =~ s/\\\\\\/\&/g;
Randy Dunlapcdccb312007-07-19 01:48:25 -0700592 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
593 print "\\&$line";
594 } else {
595 print $lineprefix, $line;
596 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700597 }
598 print "\n";
599 }
600}
601
Dan Luedtke1b40c192012-08-12 10:46:15 +0200602# output sections in html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700603sub output_section_html(%) {
604 my %args = %{$_[0]};
605 my $section;
606
607 foreach $section (@{$args{'sectionlist'}}) {
608 print "<h3>$section</h3>\n";
609 print "<blockquote>\n";
610 output_highlight($args{'sections'}{$section});
611 print "</blockquote>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800612 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700613}
614
615# output enum in html
616sub output_enum_html(%) {
617 my %args = %{$_[0]};
618 my ($parameter);
619 my $count;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700620 print "<h2>enum " . $args{'enum'} . "</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700621
Randy Dunlapb9d973282009-06-09 08:50:38 -0700622 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700623 $count = 0;
624 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700625 print " <b>" . $parameter . "</b>";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700626 if ($count != $#{$args{'parameterlist'}}) {
627 $count++;
628 print ",\n";
629 }
630 print "<br>";
631 }
632 print "};<br>\n";
633
634 print "<h3>Constants</h3>\n";
635 print "<dl>\n";
636 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700637 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700638 print "<dd>";
639 output_highlight($args{'parameterdescs'}{$parameter});
640 }
641 print "</dl>\n";
642 output_section_html(@_);
643 print "<hr>\n";
644}
645
Randy Dunlapd28bee02006-02-01 03:06:57 -0800646# output typedef in html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700647sub output_typedef_html(%) {
648 my %args = %{$_[0]};
649 my ($parameter);
650 my $count;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700651 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700652
Randy Dunlapb9d973282009-06-09 08:50:38 -0700653 print "<b>typedef " . $args{'typedef'} . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700654 output_section_html(@_);
655 print "<hr>\n";
656}
657
658# output struct in html
659sub output_struct_html(%) {
660 my %args = %{$_[0]};
661 my ($parameter);
662
Randy Dunlapb9d973282009-06-09 08:50:38 -0700663 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
664 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700665 foreach $parameter (@{$args{'parameterlist'}}) {
666 if ($parameter =~ /^#/) {
667 print "$parameter<br>\n";
668 next;
669 }
670 my $parameter_name = $parameter;
671 $parameter_name =~ s/\[.*//;
672
Randy Dunlap3c308792007-05-08 00:24:39 -0700673 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700674 $type = $args{'parametertypes'}{$parameter};
675 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
676 # pointer-to-function
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700677 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700678 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700679 # bitfield
680 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700681 } else {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700682 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700683 }
684 }
685 print "};<br>\n";
686
687 print "<h3>Members</h3>\n";
688 print "<dl>\n";
689 foreach $parameter (@{$args{'parameterlist'}}) {
690 ($parameter =~ /^#/) && next;
691
692 my $parameter_name = $parameter;
693 $parameter_name =~ s/\[.*//;
694
Randy Dunlap3c308792007-05-08 00:24:39 -0700695 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700696 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700697 print "<dd>";
698 output_highlight($args{'parameterdescs'}{$parameter_name});
699 }
700 print "</dl>\n";
701 output_section_html(@_);
702 print "<hr>\n";
703}
704
705# output function in html
706sub output_function_html(%) {
707 my %args = %{$_[0]};
708 my ($parameter, $section);
709 my $count;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700710
Randy Dunlapb9d973282009-06-09 08:50:38 -0700711 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
712 print "<i>" . $args{'functiontype'} . "</i>\n";
713 print "<b>" . $args{'function'} . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700714 print "(";
715 $count = 0;
716 foreach $parameter (@{$args{'parameterlist'}}) {
717 $type = $args{'parametertypes'}{$parameter};
718 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
719 # pointer-to-function
720 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
721 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -0700722 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700723 }
724 if ($count != $#{$args{'parameterlist'}}) {
725 $count++;
726 print ",\n";
727 }
728 }
729 print ")\n";
730
731 print "<h3>Arguments</h3>\n";
732 print "<dl>\n";
733 foreach $parameter (@{$args{'parameterlist'}}) {
734 my $parameter_name = $parameter;
735 $parameter_name =~ s/\[.*//;
736
Randy Dunlap3c308792007-05-08 00:24:39 -0700737 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -0700738 print "<dt><b>" . $parameter . "</b>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700739 print "<dd>";
740 output_highlight($args{'parameterdescs'}{$parameter_name});
741 }
742 print "</dl>\n";
743 output_section_html(@_);
744 print "<hr>\n";
745}
746
Johannes Bergb112e0f2007-10-24 15:08:48 -0700747# output DOC: block header in html
748sub output_blockhead_html(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700749 my %args = %{$_[0]};
750 my ($parameter, $section);
751 my $count;
752
753 foreach $section (@{$args{'sectionlist'}}) {
754 print "<h3>$section</h3>\n";
755 print "<ul>\n";
756 output_highlight($args{'sections'}{$section});
757 print "</ul>\n";
758 }
759 print "<hr>\n";
760}
761
Dan Luedtke1b40c192012-08-12 10:46:15 +0200762# output sections in html5
763sub output_section_html5(%) {
764 my %args = %{$_[0]};
765 my $section;
766
767 foreach $section (@{$args{'sectionlist'}}) {
768 print "<section>\n";
769 print "<h1>$section</h1>\n";
770 print "<p>\n";
771 output_highlight($args{'sections'}{$section});
772 print "</p>\n";
773 print "</section>\n";
774 }
775}
776
777# output enum in html5
778sub output_enum_html5(%) {
779 my %args = %{$_[0]};
780 my ($parameter);
781 my $count;
782 my $html5id;
783
784 $html5id = $args{'enum'};
785 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
786 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
787 print "<h1>enum " . $args{'enum'} . "</h1>\n";
788 print "<ol class=\"code\">\n";
789 print "<li>";
790 print "<span class=\"keyword\">enum</span> ";
791 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
792 print "</li>\n";
793 $count = 0;
794 foreach $parameter (@{$args{'parameterlist'}}) {
795 print "<li class=\"indent\">";
796 print "<span class=\"param\">" . $parameter . "</span>";
797 if ($count != $#{$args{'parameterlist'}}) {
798 $count++;
799 print ",";
800 }
801 print "</li>\n";
802 }
803 print "<li>};</li>\n";
804 print "</ol>\n";
805
806 print "<section>\n";
807 print "<h1>Constants</h1>\n";
808 print "<dl>\n";
809 foreach $parameter (@{$args{'parameterlist'}}) {
810 print "<dt>" . $parameter . "</dt>\n";
811 print "<dd>";
812 output_highlight($args{'parameterdescs'}{$parameter});
813 print "</dd>\n";
814 }
815 print "</dl>\n";
816 print "</section>\n";
817 output_section_html5(@_);
818 print "</article>\n";
819}
820
821# output typedef in html5
822sub output_typedef_html5(%) {
823 my %args = %{$_[0]};
824 my ($parameter);
825 my $count;
826 my $html5id;
827
828 $html5id = $args{'typedef'};
829 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
830 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
831 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
832
833 print "<ol class=\"code\">\n";
834 print "<li>";
835 print "<span class=\"keyword\">typedef</span> ";
836 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
837 print "</li>\n";
838 print "</ol>\n";
839 output_section_html5(@_);
840 print "</article>\n";
841}
842
843# output struct in html5
844sub output_struct_html5(%) {
845 my %args = %{$_[0]};
846 my ($parameter);
847 my $html5id;
848
849 $html5id = $args{'struct'};
850 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
851 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
852 print "<hgroup>\n";
853 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
854 print "<h2>". $args{'purpose'} . "</h2>\n";
855 print "</hgroup>\n";
856 print "<ol class=\"code\">\n";
857 print "<li>";
858 print "<span class=\"type\">" . $args{'type'} . "</span> ";
859 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
860 print "</li>\n";
861 foreach $parameter (@{$args{'parameterlist'}}) {
862 print "<li class=\"indent\">";
863 if ($parameter =~ /^#/) {
864 print "<span class=\"param\">" . $parameter ."</span>\n";
865 print "</li>\n";
866 next;
867 }
868 my $parameter_name = $parameter;
869 $parameter_name =~ s/\[.*//;
870
871 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
872 $type = $args{'parametertypes'}{$parameter};
873 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
874 # pointer-to-function
875 print "<span class=\"type\">$1</span> ";
876 print "<span class=\"param\">$parameter</span>";
877 print "<span class=\"type\">)</span> ";
878 print "(<span class=\"args\">$2</span>);";
879 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
880 # bitfield
881 print "<span class=\"type\">$1</span> ";
882 print "<span class=\"param\">$parameter</span>";
883 print "<span class=\"bits\">$2</span>;";
884 } else {
885 print "<span class=\"type\">$type</span> ";
886 print "<span class=\"param\">$parameter</span>;";
887 }
888 print "</li>\n";
889 }
890 print "<li>};</li>\n";
891 print "</ol>\n";
892
893 print "<section>\n";
894 print "<h1>Members</h1>\n";
895 print "<dl>\n";
896 foreach $parameter (@{$args{'parameterlist'}}) {
897 ($parameter =~ /^#/) && next;
898
899 my $parameter_name = $parameter;
900 $parameter_name =~ s/\[.*//;
901
902 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
903 print "<dt>" . $parameter . "</dt>\n";
904 print "<dd>";
905 output_highlight($args{'parameterdescs'}{$parameter_name});
906 print "</dd>\n";
907 }
908 print "</dl>\n";
909 print "</section>\n";
910 output_section_html5(@_);
911 print "</article>\n";
912}
913
914# output function in html5
915sub output_function_html5(%) {
916 my %args = %{$_[0]};
917 my ($parameter, $section);
918 my $count;
919 my $html5id;
920
921 $html5id = $args{'function'};
922 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
923 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
924 print "<hgroup>\n";
925 print "<h1>" . $args{'function'} . "</h1>";
926 print "<h2>" . $args{'purpose'} . "</h2>\n";
927 print "</hgroup>\n";
928 print "<ol class=\"code\">\n";
929 print "<li>";
930 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
931 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
932 print "</li>";
933 $count = 0;
934 foreach $parameter (@{$args{'parameterlist'}}) {
935 print "<li class=\"indent\">";
936 $type = $args{'parametertypes'}{$parameter};
937 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
938 # pointer-to-function
939 print "<span class=\"type\">$1</span> ";
940 print "<span class=\"param\">$parameter</span>";
941 print "<span class=\"type\">)</span> ";
942 print "(<span class=\"args\">$2</span>)";
943 } else {
944 print "<span class=\"type\">$type</span> ";
945 print "<span class=\"param\">$parameter</span>";
946 }
947 if ($count != $#{$args{'parameterlist'}}) {
948 $count++;
949 print ",";
950 }
951 print "</li>\n";
952 }
953 print "<li>)</li>\n";
954 print "</ol>\n";
955
956 print "<section>\n";
957 print "<h1>Arguments</h1>\n";
958 print "<p>\n";
959 print "<dl>\n";
960 foreach $parameter (@{$args{'parameterlist'}}) {
961 my $parameter_name = $parameter;
962 $parameter_name =~ s/\[.*//;
963
964 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
965 print "<dt>" . $parameter . "</dt>\n";
966 print "<dd>";
967 output_highlight($args{'parameterdescs'}{$parameter_name});
968 print "</dd>\n";
969 }
970 print "</dl>\n";
971 print "</section>\n";
972 output_section_html5(@_);
973 print "</article>\n";
974}
975
976# output DOC: block header in html5
977sub output_blockhead_html5(%) {
978 my %args = %{$_[0]};
979 my ($parameter, $section);
980 my $count;
981 my $html5id;
982
983 foreach $section (@{$args{'sectionlist'}}) {
984 $html5id = $section;
985 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
986 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
987 print "<h1>$section</h1>\n";
988 print "<p>\n";
989 output_highlight($args{'sections'}{$section});
990 print "</p>\n";
991 }
992 print "</article>\n";
993}
994
Linus Torvalds1da177e2005-04-16 15:20:36 -0700995sub output_section_xml(%) {
996 my %args = %{$_[0]};
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800997 my $section;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700998 # print out each section
999 $lineprefix=" ";
1000 foreach $section (@{$args{'sectionlist'}}) {
Rich Walkerc73894c2005-05-01 08:59:26 -07001001 print "<refsect1>\n";
1002 print "<title>$section</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001003 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -07001004 print "<informalexample><programlisting>\n";
Daniel Santose314ba32012-10-04 17:15:08 -07001005 $output_preformatted = 1;
Rich Walkerc73894c2005-05-01 08:59:26 -07001006 } else {
1007 print "<para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001008 }
1009 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -07001010 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001011 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -07001012 print "</programlisting></informalexample>\n";
1013 } else {
1014 print "</para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001015 }
Rich Walkerc73894c2005-05-01 08:59:26 -07001016 print "</refsect1>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001017 }
1018}
1019
1020# output function in XML DocBook
1021sub output_function_xml(%) {
1022 my %args = %{$_[0]};
1023 my ($parameter, $section);
1024 my $count;
1025 my $id;
1026
Randy Dunlapb9d973282009-06-09 08:50:38 -07001027 $id = "API-" . $args{'function'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001028 $id =~ s/[^A-Za-z0-9]/-/g;
1029
Pavel Pisa5449bc92007-02-10 01:45:37 -08001030 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001031 print "<refentryinfo>\n";
1032 print " <title>LINUX</title>\n";
1033 print " <productname>Kernel Hackers Manual</productname>\n";
1034 print " <date>$man_date</date>\n";
1035 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001036 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001037 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001038 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001039 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001040 print "</refmeta>\n";
1041 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001042 print " <refname>" . $args{'function'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001043 print " <refpurpose>\n";
1044 print " ";
1045 output_highlight ($args{'purpose'});
1046 print " </refpurpose>\n";
1047 print "</refnamediv>\n";
1048
1049 print "<refsynopsisdiv>\n";
1050 print " <title>Synopsis</title>\n";
1051 print " <funcsynopsis><funcprototype>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001052 print " <funcdef>" . $args{'functiontype'} . " ";
1053 print "<function>" . $args{'function'} . " </function></funcdef>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001054
1055 $count = 0;
1056 if ($#{$args{'parameterlist'}} >= 0) {
1057 foreach $parameter (@{$args{'parameterlist'}}) {
1058 $type = $args{'parametertypes'}{$parameter};
1059 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1060 # pointer-to-function
1061 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
1062 print " <funcparams>$2</funcparams></paramdef>\n";
1063 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001064 print " <paramdef>" . $type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001065 print " <parameter>$parameter</parameter></paramdef>\n";
1066 }
1067 }
1068 } else {
Martin Waitz6013d542005-05-01 08:59:25 -07001069 print " <void/>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001070 }
1071 print " </funcprototype></funcsynopsis>\n";
1072 print "</refsynopsisdiv>\n";
1073
1074 # print parameters
1075 print "<refsect1>\n <title>Arguments</title>\n";
1076 if ($#{$args{'parameterlist'}} >= 0) {
1077 print " <variablelist>\n";
1078 foreach $parameter (@{$args{'parameterlist'}}) {
1079 my $parameter_name = $parameter;
1080 $parameter_name =~ s/\[.*//;
1081
1082 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1083 print " <listitem>\n <para>\n";
1084 $lineprefix=" ";
1085 output_highlight($args{'parameterdescs'}{$parameter_name});
1086 print " </para>\n </listitem>\n </varlistentry>\n";
1087 }
1088 print " </variablelist>\n";
1089 } else {
1090 print " <para>\n None\n </para>\n";
1091 }
1092 print "</refsect1>\n";
1093
1094 output_section_xml(@_);
1095 print "</refentry>\n\n";
1096}
1097
1098# output struct in XML DocBook
1099sub output_struct_xml(%) {
1100 my %args = %{$_[0]};
1101 my ($parameter, $section);
1102 my $id;
1103
Randy Dunlapb9d973282009-06-09 08:50:38 -07001104 $id = "API-struct-" . $args{'struct'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001105 $id =~ s/[^A-Za-z0-9]/-/g;
1106
Pavel Pisa5449bc92007-02-10 01:45:37 -08001107 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001108 print "<refentryinfo>\n";
1109 print " <title>LINUX</title>\n";
1110 print " <productname>Kernel Hackers Manual</productname>\n";
1111 print " <date>$man_date</date>\n";
1112 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001113 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001114 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001115 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001116 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001117 print "</refmeta>\n";
1118 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001119 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001120 print " <refpurpose>\n";
1121 print " ";
1122 output_highlight ($args{'purpose'});
1123 print " </refpurpose>\n";
1124 print "</refnamediv>\n";
1125
1126 print "<refsynopsisdiv>\n";
1127 print " <title>Synopsis</title>\n";
1128 print " <programlisting>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001129 print $args{'type'} . " " . $args{'struct'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001130 foreach $parameter (@{$args{'parameterlist'}}) {
1131 if ($parameter =~ /^#/) {
Randy Dunlap2b35f4d2010-11-18 12:27:31 -08001132 my $prm = $parameter;
1133 # convert data read & converted thru xml_escape() into &xyz; format:
1134 # This allows us to have #define macros interspersed in a struct.
1135 $prm =~ s/\\\\\\/\&/g;
1136 print "$prm\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001137 next;
1138 }
1139
1140 my $parameter_name = $parameter;
1141 $parameter_name =~ s/\[.*//;
1142
1143 defined($args{'parameterdescs'}{$parameter_name}) || next;
Randy Dunlap3c308792007-05-08 00:24:39 -07001144 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001145 $type = $args{'parametertypes'}{$parameter};
1146 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1147 # pointer-to-function
1148 print " $1 $parameter) ($2);\n";
1149 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07001150 # bitfield
Linus Torvalds1da177e2005-04-16 15:20:36 -07001151 print " $1 $parameter$2;\n";
1152 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001153 print " " . $type . " " . $parameter . ";\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001154 }
1155 }
1156 print "};";
1157 print " </programlisting>\n";
1158 print "</refsynopsisdiv>\n";
1159
1160 print " <refsect1>\n";
1161 print " <title>Members</title>\n";
1162
Randy Dunlap39f00c02008-09-22 13:57:44 -07001163 if ($#{$args{'parameterlist'}} >= 0) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001164 print " <variablelist>\n";
1165 foreach $parameter (@{$args{'parameterlist'}}) {
1166 ($parameter =~ /^#/) && next;
1167
1168 my $parameter_name = $parameter;
1169 $parameter_name =~ s/\[.*//;
1170
1171 defined($args{'parameterdescs'}{$parameter_name}) || next;
1172 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1173 print " <varlistentry>";
1174 print " <term>$parameter</term>\n";
1175 print " <listitem><para>\n";
1176 output_highlight($args{'parameterdescs'}{$parameter_name});
1177 print " </para></listitem>\n";
1178 print " </varlistentry>\n";
1179 }
1180 print " </variablelist>\n";
Randy Dunlap39f00c02008-09-22 13:57:44 -07001181 } else {
1182 print " <para>\n None\n </para>\n";
1183 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001184 print " </refsect1>\n";
1185
1186 output_section_xml(@_);
1187
1188 print "</refentry>\n\n";
1189}
1190
1191# output enum in XML DocBook
1192sub output_enum_xml(%) {
1193 my %args = %{$_[0]};
1194 my ($parameter, $section);
1195 my $count;
1196 my $id;
1197
Randy Dunlapb9d973282009-06-09 08:50:38 -07001198 $id = "API-enum-" . $args{'enum'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001199 $id =~ s/[^A-Za-z0-9]/-/g;
1200
Pavel Pisa5449bc92007-02-10 01:45:37 -08001201 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001202 print "<refentryinfo>\n";
1203 print " <title>LINUX</title>\n";
1204 print " <productname>Kernel Hackers Manual</productname>\n";
1205 print " <date>$man_date</date>\n";
1206 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001207 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001208 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001209 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov03662992007-05-09 02:33:43 -07001210 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001211 print "</refmeta>\n";
1212 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001213 print " <refname>enum " . $args{'enum'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001214 print " <refpurpose>\n";
1215 print " ";
1216 output_highlight ($args{'purpose'});
1217 print " </refpurpose>\n";
1218 print "</refnamediv>\n";
1219
1220 print "<refsynopsisdiv>\n";
1221 print " <title>Synopsis</title>\n";
1222 print " <programlisting>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001223 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001224 $count = 0;
1225 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001226 print " $parameter";
1227 if ($count != $#{$args{'parameterlist'}}) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001228 $count++;
1229 print ",";
Randy Dunlap3c308792007-05-08 00:24:39 -07001230 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001231 print "\n";
1232 }
1233 print "};";
1234 print " </programlisting>\n";
1235 print "</refsynopsisdiv>\n";
1236
1237 print "<refsect1>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001238 print " <title>Constants</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001239 print " <variablelist>\n";
1240 foreach $parameter (@{$args{'parameterlist'}}) {
1241 my $parameter_name = $parameter;
1242 $parameter_name =~ s/\[.*//;
1243
1244 print " <varlistentry>";
1245 print " <term>$parameter</term>\n";
1246 print " <listitem><para>\n";
1247 output_highlight($args{'parameterdescs'}{$parameter_name});
1248 print " </para></listitem>\n";
1249 print " </varlistentry>\n";
1250 }
1251 print " </variablelist>\n";
1252 print "</refsect1>\n";
1253
1254 output_section_xml(@_);
1255
1256 print "</refentry>\n\n";
1257}
1258
1259# output typedef in XML DocBook
1260sub output_typedef_xml(%) {
1261 my %args = %{$_[0]};
1262 my ($parameter, $section);
1263 my $id;
1264
Randy Dunlapb9d973282009-06-09 08:50:38 -07001265 $id = "API-typedef-" . $args{'typedef'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001266 $id =~ s/[^A-Za-z0-9]/-/g;
1267
Pavel Pisa5449bc92007-02-10 01:45:37 -08001268 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001269 print "<refentryinfo>\n";
1270 print " <title>LINUX</title>\n";
1271 print " <productname>Kernel Hackers Manual</productname>\n";
1272 print " <date>$man_date</date>\n";
1273 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001274 print "<refmeta>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001275 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -07001276 print " <manvolnum>9</manvolnum>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001277 print "</refmeta>\n";
1278 print "<refnamediv>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001279 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001280 print " <refpurpose>\n";
1281 print " ";
1282 output_highlight ($args{'purpose'});
1283 print " </refpurpose>\n";
1284 print "</refnamediv>\n";
1285
1286 print "<refsynopsisdiv>\n";
1287 print " <title>Synopsis</title>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001288 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001289 print "</refsynopsisdiv>\n";
1290
1291 output_section_xml(@_);
1292
1293 print "</refentry>\n\n";
1294}
1295
1296# output in XML DocBook
Johannes Bergb112e0f2007-10-24 15:08:48 -07001297sub output_blockhead_xml(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001298 my %args = %{$_[0]};
1299 my ($parameter, $section);
1300 my $count;
1301
1302 my $id = $args{'module'};
1303 $id =~ s/[^A-Za-z0-9]/-/g;
1304
1305 # print out each section
1306 $lineprefix=" ";
1307 foreach $section (@{$args{'sectionlist'}}) {
Johannes Bergb112e0f2007-10-24 15:08:48 -07001308 if (!$args{'content-only'}) {
1309 print "<refsect1>\n <title>$section</title>\n";
1310 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001311 if ($section =~ m/EXAMPLE/i) {
1312 print "<example><para>\n";
Daniel Santose314ba32012-10-04 17:15:08 -07001313 $output_preformatted = 1;
Johannes Bergb112e0f2007-10-24 15:08:48 -07001314 } else {
1315 print "<para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001316 }
1317 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -07001318 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001319 if ($section =~ m/EXAMPLE/i) {
1320 print "</para></example>\n";
Johannes Bergb112e0f2007-10-24 15:08:48 -07001321 } else {
1322 print "</para>";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001323 }
Johannes Bergb112e0f2007-10-24 15:08:48 -07001324 if (!$args{'content-only'}) {
1325 print "\n</refsect1>\n";
1326 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001327 }
1328
1329 print "\n\n";
1330}
1331
1332# output in XML DocBook
1333sub output_function_gnome {
1334 my %args = %{$_[0]};
1335 my ($parameter, $section);
1336 my $count;
1337 my $id;
1338
Randy Dunlapb9d973282009-06-09 08:50:38 -07001339 $id = $args{'module'} . "-" . $args{'function'};
Linus Torvalds1da177e2005-04-16 15:20:36 -07001340 $id =~ s/[^A-Za-z0-9]/-/g;
1341
1342 print "<sect2>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001343 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001344
1345 print " <funcsynopsis>\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001346 print " <funcdef>" . $args{'functiontype'} . " ";
1347 print "<function>" . $args{'function'} . " ";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001348 print "</function></funcdef>\n";
1349
1350 $count = 0;
1351 if ($#{$args{'parameterlist'}} >= 0) {
1352 foreach $parameter (@{$args{'parameterlist'}}) {
1353 $type = $args{'parametertypes'}{$parameter};
1354 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1355 # pointer-to-function
1356 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1357 print " <funcparams>$2</funcparams></paramdef>\n";
1358 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001359 print " <paramdef>" . $type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001360 print " <parameter>$parameter</parameter></paramdef>\n";
1361 }
1362 }
1363 } else {
1364 print " <void>\n";
1365 }
1366 print " </funcsynopsis>\n";
1367 if ($#{$args{'parameterlist'}} >= 0) {
1368 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1369 print "<tgroup cols=\"2\">\n";
1370 print "<colspec colwidth=\"2*\">\n";
1371 print "<colspec colwidth=\"8*\">\n";
1372 print "<tbody>\n";
1373 foreach $parameter (@{$args{'parameterlist'}}) {
1374 my $parameter_name = $parameter;
1375 $parameter_name =~ s/\[.*//;
1376
1377 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1378 print " <entry>\n";
1379 $lineprefix=" ";
1380 output_highlight($args{'parameterdescs'}{$parameter_name});
1381 print " </entry></row>\n";
1382 }
1383 print " </tbody></tgroup></informaltable>\n";
1384 } else {
1385 print " <para>\n None\n </para>\n";
1386 }
1387
1388 # print out each section
1389 $lineprefix=" ";
1390 foreach $section (@{$args{'sectionlist'}}) {
1391 print "<simplesect>\n <title>$section</title>\n";
1392 if ($section =~ m/EXAMPLE/i) {
1393 print "<example><programlisting>\n";
Daniel Santose314ba32012-10-04 17:15:08 -07001394 $output_preformatted = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001395 } else {
1396 }
1397 print "<para>\n";
1398 output_highlight($args{'sections'}{$section});
Daniel Santose314ba32012-10-04 17:15:08 -07001399 $output_preformatted = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001400 print "</para>\n";
1401 if ($section =~ m/EXAMPLE/i) {
1402 print "</programlisting></example>\n";
1403 } else {
1404 }
1405 print " </simplesect>\n";
1406 }
1407
1408 print "</sect2>\n\n";
1409}
1410
1411##
1412# output function in man
1413sub output_function_man(%) {
1414 my %args = %{$_[0]};
1415 my ($parameter, $section);
1416 my $count;
1417
1418 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1419
1420 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001421 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001422
1423 print ".SH SYNOPSIS\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001424 if ($args{'functiontype'} ne "") {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001425 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001426 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001427 print ".B \"" . $args{'function'} . "\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001428 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001429 $count = 0;
1430 my $parenth = "(";
1431 my $post = ",";
1432 foreach my $parameter (@{$args{'parameterlist'}}) {
1433 if ($count == $#{$args{'parameterlist'}}) {
1434 $post = ");";
1435 }
1436 $type = $args{'parametertypes'}{$parameter};
1437 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1438 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001439 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001440 } else {
1441 $type =~ s/([^\*])$/$1 /;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001442 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001443 }
1444 $count++;
1445 $parenth = "";
1446 }
1447
1448 print ".SH ARGUMENTS\n";
1449 foreach $parameter (@{$args{'parameterlist'}}) {
1450 my $parameter_name = $parameter;
1451 $parameter_name =~ s/\[.*//;
1452
Randy Dunlapb9d973282009-06-09 08:50:38 -07001453 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001454 output_highlight($args{'parameterdescs'}{$parameter_name});
1455 }
1456 foreach $section (@{$args{'sectionlist'}}) {
1457 print ".SH \"", uc $section, "\"\n";
1458 output_highlight($args{'sections'}{$section});
1459 }
1460}
1461
1462##
1463# output enum in man
1464sub output_enum_man(%) {
1465 my %args = %{$_[0]};
1466 my ($parameter, $section);
1467 my $count;
1468
1469 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1470
1471 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001472 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001473
1474 print ".SH SYNOPSIS\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001475 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001476 $count = 0;
1477 foreach my $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001478 print ".br\n.BI \" $parameter\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001479 if ($count == $#{$args{'parameterlist'}}) {
1480 print "\n};\n";
1481 last;
1482 }
1483 else {
1484 print ", \n.br\n";
1485 }
1486 $count++;
1487 }
1488
1489 print ".SH Constants\n";
1490 foreach $parameter (@{$args{'parameterlist'}}) {
1491 my $parameter_name = $parameter;
1492 $parameter_name =~ s/\[.*//;
1493
Randy Dunlapb9d973282009-06-09 08:50:38 -07001494 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001495 output_highlight($args{'parameterdescs'}{$parameter_name});
1496 }
1497 foreach $section (@{$args{'sectionlist'}}) {
1498 print ".SH \"$section\"\n";
1499 output_highlight($args{'sections'}{$section});
1500 }
1501}
1502
1503##
1504# output struct in man
1505sub output_struct_man(%) {
1506 my %args = %{$_[0]};
1507 my ($parameter, $section);
1508
Randy Dunlapb9d973282009-06-09 08:50:38 -07001509 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001510
1511 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001512 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001513
1514 print ".SH SYNOPSIS\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001515 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001516
1517 foreach my $parameter (@{$args{'parameterlist'}}) {
1518 if ($parameter =~ /^#/) {
1519 print ".BI \"$parameter\"\n.br\n";
1520 next;
1521 }
1522 my $parameter_name = $parameter;
1523 $parameter_name =~ s/\[.*//;
1524
Randy Dunlap3c308792007-05-08 00:24:39 -07001525 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001526 $type = $args{'parametertypes'}{$parameter};
1527 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1528 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001529 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001530 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001531 # bitfield
Randy Dunlapb9d973282009-06-09 08:50:38 -07001532 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001533 } else {
1534 $type =~ s/([^\*])$/$1 /;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001535 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001536 }
1537 print "\n.br\n";
1538 }
1539 print "};\n.br\n";
1540
Randy Dunlapc51d3da2006-06-25 05:49:14 -07001541 print ".SH Members\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001542 foreach $parameter (@{$args{'parameterlist'}}) {
1543 ($parameter =~ /^#/) && next;
1544
1545 my $parameter_name = $parameter;
1546 $parameter_name =~ s/\[.*//;
1547
Randy Dunlap3c308792007-05-08 00:24:39 -07001548 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Randy Dunlapb9d973282009-06-09 08:50:38 -07001549 print ".IP \"" . $parameter . "\" 12\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001550 output_highlight($args{'parameterdescs'}{$parameter_name});
1551 }
1552 foreach $section (@{$args{'sectionlist'}}) {
1553 print ".SH \"$section\"\n";
1554 output_highlight($args{'sections'}{$section});
1555 }
1556}
1557
1558##
1559# output typedef in man
1560sub output_typedef_man(%) {
1561 my %args = %{$_[0]};
1562 my ($parameter, $section);
1563
1564 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1565
1566 print ".SH NAME\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001567 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001568
1569 foreach $section (@{$args{'sectionlist'}}) {
1570 print ".SH \"$section\"\n";
1571 output_highlight($args{'sections'}{$section});
1572 }
1573}
1574
Johannes Bergb112e0f2007-10-24 15:08:48 -07001575sub output_blockhead_man(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001576 my %args = %{$_[0]};
1577 my ($parameter, $section);
1578 my $count;
1579
1580 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1581
1582 foreach $section (@{$args{'sectionlist'}}) {
1583 print ".SH \"$section\"\n";
1584 output_highlight($args{'sections'}{$section});
1585 }
1586}
1587
1588##
1589# output in text
1590sub output_function_text(%) {
1591 my %args = %{$_[0]};
1592 my ($parameter, $section);
Randy Dunlapa21217d2007-02-10 01:46:04 -08001593 my $start;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001594
Randy Dunlapf47634b2006-07-01 04:36:36 -07001595 print "Name:\n\n";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001596 print $args{'function'} . " - " . $args{'purpose'} . "\n";
Randy Dunlapf47634b2006-07-01 04:36:36 -07001597
1598 print "\nSynopsis:\n\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001599 if ($args{'functiontype'} ne "") {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001600 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001601 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001602 $start = $args{'function'} . " (";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001603 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001604 print $start;
Randy Dunlapa21217d2007-02-10 01:46:04 -08001605
Linus Torvalds1da177e2005-04-16 15:20:36 -07001606 my $count = 0;
1607 foreach my $parameter (@{$args{'parameterlist'}}) {
1608 $type = $args{'parametertypes'}{$parameter};
1609 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1610 # pointer-to-function
Randy Dunlapb9d973282009-06-09 08:50:38 -07001611 print $1 . $parameter . ") (" . $2;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001612 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001613 print $type . " " . $parameter;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001614 }
1615 if ($count != $#{$args{'parameterlist'}}) {
1616 $count++;
1617 print ",\n";
1618 print " " x length($start);
1619 } else {
1620 print ");\n\n";
1621 }
1622 }
1623
1624 print "Arguments:\n\n";
1625 foreach $parameter (@{$args{'parameterlist'}}) {
1626 my $parameter_name = $parameter;
1627 $parameter_name =~ s/\[.*//;
1628
Randy Dunlapb9d973282009-06-09 08:50:38 -07001629 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001630 }
1631 output_section_text(@_);
1632}
1633
1634#output sections in text
1635sub output_section_text(%) {
1636 my %args = %{$_[0]};
1637 my $section;
1638
1639 print "\n";
1640 foreach $section (@{$args{'sectionlist'}}) {
1641 print "$section:\n\n";
1642 output_highlight($args{'sections'}{$section});
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001643 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001644 print "\n\n";
1645}
1646
1647# output enum in text
1648sub output_enum_text(%) {
1649 my %args = %{$_[0]};
1650 my ($parameter);
1651 my $count;
1652 print "Enum:\n\n";
1653
Randy Dunlapb9d973282009-06-09 08:50:38 -07001654 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1655 print "enum " . $args{'enum'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001656 $count = 0;
1657 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001658 print "\t$parameter";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001659 if ($count != $#{$args{'parameterlist'}}) {
1660 $count++;
1661 print ",";
1662 }
1663 print "\n";
1664 }
1665 print "};\n\n";
1666
1667 print "Constants:\n\n";
1668 foreach $parameter (@{$args{'parameterlist'}}) {
1669 print "$parameter\n\t";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001670 print $args{'parameterdescs'}{$parameter} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001671 }
1672
1673 output_section_text(@_);
1674}
1675
1676# output typedef in text
1677sub output_typedef_text(%) {
1678 my %args = %{$_[0]};
1679 my ($parameter);
1680 my $count;
1681 print "Typedef:\n\n";
1682
Randy Dunlapb9d973282009-06-09 08:50:38 -07001683 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001684 output_section_text(@_);
1685}
1686
1687# output struct as text
1688sub output_struct_text(%) {
1689 my %args = %{$_[0]};
1690 my ($parameter);
1691
Randy Dunlapb9d973282009-06-09 08:50:38 -07001692 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1693 print $args{'type'} . " " . $args{'struct'} . " {\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001694 foreach $parameter (@{$args{'parameterlist'}}) {
1695 if ($parameter =~ /^#/) {
1696 print "$parameter\n";
1697 next;
1698 }
1699
1700 my $parameter_name = $parameter;
1701 $parameter_name =~ s/\[.*//;
1702
Randy Dunlap3c308792007-05-08 00:24:39 -07001703 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001704 $type = $args{'parametertypes'}{$parameter};
1705 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1706 # pointer-to-function
1707 print "\t$1 $parameter) ($2);\n";
1708 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07001709 # bitfield
Linus Torvalds1da177e2005-04-16 15:20:36 -07001710 print "\t$1 $parameter$2;\n";
1711 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07001712 print "\t" . $type . " " . $parameter . ";\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001713 }
1714 }
1715 print "};\n\n";
1716
1717 print "Members:\n\n";
1718 foreach $parameter (@{$args{'parameterlist'}}) {
1719 ($parameter =~ /^#/) && next;
1720
1721 my $parameter_name = $parameter;
1722 $parameter_name =~ s/\[.*//;
1723
Randy Dunlap3c308792007-05-08 00:24:39 -07001724 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001725 print "$parameter\n\t";
Randy Dunlapb9d973282009-06-09 08:50:38 -07001726 print $args{'parameterdescs'}{$parameter_name} . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001727 }
1728 print "\n";
1729 output_section_text(@_);
1730}
1731
Johannes Bergb112e0f2007-10-24 15:08:48 -07001732sub output_blockhead_text(%) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001733 my %args = %{$_[0]};
1734 my ($parameter, $section);
1735
1736 foreach $section (@{$args{'sectionlist'}}) {
1737 print " $section:\n";
1738 print " -> ";
1739 output_highlight($args{'sections'}{$section});
1740 }
1741}
1742
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001743##
1744# output in restructured text
1745#
1746
1747#
1748# This could use some work; it's used to output the DOC: sections, and
1749# starts by putting out the name of the doc section itself, but that tends
1750# to duplicate a header already in the template file.
1751#
1752sub output_blockhead_rst(%) {
1753 my %args = %{$_[0]};
1754 my ($parameter, $section);
1755
1756 foreach $section (@{$args{'sectionlist'}}) {
1757 print "**$section**\n\n";
1758 output_highlight_rst($args{'sections'}{$section});
1759 print "\n";
1760 }
1761}
1762
1763sub output_highlight_rst {
1764 my $contents = join "\n",@_;
1765 my $line;
1766
1767 # undo the evil effects of xml_escape() earlier
1768 $contents = xml_unescape($contents);
1769
1770 eval $dohighlight;
1771 die $@ if $@;
1772
1773 foreach $line (split "\n", $contents) {
1774 if ($line eq "") {
1775 print $lineprefix, $blankline;
1776 } else {
1777 $line =~ s/\\\\\\/\&/g;
1778 print $lineprefix, $line;
1779 }
1780 print "\n";
1781 }
1782}
1783
1784sub output_function_rst(%) {
1785 my %args = %{$_[0]};
1786 my ($parameter, $section);
1787 my $start;
1788
1789 print ".. c:function:: ";
1790 if ($args{'functiontype'} ne "") {
1791 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1792 } else {
1793 $start = $args{'function'} . " (";
1794 }
1795 print $start;
1796
1797 my $count = 0;
1798 foreach my $parameter (@{$args{'parameterlist'}}) {
1799 if ($count ne 0) {
1800 print ", ";
1801 }
1802 $count++;
1803 $type = $args{'parametertypes'}{$parameter};
1804 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1805 # pointer-to-function
1806 print $1 . $parameter . ") (" . $2;
1807 } else {
1808 print $type . " " . $parameter;
1809 }
1810 }
1811 print ")\n\n " . $args{'purpose'} . "\n\n";
1812
1813 print ":Parameters:\n\n";
1814 foreach $parameter (@{$args{'parameterlist'}}) {
1815 my $parameter_name = $parameter;
1816 #$parameter_name =~ s/\[.*//;
1817 $type = $args{'parametertypes'}{$parameter};
1818
1819 if ($type ne "") {
1820 print " ``$type $parameter``\n";
1821 } else {
1822 print " ``$parameter``\n";
1823 }
Jani Nikula5e64fa92016-05-19 20:32:48 +03001824 if (defined($args{'parameterdescs'}{$parameter_name}) &&
1825 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001826 my $oldprefix = $lineprefix;
1827 $lineprefix = " ";
1828 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1829 $lineprefix = $oldprefix;
1830 } else {
1831 print "\n _undescribed_\n";
1832 }
1833 print "\n";
1834 }
1835 output_section_rst(@_);
1836}
1837
1838sub output_section_rst(%) {
1839 my %args = %{$_[0]};
1840 my $section;
1841 my $oldprefix = $lineprefix;
1842 $lineprefix = " ";
1843
1844 foreach $section (@{$args{'sectionlist'}}) {
1845 print ":$section:\n\n";
1846 output_highlight_rst($args{'sections'}{$section});
1847 print "\n";
1848 }
1849 print "\n";
1850 $lineprefix = $oldprefix;
1851}
1852
1853sub output_enum_rst(%) {
1854 my %args = %{$_[0]};
1855 my ($parameter);
1856 my $count;
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001857 my $name = "enum " . $args{'enum'};
Jani Nikula62850972016-05-12 16:15:38 +03001858
1859 print "\n\n.. c:type:: " . $name . "\n\n";
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001860 print " " . $args{'purpose'} . "\n\n";
1861
1862 print "..\n\n:Constants:\n\n";
1863 my $oldprefix = $lineprefix;
1864 $lineprefix = " ";
1865 foreach $parameter (@{$args{'parameterlist'}}) {
1866 print " `$parameter`\n";
1867 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1868 output_highlight_rst($args{'parameterdescs'}{$parameter});
1869 } else {
1870 print " undescribed\n";
1871 }
1872 print "\n";
1873 }
1874 $lineprefix = $oldprefix;
1875 output_section_rst(@_);
1876}
1877
1878sub output_typedef_rst(%) {
1879 my %args = %{$_[0]};
1880 my ($parameter);
1881 my $count;
1882 my $name = "typedef " . $args{'typedef'};
1883
Jani Nikula62850972016-05-12 16:15:38 +03001884 ### FIXME: should the name below contain "typedef" or not?
1885 print "\n\n.. c:type:: " . $name . "\n\n";
1886 print " " . $args{'purpose'} . "\n\n";
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001887
1888 output_section_rst(@_);
1889}
1890
1891sub output_struct_rst(%) {
1892 my %args = %{$_[0]};
1893 my ($parameter);
1894 my $name = $args{'type'} . " " . $args{'struct'};
1895
Jani Nikula62850972016-05-12 16:15:38 +03001896 print "\n\n.. c:type:: " . $name . "\n\n";
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03001897 print " " . $args{'purpose'} . "\n\n";
1898
1899 print ":Definition:\n\n";
1900 print " ::\n\n";
1901 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1902 foreach $parameter (@{$args{'parameterlist'}}) {
1903 if ($parameter =~ /^#/) {
1904 print " " . "$parameter\n";
1905 next;
1906 }
1907
1908 my $parameter_name = $parameter;
1909 $parameter_name =~ s/\[.*//;
1910
1911 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1912 $type = $args{'parametertypes'}{$parameter};
1913 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1914 # pointer-to-function
1915 print " $1 $parameter) ($2);\n";
1916 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1917 # bitfield
1918 print " $1 $parameter$2;\n";
1919 } else {
1920 print " " . $type . " " . $parameter . ";\n";
1921 }
1922 }
1923 print " };\n\n";
1924
1925 print ":Members:\n\n";
1926 foreach $parameter (@{$args{'parameterlist'}}) {
1927 ($parameter =~ /^#/) && next;
1928
1929 my $parameter_name = $parameter;
1930 $parameter_name =~ s/\[.*//;
1931
1932 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1933 $type = $args{'parametertypes'}{$parameter};
1934 print " `$type $parameter`" . "\n";
1935 my $oldprefix = $lineprefix;
1936 $lineprefix = " ";
1937 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1938 $lineprefix = $oldprefix;
1939 print "\n";
1940 }
1941 print "\n";
1942 output_section_rst(@_);
1943}
1944
1945
Johannes Bergeda603f2010-09-11 15:55:22 -07001946## list mode output functions
1947
1948sub output_function_list(%) {
1949 my %args = %{$_[0]};
1950
1951 print $args{'function'} . "\n";
1952}
1953
1954# output enum in list
1955sub output_enum_list(%) {
1956 my %args = %{$_[0]};
1957 print $args{'enum'} . "\n";
1958}
1959
1960# output typedef in list
1961sub output_typedef_list(%) {
1962 my %args = %{$_[0]};
1963 print $args{'typedef'} . "\n";
1964}
1965
1966# output struct as list
1967sub output_struct_list(%) {
1968 my %args = %{$_[0]};
1969
1970 print $args{'struct'} . "\n";
1971}
1972
1973sub output_blockhead_list(%) {
1974 my %args = %{$_[0]};
1975 my ($parameter, $section);
1976
1977 foreach $section (@{$args{'sectionlist'}}) {
1978 print "DOC: $section\n";
1979 }
1980}
1981
Linus Torvalds1da177e2005-04-16 15:20:36 -07001982##
Randy Dunlap27205742006-10-11 01:22:12 -07001983# generic output function for all types (function, struct/union, typedef, enum);
1984# calls the generated, variable output_ function name based on
1985# functype and output_mode
Linus Torvalds1da177e2005-04-16 15:20:36 -07001986sub output_declaration {
1987 no strict 'refs';
1988 my $name = shift;
1989 my $functype = shift;
1990 my $func = "output_${functype}_$output_mode";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001991 if (($function_only==0) ||
Jani Nikula86ae2e32016-01-21 13:05:22 +02001992 ( ($function_only == 1 || $function_only == 3) &&
1993 defined($function_table{$name})) ||
1994 ( ($function_only == 2 || $function_only == 4) &&
1995 !($functype eq "function" && defined($function_table{$name}))))
Linus Torvalds1da177e2005-04-16 15:20:36 -07001996 {
Randy Dunlap3c308792007-05-08 00:24:39 -07001997 &$func(@_);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001998 $section_counter++;
1999 }
2000}
2001
2002##
Randy Dunlap27205742006-10-11 01:22:12 -07002003# generic output function - calls the right one based on current output mode.
Johannes Bergb112e0f2007-10-24 15:08:48 -07002004sub output_blockhead {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002005 no strict 'refs';
Randy Dunlapb9d973282009-06-09 08:50:38 -07002006 my $func = "output_blockhead_" . $output_mode;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002007 &$func(@_);
2008 $section_counter++;
2009}
2010
2011##
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002012# takes a declaration (struct, union, enum, typedef) and
Linus Torvalds1da177e2005-04-16 15:20:36 -07002013# invokes the right handler. NOT called for functions.
2014sub dump_declaration($$) {
2015 no strict 'refs';
2016 my ($prototype, $file) = @_;
Randy Dunlapb9d973282009-06-09 08:50:38 -07002017 my $func = "dump_" . $decl_type;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002018 &$func(@_);
2019}
2020
2021sub dump_union($$) {
2022 dump_struct(@_);
2023}
2024
2025sub dump_struct($$) {
2026 my $x = shift;
2027 my $file = shift;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002028 my $nested;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002029
Randy Dunlap52dc5ae2009-04-30 15:08:53 -07002030 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2031 #my $decl_type = $1;
Randy Dunlap3c308792007-05-08 00:24:39 -07002032 $declaration_name = $2;
2033 my $members = $3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002034
2035 # ignore embedded structs or unions
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002036 $members =~ s/({.*})//g;
2037 $nested = $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002038
Martin Waitzaeec46b2005-11-13 16:08:13 -08002039 # ignore members marked private:
Mauro Carvalho Chehab0d8c39e2015-10-05 09:03:48 -03002040 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2041 $members =~ s/\/\*\s*private:.*//gosi;
Martin Waitzaeec46b2005-11-13 16:08:13 -08002042 # strip comments:
2043 $members =~ s/\/\*.*?\*\///gos;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002044 $nested =~ s/\/\*.*?\*\///gos;
Randy Dunlapd960eea2009-06-29 14:54:11 -07002045 # strip kmemcheck_bitfield_{begin,end}.*;
2046 $members =~ s/kmemcheck_bitfield_.*?;//gos;
Randy Dunlapef5da592010-03-23 13:35:14 -07002047 # strip attributes
Jonathan Corbetf0074922015-08-23 13:35:23 -06002048 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
Johannes Berg7b990782014-12-10 15:41:28 -08002049 $members =~ s/__aligned\s*\([^;]*\)//gos;
Jonathan Corbetf0074922015-08-23 13:35:23 -06002050 $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
Conchúr Navidb22b5a92015-11-08 10:52:00 +01002051 # replace DECLARE_BITMAP
2052 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
Martin Waitzaeec46b2005-11-13 16:08:13 -08002053
Linus Torvalds1da177e2005-04-16 15:20:36 -07002054 create_parameterlist($members, ';', $file);
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002055 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002056
2057 output_declaration($declaration_name,
2058 'struct',
2059 {'struct' => $declaration_name,
2060 'module' => $modulename,
2061 'parameterlist' => \@parameterlist,
2062 'parameterdescs' => \%parameterdescs,
2063 'parametertypes' => \%parametertypes,
2064 'sectionlist' => \@sectionlist,
2065 'sections' => \%sections,
2066 'purpose' => $declaration_purpose,
2067 'type' => $decl_type
2068 });
2069 }
2070 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002071 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002072 ++$errors;
2073 }
2074}
2075
2076sub dump_enum($$) {
2077 my $x = shift;
2078 my $file = shift;
2079
Martin Waitzaeec46b2005-11-13 16:08:13 -08002080 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Conchúr Navid4468e212015-11-08 10:48:05 +01002081 # strip #define macros inside enums
2082 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
Randy Dunlapb6d676d2010-08-10 18:02:50 -07002083
Linus Torvalds1da177e2005-04-16 15:20:36 -07002084 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002085 $declaration_name = $1;
2086 my $members = $2;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002087
2088 foreach my $arg (split ',', $members) {
2089 $arg =~ s/^\s*(\w+).*/$1/;
2090 push @parameterlist, $arg;
2091 if (!$parameterdescs{$arg}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002092 $parameterdescs{$arg} = $undescribed;
Bart Van Assched40e1e62015-09-04 15:43:21 -07002093 print STDERR "${file}:$.: warning: Enum value '$arg' ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07002094 "not described in enum '$declaration_name'\n";
2095 }
2096
2097 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002098
Linus Torvalds1da177e2005-04-16 15:20:36 -07002099 output_declaration($declaration_name,
2100 'enum',
2101 {'enum' => $declaration_name,
2102 'module' => $modulename,
2103 'parameterlist' => \@parameterlist,
2104 'parameterdescs' => \%parameterdescs,
2105 'sectionlist' => \@sectionlist,
2106 'sections' => \%sections,
2107 'purpose' => $declaration_purpose
2108 });
2109 }
2110 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002111 print STDERR "${file}:$.: error: Cannot parse enum!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002112 ++$errors;
2113 }
2114}
2115
2116sub dump_typedef($$) {
2117 my $x = shift;
2118 my $file = shift;
2119
Martin Waitzaeec46b2005-11-13 16:08:13 -08002120 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Mauro Carvalho Chehab83766452015-10-08 16:14:45 -03002121
2122 # Parse function prototypes
2123 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2124 # Function typedefs
2125 $return_type = $1;
2126 $declaration_name = $2;
2127 my $args = $3;
2128
2129 create_parameterlist($args, ',', $file);
2130
2131 output_declaration($declaration_name,
2132 'function',
2133 {'function' => $declaration_name,
2134 'module' => $modulename,
2135 'functiontype' => $return_type,
2136 'parameterlist' => \@parameterlist,
2137 'parameterdescs' => \%parameterdescs,
2138 'parametertypes' => \%parametertypes,
2139 'sectionlist' => \@sectionlist,
2140 'sections' => \%sections,
2141 'purpose' => $declaration_purpose
2142 });
2143 return;
2144 }
2145
Linus Torvalds1da177e2005-04-16 15:20:36 -07002146 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002147 $x =~ s/\(*.\)\s*;$/;/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002148 $x =~ s/\[*.\]\s*;$/;/;
2149 }
2150
2151 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002152 $declaration_name = $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002153
2154 output_declaration($declaration_name,
2155 'typedef',
2156 {'typedef' => $declaration_name,
2157 'module' => $modulename,
2158 'sectionlist' => \@sectionlist,
2159 'sections' => \%sections,
2160 'purpose' => $declaration_purpose
2161 });
2162 }
2163 else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002164 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002165 ++$errors;
2166 }
2167}
2168
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002169sub save_struct_actual($) {
2170 my $actual = shift;
2171
2172 # strip all spaces from the actual param so that it looks like one string item
2173 $actual =~ s/\s*//g;
2174 $struct_actual = $struct_actual . $actual . " ";
2175}
2176
Linus Torvalds1da177e2005-04-16 15:20:36 -07002177sub create_parameterlist($$$) {
2178 my $args = shift;
2179 my $splitter = shift;
2180 my $file = shift;
2181 my $type;
2182 my $param;
2183
Martin Waitza6d3fe72006-01-09 20:53:55 -08002184 # temporarily replace commas inside function pointer definition
Linus Torvalds1da177e2005-04-16 15:20:36 -07002185 while ($args =~ /(\([^\),]+),/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002186 $args =~ s/(\([^\),]+),/$1#/g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002187 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002188
Linus Torvalds1da177e2005-04-16 15:20:36 -07002189 foreach my $arg (split($splitter, $args)) {
2190 # strip comments
2191 $arg =~ s/\/\*.*\*\///;
Randy Dunlap3c308792007-05-08 00:24:39 -07002192 # strip leading/trailing spaces
2193 $arg =~ s/^\s*//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002194 $arg =~ s/\s*$//;
2195 $arg =~ s/\s+/ /;
2196
2197 if ($arg =~ /^#/) {
2198 # Treat preprocessor directive as a typeless variable just to fill
2199 # corresponding data structures "correctly". Catch it later in
2200 # output_* subs.
2201 push_parameter($arg, "", $file);
Richard Kennedy00d62962008-02-23 15:24:01 -08002202 } elsif ($arg =~ m/\(.+\)\s*\(/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002203 # pointer-to-function
2204 $arg =~ tr/#/,/;
Richard Kennedy00d62962008-02-23 15:24:01 -08002205 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002206 $param = $1;
2207 $type = $arg;
Richard Kennedy00d62962008-02-23 15:24:01 -08002208 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002209 save_struct_actual($param);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002210 push_parameter($param, $type, $file);
Martin Waitzaeec46b2005-11-13 16:08:13 -08002211 } elsif ($arg) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002212 $arg =~ s/\s*:\s*/:/g;
2213 $arg =~ s/\s*\[/\[/g;
2214
2215 my @args = split('\s*,\s*', $arg);
2216 if ($args[0] =~ m/\*/) {
2217 $args[0] =~ s/(\*+)\s*/ $1/;
2218 }
Borislav Petkov884f2812007-05-08 00:29:05 -07002219
2220 my @first_arg;
2221 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2222 shift @args;
2223 push(@first_arg, split('\s+', $1));
2224 push(@first_arg, $2);
2225 } else {
2226 @first_arg = split('\s+', shift @args);
2227 }
2228
Linus Torvalds1da177e2005-04-16 15:20:36 -07002229 unshift(@args, pop @first_arg);
2230 $type = join " ", @first_arg;
2231
2232 foreach $param (@args) {
2233 if ($param =~ m/^(\*+)\s*(.*)/) {
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002234 save_struct_actual($2);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002235 push_parameter($2, "$type $1", $file);
2236 }
2237 elsif ($param =~ m/(.*?):(\d+)/) {
Randy Dunlap7b978872008-05-16 15:45:52 -07002238 if ($type ne "") { # skip unnamed bit-fields
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002239 save_struct_actual($1);
Randy Dunlap7b978872008-05-16 15:45:52 -07002240 push_parameter($1, "$type:$2", $file)
2241 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002242 }
2243 else {
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002244 save_struct_actual($param);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002245 push_parameter($param, $type, $file);
2246 }
2247 }
2248 }
2249 }
2250}
2251
2252sub push_parameter($$$) {
2253 my $param = shift;
2254 my $type = shift;
2255 my $file = shift;
2256
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002257 if (($anon_struct_union == 1) && ($type eq "") &&
2258 ($param eq "}")) {
2259 return; # ignore the ending }; from anon. struct/union
2260 }
2261
2262 $anon_struct_union = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002263 my $param_name = $param;
2264 $param_name =~ s/\[.*//;
2265
Martin Waitza6d3fe72006-01-09 20:53:55 -08002266 if ($type eq "" && $param =~ /\.\.\.$/)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002267 {
Randy Dunlapced69092008-12-01 13:14:03 -08002268 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2269 $parameterdescs{$param} = "variable arguments";
2270 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002271 }
2272 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2273 {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002274 $param="void";
2275 $parameterdescs{void} = "no arguments";
2276 }
Randy Dunlap134fe012006-12-22 01:10:50 -08002277 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2278 # handle unnamed (anonymous) union or struct:
2279 {
2280 $type = $param;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002281 $param = "{unnamed_" . $param . "}";
Randy Dunlap134fe012006-12-22 01:10:50 -08002282 $parameterdescs{$param} = "anonymous\n";
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002283 $anon_struct_union = 1;
Randy Dunlap134fe012006-12-22 01:10:50 -08002284 }
2285
Martin Waitza6d3fe72006-01-09 20:53:55 -08002286 # warn if parameter has no description
Randy Dunlap134fe012006-12-22 01:10:50 -08002287 # (but ignore ones starting with # as these are not parameters
2288 # but inline preprocessor statements);
2289 # also ignore unnamed structs/unions;
Randy Dunlap5f8c7c92007-07-19 01:48:24 -07002290 if (!$anon_struct_union) {
Martin Waitza6d3fe72006-01-09 20:53:55 -08002291 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2292
Linus Torvalds1da177e2005-04-16 15:20:36 -07002293 $parameterdescs{$param_name} = $undescribed;
2294
2295 if (($type eq 'function') || ($type eq 'enum')) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002296 print STDERR "${file}:$.: warning: Function parameter ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07002297 "or member '$param' not " .
2298 "described in '$declaration_name'\n";
2299 }
Bart Van Assched40e1e62015-09-04 15:43:21 -07002300 print STDERR "${file}:$.: warning:" .
Randy Dunlap3c308792007-05-08 00:24:39 -07002301 " No description found for parameter '$param'\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002302 ++$warnings;
Randy Dunlap3c308792007-05-08 00:24:39 -07002303 }
2304 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002305
Randy Dunlap2b35f4d2010-11-18 12:27:31 -08002306 $param = xml_escape($param);
2307
Lucas De Marchi25985ed2011-03-30 22:57:33 -03002308 # strip spaces from $param so that it is one continuous string
Randy Dunlape34e7db2009-06-17 17:37:47 -07002309 # on @parameterlist;
2310 # this fixes a problem where check_sections() cannot find
2311 # a parameter like "addr[6 + 2]" because it actually appears
2312 # as "addr[6", "+", "2]" on the parameter list;
2313 # but it's better to maintain the param string unchanged for output,
2314 # so just weaken the string compare in check_sections() to ignore
2315 # "[blah" in a parameter string;
2316 ###$param =~ s/\s*//g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002317 push @parameterlist, $param;
2318 $parametertypes{$param} = $type;
2319}
2320
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002321sub check_sections($$$$$$) {
2322 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2323 my @sects = split ' ', $sectcheck;
2324 my @prms = split ' ', $prmscheck;
2325 my $err;
2326 my ($px, $sx);
2327 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2328
2329 foreach $sx (0 .. $#sects) {
2330 $err = 1;
2331 foreach $px (0 .. $#prms) {
2332 $prm_clean = $prms[$px];
2333 $prm_clean =~ s/\[.*\]//;
Johannes Berg1f3a6682010-09-11 15:55:12 -07002334 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
Randy Dunlape34e7db2009-06-17 17:37:47 -07002335 # ignore array size in a parameter string;
2336 # however, the original param string may contain
2337 # spaces, e.g.: addr[6 + 2]
2338 # and this appears in @prms as "addr[6" since the
2339 # parameter list is split at spaces;
2340 # hence just ignore "[..." for the sections check;
2341 $prm_clean =~ s/\[.*//;
2342
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002343 ##$prm_clean =~ s/^\**//;
2344 if ($prm_clean eq $sects[$sx]) {
2345 $err = 0;
2346 last;
2347 }
2348 }
2349 if ($err) {
2350 if ($decl_type eq "function") {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002351 print STDERR "${file}:$.: warning: " .
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002352 "Excess function parameter " .
2353 "'$sects[$sx]' " .
2354 "description in '$decl_name'\n";
2355 ++$warnings;
2356 } else {
2357 if ($nested !~ m/\Q$sects[$sx]\E/) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002358 print STDERR "${file}:$.: warning: " .
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002359 "Excess struct/union/enum/typedef member " .
2360 "'$sects[$sx]' " .
2361 "description in '$decl_name'\n";
2362 ++$warnings;
2363 }
2364 }
2365 }
2366 }
2367}
2368
Linus Torvalds1da177e2005-04-16 15:20:36 -07002369##
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002370# Checks the section describing the return value of a function.
2371sub check_return_section {
2372 my $file = shift;
2373 my $declaration_name = shift;
2374 my $return_type = shift;
2375
2376 # Ignore an empty return type (It's a macro)
2377 # Ignore functions with a "void" return type. (But don't ignore "void *")
2378 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2379 return;
2380 }
2381
2382 if (!defined($sections{$section_return}) ||
2383 $sections{$section_return} eq "") {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002384 print STDERR "${file}:$.: warning: " .
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002385 "No description found for return value of " .
2386 "'$declaration_name'\n";
2387 ++$warnings;
2388 }
2389}
2390
2391##
Linus Torvalds1da177e2005-04-16 15:20:36 -07002392# takes a function prototype and the name of the current file being
2393# processed and spits out all the details stored in the global
2394# arrays/hashes.
2395sub dump_function($$) {
2396 my $prototype = shift;
2397 my $file = shift;
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002398 my $noret = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002399
2400 $prototype =~ s/^static +//;
2401 $prototype =~ s/^extern +//;
Pavel Pisa4dc3b162005-05-01 08:59:25 -07002402 $prototype =~ s/^asmlinkage +//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002403 $prototype =~ s/^inline +//;
2404 $prototype =~ s/^__inline__ +//;
Randy Dunlap32e79402006-10-11 01:22:10 -07002405 $prototype =~ s/^__inline +//;
2406 $prototype =~ s/^__always_inline +//;
2407 $prototype =~ s/^noinline +//;
Randy Dunlap74fc5c62008-06-19 16:03:29 -07002408 $prototype =~ s/__init +//;
Randy Dunlap20072202010-03-23 13:35:24 -07002409 $prototype =~ s/__init_or_module +//;
Randy Dunlap270a0092014-08-24 18:17:17 -07002410 $prototype =~ s/__meminit +//;
Randy Dunlap70c95b02012-01-21 10:31:54 -08002411 $prototype =~ s/__must_check +//;
Randy Dunlap0df7c0e2012-08-16 16:23:20 -07002412 $prototype =~ s/__weak +//;
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002413 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
Randy Dunlap328d2442007-02-28 20:12:10 -08002414 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002415
2416 # Yes, this truly is vile. We are looking for:
2417 # 1. Return type (may be nothing if we're looking at a macro)
2418 # 2. Function name
2419 # 3. Function parameters.
2420 #
2421 # All the while we have to watch out for function pointer parameters
2422 # (which IIRC is what the two sections are for), C types (these
2423 # regexps don't even start to express all the possibilities), and
2424 # so on.
2425 #
2426 # If you mess with these regexps, it's a good idea to check that
2427 # the following functions' documentation still comes out right:
2428 # - parport_register_device (function pointer parameters)
2429 # - atomic_set (macro)
Martin Waitz9598f912006-02-01 03:06:55 -08002430 # - pci_match_device, __copy_to_user (long return type)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002431
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002432 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2433 # This is an object-like macro, it has no return type and no parameter
2434 # list.
2435 # Function-like macros are not allowed to have spaces between
2436 # declaration_name and opening parenthesis (notice the \s+).
2437 $return_type = $1;
2438 $declaration_name = $2;
2439 $noret = 1;
2440 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Linus Torvalds1da177e2005-04-16 15:20:36 -07002441 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2442 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2443 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Randy Dunlap94b3e032008-02-07 00:13:26 -08002444 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
Linus Torvalds1da177e2005-04-16 15:20:36 -07002445 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2446 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2447 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2448 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2449 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2450 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2451 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2452 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Martin Waitz9598f912006-02-01 03:06:55 -08002453 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2454 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Randy Dunlap412ecd772007-02-10 22:47:33 -08002455 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2456 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002457 $return_type = $1;
2458 $declaration_name = $2;
2459 my $args = $3;
2460
2461 create_parameterlist($args, ',', $file);
2462 } else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002463 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002464 return;
2465 }
2466
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002467 my $prms = join " ", @parameterlist;
2468 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2469
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002470 # This check emits a lot of warnings at the moment, because many
2471 # functions don't have a 'Return' doc section. So until the number
2472 # of warnings goes sufficiently down, the check is only performed in
2473 # verbose mode.
2474 # TODO: always perform the check.
Horia Geantacbb4d3e2014-07-12 09:55:03 -07002475 if ($verbose && !$noret) {
Yacine Belkadi4092bac2012-11-26 22:22:27 +01002476 check_return_section($file, $declaration_name, $return_type);
2477 }
2478
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002479 output_declaration($declaration_name,
Linus Torvalds1da177e2005-04-16 15:20:36 -07002480 'function',
2481 {'function' => $declaration_name,
2482 'module' => $modulename,
2483 'functiontype' => $return_type,
2484 'parameterlist' => \@parameterlist,
2485 'parameterdescs' => \%parameterdescs,
2486 'parametertypes' => \%parametertypes,
2487 'sectionlist' => \@sectionlist,
2488 'sections' => \%sections,
2489 'purpose' => $declaration_purpose
2490 });
2491}
2492
Linus Torvalds1da177e2005-04-16 15:20:36 -07002493sub reset_state {
2494 $function = "";
2495 %constants = ();
2496 %parameterdescs = ();
2497 %parametertypes = ();
2498 @parameterlist = ();
2499 %sections = ();
2500 @sectionlist = ();
Randy Dunlapa1d94aa2008-12-19 08:49:30 -08002501 $sectcheck = "";
2502 $struct_actual = "";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002503 $prototype = "";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002504
Jani Nikula48af6062016-05-26 14:56:05 +03002505 $state = STATE_NORMAL;
2506 $inline_doc_state = STATE_INLINE_NA;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002507}
2508
Jason Baron56afb0f2009-04-30 13:29:36 -04002509sub tracepoint_munge($) {
2510 my $file = shift;
2511 my $tracepointname = 0;
2512 my $tracepointargs = 0;
2513
Jason Baron3a9089f2009-12-01 12:18:49 -05002514 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
Jason Baron56afb0f2009-04-30 13:29:36 -04002515 $tracepointname = $1;
2516 }
Jason Baron3a9089f2009-12-01 12:18:49 -05002517 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2518 $tracepointname = $1;
2519 }
2520 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2521 $tracepointname = $2;
2522 }
2523 $tracepointname =~ s/^\s+//; #strip leading whitespace
2524 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
Jason Baron56afb0f2009-04-30 13:29:36 -04002525 $tracepointargs = $1;
2526 }
2527 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002528 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
Jason Baron56afb0f2009-04-30 13:29:36 -04002529 "$prototype\n";
2530 } else {
2531 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2532 }
2533}
2534
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002535sub syscall_munge() {
2536 my $void = 0;
2537
2538 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2539## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2540 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2541 $void = 1;
2542## $prototype = "long sys_$1(void)";
2543 }
2544
2545 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2546 if ($prototype =~ m/long (sys_.*?),/) {
2547 $prototype =~ s/,/\(/;
2548 } elsif ($void) {
2549 $prototype =~ s/\)/\(void\)/;
2550 }
2551
2552 # now delete all of the odd-number commas in $prototype
2553 # so that arg types & arg names don't have a comma between them
2554 my $count = 0;
2555 my $len = length($prototype);
2556 if ($void) {
2557 $len = 0; # skip the for-loop
2558 }
2559 for (my $ix = 0; $ix < $len; $ix++) {
2560 if (substr($prototype, $ix, 1) eq ',') {
2561 $count++;
2562 if ($count % 2 == 1) {
2563 substr($prototype, $ix, 1) = ' ';
2564 }
2565 }
2566 }
2567}
2568
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002569sub process_state3_function($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002570 my $x = shift;
2571 my $file = shift;
2572
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002573 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2574
Randy Dunlap890c78c2008-10-25 17:06:43 -07002575 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002576 # do nothing
2577 }
2578 elsif ($x =~ /([^\{]*)/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002579 $prototype .= $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002580 }
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002581
Randy Dunlap890c78c2008-10-25 17:06:43 -07002582 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002583 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
Linus Torvalds1da177e2005-04-16 15:20:36 -07002584 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2585 $prototype =~ s@^\s+@@gos; # strip leading spaces
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002586 if ($prototype =~ /SYSCALL_DEFINE/) {
2587 syscall_munge();
2588 }
Jason Baron3a9089f2009-12-01 12:18:49 -05002589 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2590 $prototype =~ /DEFINE_SINGLE_EVENT/)
2591 {
Jason Baron56afb0f2009-04-30 13:29:36 -04002592 tracepoint_munge($file);
2593 }
Randy Dunlapb4870bc2009-02-11 13:04:33 -08002594 dump_function($prototype, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002595 reset_state();
2596 }
2597}
2598
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002599sub process_state3_type($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002600 my $x = shift;
2601 my $file = shift;
2602
Linus Torvalds1da177e2005-04-16 15:20:36 -07002603 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2604 $x =~ s@^\s+@@gos; # strip leading spaces
2605 $x =~ s@\s+$@@gos; # strip trailing spaces
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002606 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2607
Linus Torvalds1da177e2005-04-16 15:20:36 -07002608 if ($x =~ /^#/) {
2609 # To distinguish preprocessor directive from regular declaration later.
2610 $x .= ";";
2611 }
2612
2613 while (1) {
Randy Dunlap3c308792007-05-08 00:24:39 -07002614 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002615 $prototype .= $1 . $2;
2616 ($2 eq '{') && $brcount++;
2617 ($2 eq '}') && $brcount--;
2618 if (($2 eq ';') && ($brcount == 0)) {
Randy Dunlapb9d973282009-06-09 08:50:38 -07002619 dump_declaration($prototype, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002620 reset_state();
Randy Dunlap3c308792007-05-08 00:24:39 -07002621 last;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002622 }
2623 $x = $3;
Randy Dunlap3c308792007-05-08 00:24:39 -07002624 } else {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002625 $prototype .= $x;
2626 last;
2627 }
2628 }
2629}
2630
Randy Dunlap6b5b55f2007-10-16 23:31:20 -07002631# xml_escape: replace <, >, and & in the text stream;
2632#
2633# however, formatting controls that are generated internally/locally in the
2634# kernel-doc script are not escaped here; instead, they begin life like
2635# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2636# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2637# just before actual output; (this is done by local_unescape())
Linus Torvalds1da177e2005-04-16 15:20:36 -07002638sub xml_escape($) {
2639 my $text = shift;
Randy Dunlapecfb2512006-06-25 05:49:13 -07002640 if (($output_mode eq "text") || ($output_mode eq "man")) {
2641 return $text;
2642 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002643 $text =~ s/\&/\\\\\\amp;/g;
2644 $text =~ s/\</\\\\\\lt;/g;
2645 $text =~ s/\>/\\\\\\gt;/g;
2646 return $text;
2647}
2648
Jonathan Corbetc0d1b6e2016-05-12 16:15:37 +03002649# xml_unescape: reverse the effects of xml_escape
2650sub xml_unescape($) {
2651 my $text = shift;
2652 if (($output_mode eq "text") || ($output_mode eq "man")) {
2653 return $text;
2654 }
2655 $text =~ s/\\\\\\amp;/\&/g;
2656 $text =~ s/\\\\\\lt;/</g;
2657 $text =~ s/\\\\\\gt;/>/g;
2658 return $text;
2659}
2660
Randy Dunlap6b5b55f2007-10-16 23:31:20 -07002661# convert local escape strings to html
2662# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2663sub local_unescape($) {
2664 my $text = shift;
2665 if (($output_mode eq "text") || ($output_mode eq "man")) {
2666 return $text;
2667 }
2668 $text =~ s/\\\\\\\\lt:/</g;
2669 $text =~ s/\\\\\\\\gt:/>/g;
2670 return $text;
2671}
2672
Linus Torvalds1da177e2005-04-16 15:20:36 -07002673sub process_file($) {
Randy Dunlap2283a112005-07-07 15:39:26 -07002674 my $file;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002675 my $identifier;
2676 my $func;
Randy Dunlapa21217d2007-02-10 01:46:04 -08002677 my $descr;
Johannes Weiner64231332009-09-17 19:26:53 -07002678 my $in_purpose = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002679 my $initial_section_counter = $section_counter;
Ben Hutchings68f86662015-09-01 23:48:49 +01002680 my ($orig_file) = @_;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002681
Randy Dunlap2283a112005-07-07 15:39:26 -07002682 if (defined($ENV{'SRCTREE'})) {
Ben Hutchings68f86662015-09-01 23:48:49 +01002683 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
Randy Dunlap2283a112005-07-07 15:39:26 -07002684 }
2685 else {
Ben Hutchings68f86662015-09-01 23:48:49 +01002686 $file = $orig_file;
Randy Dunlap2283a112005-07-07 15:39:26 -07002687 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002688 if (defined($source_map{$file})) {
2689 $file = $source_map{$file};
2690 }
2691
2692 if (!open(IN,"<$file")) {
2693 print STDERR "Error: Cannot open file $file\n";
2694 ++$errors;
2695 return;
2696 }
2697
Jani Nikula86ae2e32016-01-21 13:05:22 +02002698 # two passes for -export and -internal
2699 if ($function_only == 3 || $function_only == 4) {
2700 while (<IN>) {
2701 if (/$export_symbol/o) {
2702 $function_table{$2} = 1;
2703 }
2704 }
2705 seek(IN, 0, 0);
2706 }
2707
Ilya Dryomova9e73142010-02-26 13:05:47 -08002708 $. = 1;
2709
Linus Torvalds1da177e2005-04-16 15:20:36 -07002710 $section_counter = 0;
2711 while (<IN>) {
Daniel Santos65478422012-10-04 17:15:05 -07002712 while (s/\\\s*$//) {
2713 $_ .= <IN>;
2714 }
Jani Nikula48af6062016-05-26 14:56:05 +03002715 if ($state == STATE_NORMAL) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002716 if (/$doc_start/o) {
Jani Nikula48af6062016-05-26 14:56:05 +03002717 $state = STATE_NAME; # next line is always the function name
Randy Dunlap850622d2006-06-25 05:48:55 -07002718 $in_doc_sect = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002719 }
Jani Nikula48af6062016-05-26 14:56:05 +03002720 } elsif ($state == STATE_NAME) {# this line is the function name (always)
Linus Torvalds1da177e2005-04-16 15:20:36 -07002721 if (/$doc_block/o) {
Jani Nikula48af6062016-05-26 14:56:05 +03002722 $state = STATE_DOCBLOCK;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002723 $contents = "";
2724 if ( $1 eq "" ) {
2725 $section = $section_intro;
2726 } else {
2727 $section = $1;
2728 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002729 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002730 elsif (/$doc_decl/o) {
2731 $identifier = $1;
2732 if (/\s*([\w\s]+?)\s*-/) {
2733 $identifier = $1;
2734 }
2735
Jani Nikula48af6062016-05-26 14:56:05 +03002736 $state = STATE_FIELD;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002737 if (/-(.*)/) {
Randy Dunlap51f5a0c2007-07-19 01:48:24 -07002738 # strip leading/trailing/multiple spaces
Randy Dunlapa21217d2007-02-10 01:46:04 -08002739 $descr= $1;
2740 $descr =~ s/^\s*//;
2741 $descr =~ s/\s*$//;
Daniel Santos12ae6772012-10-04 17:15:10 -07002742 $descr =~ s/\s+/ /g;
Randy Dunlapa21217d2007-02-10 01:46:04 -08002743 $declaration_purpose = xml_escape($descr);
Johannes Weiner64231332009-09-17 19:26:53 -07002744 $in_purpose = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002745 } else {
2746 $declaration_purpose = "";
2747 }
Randy Dunlap77cc23b2008-02-07 00:13:42 -08002748
2749 if (($declaration_purpose eq "") && $verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002750 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
Randy Dunlap77cc23b2008-02-07 00:13:42 -08002751 print STDERR $_;
2752 ++$warnings;
2753 }
2754
Linus Torvalds1da177e2005-04-16 15:20:36 -07002755 if ($identifier =~ m/^struct/) {
2756 $decl_type = 'struct';
2757 } elsif ($identifier =~ m/^union/) {
2758 $decl_type = 'union';
2759 } elsif ($identifier =~ m/^enum/) {
2760 $decl_type = 'enum';
2761 } elsif ($identifier =~ m/^typedef/) {
2762 $decl_type = 'typedef';
2763 } else {
2764 $decl_type = 'function';
2765 }
2766
2767 if ($verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002768 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002769 }
2770 } else {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002771 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
Linus Torvalds1da177e2005-04-16 15:20:36 -07002772 " - I thought it was a doc line\n";
2773 ++$warnings;
Jani Nikula48af6062016-05-26 14:56:05 +03002774 $state = STATE_NORMAL;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002775 }
Jani Nikula48af6062016-05-26 14:56:05 +03002776 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
Linus Torvalds1da177e2005-04-16 15:20:36 -07002777 if (/$doc_sect/o) {
2778 $newsection = $1;
2779 $newcontents = $2;
2780
Randy Dunlap792aa2f2008-02-07 00:13:41 -08002781 if (($contents ne "") && ($contents ne "\n")) {
Randy Dunlap850622d2006-06-25 05:48:55 -07002782 if (!$in_doc_sect && $verbose) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002783 print STDERR "${file}:$.: warning: contents before sections\n";
Randy Dunlap850622d2006-06-25 05:48:55 -07002784 ++$warnings;
2785 }
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002786 dump_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002787 $section = $section_default;
2788 }
2789
Randy Dunlap850622d2006-06-25 05:48:55 -07002790 $in_doc_sect = 1;
Johannes Weiner64231332009-09-17 19:26:53 -07002791 $in_purpose = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002792 $contents = $newcontents;
2793 if ($contents ne "") {
Randy Dunlap27205742006-10-11 01:22:12 -07002794 while ((substr($contents, 0, 1) eq " ") ||
2795 substr($contents, 0, 1) eq "\t") {
2796 $contents = substr($contents, 1);
Randy Dunlap05189492006-06-25 05:47:47 -07002797 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002798 $contents .= "\n";
2799 }
2800 $section = $newsection;
2801 } elsif (/$doc_end/) {
Randy Dunlap4c98eca2010-03-10 15:22:02 -08002802 if (($contents ne "") && ($contents ne "\n")) {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002803 dump_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002804 $section = $section_default;
2805 $contents = "";
2806 }
Randy Dunlap46b958e2008-04-28 02:16:35 -07002807 # look for doc_com + <text> + doc_end:
2808 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002809 print STDERR "${file}:$.: warning: suspicious ending line: $_";
Randy Dunlap46b958e2008-04-28 02:16:35 -07002810 ++$warnings;
2811 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002812
2813 $prototype = "";
Jani Nikula48af6062016-05-26 14:56:05 +03002814 $state = STATE_PROTO;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002815 $brcount = 0;
Randy Dunlap232acbc2006-06-25 05:47:48 -07002816# print STDERR "end of doc comment, looking for prototype\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002817 } elsif (/$doc_content/) {
2818 # miguel-style comment kludge, look for blank lines after
2819 # @parameter line to signify start of description
Johannes Weiner64231332009-09-17 19:26:53 -07002820 if ($1 eq "") {
2821 if ($section =~ m/^@/ || $section eq $section_context) {
2822 dump_section($file, $section, xml_escape($contents));
2823 $section = $section_default;
2824 $contents = "";
2825 } else {
2826 $contents .= "\n";
2827 }
2828 $in_purpose = 0;
2829 } elsif ($in_purpose == 1) {
2830 # Continued declaration purpose
2831 chomp($declaration_purpose);
2832 $declaration_purpose .= " " . xml_escape($1);
Daniel Santos12ae6772012-10-04 17:15:10 -07002833 $declaration_purpose =~ s/\s+/ /g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002834 } else {
Randy Dunlapb9d973282009-06-09 08:50:38 -07002835 $contents .= $1 . "\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002836 }
2837 } else {
2838 # i dont know - bad line? ignore.
Bart Van Assched40e1e62015-09-04 15:43:21 -07002839 print STDERR "${file}:$.: warning: bad line: $_";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002840 ++$warnings;
2841 }
Jani Nikula48af6062016-05-26 14:56:05 +03002842 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002843 # First line (state 1) needs to be a @parameter
Jani Nikula48af6062016-05-26 14:56:05 +03002844 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002845 $section = $1;
2846 $contents = $2;
2847 if ($contents ne "") {
2848 while ((substr($contents, 0, 1) eq " ") ||
2849 substr($contents, 0, 1) eq "\t") {
2850 $contents = substr($contents, 1);
2851 }
2852 $contents .= "\n";
2853 }
Jani Nikula48af6062016-05-26 14:56:05 +03002854 $inline_doc_state = STATE_INLINE_TEXT;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002855 # Documentation block end */
Jani Nikula48af6062016-05-26 14:56:05 +03002856 } elsif (/$doc_inline_end/) {
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002857 if (($contents ne "") && ($contents ne "\n")) {
2858 dump_section($file, $section, xml_escape($contents));
2859 $section = $section_default;
2860 $contents = "";
2861 }
Jani Nikula48af6062016-05-26 14:56:05 +03002862 $state = STATE_PROTO;
2863 $inline_doc_state = STATE_INLINE_NA;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002864 # Regular text
2865 } elsif (/$doc_content/) {
Jani Nikula48af6062016-05-26 14:56:05 +03002866 if ($inline_doc_state == STATE_INLINE_TEXT) {
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002867 $contents .= $1 . "\n";
Jani Nikula48af6062016-05-26 14:56:05 +03002868 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2869 $inline_doc_state = STATE_INLINE_ERROR;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002870 print STDERR "Warning(${file}:$.): ";
2871 print STDERR "Incorrect use of kernel-doc format: $_";
2872 ++$warnings;
2873 }
2874 }
Jani Nikula48af6062016-05-26 14:56:05 +03002875 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2876 if (/$doc_inline_start/) {
2877 $state = STATE_INLINE;
2878 $inline_doc_state = STATE_INLINE_NAME;
Danilo Cesar Lemes de Paulaa4c6ebe2015-08-04 09:04:08 -03002879 } elsif ($decl_type eq 'function') {
Randy Dunlap3c308792007-05-08 00:24:39 -07002880 process_state3_function($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002881 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -07002882 process_state3_type($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07002883 }
Jani Nikula48af6062016-05-26 14:56:05 +03002884 } elsif ($state == STATE_DOCBLOCK) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07002885 # Documentation block
Randy Dunlap3c308792007-05-08 00:24:39 -07002886 if (/$doc_block/) {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002887 dump_doc_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002888 $contents = "";
2889 $function = "";
2890 %constants = ();
2891 %parameterdescs = ();
2892 %parametertypes = ();
2893 @parameterlist = ();
2894 %sections = ();
2895 @sectionlist = ();
2896 $prototype = "";
2897 if ( $1 eq "" ) {
2898 $section = $section_intro;
2899 } else {
2900 $section = $1;
2901 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002902 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002903 elsif (/$doc_end/)
2904 {
Randy Dunlap94dc7ad2008-04-28 02:16:34 -07002905 dump_doc_section($file, $section, xml_escape($contents));
Linus Torvalds1da177e2005-04-16 15:20:36 -07002906 $contents = "";
2907 $function = "";
2908 %constants = ();
2909 %parameterdescs = ();
2910 %parametertypes = ();
2911 @parameterlist = ();
2912 %sections = ();
2913 @sectionlist = ();
2914 $prototype = "";
Jani Nikula48af6062016-05-26 14:56:05 +03002915 $state = STATE_NORMAL;
Linus Torvalds1da177e2005-04-16 15:20:36 -07002916 }
2917 elsif (/$doc_content/)
2918 {
2919 if ( $1 eq "" )
2920 {
2921 $contents .= $blankline;
2922 }
2923 else
2924 {
2925 $contents .= $1 . "\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08002926 }
Randy Dunlap3c308792007-05-08 00:24:39 -07002927 }
2928 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002929 }
2930 if ($initial_section_counter == $section_counter) {
Bart Van Assched40e1e62015-09-04 15:43:21 -07002931 print STDERR "${file}:1: warning: no structured comments found\n";
Johannes Berge946c43a2013-11-12 15:11:12 -08002932 if (($function_only == 1) && ($show_not_found == 1)) {
2933 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2934 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07002935 if ($output_mode eq "xml") {
2936 # The template wants at least one RefEntry here; make one.
2937 print "<refentry>\n";
2938 print " <refnamediv>\n";
2939 print " <refname>\n";
Ben Hutchings68f86662015-09-01 23:48:49 +01002940 print " ${orig_file}\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002941 print " </refname>\n";
2942 print " <refpurpose>\n";
2943 print " Document generation inconsistency\n";
2944 print " </refpurpose>\n";
2945 print " </refnamediv>\n";
2946 print " <refsect1>\n";
2947 print " <title>\n";
2948 print " Oops\n";
2949 print " </title>\n";
2950 print " <warning>\n";
2951 print " <para>\n";
2952 print " The template for this document tried to insert\n";
2953 print " the structured comment from the file\n";
Ben Hutchings68f86662015-09-01 23:48:49 +01002954 print " <filename>${orig_file}</filename> at this point,\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07002955 print " but none was found.\n";
2956 print " This dummy section is inserted to allow\n";
2957 print " generation to continue.\n";
2958 print " </para>\n";
2959 print " </warning>\n";
2960 print " </refsect1>\n";
2961 print "</refentry>\n";
2962 }
2963 }
2964}
Randy Dunlap8484baa2011-01-05 16:28:43 -08002965
2966
2967$kernelversion = get_kernel_version();
2968
2969# generate a sequence of code that will splice in highlighting information
2970# using the s// operator.
Mauro Carvalho Chehab1ef06232015-11-17 13:29:49 -02002971for (my $k = 0; $k < @highlights; $k++) {
Danilo Cesar Lemes de Paula4d732702015-09-07 17:01:59 -03002972 my $pattern = $highlights[$k][0];
2973 my $result = $highlights[$k][1];
2974# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2975 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
Randy Dunlap8484baa2011-01-05 16:28:43 -08002976}
2977
2978# Read the file that maps relative names to absolute names for
2979# separate source and object directories and for shadow trees.
2980if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2981 my ($relname, $absname);
2982 while(<SOURCE_MAP>) {
2983 chop();
2984 ($relname, $absname) = (split())[0..1];
2985 $relname =~ s:^/+::;
2986 $source_map{$relname} = $absname;
2987 }
2988 close(SOURCE_MAP);
2989}
2990
2991foreach (@ARGV) {
2992 chomp;
2993 process_file($_);
2994}
2995if ($verbose && $errors) {
2996 print STDERR "$errors errors\n";
2997}
2998if ($verbose && $warnings) {
2999 print STDERR "$warnings warnings\n";
3000}
3001
3002exit($errors);