1 #!/usr/bin/env perl !! 1 #!/usr/bin/perl -w
2 # SPDX-License-Identifier: GPL-2.0 <<
3 # vim: softtabstop=4 <<
4 2
5 use warnings; <<
6 use strict; 3 use strict;
7 4
8 ## Copyright (c) 1998 Michael Zucchi, All Righ 5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
9 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@red 6 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
10 ## Copyright (C) 2001 Simon Huggins 7 ## Copyright (C) 2001 Simon Huggins ##
11 ## Copyright (C) 2005-2012 Randy Dunlap 8 ## Copyright (C) 2005-2012 Randy Dunlap ##
12 ## Copyright (C) 2012 Dan Luedtke 9 ## Copyright (C) 2012 Dan Luedtke ##
13 ## 10 ## ##
14 ## #define enhancements by Armin Kuster <akuste 11 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
15 ## Copyright (c) 2000 MontaVista Software, Inc 12 ## Copyright (c) 2000 MontaVista Software, Inc. ##
16 # !! 13 ## ##
17 # Copyright (C) 2022 Tomasz Warniełło (POD) !! 14 ## This software falls under the GNU General Public License. ##
18 !! 15 ## Please read the COPYING file for more information ##
19 use Pod::Usage qw/pod2usage/; <<
20 <<
21 =head1 NAME <<
22 <<
23 kernel-doc - Print formatted kernel documentat <<
24 <<
25 =head1 SYNOPSIS <<
26 <<
27 kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wret <<
28 [ -man | <<
29 -rst [-sphinx-version VERSION] [-enable-l <<
30 -none <<
31 ] <<
32 [ <<
33 -export | <<
34 -internal | <<
35 [-function NAME] ... | <<
36 [-nosymbol NAME] ... <<
37 ] <<
38 [-no-doc-sections] <<
39 [-export-file FILE] ... <<
40 FILE ... <<
41 <<
42 Run `kernel-doc -h` for details. <<
43 <<
44 =head1 DESCRIPTION <<
45 <<
46 Read C language source or header FILEs, extrac <<
47 and print formatted documentation to standard <<
48 <<
49 The documentation comments are identified by t <<
50 <<
51 See Documentation/doc-guide/kernel-doc.rst for <<
52 <<
53 =cut <<
54 16
55 # more perldoc at the end of the file !! 17 # 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
>> 39 # 25/07/2012 - Added support for HTML5
>> 40 # -- Dan Luedtke <mail@danrl.de>
>> 41
>> 42 #
>> 43 # This will read a 'c' file and scan for embedded comments in the
>> 44 # style of gnome comments (+minor extensions - see below).
>> 45 #
>> 46
>> 47 # Note: This only supports 'c'.
>> 48
>> 49 # usage:
>> 50 # kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
>> 51 # [ -no-doc-sections ]
>> 52 # [ -function funcname [ -function funcname ...] ]
>> 53 # c file(s)s > outputfile
>> 54 # or
>> 55 # [ -nofunction funcname [ -function funcname ...] ]
>> 56 # c file(s)s > outputfile
>> 57 #
>> 58 # Set output format using one of -docbook -html -html5 -text or -man.
>> 59 # Default is man.
>> 60 # The -list format is for internal use by docproc.
>> 61 #
>> 62 # -no-doc-sections
>> 63 # Do not output DOC: sections
>> 64 #
>> 65 # -function funcname
>> 66 # If set, then only generate documentation for the given function(s) or
>> 67 # DOC: section titles. All other functions and DOC: sections are ignored.
>> 68 #
>> 69 # -nofunction funcname
>> 70 # If set, then only generate documentation for the other function(s)/DOC:
>> 71 # sections. Cannot be used together with -function (yes, that's a bug --
>> 72 # perl hackers can fix it 8))
>> 73 #
>> 74 # c files - list of 'c' files to process
>> 75 #
>> 76 # All output goes to stdout, with errors to stderr.
>> 77
>> 78 #
>> 79 # format of comments.
>> 80 # In the following table, (...)? signifies optional structure.
>> 81 # (...)* signifies 0 or more structure elements
>> 82 # /**
>> 83 # * function_name(:)? (- short description)?
>> 84 # (* @parameterx: (description of parameter x)?)*
>> 85 # (* a blank line)?
>> 86 # * (Description:)? (Description of function)?
>> 87 # * (section header: (section description)? )*
>> 88 # (*)?*/
>> 89 #
>> 90 # So .. the trivial example would be:
>> 91 #
>> 92 # /**
>> 93 # * my_function
>> 94 # */
>> 95 #
>> 96 # If the Description: header tag is omitted, then there must be a blank line
>> 97 # after the last parameter specification.
>> 98 # e.g.
>> 99 # /**
>> 100 # * my_function - does my stuff
>> 101 # * @my_arg: its mine damnit
>> 102 # *
>> 103 # * Does my stuff explained.
>> 104 # */
>> 105 #
>> 106 # or, could also use:
>> 107 # /**
>> 108 # * my_function - does my stuff
>> 109 # * @my_arg: its mine damnit
>> 110 # * Description: Does my stuff explained.
>> 111 # */
>> 112 # etc.
>> 113 #
>> 114 # Besides functions you can also write documentation for structs, unions,
>> 115 # enums and typedefs. Instead of the function name you must write the name
>> 116 # of the declaration; the struct/union/enum/typedef must always precede
>> 117 # the name. Nesting of declarations is not supported.
>> 118 # Use the argument mechanism to document members or constants.
>> 119 # e.g.
>> 120 # /**
>> 121 # * struct my_struct - short description
>> 122 # * @a: first member
>> 123 # * @b: second member
>> 124 # *
>> 125 # * Longer description
>> 126 # */
>> 127 # struct my_struct {
>> 128 # int a;
>> 129 # int b;
>> 130 # /* private: */
>> 131 # int c;
>> 132 # };
>> 133 #
>> 134 # All descriptions can be multiline, except the short function description.
>> 135 #
>> 136 # You can also add additional sections. When documenting kernel functions you
>> 137 # should document the "Context:" of the function, e.g. whether the functions
>> 138 # can be called form interrupts. Unlike other sections you can end it with an
>> 139 # empty line.
>> 140 # A non-void function should have a "Return:" section describing the return
>> 141 # value(s).
>> 142 # Example-sections should contain the string EXAMPLE so that they are marked
>> 143 # appropriately in DocBook.
>> 144 #
>> 145 # Example:
>> 146 # /**
>> 147 # * user_function - function that can only be called in user context
>> 148 # * @a: some argument
>> 149 # * Context: !in_interrupt()
>> 150 # *
>> 151 # * Some description
>> 152 # * Example:
>> 153 # * user_function(22);
>> 154 # */
>> 155 # ...
>> 156 #
>> 157 #
>> 158 # All descriptive text is further processed, scanning for the following special
>> 159 # patterns, which are highlighted appropriately.
>> 160 #
>> 161 # 'funcname()' - function
>> 162 # '$ENVVAR' - environmental variable
>> 163 # '&struct_name' - name of a structure (up to two words including 'struct')
>> 164 # '@parameter' - name of a parameter
>> 165 # '%CONST' - name of a constant.
56 166
57 ## init lots of data 167 ## init lots of data
58 168
59 my $errors = 0; 169 my $errors = 0;
60 my $warnings = 0; 170 my $warnings = 0;
61 my $anon_struct_union = 0; 171 my $anon_struct_union = 0;
62 172
63 # match expressions used to find embedded type 173 # match expressions used to find embedded type information
64 my $type_constant = '\b``([^\`]+)``\b'; !! 174 my $type_constant = '\%([-_\w]+)';
65 my $type_constant2 = '\%([-_*\w]+)'; <<
66 my $type_func = '(\w+)\(\)'; 175 my $type_func = '(\w+)\(\)';
67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\ !! 176 my $type_param = '\@(\w+)';
68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+) !! 177 my $type_struct = '\&((struct\s*)*[_\w]+)';
69 my $type_fp_param = '\@(\w+)\(\)'; # Special !! 178 my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
70 my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Sp <<
71 my $type_env = '(\$\w+)'; 179 my $type_env = '(\$\w+)';
72 my $type_enum = '\&(enum\s*([_\w]+))'; <<
73 my $type_struct = '\&(struct\s*([_\w]+))'; <<
74 my $type_typedef = '\&(typedef\s*([_\w]+))'; <<
75 my $type_union = '\&(union\s*([_\w]+))'; <<
76 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; <<
77 my $type_fallback = '\&([_\w]+)'; <<
78 my $type_member_func = $type_member . '\(\)'; <<
79 180
80 # Output conversion substitutions. 181 # Output conversion substitutions.
81 # One for each output format 182 # One for each output format
82 183
>> 184 # these work fairly well
>> 185 my %highlights_html = ( $type_constant, "<i>\$1</i>",
>> 186 $type_func, "<b>\$1</b>",
>> 187 $type_struct_xml, "<i>\$1</i>",
>> 188 $type_env, "<b><i>\$1</i></b>",
>> 189 $type_param, "<tt><b>\$1</b></tt>" );
>> 190 my $local_lt = "\\\\\\\\lt:";
>> 191 my $local_gt = "\\\\\\\\gt:";
>> 192 my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
>> 193
>> 194 # html version 5
>> 195 my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
>> 196 $type_func, "<span class=\"func\">\$1</span>",
>> 197 $type_struct_xml, "<span class=\"struct\">\$1</span>",
>> 198 $type_env, "<span class=\"env\">\$1</span>",
>> 199 $type_param, "<span class=\"param\">\$1</span>" );
>> 200 my $blankline_html5 = $local_lt . "br /" . $local_gt;
>> 201
>> 202 # XML, docbook format
>> 203 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
>> 204 $type_constant, "<constant>\$1</constant>",
>> 205 $type_func, "<function>\$1</function>",
>> 206 $type_struct_xml, "<structname>\$1</structname>",
>> 207 $type_env, "<envar>\$1</envar>",
>> 208 $type_param, "<parameter>\$1</parameter>" );
>> 209 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
>> 210
>> 211 # gnome, docbook format
>> 212 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
>> 213 $type_func, "<function>\$1</function>",
>> 214 $type_struct, "<structname>\$1</structname>",
>> 215 $type_env, "<envar>\$1</envar>",
>> 216 $type_param, "<parameter>\$1</parameter>" );
>> 217 my $blankline_gnome = "</para><para>\n";
>> 218
83 # these are pretty rough 219 # these are pretty rough
84 my @highlights_man = ( !! 220 my %highlights_man = ( $type_constant, "\$1",
85 [$type_constant, "\$1"], !! 221 $type_func, "\\\\fB\$1\\\\fP",
86 [$type_constant2, "\$1"], !! 222 $type_struct, "\\\\fI\$1\\\\fP",
87 [$type_func, "\\\\fB\$1\\\\fP"], !! 223 $type_param, "\\\\fI\$1\\\\fP" );
88 [$type_enum, "\\\\fI\$1\\\\fP"], <<
89 [$type_struct, "\\\\fI\$1\\\\fP"], <<
90 [$type_typedef, "\\\\fI\$1\\\\fP"], <<
91 [$type_union, "\\\\fI\$1\\\\fP"], <<
92 [$type_param, "\\\\fI\$1\\\\fP"], <<
93 [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], <<
94 [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], <<
95 [$type_fallback, "\\\\fI\$1\\\\fP"] <<
96 ); <<
97 my $blankline_man = ""; 224 my $blankline_man = "";
98 225
99 # rst-mode !! 226 # text-mode
100 my @highlights_rst = ( !! 227 my %highlights_text = ( $type_constant, "\$1",
101 [$type_constant, "``\$1``"], !! 228 $type_func, "\$1",
102 [$type_constant2, "``\$1``"], !! 229 $type_struct, "\$1",
103 !! 230 $type_param, "\$1" );
104 # Note: need to escape () to avoid func ma !! 231 my $blankline_text = "";
105 [$type_member_func, "\\:c\\:type\\:`\$1\$2 !! 232
106 [$type_member, "\\:c\\:type\\:`\$1\$2\$3 < !! 233 # list mode
107 [$type_fp_param, "**\$1\\\\(\\\\)**"], !! 234 my %highlights_list = ( $type_constant, "\$1",
108 [$type_fp_param2, "**\$1\\\\(\\\\)**"], !! 235 $type_func, "\$1",
109 [$type_func, "\$1()"], !! 236 $type_struct, "\$1",
110 [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], !! 237 $type_param, "\$1" );
111 [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`" !! 238 my $blankline_list = "";
112 [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>` <<
113 [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"] <<
114 <<
115 # in rst this can refer to any type <<
116 [$type_fallback, "\\:c\\:type\\:`\$1`"], <<
117 [$type_param_ref, "**\$1\$2**"] <<
118 ); <<
119 my $blankline_rst = "\n"; <<
120 239
121 # read arguments 240 # read arguments
122 if ($#ARGV == -1) { 241 if ($#ARGV == -1) {
123 pod2usage( !! 242 usage();
124 -message => "No arguments!\n", <<
125 -exitval => 1, <<
126 -verbose => 99, <<
127 -sections => 'SYNOPSIS', <<
128 -output => \*STDERR, <<
129 ); <<
130 } 243 }
131 244
132 my $kernelversion; 245 my $kernelversion;
133 my ($sphinx_major, $sphinx_minor, $sphinx_patc <<
134 <<
135 my $dohighlight = ""; 246 my $dohighlight = "";
136 247
137 my $verbose = 0; 248 my $verbose = 0;
138 my $Werror = 0; !! 249 my $output_mode = "man";
139 my $Wreturn = 0; <<
140 my $Wshort_desc = 0; <<
141 my $Wcontents_before_sections = 0; <<
142 my $output_mode = "rst"; <<
143 my $output_preformatted = 0; 250 my $output_preformatted = 0;
144 my $no_doc_sections = 0; 251 my $no_doc_sections = 0;
145 my $enable_lineno = 0; !! 252 my %highlights = %highlights_man;
146 my @highlights = @highlights_rst; !! 253 my $blankline = $blankline_man;
147 my $blankline = $blankline_rst; <<
148 my $modulename = "Kernel API"; 254 my $modulename = "Kernel API";
149 !! 255 my $function_only = 0;
150 use constant { <<
151 OUTPUT_ALL => 0, # output all sym <<
152 OUTPUT_INCLUDE => 1, # output only sp <<
153 OUTPUT_EXPORTED => 2, # output exporte <<
154 OUTPUT_INTERNAL => 3, # output non-exp <<
155 }; <<
156 my $output_selection = OUTPUT_ALL; <<
157 my $show_not_found = 0; # No longer used <<
158 <<
159 my @export_file_list; <<
160 <<
161 my @build_time; <<
162 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && <<
163 (my $seconds = `date -d"${ENV{'KBUILD_BUIL <<
164 @build_time = gmtime($seconds); <<
165 } else { <<
166 @build_time = localtime; <<
167 } <<
168 <<
169 my $man_date = ('January', 'February', 'March' 256 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
170 'July', 'August', 'September', !! 257 'July', 'August', 'September', 'October',
171 'November', 'December')[$build !! 258 'November', 'December')[(localtime)[4]] .
172 " " . ($build_time[5]+1900); !! 259 " " . ((localtime)[5]+1900);
173 260
174 # Essentially these are globals. 261 # Essentially these are globals.
175 # They probably want to be tidied up, made mor 262 # They probably want to be tidied up, made more localised or something.
176 # CAVEAT EMPTOR! Some of the others I localis 263 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
177 # could cause "use of undefined value" or othe 264 # could cause "use of undefined value" or other bugs.
178 my ($function, %function_table, %parametertype 265 my ($function, %function_table, %parametertypes, $declaration_purpose);
179 my %nosymbol_table = (); <<
180 my $declaration_start_line; <<
181 my ($type, $declaration_name, $return_type); 266 my ($type, $declaration_name, $return_type);
182 my ($newsection, $newcontents, $prototype, $br 267 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
183 268
184 if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'K !! 269 if (defined($ENV{'KBUILD_VERBOSE'})) {
185 $verbose = 1; !! 270 $verbose = "$ENV{'KBUILD_VERBOSE'}";
186 } <<
187 <<
188 if (defined($ENV{'KCFLAGS'})) { <<
189 my $kcflags = "$ENV{'KCFLAGS'}"; <<
190 <<
191 if ($kcflags =~ /(\s|^)-Werror(\s|$)/) { <<
192 $Werror = 1; <<
193 } <<
194 } 271 }
195 272
196 # reading this variable is for backwards compa <<
197 # someone was calling it with the variable fro <<
198 # kernel's build system <<
199 if (defined($ENV{'KDOC_WERROR'})) { <<
200 $Werror = "$ENV{'KDOC_WERROR'}"; <<
201 } <<
202 # other environment variables are converted to <<
203 # arguments in cmd_checkdoc in the build syste <<
204 <<
205 # Generated docbook code is inserted in a temp 273 # Generated docbook code is inserted in a template at a point where
206 # docbook v3.1 requires a non-zero sequence of 274 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
207 # https://www.oasis-open.org/docbook/documenta !! 275 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
208 # We keep track of number of generated entries 276 # We keep track of number of generated entries and generate a dummy
209 # if needs be to ensure the expanded template 277 # if needs be to ensure the expanded template can be postprocessed
210 # into html. 278 # into html.
211 my $section_counter = 0; 279 my $section_counter = 0;
212 280
213 my $lineprefix=""; 281 my $lineprefix="";
214 282
215 # Parser states !! 283 # states
216 use constant { !! 284 # 0 - normal code
217 STATE_NORMAL => 0, # normal !! 285 # 1 - looking for function name
218 STATE_NAME => 1, # looking !! 286 # 2 - scanning field start.
219 STATE_BODY_MAYBE => 2, # body - !! 287 # 3 - scanning prototype.
220 STATE_BODY => 3, # the bod !! 288 # 4 - documentation block
221 STATE_BODY_WITH_BLANK_LINE => 4, # the bod <<
222 STATE_PROTO => 5, # scannin <<
223 STATE_DOCBLOCK => 6, # documen <<
224 STATE_INLINE => 7, # gatheri <<
225 }; <<
226 my $state; 289 my $state;
227 my $in_doc_sect; 290 my $in_doc_sect;
228 my $leading_space; <<
229 <<
230 # Inline documentation state <<
231 use constant { <<
232 STATE_INLINE_NA => 0, # not applicable <<
233 STATE_INLINE_NAME => 1, # looking for me <<
234 STATE_INLINE_TEXT => 2, # looking for me <<
235 STATE_INLINE_END => 3, # done <<
236 STATE_INLINE_ERROR => 4, # error - Commen <<
237 # Spit a warning <<
238 # proper kernel- <<
239 }; <<
240 my $inline_doc_state; <<
241 291
242 #declaration types: can be 292 #declaration types: can be
243 # 'function', 'struct', 'union', 'enum', 'type 293 # 'function', 'struct', 'union', 'enum', 'typedef'
244 my $decl_type; 294 my $decl_type;
245 295
246 # Name of the kernel-doc identifier for non-DO !! 296 my $doc_special = "\@\%\$\&";
247 my $identifier; <<
248 297
249 my $doc_start = '^/\*\*\s*$'; # Allow whitespa 298 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
250 my $doc_end = '\*/'; 299 my $doc_end = '\*/';
251 my $doc_com = '\s*\*\s*'; 300 my $doc_com = '\s*\*\s*';
252 my $doc_com_body = '\s*\* ?'; 301 my $doc_com_body = '\s*\* ?';
253 my $doc_decl = $doc_com . '(\w+)'; 302 my $doc_decl = $doc_com . '(\w+)';
254 # @params and a strictly limited set of suppor !! 303 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
255 # Specifically: <<
256 # Match @word: <<
257 # @...: <<
258 # @{section-name}: <<
259 # while trying to not match literal block star <<
260 # <<
261 my $doc_sect = $doc_com . <<
262 '\s*(\@[.\w]+|\@\.\.\.|description|context <<
263 my $doc_content = $doc_com_body . '(.*)'; 304 my $doc_content = $doc_com_body . '(.*)';
264 my $doc_block = $doc_com . 'DOC:\s*(.*)?'; 305 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
265 my $doc_inline_start = '^\s*/\*\*\s*$'; <<
266 my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.] <<
267 my $doc_inline_end = '^\s*\*/\s*$'; <<
268 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s] <<
269 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\ <<
270 my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_ <<
271 my $function_pointer = qr{([^\(]*\(\*)\s*\)\s* <<
272 my $attribute = qr{__attribute__\s*\(\([a-z0-9 <<
273 306
>> 307 my %constants;
274 my %parameterdescs; 308 my %parameterdescs;
275 my %parameterdesc_start_lines; <<
276 my @parameterlist; 309 my @parameterlist;
277 my %sections; 310 my %sections;
278 my @sectionlist; 311 my @sectionlist;
279 my %section_start_lines; <<
280 my $sectcheck; 312 my $sectcheck;
281 my $struct_actual; 313 my $struct_actual;
282 314
283 my $contents = ""; 315 my $contents = "";
284 my $new_start_line = 0; <<
285 <<
286 # the canonical section names. see also $doc_s <<
287 my $section_default = "Description"; # defa 316 my $section_default = "Description"; # default section
288 my $section_intro = "Introduction"; 317 my $section_intro = "Introduction";
289 my $section = $section_default; 318 my $section = $section_default;
290 my $section_context = "Context"; 319 my $section_context = "Context";
291 my $section_return = "Return"; 320 my $section_return = "Return";
292 321
293 my $undescribed = "-- undescribed --"; 322 my $undescribed = "-- undescribed --";
294 323
295 reset_state(); 324 reset_state();
296 325
297 while ($ARGV[0] =~ m/^--?(.*)/) { !! 326 while ($ARGV[0] =~ m/^-(.*)/) {
298 my $cmd = $1; !! 327 my $cmd = shift @ARGV;
299 shift @ARGV; !! 328 if ($cmd eq "-html") {
300 if ($cmd eq "man") { !! 329 $output_mode = "html";
301 $output_mode = "man"; !! 330 %highlights = %highlights_html;
302 @highlights = @highlights_man; !! 331 $blankline = $blankline_html;
303 $blankline = $blankline_man; !! 332 } elsif ($cmd eq "-html5") {
304 } elsif ($cmd eq "rst") { !! 333 $output_mode = "html5";
305 $output_mode = "rst"; !! 334 %highlights = %highlights_html5;
306 @highlights = @highlights_rst; !! 335 $blankline = $blankline_html5;
307 $blankline = $blankline_rst; !! 336 } elsif ($cmd eq "-man") {
308 } elsif ($cmd eq "none") { !! 337 $output_mode = "man";
309 $output_mode = "none"; !! 338 %highlights = %highlights_man;
310 } elsif ($cmd eq "module") { # not needed !! 339 $blankline = $blankline_man;
311 $modulename = shift @ARGV; !! 340 } elsif ($cmd eq "-text") {
312 } elsif ($cmd eq "function") { # to only o !! 341 $output_mode = "text";
313 $output_selection = OUTPUT_INCLUDE; !! 342 %highlights = %highlights_text;
314 $function = shift @ARGV; !! 343 $blankline = $blankline_text;
315 $function_table{$function} = 1; !! 344 } elsif ($cmd eq "-docbook") {
316 } elsif ($cmd eq "nosymbol") { # Exclude s !! 345 $output_mode = "xml";
317 my $symbol = shift @ARGV; !! 346 %highlights = %highlights_xml;
318 $nosymbol_table{$symbol} = 1; !! 347 $blankline = $blankline_xml;
319 } elsif ($cmd eq "export") { # only export !! 348 } elsif ($cmd eq "-list") {
320 $output_selection = OUTPUT_EXPORTED; !! 349 $output_mode = "list";
321 %function_table = (); !! 350 %highlights = %highlights_list;
322 } elsif ($cmd eq "internal") { # only non- !! 351 $blankline = $blankline_list;
323 $output_selection = OUTPUT_INTERNAL; !! 352 } elsif ($cmd eq "-gnome") {
324 %function_table = (); !! 353 $output_mode = "gnome";
325 } elsif ($cmd eq "export-file") { !! 354 %highlights = %highlights_gnome;
326 my $file = shift @ARGV; !! 355 $blankline = $blankline_gnome;
327 push(@export_file_list, $file); !! 356 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
328 } elsif ($cmd eq "v") { !! 357 $modulename = shift @ARGV;
329 $verbose = 1; !! 358 } elsif ($cmd eq "-function") { # to only output specific functions
330 } elsif ($cmd eq "Werror") { !! 359 $function_only = 1;
331 $Werror = 1; !! 360 $function = shift @ARGV;
332 } elsif ($cmd eq "Wreturn") { !! 361 $function_table{$function} = 1;
333 $Wreturn = 1; !! 362 } elsif ($cmd eq "-nofunction") { # to only output specific functions
334 } elsif ($cmd eq "Wshort-desc" or $cmd eq !! 363 $function_only = 2;
335 $Wshort_desc = 1; !! 364 $function = shift @ARGV;
336 } elsif ($cmd eq "Wcontents-before-section !! 365 $function_table{$function} = 1;
337 $Wcontents_before_sections = 1; !! 366 } elsif ($cmd eq "-v") {
338 } elsif ($cmd eq "Wall") { !! 367 $verbose = 1;
339 $Wreturn = 1; !! 368 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
340 $Wshort_desc = 1; !! 369 usage();
341 $Wcontents_before_sections = 1; !! 370 } elsif ($cmd eq '-no-doc-sections') {
342 } elsif (($cmd eq "h") || ($cmd eq "help") !! 371 $no_doc_sections = 1;
343 pod2usage(-exitval => 0, -verbose => 2 <<
344 } elsif ($cmd eq 'no-doc-sections') { <<
345 $no_doc_sections = 1; <<
346 } elsif ($cmd eq 'enable-lineno') { <<
347 $enable_lineno = 1; <<
348 } elsif ($cmd eq 'show-not-found') { <<
349 $show_not_found = 1; # A no-op but do <<
350 } elsif ($cmd eq "sphinx-version") { <<
351 my $ver_string = shift @ARGV; <<
352 if ($ver_string =~ m/^(\d+)(\.\d+)?(\. <<
353 $sphinx_major = $1; <<
354 if (defined($2)) { <<
355 $sphinx_minor = substr($2,1); <<
356 } else { <<
357 $sphinx_minor = 0; <<
358 } <<
359 if (defined($3)) { <<
360 $sphinx_patch = substr($3,1) <<
361 } else { <<
362 $sphinx_patch = 0; <<
363 } <<
364 } else { <<
365 die "Sphinx version should either <<
366 } <<
367 } else { <<
368 # Unknown argument <<
369 pod2usage( <<
370 -message => "Argument unknown!\n", <<
371 -exitval => 1, <<
372 -verbose => 99, <<
373 -sections => 'SYNOPSIS', <<
374 -output => \*STDERR, <<
375 ); <<
376 } <<
377 if ($#ARGV < 0){ <<
378 pod2usage( <<
379 -message => "FILE argument missing <<
380 -exitval => 1, <<
381 -verbose => 99, <<
382 -sections => 'SYNOPSIS', <<
383 -output => \*STDERR, <<
384 ); <<
385 } 372 }
386 } 373 }
387 374
388 # continue execution near EOF; 375 # continue execution near EOF;
389 376
390 # The C domain dialect changed on Sphinx 3. So !! 377 sub usage {
391 # version in order to produce the right tags. !! 378 print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
392 sub findprog($) !! 379 print " [ -no-doc-sections ]\n";
393 { !! 380 print " [ -function funcname [ -function funcname ...] ]\n";
394 foreach(split(/:/, $ENV{PATH})) { !! 381 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
395 return "$_/$_[0]" if(-x "$_/$_[0]"); !! 382 print " [ -v ]\n";
396 } !! 383 print " c source file(s) > outputfile\n";
397 } !! 384 print " -v : verbose output, more warnings & other info listed\n";
398 !! 385 exit 1;
399 sub get_sphinx_version() <<
400 { <<
401 my $ver; <<
402 <<
403 my $cmd = "sphinx-build"; <<
404 if (!findprog($cmd)) { <<
405 my $cmd = "sphinx-build3"; <<
406 if (!findprog($cmd)) { <<
407 $sphinx_major = 1; <<
408 $sphinx_minor = 2; <<
409 $sphinx_patch = 0; <<
410 printf STDERR "Warning: Sphinx ver <<
411 $sphinx_major, $sphinx_mino <<
412 return; <<
413 } <<
414 } <<
415 <<
416 open IN, "$cmd --version 2>&1 |"; <<
417 while (<IN>) { <<
418 if (m/^\s*sphinx-build\s+([\d]+)\.([\d <<
419 $sphinx_major = $1; <<
420 $sphinx_minor = $2; <<
421 $sphinx_patch = $3; <<
422 last; <<
423 } <<
424 # Sphinx 1.2.x uses a different format <<
425 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+ <<
426 $sphinx_major = $1; <<
427 $sphinx_minor = $2; <<
428 $sphinx_patch = $3; <<
429 last; <<
430 } <<
431 } <<
432 close IN; <<
433 } 386 }
434 387
435 # get kernel version from env 388 # get kernel version from env
436 sub get_kernel_version() { 389 sub get_kernel_version() {
437 my $version = 'unknown kernel version'; 390 my $version = 'unknown kernel version';
438 391
439 if (defined($ENV{'KERNELVERSION'})) { 392 if (defined($ENV{'KERNELVERSION'})) {
440 $version = $ENV{'KERNELVERSION'}; !! 393 $version = $ENV{'KERNELVERSION'};
441 } 394 }
442 return $version; 395 return $version;
443 } 396 }
444 397
445 # <<
446 sub print_lineno { <<
447 my $lineno = shift; <<
448 if ($enable_lineno && defined($lineno)) { <<
449 print ".. LINENO " . $lineno . "\n"; <<
450 } <<
451 } <<
452 <<
453 sub emit_warning { <<
454 my $location = shift; <<
455 my $msg = shift; <<
456 print STDERR "$location: warning: $msg"; <<
457 ++$warnings; <<
458 } <<
459 ## 398 ##
460 # dumps section contents to arrays/hashes inte 399 # dumps section contents to arrays/hashes intended for that purpose.
461 # 400 #
462 sub dump_section { 401 sub dump_section {
463 my $file = shift; 402 my $file = shift;
464 my $name = shift; 403 my $name = shift;
465 my $contents = join "\n", @_; 404 my $contents = join "\n", @_;
466 405
467 if ($name =~ m/$type_param/) { !! 406 if ($name =~ m/$type_constant/) {
468 $name = $1; !! 407 $name = $1;
469 $parameterdescs{$name} = $contents; !! 408 # print STDERR "constant section '$1' = '$contents'\n";
470 $sectcheck = $sectcheck . $name . " "; !! 409 $constants{$name} = $contents;
471 $parameterdesc_start_lines{$name} = $n !! 410 } elsif ($name =~ m/$type_param/) {
472 $new_start_line = 0; !! 411 # print STDERR "parameter def '$1' = '$contents'\n";
>> 412 $name = $1;
>> 413 $parameterdescs{$name} = $contents;
>> 414 $sectcheck = $sectcheck . $name . " ";
473 } elsif ($name eq "@\.\.\.") { 415 } elsif ($name eq "@\.\.\.") {
474 $name = "..."; !! 416 # print STDERR "parameter def '...' = '$contents'\n";
475 $parameterdescs{$name} = $contents; !! 417 $name = "...";
476 $sectcheck = $sectcheck . $name . " "; !! 418 $parameterdescs{$name} = $contents;
477 $parameterdesc_start_lines{$name} = $n !! 419 $sectcheck = $sectcheck . $name . " ";
478 $new_start_line = 0; <<
479 } else { 420 } else {
480 if (defined($sections{$name}) && ($sec !! 421 # print STDERR "other section '$name' = '$contents'\n";
481 # Only warn on user specified dupl !! 422 if (defined($sections{$name}) && ($sections{$name} ne "")) {
482 if ($name ne $section_default) { !! 423 print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
483 emit_warning("${file}:$.", "du !! 424 ++$errors;
484 } !! 425 }
485 $sections{$name} .= $contents; !! 426 $sections{$name} = $contents;
486 } else { !! 427 push @sectionlist, $name;
487 $sections{$name} = $contents; <<
488 push @sectionlist, $name; <<
489 $section_start_lines{$name} = $new <<
490 $new_start_line = 0; <<
491 } <<
492 } 428 }
493 } 429 }
494 430
495 ## 431 ##
496 # dump DOC: section after checking that it sho 432 # dump DOC: section after checking that it should go out
497 # 433 #
498 sub dump_doc_section { 434 sub dump_doc_section {
499 my $file = shift; 435 my $file = shift;
500 my $name = shift; 436 my $name = shift;
501 my $contents = join "\n", @_; 437 my $contents = join "\n", @_;
502 438
503 if ($no_doc_sections) { 439 if ($no_doc_sections) {
504 return; 440 return;
505 } 441 }
506 442
507 return if (defined($nosymbol_table{$name}) !! 443 if (($function_only == 0) ||
508 !! 444 ( $function_only == 1 && defined($function_table{$name})) ||
509 if (($output_selection == OUTPUT_ALL) || !! 445 ( $function_only == 2 && !defined($function_table{$name})))
510 (($output_selection == OUTPUT_INCLUDE) <<
511 defined($function_table{$name}))) <<
512 { 446 {
513 dump_section($file, $name, $contents); !! 447 dump_section($file, $name, $contents);
514 output_blockhead({'sectionlist' => \@s !! 448 output_blockhead({'sectionlist' => \@sectionlist,
515 'sections' => \%sect !! 449 'sections' => \%sections,
516 'module' => $modulen !! 450 'module' => $modulename,
517 'content-only' => ($ !! 451 'content-only' => ($function_only != 0), });
518 } 452 }
519 } 453 }
520 454
521 ## 455 ##
522 # output function 456 # output function
523 # 457 #
524 # parameterdescs, a hash. 458 # parameterdescs, a hash.
525 # function => "function name" 459 # function => "function name"
526 # parameterlist => @list of parameters 460 # parameterlist => @list of parameters
527 # parameterdescs => %parameter descriptions 461 # parameterdescs => %parameter descriptions
528 # sectionlist => @list of sections 462 # sectionlist => @list of sections
529 # sections => %section descriptions 463 # sections => %section descriptions
530 # 464 #
531 465
532 sub output_highlight { 466 sub output_highlight {
533 my $contents = join "\n",@_; 467 my $contents = join "\n",@_;
534 my $line; 468 my $line;
535 469
536 # DEBUG 470 # DEBUG
537 # if (!defined $contents) { 471 # if (!defined $contents) {
538 # use Carp; 472 # use Carp;
539 # confess "output_highlight got called w 473 # confess "output_highlight got called with no args?\n";
540 # } 474 # }
541 475
>> 476 if ($output_mode eq "html" || $output_mode eq "html5" ||
>> 477 $output_mode eq "xml") {
>> 478 $contents = local_unescape($contents);
>> 479 # convert data read & converted thru xml_escape() into &xyz; format:
>> 480 $contents =~ s/\\\\\\/\&/g;
>> 481 }
542 # print STDERR "contents b4:$contents\n"; 482 # print STDERR "contents b4:$contents\n";
543 eval $dohighlight; 483 eval $dohighlight;
544 die $@ if $@; 484 die $@ if $@;
545 # print STDERR "contents af:$contents\n"; 485 # print STDERR "contents af:$contents\n";
546 486
>> 487 # strip whitespaces when generating html5
>> 488 if ($output_mode eq "html5") {
>> 489 $contents =~ s/^\s+//;
>> 490 $contents =~ s/\s+$//;
>> 491 }
547 foreach $line (split "\n", $contents) { 492 foreach $line (split "\n", $contents) {
548 if (! $output_preformatted) { !! 493 if (! $output_preformatted) {
549 $line =~ s/^\s*//; !! 494 $line =~ s/^\s*//;
550 } !! 495 }
551 if ($line eq ""){ !! 496 if ($line eq ""){
552 if (! $output_preformatted) { !! 497 if (! $output_preformatted) {
553 print $lineprefix, $blankline; !! 498 print $lineprefix, local_unescape($blankline);
554 } !! 499 }
555 } else { !! 500 } else {
556 if ($output_mode eq "man" && subst !! 501 $line =~ s/\\\\\\/\&/g;
557 print "\\&$line"; !! 502 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
558 } else { !! 503 print "\\&$line";
559 print $lineprefix, $line; !! 504 } else {
560 } !! 505 print $lineprefix, $line;
561 } !! 506 }
562 print "\n"; !! 507 }
>> 508 print "\n";
563 } 509 }
564 } 510 }
565 511
>> 512 # output sections in html
>> 513 sub output_section_html(%) {
>> 514 my %args = %{$_[0]};
>> 515 my $section;
>> 516
>> 517 foreach $section (@{$args{'sectionlist'}}) {
>> 518 print "<h3>$section</h3>\n";
>> 519 print "<blockquote>\n";
>> 520 output_highlight($args{'sections'}{$section});
>> 521 print "</blockquote>\n";
>> 522 }
>> 523 }
>> 524
>> 525 # output enum in html
>> 526 sub output_enum_html(%) {
>> 527 my %args = %{$_[0]};
>> 528 my ($parameter);
>> 529 my $count;
>> 530 print "<h2>enum " . $args{'enum'} . "</h2>\n";
>> 531
>> 532 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
>> 533 $count = 0;
>> 534 foreach $parameter (@{$args{'parameterlist'}}) {
>> 535 print " <b>" . $parameter . "</b>";
>> 536 if ($count != $#{$args{'parameterlist'}}) {
>> 537 $count++;
>> 538 print ",\n";
>> 539 }
>> 540 print "<br>";
>> 541 }
>> 542 print "};<br>\n";
>> 543
>> 544 print "<h3>Constants</h3>\n";
>> 545 print "<dl>\n";
>> 546 foreach $parameter (@{$args{'parameterlist'}}) {
>> 547 print "<dt><b>" . $parameter . "</b>\n";
>> 548 print "<dd>";
>> 549 output_highlight($args{'parameterdescs'}{$parameter});
>> 550 }
>> 551 print "</dl>\n";
>> 552 output_section_html(@_);
>> 553 print "<hr>\n";
>> 554 }
>> 555
>> 556 # output typedef in html
>> 557 sub output_typedef_html(%) {
>> 558 my %args = %{$_[0]};
>> 559 my ($parameter);
>> 560 my $count;
>> 561 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
>> 562
>> 563 print "<b>typedef " . $args{'typedef'} . "</b>\n";
>> 564 output_section_html(@_);
>> 565 print "<hr>\n";
>> 566 }
>> 567
>> 568 # output struct in html
>> 569 sub output_struct_html(%) {
>> 570 my %args = %{$_[0]};
>> 571 my ($parameter);
>> 572
>> 573 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
>> 574 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
>> 575 foreach $parameter (@{$args{'parameterlist'}}) {
>> 576 if ($parameter =~ /^#/) {
>> 577 print "$parameter<br>\n";
>> 578 next;
>> 579 }
>> 580 my $parameter_name = $parameter;
>> 581 $parameter_name =~ s/\[.*//;
>> 582
>> 583 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 584 $type = $args{'parametertypes'}{$parameter};
>> 585 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 586 # pointer-to-function
>> 587 print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
>> 588 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 589 # bitfield
>> 590 print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
>> 591 } else {
>> 592 print " <i>$type</i> <b>$parameter</b>;<br>\n";
>> 593 }
>> 594 }
>> 595 print "};<br>\n";
>> 596
>> 597 print "<h3>Members</h3>\n";
>> 598 print "<dl>\n";
>> 599 foreach $parameter (@{$args{'parameterlist'}}) {
>> 600 ($parameter =~ /^#/) && next;
>> 601
>> 602 my $parameter_name = $parameter;
>> 603 $parameter_name =~ s/\[.*//;
>> 604
>> 605 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 606 print "<dt><b>" . $parameter . "</b>\n";
>> 607 print "<dd>";
>> 608 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 609 }
>> 610 print "</dl>\n";
>> 611 output_section_html(@_);
>> 612 print "<hr>\n";
>> 613 }
>> 614
>> 615 # output function in html
>> 616 sub output_function_html(%) {
>> 617 my %args = %{$_[0]};
>> 618 my ($parameter, $section);
>> 619 my $count;
>> 620
>> 621 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
>> 622 print "<i>" . $args{'functiontype'} . "</i>\n";
>> 623 print "<b>" . $args{'function'} . "</b>\n";
>> 624 print "(";
>> 625 $count = 0;
>> 626 foreach $parameter (@{$args{'parameterlist'}}) {
>> 627 $type = $args{'parametertypes'}{$parameter};
>> 628 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 629 # pointer-to-function
>> 630 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
>> 631 } else {
>> 632 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
>> 633 }
>> 634 if ($count != $#{$args{'parameterlist'}}) {
>> 635 $count++;
>> 636 print ",\n";
>> 637 }
>> 638 }
>> 639 print ")\n";
>> 640
>> 641 print "<h3>Arguments</h3>\n";
>> 642 print "<dl>\n";
>> 643 foreach $parameter (@{$args{'parameterlist'}}) {
>> 644 my $parameter_name = $parameter;
>> 645 $parameter_name =~ s/\[.*//;
>> 646
>> 647 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 648 print "<dt><b>" . $parameter . "</b>\n";
>> 649 print "<dd>";
>> 650 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 651 }
>> 652 print "</dl>\n";
>> 653 output_section_html(@_);
>> 654 print "<hr>\n";
>> 655 }
>> 656
>> 657 # output DOC: block header in html
>> 658 sub output_blockhead_html(%) {
>> 659 my %args = %{$_[0]};
>> 660 my ($parameter, $section);
>> 661 my $count;
>> 662
>> 663 foreach $section (@{$args{'sectionlist'}}) {
>> 664 print "<h3>$section</h3>\n";
>> 665 print "<ul>\n";
>> 666 output_highlight($args{'sections'}{$section});
>> 667 print "</ul>\n";
>> 668 }
>> 669 print "<hr>\n";
>> 670 }
>> 671
>> 672 # output sections in html5
>> 673 sub output_section_html5(%) {
>> 674 my %args = %{$_[0]};
>> 675 my $section;
>> 676
>> 677 foreach $section (@{$args{'sectionlist'}}) {
>> 678 print "<section>\n";
>> 679 print "<h1>$section</h1>\n";
>> 680 print "<p>\n";
>> 681 output_highlight($args{'sections'}{$section});
>> 682 print "</p>\n";
>> 683 print "</section>\n";
>> 684 }
>> 685 }
>> 686
>> 687 # output enum in html5
>> 688 sub output_enum_html5(%) {
>> 689 my %args = %{$_[0]};
>> 690 my ($parameter);
>> 691 my $count;
>> 692 my $html5id;
>> 693
>> 694 $html5id = $args{'enum'};
>> 695 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
>> 696 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
>> 697 print "<h1>enum " . $args{'enum'} . "</h1>\n";
>> 698 print "<ol class=\"code\">\n";
>> 699 print "<li>";
>> 700 print "<span class=\"keyword\">enum</span> ";
>> 701 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
>> 702 print "</li>\n";
>> 703 $count = 0;
>> 704 foreach $parameter (@{$args{'parameterlist'}}) {
>> 705 print "<li class=\"indent\">";
>> 706 print "<span class=\"param\">" . $parameter . "</span>";
>> 707 if ($count != $#{$args{'parameterlist'}}) {
>> 708 $count++;
>> 709 print ",";
>> 710 }
>> 711 print "</li>\n";
>> 712 }
>> 713 print "<li>};</li>\n";
>> 714 print "</ol>\n";
>> 715
>> 716 print "<section>\n";
>> 717 print "<h1>Constants</h1>\n";
>> 718 print "<dl>\n";
>> 719 foreach $parameter (@{$args{'parameterlist'}}) {
>> 720 print "<dt>" . $parameter . "</dt>\n";
>> 721 print "<dd>";
>> 722 output_highlight($args{'parameterdescs'}{$parameter});
>> 723 print "</dd>\n";
>> 724 }
>> 725 print "</dl>\n";
>> 726 print "</section>\n";
>> 727 output_section_html5(@_);
>> 728 print "</article>\n";
>> 729 }
>> 730
>> 731 # output typedef in html5
>> 732 sub output_typedef_html5(%) {
>> 733 my %args = %{$_[0]};
>> 734 my ($parameter);
>> 735 my $count;
>> 736 my $html5id;
>> 737
>> 738 $html5id = $args{'typedef'};
>> 739 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
>> 740 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
>> 741 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
>> 742
>> 743 print "<ol class=\"code\">\n";
>> 744 print "<li>";
>> 745 print "<span class=\"keyword\">typedef</span> ";
>> 746 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
>> 747 print "</li>\n";
>> 748 print "</ol>\n";
>> 749 output_section_html5(@_);
>> 750 print "</article>\n";
>> 751 }
>> 752
>> 753 # output struct in html5
>> 754 sub output_struct_html5(%) {
>> 755 my %args = %{$_[0]};
>> 756 my ($parameter);
>> 757 my $html5id;
>> 758
>> 759 $html5id = $args{'struct'};
>> 760 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
>> 761 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
>> 762 print "<hgroup>\n";
>> 763 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
>> 764 print "<h2>". $args{'purpose'} . "</h2>\n";
>> 765 print "</hgroup>\n";
>> 766 print "<ol class=\"code\">\n";
>> 767 print "<li>";
>> 768 print "<span class=\"type\">" . $args{'type'} . "</span> ";
>> 769 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
>> 770 print "</li>\n";
>> 771 foreach $parameter (@{$args{'parameterlist'}}) {
>> 772 print "<li class=\"indent\">";
>> 773 if ($parameter =~ /^#/) {
>> 774 print "<span class=\"param\">" . $parameter ."</span>\n";
>> 775 print "</li>\n";
>> 776 next;
>> 777 }
>> 778 my $parameter_name = $parameter;
>> 779 $parameter_name =~ s/\[.*//;
>> 780
>> 781 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 782 $type = $args{'parametertypes'}{$parameter};
>> 783 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 784 # pointer-to-function
>> 785 print "<span class=\"type\">$1</span> ";
>> 786 print "<span class=\"param\">$parameter</span>";
>> 787 print "<span class=\"type\">)</span> ";
>> 788 print "(<span class=\"args\">$2</span>);";
>> 789 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 790 # bitfield
>> 791 print "<span class=\"type\">$1</span> ";
>> 792 print "<span class=\"param\">$parameter</span>";
>> 793 print "<span class=\"bits\">$2</span>;";
>> 794 } else {
>> 795 print "<span class=\"type\">$type</span> ";
>> 796 print "<span class=\"param\">$parameter</span>;";
>> 797 }
>> 798 print "</li>\n";
>> 799 }
>> 800 print "<li>};</li>\n";
>> 801 print "</ol>\n";
>> 802
>> 803 print "<section>\n";
>> 804 print "<h1>Members</h1>\n";
>> 805 print "<dl>\n";
>> 806 foreach $parameter (@{$args{'parameterlist'}}) {
>> 807 ($parameter =~ /^#/) && next;
>> 808
>> 809 my $parameter_name = $parameter;
>> 810 $parameter_name =~ s/\[.*//;
>> 811
>> 812 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 813 print "<dt>" . $parameter . "</dt>\n";
>> 814 print "<dd>";
>> 815 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 816 print "</dd>\n";
>> 817 }
>> 818 print "</dl>\n";
>> 819 print "</section>\n";
>> 820 output_section_html5(@_);
>> 821 print "</article>\n";
>> 822 }
>> 823
>> 824 # output function in html5
>> 825 sub output_function_html5(%) {
>> 826 my %args = %{$_[0]};
>> 827 my ($parameter, $section);
>> 828 my $count;
>> 829 my $html5id;
>> 830
>> 831 $html5id = $args{'function'};
>> 832 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
>> 833 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
>> 834 print "<hgroup>\n";
>> 835 print "<h1>" . $args{'function'} . "</h1>";
>> 836 print "<h2>" . $args{'purpose'} . "</h2>\n";
>> 837 print "</hgroup>\n";
>> 838 print "<ol class=\"code\">\n";
>> 839 print "<li>";
>> 840 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
>> 841 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
>> 842 print "</li>";
>> 843 $count = 0;
>> 844 foreach $parameter (@{$args{'parameterlist'}}) {
>> 845 print "<li class=\"indent\">";
>> 846 $type = $args{'parametertypes'}{$parameter};
>> 847 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 848 # pointer-to-function
>> 849 print "<span class=\"type\">$1</span> ";
>> 850 print "<span class=\"param\">$parameter</span>";
>> 851 print "<span class=\"type\">)</span> ";
>> 852 print "(<span class=\"args\">$2</span>)";
>> 853 } else {
>> 854 print "<span class=\"type\">$type</span> ";
>> 855 print "<span class=\"param\">$parameter</span>";
>> 856 }
>> 857 if ($count != $#{$args{'parameterlist'}}) {
>> 858 $count++;
>> 859 print ",";
>> 860 }
>> 861 print "</li>\n";
>> 862 }
>> 863 print "<li>)</li>\n";
>> 864 print "</ol>\n";
>> 865
>> 866 print "<section>\n";
>> 867 print "<h1>Arguments</h1>\n";
>> 868 print "<p>\n";
>> 869 print "<dl>\n";
>> 870 foreach $parameter (@{$args{'parameterlist'}}) {
>> 871 my $parameter_name = $parameter;
>> 872 $parameter_name =~ s/\[.*//;
>> 873
>> 874 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 875 print "<dt>" . $parameter . "</dt>\n";
>> 876 print "<dd>";
>> 877 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 878 print "</dd>\n";
>> 879 }
>> 880 print "</dl>\n";
>> 881 print "</section>\n";
>> 882 output_section_html5(@_);
>> 883 print "</article>\n";
>> 884 }
>> 885
>> 886 # output DOC: block header in html5
>> 887 sub output_blockhead_html5(%) {
>> 888 my %args = %{$_[0]};
>> 889 my ($parameter, $section);
>> 890 my $count;
>> 891 my $html5id;
>> 892
>> 893 foreach $section (@{$args{'sectionlist'}}) {
>> 894 $html5id = $section;
>> 895 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
>> 896 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
>> 897 print "<h1>$section</h1>\n";
>> 898 print "<p>\n";
>> 899 output_highlight($args{'sections'}{$section});
>> 900 print "</p>\n";
>> 901 }
>> 902 print "</article>\n";
>> 903 }
>> 904
>> 905 sub output_section_xml(%) {
>> 906 my %args = %{$_[0]};
>> 907 my $section;
>> 908 # print out each section
>> 909 $lineprefix=" ";
>> 910 foreach $section (@{$args{'sectionlist'}}) {
>> 911 print "<refsect1>\n";
>> 912 print "<title>$section</title>\n";
>> 913 if ($section =~ m/EXAMPLE/i) {
>> 914 print "<informalexample><programlisting>\n";
>> 915 $output_preformatted = 1;
>> 916 } else {
>> 917 print "<para>\n";
>> 918 }
>> 919 output_highlight($args{'sections'}{$section});
>> 920 $output_preformatted = 0;
>> 921 if ($section =~ m/EXAMPLE/i) {
>> 922 print "</programlisting></informalexample>\n";
>> 923 } else {
>> 924 print "</para>\n";
>> 925 }
>> 926 print "</refsect1>\n";
>> 927 }
>> 928 }
>> 929
>> 930 # output function in XML DocBook
>> 931 sub output_function_xml(%) {
>> 932 my %args = %{$_[0]};
>> 933 my ($parameter, $section);
>> 934 my $count;
>> 935 my $id;
>> 936
>> 937 $id = "API-" . $args{'function'};
>> 938 $id =~ s/[^A-Za-z0-9]/-/g;
>> 939
>> 940 print "<refentry id=\"$id\">\n";
>> 941 print "<refentryinfo>\n";
>> 942 print " <title>LINUX</title>\n";
>> 943 print " <productname>Kernel Hackers Manual</productname>\n";
>> 944 print " <date>$man_date</date>\n";
>> 945 print "</refentryinfo>\n";
>> 946 print "<refmeta>\n";
>> 947 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
>> 948 print " <manvolnum>9</manvolnum>\n";
>> 949 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
>> 950 print "</refmeta>\n";
>> 951 print "<refnamediv>\n";
>> 952 print " <refname>" . $args{'function'} . "</refname>\n";
>> 953 print " <refpurpose>\n";
>> 954 print " ";
>> 955 output_highlight ($args{'purpose'});
>> 956 print " </refpurpose>\n";
>> 957 print "</refnamediv>\n";
>> 958
>> 959 print "<refsynopsisdiv>\n";
>> 960 print " <title>Synopsis</title>\n";
>> 961 print " <funcsynopsis><funcprototype>\n";
>> 962 print " <funcdef>" . $args{'functiontype'} . " ";
>> 963 print "<function>" . $args{'function'} . " </function></funcdef>\n";
>> 964
>> 965 $count = 0;
>> 966 if ($#{$args{'parameterlist'}} >= 0) {
>> 967 foreach $parameter (@{$args{'parameterlist'}}) {
>> 968 $type = $args{'parametertypes'}{$parameter};
>> 969 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 970 # pointer-to-function
>> 971 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
>> 972 print " <funcparams>$2</funcparams></paramdef>\n";
>> 973 } else {
>> 974 print " <paramdef>" . $type;
>> 975 print " <parameter>$parameter</parameter></paramdef>\n";
>> 976 }
>> 977 }
>> 978 } else {
>> 979 print " <void/>\n";
>> 980 }
>> 981 print " </funcprototype></funcsynopsis>\n";
>> 982 print "</refsynopsisdiv>\n";
>> 983
>> 984 # print parameters
>> 985 print "<refsect1>\n <title>Arguments</title>\n";
>> 986 if ($#{$args{'parameterlist'}} >= 0) {
>> 987 print " <variablelist>\n";
>> 988 foreach $parameter (@{$args{'parameterlist'}}) {
>> 989 my $parameter_name = $parameter;
>> 990 $parameter_name =~ s/\[.*//;
>> 991
>> 992 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
>> 993 print " <listitem>\n <para>\n";
>> 994 $lineprefix=" ";
>> 995 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 996 print " </para>\n </listitem>\n </varlistentry>\n";
>> 997 }
>> 998 print " </variablelist>\n";
>> 999 } else {
>> 1000 print " <para>\n None\n </para>\n";
>> 1001 }
>> 1002 print "</refsect1>\n";
>> 1003
>> 1004 output_section_xml(@_);
>> 1005 print "</refentry>\n\n";
>> 1006 }
>> 1007
>> 1008 # output struct in XML DocBook
>> 1009 sub output_struct_xml(%) {
>> 1010 my %args = %{$_[0]};
>> 1011 my ($parameter, $section);
>> 1012 my $id;
>> 1013
>> 1014 $id = "API-struct-" . $args{'struct'};
>> 1015 $id =~ s/[^A-Za-z0-9]/-/g;
>> 1016
>> 1017 print "<refentry id=\"$id\">\n";
>> 1018 print "<refentryinfo>\n";
>> 1019 print " <title>LINUX</title>\n";
>> 1020 print " <productname>Kernel Hackers Manual</productname>\n";
>> 1021 print " <date>$man_date</date>\n";
>> 1022 print "</refentryinfo>\n";
>> 1023 print "<refmeta>\n";
>> 1024 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
>> 1025 print " <manvolnum>9</manvolnum>\n";
>> 1026 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
>> 1027 print "</refmeta>\n";
>> 1028 print "<refnamediv>\n";
>> 1029 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
>> 1030 print " <refpurpose>\n";
>> 1031 print " ";
>> 1032 output_highlight ($args{'purpose'});
>> 1033 print " </refpurpose>\n";
>> 1034 print "</refnamediv>\n";
>> 1035
>> 1036 print "<refsynopsisdiv>\n";
>> 1037 print " <title>Synopsis</title>\n";
>> 1038 print " <programlisting>\n";
>> 1039 print $args{'type'} . " " . $args{'struct'} . " {\n";
>> 1040 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1041 if ($parameter =~ /^#/) {
>> 1042 my $prm = $parameter;
>> 1043 # convert data read & converted thru xml_escape() into &xyz; format:
>> 1044 # This allows us to have #define macros interspersed in a struct.
>> 1045 $prm =~ s/\\\\\\/\&/g;
>> 1046 print "$prm\n";
>> 1047 next;
>> 1048 }
>> 1049
>> 1050 my $parameter_name = $parameter;
>> 1051 $parameter_name =~ s/\[.*//;
>> 1052
>> 1053 defined($args{'parameterdescs'}{$parameter_name}) || next;
>> 1054 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 1055 $type = $args{'parametertypes'}{$parameter};
>> 1056 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 1057 # pointer-to-function
>> 1058 print " $1 $parameter) ($2);\n";
>> 1059 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 1060 # bitfield
>> 1061 print " $1 $parameter$2;\n";
>> 1062 } else {
>> 1063 print " " . $type . " " . $parameter . ";\n";
>> 1064 }
>> 1065 }
>> 1066 print "};";
>> 1067 print " </programlisting>\n";
>> 1068 print "</refsynopsisdiv>\n";
>> 1069
>> 1070 print " <refsect1>\n";
>> 1071 print " <title>Members</title>\n";
>> 1072
>> 1073 if ($#{$args{'parameterlist'}} >= 0) {
>> 1074 print " <variablelist>\n";
>> 1075 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1076 ($parameter =~ /^#/) && next;
>> 1077
>> 1078 my $parameter_name = $parameter;
>> 1079 $parameter_name =~ s/\[.*//;
>> 1080
>> 1081 defined($args{'parameterdescs'}{$parameter_name}) || next;
>> 1082 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 1083 print " <varlistentry>";
>> 1084 print " <term>$parameter</term>\n";
>> 1085 print " <listitem><para>\n";
>> 1086 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 1087 print " </para></listitem>\n";
>> 1088 print " </varlistentry>\n";
>> 1089 }
>> 1090 print " </variablelist>\n";
>> 1091 } else {
>> 1092 print " <para>\n None\n </para>\n";
>> 1093 }
>> 1094 print " </refsect1>\n";
>> 1095
>> 1096 output_section_xml(@_);
>> 1097
>> 1098 print "</refentry>\n\n";
>> 1099 }
>> 1100
>> 1101 # output enum in XML DocBook
>> 1102 sub output_enum_xml(%) {
>> 1103 my %args = %{$_[0]};
>> 1104 my ($parameter, $section);
>> 1105 my $count;
>> 1106 my $id;
>> 1107
>> 1108 $id = "API-enum-" . $args{'enum'};
>> 1109 $id =~ s/[^A-Za-z0-9]/-/g;
>> 1110
>> 1111 print "<refentry id=\"$id\">\n";
>> 1112 print "<refentryinfo>\n";
>> 1113 print " <title>LINUX</title>\n";
>> 1114 print " <productname>Kernel Hackers Manual</productname>\n";
>> 1115 print " <date>$man_date</date>\n";
>> 1116 print "</refentryinfo>\n";
>> 1117 print "<refmeta>\n";
>> 1118 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
>> 1119 print " <manvolnum>9</manvolnum>\n";
>> 1120 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
>> 1121 print "</refmeta>\n";
>> 1122 print "<refnamediv>\n";
>> 1123 print " <refname>enum " . $args{'enum'} . "</refname>\n";
>> 1124 print " <refpurpose>\n";
>> 1125 print " ";
>> 1126 output_highlight ($args{'purpose'});
>> 1127 print " </refpurpose>\n";
>> 1128 print "</refnamediv>\n";
>> 1129
>> 1130 print "<refsynopsisdiv>\n";
>> 1131 print " <title>Synopsis</title>\n";
>> 1132 print " <programlisting>\n";
>> 1133 print "enum " . $args{'enum'} . " {\n";
>> 1134 $count = 0;
>> 1135 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1136 print " $parameter";
>> 1137 if ($count != $#{$args{'parameterlist'}}) {
>> 1138 $count++;
>> 1139 print ",";
>> 1140 }
>> 1141 print "\n";
>> 1142 }
>> 1143 print "};";
>> 1144 print " </programlisting>\n";
>> 1145 print "</refsynopsisdiv>\n";
>> 1146
>> 1147 print "<refsect1>\n";
>> 1148 print " <title>Constants</title>\n";
>> 1149 print " <variablelist>\n";
>> 1150 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1151 my $parameter_name = $parameter;
>> 1152 $parameter_name =~ s/\[.*//;
>> 1153
>> 1154 print " <varlistentry>";
>> 1155 print " <term>$parameter</term>\n";
>> 1156 print " <listitem><para>\n";
>> 1157 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 1158 print " </para></listitem>\n";
>> 1159 print " </varlistentry>\n";
>> 1160 }
>> 1161 print " </variablelist>\n";
>> 1162 print "</refsect1>\n";
>> 1163
>> 1164 output_section_xml(@_);
>> 1165
>> 1166 print "</refentry>\n\n";
>> 1167 }
>> 1168
>> 1169 # output typedef in XML DocBook
>> 1170 sub output_typedef_xml(%) {
>> 1171 my %args = %{$_[0]};
>> 1172 my ($parameter, $section);
>> 1173 my $id;
>> 1174
>> 1175 $id = "API-typedef-" . $args{'typedef'};
>> 1176 $id =~ s/[^A-Za-z0-9]/-/g;
>> 1177
>> 1178 print "<refentry id=\"$id\">\n";
>> 1179 print "<refentryinfo>\n";
>> 1180 print " <title>LINUX</title>\n";
>> 1181 print " <productname>Kernel Hackers Manual</productname>\n";
>> 1182 print " <date>$man_date</date>\n";
>> 1183 print "</refentryinfo>\n";
>> 1184 print "<refmeta>\n";
>> 1185 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
>> 1186 print " <manvolnum>9</manvolnum>\n";
>> 1187 print "</refmeta>\n";
>> 1188 print "<refnamediv>\n";
>> 1189 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
>> 1190 print " <refpurpose>\n";
>> 1191 print " ";
>> 1192 output_highlight ($args{'purpose'});
>> 1193 print " </refpurpose>\n";
>> 1194 print "</refnamediv>\n";
>> 1195
>> 1196 print "<refsynopsisdiv>\n";
>> 1197 print " <title>Synopsis</title>\n";
>> 1198 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
>> 1199 print "</refsynopsisdiv>\n";
>> 1200
>> 1201 output_section_xml(@_);
>> 1202
>> 1203 print "</refentry>\n\n";
>> 1204 }
>> 1205
>> 1206 # output in XML DocBook
>> 1207 sub output_blockhead_xml(%) {
>> 1208 my %args = %{$_[0]};
>> 1209 my ($parameter, $section);
>> 1210 my $count;
>> 1211
>> 1212 my $id = $args{'module'};
>> 1213 $id =~ s/[^A-Za-z0-9]/-/g;
>> 1214
>> 1215 # print out each section
>> 1216 $lineprefix=" ";
>> 1217 foreach $section (@{$args{'sectionlist'}}) {
>> 1218 if (!$args{'content-only'}) {
>> 1219 print "<refsect1>\n <title>$section</title>\n";
>> 1220 }
>> 1221 if ($section =~ m/EXAMPLE/i) {
>> 1222 print "<example><para>\n";
>> 1223 $output_preformatted = 1;
>> 1224 } else {
>> 1225 print "<para>\n";
>> 1226 }
>> 1227 output_highlight($args{'sections'}{$section});
>> 1228 $output_preformatted = 0;
>> 1229 if ($section =~ m/EXAMPLE/i) {
>> 1230 print "</para></example>\n";
>> 1231 } else {
>> 1232 print "</para>";
>> 1233 }
>> 1234 if (!$args{'content-only'}) {
>> 1235 print "\n</refsect1>\n";
>> 1236 }
>> 1237 }
>> 1238
>> 1239 print "\n\n";
>> 1240 }
>> 1241
>> 1242 # output in XML DocBook
>> 1243 sub output_function_gnome {
>> 1244 my %args = %{$_[0]};
>> 1245 my ($parameter, $section);
>> 1246 my $count;
>> 1247 my $id;
>> 1248
>> 1249 $id = $args{'module'} . "-" . $args{'function'};
>> 1250 $id =~ s/[^A-Za-z0-9]/-/g;
>> 1251
>> 1252 print "<sect2>\n";
>> 1253 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
>> 1254
>> 1255 print " <funcsynopsis>\n";
>> 1256 print " <funcdef>" . $args{'functiontype'} . " ";
>> 1257 print "<function>" . $args{'function'} . " ";
>> 1258 print "</function></funcdef>\n";
>> 1259
>> 1260 $count = 0;
>> 1261 if ($#{$args{'parameterlist'}} >= 0) {
>> 1262 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1263 $type = $args{'parametertypes'}{$parameter};
>> 1264 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 1265 # pointer-to-function
>> 1266 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
>> 1267 print " <funcparams>$2</funcparams></paramdef>\n";
>> 1268 } else {
>> 1269 print " <paramdef>" . $type;
>> 1270 print " <parameter>$parameter</parameter></paramdef>\n";
>> 1271 }
>> 1272 }
>> 1273 } else {
>> 1274 print " <void>\n";
>> 1275 }
>> 1276 print " </funcsynopsis>\n";
>> 1277 if ($#{$args{'parameterlist'}} >= 0) {
>> 1278 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
>> 1279 print "<tgroup cols=\"2\">\n";
>> 1280 print "<colspec colwidth=\"2*\">\n";
>> 1281 print "<colspec colwidth=\"8*\">\n";
>> 1282 print "<tbody>\n";
>> 1283 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1284 my $parameter_name = $parameter;
>> 1285 $parameter_name =~ s/\[.*//;
>> 1286
>> 1287 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
>> 1288 print " <entry>\n";
>> 1289 $lineprefix=" ";
>> 1290 output_highlight($args{'parameterdescs'}{$parameter_name});
>> 1291 print " </entry></row>\n";
>> 1292 }
>> 1293 print " </tbody></tgroup></informaltable>\n";
>> 1294 } else {
>> 1295 print " <para>\n None\n </para>\n";
>> 1296 }
>> 1297
>> 1298 # print out each section
>> 1299 $lineprefix=" ";
>> 1300 foreach $section (@{$args{'sectionlist'}}) {
>> 1301 print "<simplesect>\n <title>$section</title>\n";
>> 1302 if ($section =~ m/EXAMPLE/i) {
>> 1303 print "<example><programlisting>\n";
>> 1304 $output_preformatted = 1;
>> 1305 } else {
>> 1306 }
>> 1307 print "<para>\n";
>> 1308 output_highlight($args{'sections'}{$section});
>> 1309 $output_preformatted = 0;
>> 1310 print "</para>\n";
>> 1311 if ($section =~ m/EXAMPLE/i) {
>> 1312 print "</programlisting></example>\n";
>> 1313 } else {
>> 1314 }
>> 1315 print " </simplesect>\n";
>> 1316 }
>> 1317
>> 1318 print "</sect2>\n\n";
>> 1319 }
>> 1320
566 ## 1321 ##
567 # output function in man 1322 # output function in man
568 sub output_function_man(%) { 1323 sub output_function_man(%) {
569 my %args = %{$_[0]}; 1324 my %args = %{$_[0]};
570 my ($parameter, $section); 1325 my ($parameter, $section);
571 my $count; 1326 my $count;
572 1327
573 print ".TH \"$args{'function'}\" 9 \"$args 1328 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
574 1329
575 print ".SH NAME\n"; 1330 print ".SH NAME\n";
576 print $args{'function'} . " \\- " . $args{ 1331 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
577 1332
578 print ".SH SYNOPSIS\n"; 1333 print ".SH SYNOPSIS\n";
579 if ($args{'functiontype'} ne "") { 1334 if ($args{'functiontype'} ne "") {
580 print ".B \"" . $args{'functiontype'} !! 1335 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
581 } else { 1336 } else {
582 print ".B \"" . $args{'function'} . "\ !! 1337 print ".B \"" . $args{'function'} . "\n";
583 } 1338 }
584 $count = 0; 1339 $count = 0;
585 my $parenth = "("; 1340 my $parenth = "(";
586 my $post = ","; 1341 my $post = ",";
587 foreach my $parameter (@{$args{'parameterl 1342 foreach my $parameter (@{$args{'parameterlist'}}) {
588 if ($count == $#{$args{'parameterlist' !! 1343 if ($count == $#{$args{'parameterlist'}}) {
589 $post = ");"; !! 1344 $post = ");";
590 } !! 1345 }
591 $type = $args{'parametertypes'}{$param !! 1346 $type = $args{'parametertypes'}{$parameter};
592 if ($type =~ m/$function_pointer/) { !! 1347 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
593 # pointer-to-function !! 1348 # pointer-to-function
594 print ".BI \"" . $parenth . $1 . " !! 1349 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
595 } else { !! 1350 } else {
596 $type =~ s/([^\*])$/$1 /; !! 1351 $type =~ s/([^\*])$/$1 /;
597 print ".BI \"" . $parenth . $type !! 1352 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
598 } !! 1353 }
599 $count++; !! 1354 $count++;
600 $parenth = ""; !! 1355 $parenth = "";
601 } 1356 }
602 1357
603 print ".SH ARGUMENTS\n"; 1358 print ".SH ARGUMENTS\n";
604 foreach $parameter (@{$args{'parameterlist 1359 foreach $parameter (@{$args{'parameterlist'}}) {
605 my $parameter_name = $parameter; !! 1360 my $parameter_name = $parameter;
606 $parameter_name =~ s/\[.*//; !! 1361 $parameter_name =~ s/\[.*//;
607 1362
608 print ".IP \"" . $parameter . "\" 12\n !! 1363 print ".IP \"" . $parameter . "\" 12\n";
609 output_highlight($args{'parameterdescs !! 1364 output_highlight($args{'parameterdescs'}{$parameter_name});
610 } 1365 }
611 foreach $section (@{$args{'sectionlist'}}) 1366 foreach $section (@{$args{'sectionlist'}}) {
612 print ".SH \"", uc $section, "\"\n"; !! 1367 print ".SH \"", uc $section, "\"\n";
613 output_highlight($args{'sections'}{$se !! 1368 output_highlight($args{'sections'}{$section});
614 } 1369 }
615 } 1370 }
616 1371
617 ## 1372 ##
618 # output enum in man 1373 # output enum in man
619 sub output_enum_man(%) { 1374 sub output_enum_man(%) {
620 my %args = %{$_[0]}; 1375 my %args = %{$_[0]};
621 my ($parameter, $section); 1376 my ($parameter, $section);
622 my $count; 1377 my $count;
623 1378
624 print ".TH \"$args{'module'}\" 9 \"enum $a 1379 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
625 1380
626 print ".SH NAME\n"; 1381 print ".SH NAME\n";
627 print "enum " . $args{'enum'} . " \\- " . 1382 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
628 1383
629 print ".SH SYNOPSIS\n"; 1384 print ".SH SYNOPSIS\n";
630 print "enum " . $args{'enum'} . " {\n"; 1385 print "enum " . $args{'enum'} . " {\n";
631 $count = 0; 1386 $count = 0;
632 foreach my $parameter (@{$args{'parameterl 1387 foreach my $parameter (@{$args{'parameterlist'}}) {
633 print ".br\n.BI \" $parameter\"\n"; !! 1388 print ".br\n.BI \" $parameter\"\n";
634 if ($count == $#{$args{'parameterlist' !! 1389 if ($count == $#{$args{'parameterlist'}}) {
635 print "\n};\n"; !! 1390 print "\n};\n";
636 last; !! 1391 last;
637 } else { !! 1392 }
638 print ", \n.br\n"; !! 1393 else {
639 } !! 1394 print ", \n.br\n";
640 $count++; !! 1395 }
>> 1396 $count++;
641 } 1397 }
642 1398
643 print ".SH Constants\n"; 1399 print ".SH Constants\n";
644 foreach $parameter (@{$args{'parameterlist 1400 foreach $parameter (@{$args{'parameterlist'}}) {
645 my $parameter_name = $parameter; !! 1401 my $parameter_name = $parameter;
646 $parameter_name =~ s/\[.*//; !! 1402 $parameter_name =~ s/\[.*//;
647 1403
648 print ".IP \"" . $parameter . "\" 12\n !! 1404 print ".IP \"" . $parameter . "\" 12\n";
649 output_highlight($args{'parameterdescs !! 1405 output_highlight($args{'parameterdescs'}{$parameter_name});
650 } 1406 }
651 foreach $section (@{$args{'sectionlist'}}) 1407 foreach $section (@{$args{'sectionlist'}}) {
652 print ".SH \"$section\"\n"; !! 1408 print ".SH \"$section\"\n";
653 output_highlight($args{'sections'}{$se !! 1409 output_highlight($args{'sections'}{$section});
654 } 1410 }
655 } 1411 }
656 1412
657 ## 1413 ##
658 # output struct in man 1414 # output struct in man
659 sub output_struct_man(%) { 1415 sub output_struct_man(%) {
660 my %args = %{$_[0]}; 1416 my %args = %{$_[0]};
661 my ($parameter, $section); 1417 my ($parameter, $section);
662 1418
663 print ".TH \"$args{'module'}\" 9 \"" . $ar 1419 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
664 1420
665 print ".SH NAME\n"; 1421 print ".SH NAME\n";
666 print $args{'type'} . " " . $args{'struct' 1422 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
667 1423
668 my $declaration = $args{'definition'}; <<
669 $declaration =~ s/\t/ /g; <<
670 $declaration =~ s/\n/"\n.br\n.BI \"/g; <<
671 print ".SH SYNOPSIS\n"; 1424 print ".SH SYNOPSIS\n";
672 print $args{'type'} . " " . $args{'struct' 1425 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
673 print ".BI \"$declaration\n};\n.br\n\n"; !! 1426
>> 1427 foreach my $parameter (@{$args{'parameterlist'}}) {
>> 1428 if ($parameter =~ /^#/) {
>> 1429 print ".BI \"$parameter\"\n.br\n";
>> 1430 next;
>> 1431 }
>> 1432 my $parameter_name = $parameter;
>> 1433 $parameter_name =~ s/\[.*//;
>> 1434
>> 1435 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 1436 $type = $args{'parametertypes'}{$parameter};
>> 1437 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 1438 # pointer-to-function
>> 1439 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
>> 1440 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 1441 # bitfield
>> 1442 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
>> 1443 } else {
>> 1444 $type =~ s/([^\*])$/$1 /;
>> 1445 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
>> 1446 }
>> 1447 print "\n.br\n";
>> 1448 }
>> 1449 print "};\n.br\n";
674 1450
675 print ".SH Members\n"; 1451 print ".SH Members\n";
676 foreach $parameter (@{$args{'parameterlist 1452 foreach $parameter (@{$args{'parameterlist'}}) {
677 ($parameter =~ /^#/) && next; !! 1453 ($parameter =~ /^#/) && next;
678 1454
679 my $parameter_name = $parameter; !! 1455 my $parameter_name = $parameter;
680 $parameter_name =~ s/\[.*//; !! 1456 $parameter_name =~ s/\[.*//;
681 1457
682 ($args{'parameterdescs'}{$parameter_na !! 1458 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
683 print ".IP \"" . $parameter . "\" 12\n !! 1459 print ".IP \"" . $parameter . "\" 12\n";
684 output_highlight($args{'parameterdescs !! 1460 output_highlight($args{'parameterdescs'}{$parameter_name});
685 } 1461 }
686 foreach $section (@{$args{'sectionlist'}}) 1462 foreach $section (@{$args{'sectionlist'}}) {
687 print ".SH \"$section\"\n"; !! 1463 print ".SH \"$section\"\n";
688 output_highlight($args{'sections'}{$se !! 1464 output_highlight($args{'sections'}{$section});
689 } 1465 }
690 } 1466 }
691 1467
692 ## 1468 ##
693 # output typedef in man 1469 # output typedef in man
694 sub output_typedef_man(%) { 1470 sub output_typedef_man(%) {
695 my %args = %{$_[0]}; 1471 my %args = %{$_[0]};
696 my ($parameter, $section); 1472 my ($parameter, $section);
697 1473
698 print ".TH \"$args{'module'}\" 9 \"$args{' 1474 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
699 1475
700 print ".SH NAME\n"; 1476 print ".SH NAME\n";
701 print "typedef " . $args{'typedef'} . " \\ 1477 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
702 1478
703 foreach $section (@{$args{'sectionlist'}}) 1479 foreach $section (@{$args{'sectionlist'}}) {
704 print ".SH \"$section\"\n"; !! 1480 print ".SH \"$section\"\n";
705 output_highlight($args{'sections'}{$se !! 1481 output_highlight($args{'sections'}{$section});
706 } 1482 }
707 } 1483 }
708 1484
709 sub output_blockhead_man(%) { 1485 sub output_blockhead_man(%) {
710 my %args = %{$_[0]}; 1486 my %args = %{$_[0]};
711 my ($parameter, $section); 1487 my ($parameter, $section);
712 my $count; 1488 my $count;
713 1489
714 print ".TH \"$args{'module'}\" 9 \"$args{' 1490 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
715 1491
716 foreach $section (@{$args{'sectionlist'}}) 1492 foreach $section (@{$args{'sectionlist'}}) {
717 print ".SH \"$section\"\n"; !! 1493 print ".SH \"$section\"\n";
718 output_highlight($args{'sections'}{$se !! 1494 output_highlight($args{'sections'}{$section});
719 } 1495 }
720 } 1496 }
721 1497
722 ## 1498 ##
723 # output in restructured text !! 1499 # output in text
724 # !! 1500 sub output_function_text(%) {
725 <<
726 # <<
727 # This could use some work; it's used to outpu <<
728 # starts by putting out the name of the doc se <<
729 # to duplicate a header already in the templat <<
730 # <<
731 sub output_blockhead_rst(%) { <<
732 my %args = %{$_[0]}; 1501 my %args = %{$_[0]};
733 my ($parameter, $section); 1502 my ($parameter, $section);
>> 1503 my $start;
734 1504
735 foreach $section (@{$args{'sectionlist'}}) !! 1505 print "Name:\n\n";
736 next if (defined($nosymbol_table{$sect !! 1506 print $args{'function'} . " - " . $args{'purpose'} . "\n";
737 <<
738 if ($output_selection != OUTPUT_INCLUD <<
739 print ".. _$section:\n\n"; <<
740 print "**$section**\n\n"; <<
741 } <<
742 print_lineno($section_start_lines{$sec <<
743 output_highlight_rst($args{'sections'} <<
744 print "\n"; <<
745 } <<
746 } <<
747 <<
748 # <<
749 # Apply the RST highlights to a sub-block of t <<
750 # <<
751 sub highlight_block($) { <<
752 # The dohighlight kludge requires the text <<
753 my $contents = shift; <<
754 eval $dohighlight; <<
755 die $@ if $@; <<
756 return $contents; <<
757 } <<
758 <<
759 # <<
760 # Regexes used only here. <<
761 # <<
762 my $sphinx_literal = '^[^.].*::$'; <<
763 my $sphinx_cblock = '^\.\.\ +code-block::'; <<
764 <<
765 sub output_highlight_rst { <<
766 my $input = join "\n",@_; <<
767 my $output = ""; <<
768 my $line; <<
769 my $in_literal = 0; <<
770 my $litprefix; <<
771 my $block = ""; <<
772 <<
773 foreach $line (split "\n",$input) { <<
774 # <<
775 # If we're in a literal block, see if <<
776 # of it. Otherwise pass the line stra <<
777 # <<
778 if ($in_literal) { <<
779 if (! ($line =~ /^\s*$/)) { <<
780 # <<
781 # If this is the first non-bla <<
782 # block we need to figure out <<
783 # <<
784 if ($litprefix eq "") { <<
785 $line =~ /^(\s*)/; <<
786 $litprefix = '^' . $1; <<
787 $output .= $line . "\n"; <<
788 } elsif (! ($line =~ /$litpref <<
789 $in_literal = 0; <<
790 } else { <<
791 $output .= $line . "\n"; <<
792 } <<
793 } else { <<
794 $output .= $line . "\n"; <<
795 } <<
796 } <<
797 # <<
798 # Not in a literal block (or just drop <<
799 # <<
800 if (! $in_literal) { <<
801 $block .= $line . "\n"; <<
802 if (($line =~ /$sphinx_literal/) | <<
803 $in_literal = 1; <<
804 $litprefix = ""; <<
805 $output .= highlight_block($bl <<
806 $block = "" <<
807 } <<
808 } <<
809 } <<
810 <<
811 if ($block) { <<
812 $output .= highlight_block($block); <<
813 } <<
814 foreach $line (split "\n", $output) { <<
815 print $lineprefix . $line . "\n"; <<
816 } <<
817 } <<
818 <<
819 sub output_function_rst(%) { <<
820 my %args = %{$_[0]}; <<
821 my ($parameter, $section); <<
822 my $oldprefix = $lineprefix; <<
823 1507
824 my $signature = ""; !! 1508 print "\nSynopsis:\n\n";
825 if ($args{'functiontype'} ne "") { 1509 if ($args{'functiontype'} ne "") {
826 $signature = $args{'functiontype'} . " !! 1510 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
827 } else { 1511 } else {
828 $signature = $args{'function'} . " ("; !! 1512 $start = $args{'function'} . " (";
829 } 1513 }
>> 1514 print $start;
830 1515
831 my $count = 0; 1516 my $count = 0;
832 foreach my $parameter (@{$args{'parameterl 1517 foreach my $parameter (@{$args{'parameterlist'}}) {
833 if ($count ne 0) { !! 1518 $type = $args{'parametertypes'}{$parameter};
834 $signature .= ", "; !! 1519 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
835 } !! 1520 # pointer-to-function
836 $count++; !! 1521 print $1 . $parameter . ") (" . $2;
837 $type = $args{'parametertypes'}{$param !! 1522 } else {
838 !! 1523 print $type . " " . $parameter;
839 if ($type =~ m/$function_pointer/) { !! 1524 }
840 # pointer-to-function !! 1525 if ($count != $#{$args{'parameterlist'}}) {
841 $signature .= $1 . $parameter . ") !! 1526 $count++;
842 } else { !! 1527 print ",\n";
843 $signature .= $type; !! 1528 print " " x length($start);
844 } !! 1529 } else {
845 } !! 1530 print ");\n\n";
846 !! 1531 }
847 $signature .= ")"; <<
848 <<
849 if ($sphinx_major < 3) { <<
850 if ($args{'typedef'}) { <<
851 print ".. c:type:: ". $args{'funct <<
852 print_lineno($declaration_start_li <<
853 print " **Typedef**: "; <<
854 $lineprefix = ""; <<
855 output_highlight_rst($args{'purpos <<
856 print "\n\n**Syntax**\n\n"; <<
857 print " ``$signature``\n\n"; <<
858 } else { <<
859 print ".. c:function:: $signature\ <<
860 } <<
861 } else { <<
862 if ($args{'typedef'} || $args{'functio <<
863 print ".. c:macro:: ". $args{'func <<
864 <<
865 if ($args{'typedef'}) { <<
866 print_lineno($declaration_star <<
867 print " **Typedef**: "; <<
868 $lineprefix = ""; <<
869 output_highlight_rst($args{'pu <<
870 print "\n\n**Syntax**\n\n"; <<
871 print " ``$signature``\n\n"; <<
872 } else { <<
873 print "``$signature``\n\n"; <<
874 } <<
875 } else { <<
876 print ".. c:function:: $signature\ <<
877 } <<
878 } 1532 }
879 1533
880 if (!$args{'typedef'}) { !! 1534 print "Arguments:\n\n";
881 print_lineno($declaration_start_line); !! 1535 foreach $parameter (@{$args{'parameterlist'}}) {
882 $lineprefix = " "; !! 1536 my $parameter_name = $parameter;
883 output_highlight_rst($args{'purpose'}) !! 1537 $parameter_name =~ s/\[.*//;
884 print "\n"; <<
885 } <<
886 <<
887 # <<
888 # Put our descriptive text into a containe <<
889 # set the function prototypes apart. <<
890 # <<
891 print ".. container:: kernelindent\n\n"; <<
892 $lineprefix = " "; <<
893 print $lineprefix . "**Parameters**\n\n"; <<
894 foreach $parameter (@{$args{'parameterlist <<
895 my $parameter_name = $parameter; <<
896 $parameter_name =~ s/\[.*//; <<
897 $type = $args{'parametertypes'}{$param <<
898 <<
899 if ($type ne "") { <<
900 print $lineprefix . "``$type``\n"; <<
901 } else { <<
902 print $lineprefix . "``$parameter` <<
903 } <<
904 <<
905 print_lineno($parameterdesc_start_line <<
906 1538
907 $lineprefix = " "; !! 1539 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
908 if (defined($args{'parameterdescs'}{$p <<
909 $args{'parameterdescs'}{$parameter <<
910 output_highlight_rst($args{'parame <<
911 } else { <<
912 print $lineprefix . "*undescribed* <<
913 } <<
914 $lineprefix = " "; <<
915 print "\n"; <<
916 } 1540 }
917 !! 1541 output_section_text(@_);
918 output_section_rst(@_); <<
919 $lineprefix = $oldprefix; <<
920 } 1542 }
921 1543
922 sub output_section_rst(%) { !! 1544 #output sections in text
>> 1545 sub output_section_text(%) {
923 my %args = %{$_[0]}; 1546 my %args = %{$_[0]};
924 my $section; 1547 my $section;
925 my $oldprefix = $lineprefix; <<
926 1548
>> 1549 print "\n";
927 foreach $section (@{$args{'sectionlist'}}) 1550 foreach $section (@{$args{'sectionlist'}}) {
928 print $lineprefix . "**$section**\n\n" !! 1551 print "$section:\n\n";
929 print_lineno($section_start_lines{$sec !! 1552 output_highlight($args{'sections'}{$section});
930 output_highlight_rst($args{'sections'} <<
931 print "\n"; <<
932 } 1553 }
933 print "\n"; !! 1554 print "\n\n";
934 } 1555 }
935 1556
936 sub output_enum_rst(%) { !! 1557 # output enum in text
>> 1558 sub output_enum_text(%) {
937 my %args = %{$_[0]}; 1559 my %args = %{$_[0]};
938 my ($parameter); 1560 my ($parameter);
939 my $oldprefix = $lineprefix; <<
940 my $count; 1561 my $count;
941 my $outer; !! 1562 print "Enum:\n\n";
942 1563
943 if ($sphinx_major < 3) { !! 1564 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
944 my $name = "enum " . $args{'enum'}; !! 1565 print "enum " . $args{'enum'} . " {\n";
945 print "\n\n.. c:type:: " . $name . "\n !! 1566 $count = 0;
946 } else { !! 1567 foreach $parameter (@{$args{'parameterlist'}}) {
947 my $name = $args{'enum'}; !! 1568 print "\t$parameter";
948 print "\n\n.. c:enum:: " . $name . "\n !! 1569 if ($count != $#{$args{'parameterlist'}}) {
>> 1570 $count++;
>> 1571 print ",";
>> 1572 }
>> 1573 print "\n";
949 } 1574 }
950 print_lineno($declaration_start_line); !! 1575 print "};\n\n";
951 $lineprefix = " "; <<
952 output_highlight_rst($args{'purpose'}); <<
953 print "\n"; <<
954 1576
955 print ".. container:: kernelindent\n\n"; !! 1577 print "Constants:\n\n";
956 $outer = $lineprefix . " "; !! 1578 foreach $parameter (@{$args{'parameterlist'}}) {
957 $lineprefix = $outer . " "; !! 1579 print "$parameter\n\t";
958 print $outer . "**Constants**\n\n"; !! 1580 print $args{'parameterdescs'}{$parameter} . "\n";
959 foreach $parameter (@{$args{'parameterlist <<
960 print $outer . "``$parameter``\n"; <<
961 <<
962 if ($args{'parameterdescs'}{$parameter <<
963 output_highlight_rst($args{'parame <<
964 } else { <<
965 print $lineprefix . "*undescribed* <<
966 } <<
967 print "\n"; <<
968 } 1581 }
969 print "\n"; !! 1582
970 $lineprefix = $oldprefix; !! 1583 output_section_text(@_);
971 output_section_rst(@_); <<
972 } 1584 }
973 1585
974 sub output_typedef_rst(%) { !! 1586 # output typedef in text
>> 1587 sub output_typedef_text(%) {
975 my %args = %{$_[0]}; 1588 my %args = %{$_[0]};
976 my ($parameter); 1589 my ($parameter);
977 my $oldprefix = $lineprefix; !! 1590 my $count;
978 my $name; !! 1591 print "Typedef:\n\n";
979 <<
980 if ($sphinx_major < 3) { <<
981 $name = "typedef " . $args{'typedef'}; <<
982 } else { <<
983 $name = $args{'typedef'}; <<
984 } <<
985 print "\n\n.. c:type:: " . $name . "\n\n"; <<
986 print_lineno($declaration_start_line); <<
987 $lineprefix = " "; <<
988 output_highlight_rst($args{'purpose'}); <<
989 print "\n"; <<
990 1592
991 $lineprefix = $oldprefix; !! 1593 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
992 output_section_rst(@_); !! 1594 output_section_text(@_);
993 } 1595 }
994 1596
995 sub output_struct_rst(%) { !! 1597 # output struct as text
>> 1598 sub output_struct_text(%) {
996 my %args = %{$_[0]}; 1599 my %args = %{$_[0]};
997 my ($parameter); 1600 my ($parameter);
998 my $oldprefix = $lineprefix; <<
999 1601
1000 if ($sphinx_major < 3) { !! 1602 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1001 my $name = $args{'type'} . " " . $arg !! 1603 print $args{'type'} . " " . $args{'struct'} . " {\n";
1002 print "\n\n.. c:type:: " . $name . "\ !! 1604 foreach $parameter (@{$args{'parameterlist'}}) {
1003 } else { !! 1605 if ($parameter =~ /^#/) {
1004 my $name = $args{'struct'}; !! 1606 print "$parameter\n";
1005 if ($args{'type'} eq 'union') { !! 1607 next;
1006 print "\n\n.. c:union:: " . $name !! 1608 }
1007 } else { !! 1609
1008 print "\n\n.. c:struct:: " . $nam !! 1610 my $parameter_name = $parameter;
1009 } !! 1611 $parameter_name =~ s/\[.*//;
>> 1612
>> 1613 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
>> 1614 $type = $args{'parametertypes'}{$parameter};
>> 1615 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
>> 1616 # pointer-to-function
>> 1617 print "\t$1 $parameter) ($2);\n";
>> 1618 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
>> 1619 # bitfield
>> 1620 print "\t$1 $parameter$2;\n";
>> 1621 } else {
>> 1622 print "\t" . $type . " " . $parameter . ";\n";
>> 1623 }
1010 } 1624 }
1011 print_lineno($declaration_start_line); !! 1625 print "};\n\n";
1012 $lineprefix = " "; !! 1626
1013 output_highlight_rst($args{'purpose'}); !! 1627 print "Members:\n\n";
1014 print "\n"; !! 1628 foreach $parameter (@{$args{'parameterlist'}}) {
>> 1629 ($parameter =~ /^#/) && next;
>> 1630
>> 1631 my $parameter_name = $parameter;
>> 1632 $parameter_name =~ s/\[.*//;
1015 1633
1016 print ".. container:: kernelindent\n\n"; !! 1634 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1017 print $lineprefix . "**Definition**::\n\n !! 1635 print "$parameter\n\t";
1018 my $declaration = $args{'definition'}; !! 1636 print $args{'parameterdescs'}{$parameter_name} . "\n";
1019 $lineprefix = $lineprefix . " "; <<
1020 $declaration =~ s/\t/$lineprefix/g; <<
1021 print $lineprefix . $args{'type'} . " " . <<
1022 <<
1023 $lineprefix = " "; <<
1024 print $lineprefix . "**Members**\n\n"; <<
1025 foreach $parameter (@{$args{'parameterlis <<
1026 ($parameter =~ /^#/) && next; <<
1027 <<
1028 my $parameter_name = $parameter; <<
1029 $parameter_name =~ s/\[.*//; <<
1030 <<
1031 ($args{'parameterdescs'}{$parameter_n <<
1032 $type = $args{'parametertypes'}{$para <<
1033 print_lineno($parameterdesc_start_lin <<
1034 print $lineprefix . "``" . $parameter <<
1035 $lineprefix = " "; <<
1036 output_highlight_rst($args{'parameter <<
1037 $lineprefix = " "; <<
1038 print "\n"; <<
1039 } 1637 }
1040 print "\n"; 1638 print "\n";
>> 1639 output_section_text(@_);
>> 1640 }
>> 1641
>> 1642 sub output_blockhead_text(%) {
>> 1643 my %args = %{$_[0]};
>> 1644 my ($parameter, $section);
1041 1645
1042 $lineprefix = $oldprefix; !! 1646 foreach $section (@{$args{'sectionlist'}}) {
1043 output_section_rst(@_); !! 1647 print " $section:\n";
>> 1648 print " -> ";
>> 1649 output_highlight($args{'sections'}{$section});
>> 1650 }
1044 } 1651 }
1045 1652
1046 ## none mode output functions !! 1653 ## list mode output functions
>> 1654
>> 1655 sub output_function_list(%) {
>> 1656 my %args = %{$_[0]};
1047 1657
1048 sub output_function_none(%) { !! 1658 print $args{'function'} . "\n";
1049 } 1659 }
1050 1660
1051 sub output_enum_none(%) { !! 1661 # output enum in list
>> 1662 sub output_enum_list(%) {
>> 1663 my %args = %{$_[0]};
>> 1664 print $args{'enum'} . "\n";
1052 } 1665 }
1053 1666
1054 sub output_typedef_none(%) { !! 1667 # output typedef in list
>> 1668 sub output_typedef_list(%) {
>> 1669 my %args = %{$_[0]};
>> 1670 print $args{'typedef'} . "\n";
1055 } 1671 }
1056 1672
1057 sub output_struct_none(%) { !! 1673 # output struct as list
>> 1674 sub output_struct_list(%) {
>> 1675 my %args = %{$_[0]};
>> 1676
>> 1677 print $args{'struct'} . "\n";
1058 } 1678 }
1059 1679
1060 sub output_blockhead_none(%) { !! 1680 sub output_blockhead_list(%) {
>> 1681 my %args = %{$_[0]};
>> 1682 my ($parameter, $section);
>> 1683
>> 1684 foreach $section (@{$args{'sectionlist'}}) {
>> 1685 print "DOC: $section\n";
>> 1686 }
1061 } 1687 }
1062 1688
1063 ## 1689 ##
1064 # generic output function for all types (func 1690 # generic output function for all types (function, struct/union, typedef, enum);
1065 # calls the generated, variable output_ funct 1691 # calls the generated, variable output_ function name based on
1066 # functype and output_mode 1692 # functype and output_mode
1067 sub output_declaration { 1693 sub output_declaration {
1068 no strict 'refs'; 1694 no strict 'refs';
1069 my $name = shift; 1695 my $name = shift;
1070 my $functype = shift; 1696 my $functype = shift;
1071 my $func = "output_${functype}_$output_mo 1697 my $func = "output_${functype}_$output_mode";
1072 !! 1698 if (($function_only==0) ||
1073 return if (defined($nosymbol_table{$name} !! 1699 ( $function_only == 1 && defined($function_table{$name})) ||
1074 !! 1700 ( $function_only == 2 && !defined($function_table{$name})))
1075 if (($output_selection == OUTPUT_ALL) || <<
1076 (($output_selection == OUTPUT_INCLUDE <<
1077 $output_selection == OUTPUT_EXPORTE <<
1078 defined($function_table{$name})) || <<
1079 ($output_selection == OUTPUT_INTERNAL <<
1080 !($functype eq "function" && defined <<
1081 { 1701 {
1082 &$func(@_); !! 1702 &$func(@_);
1083 $section_counter++; !! 1703 $section_counter++;
1084 } 1704 }
1085 } 1705 }
1086 1706
1087 ## 1707 ##
1088 # generic output function - calls the right o 1708 # generic output function - calls the right one based on current output mode.
1089 sub output_blockhead { 1709 sub output_blockhead {
1090 no strict 'refs'; 1710 no strict 'refs';
1091 my $func = "output_blockhead_" . $output_ 1711 my $func = "output_blockhead_" . $output_mode;
1092 &$func(@_); 1712 &$func(@_);
1093 $section_counter++; 1713 $section_counter++;
1094 } 1714 }
1095 1715
1096 ## 1716 ##
1097 # takes a declaration (struct, union, enum, t 1717 # takes a declaration (struct, union, enum, typedef) and
1098 # invokes the right handler. NOT called for f 1718 # invokes the right handler. NOT called for functions.
1099 sub dump_declaration($$) { 1719 sub dump_declaration($$) {
1100 no strict 'refs'; 1720 no strict 'refs';
1101 my ($prototype, $file) = @_; 1721 my ($prototype, $file) = @_;
1102 my $func = "dump_" . $decl_type; 1722 my $func = "dump_" . $decl_type;
1103 &$func(@_); 1723 &$func(@_);
1104 } 1724 }
1105 1725
1106 sub dump_union($$) { 1726 sub dump_union($$) {
1107 dump_struct(@_); 1727 dump_struct(@_);
1108 } 1728 }
1109 1729
1110 sub dump_struct($$) { 1730 sub dump_struct($$) {
1111 my $x = shift; 1731 my $x = shift;
1112 my $file = shift; 1732 my $file = shift;
1113 my $decl_type; !! 1733 my $nested;
1114 my $members; <<
1115 my $type = qr{struct|union}; <<
1116 # For capturing struct/union definition b <<
1117 my $qualifiers = qr{$attribute|__packed|_ <<
1118 my $definition_body = qr{\{(.*)\}\s*$qual <<
1119 my $struct_members = qr{($type)([^\{\};]+ <<
1120 <<
1121 if ($x =~ /($type)\s+(\w+)\s*$definition_ <<
1122 $decl_type = $1; <<
1123 $declaration_name = $2; <<
1124 $members = $3; <<
1125 } elsif ($x =~ /typedef\s+($type)\s*$defi <<
1126 $decl_type = $1; <<
1127 $declaration_name = $3; <<
1128 $members = $2; <<
1129 } <<
1130 <<
1131 if ($members) { <<
1132 if ($identifier ne $declaration_name) <<
1133 emit_warning("${file}:$.", "expec <<
1134 return; <<
1135 } <<
1136 <<
1137 # ignore members marked private: <<
1138 $members =~ s/\/\*\s*private:.*?\/\*\ <<
1139 $members =~ s/\/\*\s*private:.*//gosi <<
1140 # strip comments: <<
1141 $members =~ s/\/\*.*?\*\///gos; <<
1142 # strip attributes <<
1143 $members =~ s/\s*$attribute/ /gi; <<
1144 $members =~ s/\s*__aligned\s*\([^;]*\ <<
1145 $members =~ s/\s*__counted_by\s*\([^; <<
1146 $members =~ s/\s*__counted_by_(le|be) <<
1147 $members =~ s/\s*__packed\s*/ /gos; <<
1148 $members =~ s/\s*CRYPTO_MINALIGN_ATTR <<
1149 $members =~ s/\s*____cacheline_aligne <<
1150 $members =~ s/\s*____cacheline_aligne <<
1151 # unwrap struct_group(): <<
1152 # - first eat non-declaration paramet <<
1153 # - then remove macro, outer parens, <<
1154 $members =~ s/\bstruct_group\s*\(([^, <<
1155 $members =~ s/\bstruct_group_attr\s*\ <<
1156 $members =~ s/\bstruct_group_tagged\s <<
1157 $members =~ s/\b__struct_group\s*\(([ <<
1158 $members =~ s/\bSTRUCT_GROUP(\(((?:(? <<
1159 <<
1160 my $args = qr{([^,)]+)}; <<
1161 # replace DECLARE_BITMAP <<
1162 $members =~ s/__ETHTOOL_DECLARE_LINK_ <<
1163 $members =~ s/DECLARE_PHY_INTERFACE_M <<
1164 $members =~ s/DECLARE_BITMAP\s*\($arg <<
1165 # replace DECLARE_HASHTABLE <<
1166 $members =~ s/DECLARE_HASHTABLE\s*\($ <<
1167 # replace DECLARE_KFIFO <<
1168 $members =~ s/DECLARE_KFIFO\s*\($args <<
1169 # replace DECLARE_KFIFO_PTR <<
1170 $members =~ s/DECLARE_KFIFO_PTR\s*\($ <<
1171 # replace DECLARE_FLEX_ARRAY <<
1172 $members =~ s/(?:__)?DECLARE_FLEX_ARR <<
1173 #replace DEFINE_DMA_UNMAP_ADDR <<
1174 $members =~ s/DEFINE_DMA_UNMAP_ADDR\s <<
1175 #replace DEFINE_DMA_UNMAP_LEN <<
1176 $members =~ s/DEFINE_DMA_UNMAP_LEN\s* <<
1177 my $declaration = $members; <<
1178 <<
1179 # Split nested struct/union elements <<
1180 while ($members =~ m/$struct_members/ <<
1181 my $newmember; <<
1182 my $maintype = $1; <<
1183 my $ids = $4; <<
1184 my $content = $3; <<
1185 foreach my $id(split /,/, $ids) { <<
1186 $newmember .= "$maintype $id; <<
1187 <<
1188 $id =~ s/[:\[].*//; <<
1189 $id =~ s/^\s*\**(\S+)\s*/$1/; <<
1190 foreach my $arg (split /;/, $ <<
1191 next if ($arg =~ m/^\s*$/ <<
1192 if ($arg =~ m/^([^\(]+\(\ <<
1193 # pointer-to-function <<
1194 my $type = $1; <<
1195 my $name = $2; <<
1196 my $extra = $3; <<
1197 next if (!$name); <<
1198 if ($id =~ m/^\s*$/) <<
1199 # anonymous struc <<
1200 $newmember .= "$t <<
1201 } else { <<
1202 $newmember .= "$t <<
1203 } <<
1204 } else { <<
1205 my $type; <<
1206 my $names; <<
1207 $arg =~ s/^\s+//; <<
1208 $arg =~ s/\s+$//; <<
1209 # Handle bitmaps <<
1210 $arg =~ s/:\s*\d+\s*/ <<
1211 # Handle arrays <<
1212 $arg =~ s/\[.*\]//g; <<
1213 # The type may have m <<
1214 # and multiple IDs ca <<
1215 # const struct foo <<
1216 # So, we remove space <<
1217 # names, in order to <<
1218 # and commas for the <<
1219 $arg =~ s/\s*,\s*/,/g <<
1220 if ($arg =~ m/(.*)\s+ <<
1221 $type = $1; <<
1222 $names = $2; <<
1223 } else { <<
1224 $newmember .= "$a <<
1225 next; <<
1226 } <<
1227 foreach my $name (spl <<
1228 $name =~ s/^\s*\* <<
1229 next if (($name = <<
1230 if ($id =~ m/^\s* <<
1231 # anonymous s <<
1232 $newmember .= <<
1233 } else { <<
1234 $newmember .= <<
1235 } <<
1236 } <<
1237 } <<
1238 } <<
1239 } <<
1240 $members =~ s/$struct_members/$ne <<
1241 } <<
1242 <<
1243 # Ignore other nested elements, like <<
1244 $members =~ s/(\{[^\{\}]*\})//g; <<
1245 1734
1246 create_parameterlist($members, ';', $ !! 1735 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
1247 check_sections($file, $declaration_na !! 1736 #my $decl_type = $1;
1248 !! 1737 $declaration_name = $2;
1249 # Adjust declaration for better displ !! 1738 my $members = $3;
1250 $declaration =~ s/([\{;])/$1\n/g; !! 1739
1251 $declaration =~ s/\}\s+;/};/g; !! 1740 # ignore embedded structs or unions
1252 # Better handle inlined enums !! 1741 $members =~ s/({.*})//g;
1253 do {} while ($declaration =~ s/(enum\ !! 1742 $nested = $1;
1254 !! 1743
1255 my @def_args = split /\n/, $declarati !! 1744 # ignore members marked private:
1256 my $level = 1; !! 1745 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
1257 $declaration = ""; !! 1746 $members =~ s/\/\*\s*private:.*//gos;
1258 foreach my $clause (@def_args) { !! 1747 # strip comments:
1259 $clause =~ s/^\s+//; !! 1748 $members =~ s/\/\*.*?\*\///gos;
1260 $clause =~ s/\s+$//; !! 1749 $nested =~ s/\/\*.*?\*\///gos;
1261 $clause =~ s/\s+/ /; !! 1750 # strip kmemcheck_bitfield_{begin,end}.*;
1262 next if (!$clause); !! 1751 $members =~ s/kmemcheck_bitfield_.*?;//gos;
1263 $level-- if ($clause =~ m/(\})/ & !! 1752 # strip attributes
1264 if (!($clause =~ m/^\s*#/)) { !! 1753 $members =~ s/__aligned\s*\([^;]*\)//gos;
1265 $declaration .= "\t" x $level !! 1754
1266 } !! 1755 create_parameterlist($members, ';', $file);
1267 $declaration .= "\t" . $clause . !! 1756 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
1268 $level++ if ($clause =~ m/(\{)/ & !! 1757
1269 } !! 1758 output_declaration($declaration_name,
1270 output_declaration($declaration_name, !! 1759 'struct',
1271 'struct', !! 1760 {'struct' => $declaration_name,
1272 {'struct' => $declaration_ !! 1761 'module' => $modulename,
1273 'module' => $modulename, !! 1762 'parameterlist' => \@parameterlist,
1274 'definition' => $declarat !! 1763 'parameterdescs' => \%parameterdescs,
1275 'parameterlist' => \@para !! 1764 'parametertypes' => \%parametertypes,
1276 'parameterdescs' => \%par !! 1765 'sectionlist' => \@sectionlist,
1277 'parametertypes' => \%par !! 1766 'sections' => \%sections,
1278 'sectionlist' => \@sectio !! 1767 'purpose' => $declaration_purpose,
1279 'sections' => \%sections, !! 1768 'type' => $decl_type
1280 'purpose' => $declaration !! 1769 });
1281 'type' => $decl_type !! 1770 }
1282 }); !! 1771 else {
1283 } else { !! 1772 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1284 print STDERR "${file}:$.: error: Cann !! 1773 ++$errors;
1285 ++$errors; <<
1286 } 1774 }
1287 } 1775 }
1288 1776
1289 <<
1290 sub show_warnings($$) { <<
1291 my $functype = shift; <<
1292 my $name = shift; <<
1293 <<
1294 return 0 if (defined($nosymbol_table{$nam <<
1295 <<
1296 return 1 if ($output_selection == OUTPUT_ <<
1297 <<
1298 if ($output_selection == OUTPUT_EXPORTED) <<
1299 if (defined($function_table{$name})) <<
1300 return 1; <<
1301 } else { <<
1302 return 0; <<
1303 } <<
1304 } <<
1305 if ($output_selection == OUTPUT_INTERNAL) <<
1306 if (!($functype eq "function" && defi <<
1307 return 1; <<
1308 } else { <<
1309 return 0; <<
1310 } <<
1311 } <<
1312 if ($output_selection == OUTPUT_INCLUDE) <<
1313 if (defined($function_table{$name})) <<
1314 return 1; <<
1315 } else { <<
1316 return 0; <<
1317 } <<
1318 } <<
1319 die("Please add the new output type at sh <<
1320 } <<
1321 <<
1322 sub dump_enum($$) { 1777 sub dump_enum($$) {
1323 my $x = shift; 1778 my $x = shift;
1324 my $file = shift; 1779 my $file = shift;
1325 my $members; <<
1326 <<
1327 # ignore members marked private: <<
1328 $x =~ s/\/\*\s*private:.*?\/\*\s*public:. <<
1329 $x =~ s/\/\*\s*private:.*}/}/gosi; <<
1330 1780
1331 $x =~ s@/\*.*?\*/@@gos; # strip comme 1781 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1332 # strip #define macros inside enums !! 1782 $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums
1333 $x =~ s@#\s*((define|ifdef|if)\s+|endif)[ <<
1334 <<
1335 if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\ <<
1336 $declaration_name = $2; <<
1337 $members = $1; <<
1338 } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) <<
1339 $declaration_name = $1; <<
1340 $members = $2; <<
1341 } <<
1342 <<
1343 if ($members) { <<
1344 if ($identifier ne $declaration_name) <<
1345 if ($identifier eq "") { <<
1346 emit_warning("${file}:$.", "w <<
1347 } else { <<
1348 emit_warning("${file}:$.", "e <<
1349 } <<
1350 return; <<
1351 } <<
1352 $declaration_name = "(anonymous)" if <<
1353 1783
1354 my %_members; !! 1784 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1355 !! 1785 $declaration_name = $1;
1356 $members =~ s/\s+$//; !! 1786 my $members = $2;
1357 $members =~ s/\([^;]*?[\)]//g; !! 1787
1358 !! 1788 foreach my $arg (split ',', $members) {
1359 foreach my $arg (split ',', $members) !! 1789 $arg =~ s/^\s*(\w+).*/$1/;
1360 $arg =~ s/^\s*(\w+).*/$1/; !! 1790 push @parameterlist, $arg;
1361 push @parameterlist, $arg; !! 1791 if (!$parameterdescs{$arg}) {
1362 if (!$parameterdescs{$arg}) { !! 1792 $parameterdescs{$arg} = $undescribed;
1363 $parameterdescs{$arg} = $unde !! 1793 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1364 if (show_warnings("enum", $de !! 1794 "not described in enum '$declaration_name'\n";
1365 emit_warning("${file}:$." !! 1795 }
1366 } !! 1796
1367 } !! 1797 }
1368 $_members{$arg} = 1; !! 1798
1369 } !! 1799 output_declaration($declaration_name,
1370 !! 1800 'enum',
1371 while (my ($k, $v) = each %parameterd !! 1801 {'enum' => $declaration_name,
1372 if (!exists($_members{$k})) { !! 1802 'module' => $modulename,
1373 if (show_warnings("enum", $de !! 1803 'parameterlist' => \@parameterlist,
1374 emit_warning("${file}:$." !! 1804 'parameterdescs' => \%parameterdescs,
1375 } !! 1805 'sectionlist' => \@sectionlist,
1376 } !! 1806 'sections' => \%sections,
1377 } !! 1807 'purpose' => $declaration_purpose
1378 !! 1808 });
1379 output_declaration($declaration_name, !! 1809 }
1380 'enum', !! 1810 else {
1381 {'enum' => $declar !! 1811 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1382 'module' => $modu !! 1812 ++$errors;
1383 'parameterlist' = <<
1384 'parameterdescs' <<
1385 'sectionlist' => <<
1386 'sections' => \%s <<
1387 'purpose' => $dec <<
1388 }); <<
1389 } else { <<
1390 print STDERR "${file}:$.: error: Cann <<
1391 ++$errors; <<
1392 } 1813 }
1393 } 1814 }
1394 1815
1395 my $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8 <<
1396 my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; <<
1397 my $typedef_args = qr { \s*\((.*)\); }x; <<
1398 <<
1399 my $typedef1 = qr { typedef$typedef_type\($ty <<
1400 my $typedef2 = qr { typedef$typedef_type$type <<
1401 <<
1402 sub dump_typedef($$) { 1816 sub dump_typedef($$) {
1403 my $x = shift; 1817 my $x = shift;
1404 my $file = shift; 1818 my $file = shift;
1405 1819
1406 $x =~ s@/\*.*?\*/@@gos; # strip comme 1820 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1407 <<
1408 # Parse function typedef prototypes <<
1409 if ($x =~ $typedef1 || $x =~ $typedef2) { <<
1410 $return_type = $1; <<
1411 $declaration_name = $2; <<
1412 my $args = $3; <<
1413 $return_type =~ s/^\s+//; <<
1414 <<
1415 if ($identifier ne $declaration_name) <<
1416 emit_warning("${file}:$.", "expec <<
1417 return; <<
1418 } <<
1419 <<
1420 create_parameterlist($args, ',', $fil <<
1421 <<
1422 output_declaration($declaration_name, <<
1423 'function', <<
1424 {'function' => $de <<
1425 'typedef' => 1, <<
1426 'module' => $modu <<
1427 'functiontype' => <<
1428 'parameterlist' = <<
1429 'parameterdescs' <<
1430 'parametertypes' <<
1431 'sectionlist' => <<
1432 'sections' => \%s <<
1433 'purpose' => $dec <<
1434 }); <<
1435 return; <<
1436 } <<
1437 <<
1438 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\ 1821 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1439 $x =~ s/\(*.\)\s*;$/;/; !! 1822 $x =~ s/\(*.\)\s*;$/;/;
1440 $x =~ s/\[*.\]\s*;$/;/; !! 1823 $x =~ s/\[*.\]\s*;$/;/;
1441 } 1824 }
1442 1825
1443 if ($x =~ /typedef.*\s+(\w+)\s*;/) { 1826 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1444 $declaration_name = $1; !! 1827 $declaration_name = $1;
1445 <<
1446 if ($identifier ne $declaration_name) <<
1447 emit_warning("${file}:$.", "expec <<
1448 return; <<
1449 } <<
1450 1828
1451 output_declaration($declaration_name, !! 1829 output_declaration($declaration_name,
1452 'typedef', !! 1830 'typedef',
1453 {'typedef' => $dec !! 1831 {'typedef' => $declaration_name,
1454 'module' => $modu !! 1832 'module' => $modulename,
1455 'sectionlist' => !! 1833 'sectionlist' => \@sectionlist,
1456 'sections' => \%s !! 1834 'sections' => \%sections,
1457 'purpose' => $dec !! 1835 'purpose' => $declaration_purpose
1458 }); !! 1836 });
1459 } else { !! 1837 }
1460 print STDERR "${file}:$.: error: Cann !! 1838 else {
1461 ++$errors; !! 1839 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
>> 1840 ++$errors;
1462 } 1841 }
1463 } 1842 }
1464 1843
1465 sub save_struct_actual($) { 1844 sub save_struct_actual($) {
1466 my $actual = shift; 1845 my $actual = shift;
1467 1846
1468 # strip all spaces from the actual param 1847 # strip all spaces from the actual param so that it looks like one string item
1469 $actual =~ s/\s*//g; 1848 $actual =~ s/\s*//g;
1470 $struct_actual = $struct_actual . $actual 1849 $struct_actual = $struct_actual . $actual . " ";
1471 } 1850 }
1472 1851
1473 sub create_parameterlist($$$$) { !! 1852 sub create_parameterlist($$$) {
1474 my $args = shift; 1853 my $args = shift;
1475 my $splitter = shift; 1854 my $splitter = shift;
1476 my $file = shift; 1855 my $file = shift;
1477 my $declaration_name = shift; <<
1478 my $type; 1856 my $type;
1479 my $param; 1857 my $param;
1480 1858
1481 # temporarily replace commas inside funct 1859 # temporarily replace commas inside function pointer definition
1482 my $arg_expr = qr{\([^\),]+}; !! 1860 while ($args =~ /(\([^\),]+),/) {
1483 while ($args =~ /$arg_expr,/) { !! 1861 $args =~ s/(\([^\),]+),/$1#/g;
1484 $args =~ s/($arg_expr),/$1#/g; <<
1485 } 1862 }
1486 1863
1487 foreach my $arg (split($splitter, $args)) 1864 foreach my $arg (split($splitter, $args)) {
1488 # strip comments !! 1865 # strip comments
1489 $arg =~ s/\/\*.*\*\///; !! 1866 $arg =~ s/\/\*.*\*\///;
1490 # ignore argument attributes !! 1867 # strip leading/trailing spaces
1491 $arg =~ s/\sPOS0?\s/ /; !! 1868 $arg =~ s/^\s*//;
1492 # strip leading/trailing spaces !! 1869 $arg =~ s/\s*$//;
1493 $arg =~ s/^\s*//; !! 1870 $arg =~ s/\s+/ /;
1494 $arg =~ s/\s*$//; !! 1871
1495 $arg =~ s/\s+/ /; !! 1872 if ($arg =~ /^#/) {
1496 !! 1873 # Treat preprocessor directive as a typeless variable just to fill
1497 if ($arg =~ /^#/) { !! 1874 # corresponding data structures "correctly". Catch it later in
1498 # Treat preprocessor directive as !! 1875 # output_* subs.
1499 # corresponding data structures " !! 1876 push_parameter($arg, "", $file);
1500 # output_* subs. !! 1877 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1501 push_parameter($arg, "", "", $fil !! 1878 # pointer-to-function
1502 } elsif ($arg =~ m/\(.+\)\s*\(/) { !! 1879 $arg =~ tr/#/,/;
1503 # pointer-to-function !! 1880 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
1504 $arg =~ tr/#/,/; !! 1881 $param = $1;
1505 $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\ !! 1882 $type = $arg;
1506 $param = $1; !! 1883 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1507 $type = $arg; !! 1884 save_struct_actual($param);
1508 $type =~ s/([^\(]+\(\*?)\s*$param !! 1885 push_parameter($param, $type, $file);
1509 save_struct_actual($param); !! 1886 } elsif ($arg) {
1510 push_parameter($param, $type, $ar !! 1887 $arg =~ s/\s*:\s*/:/g;
1511 } elsif ($arg =~ m/\(.+\)\s*\[/) { !! 1888 $arg =~ s/\s*\[/\[/g;
1512 # array-of-pointers !! 1889
1513 $arg =~ tr/#/,/; !! 1890 my @args = split('\s*,\s*', $arg);
1514 $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\ !! 1891 if ($args[0] =~ m/\*/) {
1515 $param = $1; !! 1892 $args[0] =~ s/(\*+)\s*/ $1/;
1516 $type = $arg; !! 1893 }
1517 $type =~ s/([^\(]+\(\*?)\s*$param !! 1894
1518 save_struct_actual($param); !! 1895 my @first_arg;
1519 push_parameter($param, $type, $ar !! 1896 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1520 } elsif ($arg) { !! 1897 shift @args;
1521 $arg =~ s/\s*:\s*/:/g; !! 1898 push(@first_arg, split('\s+', $1));
1522 $arg =~ s/\s*\[/\[/g; !! 1899 push(@first_arg, $2);
1523 !! 1900 } else {
1524 my @args = split('\s*,\s*', $arg) !! 1901 @first_arg = split('\s+', shift @args);
1525 if ($args[0] =~ m/\*/) { !! 1902 }
1526 $args[0] =~ s/(\*+)\s*/ $1/; !! 1903
1527 } !! 1904 unshift(@args, pop @first_arg);
1528 !! 1905 $type = join " ", @first_arg;
1529 my @first_arg; !! 1906
1530 if ($args[0] =~ /^(.*\s+)(.*?\[.* !! 1907 foreach $param (@args) {
1531 shift @args; !! 1908 if ($param =~ m/^(\*+)\s*(.*)/) {
1532 push(@first_arg, split('\s+', !! 1909 save_struct_actual($2);
1533 push(@first_arg, $2); !! 1910 push_parameter($2, "$type $1", $file);
1534 } else { !! 1911 }
1535 @first_arg = split('\s+', shi !! 1912 elsif ($param =~ m/(.*?):(\d+)/) {
1536 } !! 1913 if ($type ne "") { # skip unnamed bit-fields
1537 !! 1914 save_struct_actual($1);
1538 unshift(@args, pop @first_arg); !! 1915 push_parameter($1, "$type:$2", $file)
1539 $type = join " ", @first_arg; !! 1916 }
1540 !! 1917 }
1541 foreach $param (@args) { !! 1918 else {
1542 if ($param =~ m/^(\*+)\s*(.*) !! 1919 save_struct_actual($param);
1543 save_struct_actual($2); !! 1920 push_parameter($param, $type, $file);
1544 !! 1921 }
1545 push_parameter($2, "$type !! 1922 }
1546 } elsif ($param =~ m/(.*?):(\ !! 1923 }
1547 if ($type ne "") { # skip !! 1924 }
1548 save_struct_actual($1 !! 1925 }
1549 push_parameter($1, "$ !! 1926
1550 } !! 1927 sub push_parameter($$$) {
1551 } else { !! 1928 my $param = shift;
1552 save_struct_actual($param !! 1929 my $type = shift;
1553 push_parameter($param, $t !! 1930 my $file = shift;
1554 } !! 1931
1555 } !! 1932 if (($anon_struct_union == 1) && ($type eq "") &&
1556 } !! 1933 ($param eq "}")) {
1557 } !! 1934 return; # ignore the ending }; from anon. struct/union
1558 } !! 1935 }
1559 !! 1936
1560 sub push_parameter($$$$$) { !! 1937 $anon_struct_union = 0;
1561 my $param = shift; !! 1938 my $param_name = $param;
1562 my $type = shift; !! 1939 $param_name =~ s/\[.*//;
1563 my $org_arg = shift; !! 1940
1564 my $file = shift; !! 1941 if ($type eq "" && $param =~ /\.\.\.$/)
1565 my $declaration_name = shift; !! 1942 {
1566 !! 1943 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1567 if (($anon_struct_union == 1) && ($type e !! 1944 $parameterdescs{$param} = "variable arguments";
1568 ($param eq "}")) { !! 1945 }
1569 return; # ignore the ending }; !! 1946 }
1570 } !! 1947 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1571 !! 1948 {
1572 $anon_struct_union = 0; !! 1949 $param="void";
1573 $param =~ s/[\[\)].*//; !! 1950 $parameterdescs{void} = "no arguments";
1574 !! 1951 }
1575 if ($type eq "" && $param =~ /\.\.\.$/) !! 1952 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1576 { !! 1953 # handle unnamed (anonymous) union or struct:
1577 if (!$param =~ /\w\.\.\.$/) { !! 1954 {
1578 # handles unnamed variable parame !! 1955 $type = $param;
1579 $param = "..."; !! 1956 $param = "{unnamed_" . $param . "}";
1580 } elsif ($param =~ /\w\.\.\.$/) { !! 1957 $parameterdescs{$param} = "anonymous\n";
1581 # for named variable parameters o !! 1958 $anon_struct_union = 1;
1582 $param =~ s/\.\.\.$//; !! 1959 }
1583 } !! 1960
1584 if (!defined $parameterdescs{$param} !! 1961 # warn if parameter has no description
1585 $parameterdescs{$param} = "variab !! 1962 # (but ignore ones starting with # as these are not parameters
1586 } !! 1963 # but inline preprocessor statements);
1587 } !! 1964 # also ignore unnamed structs/unions;
1588 elsif ($type eq "" && ($param eq "" or $p !! 1965 if (!$anon_struct_union) {
1589 { !! 1966 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1590 $param="void"; !! 1967
1591 $parameterdescs{void} = "no arguments !! 1968 $parameterdescs{$param_name} = $undescribed;
1592 } !! 1969
1593 elsif ($type eq "" && ($param eq "struct" !! 1970 if (($type eq 'function') || ($type eq 'enum')) {
1594 # handle unnamed (anonymous) union or str !! 1971 print STDERR "Warning(${file}:$.): Function parameter ".
1595 { !! 1972 "or member '$param' not " .
1596 $type = $param; !! 1973 "described in '$declaration_name'\n";
1597 $param = "{unnamed_" . $param . "}"; !! 1974 }
1598 $parameterdescs{$param} = "anonymous\ !! 1975 print STDERR "Warning(${file}:$.):" .
1599 $anon_struct_union = 1; !! 1976 " No description found for parameter '$param'\n";
1600 } !! 1977 ++$warnings;
1601 elsif ($param =~ "__cacheline_group" ) !! 1978 }
1602 # handle cache group enforcing variables: !! 1979 }
1603 { !! 1980
1604 return; # ignore __cacheline_group_be !! 1981 $param = xml_escape($param);
1605 } !! 1982
1606 !! 1983 # strip spaces from $param so that it is one continuous string
1607 # warn if parameter has no description !! 1984 # on @parameterlist;
1608 # (but ignore ones starting with # as the !! 1985 # this fixes a problem where check_sections() cannot find
1609 # but inline preprocessor statements); !! 1986 # a parameter like "addr[6 + 2]" because it actually appears
1610 # Note: It will also ignore void params a !! 1987 # as "addr[6", "+", "2]" on the parameter list;
1611 if (!defined $parameterdescs{$param} && $ !! 1988 # but it's better to maintain the param string unchanged for output,
1612 $parameterdescs{$param} = $undescribe !! 1989 # so just weaken the string compare in check_sections() to ignore
1613 !! 1990 # "[blah" in a parameter string;
1614 if (show_warnings($type, $declaration !! 1991 ###$param =~ s/\s*//g;
1615 emit_warning("${file}:$.", "Funct !! 1992 push @parameterlist, $param;
1616 } !! 1993 $parametertypes{$param} = $type;
1617 } !! 1994 }
1618 !! 1995
1619 # strip spaces from $param so that it is !! 1996 sub check_sections($$$$$$) {
1620 # on @parameterlist; !! 1997 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
1621 # this fixes a problem where check_sectio !! 1998 my @sects = split ' ', $sectcheck;
1622 # a parameter like "addr[6 + 2]" because !! 1999 my @prms = split ' ', $prmscheck;
1623 # as "addr[6", "+", "2]" on the parameter !! 2000 my $err;
1624 # but it's better to maintain the param s !! 2001 my ($px, $sx);
1625 # so just weaken the string compare in ch !! 2002 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
1626 # "[blah" in a parameter string; !! 2003
1627 ###$param =~ s/\s*//g; !! 2004 foreach $sx (0 .. $#sects) {
1628 push @parameterlist, $param; !! 2005 $err = 1;
1629 $org_arg =~ s/\s\s+/ /g; !! 2006 foreach $px (0 .. $#prms) {
1630 $parametertypes{$param} = $org_arg; !! 2007 $prm_clean = $prms[$px];
1631 } !! 2008 $prm_clean =~ s/\[.*\]//;
1632 !! 2009 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1633 sub check_sections($$$$$) { !! 2010 # ignore array size in a parameter string;
1634 my ($file, $decl_name, $decl_type, $sectc !! 2011 # however, the original param string may contain
1635 my @sects = split ' ', $sectcheck; !! 2012 # spaces, e.g.: addr[6 + 2]
1636 my @prms = split ' ', $prmscheck; !! 2013 # and this appears in @prms as "addr[6" since the
1637 my $err; !! 2014 # parameter list is split at spaces;
1638 my ($px, $sx); !! 2015 # hence just ignore "[..." for the sections check;
1639 my $prm_clean; # strip trailing "[ !! 2016 $prm_clean =~ s/\[.*//;
1640 !! 2017
1641 foreach $sx (0 .. $#sects) { !! 2018 ##$prm_clean =~ s/^\**//;
1642 $err = 1; !! 2019 if ($prm_clean eq $sects[$sx]) {
1643 foreach $px (0 .. $#prms) { !! 2020 $err = 0;
1644 $prm_clean = $prms[$px]; !! 2021 last;
1645 $prm_clean =~ s/\[.*\]//; !! 2022 }
1646 $prm_clean =~ s/$attribute//i; !! 2023 }
1647 # ignore array size in a paramete !! 2024 if ($err) {
1648 # however, the original param str !! 2025 if ($decl_type eq "function") {
1649 # spaces, e.g.: addr[6 + 2] !! 2026 print STDERR "Warning(${file}:$.): " .
1650 # and this appears in @prms as "a !! 2027 "Excess function parameter " .
1651 # parameter list is split at spac !! 2028 "'$sects[$sx]' " .
1652 # hence just ignore "[..." for th !! 2029 "description in '$decl_name'\n";
1653 $prm_clean =~ s/\[.*//; !! 2030 ++$warnings;
1654 !! 2031 } else {
1655 ##$prm_clean =~ s/^\**//; !! 2032 if ($nested !~ m/\Q$sects[$sx]\E/) {
1656 if ($prm_clean eq $sects[$sx]) { !! 2033 print STDERR "Warning(${file}:$.): " .
1657 $err = 0; !! 2034 "Excess struct/union/enum/typedef member " .
1658 last; !! 2035 "'$sects[$sx]' " .
1659 } !! 2036 "description in '$decl_name'\n";
1660 } !! 2037 ++$warnings;
1661 if ($err) { !! 2038 }
1662 if ($decl_type eq "function") { !! 2039 }
1663 emit_warning("${file}:$.", !! 2040 }
1664 "Excess function paramete !! 2041 }
1665 "'$sects[$sx]' " . <<
1666 "description in '$decl_na <<
1667 } elsif (($decl_type eq "struct") <<
1668 ($decl_type eq "uni <<
1669 emit_warning("${file}:$.", <<
1670 "Excess $decl_type member <<
1671 "'$sects[$sx]' " . <<
1672 "description in '$decl_na <<
1673 } <<
1674 } <<
1675 } <<
1676 } 2042 }
1677 2043
1678 ## 2044 ##
1679 # Checks the section describing the return va 2045 # Checks the section describing the return value of a function.
1680 sub check_return_section { 2046 sub check_return_section {
1681 my $file = shift; !! 2047 my $file = shift;
1682 my $declaration_name = shift; !! 2048 my $declaration_name = shift;
1683 my $return_type = shift; !! 2049 my $return_type = shift;
1684 !! 2050
1685 # Ignore an empty return type (It's a mac !! 2051 # Ignore an empty return type (It's a macro)
1686 # Ignore functions with a "void" return t !! 2052 # Ignore functions with a "void" return type. (But don't ignore "void *")
1687 if (($return_type eq "") || ($return_type !! 2053 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1688 return; !! 2054 return;
1689 } !! 2055 }
1690 !! 2056
1691 if (!defined($sections{$section_return}) !! 2057 if (!defined($sections{$section_return}) ||
1692 $sections{$section_return} eq "") !! 2058 $sections{$section_return} eq "") {
1693 { !! 2059 print STDERR "Warning(${file}:$.): " .
1694 emit_warning("${file}:$.", !! 2060 "No description found for return value of " .
1695 "No description found fo !! 2061 "'$declaration_name'\n";
1696 "'$declaration_name'\n") !! 2062 ++$warnings;
1697 } !! 2063 }
1698 } 2064 }
1699 2065
1700 ## 2066 ##
1701 # takes a function prototype and the name of 2067 # takes a function prototype and the name of the current file being
1702 # processed and spits out all the details sto 2068 # processed and spits out all the details stored in the global
1703 # arrays/hashes. 2069 # arrays/hashes.
1704 sub dump_function($$) { 2070 sub dump_function($$) {
1705 my $prototype = shift; 2071 my $prototype = shift;
1706 my $file = shift; 2072 my $file = shift;
1707 my $noret = 0; <<
1708 <<
1709 print_lineno($new_start_line); <<
1710 2073
1711 $prototype =~ s/^static +//; 2074 $prototype =~ s/^static +//;
1712 $prototype =~ s/^extern +//; 2075 $prototype =~ s/^extern +//;
1713 $prototype =~ s/^asmlinkage +//; 2076 $prototype =~ s/^asmlinkage +//;
1714 $prototype =~ s/^inline +//; 2077 $prototype =~ s/^inline +//;
1715 $prototype =~ s/^__inline__ +//; 2078 $prototype =~ s/^__inline__ +//;
1716 $prototype =~ s/^__inline +//; 2079 $prototype =~ s/^__inline +//;
1717 $prototype =~ s/^__always_inline +//; 2080 $prototype =~ s/^__always_inline +//;
1718 $prototype =~ s/^noinline +//; 2081 $prototype =~ s/^noinline +//;
1719 $prototype =~ s/^__FORTIFY_INLINE +//; <<
1720 $prototype =~ s/__init +//; 2082 $prototype =~ s/__init +//;
1721 $prototype =~ s/__init_or_module +//; 2083 $prototype =~ s/__init_or_module +//;
1722 $prototype =~ s/__deprecated +//; <<
1723 $prototype =~ s/__flatten +//; <<
1724 $prototype =~ s/__meminit +//; <<
1725 $prototype =~ s/__must_check +//; 2084 $prototype =~ s/__must_check +//;
1726 $prototype =~ s/__weak +//; 2085 $prototype =~ s/__weak +//;
1727 $prototype =~ s/__sched +//; !! 2086 $prototype =~ s/^#\s*define\s+//; #ak added
1728 $prototype =~ s/_noprof//; !! 2087 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1729 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s <<
1730 $prototype =~ s/__(?:re)?alloc_size\s*\(\ <<
1731 $prototype =~ s/__diagnose_as\s*\(\s*\S+\ <<
1732 $prototype =~ s/DECL_BUCKET_PARAMS\s*\(\s <<
1733 my $define = $prototype =~ s/^#\s*define\ <<
1734 $prototype =~ s/__attribute_const__ +//; <<
1735 $prototype =~ s/__attribute__\s*\(\( <<
1736 (?: <<
1737 [\w\s]++ # attribut <<
1738 (?:\([^)]*+\))? # attribut <<
1739 \s*+,? # optional <<
1740 )+ <<
1741 \)\)\s+//x; <<
1742 2088
1743 # Yes, this truly is vile. We are lookin 2089 # Yes, this truly is vile. We are looking for:
1744 # 1. Return type (may be nothing if we're 2090 # 1. Return type (may be nothing if we're looking at a macro)
1745 # 2. Function name 2091 # 2. Function name
1746 # 3. Function parameters. 2092 # 3. Function parameters.
1747 # 2093 #
1748 # All the while we have to watch out for 2094 # All the while we have to watch out for function pointer parameters
1749 # (which IIRC is what the two sections ar 2095 # (which IIRC is what the two sections are for), C types (these
1750 # regexps don't even start to express all 2096 # regexps don't even start to express all the possibilities), and
1751 # so on. 2097 # so on.
1752 # 2098 #
1753 # If you mess with these regexps, it's a 2099 # If you mess with these regexps, it's a good idea to check that
1754 # the following functions' documentation 2100 # the following functions' documentation still comes out right:
1755 # - parport_register_device (function poi 2101 # - parport_register_device (function pointer parameters)
1756 # - atomic_set (macro) 2102 # - atomic_set (macro)
1757 # - pci_match_device, __copy_to_user (lon 2103 # - pci_match_device, __copy_to_user (long return type)
1758 my $name = qr{[a-zA-Z0-9_~:]+}; <<
1759 my $prototype_end1 = qr{[^\(]*}; <<
1760 my $prototype_end2 = qr{[^\{]*}; <<
1761 my $prototype_end = qr{\(($prototype_end1 <<
1762 my $type1 = qr{[\w\s]+}; <<
1763 my $type2 = qr{$type1\*+}; <<
1764 <<
1765 if ($define && $prototype =~ m/^()($name) <<
1766 # This is an object-like macro, it ha <<
1767 # list. <<
1768 # Function-like macros are not allowe <<
1769 # declaration_name and opening parent <<
1770 $return_type = $1; <<
1771 $declaration_name = $2; <<
1772 $noret = 1; <<
1773 } elsif ($prototype =~ m/^()($name)\s*$pr <<
1774 $prototype =~ m/^($type1)\s+($name)\s <<
1775 $prototype =~ m/^($type2+)\s*($name)\ <<
1776 $return_type = $1; <<
1777 $declaration_name = $2; <<
1778 my $args = $3; <<
1779 2104
1780 create_parameterlist($args, ',', $fil !! 2105 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1781 } else { !! 2106 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1782 emit_warning("${file}:$.", "cannot un !! 2107 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1783 return; !! 2108 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1784 } !! 2109 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 2110 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 2111 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
>> 2112 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2113 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2114 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2115 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2116 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2117 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2118 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2119 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2120 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
>> 2121 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
>> 2122 $return_type = $1;
>> 2123 $declaration_name = $2;
>> 2124 my $args = $3;
1785 2125
1786 if ($identifier ne $declaration_name) { !! 2126 create_parameterlist($args, ',', $file);
1787 emit_warning("${file}:$.", "expecting !! 2127 } else {
1788 return; !! 2128 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
>> 2129 ++$errors;
>> 2130 return;
1789 } 2131 }
1790 2132
1791 my $prms = join " ", @parameterlist; !! 2133 my $prms = join " ", @parameterlist;
1792 check_sections($file, $declaration_name, !! 2134 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
>> 2135
>> 2136 # This check emits a lot of warnings at the moment, because many
>> 2137 # functions don't have a 'Return' doc section. So until the number
>> 2138 # of warnings goes sufficiently down, the check is only performed in
>> 2139 # verbose mode.
>> 2140 # TODO: always perform the check.
>> 2141 if ($verbose) {
>> 2142 check_return_section($file, $declaration_name, $return_type);
>> 2143 }
1793 2144
1794 # This check emits a lot of warnings at t !! 2145 output_declaration($declaration_name,
1795 # functions don't have a 'Return' doc sec !! 2146 'function',
1796 # of warnings goes sufficiently down, the !! 2147 {'function' => $declaration_name,
1797 # -Wreturn mode. !! 2148 'module' => $modulename,
1798 # TODO: always perform the check. !! 2149 'functiontype' => $return_type,
1799 if ($Wreturn && !$noret) { !! 2150 'parameterlist' => \@parameterlist,
1800 check_return_section($file, $declarat !! 2151 'parameterdescs' => \%parameterdescs,
1801 } !! 2152 'parametertypes' => \%parametertypes,
1802 !! 2153 'sectionlist' => \@sectionlist,
1803 # The function parser can be called with !! 2154 'sections' => \%sections,
1804 # Handle it. !! 2155 'purpose' => $declaration_purpose
1805 if ($return_type =~ /typedef/) { !! 2156 });
1806 output_declaration($declaration_name, <<
1807 'function', <<
1808 {'function' => $de <<
1809 'typedef' => 1, <<
1810 'module' => $modu <<
1811 'functiontype' => <<
1812 'parameterlist' = <<
1813 'parameterdescs' <<
1814 'parametertypes' <<
1815 'sectionlist' => <<
1816 'sections' => \%s <<
1817 'purpose' => $dec <<
1818 }); <<
1819 } else { <<
1820 output_declaration($declaration_name, <<
1821 'function', <<
1822 {'function' => $de <<
1823 'module' => $modu <<
1824 'functiontype' => <<
1825 'parameterlist' = <<
1826 'parameterdescs' <<
1827 'parametertypes' <<
1828 'sectionlist' => <<
1829 'sections' => \%s <<
1830 'purpose' => $dec <<
1831 }); <<
1832 } <<
1833 } 2157 }
1834 2158
1835 sub reset_state { 2159 sub reset_state {
1836 $function = ""; 2160 $function = "";
>> 2161 %constants = ();
1837 %parameterdescs = (); 2162 %parameterdescs = ();
1838 %parametertypes = (); 2163 %parametertypes = ();
1839 @parameterlist = (); 2164 @parameterlist = ();
1840 %sections = (); 2165 %sections = ();
1841 @sectionlist = (); 2166 @sectionlist = ();
1842 $sectcheck = ""; 2167 $sectcheck = "";
1843 $struct_actual = ""; 2168 $struct_actual = "";
1844 $prototype = ""; 2169 $prototype = "";
1845 2170
1846 $state = STATE_NORMAL; !! 2171 $state = 0;
1847 $inline_doc_state = STATE_INLINE_NA; <<
1848 } 2172 }
1849 2173
1850 sub tracepoint_munge($) { 2174 sub tracepoint_munge($) {
1851 my $file = shift; !! 2175 my $file = shift;
1852 my $tracepointname = 0; !! 2176 my $tracepointname = 0;
1853 my $tracepointargs = 0; !! 2177 my $tracepointargs = 0;
1854 !! 2178
1855 if ($prototype =~ m/TRACE_EVENT\((.*?),/) !! 2179 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
1856 $tracepointname = $1; !! 2180 $tracepointname = $1;
1857 } !! 2181 }
1858 if ($prototype =~ m/DEFINE_SINGLE_EVENT\( !! 2182 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
1859 $tracepointname = $1; !! 2183 $tracepointname = $1;
1860 } !! 2184 }
1861 if ($prototype =~ m/DEFINE_EVENT\((.*?),( !! 2185 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1862 $tracepointname = $2; !! 2186 $tracepointname = $2;
1863 } !! 2187 }
1864 $tracepointname =~ s/^\s+//; #strip leadi !! 2188 $tracepointname =~ s/^\s+//; #strip leading whitespace
1865 if ($prototype =~ m/TP_PROTO\((.*?)\)/) { !! 2189 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1866 $tracepointargs = $1; !! 2190 $tracepointargs = $1;
1867 } !! 2191 }
1868 if (($tracepointname eq 0) || ($tracepoin !! 2192 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1869 emit_warning("${file}:$.", "Unrecogni !! 2193 print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
1870 "$prototype\n"); !! 2194 "$prototype\n";
1871 } else { !! 2195 } else {
1872 $prototype = "static inline void trac !! 2196 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
1873 $identifier = "trace_$identifier"; !! 2197 }
1874 } <<
1875 } 2198 }
1876 2199
1877 sub syscall_munge() { 2200 sub syscall_munge() {
1878 my $void = 0; !! 2201 my $void = 0;
1879 <<
1880 $prototype =~ s@[\r\n]+@ @gos; # strip ne <<
1881 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\ <<
1882 if ($prototype =~ m/SYSCALL_DEFINE0/) { <<
1883 $void = 1; <<
1884 ## $prototype = "long sys_$1(void)"; <<
1885 } <<
1886 <<
1887 $prototype =~ s/SYSCALL_DEFINE.*\(/long s <<
1888 if ($prototype =~ m/long (sys_.*?),/) { <<
1889 $prototype =~ s/,/\(/; <<
1890 } elsif ($void) { <<
1891 $prototype =~ s/\)/\(void\)/; <<
1892 } <<
1893 2202
1894 # now delete all of the odd-number commas !! 2203 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
1895 # so that arg types & arg names don't hav !! 2204 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1896 my $count = 0; !! 2205 if ($prototype =~ m/SYSCALL_DEFINE0/) {
1897 my $len = length($prototype); !! 2206 $void = 1;
1898 if ($void) { !! 2207 ## $prototype = "long sys_$1(void)";
1899 $len = 0; # skip the for-loop !! 2208 }
1900 } !! 2209
1901 for (my $ix = 0; $ix < $len; $ix++) { !! 2210 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1902 if (substr($prototype, $ix, 1) eq ',' !! 2211 if ($prototype =~ m/long (sys_.*?),/) {
1903 $count++; !! 2212 $prototype =~ s/,/\(/;
1904 if ($count % 2 == 1) { !! 2213 } elsif ($void) {
1905 substr($prototype, $ix, 1) = !! 2214 $prototype =~ s/\)/\(void\)/;
1906 } !! 2215 }
1907 } !! 2216
1908 } !! 2217 # now delete all of the odd-number commas in $prototype
>> 2218 # so that arg types & arg names don't have a comma between them
>> 2219 my $count = 0;
>> 2220 my $len = length($prototype);
>> 2221 if ($void) {
>> 2222 $len = 0; # skip the for-loop
>> 2223 }
>> 2224 for (my $ix = 0; $ix < $len; $ix++) {
>> 2225 if (substr($prototype, $ix, 1) eq ',') {
>> 2226 $count++;
>> 2227 if ($count % 2 == 1) {
>> 2228 substr($prototype, $ix, 1) = ' ';
>> 2229 }
>> 2230 }
>> 2231 }
1909 } 2232 }
1910 2233
1911 sub process_proto_function($$) { !! 2234 sub process_state3_function($$) {
1912 my $x = shift; 2235 my $x = shift;
1913 my $file = shift; 2236 my $file = shift;
1914 2237
1915 $x =~ s@\/\/.*$@@gos; # strip C99-style c 2238 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1916 2239
1917 if ($x =~ /^#/ && $x !~ /^#\s*define/) { !! 2240 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1918 # do nothing !! 2241 # do nothing
1919 } elsif ($x =~ /([^\{]*)/) { !! 2242 }
1920 $prototype .= $1; !! 2243 elsif ($x =~ /([^\{]*)/) {
>> 2244 $prototype .= $1;
1921 } 2245 }
1922 2246
1923 if (($x =~ /\{/) || ($x =~ /\#\s*define/) 2247 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1924 $prototype =~ s@/\*.*?\*/@@gos; !! 2248 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1925 $prototype =~ s@[\r\n]+@ @gos; # stri !! 2249 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1926 $prototype =~ s@^\s+@@gos; # strip le !! 2250 $prototype =~ s@^\s+@@gos; # strip leading spaces
1927 !! 2251 if ($prototype =~ /SYSCALL_DEFINE/) {
1928 # Handle prototypes for function poin !! 2252 syscall_munge();
1929 # int (*pcs_config)(struct foo) !! 2253 }
1930 $prototype =~ s@^(\S+\s+)\(\s*\*(\S+) !! 2254 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1931 !! 2255 $prototype =~ /DEFINE_SINGLE_EVENT/)
1932 if ($prototype =~ /SYSCALL_DEFINE/) { !! 2256 {
1933 syscall_munge(); !! 2257 tracepoint_munge($file);
1934 } !! 2258 }
1935 if ($prototype =~ /TRACE_EVENT/ || $p !! 2259 dump_function($prototype, $file);
1936 $prototype =~ /DEFINE_SINGLE_EVEN !! 2260 reset_state();
1937 { <<
1938 tracepoint_munge($file); <<
1939 } <<
1940 dump_function($prototype, $file); <<
1941 reset_state(); <<
1942 } 2261 }
1943 } 2262 }
1944 2263
1945 sub process_proto_type($$) { !! 2264 sub process_state3_type($$) {
1946 my $x = shift; 2265 my $x = shift;
1947 my $file = shift; 2266 my $file = shift;
1948 2267
1949 $x =~ s@[\r\n]+@ @gos; # strip newlines/c 2268 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1950 $x =~ s@^\s+@@gos; # strip leading spaces 2269 $x =~ s@^\s+@@gos; # strip leading spaces
1951 $x =~ s@\s+$@@gos; # strip trailing space 2270 $x =~ s@\s+$@@gos; # strip trailing spaces
1952 $x =~ s@\/\/.*$@@gos; # strip C99-style c 2271 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1953 2272
1954 if ($x =~ /^#/) { 2273 if ($x =~ /^#/) {
1955 # To distinguish preprocessor directi !! 2274 # To distinguish preprocessor directive from regular declaration later.
1956 $x .= ";"; !! 2275 $x .= ";";
1957 } 2276 }
1958 2277
1959 while (1) { 2278 while (1) {
1960 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ !! 2279 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1961 if( length $prototype ) { !! 2280 $prototype .= $1 . $2;
1962 $prototype .= " " !! 2281 ($2 eq '{') && $brcount++;
1963 } !! 2282 ($2 eq '}') && $brcount--;
1964 $prototype .= $1 . $2; !! 2283 if (($2 eq ';') && ($brcount == 0)) {
1965 ($2 eq '{') && $brcount++; !! 2284 dump_declaration($prototype, $file);
1966 ($2 eq '}') && $brcount--; !! 2285 reset_state();
1967 if (($2 eq ';') && ($brcount == 0 !! 2286 last;
1968 dump_declaration($prototype, !! 2287 }
1969 reset_state(); !! 2288 $x = $3;
1970 last; !! 2289 } else {
1971 } !! 2290 $prototype .= $x;
1972 $x = $3; !! 2291 last;
1973 } else { !! 2292 }
1974 $prototype .= $x; <<
1975 last; <<
1976 } <<
1977 } 2293 }
1978 } 2294 }
1979 2295
>> 2296 # xml_escape: replace <, >, and & in the text stream;
>> 2297 #
>> 2298 # however, formatting controls that are generated internally/locally in the
>> 2299 # kernel-doc script are not escaped here; instead, they begin life like
>> 2300 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
>> 2301 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
>> 2302 # just before actual output; (this is done by local_unescape())
>> 2303 sub xml_escape($) {
>> 2304 my $text = shift;
>> 2305 if (($output_mode eq "text") || ($output_mode eq "man")) {
>> 2306 return $text;
>> 2307 }
>> 2308 $text =~ s/\&/\\\\\\amp;/g;
>> 2309 $text =~ s/\</\\\\\\lt;/g;
>> 2310 $text =~ s/\>/\\\\\\gt;/g;
>> 2311 return $text;
>> 2312 }
>> 2313
>> 2314 # convert local escape strings to html
>> 2315 # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
>> 2316 sub local_unescape($) {
>> 2317 my $text = shift;
>> 2318 if (($output_mode eq "text") || ($output_mode eq "man")) {
>> 2319 return $text;
>> 2320 }
>> 2321 $text =~ s/\\\\\\\\lt:/</g;
>> 2322 $text =~ s/\\\\\\\\gt:/>/g;
>> 2323 return $text;
>> 2324 }
1980 2325
1981 sub map_filename($) { !! 2326 sub process_file($) {
1982 my $file; 2327 my $file;
1983 my ($orig_file) = @_; !! 2328 my $identifier;
>> 2329 my $func;
>> 2330 my $descr;
>> 2331 my $in_purpose = 0;
>> 2332 my $initial_section_counter = $section_counter;
1984 2333
1985 if (defined($ENV{'SRCTREE'})) { 2334 if (defined($ENV{'SRCTREE'})) {
1986 $file = "$ENV{'SRCTREE'}" . "/" . $or !! 2335 $file = "$ENV{'SRCTREE'}" . "/" . "@_";
1987 } else { !! 2336 }
1988 $file = $orig_file; !! 2337 else {
>> 2338 $file = "@_";
1989 } 2339 }
1990 <<
1991 if (defined($source_map{$file})) { 2340 if (defined($source_map{$file})) {
1992 $file = $source_map{$file}; !! 2341 $file = $source_map{$file};
1993 } 2342 }
1994 2343
1995 return $file; <<
1996 } <<
1997 <<
1998 sub process_export_file($) { <<
1999 my ($orig_file) = @_; <<
2000 my $file = map_filename($orig_file); <<
2001 <<
2002 if (!open(IN,"<$file")) { 2344 if (!open(IN,"<$file")) {
2003 print STDERR "Error: Cannot open file !! 2345 print STDERR "Error: Cannot open file $file\n";
2004 ++$errors; !! 2346 ++$errors;
2005 return; !! 2347 return;
2006 } <<
2007 <<
2008 while (<IN>) { <<
2009 if (/$export_symbol/) { <<
2010 next if (defined($nosymbol_table{ <<
2011 $function_table{$2} = 1; <<
2012 } <<
2013 if (/$export_symbol_ns/) { <<
2014 next if (defined($nosymbol_table{ <<
2015 $function_table{$2} = 1; <<
2016 } <<
2017 } <<
2018 <<
2019 close(IN); <<
2020 } <<
2021 <<
2022 # <<
2023 # Parsers for the various processing states. <<
2024 # <<
2025 # STATE_NORMAL: looking for the /** to begin <<
2026 # <<
2027 sub process_normal() { <<
2028 if (/$doc_start/o) { <<
2029 $state = STATE_NAME; # next li <<
2030 $in_doc_sect = 0; <<
2031 $declaration_start_line = $. + 1; <<
2032 } <<
2033 } <<
2034 <<
2035 # <<
2036 # STATE_NAME: Looking for the "name - descrip <<
2037 # <<
2038 sub process_name($$) { <<
2039 my $file = shift; <<
2040 my $descr; <<
2041 <<
2042 if (/$doc_block/o) { <<
2043 $state = STATE_DOCBLOCK; <<
2044 $contents = ""; <<
2045 $new_start_line = $.; <<
2046 <<
2047 if ( $1 eq "" ) { <<
2048 $section = $section_intro; <<
2049 } else { <<
2050 $section = $1; <<
2051 } <<
2052 } elsif (/$doc_decl/o) { <<
2053 $identifier = $1; <<
2054 my $is_kernel_comment = 0; <<
2055 my $decl_start = qr{$doc_com}; <<
2056 # test for pointer declaration type, <<
2057 my $fn_type = qr{\w+\s*\*\s*}; <<
2058 my $parenthesis = qr{\(\w*\)}; <<
2059 my $decl_end = qr{[-:].*}; <<
2060 if (/^$decl_start([\w\s]+?)$parenthes <<
2061 $identifier = $1; <<
2062 } <<
2063 if ($identifier =~ m/^(struct|union|e <<
2064 $decl_type = $1; <<
2065 $identifier = $2; <<
2066 $is_kernel_comment = 1; <<
2067 } <<
2068 # Look for foo() or static void foo() <<
2069 # identifier <<
2070 elsif (/^$decl_start$fn_type?(\w+)\s* <<
2071 /^$decl_start$fn_type?(\w+.*)$par <<
2072 $identifier = $1; <<
2073 $decl_type = 'function'; <<
2074 $identifier =~ s/^define\s+//; <<
2075 $is_kernel_comment = 1; <<
2076 } <<
2077 $identifier =~ s/\s+$//; <<
2078 <<
2079 $state = STATE_BODY; <<
2080 # if there's no @param blocks need to <<
2081 # here <<
2082 $contents = ""; <<
2083 $section = $section_default; <<
2084 $new_start_line = $. + 1; <<
2085 if (/[-:](.*)/) { <<
2086 # strip leading/trailing/multiple <<
2087 $descr= $1; <<
2088 $descr =~ s/^\s*//; <<
2089 $descr =~ s/\s*$//; <<
2090 $descr =~ s/\s+/ /g; <<
2091 $declaration_purpose = $descr; <<
2092 $state = STATE_BODY_MAYBE; <<
2093 } else { <<
2094 $declaration_purpose = ""; <<
2095 } <<
2096 <<
2097 if (!$is_kernel_comment) { <<
2098 emit_warning("${file}:$.", "This <<
2099 $state = STATE_NORMAL; <<
2100 } <<
2101 <<
2102 if (($declaration_purpose eq "") && $ <<
2103 emit_warning("${file}:$.", "missi <<
2104 } <<
2105 <<
2106 if ($identifier eq "" && $decl_type n <<
2107 emit_warning("${file}:$.", "wrong <<
2108 $state = STATE_NORMAL; <<
2109 } <<
2110 <<
2111 if ($verbose) { <<
2112 print STDERR "${file}:$.: info: S <<
2113 } <<
2114 } else { <<
2115 emit_warning("${file}:$.", "Cannot un <<
2116 $state = STATE_NORMAL; <<
2117 } <<
2118 } <<
2119 <<
2120 <<
2121 # <<
2122 # STATE_BODY and STATE_BODY_MAYBE: the bulk o <<
2123 # <<
2124 sub process_body($$) { <<
2125 my $file = shift; <<
2126 <<
2127 if ($state == STATE_BODY_WITH_BLANK_LINE <<
2128 dump_section($file, $section, $conten <<
2129 $section = $section_default; <<
2130 $new_start_line = $.; <<
2131 $contents = ""; <<
2132 } <<
2133 <<
2134 if (/$doc_sect/i) { # case insensitive fo <<
2135 $in_doc_sect = 1; <<
2136 $newsection = $1; <<
2137 $newcontents = $2; <<
2138 <<
2139 # map the supported section names to <<
2140 if ($newsection =~ m/^description$/i) <<
2141 $newsection = $section_default; <<
2142 } elsif ($newsection =~ m/^context$/i <<
2143 $newsection = $section_context; <<
2144 } elsif ($newsection =~ m/^returns?$/ <<
2145 $newsection = $section_return; <<
2146 } elsif ($newsection =~ m/^\@return$/ <<
2147 # special: @return is a section, <<
2148 $newsection = $section_return; <<
2149 } <<
2150 <<
2151 if (($contents ne "") && ($contents n <<
2152 if (!$in_doc_sect && $Wcontents_b <<
2153 emit_warning("${file}:$.", "c <<
2154 } <<
2155 dump_section($file, $section, $co <<
2156 $section = $section_default; <<
2157 } <<
2158 <<
2159 $in_doc_sect = 1; <<
2160 $state = STATE_BODY; <<
2161 $contents = $newcontents; <<
2162 $new_start_line = $.; <<
2163 while (substr($contents, 0, 1) eq " " <<
2164 $contents = substr($contents, 1); <<
2165 } <<
2166 if ($contents ne "") { <<
2167 $contents .= "\n"; <<
2168 } <<
2169 $section = $newsection; <<
2170 $leading_space = undef; <<
2171 } elsif (/$doc_end/) { <<
2172 if (($contents ne "") && ($contents n <<
2173 dump_section($file, $section, $co <<
2174 $section = $section_default; <<
2175 $contents = ""; <<
2176 } <<
2177 # look for doc_com + <text> + doc_end <<
2178 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\ <<
2179 emit_warning("${file}:$.", "suspi <<
2180 } <<
2181 <<
2182 $prototype = ""; <<
2183 $state = STATE_PROTO; <<
2184 $brcount = 0; <<
2185 $new_start_line = $. + 1; <<
2186 } elsif (/$doc_content/) { <<
2187 if ($1 eq "") { <<
2188 if ($section eq $section_context) <<
2189 dump_section($file, $section, <<
2190 $section = $section_default; <<
2191 $contents = ""; <<
2192 $new_start_line = $.; <<
2193 $state = STATE_BODY; <<
2194 } else { <<
2195 if ($section ne $section_defa <<
2196 $state = STATE_BODY_WITH_ <<
2197 } else { <<
2198 $state = STATE_BODY; <<
2199 } <<
2200 $contents .= "\n"; <<
2201 } <<
2202 } elsif ($state == STATE_BODY_MAYBE) <<
2203 # Continued declaration purpose <<
2204 chomp($declaration_purpose); <<
2205 $declaration_purpose .= " " . $1; <<
2206 $declaration_purpose =~ s/\s+/ /g <<
2207 } else { <<
2208 my $cont = $1; <<
2209 if ($section =~ m/^@/ || $section <<
2210 if (!defined $leading_space) <<
2211 if ($cont =~ m/^(\s+)/) { <<
2212 $leading_space = $1; <<
2213 } else { <<
2214 $leading_space = ""; <<
2215 } <<
2216 } <<
2217 $cont =~ s/^$leading_space//; <<
2218 } <<
2219 $contents .= $cont . "\n"; <<
2220 } <<
2221 } else { <<
2222 # i dont know - bad line? ignore. <<
2223 emit_warning("${file}:$.", "bad line: <<
2224 } <<
2225 } <<
2226 <<
2227 <<
2228 # <<
2229 # STATE_PROTO: reading a function/whatever pr <<
2230 # <<
2231 sub process_proto($$) { <<
2232 my $file = shift; <<
2233 <<
2234 if (/$doc_inline_oneline/) { <<
2235 $section = $1; <<
2236 $contents = $2; <<
2237 if ($contents ne "") { <<
2238 $contents .= "\n"; <<
2239 dump_section($file, $section, $co <<
2240 $section = $section_default; <<
2241 $contents = ""; <<
2242 } <<
2243 } elsif (/$doc_inline_start/) { <<
2244 $state = STATE_INLINE; <<
2245 $inline_doc_state = STATE_INLINE_NAME <<
2246 } elsif ($decl_type eq 'function') { <<
2247 process_proto_function($_, $file); <<
2248 } else { <<
2249 process_proto_type($_, $file); <<
2250 } <<
2251 } <<
2252 <<
2253 # <<
2254 # STATE_DOCBLOCK: within a DOC: block. <<
2255 # <<
2256 sub process_docblock($$) { <<
2257 my $file = shift; <<
2258 <<
2259 if (/$doc_end/) { <<
2260 dump_doc_section($file, $section, $co <<
2261 $section = $section_default; <<
2262 $contents = ""; <<
2263 $function = ""; <<
2264 %parameterdescs = (); <<
2265 %parametertypes = (); <<
2266 @parameterlist = (); <<
2267 %sections = (); <<
2268 @sectionlist = (); <<
2269 $prototype = ""; <<
2270 $state = STATE_NORMAL; <<
2271 } elsif (/$doc_content/) { <<
2272 if ( $1 eq "" ) { <<
2273 $contents .= $blankline; <<
2274 } else { <<
2275 $contents .= $1 . "\n"; <<
2276 } <<
2277 } <<
2278 } <<
2279 <<
2280 # <<
2281 # STATE_INLINE: docbook comments within a pro <<
2282 # <<
2283 sub process_inline($$) { <<
2284 my $file = shift; <<
2285 <<
2286 # First line (state 1) needs to be a @par <<
2287 if ($inline_doc_state == STATE_INLINE_NAM <<
2288 $section = $1; <<
2289 $contents = $2; <<
2290 $new_start_line = $.; <<
2291 if ($contents ne "") { <<
2292 while (substr($contents, 0, 1) eq <<
2293 $contents = substr($contents, <<
2294 } <<
2295 $contents .= "\n"; <<
2296 } <<
2297 $inline_doc_state = STATE_INLINE_TEXT <<
2298 # Documentation block end */ <<
2299 } elsif (/$doc_inline_end/) { <<
2300 if (($contents ne "") && ($contents n <<
2301 dump_section($file, $section, $co <<
2302 $section = $section_default; <<
2303 $contents = ""; <<
2304 } <<
2305 $state = STATE_PROTO; <<
2306 $inline_doc_state = STATE_INLINE_NA; <<
2307 # Regular text <<
2308 } elsif (/$doc_content/) { <<
2309 if ($inline_doc_state == STATE_INLINE <<
2310 $contents .= $1 . "\n"; <<
2311 # nuke leading blank lines <<
2312 if ($contents =~ /^\s*$/) { <<
2313 $contents = ""; <<
2314 } <<
2315 } elsif ($inline_doc_state == STATE_I <<
2316 $inline_doc_state = STATE_INLINE_ <<
2317 emit_warning("${file}:$.", "Incor <<
2318 } <<
2319 } <<
2320 } <<
2321 <<
2322 <<
2323 sub process_file($) { <<
2324 my $file; <<
2325 my $initial_section_counter = $section_co <<
2326 my ($orig_file) = @_; <<
2327 <<
2328 $file = map_filename($orig_file); <<
2329 <<
2330 if (!open(IN_FILE,"<$file")) { <<
2331 print STDERR "Error: Cannot open file <<
2332 ++$errors; <<
2333 return; <<
2334 } 2348 }
2335 2349
2336 $. = 1; 2350 $. = 1;
2337 2351
2338 $section_counter = 0; 2352 $section_counter = 0;
2339 while (<IN_FILE>) { !! 2353 while (<IN>) {
2340 while (!/^ \*/ && s/\\\s*$//) { !! 2354 while (s/\\\s*$//) {
2341 $_ .= <IN_FILE>; !! 2355 $_ .= <IN>;
2342 } !! 2356 }
2343 # Replace tabs by spaces !! 2357 if ($state == 0) {
2344 while ($_ =~ s/\t+/' ' x (length($&) !! 2358 if (/$doc_start/o) {
2345 # Hand this line to the appropriate s !! 2359 $state = 1; # next line is always the function name
2346 if ($state == STATE_NORMAL) { !! 2360 $in_doc_sect = 0;
2347 process_normal(); !! 2361 }
2348 } elsif ($state == STATE_NAME) { !! 2362 } elsif ($state == 1) { # this line is the function name (always)
2349 process_name($file, $_); !! 2363 if (/$doc_block/o) {
2350 } elsif ($state == STATE_BODY || $sta !! 2364 $state = 4;
2351 $state == STATE_BODY_WITH_BL !! 2365 $contents = "";
2352 process_body($file, $_); !! 2366 if ( $1 eq "" ) {
2353 } elsif ($state == STATE_INLINE) { # !! 2367 $section = $section_intro;
2354 process_inline($file, $_); !! 2368 } else {
2355 } elsif ($state == STATE_PROTO) { !! 2369 $section = $1;
2356 process_proto($file, $_); !! 2370 }
2357 } elsif ($state == STATE_DOCBLOCK) { !! 2371 }
2358 process_docblock($file, $_); !! 2372 elsif (/$doc_decl/o) {
2359 } !! 2373 $identifier = $1;
2360 } !! 2374 if (/\s*([\w\s]+?)\s*-/) {
2361 !! 2375 $identifier = $1;
2362 # Make sure we got something interesting. !! 2376 }
2363 if ($initial_section_counter == $section_ !! 2377
2364 output_mode ne "none") { !! 2378 $state = 2;
2365 if ($output_selection == OUTPUT_INCLU !! 2379 if (/-(.*)/) {
2366 emit_warning("${file}:1", "'$_' n !! 2380 # strip leading/trailing/multiple spaces
2367 for keys %function_table; !! 2381 $descr= $1;
2368 } else { !! 2382 $descr =~ s/^\s*//;
2369 emit_warning("${file}:1", "no str !! 2383 $descr =~ s/\s*$//;
2370 } !! 2384 $descr =~ s/\s+/ /g;
>> 2385 $declaration_purpose = xml_escape($descr);
>> 2386 $in_purpose = 1;
>> 2387 } else {
>> 2388 $declaration_purpose = "";
>> 2389 }
>> 2390
>> 2391 if (($declaration_purpose eq "") && $verbose) {
>> 2392 print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
>> 2393 print STDERR $_;
>> 2394 ++$warnings;
>> 2395 }
>> 2396
>> 2397 if ($identifier =~ m/^struct/) {
>> 2398 $decl_type = 'struct';
>> 2399 } elsif ($identifier =~ m/^union/) {
>> 2400 $decl_type = 'union';
>> 2401 } elsif ($identifier =~ m/^enum/) {
>> 2402 $decl_type = 'enum';
>> 2403 } elsif ($identifier =~ m/^typedef/) {
>> 2404 $decl_type = 'typedef';
>> 2405 } else {
>> 2406 $decl_type = 'function';
>> 2407 }
>> 2408
>> 2409 if ($verbose) {
>> 2410 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
>> 2411 }
>> 2412 } else {
>> 2413 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
>> 2414 " - I thought it was a doc line\n";
>> 2415 ++$warnings;
>> 2416 $state = 0;
>> 2417 }
>> 2418 } elsif ($state == 2) { # look for head: lines, and include content
>> 2419 if (/$doc_sect/o) {
>> 2420 $newsection = $1;
>> 2421 $newcontents = $2;
>> 2422
>> 2423 if (($contents ne "") && ($contents ne "\n")) {
>> 2424 if (!$in_doc_sect && $verbose) {
>> 2425 print STDERR "Warning(${file}:$.): contents before sections\n";
>> 2426 ++$warnings;
>> 2427 }
>> 2428 dump_section($file, $section, xml_escape($contents));
>> 2429 $section = $section_default;
>> 2430 }
>> 2431
>> 2432 $in_doc_sect = 1;
>> 2433 $in_purpose = 0;
>> 2434 $contents = $newcontents;
>> 2435 if ($contents ne "") {
>> 2436 while ((substr($contents, 0, 1) eq " ") ||
>> 2437 substr($contents, 0, 1) eq "\t") {
>> 2438 $contents = substr($contents, 1);
>> 2439 }
>> 2440 $contents .= "\n";
>> 2441 }
>> 2442 $section = $newsection;
>> 2443 } elsif (/$doc_end/) {
>> 2444
>> 2445 if (($contents ne "") && ($contents ne "\n")) {
>> 2446 dump_section($file, $section, xml_escape($contents));
>> 2447 $section = $section_default;
>> 2448 $contents = "";
>> 2449 }
>> 2450 # look for doc_com + <text> + doc_end:
>> 2451 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
>> 2452 print STDERR "Warning(${file}:$.): suspicious ending line: $_";
>> 2453 ++$warnings;
>> 2454 }
>> 2455
>> 2456 $prototype = "";
>> 2457 $state = 3;
>> 2458 $brcount = 0;
>> 2459 # print STDERR "end of doc comment, looking for prototype\n";
>> 2460 } elsif (/$doc_content/) {
>> 2461 # miguel-style comment kludge, look for blank lines after
>> 2462 # @parameter line to signify start of description
>> 2463 if ($1 eq "") {
>> 2464 if ($section =~ m/^@/ || $section eq $section_context) {
>> 2465 dump_section($file, $section, xml_escape($contents));
>> 2466 $section = $section_default;
>> 2467 $contents = "";
>> 2468 } else {
>> 2469 $contents .= "\n";
>> 2470 }
>> 2471 $in_purpose = 0;
>> 2472 } elsif ($in_purpose == 1) {
>> 2473 # Continued declaration purpose
>> 2474 chomp($declaration_purpose);
>> 2475 $declaration_purpose .= " " . xml_escape($1);
>> 2476 $declaration_purpose =~ s/\s+/ /g;
>> 2477 } else {
>> 2478 $contents .= $1 . "\n";
>> 2479 }
>> 2480 } else {
>> 2481 # i dont know - bad line? ignore.
>> 2482 print STDERR "Warning(${file}:$.): bad line: $_";
>> 2483 ++$warnings;
>> 2484 }
>> 2485 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
>> 2486 if ($decl_type eq 'function') {
>> 2487 process_state3_function($_, $file);
>> 2488 } else {
>> 2489 process_state3_type($_, $file);
>> 2490 }
>> 2491 } elsif ($state == 4) {
>> 2492 # Documentation block
>> 2493 if (/$doc_block/) {
>> 2494 dump_doc_section($file, $section, xml_escape($contents));
>> 2495 $contents = "";
>> 2496 $function = "";
>> 2497 %constants = ();
>> 2498 %parameterdescs = ();
>> 2499 %parametertypes = ();
>> 2500 @parameterlist = ();
>> 2501 %sections = ();
>> 2502 @sectionlist = ();
>> 2503 $prototype = "";
>> 2504 if ( $1 eq "" ) {
>> 2505 $section = $section_intro;
>> 2506 } else {
>> 2507 $section = $1;
>> 2508 }
>> 2509 }
>> 2510 elsif (/$doc_end/)
>> 2511 {
>> 2512 dump_doc_section($file, $section, xml_escape($contents));
>> 2513 $contents = "";
>> 2514 $function = "";
>> 2515 %constants = ();
>> 2516 %parameterdescs = ();
>> 2517 %parametertypes = ();
>> 2518 @parameterlist = ();
>> 2519 %sections = ();
>> 2520 @sectionlist = ();
>> 2521 $prototype = "";
>> 2522 $state = 0;
>> 2523 }
>> 2524 elsif (/$doc_content/)
>> 2525 {
>> 2526 if ( $1 eq "" )
>> 2527 {
>> 2528 $contents .= $blankline;
>> 2529 }
>> 2530 else
>> 2531 {
>> 2532 $contents .= $1 . "\n";
>> 2533 }
>> 2534 }
>> 2535 }
>> 2536 }
>> 2537 if ($initial_section_counter == $section_counter) {
>> 2538 print STDERR "Warning(${file}): no structured comments found\n";
>> 2539 if ($output_mode eq "xml") {
>> 2540 # The template wants at least one RefEntry here; make one.
>> 2541 print "<refentry>\n";
>> 2542 print " <refnamediv>\n";
>> 2543 print " <refname>\n";
>> 2544 print " ${file}\n";
>> 2545 print " </refname>\n";
>> 2546 print " <refpurpose>\n";
>> 2547 print " Document generation inconsistency\n";
>> 2548 print " </refpurpose>\n";
>> 2549 print " </refnamediv>\n";
>> 2550 print " <refsect1>\n";
>> 2551 print " <title>\n";
>> 2552 print " Oops\n";
>> 2553 print " </title>\n";
>> 2554 print " <warning>\n";
>> 2555 print " <para>\n";
>> 2556 print " The template for this document tried to insert\n";
>> 2557 print " the structured comment from the file\n";
>> 2558 print " <filename>${file}</filename> at this point,\n";
>> 2559 print " but none was found.\n";
>> 2560 print " This dummy section is inserted to allow\n";
>> 2561 print " generation to continue.\n";
>> 2562 print " </para>\n";
>> 2563 print " </warning>\n";
>> 2564 print " </refsect1>\n";
>> 2565 print "</refentry>\n";
>> 2566 }
2371 } 2567 }
2372 close IN_FILE; <<
2373 } 2568 }
2374 2569
2375 2570
2376 if ($output_mode eq "rst") { <<
2377 get_sphinx_version() if (!$sphinx_major); <<
2378 } <<
2379 <<
2380 $kernelversion = get_kernel_version(); 2571 $kernelversion = get_kernel_version();
2381 2572
2382 # generate a sequence of code that will splic 2573 # generate a sequence of code that will splice in highlighting information
2383 # using the s// operator. 2574 # using the s// operator.
2384 for (my $k = 0; $k < @highlights; $k++) { !! 2575 foreach my $pattern (keys %highlights) {
2385 my $pattern = $highlights[$k][0]; !! 2576 # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
2386 my $result = $highlights[$k][1]; !! 2577 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
2387 # print STDERR "scanning pattern:$pattern, <<
2388 $dohighlight .= "\$contents =~ s:$patter <<
2389 } 2578 }
2390 2579
2391 # Read the file that maps relative names to a 2580 # Read the file that maps relative names to absolute names for
2392 # separate source and object directories and 2581 # separate source and object directories and for shadow trees.
2393 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { 2582 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2394 my ($relname, $absname); !! 2583 my ($relname, $absname);
2395 while(<SOURCE_MAP>) { !! 2584 while(<SOURCE_MAP>) {
2396 chop(); !! 2585 chop();
2397 ($relname, $absname) = (split())[0..1 !! 2586 ($relname, $absname) = (split())[0..1];
2398 $relname =~ s:^/+::; !! 2587 $relname =~ s:^/+::;
2399 $source_map{$relname} = $absname; !! 2588 $source_map{$relname} = $absname;
2400 } !! 2589 }
2401 close(SOURCE_MAP); !! 2590 close(SOURCE_MAP);
2402 } <<
2403 <<
2404 if ($output_selection == OUTPUT_EXPORTED || <<
2405 $output_selection == OUTPUT_INTERNAL) { <<
2406 <<
2407 push(@export_file_list, @ARGV); <<
2408 <<
2409 foreach (@export_file_list) { <<
2410 chomp; <<
2411 process_export_file($_); <<
2412 } <<
2413 } 2591 }
2414 2592
2415 foreach (@ARGV) { 2593 foreach (@ARGV) {
2416 chomp; 2594 chomp;
2417 process_file($_); 2595 process_file($_);
2418 } 2596 }
2419 if ($verbose && $errors) { 2597 if ($verbose && $errors) {
2420 print STDERR "$errors errors\n"; !! 2598 print STDERR "$errors errors\n";
2421 } 2599 }
2422 if ($verbose && $warnings) { 2600 if ($verbose && $warnings) {
2423 print STDERR "$warnings warnings\n"; !! 2601 print STDERR "$warnings warnings\n";
2424 } 2602 }
2425 2603
2426 if ($Werror && $warnings) { !! 2604 exit($errors);
2427 print STDERR "$warnings warnings as Error <<
2428 exit($warnings); <<
2429 } else { <<
2430 exit($output_mode eq "none" ? 0 : $errors <<
2431 } <<
2432 <<
2433 __END__ <<
2434 <<
2435 =head1 OPTIONS <<
2436 <<
2437 =head2 Output format selection (mutually excl <<
2438 <<
2439 =over 8 <<
2440 <<
2441 =item -man <<
2442 <<
2443 Output troff manual page format. <<
2444 <<
2445 =item -rst <<
2446 <<
2447 Output reStructuredText format. This is the d <<
2448 <<
2449 =item -none <<
2450 <<
2451 Do not output documentation, only warnings. <<
2452 <<
2453 =back <<
2454 <<
2455 =head2 Output format modifiers <<
2456 <<
2457 =head3 reStructuredText only <<
2458 <<
2459 =over 8 <<
2460 <<
2461 =item -sphinx-version VERSION <<
2462 <<
2463 Use the ReST C domain dialect compatible with <<
2464 <<
2465 If not specified, kernel-doc will auto-detect <<
2466 found on PATH. <<
2467 <<
2468 =back <<
2469 <<
2470 =head2 Output selection (mutually exclusive): <<
2471 <<
2472 =over 8 <<
2473 <<
2474 =item -export <<
2475 <<
2476 Only output documentation for the symbols tha <<
2477 EXPORT_SYMBOL() and related macros in any inp <<
2478 <<
2479 =item -internal <<
2480 <<
2481 Only output documentation for the symbols tha <<
2482 EXPORT_SYMBOL() and related macros in any inp <<
2483 <<
2484 =item -function NAME <<
2485 <<
2486 Only output documentation for the given funct <<
2487 All other functions and DOC: sections are ign <<
2488 <<
2489 May be specified multiple times. <<
2490 <<
2491 =item -nosymbol NAME <<
2492 <<
2493 Exclude the specified symbol from the output <<
2494 <<
2495 May be specified multiple times. <<
2496 <<
2497 =back <<
2498 <<
2499 =head2 Output selection modifiers: <<
2500 <<
2501 =over 8 <<
2502 <<
2503 =item -no-doc-sections <<
2504 <<
2505 Do not output DOC: sections. <<
2506 <<
2507 =item -export-file FILE <<
2508 <<
2509 Specify an additional FILE in which to look f <<
2510 <<
2511 To be used with -export or -internal. <<
2512 <<
2513 May be specified multiple times. <<
2514 <<
2515 =back <<
2516 <<
2517 =head3 reStructuredText only <<
2518 <<
2519 =over 8 <<
2520 <<
2521 =item -enable-lineno <<
2522 <<
2523 Enable output of .. LINENO lines. <<
2524 <<
2525 =back <<
2526 <<
2527 =head2 Other parameters: <<
2528 <<
2529 =over 8 <<
2530 <<
2531 =item -h, -help <<
2532 <<
2533 Print this help. <<
2534 <<
2535 =item -v <<
2536 <<
2537 Verbose output, more warnings and other infor <<
2538 <<
2539 =item -Werror <<
2540 <<
2541 Treat warnings as errors. <<
2542 <<
2543 =back <<
2544 <<
2545 =cut <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.