~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/scripts/kernel-doc

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /scripts/kernel-doc (Version linux-6.11.5) and /scripts/kernel-doc (Version unix-v6-master)


  1 #!/usr/bin/env perl                               
  2 # SPDX-License-Identifier: GPL-2.0                
  3 # vim: softtabstop=4                              
  4                                                   
  5 use warnings;                                     
  6 use strict;                                       
  7                                                   
  8 ## Copyright (c) 1998 Michael Zucchi, All Righ    
  9 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@red    
 10 ## Copyright (C) 2001  Simon Huggins              
 11 ## Copyright (C) 2005-2012  Randy Dunlap          
 12 ## Copyright (C) 2012  Dan Luedtke                
 13 ##                                                
 14 ## #define enhancements by Armin Kuster <akuste    
 15 ## Copyright (c) 2000 MontaVista Software, Inc    
 16 #                                                 
 17 # Copyright (C) 2022 Tomasz Warniełło (POD)     
 18                                                   
 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                                                   
 55 # more perldoc at the end of the file             
 56                                                   
 57 ## init lots of data                              
 58                                                   
 59 my $errors = 0;                                   
 60 my $warnings = 0;                                 
 61 my $anon_struct_union = 0;                        
 62                                                   
 63 # match expressions used to find embedded type    
 64 my $type_constant = '\b``([^\`]+)``\b';           
 65 my $type_constant2 = '\%([-_*\w]+)';              
 66 my $type_func = '(\w+)\(\)';                      
 67 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\    
 68 my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)    
 69 my $type_fp_param = '\@(\w+)\(\)';  # Special     
 70 my $type_fp_param2 = '\@(\w+->\S+)\(\)';  # Sp    
 71 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                                                   
 80 # Output conversion substitutions.                
 81 #  One for each output format                     
 82                                                   
 83 # these are pretty rough                          
 84 my @highlights_man = (                            
 85     [$type_constant, "\$1"],                      
 86     [$type_constant2, "\$1"],                     
 87     [$type_func, "\\\\fB\$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 = "";                           
 98                                                   
 99 # rst-mode                                        
100 my @highlights_rst = (                            
101     [$type_constant, "``\$1``"],                  
102     [$type_constant2, "``\$1``"],                 
103                                                   
104     # Note: need to escape () to avoid func ma    
105     [$type_member_func, "\\:c\\:type\\:`\$1\$2    
106     [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <    
107     [$type_fp_param, "**\$1\\\\(\\\\)**"],        
108     [$type_fp_param2, "**\$1\\\\(\\\\)**"],       
109     [$type_func, "\$1()"],                        
110     [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],    
111     [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"    
112     [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`    
113     [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"]    
114                                                   
115     # in rst this can refer to any type           
116     [$type_fallback, "\\:c\\:type\\:`\$1`"],      
117     [$type_param_ref, "**\$1\$2**"]               
118   );                                              
119 my $blankline_rst = "\n";                         
120                                                   
121 # read arguments                                  
122 if ($#ARGV == -1) {                               
123     pod2usage(                                    
124         -message => "No arguments!\n",            
125         -exitval => 1,                            
126         -verbose => 99,                           
127         -sections => 'SYNOPSIS',                  
128         -output => \*STDERR,                      
129       );                                          
130 }                                                 
131                                                   
132 my $kernelversion;                                
133 my ($sphinx_major, $sphinx_minor, $sphinx_patc    
134                                                   
135 my $dohighlight = "";                             
136                                                   
137 my $verbose = 0;                                  
138 my $Werror = 0;                                   
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;                          
145 my $enable_lineno = 0;                            
146 my @highlights = @highlights_rst;                 
147 my $blankline = $blankline_rst;                   
148 my $modulename = "Kernel API";                    
149                                                   
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'    
170                 'July', 'August', 'September',    
171                 'November', 'December')[$build    
172     " " . ($build_time[5]+1900);                  
173                                                   
174 # Essentially these are globals.                  
175 # They probably want to be tidied up, made mor    
176 # CAVEAT EMPTOR!  Some of the others I localis    
177 # could cause "use of undefined value" or othe    
178 my ($function, %function_table, %parametertype    
179 my %nosymbol_table = ();                          
180 my $declaration_start_line;                       
181 my ($type, $declaration_name, $return_type);      
182 my ($newsection, $newcontents, $prototype, $br    
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                                                   
196 # reading this variable is for backwards compa    
197 # someone was calling it with the variable fro    
198 # kernel's build system                           
199 if (defined($ENV{'KDOC_WERROR'})) {               
200     $Werror = "$ENV{'KDOC_WERROR'}";              
201 }                                                 
202 # other environment variables are converted to    
203 # arguments in cmd_checkdoc in the build syste    
204                                                   
205 # Generated docbook code is inserted in a temp    
206 # docbook v3.1 requires a non-zero sequence of    
207 # https://www.oasis-open.org/docbook/documenta    
208 # We keep track of number of generated entries    
209 # if needs be to ensure the expanded template     
210 # into html.                                      
211 my $section_counter = 0;                          
212                                                   
213 my $lineprefix="";                                
214                                                   
215 # Parser states                                   
216 use constant {                                    
217     STATE_NORMAL        => 0,        # normal     
218     STATE_NAME          => 1,        # looking    
219     STATE_BODY_MAYBE    => 2,        # body -     
220     STATE_BODY          => 3,        # the bod    
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;                                        
227 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                                                   
242 #declaration types: can be                        
243 # 'function', 'struct', 'union', 'enum', 'type    
244 my $decl_type;                                    
245                                                   
246 # Name of the kernel-doc identifier for non-DO    
247 my $identifier;                                   
248                                                   
249 my $doc_start = '^/\*\*\s*$'; # Allow whitespa    
250 my $doc_end = '\*/';                              
251 my $doc_com = '\s*\*\s*';                         
252 my $doc_com_body = '\s*\* ?';                     
253 my $doc_decl = $doc_com . '(\w+)';                
254 # @params and a strictly limited set of suppor    
255 # Specifically:                                   
256 #   Match @word:                                  
257 #         @...:                                   
258 #         @{section-name}:                        
259 # while trying to not match literal block star    
260 #                                                 
261 my $doc_sect = $doc_com .                         
262     '\s*(\@[.\w]+|\@\.\.\.|description|context    
263 my $doc_content = $doc_com_body . '(.*)';         
264 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                                                   
274 my %parameterdescs;                               
275 my %parameterdesc_start_lines;                    
276 my @parameterlist;                                
277 my %sections;                                     
278 my @sectionlist;                                  
279 my %section_start_lines;                          
280 my $sectcheck;                                    
281 my $struct_actual;                                
282                                                   
283 my $contents = "";                                
284 my $new_start_line = 0;                           
285                                                   
286 # the canonical section names. see also $doc_s    
287 my $section_default = "Description";    # defa    
288 my $section_intro = "Introduction";               
289 my $section = $section_default;                   
290 my $section_context = "Context";                  
291 my $section_return = "Return";                    
292                                                   
293 my $undescribed = "-- undescribed --";            
294                                                   
295 reset_state();                                    
296                                                   
297 while ($ARGV[0] =~ m/^--?(.*)/) {                 
298     my $cmd = $1;                                 
299     shift @ARGV;                                  
300     if ($cmd eq "man") {                          
301         $output_mode = "man";                     
302         @highlights = @highlights_man;            
303         $blankline = $blankline_man;              
304     } elsif ($cmd eq "rst") {                     
305         $output_mode = "rst";                     
306         @highlights = @highlights_rst;            
307         $blankline = $blankline_rst;              
308     } elsif ($cmd eq "none") {                    
309         $output_mode = "none";                    
310     } elsif ($cmd eq "module") { # not needed     
311         $modulename = shift @ARGV;                
312     } elsif ($cmd eq "function") { # to only o    
313         $output_selection = OUTPUT_INCLUDE;       
314         $function = shift @ARGV;                  
315         $function_table{$function} = 1;           
316     } elsif ($cmd eq "nosymbol") { # Exclude s    
317         my $symbol = shift @ARGV;                 
318         $nosymbol_table{$symbol} = 1;             
319     } elsif ($cmd eq "export") { # only export    
320         $output_selection = OUTPUT_EXPORTED;      
321         %function_table = ();                     
322     } elsif ($cmd eq "internal") { # only non-    
323         $output_selection = OUTPUT_INTERNAL;      
324         %function_table = ();                     
325     } elsif ($cmd eq "export-file") {             
326         my $file = shift @ARGV;                   
327         push(@export_file_list, $file);           
328     } elsif ($cmd eq "v") {                       
329         $verbose = 1;                             
330     } elsif ($cmd eq "Werror") {                  
331         $Werror = 1;                              
332     } elsif ($cmd eq "Wreturn") {                 
333         $Wreturn = 1;                             
334     } elsif ($cmd eq "Wshort-desc" or $cmd eq     
335         $Wshort_desc = 1;                         
336     } elsif ($cmd eq "Wcontents-before-section    
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     }                                             
386 }                                                 
387                                                   
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                     
436 sub get_kernel_version() {                        
437     my $version = 'unknown kernel version';       
438                                                   
439     if (defined($ENV{'KERNELVERSION'})) {         
440         $version = $ENV{'KERNELVERSION'};         
441     }                                             
442     return $version;                              
443 }                                                 
444                                                   
445 #                                                 
446 sub print_lineno {                                
447     my $lineno = shift;                           
448     if ($enable_lineno && defined($lineno)) {     
449         print ".. LINENO " . $lineno . "\n";      
450     }                                             
451 }                                                 
452                                                   
453 sub emit_warning {                                
454     my $location = shift;                         
455     my $msg = shift;                              
456     print STDERR "$location: warning: $msg";      
457     ++$warnings;                                  
458 }                                                 
459 ##                                                
460 # dumps section contents to arrays/hashes inte    
461 #                                                 
462 sub dump_section {                                
463     my $file = shift;                             
464     my $name = shift;                             
465     my $contents = join "\n", @_;                 
466                                                   
467     if ($name =~ m/$type_param/) {                
468         $name = $1;                               
469         $parameterdescs{$name} = $contents;       
470         $sectcheck = $sectcheck . $name . " ";    
471         $parameterdesc_start_lines{$name} = $n    
472         $new_start_line = 0;                      
473     } elsif ($name eq "@\.\.\.") {                
474         $name = "...";                            
475         $parameterdescs{$name} = $contents;       
476         $sectcheck = $sectcheck . $name . " ";    
477         $parameterdesc_start_lines{$name} = $n    
478         $new_start_line = 0;                      
479     } else {                                      
480         if (defined($sections{$name}) && ($sec    
481             # Only warn on user specified dupl    
482             if ($name ne $section_default) {      
483                 emit_warning("${file}:$.", "du    
484             }                                     
485             $sections{$name} .= $contents;        
486         } else {                                  
487             $sections{$name} = $contents;         
488             push @sectionlist, $name;             
489             $section_start_lines{$name} = $new    
490             $new_start_line = 0;                  
491         }                                         
492     }                                             
493 }                                                 
494                                                   
495 ##                                                
496 # dump DOC: section after checking that it sho    
497 #                                                 
498 sub dump_doc_section {                            
499     my $file = shift;                             
500     my $name = shift;                             
501     my $contents = join "\n", @_;                 
502                                                   
503     if ($no_doc_sections) {                       
504         return;                                   
505     }                                             
506                                                   
507     return if (defined($nosymbol_table{$name})    
508                                                   
509     if (($output_selection == OUTPUT_ALL) ||      
510         (($output_selection == OUTPUT_INCLUDE)    
511          defined($function_table{$name})))        
512     {                                             
513         dump_section($file, $name, $contents);    
514         output_blockhead({'sectionlist' => \@s    
515                           'sections' => \%sect    
516                           'module' => $modulen    
517                           'content-only' => ($    
518     }                                             
519 }                                                 
520                                                   
521 ##                                                
522 # output function                                 
523 #                                                 
524 # parameterdescs, a hash.                         
525 #  function => "function name"                    
526 #  parameterlist => @list of parameters           
527 #  parameterdescs => %parameter descriptions      
528 #  sectionlist => @list of sections               
529 #  sections => %section descriptions              
530 #                                                 
531                                                   
532 sub output_highlight {                            
533     my $contents = join "\n",@_;                  
534     my $line;                                     
535                                                   
536 #   DEBUG                                         
537 #   if (!defined $contents) {                     
538 #       use Carp;                                 
539 #       confess "output_highlight got called w    
540 #   }                                             
541                                                   
542 #   print STDERR "contents b4:$contents\n";       
543     eval $dohighlight;                            
544     die $@ if $@;                                 
545 #   print STDERR "contents af:$contents\n";       
546                                                   
547     foreach $line (split "\n", $contents) {       
548         if (! $output_preformatted) {             
549             $line =~ s/^\s*//;                    
550         }                                         
551         if ($line eq ""){                         
552             if (! $output_preformatted) {         
553                 print $lineprefix, $blankline;    
554             }                                     
555         } else {                                  
556             if ($output_mode eq "man" && subst    
557                 print "\\&$line";                 
558             } else {                              
559                 print $lineprefix, $line;         
560             }                                     
561         }                                         
562         print "\n";                               
563     }                                             
564 }                                                 
565                                                   
566 ##                                                
567 # output function in man                          
568 sub output_function_man(%) {                      
569     my %args = %{$_[0]};                          
570     my ($parameter, $section);                    
571     my $count;                                    
572                                                   
573     print ".TH \"$args{'function'}\" 9 \"$args    
574                                                   
575     print ".SH NAME\n";                           
576     print $args{'function'} . " \\- " . $args{    
577                                                   
578     print ".SH SYNOPSIS\n";                       
579     if ($args{'functiontype'} ne "") {            
580         print ".B \"" . $args{'functiontype'}     
581     } else {                                      
582         print ".B \"" . $args{'function'} . "\    
583     }                                             
584     $count = 0;                                   
585     my $parenth = "(";                            
586     my $post = ",";                               
587     foreach my $parameter (@{$args{'parameterl    
588         if ($count == $#{$args{'parameterlist'    
589             $post = ");";                         
590         }                                         
591         $type = $args{'parametertypes'}{$param    
592         if ($type =~ m/$function_pointer/) {      
593             # pointer-to-function                 
594             print ".BI \"" . $parenth . $1 . "    
595         } else {                                  
596             $type =~ s/([^\*])$/$1 /;             
597             print ".BI \"" . $parenth . $type     
598         }                                         
599         $count++;                                 
600         $parenth = "";                            
601     }                                             
602                                                   
603     print ".SH ARGUMENTS\n";                      
604     foreach $parameter (@{$args{'parameterlist    
605         my $parameter_name = $parameter;          
606         $parameter_name =~ s/\[.*//;              
607                                                   
608         print ".IP \"" . $parameter . "\" 12\n    
609         output_highlight($args{'parameterdescs    
610     }                                             
611     foreach $section (@{$args{'sectionlist'}})    
612         print ".SH \"", uc $section, "\"\n";      
613         output_highlight($args{'sections'}{$se    
614     }                                             
615 }                                                 
616                                                   
617 ##                                                
618 # output enum in man                              
619 sub output_enum_man(%) {                          
620     my %args = %{$_[0]};                          
621     my ($parameter, $section);                    
622     my $count;                                    
623                                                   
624     print ".TH \"$args{'module'}\" 9 \"enum $a    
625                                                   
626     print ".SH NAME\n";                           
627     print "enum " . $args{'enum'} . " \\- " .     
628                                                   
629     print ".SH SYNOPSIS\n";                       
630     print "enum " . $args{'enum'} . " {\n";       
631     $count = 0;                                   
632     foreach my $parameter (@{$args{'parameterl    
633         print ".br\n.BI \"    $parameter\"\n";    
634         if ($count == $#{$args{'parameterlist'    
635             print "\n};\n";                       
636             last;                                 
637         } else {                                  
638             print ", \n.br\n";                    
639         }                                         
640         $count++;                                 
641     }                                             
642                                                   
643     print ".SH Constants\n";                      
644     foreach $parameter (@{$args{'parameterlist    
645         my $parameter_name = $parameter;          
646         $parameter_name =~ s/\[.*//;              
647                                                   
648         print ".IP \"" . $parameter . "\" 12\n    
649         output_highlight($args{'parameterdescs    
650     }                                             
651     foreach $section (@{$args{'sectionlist'}})    
652         print ".SH \"$section\"\n";               
653         output_highlight($args{'sections'}{$se    
654     }                                             
655 }                                                 
656                                                   
657 ##                                                
658 # output struct in man                            
659 sub output_struct_man(%) {                        
660     my %args = %{$_[0]};                          
661     my ($parameter, $section);                    
662                                                   
663     print ".TH \"$args{'module'}\" 9 \"" . $ar    
664                                                   
665     print ".SH NAME\n";                           
666     print $args{'type'} . " " . $args{'struct'    
667                                                   
668     my $declaration = $args{'definition'};        
669     $declaration =~ s/\t/  /g;                    
670     $declaration =~ s/\n/"\n.br\n.BI \"/g;        
671     print ".SH SYNOPSIS\n";                       
672     print $args{'type'} . " " . $args{'struct'    
673     print ".BI \"$declaration\n};\n.br\n\n";      
674                                                   
675     print ".SH Members\n";                        
676     foreach $parameter (@{$args{'parameterlist    
677         ($parameter =~ /^#/) && next;             
678                                                   
679         my $parameter_name = $parameter;          
680         $parameter_name =~ s/\[.*//;              
681                                                   
682         ($args{'parameterdescs'}{$parameter_na    
683         print ".IP \"" . $parameter . "\" 12\n    
684         output_highlight($args{'parameterdescs    
685     }                                             
686     foreach $section (@{$args{'sectionlist'}})    
687         print ".SH \"$section\"\n";               
688         output_highlight($args{'sections'}{$se    
689     }                                             
690 }                                                 
691                                                   
692 ##                                                
693 # output typedef in man                           
694 sub output_typedef_man(%) {                       
695     my %args = %{$_[0]};                          
696     my ($parameter, $section);                    
697                                                   
698     print ".TH \"$args{'module'}\" 9 \"$args{'    
699                                                   
700     print ".SH NAME\n";                           
701     print "typedef " . $args{'typedef'} . " \\    
702                                                   
703     foreach $section (@{$args{'sectionlist'}})    
704         print ".SH \"$section\"\n";               
705         output_highlight($args{'sections'}{$se    
706     }                                             
707 }                                                 
708                                                   
709 sub output_blockhead_man(%) {                     
710     my %args = %{$_[0]};                          
711     my ($parameter, $section);                    
712     my $count;                                    
713                                                   
714     print ".TH \"$args{'module'}\" 9 \"$args{'    
715                                                   
716     foreach $section (@{$args{'sectionlist'}})    
717         print ".SH \"$section\"\n";               
718         output_highlight($args{'sections'}{$se    
719     }                                             
720 }                                                 
721                                                   
722 ##                                                
723 # output in restructured text                     
724 #                                                 
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]};                          
733     my ($parameter, $section);                    
734                                                   
735     foreach $section (@{$args{'sectionlist'}})    
736         next if (defined($nosymbol_table{$sect    
737                                                   
738         if ($output_selection != OUTPUT_INCLUD    
739             print ".. _$section:\n\n";            
740             print "**$section**\n\n";             
741         }                                         
742         print_lineno($section_start_lines{$sec    
743         output_highlight_rst($args{'sections'}    
744         print "\n";                               
745     }                                             
746 }                                                 
747                                                   
748 #                                                 
749 # Apply the RST highlights to a sub-block of t    
750 #                                                 
751 sub highlight_block($) {                          
752     # The dohighlight kludge requires the text    
753     my $contents = shift;                         
754     eval $dohighlight;                            
755     die $@ if $@;                                 
756     return $contents;                             
757 }                                                 
758                                                   
759 #                                                 
760 # Regexes used only here.                         
761 #                                                 
762 my $sphinx_literal = '^[^.].*::$';                
763 my $sphinx_cblock = '^\.\.\ +code-block::';       
764                                                   
765 sub output_highlight_rst {                        
766     my $input = join "\n",@_;                     
767     my $output = "";                              
768     my $line;                                     
769     my $in_literal = 0;                           
770     my $litprefix;                                
771     my $block = "";                               
772                                                   
773     foreach $line (split "\n",$input) {           
774         #                                         
775         # If we're in a literal block, see if     
776         # of it.  Otherwise pass the line stra    
777         #                                         
778         if ($in_literal) {                        
779             if (! ($line =~ /^\s*$/)) {           
780                 #                                 
781                 # If this is the first non-bla    
782                 # block we need to figure out     
783                 #                                 
784                 if ($litprefix eq "") {           
785                     $line =~ /^(\s*)/;            
786                     $litprefix = '^' . $1;        
787                     $output .= $line . "\n";      
788                 } elsif (! ($line =~ /$litpref    
789                     $in_literal = 0;              
790                 } else {                          
791                     $output .= $line . "\n";      
792                 }                                 
793             } else {                              
794                 $output .= $line . "\n";          
795             }                                     
796         }                                         
797         #                                         
798         # Not in a literal block (or just drop    
799         #                                         
800         if (! $in_literal) {                      
801             $block .= $line . "\n";               
802             if (($line =~ /$sphinx_literal/) |    
803                 $in_literal = 1;                  
804                 $litprefix = "";                  
805                 $output .= highlight_block($bl    
806                 $block = ""                       
807             }                                     
808         }                                         
809     }                                             
810                                                   
811     if ($block) {                                 
812         $output .= highlight_block($block);       
813     }                                             
814     foreach $line (split "\n", $output) {         
815         print $lineprefix . $line . "\n";         
816     }                                             
817 }                                                 
818                                                   
819 sub output_function_rst(%) {                      
820     my %args = %{$_[0]};                          
821     my ($parameter, $section);                    
822     my $oldprefix = $lineprefix;                  
823                                                   
824     my $signature = "";                           
825     if ($args{'functiontype'} ne "") {            
826         $signature = $args{'functiontype'} . "    
827     } else {                                      
828         $signature = $args{'function'} . " (";    
829     }                                             
830                                                   
831     my $count = 0;                                
832     foreach my $parameter (@{$args{'parameterl    
833         if ($count ne 0) {                        
834             $signature .= ", ";                   
835         }                                         
836         $count++;                                 
837         $type = $args{'parametertypes'}{$param    
838                                                   
839         if ($type =~ m/$function_pointer/) {      
840             # pointer-to-function                 
841             $signature .= $1 . $parameter . ")    
842         } else {                                  
843             $signature .= $type;                  
844         }                                         
845     }                                             
846                                                   
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     }                                             
886                                                   
887     #                                             
888     # Put our descriptive text into a containe    
889     # set the function prototypes apart.          
890     #                                             
891     print ".. container:: kernelindent\n\n";      
892     $lineprefix = "  ";                           
893     print $lineprefix . "**Parameters**\n\n";     
894     foreach $parameter (@{$args{'parameterlist    
895         my $parameter_name = $parameter;          
896         $parameter_name =~ s/\[.*//;              
897         $type = $args{'parametertypes'}{$param    
898                                                   
899         if ($type ne "") {                        
900             print $lineprefix . "``$type``\n";    
901         } else {                                  
902             print $lineprefix . "``$parameter`    
903         }                                         
904                                                   
905         print_lineno($parameterdesc_start_line    
906                                                   
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                                                   
918     output_section_rst(@_);                       
919     $lineprefix = $oldprefix;                     
920 }                                                 
921                                                   
922 sub output_section_rst(%) {                       
923     my %args = %{$_[0]};                          
924     my $section;                                  
925     my $oldprefix = $lineprefix;                  
926                                                   
927     foreach $section (@{$args{'sectionlist'}})    
928         print $lineprefix . "**$section**\n\n"    
929         print_lineno($section_start_lines{$sec    
930         output_highlight_rst($args{'sections'}    
931         print "\n";                               
932     }                                             
933     print "\n";                                   
934 }                                                 
935                                                   
936 sub output_enum_rst(%) {                          
937     my %args = %{$_[0]};                          
938     my ($parameter);                              
939     my $oldprefix = $lineprefix;                  
940     my $count;                                    
941     my $outer;                                    
942                                                   
943     if ($sphinx_major < 3) {                      
944         my $name = "enum " . $args{'enum'};       
945         print "\n\n.. c:type:: " . $name . "\n    
946     } else {                                      
947         my $name = $args{'enum'};                 
948         print "\n\n.. c:enum:: " . $name . "\n    
949     }                                             
950     print_lineno($declaration_start_line);        
951     $lineprefix = "  ";                           
952     output_highlight_rst($args{'purpose'});       
953     print "\n";                                   
954                                                   
955     print ".. container:: kernelindent\n\n";      
956     $outer = $lineprefix . "  ";                  
957     $lineprefix = $outer . "  ";                  
958     print $outer . "**Constants**\n\n";           
959     foreach $parameter (@{$args{'parameterlist    
960         print $outer . "``$parameter``\n";        
961                                                   
962         if ($args{'parameterdescs'}{$parameter    
963             output_highlight_rst($args{'parame    
964         } else {                                  
965             print $lineprefix . "*undescribed*    
966         }                                         
967         print "\n";                               
968     }                                             
969     print "\n";                                   
970     $lineprefix = $oldprefix;                     
971     output_section_rst(@_);                       
972 }                                                 
973                                                   
974 sub output_typedef_rst(%) {                       
975     my %args = %{$_[0]};                          
976     my ($parameter);                              
977     my $oldprefix = $lineprefix;                  
978     my $name;                                     
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                                                   
991     $lineprefix = $oldprefix;                     
992     output_section_rst(@_);                       
993 }                                                 
994                                                   
995 sub output_struct_rst(%) {                        
996     my %args = %{$_[0]};                          
997     my ($parameter);                              
998     my $oldprefix = $lineprefix;                  
999                                                   
1000     if ($sphinx_major < 3) {                     
1001         my $name = $args{'type'} . " " . $arg    
1002         print "\n\n.. c:type:: " . $name . "\    
1003     } else {                                     
1004         my $name = $args{'struct'};              
1005         if ($args{'type'} eq 'union') {          
1006             print "\n\n.. c:union:: " . $name    
1007         } else {                                 
1008             print "\n\n.. c:struct:: " . $nam    
1009         }                                        
1010     }                                            
1011     print_lineno($declaration_start_line);       
1012     $lineprefix = "  ";                          
1013     output_highlight_rst($args{'purpose'});      
1014     print "\n";                                  
1015                                                  
1016     print ".. container:: kernelindent\n\n";     
1017     print $lineprefix . "**Definition**::\n\n    
1018     my $declaration = $args{'definition'};       
1019     $lineprefix = $lineprefix . "  ";            
1020     $declaration =~ s/\t/$lineprefix/g;          
1021     print $lineprefix . $args{'type'} . " " .    
1022                                                  
1023     $lineprefix = "  ";                          
1024     print $lineprefix . "**Members**\n\n";       
1025     foreach $parameter (@{$args{'parameterlis    
1026         ($parameter =~ /^#/) && next;            
1027                                                  
1028         my $parameter_name = $parameter;         
1029         $parameter_name =~ s/\[.*//;             
1030                                                  
1031         ($args{'parameterdescs'}{$parameter_n    
1032         $type = $args{'parametertypes'}{$para    
1033         print_lineno($parameterdesc_start_lin    
1034         print $lineprefix . "``" . $parameter    
1035         $lineprefix = "    ";                    
1036         output_highlight_rst($args{'parameter    
1037         $lineprefix = "  ";                      
1038         print "\n";                              
1039     }                                            
1040     print "\n";                                  
1041                                                  
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 }                                                
1053                                                  
1054 sub output_typedef_none(%) {                     
1055 }                                                
1056                                                  
1057 sub output_struct_none(%) {                      
1058 }                                                
1059                                                  
1060 sub output_blockhead_none(%) {                   
1061 }                                                
1062                                                  
1063 ##                                               
1064 # generic output function for all types (func    
1065 # calls the generated, variable output_ funct    
1066 # functype and output_mode                       
1067 sub output_declaration {                         
1068     no strict 'refs';                            
1069     my $name = shift;                            
1070     my $functype = shift;                        
1071     my $func = "output_${functype}_$output_mo    
1072                                                  
1073     return if (defined($nosymbol_table{$name}    
1074                                                  
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     {                                            
1082         &$func(@_);                              
1083         $section_counter++;                      
1084     }                                            
1085 }                                                
1086                                                  
1087 ##                                               
1088 # generic output function - calls the right o    
1089 sub output_blockhead {                           
1090     no strict 'refs';                            
1091     my $func = "output_blockhead_" . $output_    
1092     &$func(@_);                                  
1093     $section_counter++;                          
1094 }                                                
1095                                                  
1096 ##                                               
1097 # takes a declaration (struct, union, enum, t    
1098 # invokes the right handler. NOT called for f    
1099 sub dump_declaration($$) {                       
1100     no strict 'refs';                            
1101     my ($prototype, $file) = @_;                 
1102     my $func = "dump_" . $decl_type;             
1103     &$func(@_);                                  
1104 }                                                
1105                                                  
1106 sub dump_union($$) {                             
1107     dump_struct(@_);                             
1108 }                                                
1109                                                  
1110 sub dump_struct($$) {                            
1111     my $x = shift;                               
1112     my $file = shift;                            
1113     my $decl_type;                               
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                                                  
1289                                                  
1290 sub show_warnings($$) {                          
1291     my $functype = shift;                        
1292     my $name = shift;                            
1293                                                  
1294     return 0 if (defined($nosymbol_table{$nam    
1295                                                  
1296     return 1 if ($output_selection == OUTPUT_    
1297                                                  
1298     if ($output_selection == OUTPUT_EXPORTED)    
1299         if (defined($function_table{$name}))     
1300             return 1;                            
1301         } else {                                 
1302             return 0;                            
1303         }                                        
1304     }                                            
1305     if ($output_selection == OUTPUT_INTERNAL)    
1306         if (!($functype eq "function" && defi    
1307             return 1;                            
1308         } else {                                 
1309             return 0;                            
1310         }                                        
1311     }                                            
1312     if ($output_selection == OUTPUT_INCLUDE)     
1313         if (defined($function_table{$name}))     
1314             return 1;                            
1315         } else {                                 
1316             return 0;                            
1317         }                                        
1318     }                                            
1319     die("Please add the new output type at sh    
1320 }                                                
1321                                                  
1322 sub dump_enum($$) {                              
1323     my $x = shift;                               
1324     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                                                  
1331     $x =~ s@/\*.*?\*/@@gos;     # strip comme    
1332     # strip #define macros inside enums          
1333     $x =~ s@#\s*((define|ifdef|if)\s+|endif)[    
1334                                                  
1335     if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\    
1336         $declaration_name = $2;                  
1337         $members = $1;                           
1338     } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/)    
1339         $declaration_name = $1;                  
1340         $members = $2;                           
1341     }                                            
1342                                                  
1343     if ($members) {                              
1344         if ($identifier ne $declaration_name)    
1345             if ($identifier eq "") {             
1346                 emit_warning("${file}:$.", "w    
1347             } else {                             
1348                 emit_warning("${file}:$.", "e    
1349             }                                    
1350             return;                              
1351         }                                        
1352         $declaration_name = "(anonymous)" if     
1353                                                  
1354         my %_members;                            
1355                                                  
1356         $members =~ s/\s+$//;                    
1357         $members =~ s/\([^;]*?[\)]//g;           
1358                                                  
1359         foreach my $arg (split ',', $members)    
1360             $arg =~ s/^\s*(\w+).*/$1/;           
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     }                                            
1393 }                                                
1394                                                  
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($$) {                           
1403     my $x = shift;                               
1404     my $file = shift;                            
1405                                                  
1406     $x =~ s@/\*.*?\*/@@gos;     # strip comme    
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 =~ /\    
1439         $x =~ s/\(*.\)\s*;$/;/;                  
1440         $x =~ s/\[*.\]\s*;$/;/;                  
1441     }                                            
1442                                                  
1443     if ($x =~ /typedef.*\s+(\w+)\s*;/) {         
1444         $declaration_name = $1;                  
1445                                                  
1446         if ($identifier ne $declaration_name)    
1447             emit_warning("${file}:$.", "expec    
1448             return;                              
1449         }                                        
1450                                                  
1451         output_declaration($declaration_name,    
1452                            'typedef',            
1453                            {'typedef' => $dec    
1454                             'module' => $modu    
1455                             'sectionlist' =>     
1456                             'sections' => \%s    
1457                             'purpose' => $dec    
1458                            });                   
1459     } else {                                     
1460         print STDERR "${file}:$.: error: Cann    
1461         ++$errors;                               
1462     }                                            
1463 }                                                
1464                                                  
1465 sub save_struct_actual($) {                      
1466     my $actual = shift;                          
1467                                                  
1468     # strip all spaces from the actual param     
1469     $actual =~ s/\s*//g;                         
1470     $struct_actual = $struct_actual . $actual    
1471 }                                                
1472                                                  
1473 sub create_parameterlist($$$$) {                 
1474     my $args = shift;                            
1475     my $splitter = shift;                        
1476     my $file = shift;                            
1477     my $declaration_name = shift;                
1478     my $type;                                    
1479     my $param;                                   
1480                                                  
1481     # temporarily replace commas inside funct    
1482     my $arg_expr = qr{\([^\),]+};                
1483     while ($args =~ /$arg_expr,/) {              
1484         $args =~ s/($arg_expr),/$1#/g;           
1485     }                                            
1486                                                  
1487     foreach my $arg (split($splitter, $args))    
1488         # strip comments                         
1489         $arg =~ s/\/\*.*\*\///;                  
1490         # ignore argument attributes             
1491         $arg =~ s/\sPOS0?\s/ /;                  
1492         # strip leading/trailing spaces          
1493         $arg =~ s/^\s*//;                        
1494         $arg =~ s/\s*$//;                        
1495         $arg =~ s/\s+/ /;                        
1496                                                  
1497         if ($arg =~ /^#/) {                      
1498             # Treat preprocessor directive as    
1499             # corresponding data structures "    
1500             # output_* subs.                     
1501             push_parameter($arg, "", "", $fil    
1502         } elsif ($arg =~ m/\(.+\)\s*\(/) {       
1503             # pointer-to-function                
1504             $arg =~ tr/#/,/;                     
1505             $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\    
1506             $param = $1;                         
1507             $type = $arg;                        
1508             $type =~ s/([^\(]+\(\*?)\s*$param    
1509             save_struct_actual($param);          
1510             push_parameter($param, $type, $ar    
1511         } elsif ($arg =~ m/\(.+\)\s*\[/) {       
1512             # array-of-pointers                  
1513             $arg =~ tr/#/,/;                     
1514             $arg =~ m/[^\(]+\(\s*\*\s*([\w\[\    
1515             $param = $1;                         
1516             $type = $arg;                        
1517             $type =~ s/([^\(]+\(\*?)\s*$param    
1518             save_struct_actual($param);          
1519             push_parameter($param, $type, $ar    
1520         } elsif ($arg) {                         
1521             $arg =~ s/\s*:\s*/:/g;               
1522             $arg =~ s/\s*\[/\[/g;                
1523                                                  
1524             my @args = split('\s*,\s*', $arg)    
1525             if ($args[0] =~ m/\*/) {             
1526                 $args[0] =~ s/(\*+)\s*/ $1/;     
1527             }                                    
1528                                                  
1529             my @first_arg;                       
1530             if ($args[0] =~ /^(.*\s+)(.*?\[.*    
1531                 shift @args;                     
1532                 push(@first_arg, split('\s+',    
1533                 push(@first_arg, $2);            
1534             } else {                             
1535                 @first_arg = split('\s+', shi    
1536             }                                    
1537                                                  
1538             unshift(@args, pop @first_arg);      
1539             $type = join " ", @first_arg;        
1540                                                  
1541             foreach $param (@args) {             
1542                 if ($param =~ m/^(\*+)\s*(.*)    
1543                     save_struct_actual($2);      
1544                                                  
1545                     push_parameter($2, "$type    
1546                 } elsif ($param =~ m/(.*?):(\    
1547                     if ($type ne "") { # skip    
1548                         save_struct_actual($1    
1549                         push_parameter($1, "$    
1550                     }                            
1551                 } else {                         
1552                     save_struct_actual($param    
1553                     push_parameter($param, $t    
1554                 }                                
1555             }                                    
1556         }                                        
1557     }                                            
1558 }                                                
1559                                                  
1560 sub push_parameter($$$$$) {                      
1561     my $param = shift;                           
1562     my $type = shift;                            
1563     my $org_arg = shift;                         
1564     my $file = shift;                            
1565     my $declaration_name = shift;                
1566                                                  
1567     if (($anon_struct_union == 1) && ($type e    
1568         ($param eq "}")) {                       
1569         return;        # ignore the ending };    
1570     }                                            
1571                                                  
1572     $anon_struct_union = 0;                      
1573     $param =~ s/[\[\)].*//;                      
1574                                                  
1575     if ($type eq "" && $param =~ /\.\.\.$/)      
1576     {                                            
1577         if (!$param =~ /\w\.\.\.$/) {            
1578             # handles unnamed variable parame    
1579             $param = "...";                      
1580         } elsif ($param =~ /\w\.\.\.$/) {        
1581             # for named variable parameters o    
1582             $param =~ s/\.\.\.$//;               
1583         }                                        
1584         if (!defined $parameterdescs{$param}     
1585             $parameterdescs{$param} = "variab    
1586         }                                        
1587     }                                            
1588     elsif ($type eq "" && ($param eq "" or $p    
1589     {                                            
1590         $param="void";                           
1591         $parameterdescs{void} = "no arguments    
1592     }                                            
1593     elsif ($type eq "" && ($param eq "struct"    
1594     # handle unnamed (anonymous) union or str    
1595     {                                            
1596         $type = $param;                          
1597         $param = "{unnamed_" . $param . "}";     
1598         $parameterdescs{$param} = "anonymous\    
1599         $anon_struct_union = 1;                  
1600     }                                            
1601     elsif ($param =~ "__cacheline_group" )       
1602     # handle cache group enforcing variables:    
1603     {                                            
1604         return; # ignore __cacheline_group_be    
1605     }                                            
1606                                                  
1607     # warn if parameter has no description       
1608     # (but ignore ones starting with # as the    
1609     # but inline preprocessor statements);       
1610     # Note: It will also ignore void params a    
1611     if (!defined $parameterdescs{$param} && $    
1612         $parameterdescs{$param} = $undescribe    
1613                                                  
1614         if (show_warnings($type, $declaration    
1615             emit_warning("${file}:$.", "Funct    
1616         }                                        
1617     }                                            
1618                                                  
1619     # strip spaces from $param so that it is     
1620     # on @parameterlist;                         
1621     # this fixes a problem where check_sectio    
1622     # a parameter like "addr[6 + 2]" because     
1623     # as "addr[6", "+", "2]" on the parameter    
1624     # but it's better to maintain the param s    
1625     # so just weaken the string compare in ch    
1626     # "[blah" in a parameter string;             
1627     ###$param =~ s/\s*//g;                       
1628     push @parameterlist, $param;                 
1629     $org_arg =~ s/\s\s+/ /g;                     
1630     $parametertypes{$param} = $org_arg;          
1631 }                                                
1632                                                  
1633 sub check_sections($$$$$) {                      
1634     my ($file, $decl_name, $decl_type, $sectc    
1635     my @sects = split ' ', $sectcheck;           
1636     my @prms = split ' ', $prmscheck;            
1637     my $err;                                     
1638     my ($px, $sx);                               
1639     my $prm_clean;        # strip trailing "[    
1640                                                  
1641     foreach $sx (0 .. $#sects) {                 
1642         $err = 1;                                
1643         foreach $px (0 .. $#prms) {              
1644             $prm_clean = $prms[$px];             
1645             $prm_clean =~ s/\[.*\]//;            
1646             $prm_clean =~ s/$attribute//i;       
1647             # ignore array size in a paramete    
1648             # however, the original param str    
1649             # spaces, e.g.:  addr[6 + 2]         
1650             # and this appears in @prms as "a    
1651             # parameter list is split at spac    
1652             # hence just ignore "[..." for th    
1653             $prm_clean =~ s/\[.*//;              
1654                                                  
1655             ##$prm_clean =~ s/^\**//;            
1656             if ($prm_clean eq $sects[$sx]) {     
1657                 $err = 0;                        
1658                 last;                            
1659             }                                    
1660         }                                        
1661         if ($err) {                              
1662             if ($decl_type eq "function") {      
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 }                                                
1699                                                  
1700 ##                                               
1701 # takes a function prototype and the name of     
1702 # processed and spits out all the details sto    
1703 # arrays/hashes.                                 
1704 sub dump_function($$) {                          
1705     my $prototype = shift;                       
1706     my $file = shift;                            
1707     my $noret = 0;                               
1708                                                  
1709     print_lineno($new_start_line);               
1710                                                  
1711     $prototype =~ s/^static +//;                 
1712     $prototype =~ s/^extern +//;                 
1713     $prototype =~ s/^asmlinkage +//;             
1714     $prototype =~ s/^inline +//;                 
1715     $prototype =~ s/^__inline__ +//;             
1716     $prototype =~ s/^__inline +//;               
1717     $prototype =~ s/^__always_inline +//;        
1718     $prototype =~ s/^noinline +//;               
1719     $prototype =~ s/^__FORTIFY_INLINE +//;       
1720     $prototype =~ s/__init +//;                  
1721     $prototype =~ s/__init_or_module +//;        
1722     $prototype =~ s/__deprecated +//;            
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                                                  
1743     # Yes, this truly is vile.  We are lookin    
1744     # 1. Return type (may be nothing if we're    
1745     # 2. Function name                           
1746     # 3. Function parameters.                    
1747     #                                            
1748     # All the while we have to watch out for     
1749     # (which IIRC is what the two sections ar    
1750     # regexps don't even start to express all    
1751     # so on.                                     
1752     #                                            
1753     # If you mess with these regexps, it's a     
1754     # the following functions' documentation     
1755     # - parport_register_device (function poi    
1756     # - atomic_set (macro)                       
1757     # - pci_match_device, __copy_to_user (lon    
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                                                  
1780         create_parameterlist($args, ',', $fil    
1781     } else {                                     
1782         emit_warning("${file}:$.", "cannot un    
1783         return;                                  
1784     }                                            
1785                                                  
1786     if ($identifier ne $declaration_name) {      
1787         emit_warning("${file}:$.", "expecting    
1788         return;                                  
1789     }                                            
1790                                                  
1791     my $prms = join " ", @parameterlist;         
1792     check_sections($file, $declaration_name,     
1793                                                  
1794     # This check emits a lot of warnings at t    
1795     # functions don't have a 'Return' doc sec    
1796     # of warnings goes sufficiently down, the    
1797     # -Wreturn mode.                             
1798     # TODO: always perform the check.            
1799     if ($Wreturn && !$noret) {                   
1800         check_return_section($file, $declarat    
1801     }                                            
1802                                                  
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 }                                                
1834                                                  
1835 sub reset_state {                                
1836     $function = "";                              
1837     %parameterdescs = ();                        
1838     %parametertypes = ();                        
1839     @parameterlist = ();                         
1840     %sections = ();                              
1841     @sectionlist = ();                           
1842     $sectcheck = "";                             
1843     $struct_actual = "";                         
1844     $prototype = "";                             
1845                                                  
1846     $state = STATE_NORMAL;                       
1847     $inline_doc_state = STATE_INLINE_NA;         
1848 }                                                
1849                                                  
1850 sub tracepoint_munge($) {                        
1851     my $file = shift;                            
1852     my $tracepointname = 0;                      
1853     my $tracepointargs = 0;                      
1854                                                  
1855     if ($prototype =~ m/TRACE_EVENT\((.*?),/)    
1856         $tracepointname = $1;                    
1857     }                                            
1858     if ($prototype =~ m/DEFINE_SINGLE_EVENT\(    
1859         $tracepointname = $1;                    
1860     }                                            
1861     if ($prototype =~ m/DEFINE_EVENT\((.*?),(    
1862         $tracepointname = $2;                    
1863     }                                            
1864     $tracepointname =~ s/^\s+//; #strip leadi    
1865     if ($prototype =~ m/TP_PROTO\((.*?)\)/) {    
1866         $tracepointargs = $1;                    
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 }                                                
1876                                                  
1877 sub syscall_munge() {                            
1878     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                                                  
1894     # now delete all of the odd-number commas    
1895     # so that arg types & arg names don't hav    
1896     my $count = 0;                               
1897     my $len = length($prototype);                
1898     if ($void) {                                 
1899         $len = 0;    # skip the for-loop         
1900     }                                            
1901     for (my $ix = 0; $ix < $len; $ix++) {        
1902         if (substr($prototype, $ix, 1) eq ','    
1903             $count++;                            
1904             if ($count % 2 == 1) {               
1905                 substr($prototype, $ix, 1) =     
1906             }                                    
1907         }                                        
1908     }                                            
1909 }                                                
1910                                                  
1911 sub process_proto_function($$) {                 
1912     my $x = shift;                               
1913     my $file = shift;                            
1914                                                  
1915     $x =~ s@\/\/.*$@@gos; # strip C99-style c    
1916                                                  
1917     if ($x =~ /^#/ && $x !~ /^#\s*define/) {     
1918         # do nothing                             
1919     } elsif ($x =~ /([^\{]*)/) {                 
1920         $prototype .= $1;                        
1921     }                                            
1922                                                  
1923     if (($x =~ /\{/) || ($x =~ /\#\s*define/)    
1924         $prototype =~ s@/\*.*?\*/@@gos;          
1925         $prototype =~ s@[\r\n]+@ @gos; # stri    
1926         $prototype =~ s@^\s+@@gos; # strip le    
1927                                                  
1928         # Handle prototypes for function poin    
1929         # int (*pcs_config)(struct foo)          
1930         $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)    
1931                                                  
1932         if ($prototype =~ /SYSCALL_DEFINE/) {    
1933             syscall_munge();                     
1934         }                                        
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     }                                            
1943 }                                                
1944                                                  
1945 sub process_proto_type($$) {                     
1946     my $x = shift;                               
1947     my $file = shift;                            
1948                                                  
1949     $x =~ s@[\r\n]+@ @gos; # strip newlines/c    
1950     $x =~ s@^\s+@@gos; # strip leading spaces    
1951     $x =~ s@\s+$@@gos; # strip trailing space    
1952     $x =~ s@\/\/.*$@@gos; # strip C99-style c    
1953                                                  
1954     if ($x =~ /^#/) {                            
1955         # To distinguish preprocessor directi    
1956         $x .= ";";                               
1957     }                                            
1958                                                  
1959     while (1) {                                  
1960         if ( $x =~ /([^\{\};]*)([\{\};])(.*)/    
1961             if( length $prototype ) {            
1962                 $prototype .= " "                
1963             }                                    
1964             $prototype .= $1 . $2;               
1965             ($2 eq '{') && $brcount++;           
1966             ($2 eq '}') && $brcount--;           
1967             if (($2 eq ';') && ($brcount == 0    
1968                 dump_declaration($prototype,     
1969                 reset_state();                   
1970                 last;                            
1971             }                                    
1972             $x = $3;                             
1973         } else {                                 
1974             $prototype .= $x;                    
1975             last;                                
1976         }                                        
1977     }                                            
1978 }                                                
1979                                                  
1980                                                  
1981 sub map_filename($) {                            
1982     my $file;                                    
1983     my ($orig_file) = @_;                        
1984                                                  
1985     if (defined($ENV{'SRCTREE'})) {              
1986         $file = "$ENV{'SRCTREE'}" . "/" . $or    
1987     } else {                                     
1988         $file = $orig_file;                      
1989     }                                            
1990                                                  
1991     if (defined($source_map{$file})) {           
1992         $file = $source_map{$file};              
1993     }                                            
1994                                                  
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")) {                    
2003         print STDERR "Error: Cannot open file    
2004         ++$errors;                               
2005         return;                                  
2006     }                                            
2007                                                  
2008     while (<IN>) {                               
2009         if (/$export_symbol/) {                  
2010             next if (defined($nosymbol_table{    
2011             $function_table{$2} = 1;             
2012         }                                        
2013         if (/$export_symbol_ns/) {               
2014             next if (defined($nosymbol_table{    
2015             $function_table{$2} = 1;             
2016         }                                        
2017     }                                            
2018                                                  
2019     close(IN);                                   
2020 }                                                
2021                                                  
2022 #                                                
2023 # Parsers for the various processing states.     
2024 #                                                
2025 # STATE_NORMAL: looking for the /** to begin     
2026 #                                                
2027 sub process_normal() {                           
2028     if (/$doc_start/o) {                         
2029         $state = STATE_NAME;        # next li    
2030         $in_doc_sect = 0;                        
2031         $declaration_start_line = $. + 1;        
2032     }                                            
2033 }                                                
2034                                                  
2035 #                                                
2036 # STATE_NAME: Looking for the "name - descrip    
2037 #                                                
2038 sub process_name($$) {                           
2039     my $file = shift;                            
2040     my $descr;                                   
2041                                                  
2042     if (/$doc_block/o) {                         
2043         $state = STATE_DOCBLOCK;                 
2044         $contents = "";                          
2045         $new_start_line = $.;                    
2046                                                  
2047         if ( $1 eq "" ) {                        
2048             $section = $section_intro;           
2049         } else {                                 
2050             $section = $1;                       
2051         }                                        
2052     } elsif (/$doc_decl/o) {                     
2053         $identifier = $1;                        
2054         my $is_kernel_comment = 0;               
2055         my $decl_start = qr{$doc_com};           
2056         # test for pointer declaration type,     
2057         my $fn_type = qr{\w+\s*\*\s*};           
2058         my $parenthesis = qr{\(\w*\)};           
2059         my $decl_end = qr{[-:].*};               
2060         if (/^$decl_start([\w\s]+?)$parenthes    
2061             $identifier = $1;                    
2062         }                                        
2063         if ($identifier =~ m/^(struct|union|e    
2064             $decl_type = $1;                     
2065             $identifier = $2;                    
2066             $is_kernel_comment = 1;              
2067         }                                        
2068         # Look for foo() or static void foo()    
2069         # identifier                             
2070         elsif (/^$decl_start$fn_type?(\w+)\s*    
2071             /^$decl_start$fn_type?(\w+.*)$par    
2072             $identifier = $1;                    
2073             $decl_type = 'function';             
2074             $identifier =~ s/^define\s+//;       
2075             $is_kernel_comment = 1;              
2076         }                                        
2077         $identifier =~ s/\s+$//;                 
2078                                                  
2079         $state = STATE_BODY;                     
2080         # if there's no @param blocks need to    
2081         # here                                   
2082         $contents = "";                          
2083         $section = $section_default;             
2084         $new_start_line = $. + 1;                
2085         if (/[-:](.*)/) {                        
2086             # strip leading/trailing/multiple    
2087             $descr= $1;                          
2088             $descr =~ s/^\s*//;                  
2089             $descr =~ s/\s*$//;                  
2090             $descr =~ s/\s+/ /g;                 
2091             $declaration_purpose = $descr;       
2092             $state = STATE_BODY_MAYBE;           
2093         } else {                                 
2094             $declaration_purpose = "";           
2095         }                                        
2096                                                  
2097         if (!$is_kernel_comment) {               
2098             emit_warning("${file}:$.", "This     
2099             $state = STATE_NORMAL;               
2100         }                                        
2101                                                  
2102         if (($declaration_purpose eq "") && $    
2103             emit_warning("${file}:$.", "missi    
2104         }                                        
2105                                                  
2106         if ($identifier eq "" && $decl_type n    
2107             emit_warning("${file}:$.", "wrong    
2108             $state = STATE_NORMAL;               
2109         }                                        
2110                                                  
2111         if ($verbose) {                          
2112             print STDERR "${file}:$.: info: S    
2113         }                                        
2114     } else {                                     
2115         emit_warning("${file}:$.", "Cannot un    
2116         $state = STATE_NORMAL;                   
2117     }                                            
2118 }                                                
2119                                                  
2120                                                  
2121 #                                                
2122 # STATE_BODY and STATE_BODY_MAYBE: the bulk o    
2123 #                                                
2124 sub process_body($$) {                           
2125     my $file = shift;                            
2126                                                  
2127     if ($state == STATE_BODY_WITH_BLANK_LINE     
2128         dump_section($file, $section, $conten    
2129         $section = $section_default;             
2130         $new_start_line = $.;                    
2131         $contents = "";                          
2132     }                                            
2133                                                  
2134     if (/$doc_sect/i) { # case insensitive fo    
2135         $in_doc_sect = 1;                        
2136         $newsection = $1;                        
2137         $newcontents = $2;                       
2138                                                  
2139         # map the supported section names to     
2140         if ($newsection =~ m/^description$/i)    
2141             $newsection = $section_default;      
2142         } elsif ($newsection =~ m/^context$/i    
2143             $newsection = $section_context;      
2144         } elsif ($newsection =~ m/^returns?$/    
2145             $newsection = $section_return;       
2146         } elsif ($newsection =~ m/^\@return$/    
2147             # special: @return is a section,     
2148             $newsection = $section_return;       
2149         }                                        
2150                                                  
2151         if (($contents ne "") && ($contents n    
2152             if (!$in_doc_sect && $Wcontents_b    
2153                 emit_warning("${file}:$.", "c    
2154             }                                    
2155             dump_section($file, $section, $co    
2156             $section = $section_default;         
2157         }                                        
2158                                                  
2159         $in_doc_sect = 1;                        
2160         $state = STATE_BODY;                     
2161         $contents = $newcontents;                
2162         $new_start_line = $.;                    
2163         while (substr($contents, 0, 1) eq " "    
2164             $contents = substr($contents, 1);    
2165         }                                        
2166         if ($contents ne "") {                   
2167             $contents .= "\n";                   
2168         }                                        
2169         $section = $newsection;                  
2170         $leading_space = undef;                  
2171     } elsif (/$doc_end/) {                       
2172         if (($contents ne "") && ($contents n    
2173             dump_section($file, $section, $co    
2174             $section = $section_default;         
2175             $contents = "";                      
2176         }                                        
2177         # look for doc_com + <text> + doc_end    
2178         if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\    
2179             emit_warning("${file}:$.", "suspi    
2180         }                                        
2181                                                  
2182         $prototype = "";                         
2183         $state = STATE_PROTO;                    
2184         $brcount = 0;                            
2185         $new_start_line = $. + 1;                
2186     } elsif (/$doc_content/) {                   
2187         if ($1 eq "") {                          
2188             if ($section eq $section_context)    
2189                 dump_section($file, $section,    
2190                 $section = $section_default;     
2191                 $contents = "";                  
2192                 $new_start_line = $.;            
2193                 $state = STATE_BODY;             
2194             } else {                             
2195                 if ($section ne $section_defa    
2196                     $state = STATE_BODY_WITH_    
2197                 } else {                         
2198                     $state = STATE_BODY;         
2199                 }                                
2200                 $contents .= "\n";               
2201             }                                    
2202         } elsif ($state == STATE_BODY_MAYBE)     
2203             # Continued declaration purpose      
2204             chomp($declaration_purpose);         
2205             $declaration_purpose .= " " . $1;    
2206             $declaration_purpose =~ s/\s+/ /g    
2207         } else {                                 
2208             my $cont = $1;                       
2209             if ($section =~ m/^@/ || $section    
2210                 if (!defined $leading_space)     
2211                     if ($cont =~ m/^(\s+)/) {    
2212                         $leading_space = $1;     
2213                     } else {                     
2214                         $leading_space = "";     
2215                     }                            
2216                 }                                
2217                 $cont =~ s/^$leading_space//;    
2218             }                                    
2219             $contents .= $cont . "\n";           
2220         }                                        
2221     } else {                                     
2222         # i dont know - bad line?  ignore.       
2223         emit_warning("${file}:$.", "bad line:    
2224     }                                            
2225 }                                                
2226                                                  
2227                                                  
2228 #                                                
2229 # STATE_PROTO: reading a function/whatever pr    
2230 #                                                
2231 sub process_proto($$) {                          
2232     my $file = shift;                            
2233                                                  
2234     if (/$doc_inline_oneline/) {                 
2235         $section = $1;                           
2236         $contents = $2;                          
2237         if ($contents ne "") {                   
2238             $contents .= "\n";                   
2239             dump_section($file, $section, $co    
2240             $section = $section_default;         
2241             $contents = "";                      
2242         }                                        
2243     } elsif (/$doc_inline_start/) {              
2244         $state = STATE_INLINE;                   
2245         $inline_doc_state = STATE_INLINE_NAME    
2246     } elsif ($decl_type eq 'function') {         
2247         process_proto_function($_, $file);       
2248     } else {                                     
2249         process_proto_type($_, $file);           
2250     }                                            
2251 }                                                
2252                                                  
2253 #                                                
2254 # STATE_DOCBLOCK: within a DOC: block.           
2255 #                                                
2256 sub process_docblock($$) {                       
2257     my $file = shift;                            
2258                                                  
2259     if (/$doc_end/) {                            
2260         dump_doc_section($file, $section, $co    
2261         $section = $section_default;             
2262         $contents = "";                          
2263         $function = "";                          
2264         %parameterdescs = ();                    
2265         %parametertypes = ();                    
2266         @parameterlist = ();                     
2267         %sections = ();                          
2268         @sectionlist = ();                       
2269         $prototype = "";                         
2270         $state = STATE_NORMAL;                   
2271     } elsif (/$doc_content/) {                   
2272         if ( $1 eq "" )        {                 
2273             $contents .= $blankline;             
2274         } else {                                 
2275             $contents .= $1 . "\n";              
2276         }                                        
2277     }                                            
2278 }                                                
2279                                                  
2280 #                                                
2281 # STATE_INLINE: docbook comments within a pro    
2282 #                                                
2283 sub process_inline($$) {                         
2284     my $file = shift;                            
2285                                                  
2286     # First line (state 1) needs to be a @par    
2287     if ($inline_doc_state == STATE_INLINE_NAM    
2288         $section = $1;                           
2289         $contents = $2;                          
2290         $new_start_line = $.;                    
2291         if ($contents ne "") {                   
2292             while (substr($contents, 0, 1) eq    
2293                 $contents = substr($contents,    
2294             }                                    
2295             $contents .= "\n";                   
2296         }                                        
2297         $inline_doc_state = STATE_INLINE_TEXT    
2298         # Documentation block end */             
2299     } elsif (/$doc_inline_end/) {                
2300         if (($contents ne "") && ($contents n    
2301             dump_section($file, $section, $co    
2302             $section = $section_default;         
2303             $contents = "";                      
2304         }                                        
2305         $state = STATE_PROTO;                    
2306         $inline_doc_state = STATE_INLINE_NA;     
2307         # Regular text                           
2308     } elsif (/$doc_content/) {                   
2309         if ($inline_doc_state == STATE_INLINE    
2310             $contents .= $1 . "\n";              
2311             # nuke leading blank lines           
2312             if ($contents =~ /^\s*$/) {          
2313                 $contents = "";                  
2314             }                                    
2315         } elsif ($inline_doc_state == STATE_I    
2316             $inline_doc_state = STATE_INLINE_    
2317             emit_warning("${file}:$.", "Incor    
2318         }                                        
2319     }                                            
2320 }                                                
2321                                                  
2322                                                  
2323 sub process_file($) {                            
2324     my $file;                                    
2325     my $initial_section_counter = $section_co    
2326     my ($orig_file) = @_;                        
2327                                                  
2328     $file = map_filename($orig_file);            
2329                                                  
2330     if (!open(IN_FILE,"<$file")) {               
2331         print STDERR "Error: Cannot open file    
2332         ++$errors;                               
2333         return;                                  
2334     }                                            
2335                                                  
2336     $. = 1;                                      
2337                                                  
2338     $section_counter = 0;                        
2339     while (<IN_FILE>) {                          
2340         while (!/^ \*/ && s/\\\s*$//) {          
2341             $_ .= <IN_FILE>;                     
2342         }                                        
2343         # Replace tabs by spaces                 
2344         while ($_ =~ s/\t+/' ' x (length($&)     
2345         # Hand this line to the appropriate s    
2346         if ($state == STATE_NORMAL) {            
2347             process_normal();                    
2348         } elsif ($state == STATE_NAME) {         
2349             process_name($file, $_);             
2350         } elsif ($state == STATE_BODY || $sta    
2351                  $state == STATE_BODY_WITH_BL    
2352             process_body($file, $_);             
2353         } elsif ($state == STATE_INLINE) { #     
2354             process_inline($file, $_);           
2355         } elsif ($state == STATE_PROTO) {        
2356             process_proto($file, $_);            
2357         } elsif ($state == STATE_DOCBLOCK) {     
2358             process_docblock($file, $_);         
2359         }                                        
2360     }                                            
2361                                                  
2362     # Make sure we got something interesting.    
2363     if ($initial_section_counter == $section_    
2364         output_mode ne "none") {                 
2365         if ($output_selection == OUTPUT_INCLU    
2366             emit_warning("${file}:1", "'$_' n    
2367                 for keys %function_table;        
2368         } else {                                 
2369             emit_warning("${file}:1", "no str    
2370         }                                        
2371     }                                            
2372     close IN_FILE;                               
2373 }                                                
2374                                                  
2375                                                  
2376 if ($output_mode eq "rst") {                     
2377     get_sphinx_version() if (!$sphinx_major);    
2378 }                                                
2379                                                  
2380 $kernelversion = get_kernel_version();           
2381                                                  
2382 # generate a sequence of code that will splic    
2383 # using the s// operator.                        
2384 for (my $k = 0; $k < @highlights; $k++) {        
2385     my $pattern = $highlights[$k][0];            
2386     my $result = $highlights[$k][1];             
2387 #   print STDERR "scanning pattern:$pattern,     
2388     $dohighlight .=  "\$contents =~ s:$patter    
2389 }                                                
2390                                                  
2391 # Read the file that maps relative names to a    
2392 # separate source and object directories and     
2393 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {    
2394     my ($relname, $absname);                     
2395     while(<SOURCE_MAP>) {                        
2396         chop();                                  
2397         ($relname, $absname) = (split())[0..1    
2398         $relname =~ s:^/+::;                     
2399         $source_map{$relname} = $absname;        
2400     }                                            
2401     close(SOURCE_MAP);                           
2402 }                                                
2403                                                  
2404 if ($output_selection == OUTPUT_EXPORTED ||      
2405     $output_selection == OUTPUT_INTERNAL) {      
2406                                                  
2407     push(@export_file_list, @ARGV);              
2408                                                  
2409     foreach (@export_file_list) {                
2410         chomp;                                   
2411         process_export_file($_);                 
2412     }                                            
2413 }                                                
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                                             
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php