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 """ 186 Helper class to capitalize errors and warnings, the same way 187 the venerable (now retired) kernel-doc.pl used to do. 188 """ 189 190 def format(self, record): 191 record.levelname = record.levelname.capitalize() 192 return logging.Formatter.format(self, record) 193 194def main(): 195 """ 196 Main program. 197 198 """ 199 200 parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, 201 description=DESC, epilog=EPILOG) 202 203 # 204 # Normal arguments 205 # 206 parser.add_argument("-v", "-verbose", "--verbose", action="store_true", 207 help="Verbose output, more warnings and other information.") 208 209 parser.add_argument("-d", "-debug", "--debug", action="store_true", 210 help="Enable debug messages") 211 212 parser.add_argument("-M", "-modulename", "--modulename", 213 help="Allow setting a module name at the output.") 214 215 parser.add_argument("-l", "-enable-lineno", "--enable_lineno", 216 action="store_true", 217 help="Enable line number output (only in ReST mode)") 218 219 # 220 # Arguments to control the warning behavior 221 # 222 parser.add_argument("-Wreturn", "--wreturn", action="store_true", 223 help="Warns about the lack of a return markup on functions.") 224 225 parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", 226 action="store_true", 227 help="Warns if initial short description is missing") 228 229 parser.add_argument("-Wcontents-before-sections", 230 "--wcontents-before-sections", action="store_true", 231 help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) 232 233 parser.add_argument("-Wall", "--wall", action="store_true", 234 help="Enable all types of warnings") 235 236 parser.add_argument("-Werror", "--werror", action="store_true", 237 help="Treat warnings as errors.") 238 239 parser.add_argument("-export-file", "--export-file", action='append', 240 help=EXPORT_FILE_DESC) 241 242 # 243 # Output format mutually-exclusive group 244 # 245 out_group = parser.add_argument_group("Output format selection (mutually exclusive)") 246 247 out_fmt = out_group.add_mutually_exclusive_group() 248 249 out_fmt.add_argument("-m", "-man", "--man", action="store_true", 250 help="Output troff manual page format.") 251 out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", 252 help="Output reStructuredText format (default).") 253 out_fmt.add_argument("-N", "-none", "--none", action="store_true", 254 help="Do not output documentation, only warnings.") 255 256 # 257 # Output selection mutually-exclusive group 258 # 259 sel_group = parser.add_argument_group("Output selection (mutually exclusive)") 260 sel_mut = sel_group.add_mutually_exclusive_group() 261 262 sel_mut.add_argument("-e", "-export", "--export", action='store_true', 263 help=EXPORT_DESC) 264 265 sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', 266 help=INTERNAL_DESC) 267 268 sel_mut.add_argument("-s", "-function", "--symbol", action='append', 269 help=FUNCTION_DESC) 270 271 # 272 # Those are valid for all 3 types of filter 273 # 274 parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', 275 help=NOSYMBOL_DESC) 276 277 parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", 278 action='store_true', help="Don't output DOC sections") 279 280 parser.add_argument("files", metavar="FILE", 281 nargs="+", help=FILES_DESC) 282 283 args = parser.parse_args() 284 285 if args.wall: 286 args.wreturn = True 287 args.wshort_desc = True 288 args.wcontents_before_sections = True 289 290 logger = logging.getLogger() 291 292 if not args.debug: 293 logger.setLevel(logging.INFO) 294 else: 295 logger.setLevel(logging.DEBUG) 296 297 formatter = MsgFormatter('%(levelname)s: %(message)s') 298 299 handler = logging.StreamHandler() 300 handler.setFormatter(formatter) 301 302 logger.addHandler(handler) 303 304 python_ver = sys.version_info[:2] 305 if python_ver < (3,6): 306 # 307 # Depending on the Kernel configuration, kernel-doc --none is called at 308 # build time. As we don't want to break compilation due to the 309 # usage of an old Python version, return 0 here. 310 # 311 if args.none: 312 logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") 313 sys.exit(0) 314 315 sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") 316 317 if python_ver < (3,7): 318 logger.warning("Python 3.7 or later is required for correct results") 319 320 # 321 # Import kernel-doc libraries only after checking the Python version 322 # 323 from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 324 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 325 326 if args.man: 327 out_style = ManFormat(modulename=args.modulename) 328 elif args.none: 329 out_style = None 330 else: 331 out_style = RestFormat() 332 333 kfiles = KernelFiles(verbose=args.verbose, 334 out_style=out_style, werror=args.werror, 335 wreturn=args.wreturn, wshort_desc=args.wshort_desc, 336 wcontents_before_sections=args.wcontents_before_sections) 337 338 kfiles.parse(args.files, export_file=args.export_file) 339 340 for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, 341 internal=args.internal, symbol=args.symbol, 342 nosymbol=args.nosymbol, export_file=args.export_file, 343 no_doc_sections=args.no_doc_sections): 344 msg = t[1] 345 if msg: 346 print(msg) 347 348 error_count = kfiles.errors 349 if not error_count: 350 sys.exit(0) 351 352 if args.werror: 353 print("%s warnings as errors" % error_count) # pylint: disable=C0209 354 sys.exit(WERROR_RETURN_CODE) 355 356 if args.verbose: 357 print("%s errors" % error_count) # pylint: disable=C0209 358 359 sys.exit(0) 360 361# 362# Call main method 363# 364if __name__ == "__main__": 365 main() 366