Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398#!/usr/bin/env python3# SPDX-License-Identifier: GPL-2.0# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.## pylint: disable=C0103,R0912,R0914,R0915## NOTE: While kernel-doc requires at least version 3.6 to run, the# command line should work with Python 3.2+ (tested with 3.4).# The rationale is that it shall fail gracefully during Kernel# compilation with older Kernel versions. Due to that:# - encoding line is needed here;# - f-strings cannot be used in this file.# - libraries that require newer versions can only be included# after the Python version has been checked.## Converted from the kernel-doc script originally written in Perl# under GPLv2, copyrighted since 1998 by the following authors:## Aditya Srivastava <yashsri421@gmail.com># Akira Yokosawa <akiyks@gmail.com># Alexander A. Klimov <grandmaster@al2klimov.de># Alexander Lobakin <aleksander.lobakin@intel.com># André Almeida <andrealmeid@igalia.com># Andy Shevchenko <andriy.shevchenko@linux.intel.com># Anna-Maria Behnsen <anna-maria@linutronix.de># Armin Kuster <akuster@mvista.com># Bart Van Assche <bart.vanassche@sandisk.com># Ben Hutchings <ben@decadent.org.uk># Borislav Petkov <bbpetkov@yahoo.de># Chen-Yu Tsai <wenst@chromium.org># Coco Li <lixiaoyan@google.com># Conchúr Navid <conchur@web.de># Daniel Santos <daniel.santos@pobox.com># Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk># Dan Luedtke <mail@danrl.de># Donald Hunter <donald.hunter@gmail.com># Gabriel Krisman Bertazi <krisman@collabora.co.uk># Greg Kroah-Hartman <gregkh@linuxfoundation.org># Harvey Harrison <harvey.harrison@gmail.com># Horia Geanta <horia.geanta@freescale.com># Ilya Dryomov <idryomov@gmail.com># Jakub Kicinski <kuba@kernel.org># Jani Nikula <jani.nikula@intel.com># Jason Baron <jbaron@redhat.com># Jason Gunthorpe <jgg@nvidia.com># Jérémy Bobbio <lunar@debian.org># Johannes Berg <johannes.berg@intel.com># Johannes Weiner <hannes@cmpxchg.org># Jonathan Cameron <Jonathan.Cameron@huawei.com># Jonathan Corbet <corbet@lwn.net># Jonathan Neuschäfer <j.neuschaefer@gmx.net># Kamil Rytarowski <n54@gmx.com># Kees Cook <kees@kernel.org># Laurent Pinchart <laurent.pinchart@ideasonboard.com># Levin, Alexander (Sasha Levin) <alexander.levin@verizon.com># Linus Torvalds <torvalds@linux-foundation.org># Lucas De Marchi <lucas.demarchi@profusion.mobi># Mark Rutland <mark.rutland@arm.com># Markus Heiser <markus.heiser@darmarit.de># Martin Waitz <tali@admingilde.org># Masahiro Yamada <masahiroy@kernel.org># Matthew Wilcox <willy@infradead.org># Mauro Carvalho Chehab <mchehab+huawei@kernel.org># Michal Wajdeczko <michal.wajdeczko@intel.com># Michael Zucchi# Mike Rapoport <rppt@linux.ibm.com># Niklas Söderlund <niklas.soderlund@corigine.com># Nishanth Menon <nm@ti.com># Paolo Bonzini <pbonzini@redhat.com># Pavan Kumar Linga <pavan.kumar.linga@intel.com># Pavel Pisa <pisa@cmp.felk.cvut.cz># Peter Maydell <peter.maydell@linaro.org># Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com># Randy Dunlap <rdunlap@infradead.org># Richard Kennedy <richard@rsk.demon.co.uk># Rich Walker <rw@shadow.org.uk># Rolf Eike Beer <eike-kernel@sf-tec.de># Sakari Ailus <sakari.ailus@linux.intel.com># Silvio Fricke <silvio.fricke@gmail.com># Simon Huggins# Tim Waugh <twaugh@redhat.com># Tomasz Warniełło <tomasz.warniello@gmail.com># Utkarsh Tripathi <utripathi2002@gmail.com># valdis.kletnieks@vt.edu <valdis.kletnieks@vt.edu># Vegard Nossum <vegard.nossum@oracle.com># Will Deacon <will.deacon@arm.com># Yacine Belkadi <yacine.belkadi.1@gmail.com># Yujie Liu <yujie.liu@intel.com>
"""Print formatted kernel documentation to stdout.
Read C language source or header FILEs, extract embeddeddocumentation comments, and print formatted documentationto standard output.
The documentation comments are identified by the ``/**``opening comment mark.
See Documentation/doc-guide/kernel-doc.rst for thedocumentation comment syntax."""
import argparseimport loggingimport osimport sys
# Import Python modules
LIB_DIR = "../lib/python"SRC_DIR = os.path.dirname(os.path.realpath(__file__))
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
WERROR_RETURN_CODE = 3
DESC = """Read C language source or header FILEs, extract embedded documentation comments,and print formatted documentation to standard output.
The documentation comments are identified by the "/**" opening comment mark.
See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax."""
EXPORT_FILE_DESC = """Specify an additional FILE in which to look for EXPORT_SYMBOL information.
May be used multiple times."""
EXPORT_DESC = """Only output documentation for symbols that have beenexported using EXPORT_SYMBOL() and related macros in any inputFILE or -export-file FILE."""
INTERNAL_DESC = """Only output documentation for symbols that have NOT beenexported using EXPORT_SYMBOL() and related macros in any inputFILE or -export-file FILE."""
FUNCTION_DESC = """Only output documentation for the given function or DOC: sectiontitle. All other functions and DOC: sections are ignored.
May be used multiple times."""
NOSYMBOL_DESC = """Exclude the specified symbol from the output documentation.
May be used multiple times."""
FILES_DESC = """Header and C source files to be parsed."""
WARN_CONTENTS_BEFORE_SECTIONS_DESC = """Warn if there are contents before sections (deprecated).
This option is kept just for backward-compatibility, but it does nothing,neither here nor at the original Perl script."""
EPILOG = """The return value is:
- 0: success or Python version is not compatible withkernel-doc. If -Werror is not used, it will alsoreturn 0 if there are issues at kernel-doc markups;
- 1: an abnormal condition happened;
- 2: argparse issued an error;
- 3: When -Werror is used, it means that one or more unfiltered parse warnings happened."""
class MsgFormatter(logging.Formatter): """ Helper class to capitalize errors and warnings, the same way the venerable (now retired) kernel-doc.pl used to do. """
def format(self, record): record.levelname = record.levelname.capitalize() return logging.Formatter.format(self, record)
def main(): """ Main program.
"""
parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, description=DESC, epilog=EPILOG)
# # Normal arguments # parser.add_argument("-v", "-verbose", "--verbose", action="store_true", help="Verbose output, more warnings and other information.")
parser.add_argument("-d", "-debug", "--debug", action="store_true", help="Enable debug messages")
parser.add_argument("-M", "-modulename", "--modulename", help="Allow setting a module name at the output.")
parser.add_argument("-l", "-enable-lineno", "--enable_lineno", action="store_true", help="Enable line number output (only in ReST mode)")
# # Arguments to control the warning behavior # parser.add_argument("-Wreturn", "--wreturn", action="store_true", help="Warns about the lack of a return markup on functions.")
parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", action="store_true", help="Warns if initial short description is missing")
parser.add_argument("-Wcontents-before-sections", "--wcontents-before-sections", action="store_true", help=WARN_CONTENTS_BEFORE_SECTIONS_DESC)
parser.add_argument("-Wall", "--wall", action="store_true", help="Enable all types of warnings")
parser.add_argument("-Werror", "--werror", action="store_true", help="Treat warnings as errors.")
parser.add_argument("-export-file", "--export-file", action='append', help=EXPORT_FILE_DESC)
# # Output format # out_fmt = parser.add_argument_group("Output format selection (mutually exclusive)")
out_fmt.add_argument("-m", "-man", "--man", action="store_true", help="Output troff manual page format.") out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", help="Output reStructuredText format (default).") out_fmt.add_argument("-N", "-none", "--none", action="store_true", help="Do not output documentation, only warnings.")
out_fmt.add_argument("-y", "--yaml-file", "--yaml", help="Stores kernel-doc output on a yaml file.") out_fmt.add_argument("-k", "--kdoc-item", "--kdoc", action="store_true", help="Store KdocItem inside yaml file. Ued together with --yaml.")
# # Output selection mutually-exclusive group # sel_group = parser.add_argument_group("Output selection (mutually exclusive)") sel_mut = sel_group.add_mutually_exclusive_group()
sel_mut.add_argument("-e", "-export", "--export", action='store_true', help=EXPORT_DESC)
sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', help=INTERNAL_DESC)
sel_mut.add_argument("-s", "-function", "--symbol", action='append', help=FUNCTION_DESC)
# # Those are valid for all 3 types of filter # parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', help=NOSYMBOL_DESC)
parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", action='store_true', help="Don't output DOC sections")
parser.add_argument("files", metavar="FILE", nargs="+", help=FILES_DESC)
args = parser.parse_args()
if args.wall: args.wreturn = True args.wshort_desc = True args.wcontents_before_sections = True
logger = logging.getLogger()
if not args.debug: logger.setLevel(logging.INFO) else: logger.setLevel(logging.DEBUG)
formatter = MsgFormatter('%(levelname)s: %(message)s')
handler = logging.StreamHandler() handler.setFormatter(formatter)
logger.addHandler(handler)
python_ver = sys.version_info[:2] if python_ver < (3,6): # # Depending on the Kernel configuration, kernel-doc --none is called at # build time. As we don't want to break compilation due to the # usage of an old Python version, return 0 here. # if args.none: logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") sys.exit(0)
sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.")
if python_ver < (3,7): logger.warning("Python 3.7 or later is required for correct results")
# # Import kernel-doc libraries only after checking the Python version # from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415
yaml_content = set() if args.yaml_file: out_style = None
if args.man: yaml_content |= {"man"}
if args.rst: yaml_content |= {"rst"}
if args.kdoc_item or not yaml_content: yaml_content |= {"KdocItem"}
else: n_outputs = 0
if args.man: out_style = ManFormat(modulename=args.modulename) n_outputs += 1
if args.none: out_style = None n_outputs += 1
if args.rst or n_outputs == 0: n_outputs += 1 out_style = RestFormat()
if n_outputs > 1: parser.error("Those arguments are muttually exclusive: --man, --rst, --none, except when generating a YAML file.")
elif not n_outputs: out_style = RestFormat()
kfiles = KernelFiles(verbose=args.verbose, yaml_file=args.yaml_file, yaml_content=yaml_content, out_style=out_style, werror=args.werror, wreturn=args.wreturn, wshort_desc=args.wshort_desc, wcontents_before_sections=args.wcontents_before_sections)
kfiles.parse(args.files, export_file=args.export_file)
for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, internal=args.internal, symbol=args.symbol, nosymbol=args.nosymbol, export_file=args.export_file, no_doc_sections=args.no_doc_sections): msg = t[1] if msg: print(msg)
error_count = kfiles.errors if not error_count: sys.exit(0)
if args.werror: print("%s warnings as errors" % error_count) # pylint: disable=C0209 sys.exit(WERROR_RETURN_CODE)
if args.verbose: print("%s errors" % error_count) # pylint: disable=C0209
sys.exit(0)
## Call main method#if __name__ == "__main__": main()