1cb77f0d6SKamil Rytarowski#!/usr/bin/env perl 238476378SJonathan Corbet# SPDX-License-Identifier: GPL-2.0 31da177e4SLinus Torvalds 4cb77f0d6SKamil Rytarowskiuse warnings; 51da177e4SLinus Torvaldsuse strict; 61da177e4SLinus Torvalds 71da177e4SLinus Torvalds## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## 81da177e4SLinus Torvalds## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## 91da177e4SLinus Torvalds## Copyright (C) 2001 Simon Huggins ## 1070c95b00SRandy Dunlap## Copyright (C) 2005-2012 Randy Dunlap ## 111b40c194SDan Luedtke## Copyright (C) 2012 Dan Luedtke ## 121da177e4SLinus Torvalds## ## 131da177e4SLinus Torvalds## #define enhancements by Armin Kuster <akuster@mvista.com> ## 141da177e4SLinus Torvalds## Copyright (c) 2000 MontaVista Software, Inc. ## 151da177e4SLinus Torvalds## ## 161da177e4SLinus Torvalds## This software falls under the GNU General Public License. ## 171da177e4SLinus Torvalds## Please read the COPYING file for more information ## 181da177e4SLinus Torvalds 191da177e4SLinus Torvalds# 18/01/2001 - Cleanups 201da177e4SLinus Torvalds# Functions prototyped as foo(void) same as foo() 211da177e4SLinus Torvalds# Stop eval'ing where we don't need to. 221da177e4SLinus Torvalds# -- huggie@earth.li 231da177e4SLinus Torvalds 241da177e4SLinus Torvalds# 27/06/2001 - Allowed whitespace after initial "/**" and 251da177e4SLinus Torvalds# allowed comments before function declarations. 261da177e4SLinus Torvalds# -- Christian Kreibich <ck@whoop.org> 271da177e4SLinus Torvalds 281da177e4SLinus Torvalds# Still to do: 291da177e4SLinus Torvalds# - add perldoc documentation 301da177e4SLinus Torvalds# - Look more closely at some of the scarier bits :) 311da177e4SLinus Torvalds 321da177e4SLinus Torvalds# 26/05/2001 - Support for separate source and object trees. 331da177e4SLinus Torvalds# Return error code. 341da177e4SLinus Torvalds# Keith Owens <kaos@ocs.com.au> 351da177e4SLinus Torvalds 361da177e4SLinus Torvalds# 23/09/2001 - Added support for typedefs, structs, enums and unions 371da177e4SLinus Torvalds# Support for Context section; can be terminated using empty line 381da177e4SLinus Torvalds# Small fixes (like spaces vs. \s in regex) 391da177e4SLinus Torvalds# -- Tim Jansen <tim@tjansen.de> 401da177e4SLinus Torvalds 411b40c194SDan Luedtke# 25/07/2012 - Added support for HTML5 421b40c194SDan Luedtke# -- Dan Luedtke <mail@danrl.de> 431da177e4SLinus Torvalds 44fadc0b31SJani Nikulasub usage { 45fadc0b31SJani Nikula my $message = <<"EOF"; 46fadc0b31SJani NikulaUsage: $0 [OPTION ...] FILE ... 471da177e4SLinus Torvalds 48fadc0b31SJani NikulaRead C language source or header FILEs, extract embedded documentation comments, 49fadc0b31SJani Nikulaand print formatted documentation to standard output. 501da177e4SLinus Torvalds 51fadc0b31SJani NikulaThe documentation comments are identified by "/**" opening comment mark. See 52857af3b7SMauro Carvalho ChehabDocumentation/doc-guide/kernel-doc.rst for the documentation comment syntax. 53fadc0b31SJani Nikula 54fadc0b31SJani NikulaOutput format selection (mutually exclusive): 55fadc0b31SJani Nikula -man Output troff manual page format. This is the default. 56c0d1b6eeSJonathan Corbet -rst Output reStructuredText format. 573a025e1dSMatthew Wilcox -none Do not output documentation, only warnings. 58fadc0b31SJani Nikula 5993351d41SMauro Carvalho ChehabOutput format selection modifier (affects only ReST output): 6093351d41SMauro Carvalho Chehab 6193351d41SMauro Carvalho Chehab -sphinx-version Use the ReST C domain dialect compatible with an 6293351d41SMauro Carvalho Chehab specific Sphinx Version. 6393351d41SMauro Carvalho Chehab If not specified, kernel-doc will auto-detect using 6493351d41SMauro Carvalho Chehab the sphinx-build version found on PATH. 6593351d41SMauro Carvalho Chehab 66fadc0b31SJani NikulaOutput selection (mutually exclusive): 6786ae2e38SJani Nikula -export Only output documentation for symbols that have been 6886ae2e38SJani Nikula exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() 69c9b2cfb3SJani Nikula in any input FILE or -export-file FILE. 7086ae2e38SJani Nikula -internal Only output documentation for symbols that have NOT been 7186ae2e38SJani Nikula exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() 72c9b2cfb3SJani Nikula in any input FILE or -export-file FILE. 73fadc0b31SJani Nikula -function NAME Only output documentation for the given function(s) 74fadc0b31SJani Nikula or DOC: section title(s). All other functions and DOC: 75fadc0b31SJani Nikula sections are ignored. May be specified multiple times. 76eab795ddSMauro Carvalho Chehab -nosymbol NAME Exclude the specified symbols from the output 77eab795ddSMauro Carvalho Chehab documentation. May be specified multiple times. 78fadc0b31SJani Nikula 79fadc0b31SJani NikulaOutput selection modifiers: 80fadc0b31SJani Nikula -no-doc-sections Do not output DOC: sections. 810b0f5f29SDaniel Vetter -enable-lineno Enable output of #define LINENO lines. Only works with 820b0f5f29SDaniel Vetter reStructuredText format. 8388c2b57dSJani Nikula -export-file FILE Specify an additional FILE in which to look for 8488c2b57dSJani Nikula EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with 8588c2b57dSJani Nikula -export or -internal. May be specified multiple times. 86fadc0b31SJani Nikula 87fadc0b31SJani NikulaOther parameters: 88fadc0b31SJani Nikula -v Verbose output, more warnings and other information. 89fadc0b31SJani Nikula -h Print this help. 902c12c810SPierre-Louis Bossart -Werror Treat warnings as errors. 91fadc0b31SJani Nikula 92fadc0b31SJani NikulaEOF 93fadc0b31SJani Nikula print $message; 94fadc0b31SJani Nikula exit 1; 95fadc0b31SJani Nikula} 961da177e4SLinus Torvalds 971da177e4SLinus Torvalds# 981da177e4SLinus Torvalds# format of comments. 991da177e4SLinus Torvalds# In the following table, (...)? signifies optional structure. 1001da177e4SLinus Torvalds# (...)* signifies 0 or more structure elements 1011da177e4SLinus Torvalds# /** 1021da177e4SLinus Torvalds# * function_name(:)? (- short description)? 1031da177e4SLinus Torvalds# (* @parameterx: (description of parameter x)?)* 1041da177e4SLinus Torvalds# (* a blank line)? 1051da177e4SLinus Torvalds# * (Description:)? (Description of function)? 1061da177e4SLinus Torvalds# * (section header: (section description)? )* 1071da177e4SLinus Torvalds# (*)?*/ 1081da177e4SLinus Torvalds# 1091da177e4SLinus Torvalds# So .. the trivial example would be: 1101da177e4SLinus Torvalds# 1111da177e4SLinus Torvalds# /** 1121da177e4SLinus Torvalds# * my_function 113b9d97328SRandy Dunlap# */ 1141da177e4SLinus Torvalds# 115891dcd2fSRandy Dunlap# If the Description: header tag is omitted, then there must be a blank line 1161da177e4SLinus Torvalds# after the last parameter specification. 1171da177e4SLinus Torvalds# e.g. 1181da177e4SLinus Torvalds# /** 1191da177e4SLinus Torvalds# * my_function - does my stuff 1201da177e4SLinus Torvalds# * @my_arg: its mine damnit 1211da177e4SLinus Torvalds# * 1221da177e4SLinus Torvalds# * Does my stuff explained. 1231da177e4SLinus Torvalds# */ 1241da177e4SLinus Torvalds# 1251da177e4SLinus Torvalds# or, could also use: 1261da177e4SLinus Torvalds# /** 1271da177e4SLinus Torvalds# * my_function - does my stuff 1281da177e4SLinus Torvalds# * @my_arg: its mine damnit 1291da177e4SLinus Torvalds# * Description: Does my stuff explained. 1301da177e4SLinus Torvalds# */ 1311da177e4SLinus Torvalds# etc. 1321da177e4SLinus Torvalds# 133b9d97328SRandy Dunlap# Besides functions you can also write documentation for structs, unions, 1341da177e4SLinus Torvalds# enums and typedefs. Instead of the function name you must write the name 1351da177e4SLinus Torvalds# of the declaration; the struct/union/enum/typedef must always precede 1361da177e4SLinus Torvalds# the name. Nesting of declarations is not supported. 1371da177e4SLinus Torvalds# Use the argument mechanism to document members or constants. 1381da177e4SLinus Torvalds# e.g. 1391da177e4SLinus Torvalds# /** 1401da177e4SLinus Torvalds# * struct my_struct - short description 1411da177e4SLinus Torvalds# * @a: first member 1421da177e4SLinus Torvalds# * @b: second member 1431da177e4SLinus Torvalds# * 1441da177e4SLinus Torvalds# * Longer description 1451da177e4SLinus Torvalds# */ 1461da177e4SLinus Torvalds# struct my_struct { 1471da177e4SLinus Torvalds# int a; 1481da177e4SLinus Torvalds# int b; 149aeec46b9SMartin Waitz# /* private: */ 150aeec46b9SMartin Waitz# int c; 1511da177e4SLinus Torvalds# }; 1521da177e4SLinus Torvalds# 1531da177e4SLinus Torvalds# All descriptions can be multiline, except the short function description. 1541da177e4SLinus Torvalds# 155a4c6ebedSDanilo Cesar Lemes de Paula# For really longs structs, you can also describe arguments inside the 156a4c6ebedSDanilo Cesar Lemes de Paula# body of the struct. 157a4c6ebedSDanilo Cesar Lemes de Paula# eg. 158a4c6ebedSDanilo Cesar Lemes de Paula# /** 159a4c6ebedSDanilo Cesar Lemes de Paula# * struct my_struct - short description 160a4c6ebedSDanilo Cesar Lemes de Paula# * @a: first member 161a4c6ebedSDanilo Cesar Lemes de Paula# * @b: second member 162a4c6ebedSDanilo Cesar Lemes de Paula# * 163a4c6ebedSDanilo Cesar Lemes de Paula# * Longer description 164a4c6ebedSDanilo Cesar Lemes de Paula# */ 165a4c6ebedSDanilo Cesar Lemes de Paula# struct my_struct { 166a4c6ebedSDanilo Cesar Lemes de Paula# int a; 167a4c6ebedSDanilo Cesar Lemes de Paula# int b; 168a4c6ebedSDanilo Cesar Lemes de Paula# /** 169a4c6ebedSDanilo Cesar Lemes de Paula# * @c: This is longer description of C 170a4c6ebedSDanilo Cesar Lemes de Paula# * 171a4c6ebedSDanilo Cesar Lemes de Paula# * You can use paragraphs to describe arguments 172a4c6ebedSDanilo Cesar Lemes de Paula# * using this method. 173a4c6ebedSDanilo Cesar Lemes de Paula# */ 174a4c6ebedSDanilo Cesar Lemes de Paula# int c; 175a4c6ebedSDanilo Cesar Lemes de Paula# }; 176a4c6ebedSDanilo Cesar Lemes de Paula# 177a4c6ebedSDanilo Cesar Lemes de Paula# This should be use only for struct/enum members. 178a4c6ebedSDanilo Cesar Lemes de Paula# 1791da177e4SLinus Torvalds# You can also add additional sections. When documenting kernel functions you 1801da177e4SLinus Torvalds# should document the "Context:" of the function, e.g. whether the functions 1811da177e4SLinus Torvalds# can be called form interrupts. Unlike other sections you can end it with an 1821da177e4SLinus Torvalds# empty line. 1834092bac7SYacine Belkadi# A non-void function should have a "Return:" section describing the return 1844092bac7SYacine Belkadi# value(s). 1851da177e4SLinus Torvalds# Example-sections should contain the string EXAMPLE so that they are marked 1861da177e4SLinus Torvalds# appropriately in DocBook. 1871da177e4SLinus Torvalds# 1881da177e4SLinus Torvalds# Example: 1891da177e4SLinus Torvalds# /** 1901da177e4SLinus Torvalds# * user_function - function that can only be called in user context 1911da177e4SLinus Torvalds# * @a: some argument 1921da177e4SLinus Torvalds# * Context: !in_interrupt() 1931da177e4SLinus Torvalds# * 1941da177e4SLinus Torvalds# * Some description 1951da177e4SLinus Torvalds# * Example: 1961da177e4SLinus Torvalds# * user_function(22); 1971da177e4SLinus Torvalds# */ 1981da177e4SLinus Torvalds# ... 1991da177e4SLinus Torvalds# 2001da177e4SLinus Torvalds# 2011da177e4SLinus Torvalds# All descriptive text is further processed, scanning for the following special 2021da177e4SLinus Torvalds# patterns, which are highlighted appropriately. 2031da177e4SLinus Torvalds# 2041da177e4SLinus Torvalds# 'funcname()' - function 2051da177e4SLinus Torvalds# '$ENVVAR' - environmental variable 2061da177e4SLinus Torvalds# '&struct_name' - name of a structure (up to two words including 'struct') 2075267dd35SPaolo Bonzini# '&struct_name.member' - name of a structure member 2081da177e4SLinus Torvalds# '@parameter' - name of a parameter 2091da177e4SLinus Torvalds# '%CONST' - name of a constant. 210b97f193aSMauro Carvalho Chehab# '``LITERAL``' - literal string without any spaces on it. 2111da177e4SLinus Torvalds 2128484baaaSRandy Dunlap## init lots of data 2138484baaaSRandy Dunlap 2141da177e4SLinus Torvaldsmy $errors = 0; 2151da177e4SLinus Torvaldsmy $warnings = 0; 2165f8c7c98SRandy Dunlapmy $anon_struct_union = 0; 2171da177e4SLinus Torvalds 2181da177e4SLinus Torvalds# match expressions used to find embedded type information 219b97f193aSMauro Carvalho Chehabmy $type_constant = '\b``([^\`]+)``\b'; 220b97f193aSMauro Carvalho Chehabmy $type_constant2 = '\%([-_\w]+)'; 2211da177e4SLinus Torvaldsmy $type_func = '(\w+)\(\)'; 222bfd228c7SMike Rapoportmy $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; 223ee2aa759SMauro Carvalho Chehabmy $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; 2245219f18aSJonathan Corbetmy $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params 225346282dbSMauro Carvalho Chehabmy $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params 2261da177e4SLinus Torvaldsmy $type_env = '(\$\w+)'; 227df31175bSPaolo Bonzinimy $type_enum = '\&(enum\s*([_\w]+))'; 228df31175bSPaolo Bonzinimy $type_struct = '\&(struct\s*([_\w]+))'; 229df31175bSPaolo Bonzinimy $type_typedef = '\&(typedef\s*([_\w]+))'; 230df31175bSPaolo Bonzinimy $type_union = '\&(union\s*([_\w]+))'; 2315267dd35SPaolo Bonzinimy $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; 232df31175bSPaolo Bonzinimy $type_fallback = '\&([_\w]+)'; 233f3341dcfSJani Nikulamy $type_member_func = $type_member . '\(\)'; 2341da177e4SLinus Torvalds 2351da177e4SLinus Torvalds# Output conversion substitutions. 2361da177e4SLinus Torvalds# One for each output format 2371da177e4SLinus Torvalds 2381da177e4SLinus Torvalds# these are pretty rough 2394d732701SDanilo Cesar Lemes de Paulamy @highlights_man = ( 2404d732701SDanilo Cesar Lemes de Paula [$type_constant, "\$1"], 241b97f193aSMauro Carvalho Chehab [$type_constant2, "\$1"], 2424d732701SDanilo Cesar Lemes de Paula [$type_func, "\\\\fB\$1\\\\fP"], 243df31175bSPaolo Bonzini [$type_enum, "\\\\fI\$1\\\\fP"], 2444d732701SDanilo Cesar Lemes de Paula [$type_struct, "\\\\fI\$1\\\\fP"], 245df31175bSPaolo Bonzini [$type_typedef, "\\\\fI\$1\\\\fP"], 246df31175bSPaolo Bonzini [$type_union, "\\\\fI\$1\\\\fP"], 2475267dd35SPaolo Bonzini [$type_param, "\\\\fI\$1\\\\fP"], 248ee2aa759SMauro Carvalho Chehab [$type_param_ref, "\\\\fI\$1\$2\\\\fP"], 249df31175bSPaolo Bonzini [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], 250df31175bSPaolo Bonzini [$type_fallback, "\\\\fI\$1\\\\fP"] 2514d732701SDanilo Cesar Lemes de Paula ); 2521da177e4SLinus Torvaldsmy $blankline_man = ""; 2531da177e4SLinus Torvalds 254c0d1b6eeSJonathan Corbet# rst-mode 255c0d1b6eeSJonathan Corbetmy @highlights_rst = ( 256c0d1b6eeSJonathan Corbet [$type_constant, "``\$1``"], 257b97f193aSMauro Carvalho Chehab [$type_constant2, "``\$1``"], 258f3341dcfSJani Nikula # Note: need to escape () to avoid func matching later 2595267dd35SPaolo Bonzini [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], 2605267dd35SPaolo Bonzini [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], 2615219f18aSJonathan Corbet [$type_fp_param, "**\$1\\\\(\\\\)**"], 262346282dbSMauro Carvalho Chehab [$type_fp_param2, "**\$1\\\\(\\\\)**"], 263344fdb28SJonathan Corbet [$type_func, "\$1()"], 264df31175bSPaolo Bonzini [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], 265df31175bSPaolo Bonzini [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], 266df31175bSPaolo Bonzini [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], 267df31175bSPaolo Bonzini [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], 268a7291e7eSJani Nikula # in rst this can refer to any type 269df31175bSPaolo Bonzini [$type_fallback, "\\:c\\:type\\:`\$1`"], 270ee2aa759SMauro Carvalho Chehab [$type_param_ref, "**\$1\$2**"] 271c0d1b6eeSJonathan Corbet ); 272c0d1b6eeSJonathan Corbetmy $blankline_rst = "\n"; 273c0d1b6eeSJonathan Corbet 2741da177e4SLinus Torvalds# read arguments 2751da177e4SLinus Torvaldsif ($#ARGV == -1) { 2761da177e4SLinus Torvalds usage(); 2771da177e4SLinus Torvalds} 2781da177e4SLinus Torvalds 2798484baaaSRandy Dunlapmy $kernelversion; 28093351d41SMauro Carvalho Chehabmy ($sphinx_major, $sphinx_minor, $sphinx_patch); 281efa44475SMauro Carvalho Chehab 2828484baaaSRandy Dunlapmy $dohighlight = ""; 2838484baaaSRandy Dunlap 2841da177e4SLinus Torvaldsmy $verbose = 0; 2852c12c810SPierre-Louis Bossartmy $Werror = 0; 286bdfe2be3SMauro Carvalho Chehabmy $output_mode = "rst"; 287e314ba31SDaniel Santosmy $output_preformatted = 0; 2884b44595aSJohannes Bergmy $no_doc_sections = 0; 2890b0f5f29SDaniel Vettermy $enable_lineno = 0; 290bdfe2be3SMauro Carvalho Chehabmy @highlights = @highlights_rst; 291bdfe2be3SMauro Carvalho Chehabmy $blankline = $blankline_rst; 2921da177e4SLinus Torvaldsmy $modulename = "Kernel API"; 293b6c3f456SJani Nikula 294b6c3f456SJani Nikulause constant { 295b6c3f456SJani Nikula OUTPUT_ALL => 0, # output all symbols and doc sections 296b6c3f456SJani Nikula OUTPUT_INCLUDE => 1, # output only specified symbols 297eab795ddSMauro Carvalho Chehab OUTPUT_EXPORTED => 2, # output exported symbols 298eab795ddSMauro Carvalho Chehab OUTPUT_INTERNAL => 3, # output non-exported symbols 299b6c3f456SJani Nikula}; 300b6c3f456SJani Nikulamy $output_selection = OUTPUT_ALL; 301b0d60bfbSJonathan Corbetmy $show_not_found = 0; # No longer used 302b2c4105bSBen Hutchings 30388c2b57dSJani Nikulamy @export_file_list; 30488c2b57dSJani Nikula 305b2c4105bSBen Hutchingsmy @build_time; 306b2c4105bSBen Hutchingsif (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && 307b2c4105bSBen Hutchings (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { 308b2c4105bSBen Hutchings @build_time = gmtime($seconds); 309b2c4105bSBen Hutchings} else { 310b2c4105bSBen Hutchings @build_time = localtime; 311b2c4105bSBen Hutchings} 312b2c4105bSBen Hutchings 3131da177e4SLinus Torvaldsmy $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 3141da177e4SLinus Torvalds 'July', 'August', 'September', 'October', 315b2c4105bSBen Hutchings 'November', 'December')[$build_time[4]] . 316b2c4105bSBen Hutchings " " . ($build_time[5]+1900); 3171da177e4SLinus Torvalds 3188484baaaSRandy Dunlap# Essentially these are globals. 319b9d97328SRandy Dunlap# They probably want to be tidied up, made more localised or something. 320b9d97328SRandy Dunlap# CAVEAT EMPTOR! Some of the others I localised may not want to be, which 3211da177e4SLinus Torvalds# could cause "use of undefined value" or other bugs. 3221da177e4SLinus Torvaldsmy ($function, %function_table, %parametertypes, $declaration_purpose); 323eab795ddSMauro Carvalho Chehabmy %nosymbol_table = (); 3240b0f5f29SDaniel Vettermy $declaration_start_line; 3251da177e4SLinus Torvaldsmy ($type, $declaration_name, $return_type); 3261c32fd0cSIlya Dryomovmy ($newsection, $newcontents, $prototype, $brcount, %source_map); 3271da177e4SLinus Torvalds 328bd0e88e5SRandy Dunlapif (defined($ENV{'KBUILD_VERBOSE'})) { 329bd0e88e5SRandy Dunlap $verbose = "$ENV{'KBUILD_VERBOSE'}"; 330bd0e88e5SRandy Dunlap} 331bd0e88e5SRandy Dunlap 3322c12c810SPierre-Louis Bossartif (defined($ENV{'KDOC_WERROR'})) { 3332c12c810SPierre-Louis Bossart $Werror = "$ENV{'KDOC_WERROR'}"; 3342c12c810SPierre-Louis Bossart} 3352c12c810SPierre-Louis Bossart 3362c12c810SPierre-Louis Bossartif (defined($ENV{'KCFLAGS'})) { 3372c12c810SPierre-Louis Bossart my $kcflags = "$ENV{'KCFLAGS'}"; 3382c12c810SPierre-Louis Bossart 3392c12c810SPierre-Louis Bossart if ($kcflags =~ /Werror/) { 3402c12c810SPierre-Louis Bossart $Werror = 1; 3412c12c810SPierre-Louis Bossart } 3422c12c810SPierre-Louis Bossart} 3432c12c810SPierre-Louis Bossart 3441da177e4SLinus Torvalds# Generated docbook code is inserted in a template at a point where 3451da177e4SLinus Torvalds# docbook v3.1 requires a non-zero sequence of RefEntry's; see: 34693431e06SAlexander A. Klimov# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html 3471da177e4SLinus Torvalds# We keep track of number of generated entries and generate a dummy 3481da177e4SLinus Torvalds# if needs be to ensure the expanded template can be postprocessed 3491da177e4SLinus Torvalds# into html. 3501da177e4SLinus Torvaldsmy $section_counter = 0; 3511da177e4SLinus Torvalds 3521da177e4SLinus Torvaldsmy $lineprefix=""; 3531da177e4SLinus Torvalds 35448af606aSJani Nikula# Parser states 35548af606aSJani Nikulause constant { 35648af606aSJani Nikula STATE_NORMAL => 0, # normal code 35748af606aSJani Nikula STATE_NAME => 1, # looking for function name 35817b78717SJonathan Corbet STATE_BODY_MAYBE => 2, # body - or maybe more description 35917b78717SJonathan Corbet STATE_BODY => 3, # the body of the comment 3600d55d48bSMauro Carvalho Chehab STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line 3610d55d48bSMauro Carvalho Chehab STATE_PROTO => 5, # scanning prototype 3620d55d48bSMauro Carvalho Chehab STATE_DOCBLOCK => 6, # documentation block 3630d55d48bSMauro Carvalho Chehab STATE_INLINE => 7, # gathering doc outside main block 36448af606aSJani Nikula}; 3651da177e4SLinus Torvaldsmy $state; 366850622dfSRandy Dunlapmy $in_doc_sect; 367d742f24dSJonathan Corbetmy $leading_space; 3681da177e4SLinus Torvalds 36948af606aSJani Nikula# Inline documentation state 37048af606aSJani Nikulause constant { 37148af606aSJani Nikula STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE) 37248af606aSJani Nikula STATE_INLINE_NAME => 1, # looking for member name (@foo:) 37348af606aSJani Nikula STATE_INLINE_TEXT => 2, # looking for member documentation 37448af606aSJani Nikula STATE_INLINE_END => 3, # done 37548af606aSJani Nikula STATE_INLINE_ERROR => 4, # error - Comment without header was found. 37648af606aSJani Nikula # Spit a warning as it's not 377a4c6ebedSDanilo Cesar Lemes de Paula # proper kernel-doc and ignore the rest. 37848af606aSJani Nikula}; 37948af606aSJani Nikulamy $inline_doc_state; 380a4c6ebedSDanilo Cesar Lemes de Paula 3811da177e4SLinus Torvalds#declaration types: can be 3821da177e4SLinus Torvalds# 'function', 'struct', 'union', 'enum', 'typedef' 3831da177e4SLinus Torvaldsmy $decl_type; 3841da177e4SLinus Torvalds 38552042e2dSMauro Carvalho Chehab# Name of the kernel-doc identifier for non-DOC markups 38652042e2dSMauro Carvalho Chehabmy $identifier; 38752042e2dSMauro Carvalho Chehab 3881da177e4SLinus Torvaldsmy $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. 3891da177e4SLinus Torvaldsmy $doc_end = '\*/'; 3901da177e4SLinus Torvaldsmy $doc_com = '\s*\*\s*'; 39112ae6779SDaniel Santosmy $doc_com_body = '\s*\* ?'; 3921da177e4SLinus Torvaldsmy $doc_decl = $doc_com . '(\w+)'; 393f624adefSJani Nikula# @params and a strictly limited set of supported section names 3948569de68SJonathan Corbetmy $doc_sect = $doc_com . 395ef00028bSJonathan Corbet '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; 39612ae6779SDaniel Santosmy $doc_content = $doc_com_body . '(.*)'; 3971da177e4SLinus Torvaldsmy $doc_block = $doc_com . 'DOC:\s*(.*)?'; 39848af606aSJani Nikulamy $doc_inline_start = '^\s*/\*\*\s*$'; 399fe7bc493SMauro Carvalho Chehabmy $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)'; 40048af606aSJani Nikulamy $doc_inline_end = '^\s*\*/\s*$'; 4010c9aa209SJani Nikulamy $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; 40286ae2e38SJani Nikulamy $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; 4031da177e4SLinus Torvalds 4041da177e4SLinus Torvaldsmy %parameterdescs; 4050b0f5f29SDaniel Vettermy %parameterdesc_start_lines; 4061da177e4SLinus Torvaldsmy @parameterlist; 4071da177e4SLinus Torvaldsmy %sections; 4081da177e4SLinus Torvaldsmy @sectionlist; 4090b0f5f29SDaniel Vettermy %section_start_lines; 410a1d94aa5SRandy Dunlapmy $sectcheck; 411a1d94aa5SRandy Dunlapmy $struct_actual; 4121da177e4SLinus Torvalds 4131da177e4SLinus Torvaldsmy $contents = ""; 4140b0f5f29SDaniel Vettermy $new_start_line = 0; 415f624adefSJani Nikula 416f624adefSJani Nikula# the canonical section names. see also $doc_sect above. 4171da177e4SLinus Torvaldsmy $section_default = "Description"; # default section 4181da177e4SLinus Torvaldsmy $section_intro = "Introduction"; 4191da177e4SLinus Torvaldsmy $section = $section_default; 4201da177e4SLinus Torvaldsmy $section_context = "Context"; 4214092bac7SYacine Belkadimy $section_return = "Return"; 4221da177e4SLinus Torvalds 4231da177e4SLinus Torvaldsmy $undescribed = "-- undescribed --"; 4241da177e4SLinus Torvalds 4251da177e4SLinus Torvaldsreset_state(); 4261da177e4SLinus Torvalds 427b031ac4eSMauro Carvalho Chehabwhile ($ARGV[0] =~ m/^--?(.*)/) { 428b031ac4eSMauro Carvalho Chehab my $cmd = $1; 429b031ac4eSMauro Carvalho Chehab shift @ARGV; 430b031ac4eSMauro Carvalho Chehab if ($cmd eq "man") { 4311da177e4SLinus Torvalds $output_mode = "man"; 4324d732701SDanilo Cesar Lemes de Paula @highlights = @highlights_man; 4331da177e4SLinus Torvalds $blankline = $blankline_man; 434b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "rst") { 435c0d1b6eeSJonathan Corbet $output_mode = "rst"; 436c0d1b6eeSJonathan Corbet @highlights = @highlights_rst; 437c0d1b6eeSJonathan Corbet $blankline = $blankline_rst; 438b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "none") { 4393a025e1dSMatthew Wilcox $output_mode = "none"; 440b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document 4411da177e4SLinus Torvalds $modulename = shift @ARGV; 442b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "function") { # to only output specific functions 443b6c3f456SJani Nikula $output_selection = OUTPUT_INCLUDE; 4441da177e4SLinus Torvalds $function = shift @ARGV; 4451da177e4SLinus Torvalds $function_table{$function} = 1; 446eab795ddSMauro Carvalho Chehab } elsif ($cmd eq "nosymbol") { # Exclude specific symbols 447eab795ddSMauro Carvalho Chehab my $symbol = shift @ARGV; 448eab795ddSMauro Carvalho Chehab $nosymbol_table{$symbol} = 1; 449b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "export") { # only exported symbols 450b6c3f456SJani Nikula $output_selection = OUTPUT_EXPORTED; 451da9726ecSJani Nikula %function_table = (); 452b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "internal") { # only non-exported symbols 453b6c3f456SJani Nikula $output_selection = OUTPUT_INTERNAL; 454da9726ecSJani Nikula %function_table = (); 455b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "export-file") { 45688c2b57dSJani Nikula my $file = shift @ARGV; 45788c2b57dSJani Nikula push(@export_file_list, $file); 458b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq "v") { 4591da177e4SLinus Torvalds $verbose = 1; 4602c12c810SPierre-Louis Bossart } elsif ($cmd eq "Werror") { 4612c12c810SPierre-Louis Bossart $Werror = 1; 462b031ac4eSMauro Carvalho Chehab } elsif (($cmd eq "h") || ($cmd eq "help")) { 4631da177e4SLinus Torvalds usage(); 464b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq 'no-doc-sections') { 4654b44595aSJohannes Berg $no_doc_sections = 1; 466b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq 'enable-lineno') { 4670b0f5f29SDaniel Vetter $enable_lineno = 1; 468b031ac4eSMauro Carvalho Chehab } elsif ($cmd eq 'show-not-found') { 469b0d60bfbSJonathan Corbet $show_not_found = 1; # A no-op but don't fail 47093351d41SMauro Carvalho Chehab } elsif ($cmd eq "sphinx-version") { 47193351d41SMauro Carvalho Chehab my $ver_string = shift @ARGV; 47293351d41SMauro Carvalho Chehab if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) { 47393351d41SMauro Carvalho Chehab $sphinx_major = $1; 47493351d41SMauro Carvalho Chehab if (defined($2)) { 47593351d41SMauro Carvalho Chehab $sphinx_minor = substr($2,1); 47693351d41SMauro Carvalho Chehab } else { 47793351d41SMauro Carvalho Chehab $sphinx_minor = 0; 47893351d41SMauro Carvalho Chehab } 47993351d41SMauro Carvalho Chehab if (defined($3)) { 48093351d41SMauro Carvalho Chehab $sphinx_patch = substr($3,1) 48193351d41SMauro Carvalho Chehab } else { 48293351d41SMauro Carvalho Chehab $sphinx_patch = 0; 48393351d41SMauro Carvalho Chehab } 48493351d41SMauro Carvalho Chehab } else { 48593351d41SMauro Carvalho Chehab die "Sphinx version should either major.minor or major.minor.patch format\n"; 48693351d41SMauro Carvalho Chehab } 487b031ac4eSMauro Carvalho Chehab } else { 488b031ac4eSMauro Carvalho Chehab # Unknown argument 489b031ac4eSMauro Carvalho Chehab usage(); 4901da177e4SLinus Torvalds } 4911da177e4SLinus Torvalds} 4921da177e4SLinus Torvalds 4938484baaaSRandy Dunlap# continue execution near EOF; 4948484baaaSRandy Dunlap 495efa44475SMauro Carvalho Chehab# The C domain dialect changed on Sphinx 3. So, we need to check the 496efa44475SMauro Carvalho Chehab# version in order to produce the right tags. 497efa44475SMauro Carvalho Chehabsub findprog($) 498efa44475SMauro Carvalho Chehab{ 499efa44475SMauro Carvalho Chehab foreach(split(/:/, $ENV{PATH})) { 500efa44475SMauro Carvalho Chehab return "$_/$_[0]" if(-x "$_/$_[0]"); 501efa44475SMauro Carvalho Chehab } 502efa44475SMauro Carvalho Chehab} 503efa44475SMauro Carvalho Chehab 504efa44475SMauro Carvalho Chehabsub get_sphinx_version() 505efa44475SMauro Carvalho Chehab{ 506efa44475SMauro Carvalho Chehab my $ver; 507efa44475SMauro Carvalho Chehab 508efa44475SMauro Carvalho Chehab my $cmd = "sphinx-build"; 509efa44475SMauro Carvalho Chehab if (!findprog($cmd)) { 510efa44475SMauro Carvalho Chehab my $cmd = "sphinx-build3"; 51193351d41SMauro Carvalho Chehab if (!findprog($cmd)) { 51293351d41SMauro Carvalho Chehab $sphinx_major = 1; 51393351d41SMauro Carvalho Chehab $sphinx_minor = 2; 51493351d41SMauro Carvalho Chehab $sphinx_patch = 0; 51593351d41SMauro Carvalho Chehab printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n", 51693351d41SMauro Carvalho Chehab $sphinx_major, $sphinx_minor, $sphinx_patch; 51793351d41SMauro Carvalho Chehab return; 51893351d41SMauro Carvalho Chehab } 519efa44475SMauro Carvalho Chehab } 520efa44475SMauro Carvalho Chehab 521efa44475SMauro Carvalho Chehab open IN, "$cmd --version 2>&1 |"; 522efa44475SMauro Carvalho Chehab while (<IN>) { 523efa44475SMauro Carvalho Chehab if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) { 52493351d41SMauro Carvalho Chehab $sphinx_major = $1; 52593351d41SMauro Carvalho Chehab $sphinx_minor = $2; 52693351d41SMauro Carvalho Chehab $sphinx_patch = $3; 527efa44475SMauro Carvalho Chehab last; 528efa44475SMauro Carvalho Chehab } 529efa44475SMauro Carvalho Chehab # Sphinx 1.2.x uses a different format 530efa44475SMauro Carvalho Chehab if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) { 53193351d41SMauro Carvalho Chehab $sphinx_major = $1; 53293351d41SMauro Carvalho Chehab $sphinx_minor = $2; 53393351d41SMauro Carvalho Chehab $sphinx_patch = $3; 534efa44475SMauro Carvalho Chehab last; 535efa44475SMauro Carvalho Chehab } 536efa44475SMauro Carvalho Chehab } 537efa44475SMauro Carvalho Chehab close IN; 538efa44475SMauro Carvalho Chehab} 539efa44475SMauro Carvalho Chehab 54053f049faSBorislav Petkov# get kernel version from env 54153f049faSBorislav Petkovsub get_kernel_version() { 5421b9bc22dSJohannes Berg my $version = 'unknown kernel version'; 54353f049faSBorislav Petkov 54453f049faSBorislav Petkov if (defined($ENV{'KERNELVERSION'})) { 54553f049faSBorislav Petkov $version = $ENV{'KERNELVERSION'}; 54653f049faSBorislav Petkov } 54753f049faSBorislav Petkov return $version; 54853f049faSBorislav Petkov} 5491da177e4SLinus Torvalds 5500b0f5f29SDaniel Vetter# 5510b0f5f29SDaniel Vettersub print_lineno { 5520b0f5f29SDaniel Vetter my $lineno = shift; 5530b0f5f29SDaniel Vetter if ($enable_lineno && defined($lineno)) { 5540b0f5f29SDaniel Vetter print "#define LINENO " . $lineno . "\n"; 5550b0f5f29SDaniel Vetter } 5560b0f5f29SDaniel Vetter} 5571da177e4SLinus Torvalds## 5581da177e4SLinus Torvalds# dumps section contents to arrays/hashes intended for that purpose. 5591da177e4SLinus Torvalds# 5601da177e4SLinus Torvaldssub dump_section { 56194dc7ad5SRandy Dunlap my $file = shift; 5621da177e4SLinus Torvalds my $name = shift; 5631da177e4SLinus Torvalds my $contents = join "\n", @_; 5641da177e4SLinus Torvalds 56513901ef2SJani Nikula if ($name =~ m/$type_param/) { 5661da177e4SLinus Torvalds $name = $1; 5671da177e4SLinus Torvalds $parameterdescs{$name} = $contents; 568a1d94aa5SRandy Dunlap $sectcheck = $sectcheck . $name . " "; 5690b0f5f29SDaniel Vetter $parameterdesc_start_lines{$name} = $new_start_line; 5700b0f5f29SDaniel Vetter $new_start_line = 0; 571ced69090SRandy Dunlap } elsif ($name eq "@\.\.\.") { 572ced69090SRandy Dunlap $name = "..."; 573ced69090SRandy Dunlap $parameterdescs{$name} = $contents; 574a1d94aa5SRandy Dunlap $sectcheck = $sectcheck . $name . " "; 5750b0f5f29SDaniel Vetter $parameterdesc_start_lines{$name} = $new_start_line; 5760b0f5f29SDaniel Vetter $new_start_line = 0; 5771da177e4SLinus Torvalds } else { 57894dc7ad5SRandy Dunlap if (defined($sections{$name}) && ($sections{$name} ne "")) { 57995b6be9dSJani Nikula # Only warn on user specified duplicate section names. 58095b6be9dSJani Nikula if ($name ne $section_default) { 58132217761SJani Nikula print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; 58232217761SJani Nikula ++$warnings; 58395b6be9dSJani Nikula } 58432217761SJani Nikula $sections{$name} .= $contents; 58532217761SJani Nikula } else { 5861da177e4SLinus Torvalds $sections{$name} = $contents; 5871da177e4SLinus Torvalds push @sectionlist, $name; 5880b0f5f29SDaniel Vetter $section_start_lines{$name} = $new_start_line; 5890b0f5f29SDaniel Vetter $new_start_line = 0; 5901da177e4SLinus Torvalds } 5911da177e4SLinus Torvalds } 59232217761SJani Nikula} 5931da177e4SLinus Torvalds 5941da177e4SLinus Torvalds## 595b112e0f7SJohannes Berg# dump DOC: section after checking that it should go out 596b112e0f7SJohannes Berg# 597b112e0f7SJohannes Bergsub dump_doc_section { 59894dc7ad5SRandy Dunlap my $file = shift; 599b112e0f7SJohannes Berg my $name = shift; 600b112e0f7SJohannes Berg my $contents = join "\n", @_; 601b112e0f7SJohannes Berg 6024b44595aSJohannes Berg if ($no_doc_sections) { 6034b44595aSJohannes Berg return; 6044b44595aSJohannes Berg } 6054b44595aSJohannes Berg 606eab795ddSMauro Carvalho Chehab return if (defined($nosymbol_table{$name})); 607eab795ddSMauro Carvalho Chehab 608b6c3f456SJani Nikula if (($output_selection == OUTPUT_ALL) || 609eab795ddSMauro Carvalho Chehab (($output_selection == OUTPUT_INCLUDE) && 610eab795ddSMauro Carvalho Chehab defined($function_table{$name}))) 611b112e0f7SJohannes Berg { 61294dc7ad5SRandy Dunlap dump_section($file, $name, $contents); 613b112e0f7SJohannes Berg output_blockhead({'sectionlist' => \@sectionlist, 614b112e0f7SJohannes Berg 'sections' => \%sections, 615b112e0f7SJohannes Berg 'module' => $modulename, 616b6c3f456SJani Nikula 'content-only' => ($output_selection != OUTPUT_ALL), }); 617b112e0f7SJohannes Berg } 618b112e0f7SJohannes Berg} 619b112e0f7SJohannes Berg 620b112e0f7SJohannes Berg## 6211da177e4SLinus Torvalds# output function 6221da177e4SLinus Torvalds# 6231da177e4SLinus Torvalds# parameterdescs, a hash. 6241da177e4SLinus Torvalds# function => "function name" 6251da177e4SLinus Torvalds# parameterlist => @list of parameters 6261da177e4SLinus Torvalds# parameterdescs => %parameter descriptions 6271da177e4SLinus Torvalds# sectionlist => @list of sections 628a21217daSRandy Dunlap# sections => %section descriptions 6291da177e4SLinus Torvalds# 6301da177e4SLinus Torvalds 6311da177e4SLinus Torvaldssub output_highlight { 6321da177e4SLinus Torvalds my $contents = join "\n",@_; 6331da177e4SLinus Torvalds my $line; 6341da177e4SLinus Torvalds 6351da177e4SLinus Torvalds# DEBUG 6361da177e4SLinus Torvalds# if (!defined $contents) { 6371da177e4SLinus Torvalds# use Carp; 6381da177e4SLinus Torvalds# confess "output_highlight got called with no args?\n"; 6391da177e4SLinus Torvalds# } 6401da177e4SLinus Torvalds 6413eb014a1SRandy Dunlap# print STDERR "contents b4:$contents\n"; 6421da177e4SLinus Torvalds eval $dohighlight; 6431da177e4SLinus Torvalds die $@ if $@; 6443eb014a1SRandy Dunlap# print STDERR "contents af:$contents\n"; 6453eb014a1SRandy Dunlap 6461da177e4SLinus Torvalds foreach $line (split "\n", $contents) { 64712ae6779SDaniel Santos if (! $output_preformatted) { 64812ae6779SDaniel Santos $line =~ s/^\s*//; 64912ae6779SDaniel Santos } 6501da177e4SLinus Torvalds if ($line eq ""){ 651e314ba31SDaniel Santos if (! $output_preformatted) { 6520bba924cSJonathan Corbet print $lineprefix, $blankline; 653e314ba31SDaniel Santos } 6541da177e4SLinus Torvalds } else { 655cdccb316SRandy Dunlap if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { 656cdccb316SRandy Dunlap print "\\&$line"; 657cdccb316SRandy Dunlap } else { 6581da177e4SLinus Torvalds print $lineprefix, $line; 6591da177e4SLinus Torvalds } 660cdccb316SRandy Dunlap } 6611da177e4SLinus Torvalds print "\n"; 6621da177e4SLinus Torvalds } 6631da177e4SLinus Torvalds} 6641da177e4SLinus Torvalds 6651da177e4SLinus Torvalds## 6661da177e4SLinus Torvalds# output function in man 6671da177e4SLinus Torvaldssub output_function_man(%) { 6681da177e4SLinus Torvalds my %args = %{$_[0]}; 6691da177e4SLinus Torvalds my ($parameter, $section); 6701da177e4SLinus Torvalds my $count; 6711da177e4SLinus Torvalds 6721da177e4SLinus Torvalds print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; 6731da177e4SLinus Torvalds 6741da177e4SLinus Torvalds print ".SH NAME\n"; 6751da177e4SLinus Torvalds print $args{'function'} . " \\- " . $args{'purpose'} . "\n"; 6761da177e4SLinus Torvalds 6771da177e4SLinus Torvalds print ".SH SYNOPSIS\n"; 678a21217daSRandy Dunlap if ($args{'functiontype'} ne "") { 6791da177e4SLinus Torvalds print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n"; 680a21217daSRandy Dunlap } else { 681a21217daSRandy Dunlap print ".B \"" . $args{'function'} . "\n"; 682a21217daSRandy Dunlap } 6831da177e4SLinus Torvalds $count = 0; 6841da177e4SLinus Torvalds my $parenth = "("; 6851da177e4SLinus Torvalds my $post = ","; 6861da177e4SLinus Torvalds foreach my $parameter (@{$args{'parameterlist'}}) { 6871da177e4SLinus Torvalds if ($count == $#{$args{'parameterlist'}}) { 6881da177e4SLinus Torvalds $post = ");"; 6891da177e4SLinus Torvalds } 6901da177e4SLinus Torvalds $type = $args{'parametertypes'}{$parameter}; 6911da177e4SLinus Torvalds if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { 6921da177e4SLinus Torvalds # pointer-to-function 693ed8348e2SMauro Carvalho Chehab print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n"; 6941da177e4SLinus Torvalds } else { 6951da177e4SLinus Torvalds $type =~ s/([^\*])$/$1 /; 696ed8348e2SMauro Carvalho Chehab print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n"; 6971da177e4SLinus Torvalds } 6981da177e4SLinus Torvalds $count++; 6991da177e4SLinus Torvalds $parenth = ""; 7001da177e4SLinus Torvalds } 7011da177e4SLinus Torvalds 7021da177e4SLinus Torvalds print ".SH ARGUMENTS\n"; 7031da177e4SLinus Torvalds foreach $parameter (@{$args{'parameterlist'}}) { 7041da177e4SLinus Torvalds my $parameter_name = $parameter; 7051da177e4SLinus Torvalds $parameter_name =~ s/\[.*//; 7061da177e4SLinus Torvalds 7071da177e4SLinus Torvalds print ".IP \"" . $parameter . "\" 12\n"; 7081da177e4SLinus Torvalds output_highlight($args{'parameterdescs'}{$parameter_name}); 7091da177e4SLinus Torvalds } 7101da177e4SLinus Torvalds foreach $section (@{$args{'sectionlist'}}) { 7111da177e4SLinus Torvalds print ".SH \"", uc $section, "\"\n"; 7121da177e4SLinus Torvalds output_highlight($args{'sections'}{$section}); 7131da177e4SLinus Torvalds } 7141da177e4SLinus Torvalds} 7151da177e4SLinus Torvalds 7161da177e4SLinus Torvalds## 7171da177e4SLinus Torvalds# output enum in man 7181da177e4SLinus Torvaldssub output_enum_man(%) { 7191da177e4SLinus Torvalds my %args = %{$_[0]}; 7201da177e4SLinus Torvalds my ($parameter, $section); 7211da177e4SLinus Torvalds my $count; 7221da177e4SLinus Torvalds 7231da177e4SLinus Torvalds print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; 7241da177e4SLinus Torvalds 7251da177e4SLinus Torvalds print ".SH NAME\n"; 7261da177e4SLinus Torvalds print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n"; 7271da177e4SLinus Torvalds 7281da177e4SLinus Torvalds print ".SH SYNOPSIS\n"; 7291da177e4SLinus Torvalds print "enum " . $args{'enum'} . " {\n"; 7301da177e4SLinus Torvalds $count = 0; 7311da177e4SLinus Torvalds foreach my $parameter (@{$args{'parameterlist'}}) { 7321da177e4SLinus Torvalds print ".br\n.BI \" $parameter\"\n"; 7331da177e4SLinus Torvalds if ($count == $#{$args{'parameterlist'}}) { 7341da177e4SLinus Torvalds print "\n};\n"; 7351da177e4SLinus Torvalds last; 7361da177e4SLinus Torvalds } 7371da177e4SLinus Torvalds else { 7381da177e4SLinus Torvalds print ", \n.br\n"; 7391da177e4SLinus Torvalds } 7401da177e4SLinus Torvalds $count++; 7411da177e4SLinus Torvalds } 7421da177e4SLinus Torvalds 7431da177e4SLinus Torvalds print ".SH Constants\n"; 7441da177e4SLinus Torvalds foreach $parameter (@{$args{'parameterlist'}}) { 7451da177e4SLinus Torvalds my $parameter_name = $parameter; 7461da177e4SLinus Torvalds $parameter_name =~ s/\[.*//; 7471da177e4SLinus Torvalds 7481da177e4SLinus Torvalds print ".IP \"" . $parameter . "\" 12\n"; 7491da177e4SLinus Torvalds output_highlight($args{'parameterdescs'}{$parameter_name}); 7501da177e4SLinus Torvalds } 7511da177e4SLinus Torvalds foreach $section (@{$args{'sectionlist'}}) { 7521da177e4SLinus Torvalds print ".SH \"$section\"\n"; 7531da177e4SLinus Torvalds output_highlight($args{'sections'}{$section}); 7541da177e4SLinus Torvalds } 7551da177e4SLinus Torvalds} 7561da177e4SLinus Torvalds 7571da177e4SLinus Torvalds## 7581da177e4SLinus Torvalds# output struct in man 7591da177e4SLinus Torvaldssub output_struct_man(%) { 7601da177e4SLinus Torvalds my %args = %{$_[0]}; 7611da177e4SLinus Torvalds my ($parameter, $section); 7621da177e4SLinus Torvalds 7631da177e4SLinus Torvalds print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n"; 7641da177e4SLinus Torvalds 7651da177e4SLinus Torvalds print ".SH NAME\n"; 7661da177e4SLinus Torvalds print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n"; 7671da177e4SLinus Torvalds 7688ad72163SMauro Carvalho Chehab my $declaration = $args{'definition'}; 7698ad72163SMauro Carvalho Chehab $declaration =~ s/\t/ /g; 7708ad72163SMauro Carvalho Chehab $declaration =~ s/\n/"\n.br\n.BI \"/g; 7711da177e4SLinus Torvalds print ".SH SYNOPSIS\n"; 7721da177e4SLinus Torvalds print $args{'type'} . " " . $args{'struct'} . " {\n.br\n"; 7738ad72163SMauro Carvalho Chehab print ".BI \"$declaration\n};\n.br\n\n"; 7741da177e4SLinus Torvalds 775c51d3dacSRandy Dunlap print ".SH Members\n"; 7761da177e4SLinus Torvalds foreach $parameter (@{$args{'parameterlist'}}) { 7771da177e4SLinus Torvalds ($parameter =~ /^#/) && next; 7781da177e4SLinus Torvalds 7791da177e4SLinus Torvalds my $parameter_name = $parameter; 7801da177e4SLinus Torvalds $parameter_name =~ s/\[.*//; 7811da177e4SLinus Torvalds 7821da177e4SLinus Torvalds ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; 7831da177e4SLinus Torvalds print ".IP \"" . $parameter . "\" 12\n"; 7841da177e4SLinus Torvalds output_highlight($args{'parameterdescs'}{$parameter_name}); 7851da177e4SLinus Torvalds } 7861da177e4SLinus Torvalds foreach $section (@{$args{'sectionlist'}}) { 7871da177e4SLinus Torvalds print ".SH \"$section\"\n"; 7881da177e4SLinus Torvalds output_highlight($args{'sections'}{$section}); 7891da177e4SLinus Torvalds } 7901da177e4SLinus Torvalds} 7911da177e4SLinus Torvalds 7921da177e4SLinus Torvalds## 7931da177e4SLinus Torvalds# output typedef in man 7941da177e4SLinus Torvaldssub output_typedef_man(%) { 7951da177e4SLinus Torvalds my %args = %{$_[0]}; 7961da177e4SLinus Torvalds my ($parameter, $section); 7971da177e4SLinus Torvalds 7981da177e4SLinus Torvalds print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; 7991da177e4SLinus Torvalds 8001da177e4SLinus Torvalds print ".SH NAME\n"; 8011da177e4SLinus Torvalds print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n"; 8021da177e4SLinus Torvalds 8031da177e4SLinus Torvalds foreach $section (@{$args{'sectionlist'}}) { 8041da177e4SLinus Torvalds print ".SH \"$section\"\n"; 8051da177e4SLinus Torvalds output_highlight($args{'sections'}{$section}); 8061da177e4SLinus Torvalds } 8071da177e4SLinus Torvalds} 8081da177e4SLinus Torvalds 809b112e0f7SJohannes Bergsub output_blockhead_man(%) { 8101da177e4SLinus Torvalds my %args = %{$_[0]}; 8111da177e4SLinus Torvalds my ($parameter, $section); 8121da177e4SLinus Torvalds my $count; 8131da177e4SLinus Torvalds 8141da177e4SLinus Torvalds print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; 8151da177e4SLinus Torvalds 8161da177e4SLinus Torvalds foreach $section (@{$args{'sectionlist'}}) { 8171da177e4SLinus Torvalds print ".SH \"$section\"\n"; 8181da177e4SLinus Torvalds output_highlight($args{'sections'}{$section}); 8191da177e4SLinus Torvalds } 8201da177e4SLinus Torvalds} 8211da177e4SLinus Torvalds 8221da177e4SLinus Torvalds## 823c0d1b6eeSJonathan Corbet# output in restructured text 824c0d1b6eeSJonathan Corbet# 825c0d1b6eeSJonathan Corbet 826c0d1b6eeSJonathan Corbet# 827c0d1b6eeSJonathan Corbet# This could use some work; it's used to output the DOC: sections, and 828c0d1b6eeSJonathan Corbet# starts by putting out the name of the doc section itself, but that tends 829c0d1b6eeSJonathan Corbet# to duplicate a header already in the template file. 830c0d1b6eeSJonathan Corbet# 831c0d1b6eeSJonathan Corbetsub output_blockhead_rst(%) { 832c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 833c0d1b6eeSJonathan Corbet my ($parameter, $section); 834c0d1b6eeSJonathan Corbet 835c0d1b6eeSJonathan Corbet foreach $section (@{$args{'sectionlist'}}) { 836eab795ddSMauro Carvalho Chehab next if (defined($nosymbol_table{$section})); 837eab795ddSMauro Carvalho Chehab 8389e72184bSJani Nikula if ($output_selection != OUTPUT_INCLUDE) { 83906a755d6SMichal Wajdeczko print ".. _$section:\n\n"; 840c0d1b6eeSJonathan Corbet print "**$section**\n\n"; 8419e72184bSJani Nikula } 8420b0f5f29SDaniel Vetter print_lineno($section_start_lines{$section}); 843c0d1b6eeSJonathan Corbet output_highlight_rst($args{'sections'}{$section}); 844c0d1b6eeSJonathan Corbet print "\n"; 845c0d1b6eeSJonathan Corbet } 846c0d1b6eeSJonathan Corbet} 847c0d1b6eeSJonathan Corbet 848af250290SJonathan Corbet# 849af250290SJonathan Corbet# Apply the RST highlights to a sub-block of text. 850af250290SJonathan Corbet# 851af250290SJonathan Corbetsub highlight_block($) { 852af250290SJonathan Corbet # The dohighlight kludge requires the text be called $contents 853af250290SJonathan Corbet my $contents = shift; 854c0d1b6eeSJonathan Corbet eval $dohighlight; 855c0d1b6eeSJonathan Corbet die $@ if $@; 856af250290SJonathan Corbet return $contents; 857af250290SJonathan Corbet} 858c0d1b6eeSJonathan Corbet 859af250290SJonathan Corbet# 860af250290SJonathan Corbet# Regexes used only here. 861af250290SJonathan Corbet# 862af250290SJonathan Corbetmy $sphinx_literal = '^[^.].*::$'; 863af250290SJonathan Corbetmy $sphinx_cblock = '^\.\.\ +code-block::'; 864af250290SJonathan Corbet 865af250290SJonathan Corbetsub output_highlight_rst { 866af250290SJonathan Corbet my $input = join "\n",@_; 867af250290SJonathan Corbet my $output = ""; 868af250290SJonathan Corbet my $line; 869af250290SJonathan Corbet my $in_literal = 0; 870af250290SJonathan Corbet my $litprefix; 871af250290SJonathan Corbet my $block = ""; 872af250290SJonathan Corbet 873af250290SJonathan Corbet foreach $line (split "\n",$input) { 874af250290SJonathan Corbet # 875af250290SJonathan Corbet # If we're in a literal block, see if we should drop out 876af250290SJonathan Corbet # of it. Otherwise pass the line straight through unmunged. 877af250290SJonathan Corbet # 878af250290SJonathan Corbet if ($in_literal) { 879af250290SJonathan Corbet if (! ($line =~ /^\s*$/)) { 880af250290SJonathan Corbet # 881af250290SJonathan Corbet # If this is the first non-blank line in a literal 882af250290SJonathan Corbet # block we need to figure out what the proper indent is. 883af250290SJonathan Corbet # 884af250290SJonathan Corbet if ($litprefix eq "") { 885af250290SJonathan Corbet $line =~ /^(\s*)/; 886af250290SJonathan Corbet $litprefix = '^' . $1; 887af250290SJonathan Corbet $output .= $line . "\n"; 888af250290SJonathan Corbet } elsif (! ($line =~ /$litprefix/)) { 889af250290SJonathan Corbet $in_literal = 0; 890af250290SJonathan Corbet } else { 891af250290SJonathan Corbet $output .= $line . "\n"; 892af250290SJonathan Corbet } 893af250290SJonathan Corbet } else { 894af250290SJonathan Corbet $output .= $line . "\n"; 895af250290SJonathan Corbet } 896af250290SJonathan Corbet } 897af250290SJonathan Corbet # 898af250290SJonathan Corbet # Not in a literal block (or just dropped out) 899af250290SJonathan Corbet # 900af250290SJonathan Corbet if (! $in_literal) { 901af250290SJonathan Corbet $block .= $line . "\n"; 902af250290SJonathan Corbet if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { 903af250290SJonathan Corbet $in_literal = 1; 904af250290SJonathan Corbet $litprefix = ""; 905af250290SJonathan Corbet $output .= highlight_block($block); 906af250290SJonathan Corbet $block = "" 907af250290SJonathan Corbet } 908af250290SJonathan Corbet } 909af250290SJonathan Corbet } 910af250290SJonathan Corbet 911af250290SJonathan Corbet if ($block) { 912af250290SJonathan Corbet $output .= highlight_block($block); 913af250290SJonathan Corbet } 914af250290SJonathan Corbet foreach $line (split "\n", $output) { 915830066a7SJani Nikula print $lineprefix . $line . "\n"; 916c0d1b6eeSJonathan Corbet } 917c0d1b6eeSJonathan Corbet} 918c0d1b6eeSJonathan Corbet 919c0d1b6eeSJonathan Corbetsub output_function_rst(%) { 920c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 921c0d1b6eeSJonathan Corbet my ($parameter, $section); 922c099ff69SJani Nikula my $oldprefix = $lineprefix; 92382801d06SMauro Carvalho Chehab my $start = ""; 9246e9e4158SMauro Carvalho Chehab my $is_macro = 0; 925c0d1b6eeSJonathan Corbet 926efa44475SMauro Carvalho Chehab if ($sphinx_major < 3) { 927e3ad05feSMauro Carvalho Chehab if ($args{'typedef'}) { 92882801d06SMauro Carvalho Chehab print ".. c:type:: ". $args{'function'} . "\n\n"; 92982801d06SMauro Carvalho Chehab print_lineno($declaration_start_line); 93082801d06SMauro Carvalho Chehab print " **Typedef**: "; 93182801d06SMauro Carvalho Chehab $lineprefix = ""; 93282801d06SMauro Carvalho Chehab output_highlight_rst($args{'purpose'}); 93382801d06SMauro Carvalho Chehab $start = "\n\n**Syntax**\n\n ``"; 9346e9e4158SMauro Carvalho Chehab $is_macro = 1; 935c0d1b6eeSJonathan Corbet } else { 93682801d06SMauro Carvalho Chehab print ".. c:function:: "; 93782801d06SMauro Carvalho Chehab } 938e3ad05feSMauro Carvalho Chehab } else { 9396e9e4158SMauro Carvalho Chehab if ($args{'typedef'} || $args{'functiontype'} eq "") { 9406e9e4158SMauro Carvalho Chehab $is_macro = 1; 941e3ad05feSMauro Carvalho Chehab print ".. c:macro:: ". $args{'function'} . "\n\n"; 9426e9e4158SMauro Carvalho Chehab } else { 9436e9e4158SMauro Carvalho Chehab print ".. c:function:: "; 9446e9e4158SMauro Carvalho Chehab } 945e3ad05feSMauro Carvalho Chehab 946e3ad05feSMauro Carvalho Chehab if ($args{'typedef'}) { 947e3ad05feSMauro Carvalho Chehab print_lineno($declaration_start_line); 948e3ad05feSMauro Carvalho Chehab print " **Typedef**: "; 949e3ad05feSMauro Carvalho Chehab $lineprefix = ""; 950e3ad05feSMauro Carvalho Chehab output_highlight_rst($args{'purpose'}); 951e3ad05feSMauro Carvalho Chehab $start = "\n\n**Syntax**\n\n ``"; 952e3ad05feSMauro Carvalho Chehab } else { 9536e9e4158SMauro Carvalho Chehab print "``" if ($is_macro); 954e3ad05feSMauro Carvalho Chehab } 955e3ad05feSMauro Carvalho Chehab } 95682801d06SMauro Carvalho Chehab if ($args{'functiontype'} ne "") { 95782801d06SMauro Carvalho Chehab $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; 95882801d06SMauro Carvalho Chehab } else { 95982801d06SMauro Carvalho Chehab $start .= $args{'function'} . " ("; 960c0d1b6eeSJonathan Corbet } 961c0d1b6eeSJonathan Corbet print $start; 962c0d1b6eeSJonathan Corbet 963c0d1b6eeSJonathan Corbet my $count = 0; 964c0d1b6eeSJonathan Corbet foreach my $parameter (@{$args{'parameterlist'}}) { 965c0d1b6eeSJonathan Corbet if ($count ne 0) { 966c0d1b6eeSJonathan Corbet print ", "; 967c0d1b6eeSJonathan Corbet } 968c0d1b6eeSJonathan Corbet $count++; 969c0d1b6eeSJonathan Corbet $type = $args{'parametertypes'}{$parameter}; 970a88b1672SMauro Carvalho Chehab 971c0d1b6eeSJonathan Corbet if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { 972c0d1b6eeSJonathan Corbet # pointer-to-function 973e8f4ba83SPeter Maydell print $1 . $parameter . ") (" . $2 . ")"; 974c0d1b6eeSJonathan Corbet } else { 975ed8348e2SMauro Carvalho Chehab print $type; 976c0d1b6eeSJonathan Corbet } 977c0d1b6eeSJonathan Corbet } 9786e9e4158SMauro Carvalho Chehab if ($is_macro) { 9796e9e4158SMauro Carvalho Chehab print ")``\n\n"; 98082801d06SMauro Carvalho Chehab } else { 981c099ff69SJani Nikula print ")\n\n"; 982e3ad05feSMauro Carvalho Chehab } 9836e9e4158SMauro Carvalho Chehab if (!$args{'typedef'}) { 9840b0f5f29SDaniel Vetter print_lineno($declaration_start_line); 985c099ff69SJani Nikula $lineprefix = " "; 986c099ff69SJani Nikula output_highlight_rst($args{'purpose'}); 987c099ff69SJani Nikula print "\n"; 98882801d06SMauro Carvalho Chehab } 989c0d1b6eeSJonathan Corbet 990ecbcfba1SJani Nikula print "**Parameters**\n\n"; 991c099ff69SJani Nikula $lineprefix = " "; 992c0d1b6eeSJonathan Corbet foreach $parameter (@{$args{'parameterlist'}}) { 993c0d1b6eeSJonathan Corbet my $parameter_name = $parameter; 994ada5f446SGabriel Krisman Bertazi $parameter_name =~ s/\[.*//; 995c0d1b6eeSJonathan Corbet $type = $args{'parametertypes'}{$parameter}; 996c0d1b6eeSJonathan Corbet 997c0d1b6eeSJonathan Corbet if ($type ne "") { 998ed8348e2SMauro Carvalho Chehab print "``$type``\n"; 999c0d1b6eeSJonathan Corbet } else { 1000c0d1b6eeSJonathan Corbet print "``$parameter``\n"; 1001c0d1b6eeSJonathan Corbet } 10020b0f5f29SDaniel Vetter 10030b0f5f29SDaniel Vetter print_lineno($parameterdesc_start_lines{$parameter_name}); 10040b0f5f29SDaniel Vetter 10055e64fa9cSJani Nikula if (defined($args{'parameterdescs'}{$parameter_name}) && 10065e64fa9cSJani Nikula $args{'parameterdescs'}{$parameter_name} ne $undescribed) { 1007c0d1b6eeSJonathan Corbet output_highlight_rst($args{'parameterdescs'}{$parameter_name}); 1008c0d1b6eeSJonathan Corbet } else { 1009d4b08e0cSJani Nikula print " *undescribed*\n"; 1010c0d1b6eeSJonathan Corbet } 1011c0d1b6eeSJonathan Corbet print "\n"; 1012c0d1b6eeSJonathan Corbet } 1013c099ff69SJani Nikula 1014c099ff69SJani Nikula $lineprefix = $oldprefix; 1015c0d1b6eeSJonathan Corbet output_section_rst(@_); 1016c0d1b6eeSJonathan Corbet} 1017c0d1b6eeSJonathan Corbet 1018c0d1b6eeSJonathan Corbetsub output_section_rst(%) { 1019c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 1020c0d1b6eeSJonathan Corbet my $section; 1021c0d1b6eeSJonathan Corbet my $oldprefix = $lineprefix; 1022c0d1b6eeSJonathan Corbet $lineprefix = ""; 1023c0d1b6eeSJonathan Corbet 1024c0d1b6eeSJonathan Corbet foreach $section (@{$args{'sectionlist'}}) { 1025ecbcfba1SJani Nikula print "**$section**\n\n"; 10260b0f5f29SDaniel Vetter print_lineno($section_start_lines{$section}); 1027c0d1b6eeSJonathan Corbet output_highlight_rst($args{'sections'}{$section}); 1028c0d1b6eeSJonathan Corbet print "\n"; 1029c0d1b6eeSJonathan Corbet } 1030c0d1b6eeSJonathan Corbet print "\n"; 1031c0d1b6eeSJonathan Corbet $lineprefix = $oldprefix; 1032c0d1b6eeSJonathan Corbet} 1033c0d1b6eeSJonathan Corbet 1034c0d1b6eeSJonathan Corbetsub output_enum_rst(%) { 1035c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 1036c0d1b6eeSJonathan Corbet my ($parameter); 1037c099ff69SJani Nikula my $oldprefix = $lineprefix; 1038c0d1b6eeSJonathan Corbet my $count; 103962850976SJani Nikula 1040efa44475SMauro Carvalho Chehab if ($sphinx_major < 3) { 1041efa44475SMauro Carvalho Chehab my $name = "enum " . $args{'enum'}; 104262850976SJani Nikula print "\n\n.. c:type:: " . $name . "\n\n"; 1043efa44475SMauro Carvalho Chehab } else { 1044efa44475SMauro Carvalho Chehab my $name = $args{'enum'}; 1045efa44475SMauro Carvalho Chehab print "\n\n.. c:enum:: " . $name . "\n\n"; 1046efa44475SMauro Carvalho Chehab } 10470b0f5f29SDaniel Vetter print_lineno($declaration_start_line); 1048c099ff69SJani Nikula $lineprefix = " "; 1049c099ff69SJani Nikula output_highlight_rst($args{'purpose'}); 1050c099ff69SJani Nikula print "\n"; 1051c0d1b6eeSJonathan Corbet 1052ecbcfba1SJani Nikula print "**Constants**\n\n"; 1053c0d1b6eeSJonathan Corbet $lineprefix = " "; 1054c0d1b6eeSJonathan Corbet foreach $parameter (@{$args{'parameterlist'}}) { 1055ecbcfba1SJani Nikula print "``$parameter``\n"; 1056c0d1b6eeSJonathan Corbet if ($args{'parameterdescs'}{$parameter} ne $undescribed) { 1057c0d1b6eeSJonathan Corbet output_highlight_rst($args{'parameterdescs'}{$parameter}); 1058c0d1b6eeSJonathan Corbet } else { 1059d4b08e0cSJani Nikula print " *undescribed*\n"; 1060c0d1b6eeSJonathan Corbet } 1061c0d1b6eeSJonathan Corbet print "\n"; 1062c0d1b6eeSJonathan Corbet } 1063c099ff69SJani Nikula 1064c0d1b6eeSJonathan Corbet $lineprefix = $oldprefix; 1065c0d1b6eeSJonathan Corbet output_section_rst(@_); 1066c0d1b6eeSJonathan Corbet} 1067c0d1b6eeSJonathan Corbet 1068c0d1b6eeSJonathan Corbetsub output_typedef_rst(%) { 1069c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 1070c0d1b6eeSJonathan Corbet my ($parameter); 1071c099ff69SJani Nikula my $oldprefix = $lineprefix; 1072efa44475SMauro Carvalho Chehab my $name; 1073c0d1b6eeSJonathan Corbet 1074efa44475SMauro Carvalho Chehab if ($sphinx_major < 3) { 1075efa44475SMauro Carvalho Chehab $name = "typedef " . $args{'typedef'}; 1076efa44475SMauro Carvalho Chehab } else { 1077efa44475SMauro Carvalho Chehab $name = $args{'typedef'}; 1078efa44475SMauro Carvalho Chehab } 107962850976SJani Nikula print "\n\n.. c:type:: " . $name . "\n\n"; 10800b0f5f29SDaniel Vetter print_lineno($declaration_start_line); 1081c099ff69SJani Nikula $lineprefix = " "; 1082c099ff69SJani Nikula output_highlight_rst($args{'purpose'}); 1083c099ff69SJani Nikula print "\n"; 1084c0d1b6eeSJonathan Corbet 1085c099ff69SJani Nikula $lineprefix = $oldprefix; 1086c0d1b6eeSJonathan Corbet output_section_rst(@_); 1087c0d1b6eeSJonathan Corbet} 1088c0d1b6eeSJonathan Corbet 1089c0d1b6eeSJonathan Corbetsub output_struct_rst(%) { 1090c0d1b6eeSJonathan Corbet my %args = %{$_[0]}; 1091c0d1b6eeSJonathan Corbet my ($parameter); 1092c099ff69SJani Nikula my $oldprefix = $lineprefix; 1093c0d1b6eeSJonathan Corbet 1094efa44475SMauro Carvalho Chehab if ($sphinx_major < 3) { 1095efa44475SMauro Carvalho Chehab my $name = $args{'type'} . " " . $args{'struct'}; 109662850976SJani Nikula print "\n\n.. c:type:: " . $name . "\n\n"; 1097efa44475SMauro Carvalho Chehab } else { 1098efa44475SMauro Carvalho Chehab my $name = $args{'struct'}; 109972b97d0bSMauro Carvalho Chehab if ($args{'type'} eq 'union') { 110072b97d0bSMauro Carvalho Chehab print "\n\n.. c:union:: " . $name . "\n\n"; 110172b97d0bSMauro Carvalho Chehab } else { 1102efa44475SMauro Carvalho Chehab print "\n\n.. c:struct:: " . $name . "\n\n"; 1103efa44475SMauro Carvalho Chehab } 110472b97d0bSMauro Carvalho Chehab } 11050b0f5f29SDaniel Vetter print_lineno($declaration_start_line); 1106c099ff69SJani Nikula $lineprefix = " "; 1107c099ff69SJani Nikula output_highlight_rst($args{'purpose'}); 1108c099ff69SJani Nikula print "\n"; 1109c0d1b6eeSJonathan Corbet 1110ecbcfba1SJani Nikula print "**Definition**\n\n"; 1111c0d1b6eeSJonathan Corbet print "::\n\n"; 11128ad72163SMauro Carvalho Chehab my $declaration = $args{'definition'}; 11138ad72163SMauro Carvalho Chehab $declaration =~ s/\t/ /g; 11148ad72163SMauro Carvalho Chehab print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; 1115c0d1b6eeSJonathan Corbet 1116ecbcfba1SJani Nikula print "**Members**\n\n"; 1117c099ff69SJani Nikula $lineprefix = " "; 1118c0d1b6eeSJonathan Corbet foreach $parameter (@{$args{'parameterlist'}}) { 1119c0d1b6eeSJonathan Corbet ($parameter =~ /^#/) && next; 1120c0d1b6eeSJonathan Corbet 1121c0d1b6eeSJonathan Corbet my $parameter_name = $parameter; 1122c0d1b6eeSJonathan Corbet $parameter_name =~ s/\[.*//; 1123c0d1b6eeSJonathan Corbet 1124c0d1b6eeSJonathan Corbet ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; 1125c0d1b6eeSJonathan Corbet $type = $args{'parametertypes'}{$parameter}; 11260b0f5f29SDaniel Vetter print_lineno($parameterdesc_start_lines{$parameter_name}); 11276d232c80SMauro Carvalho Chehab print "``" . $parameter . "``\n"; 1128c0d1b6eeSJonathan Corbet output_highlight_rst($args{'parameterdescs'}{$parameter_name}); 1129c0d1b6eeSJonathan Corbet print "\n"; 1130c0d1b6eeSJonathan Corbet } 1131c0d1b6eeSJonathan Corbet print "\n"; 1132c099ff69SJani Nikula 1133c099ff69SJani Nikula $lineprefix = $oldprefix; 1134c0d1b6eeSJonathan Corbet output_section_rst(@_); 1135c0d1b6eeSJonathan Corbet} 1136c0d1b6eeSJonathan Corbet 11373a025e1dSMatthew Wilcox## none mode output functions 11383a025e1dSMatthew Wilcox 11393a025e1dSMatthew Wilcoxsub output_function_none(%) { 11403a025e1dSMatthew Wilcox} 11413a025e1dSMatthew Wilcox 11423a025e1dSMatthew Wilcoxsub output_enum_none(%) { 11433a025e1dSMatthew Wilcox} 11443a025e1dSMatthew Wilcox 11453a025e1dSMatthew Wilcoxsub output_typedef_none(%) { 11463a025e1dSMatthew Wilcox} 11473a025e1dSMatthew Wilcox 11483a025e1dSMatthew Wilcoxsub output_struct_none(%) { 11493a025e1dSMatthew Wilcox} 11503a025e1dSMatthew Wilcox 11513a025e1dSMatthew Wilcoxsub output_blockhead_none(%) { 11523a025e1dSMatthew Wilcox} 11533a025e1dSMatthew Wilcox 11541da177e4SLinus Torvalds## 115527205744SRandy Dunlap# generic output function for all types (function, struct/union, typedef, enum); 115627205744SRandy Dunlap# calls the generated, variable output_ function name based on 115727205744SRandy Dunlap# functype and output_mode 11581da177e4SLinus Torvaldssub output_declaration { 11591da177e4SLinus Torvalds no strict 'refs'; 11601da177e4SLinus Torvalds my $name = shift; 11611da177e4SLinus Torvalds my $functype = shift; 11621da177e4SLinus Torvalds my $func = "output_${functype}_$output_mode"; 1163eab795ddSMauro Carvalho Chehab 1164eab795ddSMauro Carvalho Chehab return if (defined($nosymbol_table{$name})); 1165eab795ddSMauro Carvalho Chehab 1166b6c3f456SJani Nikula if (($output_selection == OUTPUT_ALL) || 1167b6c3f456SJani Nikula (($output_selection == OUTPUT_INCLUDE || 1168b6c3f456SJani Nikula $output_selection == OUTPUT_EXPORTED) && 116986ae2e38SJani Nikula defined($function_table{$name})) || 1170eab795ddSMauro Carvalho Chehab ($output_selection == OUTPUT_INTERNAL && 117186ae2e38SJani Nikula !($functype eq "function" && defined($function_table{$name})))) 11721da177e4SLinus Torvalds { 11731da177e4SLinus Torvalds &$func(@_); 11741da177e4SLinus Torvalds $section_counter++; 11751da177e4SLinus Torvalds } 11761da177e4SLinus Torvalds} 11771da177e4SLinus Torvalds 11781da177e4SLinus Torvalds## 117927205744SRandy Dunlap# generic output function - calls the right one based on current output mode. 1180b112e0f7SJohannes Bergsub output_blockhead { 11811da177e4SLinus Torvalds no strict 'refs'; 1182b112e0f7SJohannes Berg my $func = "output_blockhead_" . $output_mode; 11831da177e4SLinus Torvalds &$func(@_); 11841da177e4SLinus Torvalds $section_counter++; 11851da177e4SLinus Torvalds} 11861da177e4SLinus Torvalds 11871da177e4SLinus Torvalds## 11881da177e4SLinus Torvalds# takes a declaration (struct, union, enum, typedef) and 11891da177e4SLinus Torvalds# invokes the right handler. NOT called for functions. 11901da177e4SLinus Torvaldssub dump_declaration($$) { 11911da177e4SLinus Torvalds no strict 'refs'; 11921da177e4SLinus Torvalds my ($prototype, $file) = @_; 11931da177e4SLinus Torvalds my $func = "dump_" . $decl_type; 11941da177e4SLinus Torvalds &$func(@_); 11951da177e4SLinus Torvalds} 11961da177e4SLinus Torvalds 11971da177e4SLinus Torvaldssub dump_union($$) { 11981da177e4SLinus Torvalds dump_struct(@_); 11991da177e4SLinus Torvalds} 12001da177e4SLinus Torvalds 12011da177e4SLinus Torvaldssub dump_struct($$) { 12021da177e4SLinus Torvalds my $x = shift; 12031da177e4SLinus Torvalds my $file = shift; 1204a746fe32SAditya Srivastava my $decl_type; 1205a746fe32SAditya Srivastava my $members; 1206a746fe32SAditya Srivastava my $type = qr{struct|union}; 1207a746fe32SAditya Srivastava # For capturing struct/union definition body, i.e. "{members*}qualifiers*" 1208a746fe32SAditya Srivastava my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*}; 12091da177e4SLinus Torvalds 1210a746fe32SAditya Srivastava if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { 1211a746fe32SAditya Srivastava $decl_type = $1; 12121da177e4SLinus Torvalds $declaration_name = $2; 1213a746fe32SAditya Srivastava $members = $3; 1214a746fe32SAditya Srivastava } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) { 1215a746fe32SAditya Srivastava $decl_type = $1; 1216a746fe32SAditya Srivastava $declaration_name = $3; 1217a746fe32SAditya Srivastava $members = $2; 1218a746fe32SAditya Srivastava } 12191da177e4SLinus Torvalds 1220a746fe32SAditya Srivastava if ($members) { 122152042e2dSMauro Carvalho Chehab if ($identifier ne $declaration_name) { 122252042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n"; 122352042e2dSMauro Carvalho Chehab return; 122452042e2dSMauro Carvalho Chehab } 122552042e2dSMauro Carvalho Chehab 1226aeec46b9SMartin Waitz # ignore members marked private: 12270d8c39e6SMauro Carvalho Chehab $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; 12280d8c39e6SMauro Carvalho Chehab $members =~ s/\/\*\s*private:.*//gosi; 1229aeec46b9SMartin Waitz # strip comments: 1230aeec46b9SMartin Waitz $members =~ s/\/\*.*?\*\///gos; 1231ef5da59fSRandy Dunlap # strip attributes 12323d9bfb19SSakari Ailus $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi; 12333d9bfb19SSakari Ailus $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; 12343d9bfb19SSakari Ailus $members =~ s/\s*__packed\s*/ /gos; 1235f0074929SJonathan Corbet $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; 1236f861537dSAndré Almeida $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; 1237a070991fSJonathan Cameron $members =~ s/\s*____cacheline_aligned/ /gos; 12383556108eSMauro Carvalho Chehab 1239b22b5a9eSConchúr Navid # replace DECLARE_BITMAP 12403556108eSMauro Carvalho Chehab $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos; 124145005b27SMauro Carvalho Chehab $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; 12421cb566baSJakub Kicinski # replace DECLARE_HASHTABLE 124345005b27SMauro Carvalho Chehab $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos; 124445005b27SMauro Carvalho Chehab # replace DECLARE_KFIFO 124545005b27SMauro Carvalho Chehab $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; 124645005b27SMauro Carvalho Chehab # replace DECLARE_KFIFO_PTR 124745005b27SMauro Carvalho Chehab $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; 1248aeec46b9SMartin Waitz 12498ad72163SMauro Carvalho Chehab my $declaration = $members; 12508ad72163SMauro Carvalho Chehab 12518ad72163SMauro Carvalho Chehab # Split nested struct/union elements as newer ones 125284ce5b98SMauro Carvalho Chehab while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) { 125384ce5b98SMauro Carvalho Chehab my $newmember; 125484ce5b98SMauro Carvalho Chehab my $maintype = $1; 125584ce5b98SMauro Carvalho Chehab my $ids = $4; 12568ad72163SMauro Carvalho Chehab my $content = $3; 125784ce5b98SMauro Carvalho Chehab foreach my $id(split /,/, $ids) { 125884ce5b98SMauro Carvalho Chehab $newmember .= "$maintype $id; "; 125984ce5b98SMauro Carvalho Chehab 12608ad72163SMauro Carvalho Chehab $id =~ s/[:\[].*//; 126184ce5b98SMauro Carvalho Chehab $id =~ s/^\s*\**(\S+)\s*/$1/; 12628ad72163SMauro Carvalho Chehab foreach my $arg (split /;/, $content) { 12638ad72163SMauro Carvalho Chehab next if ($arg =~ m/^\s*$/); 12647c0d7e87SMauro Carvalho Chehab if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) { 12657c0d7e87SMauro Carvalho Chehab # pointer-to-function 12667c0d7e87SMauro Carvalho Chehab my $type = $1; 12677c0d7e87SMauro Carvalho Chehab my $name = $2; 12687c0d7e87SMauro Carvalho Chehab my $extra = $3; 12697c0d7e87SMauro Carvalho Chehab next if (!$name); 12707c0d7e87SMauro Carvalho Chehab if ($id =~ m/^\s*$/) { 12717c0d7e87SMauro Carvalho Chehab # anonymous struct/union 12727c0d7e87SMauro Carvalho Chehab $newmember .= "$type$name$extra; "; 12737c0d7e87SMauro Carvalho Chehab } else { 12747c0d7e87SMauro Carvalho Chehab $newmember .= "$type$id.$name$extra; "; 12757c0d7e87SMauro Carvalho Chehab } 12767c0d7e87SMauro Carvalho Chehab } else { 127784ce5b98SMauro Carvalho Chehab my $type; 127884ce5b98SMauro Carvalho Chehab my $names; 127984ce5b98SMauro Carvalho Chehab $arg =~ s/^\s+//; 128084ce5b98SMauro Carvalho Chehab $arg =~ s/\s+$//; 128184ce5b98SMauro Carvalho Chehab # Handle bitmaps 128284ce5b98SMauro Carvalho Chehab $arg =~ s/:\s*\d+\s*//g; 128384ce5b98SMauro Carvalho Chehab # Handle arrays 1284d404d579SMauro Carvalho Chehab $arg =~ s/\[.*\]//g; 128584ce5b98SMauro Carvalho Chehab # The type may have multiple words, 128684ce5b98SMauro Carvalho Chehab # and multiple IDs can be defined, like: 128784ce5b98SMauro Carvalho Chehab # const struct foo, *bar, foobar 128884ce5b98SMauro Carvalho Chehab # So, we remove spaces when parsing the 128984ce5b98SMauro Carvalho Chehab # names, in order to match just names 129084ce5b98SMauro Carvalho Chehab # and commas for the names 129184ce5b98SMauro Carvalho Chehab $arg =~ s/\s*,\s*/,/g; 129284ce5b98SMauro Carvalho Chehab if ($arg =~ m/(.*)\s+([\S+,]+)/) { 129384ce5b98SMauro Carvalho Chehab $type = $1; 129484ce5b98SMauro Carvalho Chehab $names = $2; 129584ce5b98SMauro Carvalho Chehab } else { 129684ce5b98SMauro Carvalho Chehab $newmember .= "$arg; "; 129784ce5b98SMauro Carvalho Chehab next; 129884ce5b98SMauro Carvalho Chehab } 129984ce5b98SMauro Carvalho Chehab foreach my $name (split /,/, $names) { 130084ce5b98SMauro Carvalho Chehab $name =~ s/^\s*\**(\S+)\s*/$1/; 13018ad72163SMauro Carvalho Chehab next if (($name =~ m/^\s*$/)); 13028ad72163SMauro Carvalho Chehab if ($id =~ m/^\s*$/) { 13038ad72163SMauro Carvalho Chehab # anonymous struct/union 13048ad72163SMauro Carvalho Chehab $newmember .= "$type $name; "; 13058ad72163SMauro Carvalho Chehab } else { 13068ad72163SMauro Carvalho Chehab $newmember .= "$type $id.$name; "; 13078ad72163SMauro Carvalho Chehab } 13088ad72163SMauro Carvalho Chehab } 13097c0d7e87SMauro Carvalho Chehab } 131084ce5b98SMauro Carvalho Chehab } 131184ce5b98SMauro Carvalho Chehab } 1312673bb2dfSBen Hutchings $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/; 131384ce5b98SMauro Carvalho Chehab } 13148ad72163SMauro Carvalho Chehab 13158ad72163SMauro Carvalho Chehab # Ignore other nested elements, like enums 1316673bb2dfSBen Hutchings $members =~ s/(\{[^\{\}]*\})//g; 13178ad72163SMauro Carvalho Chehab 1318151c468bSMauro Carvalho Chehab create_parameterlist($members, ';', $file, $declaration_name); 13191081de2dSMauro Carvalho Chehab check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); 13201da177e4SLinus Torvalds 13218ad72163SMauro Carvalho Chehab # Adjust declaration for better display 1322673bb2dfSBen Hutchings $declaration =~ s/([\{;])/$1\n/g; 1323673bb2dfSBen Hutchings $declaration =~ s/\}\s+;/};/g; 13248ad72163SMauro Carvalho Chehab # Better handle inlined enums 1325673bb2dfSBen Hutchings do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/); 13268ad72163SMauro Carvalho Chehab 13278ad72163SMauro Carvalho Chehab my @def_args = split /\n/, $declaration; 13288ad72163SMauro Carvalho Chehab my $level = 1; 13298ad72163SMauro Carvalho Chehab $declaration = ""; 13308ad72163SMauro Carvalho Chehab foreach my $clause (@def_args) { 13318ad72163SMauro Carvalho Chehab $clause =~ s/^\s+//; 13328ad72163SMauro Carvalho Chehab $clause =~ s/\s+$//; 13338ad72163SMauro Carvalho Chehab $clause =~ s/\s+/ /; 13348ad72163SMauro Carvalho Chehab next if (!$clause); 1335673bb2dfSBen Hutchings $level-- if ($clause =~ m/(\})/ && $level > 1); 13368ad72163SMauro Carvalho Chehab if (!($clause =~ m/^\s*#/)) { 13378ad72163SMauro Carvalho Chehab $declaration .= "\t" x $level; 13388ad72163SMauro Carvalho Chehab } 13398ad72163SMauro Carvalho Chehab $declaration .= "\t" . $clause . "\n"; 1340673bb2dfSBen Hutchings $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/)); 13418ad72163SMauro Carvalho Chehab } 13421da177e4SLinus Torvalds output_declaration($declaration_name, 13431da177e4SLinus Torvalds 'struct', 13441da177e4SLinus Torvalds {'struct' => $declaration_name, 13451da177e4SLinus Torvalds 'module' => $modulename, 13468ad72163SMauro Carvalho Chehab 'definition' => $declaration, 13471da177e4SLinus Torvalds 'parameterlist' => \@parameterlist, 13481da177e4SLinus Torvalds 'parameterdescs' => \%parameterdescs, 13491da177e4SLinus Torvalds 'parametertypes' => \%parametertypes, 13501da177e4SLinus Torvalds 'sectionlist' => \@sectionlist, 13511da177e4SLinus Torvalds 'sections' => \%sections, 13521da177e4SLinus Torvalds 'purpose' => $declaration_purpose, 13531da177e4SLinus Torvalds 'type' => $decl_type 13541da177e4SLinus Torvalds }); 13551da177e4SLinus Torvalds } 13561da177e4SLinus Torvalds else { 1357d40e1e65SBart Van Assche print STDERR "${file}:$.: error: Cannot parse struct or union!\n"; 13581da177e4SLinus Torvalds ++$errors; 13591da177e4SLinus Torvalds } 13601da177e4SLinus Torvalds} 13611da177e4SLinus Torvalds 136285afe608SMauro Carvalho Chehab 136385afe608SMauro Carvalho Chehabsub show_warnings($$) { 136485afe608SMauro Carvalho Chehab my $functype = shift; 136585afe608SMauro Carvalho Chehab my $name = shift; 136685afe608SMauro Carvalho Chehab 1367eab795ddSMauro Carvalho Chehab return 0 if (defined($nosymbol_table{$name})); 1368eab795ddSMauro Carvalho Chehab 136985afe608SMauro Carvalho Chehab return 1 if ($output_selection == OUTPUT_ALL); 137085afe608SMauro Carvalho Chehab 137185afe608SMauro Carvalho Chehab if ($output_selection == OUTPUT_EXPORTED) { 137285afe608SMauro Carvalho Chehab if (defined($function_table{$name})) { 137385afe608SMauro Carvalho Chehab return 1; 137485afe608SMauro Carvalho Chehab } else { 137585afe608SMauro Carvalho Chehab return 0; 137685afe608SMauro Carvalho Chehab } 137785afe608SMauro Carvalho Chehab } 137885afe608SMauro Carvalho Chehab if ($output_selection == OUTPUT_INTERNAL) { 137985afe608SMauro Carvalho Chehab if (!($functype eq "function" && defined($function_table{$name}))) { 138085afe608SMauro Carvalho Chehab return 1; 138185afe608SMauro Carvalho Chehab } else { 138285afe608SMauro Carvalho Chehab return 0; 138385afe608SMauro Carvalho Chehab } 138485afe608SMauro Carvalho Chehab } 138585afe608SMauro Carvalho Chehab if ($output_selection == OUTPUT_INCLUDE) { 138685afe608SMauro Carvalho Chehab if (defined($function_table{$name})) { 138785afe608SMauro Carvalho Chehab return 1; 138885afe608SMauro Carvalho Chehab } else { 138985afe608SMauro Carvalho Chehab return 0; 139085afe608SMauro Carvalho Chehab } 139185afe608SMauro Carvalho Chehab } 139285afe608SMauro Carvalho Chehab die("Please add the new output type at show_warnings()"); 139385afe608SMauro Carvalho Chehab} 139485afe608SMauro Carvalho Chehab 13951da177e4SLinus Torvaldssub dump_enum($$) { 13961da177e4SLinus Torvalds my $x = shift; 13971da177e4SLinus Torvalds my $file = shift; 1398d38c8cfbSMauro Carvalho Chehab my $members; 1399d38c8cfbSMauro Carvalho Chehab 14001da177e4SLinus Torvalds 1401aeec46b9SMartin Waitz $x =~ s@/\*.*?\*/@@gos; # strip comments. 14024468e21eSConchúr Navid # strip #define macros inside enums 14034468e21eSConchúr Navid $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; 1404b6d676dbSRandy Dunlap 1405d38c8cfbSMauro Carvalho Chehab if ($x =~ /typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;/) { 1406d38c8cfbSMauro Carvalho Chehab $declaration_name = $2; 1407d38c8cfbSMauro Carvalho Chehab $members = $1; 1408d38c8cfbSMauro Carvalho Chehab } elsif ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { 14091da177e4SLinus Torvalds $declaration_name = $1; 1410d38c8cfbSMauro Carvalho Chehab $members = $2; 1411d38c8cfbSMauro Carvalho Chehab } 1412d38c8cfbSMauro Carvalho Chehab 1413ae5b17e4SAndy Shevchenko if ($members) { 141452042e2dSMauro Carvalho Chehab if ($identifier ne $declaration_name) { 141552042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; 141652042e2dSMauro Carvalho Chehab return; 141752042e2dSMauro Carvalho Chehab } 141852042e2dSMauro Carvalho Chehab 14195cb5c31cSJohannes Berg my %_members; 14205cb5c31cSJohannes Berg 1421463a0fdcSMarkus Heiser $members =~ s/\s+$//; 14221da177e4SLinus Torvalds 14231da177e4SLinus Torvalds foreach my $arg (split ',', $members) { 14241da177e4SLinus Torvalds $arg =~ s/^\s*(\w+).*/$1/; 14251da177e4SLinus Torvalds push @parameterlist, $arg; 14261da177e4SLinus Torvalds if (!$parameterdescs{$arg}) { 14271da177e4SLinus Torvalds $parameterdescs{$arg} = $undescribed; 142885afe608SMauro Carvalho Chehab if (show_warnings("enum", $declaration_name)) { 14292defb272SMauro Carvalho Chehab print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n"; 14302defb272SMauro Carvalho Chehab } 14311da177e4SLinus Torvalds } 14325cb5c31cSJohannes Berg $_members{$arg} = 1; 14335cb5c31cSJohannes Berg } 14341da177e4SLinus Torvalds 14355cb5c31cSJohannes Berg while (my ($k, $v) = each %parameterdescs) { 14365cb5c31cSJohannes Berg if (!exists($_members{$k})) { 143785afe608SMauro Carvalho Chehab if (show_warnings("enum", $declaration_name)) { 14382defb272SMauro Carvalho Chehab print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n"; 14392defb272SMauro Carvalho Chehab } 14405cb5c31cSJohannes Berg } 14411da177e4SLinus Torvalds } 14421da177e4SLinus Torvalds 14431da177e4SLinus Torvalds output_declaration($declaration_name, 14441da177e4SLinus Torvalds 'enum', 14451da177e4SLinus Torvalds {'enum' => $declaration_name, 14461da177e4SLinus Torvalds 'module' => $modulename, 14471da177e4SLinus Torvalds 'parameterlist' => \@parameterlist, 14481da177e4SLinus Torvalds 'parameterdescs' => \%parameterdescs, 14491da177e4SLinus Torvalds 'sectionlist' => \@sectionlist, 14501da177e4SLinus Torvalds 'sections' => \%sections, 14511da177e4SLinus Torvalds 'purpose' => $declaration_purpose 14521da177e4SLinus Torvalds }); 1453d38c8cfbSMauro Carvalho Chehab } else { 1454d40e1e65SBart Van Assche print STDERR "${file}:$.: error: Cannot parse enum!\n"; 14551da177e4SLinus Torvalds ++$errors; 14561da177e4SLinus Torvalds } 14571da177e4SLinus Torvalds} 14581da177e4SLinus Torvalds 14597d2c6b1eSMauro Carvalho Chehabmy $typedef_type = qr { ((?:\s+[\w\*]+\b){1,8})\s* }x; 14607efc6c42SMauro Carvalho Chehabmy $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; 14617efc6c42SMauro Carvalho Chehabmy $typedef_args = qr { \s*\((.*)\); }x; 14627efc6c42SMauro Carvalho Chehab 14637efc6c42SMauro Carvalho Chehabmy $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x; 14647efc6c42SMauro Carvalho Chehabmy $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x; 14657efc6c42SMauro Carvalho Chehab 14661da177e4SLinus Torvaldssub dump_typedef($$) { 14671da177e4SLinus Torvalds my $x = shift; 14681da177e4SLinus Torvalds my $file = shift; 14691da177e4SLinus Torvalds 1470aeec46b9SMartin Waitz $x =~ s@/\*.*?\*/@@gos; # strip comments. 147183766452SMauro Carvalho Chehab 14727efc6c42SMauro Carvalho Chehab # Parse function typedef prototypes 14737efc6c42SMauro Carvalho Chehab if ($x =~ $typedef1 || $x =~ $typedef2) { 147483766452SMauro Carvalho Chehab $return_type = $1; 147583766452SMauro Carvalho Chehab $declaration_name = $2; 147683766452SMauro Carvalho Chehab my $args = $3; 14776b80975cSMauro Carvalho Chehab $return_type =~ s/^\s+//; 147883766452SMauro Carvalho Chehab 147952042e2dSMauro Carvalho Chehab if ($identifier ne $declaration_name) { 148052042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"; 148152042e2dSMauro Carvalho Chehab return; 148252042e2dSMauro Carvalho Chehab } 148352042e2dSMauro Carvalho Chehab 1484151c468bSMauro Carvalho Chehab create_parameterlist($args, ',', $file, $declaration_name); 148583766452SMauro Carvalho Chehab 148683766452SMauro Carvalho Chehab output_declaration($declaration_name, 148783766452SMauro Carvalho Chehab 'function', 148883766452SMauro Carvalho Chehab {'function' => $declaration_name, 148982801d06SMauro Carvalho Chehab 'typedef' => 1, 149083766452SMauro Carvalho Chehab 'module' => $modulename, 149183766452SMauro Carvalho Chehab 'functiontype' => $return_type, 149283766452SMauro Carvalho Chehab 'parameterlist' => \@parameterlist, 149383766452SMauro Carvalho Chehab 'parameterdescs' => \%parameterdescs, 149483766452SMauro Carvalho Chehab 'parametertypes' => \%parametertypes, 149583766452SMauro Carvalho Chehab 'sectionlist' => \@sectionlist, 149683766452SMauro Carvalho Chehab 'sections' => \%sections, 149783766452SMauro Carvalho Chehab 'purpose' => $declaration_purpose 149883766452SMauro Carvalho Chehab }); 149983766452SMauro Carvalho Chehab return; 150083766452SMauro Carvalho Chehab } 150183766452SMauro Carvalho Chehab 15021da177e4SLinus Torvalds while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { 15031da177e4SLinus Torvalds $x =~ s/\(*.\)\s*;$/;/; 15041da177e4SLinus Torvalds $x =~ s/\[*.\]\s*;$/;/; 15051da177e4SLinus Torvalds } 15061da177e4SLinus Torvalds 15071da177e4SLinus Torvalds if ($x =~ /typedef.*\s+(\w+)\s*;/) { 15081da177e4SLinus Torvalds $declaration_name = $1; 15091da177e4SLinus Torvalds 151052042e2dSMauro Carvalho Chehab if ($identifier ne $declaration_name) { 151152042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n"; 151252042e2dSMauro Carvalho Chehab return; 151352042e2dSMauro Carvalho Chehab } 151452042e2dSMauro Carvalho Chehab 15151da177e4SLinus Torvalds output_declaration($declaration_name, 15161da177e4SLinus Torvalds 'typedef', 15171da177e4SLinus Torvalds {'typedef' => $declaration_name, 15181da177e4SLinus Torvalds 'module' => $modulename, 15191da177e4SLinus Torvalds 'sectionlist' => \@sectionlist, 15201da177e4SLinus Torvalds 'sections' => \%sections, 15211da177e4SLinus Torvalds 'purpose' => $declaration_purpose 15221da177e4SLinus Torvalds }); 15231da177e4SLinus Torvalds } 15241da177e4SLinus Torvalds else { 1525d40e1e65SBart Van Assche print STDERR "${file}:$.: error: Cannot parse typedef!\n"; 15261da177e4SLinus Torvalds ++$errors; 15271da177e4SLinus Torvalds } 15281da177e4SLinus Torvalds} 15291da177e4SLinus Torvalds 1530a1d94aa5SRandy Dunlapsub save_struct_actual($) { 1531a1d94aa5SRandy Dunlap my $actual = shift; 1532a1d94aa5SRandy Dunlap 1533a1d94aa5SRandy Dunlap # strip all spaces from the actual param so that it looks like one string item 1534a1d94aa5SRandy Dunlap $actual =~ s/\s*//g; 1535a1d94aa5SRandy Dunlap $struct_actual = $struct_actual . $actual . " "; 1536a1d94aa5SRandy Dunlap} 1537a1d94aa5SRandy Dunlap 1538151c468bSMauro Carvalho Chehabsub create_parameterlist($$$$) { 15391da177e4SLinus Torvalds my $args = shift; 15401da177e4SLinus Torvalds my $splitter = shift; 15411da177e4SLinus Torvalds my $file = shift; 1542151c468bSMauro Carvalho Chehab my $declaration_name = shift; 15431da177e4SLinus Torvalds my $type; 15441da177e4SLinus Torvalds my $param; 15451da177e4SLinus Torvalds 1546a6d3fe77SMartin Waitz # temporarily replace commas inside function pointer definition 15471da177e4SLinus Torvalds while ($args =~ /(\([^\),]+),/) { 15481da177e4SLinus Torvalds $args =~ s/(\([^\),]+),/$1#/g; 15491da177e4SLinus Torvalds } 15501da177e4SLinus Torvalds 15511da177e4SLinus Torvalds foreach my $arg (split($splitter, $args)) { 15521da177e4SLinus Torvalds # strip comments 15531da177e4SLinus Torvalds $arg =~ s/\/\*.*\*\///; 15541da177e4SLinus Torvalds # strip leading/trailing spaces 15551da177e4SLinus Torvalds $arg =~ s/^\s*//; 15561da177e4SLinus Torvalds $arg =~ s/\s*$//; 15571da177e4SLinus Torvalds $arg =~ s/\s+/ /; 15581da177e4SLinus Torvalds 15591da177e4SLinus Torvalds if ($arg =~ /^#/) { 15601da177e4SLinus Torvalds # Treat preprocessor directive as a typeless variable just to fill 15611da177e4SLinus Torvalds # corresponding data structures "correctly". Catch it later in 15621da177e4SLinus Torvalds # output_* subs. 1563ed8348e2SMauro Carvalho Chehab push_parameter($arg, "", "", $file); 156400d62961SRichard Kennedy } elsif ($arg =~ m/\(.+\)\s*\(/) { 15651da177e4SLinus Torvalds # pointer-to-function 15661da177e4SLinus Torvalds $arg =~ tr/#/,/; 1567336ced2dSAditya Srivastava $arg =~ m/[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)/; 15681da177e4SLinus Torvalds $param = $1; 15691da177e4SLinus Torvalds $type = $arg; 157000d62961SRichard Kennedy $type =~ s/([^\(]+\(\*?)\s*$param/$1/; 1571a1d94aa5SRandy Dunlap save_struct_actual($param); 1572ed8348e2SMauro Carvalho Chehab push_parameter($param, $type, $arg, $file, $declaration_name); 1573aeec46b9SMartin Waitz } elsif ($arg) { 15741da177e4SLinus Torvalds $arg =~ s/\s*:\s*/:/g; 15751da177e4SLinus Torvalds $arg =~ s/\s*\[/\[/g; 15761da177e4SLinus Torvalds 15771da177e4SLinus Torvalds my @args = split('\s*,\s*', $arg); 15781da177e4SLinus Torvalds if ($args[0] =~ m/\*/) { 15791da177e4SLinus Torvalds $args[0] =~ s/(\*+)\s*/ $1/; 15801da177e4SLinus Torvalds } 1581884f2810SBorislav Petkov 1582884f2810SBorislav Petkov my @first_arg; 1583884f2810SBorislav Petkov if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) { 1584884f2810SBorislav Petkov shift @args; 1585884f2810SBorislav Petkov push(@first_arg, split('\s+', $1)); 1586884f2810SBorislav Petkov push(@first_arg, $2); 1587884f2810SBorislav Petkov } else { 1588884f2810SBorislav Petkov @first_arg = split('\s+', shift @args); 1589884f2810SBorislav Petkov } 1590884f2810SBorislav Petkov 15911da177e4SLinus Torvalds unshift(@args, pop @first_arg); 15921da177e4SLinus Torvalds $type = join " ", @first_arg; 15931da177e4SLinus Torvalds 15941da177e4SLinus Torvalds foreach $param (@args) { 15951da177e4SLinus Torvalds if ($param =~ m/^(\*+)\s*(.*)/) { 1596a1d94aa5SRandy Dunlap save_struct_actual($2); 1597ed8348e2SMauro Carvalho Chehab 1598ed8348e2SMauro Carvalho Chehab push_parameter($2, "$type $1", $arg, $file, $declaration_name); 15991da177e4SLinus Torvalds } 16001da177e4SLinus Torvalds elsif ($param =~ m/(.*?):(\d+)/) { 16017b97887eSRandy Dunlap if ($type ne "") { # skip unnamed bit-fields 1602a1d94aa5SRandy Dunlap save_struct_actual($1); 1603ed8348e2SMauro Carvalho Chehab push_parameter($1, "$type:$2", $arg, $file, $declaration_name) 16041da177e4SLinus Torvalds } 16057b97887eSRandy Dunlap } 16061da177e4SLinus Torvalds else { 1607a1d94aa5SRandy Dunlap save_struct_actual($param); 1608ed8348e2SMauro Carvalho Chehab push_parameter($param, $type, $arg, $file, $declaration_name); 16091da177e4SLinus Torvalds } 16101da177e4SLinus Torvalds } 16111da177e4SLinus Torvalds } 16121da177e4SLinus Torvalds } 16131da177e4SLinus Torvalds} 16141da177e4SLinus Torvalds 1615ed8348e2SMauro Carvalho Chehabsub push_parameter($$$$$) { 16161da177e4SLinus Torvalds my $param = shift; 16171da177e4SLinus Torvalds my $type = shift; 1618ed8348e2SMauro Carvalho Chehab my $org_arg = shift; 16191da177e4SLinus Torvalds my $file = shift; 1620151c468bSMauro Carvalho Chehab my $declaration_name = shift; 16211da177e4SLinus Torvalds 16225f8c7c98SRandy Dunlap if (($anon_struct_union == 1) && ($type eq "") && 16235f8c7c98SRandy Dunlap ($param eq "}")) { 16245f8c7c98SRandy Dunlap return; # ignore the ending }; from anon. struct/union 16255f8c7c98SRandy Dunlap } 16265f8c7c98SRandy Dunlap 16275f8c7c98SRandy Dunlap $anon_struct_union = 0; 1628f9b5c530SMauro Carvalho Chehab $param =~ s/[\[\)].*//; 16291da177e4SLinus Torvalds 1630a6d3fe77SMartin Waitz if ($type eq "" && $param =~ /\.\.\.$/) 16311da177e4SLinus Torvalds { 1632c950a173SSilvio Fricke if (!$param =~ /\w\.\.\.$/) { 1633c950a173SSilvio Fricke # handles unnamed variable parameters 1634ef00028bSJonathan Corbet $param = "..."; 1635c950a173SSilvio Fricke } 163643756e34SJonathan Neuschäfer elsif ($param =~ /\w\.\.\.$/) { 163743756e34SJonathan Neuschäfer # for named variable parameters of the form `x...`, remove the dots 163843756e34SJonathan Neuschäfer $param =~ s/\.\.\.$//; 163943756e34SJonathan Neuschäfer } 1640ced69090SRandy Dunlap if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { 1641a6d3fe77SMartin Waitz $parameterdescs{$param} = "variable arguments"; 16421da177e4SLinus Torvalds } 1643ced69090SRandy Dunlap } 16441da177e4SLinus Torvalds elsif ($type eq "" && ($param eq "" or $param eq "void")) 16451da177e4SLinus Torvalds { 16461da177e4SLinus Torvalds $param="void"; 16471da177e4SLinus Torvalds $parameterdescs{void} = "no arguments"; 16481da177e4SLinus Torvalds } 1649134fe01bSRandy Dunlap elsif ($type eq "" && ($param eq "struct" or $param eq "union")) 1650134fe01bSRandy Dunlap # handle unnamed (anonymous) union or struct: 1651134fe01bSRandy Dunlap { 1652134fe01bSRandy Dunlap $type = $param; 1653134fe01bSRandy Dunlap $param = "{unnamed_" . $param . "}"; 1654134fe01bSRandy Dunlap $parameterdescs{$param} = "anonymous\n"; 16555f8c7c98SRandy Dunlap $anon_struct_union = 1; 1656134fe01bSRandy Dunlap } 1657134fe01bSRandy Dunlap 1658a6d3fe77SMartin Waitz # warn if parameter has no description 1659134fe01bSRandy Dunlap # (but ignore ones starting with # as these are not parameters 1660134fe01bSRandy Dunlap # but inline preprocessor statements); 1661151c468bSMauro Carvalho Chehab # Note: It will also ignore void params and unnamed structs/unions 1662f9b5c530SMauro Carvalho Chehab if (!defined $parameterdescs{$param} && $param !~ /^#/) { 1663f9b5c530SMauro Carvalho Chehab $parameterdescs{$param} = $undescribed; 16641da177e4SLinus Torvalds 1665be5cd20cSJonathan Corbet if (show_warnings($type, $declaration_name) && $param !~ /\./) { 1666151c468bSMauro Carvalho Chehab print STDERR 1667151c468bSMauro Carvalho Chehab "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; 16681da177e4SLinus Torvalds ++$warnings; 16691da177e4SLinus Torvalds } 16702defb272SMauro Carvalho Chehab } 16711da177e4SLinus Torvalds 167225985edcSLucas De Marchi # strip spaces from $param so that it is one continuous string 1673e34e7dbbSRandy Dunlap # on @parameterlist; 1674e34e7dbbSRandy Dunlap # this fixes a problem where check_sections() cannot find 1675e34e7dbbSRandy Dunlap # a parameter like "addr[6 + 2]" because it actually appears 1676e34e7dbbSRandy Dunlap # as "addr[6", "+", "2]" on the parameter list; 1677e34e7dbbSRandy Dunlap # but it's better to maintain the param string unchanged for output, 1678e34e7dbbSRandy Dunlap # so just weaken the string compare in check_sections() to ignore 1679e34e7dbbSRandy Dunlap # "[blah" in a parameter string; 1680e34e7dbbSRandy Dunlap ###$param =~ s/\s*//g; 16811da177e4SLinus Torvalds push @parameterlist, $param; 1682ed8348e2SMauro Carvalho Chehab $org_arg =~ s/\s\s+/ /g; 1683ed8348e2SMauro Carvalho Chehab $parametertypes{$param} = $org_arg; 16841da177e4SLinus Torvalds} 16851da177e4SLinus Torvalds 16861081de2dSMauro Carvalho Chehabsub check_sections($$$$$) { 16871081de2dSMauro Carvalho Chehab my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_; 1688a1d94aa5SRandy Dunlap my @sects = split ' ', $sectcheck; 1689a1d94aa5SRandy Dunlap my @prms = split ' ', $prmscheck; 1690a1d94aa5SRandy Dunlap my $err; 1691a1d94aa5SRandy Dunlap my ($px, $sx); 1692a1d94aa5SRandy Dunlap my $prm_clean; # strip trailing "[array size]" and/or beginning "*" 1693a1d94aa5SRandy Dunlap 1694a1d94aa5SRandy Dunlap foreach $sx (0 .. $#sects) { 1695a1d94aa5SRandy Dunlap $err = 1; 1696a1d94aa5SRandy Dunlap foreach $px (0 .. $#prms) { 1697a1d94aa5SRandy Dunlap $prm_clean = $prms[$px]; 1698a1d94aa5SRandy Dunlap $prm_clean =~ s/\[.*\]//; 16991f3a6688SJohannes Berg $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; 1700e34e7dbbSRandy Dunlap # ignore array size in a parameter string; 1701e34e7dbbSRandy Dunlap # however, the original param string may contain 1702e34e7dbbSRandy Dunlap # spaces, e.g.: addr[6 + 2] 1703e34e7dbbSRandy Dunlap # and this appears in @prms as "addr[6" since the 1704e34e7dbbSRandy Dunlap # parameter list is split at spaces; 1705e34e7dbbSRandy Dunlap # hence just ignore "[..." for the sections check; 1706e34e7dbbSRandy Dunlap $prm_clean =~ s/\[.*//; 1707e34e7dbbSRandy Dunlap 1708a1d94aa5SRandy Dunlap ##$prm_clean =~ s/^\**//; 1709a1d94aa5SRandy Dunlap if ($prm_clean eq $sects[$sx]) { 1710a1d94aa5SRandy Dunlap $err = 0; 1711a1d94aa5SRandy Dunlap last; 1712a1d94aa5SRandy Dunlap } 1713a1d94aa5SRandy Dunlap } 1714a1d94aa5SRandy Dunlap if ($err) { 1715a1d94aa5SRandy Dunlap if ($decl_type eq "function") { 1716d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: " . 1717a1d94aa5SRandy Dunlap "Excess function parameter " . 1718a1d94aa5SRandy Dunlap "'$sects[$sx]' " . 1719a1d94aa5SRandy Dunlap "description in '$decl_name'\n"; 1720a1d94aa5SRandy Dunlap ++$warnings; 1721a1d94aa5SRandy Dunlap } 1722a1d94aa5SRandy Dunlap } 1723a1d94aa5SRandy Dunlap } 1724a1d94aa5SRandy Dunlap} 1725a1d94aa5SRandy Dunlap 17261da177e4SLinus Torvalds## 17274092bac7SYacine Belkadi# Checks the section describing the return value of a function. 17284092bac7SYacine Belkadisub check_return_section { 17294092bac7SYacine Belkadi my $file = shift; 17304092bac7SYacine Belkadi my $declaration_name = shift; 17314092bac7SYacine Belkadi my $return_type = shift; 17324092bac7SYacine Belkadi 17334092bac7SYacine Belkadi # Ignore an empty return type (It's a macro) 17344092bac7SYacine Belkadi # Ignore functions with a "void" return type. (But don't ignore "void *") 17354092bac7SYacine Belkadi if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { 17364092bac7SYacine Belkadi return; 17374092bac7SYacine Belkadi } 17384092bac7SYacine Belkadi 17394092bac7SYacine Belkadi if (!defined($sections{$section_return}) || 17404092bac7SYacine Belkadi $sections{$section_return} eq "") { 1741d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: " . 17424092bac7SYacine Belkadi "No description found for return value of " . 17434092bac7SYacine Belkadi "'$declaration_name'\n"; 17444092bac7SYacine Belkadi ++$warnings; 17454092bac7SYacine Belkadi } 17464092bac7SYacine Belkadi} 17474092bac7SYacine Belkadi 17484092bac7SYacine Belkadi## 17491da177e4SLinus Torvalds# takes a function prototype and the name of the current file being 17501da177e4SLinus Torvalds# processed and spits out all the details stored in the global 17511da177e4SLinus Torvalds# arrays/hashes. 17521da177e4SLinus Torvaldssub dump_function($$) { 17531da177e4SLinus Torvalds my $prototype = shift; 17541da177e4SLinus Torvalds my $file = shift; 1755cbb4d3e6SHoria Geanta my $noret = 0; 17561da177e4SLinus Torvalds 17575ef09c96SMauro Carvalho Chehab print_lineno($new_start_line); 17585eb6b4b3SMauro Carvalho Chehab 17591da177e4SLinus Torvalds $prototype =~ s/^static +//; 17601da177e4SLinus Torvalds $prototype =~ s/^extern +//; 17614dc3b16bSPavel Pisa $prototype =~ s/^asmlinkage +//; 17621da177e4SLinus Torvalds $prototype =~ s/^inline +//; 17631da177e4SLinus Torvalds $prototype =~ s/^__inline__ +//; 176432e79401SRandy Dunlap $prototype =~ s/^__inline +//; 176532e79401SRandy Dunlap $prototype =~ s/^__always_inline +//; 176632e79401SRandy Dunlap $prototype =~ s/^noinline +//; 176774fc5c65SRandy Dunlap $prototype =~ s/__init +//; 176820072205SRandy Dunlap $prototype =~ s/__init_or_module +//; 1769*084aa001SAditya Srivastava $prototype =~ s/__flatten +//; 1770270a0096SRandy Dunlap $prototype =~ s/__meminit +//; 177170c95b00SRandy Dunlap $prototype =~ s/__must_check +//; 17720df7c0e3SRandy Dunlap $prototype =~ s/__weak +//; 17730891f959SMatthew Wilcox $prototype =~ s/__sched +//; 177495e760cbSRandy Dunlap $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; 1775cbb4d3e6SHoria Geanta my $define = $prototype =~ s/^#\s*define\s+//; #ak added 1776*084aa001SAditya Srivastava $prototype =~ s/__attribute_const__ +//; 1777b1aaa546SPaolo Bonzini $prototype =~ s/__attribute__\s*\(\( 1778b1aaa546SPaolo Bonzini (?: 1779b1aaa546SPaolo Bonzini [\w\s]++ # attribute name 1780b1aaa546SPaolo Bonzini (?:\([^)]*+\))? # attribute arguments 1781b1aaa546SPaolo Bonzini \s*+,? # optional comma at the end 1782b1aaa546SPaolo Bonzini )+ 1783b1aaa546SPaolo Bonzini \)\)\s+//x; 17841da177e4SLinus Torvalds 17851da177e4SLinus Torvalds # Yes, this truly is vile. We are looking for: 17861da177e4SLinus Torvalds # 1. Return type (may be nothing if we're looking at a macro) 17871da177e4SLinus Torvalds # 2. Function name 17881da177e4SLinus Torvalds # 3. Function parameters. 17891da177e4SLinus Torvalds # 17901da177e4SLinus Torvalds # All the while we have to watch out for function pointer parameters 17911da177e4SLinus Torvalds # (which IIRC is what the two sections are for), C types (these 17921da177e4SLinus Torvalds # regexps don't even start to express all the possibilities), and 17931da177e4SLinus Torvalds # so on. 17941da177e4SLinus Torvalds # 17951da177e4SLinus Torvalds # If you mess with these regexps, it's a good idea to check that 17961da177e4SLinus Torvalds # the following functions' documentation still comes out right: 17971da177e4SLinus Torvalds # - parport_register_device (function pointer parameters) 17981da177e4SLinus Torvalds # - atomic_set (macro) 17999598f91fSMartin Waitz # - pci_match_device, __copy_to_user (long return type) 18001da177e4SLinus Torvalds 1801cbb4d3e6SHoria Geanta if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) { 1802cbb4d3e6SHoria Geanta # This is an object-like macro, it has no return type and no parameter 1803cbb4d3e6SHoria Geanta # list. 1804cbb4d3e6SHoria Geanta # Function-like macros are not allowed to have spaces between 1805cbb4d3e6SHoria Geanta # declaration_name and opening parenthesis (notice the \s+). 1806cbb4d3e6SHoria Geanta $return_type = $1; 1807cbb4d3e6SHoria Geanta $declaration_name = $2; 1808cbb4d3e6SHoria Geanta $noret = 1; 1809cbb4d3e6SHoria Geanta } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18101da177e4SLinus Torvalds $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18115a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18121da177e4SLinus Torvalds $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 181394b3e03cSRandy Dunlap $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18141da177e4SLinus Torvalds $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18155a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || 18161da177e4SLinus Torvalds $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18171da177e4SLinus Torvalds $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18185a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18191da177e4SLinus Torvalds $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18205a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18211da177e4SLinus Torvalds $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18225a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18239598f91fSMartin Waitz $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18245a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || 18255a0bc578SMatthew Wilcox $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { 18261da177e4SLinus Torvalds $return_type = $1; 18271da177e4SLinus Torvalds $declaration_name = $2; 18281da177e4SLinus Torvalds my $args = $3; 18291da177e4SLinus Torvalds 1830151c468bSMauro Carvalho Chehab create_parameterlist($args, ',', $file, $declaration_name); 18311da177e4SLinus Torvalds } else { 1832d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n"; 18331da177e4SLinus Torvalds return; 18341da177e4SLinus Torvalds } 18351da177e4SLinus Torvalds 183652042e2dSMauro Carvalho Chehab if ($identifier ne $declaration_name) { 183752042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n"; 183852042e2dSMauro Carvalho Chehab return; 183952042e2dSMauro Carvalho Chehab } 184052042e2dSMauro Carvalho Chehab 1841a1d94aa5SRandy Dunlap my $prms = join " ", @parameterlist; 18421081de2dSMauro Carvalho Chehab check_sections($file, $declaration_name, "function", $sectcheck, $prms); 1843a1d94aa5SRandy Dunlap 18444092bac7SYacine Belkadi # This check emits a lot of warnings at the moment, because many 18454092bac7SYacine Belkadi # functions don't have a 'Return' doc section. So until the number 18464092bac7SYacine Belkadi # of warnings goes sufficiently down, the check is only performed in 18474092bac7SYacine Belkadi # verbose mode. 18484092bac7SYacine Belkadi # TODO: always perform the check. 1849cbb4d3e6SHoria Geanta if ($verbose && !$noret) { 18504092bac7SYacine Belkadi check_return_section($file, $declaration_name, $return_type); 18514092bac7SYacine Belkadi } 18524092bac7SYacine Belkadi 185347bcacfdSMauro Carvalho Chehab # The function parser can be called with a typedef parameter. 185447bcacfdSMauro Carvalho Chehab # Handle it. 185547bcacfdSMauro Carvalho Chehab if ($return_type =~ /typedef/) { 185647bcacfdSMauro Carvalho Chehab output_declaration($declaration_name, 185747bcacfdSMauro Carvalho Chehab 'function', 185847bcacfdSMauro Carvalho Chehab {'function' => $declaration_name, 185947bcacfdSMauro Carvalho Chehab 'typedef' => 1, 186047bcacfdSMauro Carvalho Chehab 'module' => $modulename, 186147bcacfdSMauro Carvalho Chehab 'functiontype' => $return_type, 186247bcacfdSMauro Carvalho Chehab 'parameterlist' => \@parameterlist, 186347bcacfdSMauro Carvalho Chehab 'parameterdescs' => \%parameterdescs, 186447bcacfdSMauro Carvalho Chehab 'parametertypes' => \%parametertypes, 186547bcacfdSMauro Carvalho Chehab 'sectionlist' => \@sectionlist, 186647bcacfdSMauro Carvalho Chehab 'sections' => \%sections, 186747bcacfdSMauro Carvalho Chehab 'purpose' => $declaration_purpose 186847bcacfdSMauro Carvalho Chehab }); 186947bcacfdSMauro Carvalho Chehab } else { 18701da177e4SLinus Torvalds output_declaration($declaration_name, 18711da177e4SLinus Torvalds 'function', 18721da177e4SLinus Torvalds {'function' => $declaration_name, 18731da177e4SLinus Torvalds 'module' => $modulename, 18741da177e4SLinus Torvalds 'functiontype' => $return_type, 18751da177e4SLinus Torvalds 'parameterlist' => \@parameterlist, 18761da177e4SLinus Torvalds 'parameterdescs' => \%parameterdescs, 18771da177e4SLinus Torvalds 'parametertypes' => \%parametertypes, 18781da177e4SLinus Torvalds 'sectionlist' => \@sectionlist, 18791da177e4SLinus Torvalds 'sections' => \%sections, 18801da177e4SLinus Torvalds 'purpose' => $declaration_purpose 18811da177e4SLinus Torvalds }); 18821da177e4SLinus Torvalds } 188347bcacfdSMauro Carvalho Chehab} 18841da177e4SLinus Torvalds 18851da177e4SLinus Torvaldssub reset_state { 18861da177e4SLinus Torvalds $function = ""; 18871da177e4SLinus Torvalds %parameterdescs = (); 18881da177e4SLinus Torvalds %parametertypes = (); 18891da177e4SLinus Torvalds @parameterlist = (); 18901da177e4SLinus Torvalds %sections = (); 18911da177e4SLinus Torvalds @sectionlist = (); 1892a1d94aa5SRandy Dunlap $sectcheck = ""; 1893a1d94aa5SRandy Dunlap $struct_actual = ""; 18941da177e4SLinus Torvalds $prototype = ""; 18951da177e4SLinus Torvalds 189648af606aSJani Nikula $state = STATE_NORMAL; 189748af606aSJani Nikula $inline_doc_state = STATE_INLINE_NA; 18981da177e4SLinus Torvalds} 18991da177e4SLinus Torvalds 190056afb0f8SJason Baronsub tracepoint_munge($) { 190156afb0f8SJason Baron my $file = shift; 190256afb0f8SJason Baron my $tracepointname = 0; 190356afb0f8SJason Baron my $tracepointargs = 0; 190456afb0f8SJason Baron 190556afb0f8SJason Baron if ($prototype =~ m/TRACE_EVENT\((.*?),/) { 190656afb0f8SJason Baron $tracepointname = $1; 190756afb0f8SJason Baron } 19083a9089fdSJason Baron if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) { 19093a9089fdSJason Baron $tracepointname = $1; 19103a9089fdSJason Baron } 19113a9089fdSJason Baron if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) { 19123a9089fdSJason Baron $tracepointname = $2; 19133a9089fdSJason Baron } 19143a9089fdSJason Baron $tracepointname =~ s/^\s+//; #strip leading whitespace 191556afb0f8SJason Baron if ($prototype =~ m/TP_PROTO\((.*?)\)/) { 191656afb0f8SJason Baron $tracepointargs = $1; 191756afb0f8SJason Baron } 191856afb0f8SJason Baron if (($tracepointname eq 0) || ($tracepointargs eq 0)) { 1919d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n". 192056afb0f8SJason Baron "$prototype\n"; 192156afb0f8SJason Baron } else { 192256afb0f8SJason Baron $prototype = "static inline void trace_$tracepointname($tracepointargs)"; 192352042e2dSMauro Carvalho Chehab $identifier = "trace_$identifier"; 192456afb0f8SJason Baron } 192556afb0f8SJason Baron} 192656afb0f8SJason Baron 1927b4870bc5SRandy Dunlapsub syscall_munge() { 1928b4870bc5SRandy Dunlap my $void = 0; 1929b4870bc5SRandy Dunlap 19307c9aa015SMauro Carvalho Chehab $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's 1931b4870bc5SRandy Dunlap## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) { 1932b4870bc5SRandy Dunlap if ($prototype =~ m/SYSCALL_DEFINE0/) { 1933b4870bc5SRandy Dunlap $void = 1; 1934b4870bc5SRandy Dunlap## $prototype = "long sys_$1(void)"; 1935b4870bc5SRandy Dunlap } 1936b4870bc5SRandy Dunlap 1937b4870bc5SRandy Dunlap $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name 1938b4870bc5SRandy Dunlap if ($prototype =~ m/long (sys_.*?),/) { 1939b4870bc5SRandy Dunlap $prototype =~ s/,/\(/; 1940b4870bc5SRandy Dunlap } elsif ($void) { 1941b4870bc5SRandy Dunlap $prototype =~ s/\)/\(void\)/; 1942b4870bc5SRandy Dunlap } 1943b4870bc5SRandy Dunlap 1944b4870bc5SRandy Dunlap # now delete all of the odd-number commas in $prototype 1945b4870bc5SRandy Dunlap # so that arg types & arg names don't have a comma between them 1946b4870bc5SRandy Dunlap my $count = 0; 1947b4870bc5SRandy Dunlap my $len = length($prototype); 1948b4870bc5SRandy Dunlap if ($void) { 1949b4870bc5SRandy Dunlap $len = 0; # skip the for-loop 1950b4870bc5SRandy Dunlap } 1951b4870bc5SRandy Dunlap for (my $ix = 0; $ix < $len; $ix++) { 1952b4870bc5SRandy Dunlap if (substr($prototype, $ix, 1) eq ',') { 1953b4870bc5SRandy Dunlap $count++; 1954b4870bc5SRandy Dunlap if ($count % 2 == 1) { 1955b4870bc5SRandy Dunlap substr($prototype, $ix, 1) = ' '; 1956b4870bc5SRandy Dunlap } 1957b4870bc5SRandy Dunlap } 1958b4870bc5SRandy Dunlap } 1959b4870bc5SRandy Dunlap} 1960b4870bc5SRandy Dunlap 1961b7afa92bSDaniel Vettersub process_proto_function($$) { 19621da177e4SLinus Torvalds my $x = shift; 19631da177e4SLinus Torvalds my $file = shift; 19641da177e4SLinus Torvalds 196551f5a0c8SRandy Dunlap $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line 196651f5a0c8SRandy Dunlap 1967890c78c2SRandy Dunlap if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) { 19681da177e4SLinus Torvalds # do nothing 19691da177e4SLinus Torvalds } 19701da177e4SLinus Torvalds elsif ($x =~ /([^\{]*)/) { 19711da177e4SLinus Torvalds $prototype .= $1; 19721da177e4SLinus Torvalds } 1973b4870bc5SRandy Dunlap 1974890c78c2SRandy Dunlap if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) { 19751da177e4SLinus Torvalds $prototype =~ s@/\*.*?\*/@@gos; # strip comments. 19761da177e4SLinus Torvalds $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. 19771da177e4SLinus Torvalds $prototype =~ s@^\s+@@gos; # strip leading spaces 19787ae281b0SMauro Carvalho Chehab 19797ae281b0SMauro Carvalho Chehab # Handle prototypes for function pointers like: 19807ae281b0SMauro Carvalho Chehab # int (*pcs_config)(struct foo) 19817ae281b0SMauro Carvalho Chehab $prototype =~ s@^(\S+\s+)\(\s*\*(\S+)\)@$1$2@gos; 19827ae281b0SMauro Carvalho Chehab 1983b4870bc5SRandy Dunlap if ($prototype =~ /SYSCALL_DEFINE/) { 1984b4870bc5SRandy Dunlap syscall_munge(); 1985b4870bc5SRandy Dunlap } 19863a9089fdSJason Baron if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ || 19873a9089fdSJason Baron $prototype =~ /DEFINE_SINGLE_EVENT/) 19883a9089fdSJason Baron { 198956afb0f8SJason Baron tracepoint_munge($file); 199056afb0f8SJason Baron } 19911da177e4SLinus Torvalds dump_function($prototype, $file); 19921da177e4SLinus Torvalds reset_state(); 19931da177e4SLinus Torvalds } 19941da177e4SLinus Torvalds} 19951da177e4SLinus Torvalds 1996b7afa92bSDaniel Vettersub process_proto_type($$) { 19971da177e4SLinus Torvalds my $x = shift; 19981da177e4SLinus Torvalds my $file = shift; 19991da177e4SLinus Torvalds 20001da177e4SLinus Torvalds $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. 20011da177e4SLinus Torvalds $x =~ s@^\s+@@gos; # strip leading spaces 20021da177e4SLinus Torvalds $x =~ s@\s+$@@gos; # strip trailing spaces 200351f5a0c8SRandy Dunlap $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line 200451f5a0c8SRandy Dunlap 20051da177e4SLinus Torvalds if ($x =~ /^#/) { 20061da177e4SLinus Torvalds # To distinguish preprocessor directive from regular declaration later. 20071da177e4SLinus Torvalds $x .= ";"; 20081da177e4SLinus Torvalds } 20091da177e4SLinus Torvalds 20101da177e4SLinus Torvalds while (1) { 2011673bb2dfSBen Hutchings if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) { 2012463a0fdcSMarkus Heiser if( length $prototype ) { 2013463a0fdcSMarkus Heiser $prototype .= " " 2014463a0fdcSMarkus Heiser } 20151da177e4SLinus Torvalds $prototype .= $1 . $2; 20161da177e4SLinus Torvalds ($2 eq '{') && $brcount++; 20171da177e4SLinus Torvalds ($2 eq '}') && $brcount--; 20181da177e4SLinus Torvalds if (($2 eq ';') && ($brcount == 0)) { 20191da177e4SLinus Torvalds dump_declaration($prototype, $file); 20201da177e4SLinus Torvalds reset_state(); 20211da177e4SLinus Torvalds last; 20221da177e4SLinus Torvalds } 20231da177e4SLinus Torvalds $x = $3; 20241da177e4SLinus Torvalds } else { 20251da177e4SLinus Torvalds $prototype .= $x; 20261da177e4SLinus Torvalds last; 20271da177e4SLinus Torvalds } 20281da177e4SLinus Torvalds } 20291da177e4SLinus Torvalds} 20301da177e4SLinus Torvalds 20316b5b55f6SRandy Dunlap 20321ad560e4SJani Nikulasub map_filename($) { 20331ad560e4SJani Nikula my $file; 20341ad560e4SJani Nikula my ($orig_file) = @_; 20351ad560e4SJani Nikula 20361ad560e4SJani Nikula if (defined($ENV{'SRCTREE'})) { 20371ad560e4SJani Nikula $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; 20381ad560e4SJani Nikula } else { 20391ad560e4SJani Nikula $file = $orig_file; 20401ad560e4SJani Nikula } 20411ad560e4SJani Nikula 20421ad560e4SJani Nikula if (defined($source_map{$file})) { 20431ad560e4SJani Nikula $file = $source_map{$file}; 20441ad560e4SJani Nikula } 20451ad560e4SJani Nikula 20461ad560e4SJani Nikula return $file; 20471ad560e4SJani Nikula} 20481ad560e4SJani Nikula 204988c2b57dSJani Nikulasub process_export_file($) { 205088c2b57dSJani Nikula my ($orig_file) = @_; 205188c2b57dSJani Nikula my $file = map_filename($orig_file); 205288c2b57dSJani Nikula 205388c2b57dSJani Nikula if (!open(IN,"<$file")) { 205488c2b57dSJani Nikula print STDERR "Error: Cannot open file $file\n"; 205588c2b57dSJani Nikula ++$errors; 205688c2b57dSJani Nikula return; 205788c2b57dSJani Nikula } 205888c2b57dSJani Nikula 205988c2b57dSJani Nikula while (<IN>) { 206088c2b57dSJani Nikula if (/$export_symbol/) { 2061eab795ddSMauro Carvalho Chehab next if (defined($nosymbol_table{$2})); 206288c2b57dSJani Nikula $function_table{$2} = 1; 206388c2b57dSJani Nikula } 206488c2b57dSJani Nikula } 206588c2b57dSJani Nikula 206688c2b57dSJani Nikula close(IN); 206788c2b57dSJani Nikula} 206888c2b57dSJani Nikula 206907048d13SJonathan Corbet# 207007048d13SJonathan Corbet# Parsers for the various processing states. 207107048d13SJonathan Corbet# 207207048d13SJonathan Corbet# STATE_NORMAL: looking for the /** to begin everything. 207307048d13SJonathan Corbet# 207407048d13SJonathan Corbetsub process_normal() { 20751da177e4SLinus Torvalds if (/$doc_start/o) { 207648af606aSJani Nikula $state = STATE_NAME; # next line is always the function name 2077850622dfSRandy Dunlap $in_doc_sect = 0; 20780b0f5f29SDaniel Vetter $declaration_start_line = $. + 1; 20791da177e4SLinus Torvalds } 208007048d13SJonathan Corbet} 208107048d13SJonathan Corbet 20823cac2bc4SJonathan Corbet# 20833cac2bc4SJonathan Corbet# STATE_NAME: Looking for the "name - description" line 20843cac2bc4SJonathan Corbet# 20853cac2bc4SJonathan Corbetsub process_name($$) { 20863cac2bc4SJonathan Corbet my $file = shift; 20871da177e4SLinus Torvalds my $descr; 20881da177e4SLinus Torvalds 20891da177e4SLinus Torvalds if (/$doc_block/o) { 209048af606aSJani Nikula $state = STATE_DOCBLOCK; 20911da177e4SLinus Torvalds $contents = ""; 20925ef09c96SMauro Carvalho Chehab $new_start_line = $.; 20930b0f5f29SDaniel Vetter 20941da177e4SLinus Torvalds if ( $1 eq "" ) { 20951da177e4SLinus Torvalds $section = $section_intro; 20961da177e4SLinus Torvalds } else { 20971da177e4SLinus Torvalds $section = $1; 20981da177e4SLinus Torvalds } 209952042e2dSMauro Carvalho Chehab } elsif (/$doc_decl/o) { 21001da177e4SLinus Torvalds $identifier = $1; 210152042e2dSMauro Carvalho Chehab if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { 21021da177e4SLinus Torvalds $identifier = $1; 21031da177e4SLinus Torvalds } 210452042e2dSMauro Carvalho Chehab if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { 210552042e2dSMauro Carvalho Chehab $decl_type = $1; 210652042e2dSMauro Carvalho Chehab $identifier = $2; 210752042e2dSMauro Carvalho Chehab } else { 210852042e2dSMauro Carvalho Chehab $decl_type = 'function'; 210952042e2dSMauro Carvalho Chehab $identifier =~ s/^define\s+//; 211052042e2dSMauro Carvalho Chehab } 211152042e2dSMauro Carvalho Chehab $identifier =~ s/\s+$//; 21121da177e4SLinus Torvalds 211317b78717SJonathan Corbet $state = STATE_BODY; 21140b0f5f29SDaniel Vetter # if there's no @param blocks need to set up default section 21150b0f5f29SDaniel Vetter # here 21162f4ad40aSJani Nikula $contents = ""; 21172f4ad40aSJani Nikula $section = $section_default; 21180b0f5f29SDaniel Vetter $new_start_line = $. + 1; 211952042e2dSMauro Carvalho Chehab if (/[-:](.*)/) { 212051f5a0c8SRandy Dunlap # strip leading/trailing/multiple spaces 2121a21217daSRandy Dunlap $descr= $1; 2122a21217daSRandy Dunlap $descr =~ s/^\s*//; 2123a21217daSRandy Dunlap $descr =~ s/\s*$//; 212412ae6779SDaniel Santos $descr =~ s/\s+/ /g; 21250bba924cSJonathan Corbet $declaration_purpose = $descr; 212617b78717SJonathan Corbet $state = STATE_BODY_MAYBE; 21271da177e4SLinus Torvalds } else { 21281da177e4SLinus Torvalds $declaration_purpose = ""; 21291da177e4SLinus Torvalds } 213077cc23b8SRandy Dunlap 213177cc23b8SRandy Dunlap if (($declaration_purpose eq "") && $verbose) { 2132d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: missing initial short description on line:\n"; 213377cc23b8SRandy Dunlap print STDERR $_; 213477cc23b8SRandy Dunlap ++$warnings; 213577cc23b8SRandy Dunlap } 213677cc23b8SRandy Dunlap 213752042e2dSMauro Carvalho Chehab if ($identifier eq "") { 213852042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; 213952042e2dSMauro Carvalho Chehab print STDERR $_; 214052042e2dSMauro Carvalho Chehab ++$warnings; 214152042e2dSMauro Carvalho Chehab $state = STATE_NORMAL; 21421da177e4SLinus Torvalds } 21431da177e4SLinus Torvalds 21441da177e4SLinus Torvalds if ($verbose) { 214552042e2dSMauro Carvalho Chehab print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n"; 21461da177e4SLinus Torvalds } 21471da177e4SLinus Torvalds } else { 2148d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", 21491da177e4SLinus Torvalds " - I thought it was a doc line\n"; 21501da177e4SLinus Torvalds ++$warnings; 215148af606aSJani Nikula $state = STATE_NORMAL; 21521da177e4SLinus Torvalds } 21533cac2bc4SJonathan Corbet} 21543cac2bc4SJonathan Corbet 21553cac2bc4SJonathan Corbet 2156d742f24dSJonathan Corbet# 2157d742f24dSJonathan Corbet# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. 2158d742f24dSJonathan Corbet# 2159d742f24dSJonathan Corbetsub process_body($$) { 2160d742f24dSJonathan Corbet my $file = shift; 21613cac2bc4SJonathan Corbet 216243756e34SJonathan Neuschäfer # Until all named variable macro parameters are 216343756e34SJonathan Neuschäfer # documented using the bare name (`x`) rather than with 216443756e34SJonathan Neuschäfer # dots (`x...`), strip the dots: 216543756e34SJonathan Neuschäfer if ($section =~ /\w\.\.\.$/) { 216643756e34SJonathan Neuschäfer $section =~ s/\.\.\.$//; 216743756e34SJonathan Neuschäfer 216843756e34SJonathan Neuschäfer if ($verbose) { 216943756e34SJonathan Neuschäfer print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n"; 217043756e34SJonathan Neuschäfer ++$warnings; 217143756e34SJonathan Neuschäfer } 217243756e34SJonathan Neuschäfer } 217343756e34SJonathan Neuschäfer 21740d55d48bSMauro Carvalho Chehab if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) { 21750d55d48bSMauro Carvalho Chehab dump_section($file, $section, $contents); 21760d55d48bSMauro Carvalho Chehab $section = $section_default; 21775ef09c96SMauro Carvalho Chehab $new_start_line = $.; 21780d55d48bSMauro Carvalho Chehab $contents = ""; 21790d55d48bSMauro Carvalho Chehab } 21800d55d48bSMauro Carvalho Chehab 2181f624adefSJani Nikula if (/$doc_sect/i) { # case insensitive for supported section names 21821da177e4SLinus Torvalds $newsection = $1; 21831da177e4SLinus Torvalds $newcontents = $2; 21841da177e4SLinus Torvalds 2185f624adefSJani Nikula # map the supported section names to the canonical names 2186f624adefSJani Nikula if ($newsection =~ m/^description$/i) { 2187f624adefSJani Nikula $newsection = $section_default; 2188f624adefSJani Nikula } elsif ($newsection =~ m/^context$/i) { 2189f624adefSJani Nikula $newsection = $section_context; 2190f624adefSJani Nikula } elsif ($newsection =~ m/^returns?$/i) { 2191f624adefSJani Nikula $newsection = $section_return; 2192f624adefSJani Nikula } elsif ($newsection =~ m/^\@return$/) { 2193f624adefSJani Nikula # special: @return is a section, not a param description 2194f624adefSJani Nikula $newsection = $section_return; 2195f624adefSJani Nikula } 2196f624adefSJani Nikula 2197792aa2f2SRandy Dunlap if (($contents ne "") && ($contents ne "\n")) { 2198850622dfSRandy Dunlap if (!$in_doc_sect && $verbose) { 2199d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: contents before sections\n"; 2200850622dfSRandy Dunlap ++$warnings; 2201850622dfSRandy Dunlap } 22020bba924cSJonathan Corbet dump_section($file, $section, $contents); 22031da177e4SLinus Torvalds $section = $section_default; 22041da177e4SLinus Torvalds } 22051da177e4SLinus Torvalds 2206850622dfSRandy Dunlap $in_doc_sect = 1; 220717b78717SJonathan Corbet $state = STATE_BODY; 22081da177e4SLinus Torvalds $contents = $newcontents; 22090b0f5f29SDaniel Vetter $new_start_line = $.; 22107c9aa015SMauro Carvalho Chehab while (substr($contents, 0, 1) eq " ") { 221105189497SRandy Dunlap $contents = substr($contents, 1); 221205189497SRandy Dunlap } 22130a726301SJani Nikula if ($contents ne "") { 22141da177e4SLinus Torvalds $contents .= "\n"; 22151da177e4SLinus Torvalds } 22161da177e4SLinus Torvalds $section = $newsection; 2217b7886de4SJani Nikula $leading_space = undef; 22181da177e4SLinus Torvalds } elsif (/$doc_end/) { 22194c98ecafSRandy Dunlap if (($contents ne "") && ($contents ne "\n")) { 22200bba924cSJonathan Corbet dump_section($file, $section, $contents); 22211da177e4SLinus Torvalds $section = $section_default; 22221da177e4SLinus Torvalds $contents = ""; 22231da177e4SLinus Torvalds } 222446b958ebSRandy Dunlap # look for doc_com + <text> + doc_end: 222546b958ebSRandy Dunlap if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { 2226d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: suspicious ending line: $_"; 222746b958ebSRandy Dunlap ++$warnings; 222846b958ebSRandy Dunlap } 22291da177e4SLinus Torvalds 22301da177e4SLinus Torvalds $prototype = ""; 223148af606aSJani Nikula $state = STATE_PROTO; 22321da177e4SLinus Torvalds $brcount = 0; 22335ef09c96SMauro Carvalho Chehab $new_start_line = $. + 1; 22341da177e4SLinus Torvalds } elsif (/$doc_content/) { 22356423133bSJohannes Weiner if ($1 eq "") { 22360d55d48bSMauro Carvalho Chehab if ($section eq $section_context) { 22370bba924cSJonathan Corbet dump_section($file, $section, $contents); 22381da177e4SLinus Torvalds $section = $section_default; 22391da177e4SLinus Torvalds $contents = ""; 22400b0f5f29SDaniel Vetter $new_start_line = $.; 22410d55d48bSMauro Carvalho Chehab $state = STATE_BODY; 22421da177e4SLinus Torvalds } else { 22430d55d48bSMauro Carvalho Chehab if ($section ne $section_default) { 22440d55d48bSMauro Carvalho Chehab $state = STATE_BODY_WITH_BLANK_LINE; 22450d55d48bSMauro Carvalho Chehab } else { 22460d55d48bSMauro Carvalho Chehab $state = STATE_BODY; 22470d55d48bSMauro Carvalho Chehab } 22486423133bSJohannes Weiner $contents .= "\n"; 22496423133bSJohannes Weiner } 225017b78717SJonathan Corbet } elsif ($state == STATE_BODY_MAYBE) { 22516423133bSJohannes Weiner # Continued declaration purpose 22526423133bSJohannes Weiner chomp($declaration_purpose); 22530bba924cSJonathan Corbet $declaration_purpose .= " " . $1; 225412ae6779SDaniel Santos $declaration_purpose =~ s/\s+/ /g; 22556423133bSJohannes Weiner } else { 2256b7886de4SJani Nikula my $cont = $1; 2257b7886de4SJani Nikula if ($section =~ m/^@/ || $section eq $section_context) { 2258b7886de4SJani Nikula if (!defined $leading_space) { 2259b7886de4SJani Nikula if ($cont =~ m/^(\s+)/) { 2260b7886de4SJani Nikula $leading_space = $1; 2261b7886de4SJani Nikula } else { 2262b7886de4SJani Nikula $leading_space = ""; 2263b7886de4SJani Nikula } 2264b7886de4SJani Nikula } 2265b7886de4SJani Nikula $cont =~ s/^$leading_space//; 2266b7886de4SJani Nikula } 2267b7886de4SJani Nikula $contents .= $cont . "\n"; 22681da177e4SLinus Torvalds } 22691da177e4SLinus Torvalds } else { 22701da177e4SLinus Torvalds # i dont know - bad line? ignore. 2271d40e1e65SBart Van Assche print STDERR "${file}:$.: warning: bad line: $_"; 22721da177e4SLinus Torvalds ++$warnings; 22731da177e4SLinus Torvalds } 2274d742f24dSJonathan Corbet} 2275d742f24dSJonathan Corbet 2276d742f24dSJonathan Corbet 2277cc794812SJonathan Corbet# 2278cc794812SJonathan Corbet# STATE_PROTO: reading a function/whatever prototype. 2279cc794812SJonathan Corbet# 2280cc794812SJonathan Corbetsub process_proto($$) { 2281cc794812SJonathan Corbet my $file = shift; 2282cc794812SJonathan Corbet 2283cc794812SJonathan Corbet if (/$doc_inline_oneline/) { 2284cc794812SJonathan Corbet $section = $1; 2285cc794812SJonathan Corbet $contents = $2; 2286cc794812SJonathan Corbet if ($contents ne "") { 2287cc794812SJonathan Corbet $contents .= "\n"; 2288cc794812SJonathan Corbet dump_section($file, $section, $contents); 2289cc794812SJonathan Corbet $section = $section_default; 2290cc794812SJonathan Corbet $contents = ""; 2291cc794812SJonathan Corbet } 2292cc794812SJonathan Corbet } elsif (/$doc_inline_start/) { 2293cc794812SJonathan Corbet $state = STATE_INLINE; 2294cc794812SJonathan Corbet $inline_doc_state = STATE_INLINE_NAME; 2295cc794812SJonathan Corbet } elsif ($decl_type eq 'function') { 2296cc794812SJonathan Corbet process_proto_function($_, $file); 2297cc794812SJonathan Corbet } else { 2298cc794812SJonathan Corbet process_proto_type($_, $file); 2299cc794812SJonathan Corbet } 2300cc794812SJonathan Corbet} 2301cc794812SJonathan Corbet 2302c17add56SJonathan Corbet# 2303c17add56SJonathan Corbet# STATE_DOCBLOCK: within a DOC: block. 2304c17add56SJonathan Corbet# 2305c17add56SJonathan Corbetsub process_docblock($$) { 2306c17add56SJonathan Corbet my $file = shift; 2307cc794812SJonathan Corbet 2308c17add56SJonathan Corbet if (/$doc_end/) { 2309c17add56SJonathan Corbet dump_doc_section($file, $section, $contents); 2310c17add56SJonathan Corbet $section = $section_default; 2311c17add56SJonathan Corbet $contents = ""; 2312c17add56SJonathan Corbet $function = ""; 2313c17add56SJonathan Corbet %parameterdescs = (); 2314c17add56SJonathan Corbet %parametertypes = (); 2315c17add56SJonathan Corbet @parameterlist = (); 2316c17add56SJonathan Corbet %sections = (); 2317c17add56SJonathan Corbet @sectionlist = (); 2318c17add56SJonathan Corbet $prototype = ""; 2319c17add56SJonathan Corbet $state = STATE_NORMAL; 2320c17add56SJonathan Corbet } elsif (/$doc_content/) { 2321c17add56SJonathan Corbet if ( $1 eq "" ) { 2322c17add56SJonathan Corbet $contents .= $blankline; 2323c17add56SJonathan Corbet } else { 2324c17add56SJonathan Corbet $contents .= $1 . "\n"; 2325c17add56SJonathan Corbet } 2326c17add56SJonathan Corbet } 2327d742f24dSJonathan Corbet} 2328d742f24dSJonathan Corbet 2329c17add56SJonathan Corbet# 2330c17add56SJonathan Corbet# STATE_INLINE: docbook comments within a prototype. 2331c17add56SJonathan Corbet# 2332c17add56SJonathan Corbetsub process_inline($$) { 2333c17add56SJonathan Corbet my $file = shift; 2334d742f24dSJonathan Corbet 2335a4c6ebedSDanilo Cesar Lemes de Paula # First line (state 1) needs to be a @parameter 233648af606aSJani Nikula if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { 2337a4c6ebedSDanilo Cesar Lemes de Paula $section = $1; 2338a4c6ebedSDanilo Cesar Lemes de Paula $contents = $2; 23390b0f5f29SDaniel Vetter $new_start_line = $.; 2340a4c6ebedSDanilo Cesar Lemes de Paula if ($contents ne "") { 23417c9aa015SMauro Carvalho Chehab while (substr($contents, 0, 1) eq " ") { 2342a4c6ebedSDanilo Cesar Lemes de Paula $contents = substr($contents, 1); 2343a4c6ebedSDanilo Cesar Lemes de Paula } 2344a4c6ebedSDanilo Cesar Lemes de Paula $contents .= "\n"; 2345a4c6ebedSDanilo Cesar Lemes de Paula } 234648af606aSJani Nikula $inline_doc_state = STATE_INLINE_TEXT; 2347a4c6ebedSDanilo Cesar Lemes de Paula # Documentation block end */ 234848af606aSJani Nikula } elsif (/$doc_inline_end/) { 2349a4c6ebedSDanilo Cesar Lemes de Paula if (($contents ne "") && ($contents ne "\n")) { 23500bba924cSJonathan Corbet dump_section($file, $section, $contents); 2351a4c6ebedSDanilo Cesar Lemes de Paula $section = $section_default; 2352a4c6ebedSDanilo Cesar Lemes de Paula $contents = ""; 2353a4c6ebedSDanilo Cesar Lemes de Paula } 235448af606aSJani Nikula $state = STATE_PROTO; 235548af606aSJani Nikula $inline_doc_state = STATE_INLINE_NA; 2356a4c6ebedSDanilo Cesar Lemes de Paula # Regular text 2357a4c6ebedSDanilo Cesar Lemes de Paula } elsif (/$doc_content/) { 235848af606aSJani Nikula if ($inline_doc_state == STATE_INLINE_TEXT) { 2359a4c6ebedSDanilo Cesar Lemes de Paula $contents .= $1 . "\n"; 23606450c895SJani Nikula # nuke leading blank lines 23616450c895SJani Nikula if ($contents =~ /^\s*$/) { 23626450c895SJani Nikula $contents = ""; 23636450c895SJani Nikula } 236448af606aSJani Nikula } elsif ($inline_doc_state == STATE_INLINE_NAME) { 236548af606aSJani Nikula $inline_doc_state = STATE_INLINE_ERROR; 2366e7ca311eSDaniel Vetter print STDERR "${file}:$.: warning: "; 2367a4c6ebedSDanilo Cesar Lemes de Paula print STDERR "Incorrect use of kernel-doc format: $_"; 2368a4c6ebedSDanilo Cesar Lemes de Paula ++$warnings; 2369a4c6ebedSDanilo Cesar Lemes de Paula } 2370a4c6ebedSDanilo Cesar Lemes de Paula } 23710c9aa209SJani Nikula} 2372c17add56SJonathan Corbet 2373c17add56SJonathan Corbet 2374c17add56SJonathan Corbetsub process_file($) { 2375c17add56SJonathan Corbet my $file; 2376c17add56SJonathan Corbet my $initial_section_counter = $section_counter; 2377c17add56SJonathan Corbet my ($orig_file) = @_; 2378c17add56SJonathan Corbet 2379c17add56SJonathan Corbet $file = map_filename($orig_file); 2380c17add56SJonathan Corbet 2381dbe8ba00SMauro Carvalho Chehab if (!open(IN_FILE,"<$file")) { 2382c17add56SJonathan Corbet print STDERR "Error: Cannot open file $file\n"; 2383c17add56SJonathan Corbet ++$errors; 2384c17add56SJonathan Corbet return; 23851da177e4SLinus Torvalds } 2386c17add56SJonathan Corbet 2387c17add56SJonathan Corbet $. = 1; 2388c17add56SJonathan Corbet 2389c17add56SJonathan Corbet $section_counter = 0; 2390dbe8ba00SMauro Carvalho Chehab while (<IN_FILE>) { 2391c17add56SJonathan Corbet while (s/\\\s*$//) { 2392dbe8ba00SMauro Carvalho Chehab $_ .= <IN_FILE>; 2393c17add56SJonathan Corbet } 2394c17add56SJonathan Corbet # Replace tabs by spaces 2395c17add56SJonathan Corbet while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; 2396c17add56SJonathan Corbet # Hand this line to the appropriate state handler 2397c17add56SJonathan Corbet if ($state == STATE_NORMAL) { 2398c17add56SJonathan Corbet process_normal(); 2399c17add56SJonathan Corbet } elsif ($state == STATE_NAME) { 2400c17add56SJonathan Corbet process_name($file, $_); 24010d55d48bSMauro Carvalho Chehab } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE || 24020d55d48bSMauro Carvalho Chehab $state == STATE_BODY_WITH_BLANK_LINE) { 2403c17add56SJonathan Corbet process_body($file, $_); 2404c17add56SJonathan Corbet } elsif ($state == STATE_INLINE) { # scanning for inline parameters 2405c17add56SJonathan Corbet process_inline($file, $_); 2406cc794812SJonathan Corbet } elsif ($state == STATE_PROTO) { 2407cc794812SJonathan Corbet process_proto($file, $_); 240848af606aSJani Nikula } elsif ($state == STATE_DOCBLOCK) { 2409c17add56SJonathan Corbet process_docblock($file, $_); 24101da177e4SLinus Torvalds } 24111da177e4SLinus Torvalds } 2412c17add56SJonathan Corbet 2413c17add56SJonathan Corbet # Make sure we got something interesting. 2414b0d60bfbSJonathan Corbet if ($initial_section_counter == $section_counter && $ 2415b0d60bfbSJonathan Corbet output_mode ne "none") { 2416b0d60bfbSJonathan Corbet if ($output_selection == OUTPUT_INCLUDE) { 2417b0d60bfbSJonathan Corbet print STDERR "${file}:1: warning: '$_' not found\n" 2418b0d60bfbSJonathan Corbet for keys %function_table; 24193a025e1dSMatthew Wilcox } 2420b0d60bfbSJonathan Corbet else { 2421b0d60bfbSJonathan Corbet print STDERR "${file}:1: warning: no structured comments found\n"; 2422e946c43aSJohannes Berg } 24231da177e4SLinus Torvalds } 2424dbe8ba00SMauro Carvalho Chehab close IN_FILE; 24251da177e4SLinus Torvalds} 24268484baaaSRandy Dunlap 24278484baaaSRandy Dunlap 242893351d41SMauro Carvalho Chehabif ($output_mode eq "rst") { 242993351d41SMauro Carvalho Chehab get_sphinx_version() if (!$sphinx_major); 243093351d41SMauro Carvalho Chehab} 243193351d41SMauro Carvalho Chehab 24328484baaaSRandy Dunlap$kernelversion = get_kernel_version(); 24338484baaaSRandy Dunlap 24348484baaaSRandy Dunlap# generate a sequence of code that will splice in highlighting information 24358484baaaSRandy Dunlap# using the s// operator. 24361ef06233SMauro Carvalho Chehabfor (my $k = 0; $k < @highlights; $k++) { 24374d732701SDanilo Cesar Lemes de Paula my $pattern = $highlights[$k][0]; 24384d732701SDanilo Cesar Lemes de Paula my $result = $highlights[$k][1]; 24394d732701SDanilo Cesar Lemes de Paula# print STDERR "scanning pattern:$pattern, highlight:($result)\n"; 24404d732701SDanilo Cesar Lemes de Paula $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n"; 24418484baaaSRandy Dunlap} 24428484baaaSRandy Dunlap 24438484baaaSRandy Dunlap# Read the file that maps relative names to absolute names for 24448484baaaSRandy Dunlap# separate source and object directories and for shadow trees. 24458484baaaSRandy Dunlapif (open(SOURCE_MAP, "<.tmp_filelist.txt")) { 24468484baaaSRandy Dunlap my ($relname, $absname); 24478484baaaSRandy Dunlap while(<SOURCE_MAP>) { 24488484baaaSRandy Dunlap chop(); 24498484baaaSRandy Dunlap ($relname, $absname) = (split())[0..1]; 24508484baaaSRandy Dunlap $relname =~ s:^/+::; 24518484baaaSRandy Dunlap $source_map{$relname} = $absname; 24528484baaaSRandy Dunlap } 24538484baaaSRandy Dunlap close(SOURCE_MAP); 24548484baaaSRandy Dunlap} 24558484baaaSRandy Dunlap 245688c2b57dSJani Nikulaif ($output_selection == OUTPUT_EXPORTED || 245788c2b57dSJani Nikula $output_selection == OUTPUT_INTERNAL) { 2458c9b2cfb3SJani Nikula 2459c9b2cfb3SJani Nikula push(@export_file_list, @ARGV); 2460c9b2cfb3SJani Nikula 246188c2b57dSJani Nikula foreach (@export_file_list) { 246288c2b57dSJani Nikula chomp; 246388c2b57dSJani Nikula process_export_file($_); 246488c2b57dSJani Nikula } 246588c2b57dSJani Nikula} 246688c2b57dSJani Nikula 24678484baaaSRandy Dunlapforeach (@ARGV) { 24688484baaaSRandy Dunlap chomp; 24698484baaaSRandy Dunlap process_file($_); 24708484baaaSRandy Dunlap} 24718484baaaSRandy Dunlapif ($verbose && $errors) { 24728484baaaSRandy Dunlap print STDERR "$errors errors\n"; 24738484baaaSRandy Dunlap} 24748484baaaSRandy Dunlapif ($verbose && $warnings) { 24758484baaaSRandy Dunlap print STDERR "$warnings warnings\n"; 24768484baaaSRandy Dunlap} 24778484baaaSRandy Dunlap 24782c12c810SPierre-Louis Bossartif ($Werror && $warnings) { 24792c12c810SPierre-Louis Bossart print STDERR "$warnings warnings as Errors\n"; 24802c12c810SPierre-Louis Bossart exit($warnings); 24812c12c810SPierre-Louis Bossart} else { 24822c12c810SPierre-Louis Bossart exit($output_mode eq "none" ? 0 : $errors) 24832c12c810SPierre-Louis Bossart} 2484