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# - f-strings cannot be used in this file. 13# - libraries that require newer versions can only be included 14# after the Python version has been 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""" 91Print formatted kernel documentation to stdout. 92 93Read C language source or header FILEs, extract embedded 94documentation comments, and print formatted documentation 95to standard output. 96 97The documentation comments are identified by the ``/**`` 98opening comment mark. 99 100See Documentation/doc-guide/kernel-doc.rst for the 101documentation comment syntax. 102""" 103 104import argparse 105import logging 106import os 107import sys 108 109# Import Python modules 110 111LIB_DIR = "../lib/python" 112SRC_DIR = os.path.dirname(os.path.realpath(__file__)) 113 114sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) 115 116WERROR_RETURN_CODE = 3 117 118DESC = """ 119Read C language source or header FILEs, extract embedded documentation comments, 120and print formatted documentation to standard output. 121 122The documentation comments are identified by the "/**" opening comment mark. 123 124See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. 125""" 126 127EXPORT_FILE_DESC = """ 128Specify an additional FILE in which to look for EXPORT_SYMBOL information. 129 130May be used multiple times. 131""" 132 133EXPORT_DESC = """ 134Only output documentation for symbols that have been 135exported using EXPORT_SYMBOL() and related macros in any input 136FILE or -export-file FILE. 137""" 138 139INTERNAL_DESC = """ 140Only output documentation for symbols that have NOT been 141exported using EXPORT_SYMBOL() and related macros in any input 142FILE or -export-file FILE. 143""" 144 145FUNCTION_DESC = """ 146Only output documentation for the given function or DOC: section 147title. All other functions and DOC: sections are ignored. 148 149May be used multiple times. 150""" 151 152NOSYMBOL_DESC = """ 153Exclude the specified symbol from the output documentation. 154 155May be used multiple times. 156""" 157 158FILES_DESC = """ 159Header and C source files to be parsed. 160""" 161 162WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ 163Warn if there are contents before sections (deprecated). 164 165This option is kept just for backward-compatibility, but it does nothing, 166neither here nor at the original Perl script. 167""" 168 169EPILOG = """ 170The return value is: 171 172- 0: success or Python version is not compatible with 173kernel-doc. If -Werror is not used, it will also 174return 0 if there are issues at kernel-doc markups; 175 176- 1: an abnormal condition happened; 177 178- 2: argparse issued an error; 179 180- 3: When -Werror is used, it means that one or more unfiltered parse 181 warnings happened. 182""" 183 184class MsgFormatter(logging.Formatter): 185 """Helper class to format warnings in a similar way to kernel-doc.pl.""" 186 187 def format(self, record): 188 record.levelname = record.levelname.capitalize() 189 return logging.Formatter.format(self, record) 190 191def main(): 192 """ 193 Main program. 194 195 """ 196 197 parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, 198 description=DESC, epilog=EPILOG) 199 200 # 201 # Normal arguments 202 # 203 parser.add_argument("-v", "-verbose", "--verbose", action="store_true", 204 help="Verbose output, more warnings and other information.") 205 206 parser.add_argument("-d", "-debug", "--debug", action="store_true", 207 help="Enable debug messages") 208 209 parser.add_argument("-M", "-modulename", "--modulename", 210 default="Kernel API", 211 help="Allow setting a module name at the output.") 212 213 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", 214 action="store_true", 215 help="Enable line number output (only in ReST mode)") 216 217 # 218 # Arguments to control the warning behavior 219 # 220 parser.add_argument("-Wreturn", "--wreturn", action="store_true", 221 help="Warns about the lack of a return markup on functions.") 222 223 parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", 224 action="store_true", 225 help="Warns if initial short description is missing") 226 227 parser.add_argument("-Wcontents-before-sections", 228 "--wcontents-before-sections", action="store_true", 229 help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) 230 231 parser.add_argument("-Wall", "--wall", action="store_true", 232 help="Enable all types of warnings") 233 234 parser.add_argument("-Werror", "--werror", action="store_true", 235 help="Treat warnings as errors.") 236 237 parser.add_argument("-export-file", "--export-file", action='append', 238 help=EXPORT_FILE_DESC) 239 240 # 241 # Output format mutually-exclusive group 242 # 243 out_group = parser.add_argument_group("Output format selection (mutually exclusive)") 244 245 out_fmt = out_group.add_mutually_exclusive_group() 246 247 out_fmt.add_argument("-m", "-man", "--man", action="store_true", 248 help="Output troff manual page format.") 249 out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", 250 help="Output reStructuredText format (default).") 251 out_fmt.add_argument("-N", "-none", "--none", action="store_true", 252 help="Do not output documentation, only warnings.") 253 254 # 255 # Output selection mutually-exclusive group 256 # 257 sel_group = parser.add_argument_group("Output selection (mutually exclusive)") 258 sel_mut = sel_group.add_mutually_exclusive_group() 259 260 sel_mut.add_argument("-e", "-export", "--export", action='store_true', 261 help=EXPORT_DESC) 262 263 sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', 264 help=INTERNAL_DESC) 265 266 sel_mut.add_argument("-s", "-function", "--symbol", action='append', 267 help=FUNCTION_DESC) 268 269 # 270 # Those are valid for all 3 types of filter 271 # 272 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', 273 help=NOSYMBOL_DESC) 274 275 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", 276 action='store_true', help="Don't output DOC sections") 277 278 parser.add_argument("files", metavar="FILE", 279 nargs="+", help=FILES_DESC) 280 281 args = parser.parse_args() 282 283 if args.wall: 284 args.wreturn = True 285 args.wshort_desc = True 286 args.wcontents_before_sections = True 287 288 logger = logging.getLogger() 289 290 if not args.debug: 291 logger.setLevel(logging.INFO) 292 else: 293 logger.setLevel(logging.DEBUG) 294 295 formatter = MsgFormatter('%(levelname)s: %(message)s') 296 297 handler = logging.StreamHandler() 298 handler.setFormatter(formatter) 299 300 logger.addHandler(handler) 301 302 python_ver = sys.version_info[:2] 303 if python_ver < (3,6): 304 # 305 # Depending on the Kernel configuration, kernel-doc --none is called at 306 # build time. As we don't want to break compilation due to the 307 # usage of an old Python version, return 0 here. 308 # 309 if args.none: 310 logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") 311 sys.exit(0) 312 313 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") 314 315 if python_ver < (3,7): 316 logger.warning("Python 3.7 or later is required for correct results") 317 318 # 319 # Import kernel-doc libraries only after checking the Python version 320 # 321 from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 322 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 323 324 if args.man: 325 out_style = ManFormat(modulename=args.modulename) 326 elif args.none: 327 out_style = None 328 else: 329 out_style = RestFormat() 330 331 kfiles = KernelFiles(verbose=args.verbose, 332 out_style=out_style, werror=args.werror, 333 wreturn=args.wreturn, wshort_desc=args.wshort_desc, 334 wcontents_before_sections=args.wcontents_before_sections) 335 336 kfiles.parse(args.files, export_file=args.export_file) 337 338 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 339 internal=args.internal, symbol=args.symbol, 340 nosymbol=args.nosymbol, export_file=args.export_file, 341 no_doc_sections=args.no_doc_sections): 342 msg = t[1] 343 if msg: 344 print(msg) 345 346 error_count = kfiles.errors 347 if not error_count: 348 sys.exit(0) 349 350 if args.werror: 351 print("%s warnings as errors" % error_count) # pylint: disable=C0209 352 sys.exit(WERROR_RETURN_CODE) 353 354 if args.verbose: 355 print("%s errors" % error_count) # pylint: disable=C0209 356 357 sys.exit(0) 358 359# 360# Call main method 361# 362if __name__ == "__main__": 363 main() 364