]>
git.proxmox.com Git - mirror_ubuntu-kernels.git/blob - scripts/kernel-doc
2 # SPDX-License-Identifier: GPL-2.0
7 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
9 ## Copyright (C) 2001 Simon Huggins ##
10 ## Copyright (C) 2005-2012 Randy Dunlap ##
11 ## Copyright (C) 2012 Dan Luedtke ##
13 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
14 ## Copyright (c) 2000 MontaVista Software, Inc. ##
16 # Copyright (C) 2022 Tomasz Warniełło (POD)
18 use Pod
:: Usage qw
/pod2usage/ ;
22 kernel-doc - Print formatted kernel documentation to stdout
26 kernel-doc [-h] [-v] [-Werror]
28 -rst [-sphinx-version VERSION] [-enable-lineno] |
34 [-function NAME] ... |
38 [-export-file FILE] ...
41 Run `kernel-doc -h` for details.
45 Read C language source or header FILEs, extract embedded documentation comments,
46 and print formatted documentation to standard output.
48 The documentation comments are identified by the "/**" opening comment mark.
50 See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
54 # more perldoc at the end of the file
60 my $anon_struct_union = 0 ;
62 # match expressions used to find embedded type information
63 my $type_constant = ' \b ``([^\`]+)`` \b ' ;
64 my $type_constant2 = '\%([-_\w]+)' ;
65 my $type_func = '(\w+)\(\)' ;
66 my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)' ;
67 my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)' ;
68 my $type_fp_param = '\@(\w+)\(\)' ; # Special RST handling for func ptr params
69 my $type_fp_param2 = '\@(\w+->\S+)\(\)' ; # Special RST handling for structs with func ptr params
70 my $type_env = '(\ $\w+ )' ;
71 my $type_enum = '\&(enum\s*([_\w]+))' ;
72 my $type_struct = '\&(struct\s*([_\w]+))' ;
73 my $type_typedef = '\&(typedef\s*([_\w]+))' ;
74 my $type_union = '\&(union\s*([_\w]+))' ;
75 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)' ;
76 my $type_fallback = '\&([_\w]+)' ;
77 my $type_member_func = $type_member . '\(\)' ;
79 # Output conversion substitutions.
80 # One for each output format
82 # these are pretty rough
83 my @highlights_man = (
84 [ $type_constant, "\ $1 " ],
85 [ $type_constant2, "\ $1 " ],
86 [ $type_func, " \\\\ fB\ $1\\\\fP " ],
87 [ $type_enum, " \\\\ fI\ $1\\\\fP " ],
88 [ $type_struct, " \\\\ fI\ $1\\\\fP " ],
89 [ $type_typedef, " \\\\ fI\ $1\\\\fP " ],
90 [ $type_union, " \\\\ fI\ $1\\\\fP " ],
91 [ $type_param, " \\\\ fI\ $1\\\\fP " ],
92 [ $type_param_ref, " \\\\ fI\ $1\$2\\\\fP " ],
93 [ $type_member, " \\\\ fI\ $1\$2\$3\\\\fP " ],
94 [ $type_fallback, " \\\\ fI\ $1\\\\fP " ]
96 my $blankline_man = "" ;
99 my @highlights_rst = (
100 [ $type_constant, "``\ $1`` " ],
101 [ $type_constant2, "``\ $1`` " ],
102 # Note: need to escape () to avoid func matching later
103 [ $type_member_func, " \\ :c \\ :type \\ :`\ $1\$2\$3\\\\ ( \\\\ ) <\ $1 >`" ],
104 [ $type_member, " \\ :c \\ :type \\ :`\ $1\$2\$3 <\ $1 >`" ],
105 [ $type_fp_param, "**\ $1\\\\ ( \\\\ )**" ],
106 [ $type_fp_param2, "**\ $1\\\\ ( \\\\ )**" ],
107 [ $type_func, "\ $1 ()" ],
108 [ $type_enum, " \\ :c \\ :type \\ :`\ $1 <\ $2 >`" ],
109 [ $type_struct, " \\ :c \\ :type \\ :`\ $1 <\ $2 >`" ],
110 [ $type_typedef, " \\ :c \\ :type \\ :`\ $1 <\ $2 >`" ],
111 [ $type_union, " \\ :c \\ :type \\ :`\ $1 <\ $2 >`" ],
112 # in rst this can refer to any type
113 [ $type_fallback, " \\ :c \\ :type \\ :`\ $1` " ],
114 [ $type_param_ref, "**\ $1\$2** " ]
116 my $blankline_rst = " \n " ;
121 - message
=> "No arguments! \n " ,
124 - sections
=> 'SYNOPSIS' ,
130 my ( $sphinx_major, $sphinx_minor, $sphinx_patch );
132 my $dohighlight = "" ;
136 my $output_mode = "rst" ;
137 my $output_preformatted = 0 ;
138 my $no_doc_sections = 0 ;
139 my $enable_lineno = 0 ;
140 my @highlights = @highlights_rst ;
141 my $blankline = $blankline_rst ;
142 my $modulename = "Kernel API" ;
145 OUTPUT_ALL
=> 0 , # output all symbols and doc sections
146 OUTPUT_INCLUDE
=> 1 , # output only specified symbols
147 OUTPUT_EXPORTED
=> 2 , # output exported symbols
148 OUTPUT_INTERNAL
=> 3 , # output non-exported symbols
150 my $output_selection = OUTPUT_ALL
;
151 my $show_not_found = 0 ; # No longer used
153 my @export_file_list ;
156 if ( defined ( $ENV { 'KBUILD_BUILD_TIMESTAMP' }) &&
157 ( my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" + %s` ) ne '') {
158 @build_time = gmtime( $seconds );
160 @build_time = localtime;
163 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
164 'July', 'August', 'September', 'October',
165 'November', 'December')[ $build_time [4]] .
166 " " . ( $build_time [5]+1900);
168 # Essentially these are globals.
169 # They probably want to be tidied up, made more localised or something.
170 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
171 # could cause "use of undefined value" or other bugs.
172 my ( $function, %function_table, %parametertypes, $declaration_purpose );
173 my %nosymbol_table = ();
174 my $declaration_start_line ;
175 my ( $type, $declaration_name, $return_type );
176 my ( $newsection, $newcontents, $prototype, $brcount, %source_map );
178 if (defined( $ENV {'KBUILD_VERBOSE'})) {
179 $verbose = " $ENV {'KBUILD_VERBOSE'}";
182 if (defined( $ENV {'KCFLAGS'})) {
183 my $kcflags = " $ENV {'KCFLAGS'}";
185 if ( $kcflags =~ /Werror/) {
190 if (defined( $ENV {'KDOC_WERROR'})) {
191 $Werror = " $ENV {'KDOC_WERROR'}";
194 # Generated docbook code is inserted in a template at a point where
195 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
196 # https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
197 # We keep track of number of generated entries and generate a dummy
198 # if needs be to ensure the expanded template can be postprocessed
200 my $section_counter = 0;
206 STATE_NORMAL => 0, # normal code
207 STATE_NAME => 1, # looking for function name
208 STATE_BODY_MAYBE => 2, # body - or maybe more description
209 STATE_BODY => 3, # the body of the comment
210 STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
211 STATE_PROTO => 5, # scanning prototype
212 STATE_DOCBLOCK => 6, # documentation block
213 STATE_INLINE => 7, # gathering doc outside main block
219 # Inline documentation state
221 STATE_INLINE_NA => 0, # not applicable ( $state != STATE_INLINE)
222 STATE_INLINE_NAME => 1, # looking for member name ( @foo :)
223 STATE_INLINE_TEXT => 2, # looking for member documentation
224 STATE_INLINE_END => 3, # done
225 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
226 # Spit a warning as it's not
227 # proper kernel-doc and ignore the rest.
229 my $inline_doc_state ;
231 #declaration types: can be
232 # 'function', 'struct', 'union', 'enum', 'typedef'
235 # Name of the kernel-doc identifier for non-DOC markups
238 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
240 my $doc_com = '\s*\*\s*';
241 my $doc_com_body = '\s*\* ?';
242 my $doc_decl = $doc_com . '(\w+)';
243 # @params and a strictly limited set of supported section names
248 # while trying to not match literal block starts like "example::"
250 my $doc_sect = $doc_com .
251 '\s*(\@[.\w]+|\ @\ .\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
252 my $doc_content = $doc_com_body . '(.*)';
253 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
254 my $doc_inline_start = '^\s*/\*\*\s*$';
255 my $doc_inline_sect = '\s*\*\s*( @\s* [\w][\w\.]*\s*):(.*)';
256 my $doc_inline_end = '^\s*\*/\s*$';
257 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
258 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
259 my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
260 my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
263 my %parameterdesc_start_lines ;
267 my %section_start_lines ;
272 my $new_start_line = 0;
274 # the canonical section names. see also $doc_sect above.
275 my $section_default = "Description"; # default section
276 my $section_intro = "Introduction";
277 my $section = $section_default ;
278 my $section_context = "Context";
279 my $section_return = "Return";
281 my $undescribed = "-- undescribed --";
285 while ( $ARGV [0] =~ m/^--?(.*)/) {
289 $output_mode = "man";
290 @highlights = @highlights_man ;
291 $blankline = $blankline_man ;
292 } elsif ( $cmd eq "rst") {
293 $output_mode = "rst";
294 @highlights = @highlights_rst ;
295 $blankline = $blankline_rst ;
296 } elsif ( $cmd eq "none") {
297 $output_mode = "none";
298 } elsif ( $cmd eq "module") { # not needed for XML, inherits from calling document
299 $modulename = shift @ARGV ;
300 } elsif ( $cmd eq "function") { # to only output specific functions
301 $output_selection = OUTPUT_INCLUDE;
302 $function = shift @ARGV ;
303 $function_table { $function } = 1;
304 } elsif ( $cmd eq "nosymbol") { # Exclude specific symbols
305 my $symbol = shift @ARGV ;
306 $nosymbol_table { $symbol } = 1;
307 } elsif ( $cmd eq "export") { # only exported symbols
308 $output_selection = OUTPUT_EXPORTED;
309 %function_table = ();
310 } elsif ( $cmd eq "internal") { # only non-exported symbols
311 $output_selection = OUTPUT_INTERNAL;
312 %function_table = ();
313 } elsif ( $cmd eq "export-file") {
314 my $file = shift @ARGV ;
315 push( @export_file_list, $file );
316 } elsif ( $cmd eq "v") {
318 } elsif ( $cmd eq "Werror") {
320 } elsif (( $cmd eq "h") || ( $cmd eq "help")) {
321 pod2usage(-exitval => 0, -verbose => 2);
322 } elsif ( $cmd eq 'no-doc-sections') {
323 $no_doc_sections = 1;
324 } elsif ( $cmd eq 'enable-lineno') {
326 } elsif ( $cmd eq 'show-not-found') {
327 $show_not_found = 1; # A no-op but don't fail
328 } elsif ( $cmd eq "sphinx-version") {
329 my $ver_string = shift @ARGV ;
330 if ( $ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
333 $sphinx_minor = substr( $2,1 );
338 $sphinx_patch = substr( $3,1 )
343 die "Sphinx version should either major.minor or major.minor.patch format \n ";
348 -message => "Argument unknown! \n ",
351 -sections => 'SYNOPSIS',
357 -message => "FILE argument missing \n ",
360 -sections => 'SYNOPSIS',
366 # continue execution near EOF;
368 # The C domain dialect changed on Sphinx 3. So, we need to check the
369 # version in order to produce the right tags.
372 foreach(split(/:/, $ENV {PATH})) {
373 return " $_/$_ [0]" if(-x " $_/$_ [0]");
377 sub get_sphinx_version()
381 my $cmd = "sphinx-build";
382 if (!findprog( $cmd )) {
383 my $cmd = "sphinx-build3";
384 if (!findprog( $cmd )) {
388 printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d . %d . %d ) \n ",
389 $sphinx_major, $sphinx_minor, $sphinx_patch ;
394 open IN, " $cmd --version 2>&1 |";
396 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)? $/ ) {
402 # Sphinx 1.2.x uses a different format
403 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
413 # get kernel version from env
414 sub get_kernel_version() {
415 my $version = 'unknown kernel version';
417 if (defined( $ENV {'KERNELVERSION'})) {
418 $version = $ENV {'KERNELVERSION'};
426 if ( $enable_lineno && defined( $lineno )) {
427 print ".. LINENO " . $lineno . " \n ";
431 # dumps section contents to arrays/hashes intended for that purpose.
436 my $contents = join " \n ", @_ ;
438 if ( $name =~ m/$type_param/) {
440 $parameterdescs { $name } = $contents ;
441 $sectcheck = $sectcheck . $name . " ";
442 $parameterdesc_start_lines { $name } = $new_start_line ;
444 } elsif ( $name eq " @\ .\.\.") {
446 $parameterdescs { $name } = $contents ;
447 $sectcheck = $sectcheck . $name . " ";
448 $parameterdesc_start_lines { $name } = $new_start_line ;
451 if (defined( $sections { $name }) && ( $sections { $name } ne "")) {
452 # Only warn on user specified duplicate section names.
453 if ( $name ne $section_default ) {
454 print STDERR "${file}:$.: warning: duplicate section name ' $name ' \n ";
457 $sections { $name } .= $contents ;
459 $sections { $name } = $contents ;
460 push @sectionlist, $name ;
461 $section_start_lines { $name } = $new_start_line ;
468 # dump DOC: section after checking that it should go out
470 sub dump_doc_section {
473 my $contents = join " \n ", @_ ;
475 if ( $no_doc_sections ) {
479 return if (defined( $nosymbol_table { $name }));
481 if (( $output_selection == OUTPUT_ALL) ||
482 (( $output_selection == OUTPUT_INCLUDE) &&
483 defined( $function_table { $name })))
485 dump_section( $file, $name, $contents );
486 output_blockhead({'sectionlist' => \ @sectionlist,
487 'sections' => \ %sections,
488 'module' => $modulename,
489 'content-only' => ( $output_selection != OUTPUT_ALL), });
496 # parameterdescs, a hash.
497 # function => "function name"
498 # parameterlist => @list of parameters
499 # parameterdescs => %parameter descriptions
500 # sectionlist => @list of sections
501 # sections => %section descriptions
504 sub output_highlight {
505 my $contents = join " \n ", @_ ;
509 # if (!defined $contents ) {
511 # confess "output_highlight got called with no args? \n ";
514 # print STDERR "contents b4: $contents\n ";
517 # print STDERR "contents af: $contents\n ";
519 foreach $line (split " \n ", $contents ) {
520 if (! $output_preformatted ) {
524 if (! $output_preformatted ) {
525 print $lineprefix, $blankline ;
528 if ( $output_mode eq "man" && substr( $line, 0, 1) eq ".") {
531 print $lineprefix, $line ;
539 # output function in man
540 sub output_function_man(%) {
542 my ( $parameter, $section );
545 print ".TH \" $args {'function'} \" 9 \" $args {'function'} \" \" $man_date\ " \" Kernel Hacker's Manual \" LINUX \n ";
548 print $args {'function'} . " \\ - " . $args {'purpose'} . " \n ";
550 print ".SH SYNOPSIS \n ";
551 if ( $args {'functiontype'} ne "") {
552 print ".B \" " . $args {'functiontype'} . " \" " . $args {'function'} . " \n ";
554 print ".B \" " . $args {'function'} . " \n ";
559 foreach my $parameter (@{ $args {'parameterlist'}}) {
560 if ( $count == $# { $args {'parameterlist'}}) {
563 $type = $args {'parametertypes'}{ $parameter };
564 if ( $type =~ m/$function_pointer/) {
565 # pointer-to-function
566 print ".BI \" " . $parenth . $1 . " \" " . " \" ) (" . $2 . ")" . $post . " \"\n ";
568 $type =~ s/([^\*])$/$1 /;
569 print ".BI \" " . $parenth . $type . " \" " . " \" " . $post . " \"\n ";
575 print ".SH ARGUMENTS \n ";
576 foreach $parameter (@{ $args {'parameterlist'}}) {
577 my $parameter_name = $parameter ;
578 $parameter_name =~ s/\[.*//;
580 print ".IP \" " . $parameter . " \" 12 \n ";
581 output_highlight( $args {'parameterdescs'}{ $parameter_name });
583 foreach $section (@{ $args {'sectionlist'}}) {
584 print ".SH \" ", uc $section, " \"\n ";
585 output_highlight( $args {'sections'}{ $section });
591 sub output_enum_man(%) {
593 my ( $parameter, $section );
596 print ".TH \" $args {'module'} \" 9 \" enum $args {'enum'} \" \" $man_date\ " \" API Manual \" LINUX \n ";
599 print "enum " . $args {'enum'} . " \\ - " . $args {'purpose'} . " \n ";
601 print ".SH SYNOPSIS \n ";
602 print "enum " . $args {'enum'} . " { \n ";
604 foreach my $parameter (@{ $args {'parameterlist'}}) {
605 print ".br \n .BI \" $parameter\ " \n ";
606 if ( $count == $# { $args {'parameterlist'}}) {
616 print ".SH Constants \n ";
617 foreach $parameter (@{ $args {'parameterlist'}}) {
618 my $parameter_name = $parameter ;
619 $parameter_name =~ s/\[.*//;
621 print ".IP \" " . $parameter . " \" 12 \n ";
622 output_highlight( $args {'parameterdescs'}{ $parameter_name });
624 foreach $section (@{ $args {'sectionlist'}}) {
625 print ".SH \" $section\ " \n ";
626 output_highlight( $args {'sections'}{ $section });
631 # output struct in man
632 sub output_struct_man(%) {
634 my ( $parameter, $section );
636 print ".TH \" $args {'module'} \" 9 \" " . $args {'type'} . " " . $args {'struct'} . " \" \" $man_date\ " \" API Manual \" LINUX \n ";
639 print $args {'type'} . " " . $args {'struct'} . " \\ - " . $args {'purpose'} . " \n ";
641 my $declaration = $args {'definition'};
642 $declaration =~ s/\t/ /g;
643 $declaration =~ s/\n/"\n.br\n.BI \"/g;
644 print ".SH SYNOPSIS \n ";
645 print $args {'type'} . " " . $args {'struct'} . " { \n .br \n ";
646 print ".BI \" $declaration\n }; \n .br \n\n ";
648 print ".SH Members \n ";
649 foreach $parameter (@{ $args {'parameterlist'}}) {
650 ( $parameter =~ /^#/) && next;
652 my $parameter_name = $parameter ;
653 $parameter_name =~ s/\[.*//;
655 ( $args {'parameterdescs'}{ $parameter_name } ne $undescribed ) || next;
656 print ".IP \" " . $parameter . " \" 12 \n ";
657 output_highlight( $args {'parameterdescs'}{ $parameter_name });
659 foreach $section (@{ $args {'sectionlist'}}) {
660 print ".SH \" $section\ " \n ";
661 output_highlight( $args {'sections'}{ $section });
666 # output typedef in man
667 sub output_typedef_man(%) {
669 my ( $parameter, $section );
671 print ".TH \" $args {'module'} \" 9 \" $args {'typedef'} \" \" $man_date\ " \" API Manual \" LINUX \n ";
674 print "typedef " . $args {'typedef'} . " \\ - " . $args {'purpose'} . " \n ";
676 foreach $section (@{ $args {'sectionlist'}}) {
677 print ".SH \" $section\ " \n ";
678 output_highlight( $args {'sections'}{ $section });
682 sub output_blockhead_man(%) {
684 my ( $parameter, $section );
687 print ".TH \" $args {'module'} \" 9 \" $args {'module'} \" \" $man_date\ " \" API Manual \" LINUX \n ";
689 foreach $section (@{ $args {'sectionlist'}}) {
690 print ".SH \" $section\ " \n ";
691 output_highlight( $args {'sections'}{ $section });
696 # output in restructured text
700 # This could use some work; it's used to output the DOC: sections, and
701 # starts by putting out the name of the doc section itself, but that tends
702 # to duplicate a header already in the template file.
704 sub output_blockhead_rst(%) {
706 my ( $parameter, $section );
708 foreach $section (@{ $args {'sectionlist'}}) {
709 next if (defined( $nosymbol_table { $section }));
711 if ( $output_selection != OUTPUT_INCLUDE) {
712 print ".. _ $section : \n\n ";
713 print "** $section**\n\n ";
715 print_lineno( $section_start_lines { $section });
716 output_highlight_rst( $args {'sections'}{ $section });
722 # Apply the RST highlights to a sub-block of text.
724 sub highlight_block($) {
725 # The dohighlight kludge requires the text be called $contents
726 my $contents = shift;
733 # Regexes used only here.
735 my $sphinx_literal = '^[^.].*::$';
736 my $sphinx_cblock = '^\.\.\ +code-block::';
738 sub output_highlight_rst {
739 my $input = join " \n ", @_ ;
746 foreach $line (split " \n ", $input ) {
748 # If we're in a literal block, see if we should drop out
749 # of it. Otherwise pass the line straight through unmunged.
752 if (! ( $line =~ /^\s* $/ )) {
754 # If this is the first non-blank line in a literal
755 # block we need to figure out what the proper indent is.
757 if ( $litprefix eq "") {
759 $litprefix = '^' . $1 ;
760 $output .= $line . " \n ";
761 } elsif (! ( $line =~ / $litprefix/ )) {
764 $output .= $line . " \n ";
767 $output .= $line . " \n ";
771 # Not in a literal block (or just dropped out)
774 $block .= $line . " \n ";
775 if (( $line =~ / $sphinx_literal/ ) || ( $line =~ / $sphinx_cblock/ )) {
778 $output .= highlight_block( $block );
785 $output .= highlight_block( $block );
787 foreach $line (split " \n ", $output ) {
788 print $lineprefix . $line . " \n ";
792 sub output_function_rst(%) {
794 my ( $parameter, $section );
795 my $oldprefix = $lineprefix ;
799 if ( $sphinx_major < 3) {
800 if ( $args {'typedef'}) {
801 print ".. c:type:: ". $args {'function'} . " \n\n ";
802 print_lineno( $declaration_start_line );
803 print " **Typedef**: ";
805 output_highlight_rst( $args {'purpose'});
806 $start = " \n\n **Syntax** \n\n ` `";
809 print ".. c:function:: ";
812 if ( $args {'typedef'} || $args {'functiontype'} eq "") {
814 print ".. c:macro:: ". $args {'function'} . " \n\n ";
816 print ".. c:function:: ";
819 if ( $args {'typedef'}) {
820 print_lineno( $declaration_start_line );
821 print " **Typedef**: ";
823 output_highlight_rst( $args {'purpose'});
824 $start = " \n\n **Syntax** \n\n ` `";
826 print "` `" if ( $is_macro );
829 if ( $args {'functiontype'} ne "") {
830 $start .= $args {'functiontype'} . " " . $args {'function'} . " (";
832 $start .= $args {'function'} . " (";
837 foreach my $parameter (@{ $args {'parameterlist'}}) {
842 $type = $args {'parametertypes'}{ $parameter };
844 if ( $type =~ m/$function_pointer/) {
845 # pointer-to-function
846 print $1 . $parameter . ") (" . $2 . ")";
856 if (! $args {'typedef'}) {
857 print_lineno( $declaration_start_line );
859 output_highlight_rst( $args {'purpose'});
863 print "**Parameters** \n\n ";
865 foreach $parameter (@{ $args {'parameterlist'}}) {
866 my $parameter_name = $parameter ;
867 $parameter_name =~ s/\[.*//;
868 $type = $args {'parametertypes'}{ $parameter };
873 print "` ` $parameter``\n ";
876 print_lineno( $parameterdesc_start_lines { $parameter_name });
878 if (defined( $args {'parameterdescs'}{ $parameter_name }) &&
879 $args {'parameterdescs'}{ $parameter_name } ne $undescribed ) {
880 output_highlight_rst( $args {'parameterdescs'}{ $parameter_name });
882 print " *undescribed* \n ";
887 $lineprefix = $oldprefix ;
888 output_section_rst( @_ );
891 sub output_section_rst(%) {
894 my $oldprefix = $lineprefix ;
897 foreach $section (@{ $args {'sectionlist'}}) {
898 print "** $section**\n\n ";
899 print_lineno( $section_start_lines { $section });
900 output_highlight_rst( $args {'sections'}{ $section });
904 $lineprefix = $oldprefix ;
907 sub output_enum_rst(%) {
910 my $oldprefix = $lineprefix ;
913 if ( $sphinx_major < 3) {
914 my $name = "enum " . $args {'enum'};
915 print " \n\n .. c:type:: " . $name . " \n\n ";
917 my $name = $args {'enum'};
918 print " \n\n .. c:enum:: " . $name . " \n\n ";
920 print_lineno( $declaration_start_line );
922 output_highlight_rst( $args {'purpose'});
925 print "**Constants** \n\n ";
927 foreach $parameter (@{ $args {'parameterlist'}}) {
928 print "` ` $parameter``\n ";
929 if ( $args {'parameterdescs'}{ $parameter } ne $undescribed ) {
930 output_highlight_rst( $args {'parameterdescs'}{ $parameter });
932 print " *undescribed* \n ";
937 $lineprefix = $oldprefix ;
938 output_section_rst( @_ );
941 sub output_typedef_rst(%) {
944 my $oldprefix = $lineprefix ;
947 if ( $sphinx_major < 3) {
948 $name = "typedef " . $args {'typedef'};
950 $name = $args {'typedef'};
952 print " \n\n .. c:type:: " . $name . " \n\n ";
953 print_lineno( $declaration_start_line );
955 output_highlight_rst( $args {'purpose'});
958 $lineprefix = $oldprefix ;
959 output_section_rst( @_ );
962 sub output_struct_rst(%) {
965 my $oldprefix = $lineprefix ;
967 if ( $sphinx_major < 3) {
968 my $name = $args {'type'} . " " . $args {'struct'};
969 print " \n\n .. c:type:: " . $name . " \n\n ";
971 my $name = $args {'struct'};
972 if ( $args {'type'} eq 'union') {
973 print " \n\n .. c:union:: " . $name . " \n\n ";
975 print " \n\n .. c:struct:: " . $name . " \n\n ";
978 print_lineno( $declaration_start_line );
980 output_highlight_rst( $args {'purpose'});
983 print "**Definition** \n\n ";
985 my $declaration = $args {'definition'};
986 $declaration =~ s/\t/ /g;
987 print " " . $args {'type'} . " " . $args {'struct'} . " { \n $declaration }; \n\n ";
989 print "**Members** \n\n ";
991 foreach $parameter (@{ $args {'parameterlist'}}) {
992 ( $parameter =~ /^#/) && next;
994 my $parameter_name = $parameter ;
995 $parameter_name =~ s/\[.*//;
997 ( $args {'parameterdescs'}{ $parameter_name } ne $undescribed ) || next;
998 $type = $args {'parametertypes'}{ $parameter };
999 print_lineno( $parameterdesc_start_lines { $parameter_name });
1000 print "` `" . $parameter . "` ` \n ";
1001 output_highlight_rst( $args {'parameterdescs'}{ $parameter_name });
1006 $lineprefix = $oldprefix ;
1007 output_section_rst( @_ );
1010 ## none mode output functions
1012 sub output_function_none(%) {
1015 sub output_enum_none(%) {
1018 sub output_typedef_none(%) {
1021 sub output_struct_none(%) {
1024 sub output_blockhead_none(%) {
1028 # generic output function for all types (function, struct/union, typedef, enum);
1029 # calls the generated, variable output_ function name based on
1030 # functype and output_mode
1031 sub output_declaration {
1034 my $functype = shift;
1035 my $func = "output_${functype}_ $output_mode ";
1037 return if (defined( $nosymbol_table { $name }));
1039 if (( $output_selection == OUTPUT_ALL) ||
1040 (( $output_selection == OUTPUT_INCLUDE ||
1041 $output_selection == OUTPUT_EXPORTED) &&
1042 defined( $function_table { $name })) ||
1043 ( $output_selection == OUTPUT_INTERNAL &&
1044 !( $functype eq "function" && defined( $function_table { $name }))))
1052 # generic output function - calls the right one based on current output mode.
1053 sub output_blockhead {
1055 my $func = "output_blockhead_" . $output_mode ;
1061 # takes a declaration (struct, union, enum, typedef) and
1062 # invokes the right handler. NOT called for functions.
1063 sub dump_declaration( $$ ) {
1065 my ( $prototype, $file ) = @_ ;
1066 my $func = "dump_" . $decl_type ;
1070 sub dump_union( $$ ) {
1074 sub dump_struct( $$ ) {
1079 my $type = qr{struct|union};
1080 # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
1081 my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
1082 my $definition_body = qr{\{(.*)\}\s* $qualifiers* };
1083 my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};
1085 if ( $x =~ /( $type )\s+(\w+)\s* $definition_body/ ) {
1087 $declaration_name = $2 ;
1089 } elsif ( $x =~ /typedef\s+( $type )\s* $definition_body\s* (\w+)\s*;/) {
1091 $declaration_name = $3 ;
1096 if ( $identifier ne $declaration_name ) {
1097 print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier . Prototype was for $decl_type $declaration_name instead \n ";
1101 # ignore members marked private:
1102 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1103 $members =~ s/\/\*\s*private:.*//gosi;
1105 $members =~ s/\/\*.*?\*\///gos;
1107 $members =~ s/\s*$attribute/ /gi;
1108 $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos;
1109 $members =~ s/\s*__packed\s*/ /gos;
1110 $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
1111 $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
1112 $members =~ s/\s*____cacheline_aligned/ /gos;
1113 # unwrap struct_group():
1114 # - first eat non-declaration parameters and rewrite for final match
1115 # - then remove macro, outer parens, and trailing semicolon
1116 $members =~ s/\bstruct_group\s*\(([^,]*,)/STRUCT_GROUP(/gos;
1117 $members =~ s/\bstruct_group_(attr|tagged)\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
1118 $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
1119 $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;/$2/gos;
1121 my $args = qr{([^,)]+)};
1122 # replace DECLARE_BITMAP
1123 $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
1124 $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
1125 $members =~ s/DECLARE_BITMAP\s*\($args,\s*$args\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1126 # replace DECLARE_HASHTABLE
1127 $members =~ s/DECLARE_HASHTABLE\s*\($args,\s*$args\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1128 # replace DECLARE_KFIFO
1129 $members =~ s/DECLARE_KFIFO\s*\($args,\s*$args,\s*$args\)/$2 \*$1/gos;
1130 # replace DECLARE_KFIFO_PTR
1131 $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
1132 # replace DECLARE_FLEX_ARRAY
1133 $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
1134 my $declaration = $members ;
1136 # Split nested struct/union elements as newer ones
1137 while ( $members =~ m/$struct_members/) {
1142 foreach my $id (split /,/, $ids ) {
1143 $newmember .= " $maintype $id ; ";
1146 $id =~ s/^\s*\**(\S+)\s*/$1/;
1147 foreach my $arg (split /;/, $content ) {
1148 next if ( $arg =~ m/^\s*$/);
1149 if ( $arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
1150 # pointer-to-function
1155 if ( $id =~ m/^\s*$/) {
1156 # anonymous struct/union
1157 $newmember .= " $type$name$extra ; ";
1159 $newmember .= " $type$id . $name$extra ; ";
1167 $arg =~ s/:\s*\d+\s*//g;
1169 $arg =~ s/\[.*\]//g;
1170 # The type may have multiple words,
1171 # and multiple IDs can be defined, like:
1172 # const struct foo, *bar, foobar
1173 # So, we remove spaces when parsing the
1174 # names, in order to match just names
1175 # and commas for the names
1176 $arg =~ s/\s*,\s*/,/g;
1177 if ( $arg =~ m/(.*)\s+([\S+,]+)/) {
1181 $newmember .= " $arg ; ";
1184 foreach my $name (split /,/, $names ) {
1185 $name =~ s/^\s*\**(\S+)\s*/$1/;
1186 next if (( $name =~ m/^\s*$/));
1187 if ( $id =~ m/^\s*$/) {
1188 # anonymous struct/union
1189 $newmember .= " $type $name ; ";
1191 $newmember .= " $type $id . $name ; ";
1197 $members =~ s/$struct_members/$newmember/;
1200 # Ignore other nested elements, like enums
1201 $members =~ s/(\{[^\{\}]*\})//g;
1203 create_parameterlist( $members, ';', $file, $declaration_name );
1204 check_sections( $file, $declaration_name, $decl_type, $sectcheck, $struct_actual );
1206 # Adjust declaration for better display
1207 $declaration =~ s/([\{;])/$1\n/g;
1208 $declaration =~ s/\}\s+;/};/g;
1209 # Better handle inlined enums
1210 do {} while ( $declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);
1212 my @def_args = split / \n /, $declaration ;
1215 foreach my $clause ( @def_args ) {
1216 $clause =~ s/^\s+//;
1217 $clause =~ s/\s+$//;
1218 $clause =~ s/\s+/ /;
1220 $level -- if ( $clause =~ m/(\})/ && $level > 1);
1221 if (!( $clause =~ m/^\s*#/)) {
1222 $declaration .= " \t " x $level ;
1224 $declaration .= " \t " . $clause . " \n ";
1225 $level++ if ( $clause =~ m/(\{)/ && !( $clause =~m/\}/));
1227 output_declaration( $declaration_name,
1229 {'struct' => $declaration_name,
1230 'module' => $modulename,
1231 'definition' => $declaration,
1232 'parameterlist' => \ @parameterlist,
1233 'parameterdescs' => \ %parameterdescs,
1234 'parametertypes' => \ %parametertypes,
1235 'sectionlist' => \ @sectionlist,
1236 'sections' => \ %sections,
1237 'purpose' => $declaration_purpose,
1238 'type' => $decl_type
1242 print STDERR "${file}:$.: error: Cannot parse struct or union! \n ";
1248 sub show_warnings( $$ ) {
1249 my $functype = shift;
1252 return 0 if (defined( $nosymbol_table { $name }));
1254 return 1 if ( $output_selection == OUTPUT_ALL);
1256 if ( $output_selection == OUTPUT_EXPORTED) {
1257 if (defined( $function_table { $name })) {
1263 if ( $output_selection == OUTPUT_INTERNAL) {
1264 if (!( $functype eq "function" && defined( $function_table { $name }))) {
1270 if ( $output_selection == OUTPUT_INCLUDE) {
1271 if (defined( $function_table { $name })) {
1277 die("Please add the new output type at show_warnings()");
1286 $x =~ s @/\* .*?\*/ @@gos ; # strip comments.
1287 # strip #define macros inside enums
1288 $x =~ s @#\s* ((define|ifdef)\s+|endif)[^;]*; @@gos ;
1290 if ( $x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) {
1291 $declaration_name = $2 ;
1293 } elsif ( $x =~ /enum\s+(\w*)\s*\{(.*)\}/) {
1294 $declaration_name = $1 ;
1299 if ( $identifier ne $declaration_name ) {
1300 if ( $identifier eq "") {
1301 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line: \n ";
1303 print STDERR "${file}:$.: warning: expecting prototype for enum $identifier . Prototype was for enum $declaration_name instead \n ";
1307 $declaration_name = "(anonymous)" if ( $declaration_name eq "");
1311 $members =~ s/\s+$//;
1313 foreach my $arg (split ',', $members ) {
1314 $arg =~ s/^\s*(\w+).*/$1/;
1315 push @parameterlist, $arg ;
1316 if (! $parameterdescs { $arg }) {
1317 $parameterdescs { $arg } = $undescribed ;
1318 if (show_warnings("enum", $declaration_name )) {
1319 print STDERR "${file}:$.: warning: Enum value ' $arg ' not described in enum ' $declaration_name ' \n ";
1322 $_members { $arg } = 1;
1325 while (my ( $k, $v ) = each %parameterdescs ) {
1326 if (!exists( $_members { $k })) {
1327 if (show_warnings("enum", $declaration_name )) {
1328 print STDERR "${file}:$.: warning: Excess enum value ' $k ' description in ' $declaration_name ' \n ";
1333 output_declaration( $declaration_name,
1335 {'enum' => $declaration_name,
1336 'module' => $modulename,
1337 'parameterlist' => \ @parameterlist,
1338 'parameterdescs' => \ %parameterdescs,
1339 'sectionlist' => \ @sectionlist,
1340 'sections' => \ %sections,
1341 'purpose' => $declaration_purpose
1344 print STDERR "${file}:$.: error: Cannot parse enum! \n ";
1349 my $typedef_type = qr { ((?:\s+[\w\*]+ \b ){1,8})\s* }x;
1350 my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
1351 my $typedef_args = qr { \s*\((.*)\); }x;
1353 my $typedef1 = qr { typedef $typedef_type\ ( $typedef_ident\ ) $typedef_args }x;
1354 my $typedef2 = qr { typedef $typedef_type$typedef_ident$typedef_args }x;
1356 sub dump_typedef( $$ ) {
1360 $x =~ s @/\* .*?\*/ @@gos ; # strip comments.
1362 # Parse function typedef prototypes
1363 if ( $x =~ $typedef1 || $x =~ $typedef2 ) {
1365 $declaration_name = $2 ;
1367 $return_type =~ s/^\s+//;
1369 if ( $identifier ne $declaration_name ) {
1370 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier . Prototype was for typedef $declaration_name instead \n ";
1374 create_parameterlist( $args, ',', $file, $declaration_name );
1376 output_declaration( $declaration_name,
1378 {'function' => $declaration_name,
1380 'module' => $modulename,
1381 'functiontype' => $return_type,
1382 'parameterlist' => \ @parameterlist,
1383 'parameterdescs' => \ %parameterdescs,
1384 'parametertypes' => \ %parametertypes,
1385 'sectionlist' => \ @sectionlist,
1386 'sections' => \ %sections,
1387 'purpose' => $declaration_purpose
1392 while (( $x =~ /\(*.\)\s*; $/ ) || ( $x =~ /\[*.\]\s*; $/ )) {
1393 $x =~ s/\(*.\)\s*;$/;/;
1394 $x =~ s/\[*.\]\s*;$/;/;
1397 if ( $x =~ /typedef.*\s+(\w+)\s*;/) {
1398 $declaration_name = $1 ;
1400 if ( $identifier ne $declaration_name ) {
1401 print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier . Prototype was for typedef $declaration_name instead \n ";
1405 output_declaration( $declaration_name,
1407 {'typedef' => $declaration_name,
1408 'module' => $modulename,
1409 'sectionlist' => \ @sectionlist,
1410 'sections' => \ %sections,
1411 'purpose' => $declaration_purpose
1415 print STDERR "${file}:$.: error: Cannot parse typedef! \n ";
1420 sub save_struct_actual($) {
1423 # strip all spaces from the actual param so that it looks like one string item
1424 $actual =~ s/\s*//g;
1425 $struct_actual = $struct_actual . $actual . " ";
1428 sub create_parameterlist( $$$$ ) {
1430 my $splitter = shift;
1432 my $declaration_name = shift;
1436 # temporarily replace commas inside function pointer definition
1437 my $arg_expr = qr{\([^\),]+};
1438 while ( $args =~ / $arg_expr,/ ) {
1439 $args =~ s/($arg_expr),/$1#/g;
1442 foreach my $arg (split( $splitter, $args )) {
1444 $arg =~ s/\/\*.*\*\///;
1445 # strip leading/trailing spaces
1451 # Treat preprocessor directive as a typeless variable just to fill
1452 # corresponding data structures "correctly". Catch it later in
1454 push_parameter( $arg, "", "", $file );
1455 } elsif ( $arg =~ m/\(.+\)\s*\(/) {
1456 # pointer-to-function
1458 $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/;
1461 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1462 save_struct_actual( $param );
1463 push_parameter( $param, $type, $arg, $file, $declaration_name );
1465 $arg =~ s/\s*:\s*/:/g;
1466 $arg =~ s/\s*\[/\[/g;
1468 my @args = split('\s*,\s*', $arg );
1469 if ( $args [0] =~ m/\*/) {
1470 $args [0] =~ s/(\*+)\s*/ $1/;
1474 if ( $args [0] =~ /^(.*\s+)(.*?\[.*\].*) $/ ) {
1476 push( @first_arg, split('\s+', $1 ));
1477 push( @first_arg, $2 );
1479 @first_arg = split('\s+', shift @args );
1482 unshift( @args, pop @first_arg );
1483 $type = join " ", @first_arg ;
1485 foreach $param ( @args ) {
1486 if ( $param =~ m/^(\*+)\s*(.*)/) {
1487 save_struct_actual( $2 );
1489 push_parameter( $2, " $type $1 ", $arg, $file, $declaration_name );
1491 elsif ( $param =~ m/(.*?):(\d+)/) {
1492 if ( $type ne "") { # skip unnamed bit-fields
1493 save_struct_actual( $1 );
1494 push_parameter( $1, " $type : $2 ", $arg, $file, $declaration_name )
1498 save_struct_actual( $param );
1499 push_parameter( $param, $type, $arg, $file, $declaration_name );
1506 sub push_parameter( $$$$$ ) {
1509 my $org_arg = shift;
1511 my $declaration_name = shift;
1513 if (( $anon_struct_union == 1) && ( $type eq "") &&
1515 return; # ignore the ending }; from anon. struct/union
1518 $anon_struct_union = 0;
1519 $param =~ s/[\[\)].*//;
1521 if ( $type eq "" && $param =~ /\.\.\. $/ )
1523 if (! $param =~ /\w\.\.\. $/ ) {
1524 # handles unnamed variable parameters
1527 elsif ( $param =~ /\w\.\.\. $/ ) {
1528 # for named variable parameters of the form ` x
... `, remove the dots
1529 $param =~ s/\.\.\.$//;
1531 if (!defined $parameterdescs { $param } || $parameterdescs { $param } eq "") {
1532 $parameterdescs { $param } = "variable arguments";
1535 elsif ( $type eq "" && ( $param eq "" or $param eq "void"))
1538 $parameterdescs {void} = "no arguments";
1540 elsif ( $type eq "" && ( $param eq "struct" or $param eq "union"))
1541 # handle unnamed (anonymous) union or struct:
1544 $param = "{unnamed_" . $param . "}";
1545 $parameterdescs { $param } = "anonymous \n ";
1546 $anon_struct_union = 1;
1549 # warn if parameter has no description
1550 # (but ignore ones starting with # as these are not parameters
1551 # but inline preprocessor statements);
1552 # Note: It will also ignore void params and unnamed structs/unions
1553 if (!defined $parameterdescs { $param } && $param !~ /^#/) {
1554 $parameterdescs { $param } = $undescribed ;
1556 if (show_warnings( $type, $declaration_name ) && $param !~ /\./) {
1558 "${file}:$.: warning: Function parameter or member ' $param ' not described in ' $declaration_name ' \n ";
1563 # strip spaces from $param so that it is one continuous string
1564 # on @parameterlist ;
1565 # this fixes a problem where check_sections() cannot find
1566 # a parameter like "addr[6 + 2]" because it actually appears
1567 # as "addr[6", "+", "2]" on the parameter list;
1568 # but it's better to maintain the param string unchanged for output,
1569 # so just weaken the string compare in check_sections() to ignore
1570 # "[blah" in a parameter string;
1571 ### $param =~ s/\s*//g;
1572 push @parameterlist, $param ;
1573 $org_arg =~ s/\s\s+/ /g;
1574 $parametertypes { $param } = $org_arg ;
1577 sub check_sections( $$$$$ ) {
1578 my ( $file, $decl_name, $decl_type, $sectcheck, $prmscheck ) = @_ ;
1579 my @sects = split ' ', $sectcheck ;
1580 my @prms = split ' ', $prmscheck ;
1583 my $prm_clean ; # strip trailing "[array size]" and/or beginning "*"
1585 foreach $sx (0 .. $#sects ) {
1587 foreach $px (0 .. $#prms ) {
1588 $prm_clean = $prms [ $px ];
1589 $prm_clean =~ s/\[.*\]//;
1590 $prm_clean =~ s/$attribute//i;
1591 # ignore array size in a parameter string;
1592 # however, the original param string may contain
1593 # spaces, e.g.: addr[6 + 2]
1594 # and this appears in @prms as "addr[6" since the
1595 # parameter list is split at spaces;
1596 # hence just ignore "[..." for the sections check;
1597 $prm_clean =~ s/\[.*//;
1599 ## $prm_clean =~ s/^\**//;
1600 if ( $prm_clean eq $sects [ $sx ]) {
1606 if ( $decl_type eq "function") {
1607 print STDERR "${file}:$.: warning: " .
1608 "Excess function parameter " .
1610 "description in ' $decl_name ' \n ";
1618 # Checks the section describing the return value of a function.
1619 sub check_return_section {
1621 my $declaration_name = shift;
1622 my $return_type = shift;
1624 # Ignore an empty return type (It's a macro)
1625 # Ignore functions with a "void" return type. (But don't ignore "void *")
1626 if (( $return_type eq "") || ( $return_type =~ /void\s*\w*\s* $/ )) {
1630 if (!defined( $sections { $section_return }) ||
1631 $sections { $section_return } eq "") {
1632 print STDERR "${file}:$.: warning: " .
1633 "No description found for return value of " .
1634 "' $declaration_name ' \n ";
1640 # takes a function prototype and the name of the current file being
1641 # processed and spits out all the details stored in the global
1643 sub dump_function( $$ ) {
1644 my $prototype = shift;
1648 print_lineno( $new_start_line );
1650 $prototype =~ s/^static +//;
1651 $prototype =~ s/^extern +//;
1652 $prototype =~ s/^asmlinkage +//;
1653 $prototype =~ s/^inline +//;
1654 $prototype =~ s/^__inline__ +//;
1655 $prototype =~ s/^__inline +//;
1656 $prototype =~ s/^__always_inline +//;
1657 $prototype =~ s/^noinline +//;
1658 $prototype =~ s/__init +//;
1659 $prototype =~ s/__init_or_module +//;
1660 $prototype =~ s/__deprecated +//;
1661 $prototype =~ s/__flatten +//;
1662 $prototype =~ s/__meminit +//;
1663 $prototype =~ s/__must_check +//;
1664 $prototype =~ s/__weak +//;
1665 $prototype =~ s/__sched +//;
1666 $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//;
1667 $prototype =~ s/__alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +//;
1668 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1669 $prototype =~ s/__attribute_const__ +//;
1670 $prototype =~ s/__attribute__\s*\(\(
1672 [\w\s]++ # attribute name
1673 (?:\([^)]*+\))? # attribute arguments
1674 \s*+,? # optional comma at the end
1678 # Yes, this truly is vile. We are looking for:
1679 # 1. Return type (may be nothing if we're looking at a macro)
1681 # 3. Function parameters.
1683 # All the while we have to watch out for function pointer parameters
1684 # (which IIRC is what the two sections are for), C types (these
1685 # regexps don't even start to express all the possibilities), and
1688 # If you mess with these regexps, it's a good idea to check that
1689 # the following functions' documentation still comes out right:
1690 # - parport_register_device (function pointer parameters)
1691 # - atomic_set (macro)
1692 # - pci_match_device, __copy_to_user (long return type)
1693 my $name = qr{[a-zA-Z0-9_~:]+};
1694 my $prototype_end1 = qr{[^\(]*};
1695 my $prototype_end2 = qr{[^\{]*};
1696 my $prototype_end = qr{\(($prototype_end1|$prototype_end2)\)};
1697 my $type1 = qr{[\w\s]+};
1698 my $type2 = qr{$type1\*+};
1700 if ( $define && $prototype =~ m/^()($name)\s+/) {
1701 # This is an object-like macro, it has no return type and no parameter
1703 # Function-like macros are not allowed to have spaces between
1704 # declaration_name and opening parenthesis (notice the \s+).
1706 $declaration_name = $2 ;
1708 } elsif ( $prototype =~ m/^()($name)\s*$prototype_end/ ||
1709 $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
1710 $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/) {
1712 $declaration_name = $2 ;
1715 create_parameterlist( $args, ',', $file, $declaration_name );
1717 print STDERR "${file}:$.: warning: cannot understand function prototype: ' $prototype ' \n ";
1721 if ( $identifier ne $declaration_name ) {
1722 print STDERR "${file}:$.: warning: expecting prototype for $identifier (). Prototype was for $declaration_name () instead \n ";
1726 my $prms = join " ", @parameterlist ;
1727 check_sections( $file, $declaration_name, "function", $sectcheck, $prms );
1729 # This check emits a lot of warnings at the moment, because many
1730 # functions don't have a 'Return' doc section. So until the number
1731 # of warnings goes sufficiently down, the check is only performed in
1733 # TODO: always perform the check.
1734 if ( $verbose && ! $noret ) {
1735 check_return_section( $file, $declaration_name, $return_type );
1738 # The function parser can be called with a typedef parameter.
1740 if ( $return_type =~ /typedef/) {
1741 output_declaration( $declaration_name,
1743 {'function' => $declaration_name,
1745 'module' => $modulename,
1746 'functiontype' => $return_type,
1747 'parameterlist' => \ @parameterlist,
1748 'parameterdescs' => \ %parameterdescs,
1749 'parametertypes' => \ %parametertypes,
1750 'sectionlist' => \ @sectionlist,
1751 'sections' => \ %sections,
1752 'purpose' => $declaration_purpose
1755 output_declaration( $declaration_name,
1757 {'function' => $declaration_name,
1758 'module' => $modulename,
1759 'functiontype' => $return_type,
1760 'parameterlist' => \ @parameterlist,
1761 'parameterdescs' => \ %parameterdescs,
1762 'parametertypes' => \ %parametertypes,
1763 'sectionlist' => \ @sectionlist,
1764 'sections' => \ %sections,
1765 'purpose' => $declaration_purpose
1772 %parameterdescs = ();
1773 %parametertypes = ();
1774 @parameterlist = ();
1778 $struct_actual = "";
1781 $state = STATE_NORMAL;
1782 $inline_doc_state = STATE_INLINE_NA;
1785 sub tracepoint_munge($) {
1787 my $tracepointname = 0;
1788 my $tracepointargs = 0;
1790 if ( $prototype =~ m/TRACE_EVENT\((.*?),/) {
1791 $tracepointname = $1 ;
1793 if ( $prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
1794 $tracepointname = $1 ;
1796 if ( $prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1797 $tracepointname = $2 ;
1799 $tracepointname =~ s/^\s+//; #strip leading whitespace
1800 if ( $prototype =~ m/TP_PROTO\((.*?)\)/) {
1801 $tracepointargs = $1 ;
1803 if (( $tracepointname eq 0) || ( $tracepointargs eq 0)) {
1804 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n ".
1807 $prototype = "static inline void trace_ $tracepointname ( $tracepointargs )";
1808 $identifier = "trace_ $identifier ";
1812 sub syscall_munge() {
1815 $prototype =~ s@[ \r\n ]+@ @gos ; # strip newlines/CR's
1816 ## if ( $prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1817 if ( $prototype =~ m/SYSCALL_DEFINE0/) {
1819 ## $prototype = "long sys_ $1 (void)";
1822 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1823 if ( $prototype =~ m/long (sys_.*?),/) {
1824 $prototype =~ s/,/\(/;
1826 $prototype =~ s/\)/\(void\)/;
1829 # now delete all of the odd-number commas in $prototype
1830 # so that arg types & arg names don't have a comma between them
1832 my $len = length( $prototype );
1834 $len = 0; # skip the for-loop
1836 for (my $ix = 0; $ix < $len ; $ix++ ) {
1837 if (substr( $prototype, $ix, 1) eq ',') {
1839 if ( $count % 2 == 1) {
1840 substr( $prototype, $ix, 1) = ' ';
1846 sub process_proto_function( $$ ) {
1850 $x =~ s @\/\/ .* $@@gos ; # strip C99-style comments to end of line
1852 if ( $x =~ m#\s*/\*\s+MACDOC\s*#io || ( $x =~ /^#/ && $x !~ /^#\s*define/)) {
1855 elsif ( $x =~ /([^\{]*)/) {
1859 if (( $x =~ /\{/) || ( $x =~ /\#\s*define/) || ( $x =~ /;/)) {
1860 $prototype =~ s @/\* .*?\*/ @@gos ; # strip comments.
1861 $prototype =~ s@[ \r\n ]+@ @gos ; # strip newlines/cr's.
1862 $prototype =~ s @^\s+@@gos ; # strip leading spaces
1864 # Handle prototypes for function pointers like:
1865 # int (*pcs_config)(struct foo)
1866 $prototype =~ s @^ (\S+\s+)\(\s*\*(\S+)\) @$1$2@gos ;
1868 if ( $prototype =~ /SYSCALL_DEFINE/) {
1871 if ( $prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1872 $prototype =~ /DEFINE_SINGLE_EVENT/)
1874 tracepoint_munge( $file );
1876 dump_function( $prototype, $file );
1881 sub process_proto_type( $$ ) {
1885 $x =~ s@[ \r\n ]+@ @gos ; # strip newlines/cr's.
1886 $x =~ s @^\s+@@gos ; # strip leading spaces
1887 $x =~ s @\s+$@@gos ; # strip trailing spaces
1888 $x =~ s @\/\/ .* $@@gos ; # strip C99-style comments to end of line
1891 # To distinguish preprocessor directive from regular declaration later.
1896 if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
1897 if( length $prototype ) {
1900 $prototype .= $1 . $2 ;
1901 ( $2 eq '{') && $brcount++ ;
1902 ( $2 eq '}') && $brcount --;
1903 if (( $2 eq ';') && ( $brcount == 0)) {
1904 dump_declaration( $prototype, $file );
1917 sub map_filename($) {
1919 my ( $orig_file ) = @_ ;
1921 if (defined( $ENV {'SRCTREE'})) {
1922 $file = " $ENV {'SRCTREE'}" . "/" . $orig_file ;
1927 if (defined( $source_map { $file })) {
1928 $file = $source_map { $file };
1934 sub process_export_file($) {
1935 my ( $orig_file ) = @_ ;
1936 my $file = map_filename( $orig_file );
1938 if (!open(IN,"< $file ")) {
1939 print STDERR "Error: Cannot open file $file\n ";
1945 if (/ $export_symbol/ ) {
1946 next if (defined( $nosymbol_table { $2 }));
1947 $function_table { $2 } = 1;
1955 # Parsers for the various processing states.
1957 # STATE_NORMAL: looking for the /** to begin everything.
1959 sub process_normal() {
1960 if (/ $doc_start/o ) {
1961 $state = STATE_NAME; # next line is always the function name
1963 $declaration_start_line = $. + 1;
1968 # STATE_NAME: Looking for the "name - description" line
1970 sub process_name( $$ ) {
1974 if (/ $doc_block/o ) {
1975 $state = STATE_DOCBLOCK;
1977 $new_start_line = $.;
1980 $section = $section_intro ;
1984 } elsif (/ $doc_decl/o ) {
1986 my $is_kernel_comment = 0;
1987 my $decl_start = qr{$doc_com};
1988 # test for pointer declaration type, foo * bar() - desc
1989 my $fn_type = qr{\w+\s*\*\s*};
1990 my $parenthesis = qr{\(\w*\)};
1991 my $decl_end = qr{[-:].*};
1992 if (/^ $decl_start ([\w\s]+?) $parenthesis?\s*$decl_end?$/ ) {
1995 if ( $identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
1998 $is_kernel_comment = 1;
2000 # Look for foo() or static void foo() - description; or misspelt
2002 elsif (/^ $decl_start$fn_type? (\w+)\s* $parenthesis?\s*$decl_end?$/ ||
2003 /^ $decl_start$fn_type? (\w+.*) $parenthesis?\s*$decl_end$/ ) {
2005 $decl_type = 'function';
2006 $identifier =~ s/^define\s+//;
2007 $is_kernel_comment = 1;
2009 $identifier =~ s/\s+$//;
2011 $state = STATE_BODY;
2012 # if there's no @param blocks need to set up default section
2015 $section = $section_default ;
2016 $new_start_line = $. + 1;
2018 # strip leading/trailing/multiple spaces
2022 $descr =~ s/\s+/ /g;
2023 $declaration_purpose = $descr ;
2024 $state = STATE_BODY_MAYBE;
2026 $declaration_purpose = "";
2029 if (! $is_kernel_comment ) {
2030 print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst \n ";
2033 $state = STATE_NORMAL;
2036 if (( $declaration_purpose eq "") && $verbose ) {
2037 print STDERR "${file}:$.: warning: missing initial short description on line: \n ";
2042 if ( $identifier eq "" && $decl_type ne "enum") {
2043 print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line: \n ";
2046 $state = STATE_NORMAL;
2050 print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n ";
2053 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2054 " - I thought it was a doc line \n ";
2056 $state = STATE_NORMAL;
2062 # STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
2064 sub process_body( $$ ) {
2067 # Until all named variable macro parameters are
2068 # documented using the bare name (` x
`) rather than with
2069 # dots (` x
... `), strip the dots:
2070 if ( $section =~ /\w\.\.\. $/ ) {
2071 $section =~ s/\.\.\.$//;
2074 print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots \n ";
2079 if ( $state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) {
2080 dump_section( $file, $section, $contents );
2081 $section = $section_default ;
2082 $new_start_line = $.;
2086 if (/ $doc_sect/i ) { # case insensitive for supported section names
2090 # map the supported section names to the canonical names
2091 if ( $newsection =~ m/^description$/i) {
2092 $newsection = $section_default ;
2093 } elsif ( $newsection =~ m/^context$/i) {
2094 $newsection = $section_context ;
2095 } elsif ( $newsection =~ m/^returns?$/i) {
2096 $newsection = $section_return ;
2097 } elsif ( $newsection =~ m/^\@return$/) {
2098 # special: @return is a section, not a param description
2099 $newsection = $section_return ;
2102 if (( $contents ne "") && ( $contents ne " \n ")) {
2103 if (! $in_doc_sect && $verbose ) {
2104 print STDERR "${file}:$.: warning: contents before sections \n ";
2107 dump_section( $file, $section, $contents );
2108 $section = $section_default ;
2112 $state = STATE_BODY;
2113 $contents = $newcontents ;
2114 $new_start_line = $.;
2115 while (substr( $contents, 0, 1) eq " ") {
2116 $contents = substr( $contents, 1);
2118 if ( $contents ne "") {
2121 $section = $newsection ;
2122 $leading_space = undef;
2123 } elsif (/ $doc_end/ ) {
2124 if (( $contents ne "") && ( $contents ne " \n ")) {
2125 dump_section( $file, $section, $contents );
2126 $section = $section_default ;
2129 # look for doc_com + <text> + doc_end:
2130 if ( $_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2131 print STDERR "${file}:$.: warning: suspicious ending line: $_ ";
2136 $state = STATE_PROTO;
2138 $new_start_line = $. + 1;
2139 } elsif (/ $doc_content/ ) {
2141 if ( $section eq $section_context ) {
2142 dump_section( $file, $section, $contents );
2143 $section = $section_default ;
2145 $new_start_line = $.;
2146 $state = STATE_BODY;
2148 if ( $section ne $section_default ) {
2149 $state = STATE_BODY_WITH_BLANK_LINE;
2151 $state = STATE_BODY;
2155 } elsif ( $state == STATE_BODY_MAYBE) {
2156 # Continued declaration purpose
2157 chomp( $declaration_purpose );
2158 $declaration_purpose .= " " . $1 ;
2159 $declaration_purpose =~ s/\s+/ /g;
2162 if ( $section =~ m/^@/ || $section eq $section_context ) {
2163 if (!defined $leading_space ) {
2164 if ( $cont =~ m/^(\s+)/) {
2165 $leading_space = $1 ;
2167 $leading_space = "";
2170 $cont =~ s/^$leading_space//;
2172 $contents .= $cont . " \n ";
2175 # i dont know - bad line? ignore.
2176 print STDERR "${file}:$.: warning: bad line: $_ ";
2183 # STATE_PROTO: reading a function/whatever prototype.
2185 sub process_proto( $$ ) {
2188 if (/ $doc_inline_oneline/ ) {
2191 if ( $contents ne "") {
2193 dump_section( $file, $section, $contents );
2194 $section = $section_default ;
2197 } elsif (/ $doc_inline_start/ ) {
2198 $state = STATE_INLINE;
2199 $inline_doc_state = STATE_INLINE_NAME;
2200 } elsif ( $decl_type eq 'function') {
2201 process_proto_function( $_, $file );
2203 process_proto_type( $_, $file );
2208 # STATE_DOCBLOCK: within a DOC: block.
2210 sub process_docblock( $$ ) {
2214 dump_doc_section( $file, $section, $contents );
2215 $section = $section_default ;
2218 %parameterdescs = ();
2219 %parametertypes = ();
2220 @parameterlist = ();
2224 $state = STATE_NORMAL;
2225 } elsif (/ $doc_content/ ) {
2227 $contents .= $blankline ;
2229 $contents .= $1 . " \n ";
2235 # STATE_INLINE: docbook comments within a prototype.
2237 sub process_inline( $$ ) {
2240 # First line (state 1) needs to be a @parameter
2241 if ( $inline_doc_state == STATE_INLINE_NAME && / $doc_inline_sect/o ) {
2244 $new_start_line = $.;
2245 if ( $contents ne "") {
2246 while (substr( $contents, 0, 1) eq " ") {
2247 $contents = substr( $contents, 1);
2251 $inline_doc_state = STATE_INLINE_TEXT;
2252 # Documentation block end */
2253 } elsif (/ $doc_inline_end/ ) {
2254 if (( $contents ne "") && ( $contents ne " \n ")) {
2255 dump_section( $file, $section, $contents );
2256 $section = $section_default ;
2259 $state = STATE_PROTO;
2260 $inline_doc_state = STATE_INLINE_NA;
2262 } elsif (/ $doc_content/ ) {
2263 if ( $inline_doc_state == STATE_INLINE_TEXT) {
2264 $contents .= $1 . " \n ";
2265 # nuke leading blank lines
2266 if ( $contents =~ /^\s* $/ ) {
2269 } elsif ( $inline_doc_state == STATE_INLINE_NAME) {
2270 $inline_doc_state = STATE_INLINE_ERROR;
2271 print STDERR "${file}:$.: warning: ";
2272 print STDERR "Incorrect use of kernel-doc format: $_ ";
2279 sub process_file($) {
2281 my $initial_section_counter = $section_counter ;
2282 my ( $orig_file ) = @_ ;
2284 $file = map_filename( $orig_file );
2286 if (!open(IN_FILE,"< $file ")) {
2287 print STDERR "Error: Cannot open file $file\n ";
2294 $section_counter = 0;
2296 while (s/\\\s*$//) {
2299 # Replace tabs by spaces
2300 while ( $_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
2301 # Hand this line to the appropriate state handler
2302 if ( $state == STATE_NORMAL) {
2304 } elsif ( $state == STATE_NAME) {
2305 process_name( $file, $_ );
2306 } elsif ( $state == STATE_BODY || $state == STATE_BODY_MAYBE ||
2307 $state == STATE_BODY_WITH_BLANK_LINE) {
2308 process_body( $file, $_ );
2309 } elsif ( $state == STATE_INLINE) { # scanning for inline parameters
2310 process_inline( $file, $_ );
2311 } elsif ( $state == STATE_PROTO) {
2312 process_proto( $file, $_ );
2313 } elsif ( $state == STATE_DOCBLOCK) {
2314 process_docblock( $file, $_ );
2318 # Make sure we got something interesting.
2319 if ( $initial_section_counter == $section_counter && $
2320 output_mode ne "none") {
2321 if ( $output_selection == OUTPUT_INCLUDE) {
2322 print STDERR "${file}:1: warning: ' $_ ' not found \n "
2323 for keys %function_table ;
2326 print STDERR "${file}:1: warning: no structured comments found \n ";
2333 if ( $output_mode eq "rst") {
2334 get_sphinx_version() if (! $sphinx_major );
2337 $kernelversion = get_kernel_version();
2339 # generate a sequence of code that will splice in highlighting information
2340 # using the s// operator.
2341 for (my $k = 0; $k < @highlights ; $k++ ) {
2342 my $pattern = $highlights [ $k ][0];
2343 my $result = $highlights [ $k ][1];
2344 # print STDERR "scanning pattern: $pattern, highlight:( $result ) \n ";
2345 $dohighlight .= "\ $contents =~ s: $pattern : $result :gs; \n ";
2348 # Read the file that maps relative names to absolute names for
2349 # separate source and object directories and for shadow trees.
2350 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2351 my ( $relname, $absname );
2352 while(<SOURCE_MAP>) {
2354 ( $relname, $absname ) = (split())[0..1];
2355 $relname =~ s:^/+::;
2356 $source_map { $relname } = $absname ;
2361 if ( $output_selection == OUTPUT_EXPORTED ||
2362 $output_selection == OUTPUT_INTERNAL) {
2364 push( @export_file_list, @ARGV );
2366 foreach ( @export_file_list ) {
2368 process_export_file( $_ );
2376 if ( $verbose && $errors ) {
2377 print STDERR " $errors errors \n ";
2379 if ( $verbose && $warnings ) {
2380 print STDERR " $warnings warnings \n ";
2383 if ( $Werror && $warnings ) {
2384 print STDERR " $warnings warnings as Errors \n ";
2387 exit( $output_mode eq "none" ? 0 : $errors )
2394 =head2 Output format selection (mutually exclusive):
2400 Output troff manual page format.
2404 Output reStructuredText format. This is the default.
2408 Do not output documentation, only warnings.
2412 =head2 Output format modifiers
2414 =head3 reStructuredText only
2418 =item -sphinx-version VERSION
2420 Use the ReST C domain dialect compatible with a specific Sphinx Version.
2422 If not specified, kernel-doc will auto-detect using the sphinx-build version
2427 =head2 Output selection (mutually exclusive):
2433 Only output documentation for the symbols that have been exported using
2434 EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
2438 Only output documentation for the symbols that have NOT been exported using
2439 EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
2441 =item -function NAME
2443 Only output documentation for the given function or DOC: section title.
2444 All other functions and DOC: sections are ignored.
2446 May be specified multiple times.
2448 =item -nosymbol NAME
2450 Exclude the specified symbol from the output documentation.
2452 May be specified multiple times.
2456 =head2 Output selection modifiers:
2460 =item -no-doc-sections
2462 Do not output DOC: sections.
2464 =item -export-file FILE
2466 Specify an additional FILE in which to look for EXPORT_SYMBOL() and
2467 EXPORT_SYMBOL_GPL().
2469 To be used with -export or -internal.
2471 May be specified multiple times.
2475 =head3 reStructuredText only
2479 =item -enable-lineno
2481 Enable output of .. LINENO lines.
2485 =head2 Other parameters:
2495 Verbose output, more warnings and other information.
2499 Treat warnings as errors.