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