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