1#!/usr/bin/env python3 2# SPDX-License-Identifier: GPL-2.0 3# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>. 4# 5# pylint: disable=C0103,R0912,R0914,R0915 6 7# NOTE: While kernel-doc requires at least version 3.6 to run, the 8# command line should work with Python 3.2+ (tested with 3.4). 9# The rationale is that it shall fail gracefully during Kernel 10# compilation with older Kernel versions. Due to that: 11# - encoding line is needed here; 12# - no f-strings can be used on this file. 13# - the libraries that require newer versions can only be included 14# after Python version is checked. 15 16# Converted from the kernel-doc script originally written in Perl 17# under GPLv2, copyrighted since 1998 by the following authors: 18# 19# Aditya Srivastava <yashsri421@gmail.com> 20# Akira Yokosawa <akiyks@gmail.com> 21# Alexander A. Klimov <grandmaster@al2klimov.de> 22# Alexander Lobakin <aleksander.lobakin@intel.com> 23# André Almeida <andrealmeid@igalia.com> 24# Andy Shevchenko <andriy.shevchenko@linux.intel.com> 25# Anna-Maria Behnsen <anna-maria@linutronix.de> 26# Armin Kuster <akuster@mvista.com> 27# Bart Van Assche <bart.vanassche@sandisk.com> 28# Ben Hutchings <ben@decadent.org.uk> 29# Borislav Petkov <bbpetkov@yahoo.de> 30# Chen-Yu Tsai <wenst@chromium.org> 31# Coco Li <lixiaoyan@google.com> 32# Conchúr Navid <conchur@web.de> 33# Daniel Santos <daniel.santos@pobox.com> 34# Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> 35# Dan Luedtke <mail@danrl.de> 36# Donald Hunter <donald.hunter@gmail.com> 37# Gabriel Krisman Bertazi <krisman@collabora.co.uk> 38# Greg Kroah-Hartman <gregkh@linuxfoundation.org> 39# Harvey Harrison <harvey.harrison@gmail.com> 40# Horia Geanta <horia.geanta@freescale.com> 41# Ilya Dryomov <idryomov@gmail.com> 42# Jakub Kicinski <kuba@kernel.org> 43# Jani Nikula <jani.nikula@intel.com> 44# Jason Baron <jbaron@redhat.com> 45# Jason Gunthorpe <jgg@nvidia.com> 46# Jérémy Bobbio <lunar@debian.org> 47# Johannes Berg <johannes.berg@intel.com> 48# Johannes Weiner <hannes@cmpxchg.org> 49# Jonathan Cameron <Jonathan.Cameron@huawei.com> 50# Jonathan Corbet <corbet@lwn.net> 51# Jonathan Neuschäfer <j.neuschaefer@gmx.net> 52# Kamil Rytarowski <n54@gmx.com> 53# Kees Cook <kees@kernel.org> 54# Laurent Pinchart <laurent.pinchart@ideasonboard.com> 55# Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com> 56# Linus Torvalds <torvalds@linux-foundation.org> 57# Lucas De Marchi <lucas.demarchi@profusion.mobi> 58# Mark Rutland <mark.rutland@arm.com> 59# Markus Heiser <markus.heiser@darmarit.de> 60# Martin Waitz <tali@admingilde.org> 61# Masahiro Yamada <masahiroy@kernel.org> 62# Matthew Wilcox <willy@infradead.org> 63# Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 64# Michal Wajdeczko <michal.wajdeczko@intel.com> 65# Michael Zucchi 66# Mike Rapoport <rppt@linux.ibm.com> 67# Niklas Söderlund <niklas.soderlund@corigine.com> 68# Nishanth Menon <nm@ti.com> 69# Paolo Bonzini <pbonzini@redhat.com> 70# Pavan Kumar Linga <pavan.kumar.linga@intel.com> 71# Pavel Pisa <pisa@cmp.felk.cvut.cz> 72# Peter Maydell <peter.maydell@linaro.org> 73# Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com> 74# Randy Dunlap <rdunlap@infradead.org> 75# Richard Kennedy <richard@rsk.demon.co.uk> 76# Rich Walker <rw@shadow.org.uk> 77# Rolf Eike Beer <eike-kernel@sf-tec.de> 78# Sakari Ailus <sakari.ailus@linux.intel.com> 79# Silvio Fricke <silvio.fricke@gmail.com> 80# Simon Huggins 81# Tim Waugh <twaugh@redhat.com> 82# Tomasz Warniełło <tomasz.warniello@gmail.com> 83# Utkarsh Tripathi <utripathi2002@gmail.com> 84# valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu> 85# Vegard Nossum <vegard.nossum@oracle.com> 86# Will Deacon <will.deacon@arm.com> 87# Yacine Belkadi <yacine.belkadi.1@gmail.com> 88# Yujie Liu <yujie.liu@intel.com> 89 90""" 91kernel_doc 92========== 93 94Print formatted kernel documentation to stdout 95 96Read C language source or header FILEs, extract embedded 97documentation comments, and print formatted documentation 98to standard output. 99 100The documentation comments are identified by the "/**" 101opening comment mark. 102 103See Documentation/doc-guide/kernel-doc.rst for the 104documentation comment syntax. 105""" 106 107import argparse 108import logging 109import os 110import sys 111 112# Import Python modules 113 114LIB_DIR = "lib/kdoc" 115SRC_DIR = os.path.dirname(os.path.realpath(__file__)) 116 117sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) 118 119DESC = """ 120Read C language source or header FILEs, extract embedded documentation comments, 121and print formatted documentation to standard output. 122 123The documentation comments are identified by the "/**" opening comment mark. 124 125See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. 126""" 127 128EXPORT_FILE_DESC = """ 129Specify an additional FILE in which to look for EXPORT_SYMBOL information. 130 131May be used multiple times. 132""" 133 134EXPORT_DESC = """ 135Only output documentation for the symbols that have been 136exported using EXPORT_SYMBOL() and related macros in any input 137FILE or -export-file FILE. 138""" 139 140INTERNAL_DESC = """ 141Only output documentation for the symbols that have NOT been 142exported using EXPORT_SYMBOL() and related macros in any input 143FILE or -export-file FILE. 144""" 145 146FUNCTION_DESC = """ 147Only output documentation for the given function or DOC: section 148title. All other functions and DOC: sections are ignored. 149 150May be used multiple times. 151""" 152 153NOSYMBOL_DESC = """ 154Exclude the specified symbol from the output documentation. 155 156May be used multiple times. 157""" 158 159FILES_DESC = """ 160Header and C source files to be parsed. 161""" 162 163WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ 164Warns if there are contents before sections (deprecated). 165 166This option is kept just for backward-compatibility, but it does nothing, 167neither here nor at the original Perl script. 168""" 169 170 171class MsgFormatter(logging.Formatter): 172 """Helper class to format warnings on a similar way to kernel-doc.pl""" 173 174 def format(self, record): 175 record.levelname = record.levelname.capitalize() 176 return logging.Formatter.format(self, record) 177 178def main(): 179 """Main program""" 180 181 parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, 182 description=DESC) 183 184 # Normal arguments 185 186 parser.add_argument("-v", "-verbose", "--verbose", action="store_true", 187 help="Verbose output, more warnings and other information.") 188 189 parser.add_argument("-d", "-debug", "--debug", action="store_true", 190 help="Enable debug messages") 191 192 parser.add_argument("-M", "-modulename", "--modulename", 193 default="Kernel API", 194 help="Allow setting a module name at the output.") 195 196 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", 197 action="store_true", 198 help="Enable line number output (only in ReST mode)") 199 200 # Arguments to control the warning behavior 201 202 parser.add_argument("-Wreturn", "--wreturn", action="store_true", 203 help="Warns about the lack of a return markup on functions.") 204 205 parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", 206 action="store_true", 207 help="Warns if initial short description is missing") 208 209 parser.add_argument("-Wcontents-before-sections", 210 "--wcontents-before-sections", action="store_true", 211 help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) 212 213 parser.add_argument("-Wall", "--wall", action="store_true", 214 help="Enable all types of warnings") 215 216 parser.add_argument("-Werror", "--werror", action="store_true", 217 help="Treat warnings as errors.") 218 219 parser.add_argument("-export-file", "--export-file", action='append', 220 help=EXPORT_FILE_DESC) 221 222 # Output format mutually-exclusive group 223 224 out_group = parser.add_argument_group("Output format selection (mutually exclusive)") 225 226 out_fmt = out_group.add_mutually_exclusive_group() 227 228 out_fmt.add_argument("-m", "-man", "--man", action="store_true", 229 help="Output troff manual page format.") 230 out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", 231 help="Output reStructuredText format (default).") 232 out_fmt.add_argument("-N", "-none", "--none", action="store_true", 233 help="Do not output documentation, only warnings.") 234 235 # Output selection mutually-exclusive group 236 237 sel_group = parser.add_argument_group("Output selection (mutually exclusive)") 238 sel_mut = sel_group.add_mutually_exclusive_group() 239 240 sel_mut.add_argument("-e", "-export", "--export", action='store_true', 241 help=EXPORT_DESC) 242 243 sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', 244 help=INTERNAL_DESC) 245 246 sel_mut.add_argument("-s", "-function", "--symbol", action='append', 247 help=FUNCTION_DESC) 248 249 # Those are valid for all 3 types of filter 250 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', 251 help=NOSYMBOL_DESC) 252 253 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", 254 action='store_true', help="Don't outputt DOC sections") 255 256 parser.add_argument("files", metavar="FILE", 257 nargs="+", help=FILES_DESC) 258 259 args = parser.parse_args() 260 261 if args.wall: 262 args.wreturn = True 263 args.wshort_desc = True 264 args.wcontents_before_sections = True 265 266 logger = logging.getLogger() 267 268 if not args.debug: 269 logger.setLevel(logging.INFO) 270 else: 271 logger.setLevel(logging.DEBUG) 272 273 formatter = MsgFormatter('%(levelname)s: %(message)s') 274 275 handler = logging.StreamHandler() 276 handler.setFormatter(formatter) 277 278 logger.addHandler(handler) 279 280 python_ver = sys.version_info[:2] 281 if python_ver < (3,6): 282 # Depending on Kernel configuration, kernel-doc --none is called at 283 # build time. As we don't want to break compilation due to the 284 # usage of an old Python version, return 0 here. 285 if args.none: 286 logger.error("Python 3.6 or later is required by kernel-doc. skipping checks") 287 sys.exit(0) 288 289 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") 290 291 if python_ver < (3,7): 292 logger.warning("Python 3.7 or later is required for correct results") 293 294 # Import kernel-doc libraries only after checking Python version 295 from kdoc_files import KernelFiles # pylint: disable=C0415 296 from kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 297 298 if args.man: 299 out_style = ManFormat(modulename=args.modulename) 300 elif args.none: 301 out_style = None 302 else: 303 out_style = RestFormat() 304 305 kfiles = KernelFiles(verbose=args.verbose, 306 out_style=out_style, werror=args.werror, 307 wreturn=args.wreturn, wshort_desc=args.wshort_desc, 308 wcontents_before_sections=args.wcontents_before_sections) 309 310 kfiles.parse(args.files, export_file=args.export_file) 311 312 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 313 internal=args.internal, symbol=args.symbol, 314 nosymbol=args.nosymbol, export_file=args.export_file, 315 no_doc_sections=args.no_doc_sections): 316 msg = t[1] 317 if msg: 318 print(msg) 319 320 error_count = kfiles.errors 321 if not error_count: 322 sys.exit(0) 323 324 if args.werror: 325 print("%s warnings as errors" % error_count) # pylint: disable=C0209 326 sys.exit(error_count) 327 328 if args.verbose: 329 print("%s errors" % error_count) # pylint: disable=C0209 330 331 if args.none: 332 sys.exit(0) 333 334 sys.exit(error_count) 335 336 337# Call main method 338if __name__ == "__main__": 339 main() 340