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