mirror of
git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-09-04 20:19:47 +08:00
e3b42e94cf
The KernelDoc class is too complex. Start optimizing it by placing the kernel-doc parser entry to a separate class. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <28b456f726a022011f0ce5810dbcc26827c1403a.1745564565.git.mchehab+huawei@kernel.org>
1746 lines
64 KiB
Python
1746 lines
64 KiB
Python
#!/usr/bin/env python3
|
|
# SPDX-License-Identifier: GPL-2.0
|
|
# Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>.
|
|
#
|
|
# pylint: disable=C0301,C0302,R0904,R0912,R0913,R0914,R0915,R0917,R1702
|
|
|
|
"""
|
|
kdoc_parser
|
|
===========
|
|
|
|
Read a C language source or header FILE and extract embedded
|
|
documentation comments
|
|
"""
|
|
|
|
import re
|
|
from pprint import pformat
|
|
|
|
from kdoc_re import NestedMatch, KernRe
|
|
|
|
|
|
#
|
|
# Regular expressions used to parse kernel-doc markups at KernelDoc class.
|
|
#
|
|
# Let's declare them in lowercase outside any class to make easier to
|
|
# convert from the python script.
|
|
#
|
|
# As those are evaluated at the beginning, no need to cache them
|
|
#
|
|
|
|
# Allow whitespace at end of comment start.
|
|
doc_start = KernRe(r'^/\*\*\s*$', cache=False)
|
|
|
|
doc_end = KernRe(r'\*/', cache=False)
|
|
doc_com = KernRe(r'\s*\*\s*', cache=False)
|
|
doc_com_body = KernRe(r'\s*\* ?', cache=False)
|
|
doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
|
|
|
|
# @params and a strictly limited set of supported section names
|
|
# Specifically:
|
|
# Match @word:
|
|
# @...:
|
|
# @{section-name}:
|
|
# while trying to not match literal block starts like "example::"
|
|
#
|
|
doc_sect = doc_com + \
|
|
KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$',
|
|
flags=re.I, cache=False)
|
|
|
|
doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
|
|
doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
|
|
doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False)
|
|
doc_inline_sect = KernRe(r'\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)', cache=False)
|
|
doc_inline_end = KernRe(r'^\s*\*/\s*$', cache=False)
|
|
doc_inline_oneline = KernRe(r'^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$', cache=False)
|
|
attribute = KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)",
|
|
flags=re.I | re.S, cache=False)
|
|
|
|
export_symbol = KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*', cache=False)
|
|
export_symbol_ns = KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*', cache=False)
|
|
|
|
type_param = KernRe(r"\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
|
|
|
|
class state:
|
|
"""
|
|
State machine enums
|
|
"""
|
|
|
|
# Parser states
|
|
NORMAL = 0 # normal code
|
|
NAME = 1 # looking for function name
|
|
BODY_MAYBE = 2 # body - or maybe more description
|
|
BODY = 3 # the body of the comment
|
|
BODY_WITH_BLANK_LINE = 4 # the body which has a blank line
|
|
PROTO = 5 # scanning prototype
|
|
DOCBLOCK = 6 # documentation block
|
|
INLINE = 7 # gathering doc outside main block
|
|
|
|
name = [
|
|
"NORMAL",
|
|
"NAME",
|
|
"BODY_MAYBE",
|
|
"BODY",
|
|
"BODY_WITH_BLANK_LINE",
|
|
"PROTO",
|
|
"DOCBLOCK",
|
|
"INLINE",
|
|
]
|
|
|
|
# Inline documentation state
|
|
INLINE_NA = 0 # not applicable ($state != INLINE)
|
|
INLINE_NAME = 1 # looking for member name (@foo:)
|
|
INLINE_TEXT = 2 # looking for member documentation
|
|
INLINE_END = 3 # done
|
|
INLINE_ERROR = 4 # error - Comment without header was found.
|
|
# Spit a warning as it's not
|
|
# proper kernel-doc and ignore the rest.
|
|
|
|
inline_name = [
|
|
"",
|
|
"_NAME",
|
|
"_TEXT",
|
|
"_END",
|
|
"_ERROR",
|
|
]
|
|
|
|
SECTION_DEFAULT = "Description" # default section
|
|
|
|
class KernelEntry:
|
|
|
|
def __init__(self, config, ln):
|
|
self.config = config
|
|
|
|
self.contents = ""
|
|
self.function = ""
|
|
self.sectcheck = ""
|
|
self.struct_actual = ""
|
|
self.prototype = ""
|
|
|
|
self.warnings = []
|
|
|
|
self.parameterlist = []
|
|
self.parameterdescs = {}
|
|
self.parametertypes = {}
|
|
self.parameterdesc_start_lines = {}
|
|
|
|
self.section_start_lines = {}
|
|
self.sectionlist = []
|
|
self.sections = {}
|
|
|
|
self.anon_struct_union = False
|
|
|
|
self.leading_space = None
|
|
|
|
# State flags
|
|
self.brcount = 0
|
|
|
|
self.in_doc_sect = False
|
|
self.declaration_start_line = ln + 1
|
|
|
|
# TODO: rename to emit_message after removal of kernel-doc.pl
|
|
def emit_msg(self, log_msg, warning=True):
|
|
"""Emit a message"""
|
|
|
|
if not warning:
|
|
self.config.log.info(log_msg)
|
|
return
|
|
|
|
# Delegate warning output to output logic, as this way it
|
|
# will report warnings/info only for symbols that are output
|
|
|
|
self.warnings.append(log_msg)
|
|
return
|
|
|
|
def dump_section(self, start_new=True):
|
|
"""
|
|
Dumps section contents to arrays/hashes intended for that purpose.
|
|
"""
|
|
|
|
name = self.section
|
|
contents = self.contents
|
|
|
|
if type_param.match(name):
|
|
name = type_param.group(1)
|
|
|
|
self.parameterdescs[name] = contents
|
|
self.parameterdesc_start_lines[name] = self.new_start_line
|
|
|
|
self.sectcheck += name + " "
|
|
self.new_start_line = 0
|
|
|
|
elif name == "@...":
|
|
name = "..."
|
|
self.parameterdescs[name] = contents
|
|
self.sectcheck += name + " "
|
|
self.parameterdesc_start_lines[name] = self.new_start_line
|
|
self.new_start_line = 0
|
|
|
|
else:
|
|
if name in self.sections and self.sections[name] != "":
|
|
# Only warn on user-specified duplicate section names
|
|
if name != SECTION_DEFAULT:
|
|
self.emit_msg(self.new_start_line,
|
|
f"duplicate section name '{name}'\n")
|
|
self.sections[name] += contents
|
|
else:
|
|
self.sections[name] = contents
|
|
self.sectionlist.append(name)
|
|
self.section_start_lines[name] = self.new_start_line
|
|
self.new_start_line = 0
|
|
|
|
# self.config.log.debug("Section: %s : %s", name, pformat(vars(self)))
|
|
|
|
if start_new:
|
|
self.section = SECTION_DEFAULT
|
|
self.contents = ""
|
|
|
|
|
|
class KernelDoc:
|
|
"""
|
|
Read a C language source or header FILE and extract embedded
|
|
documentation comments.
|
|
"""
|
|
|
|
# Section names
|
|
|
|
section_intro = "Introduction"
|
|
section_context = "Context"
|
|
section_return = "Return"
|
|
|
|
undescribed = "-- undescribed --"
|
|
|
|
def __init__(self, config, fname):
|
|
"""Initialize internal variables"""
|
|
|
|
self.fname = fname
|
|
self.config = config
|
|
|
|
# Initial state for the state machines
|
|
self.state = state.NORMAL
|
|
self.inline_doc_state = state.INLINE_NA
|
|
|
|
# Store entry currently being processed
|
|
self.entry = None
|
|
|
|
# Place all potential outputs into an array
|
|
self.entries = []
|
|
|
|
def emit_msg(self, ln, msg, warning=True):
|
|
"""Emit a message"""
|
|
|
|
log_msg = f"{self.fname}:{ln} {msg}"
|
|
|
|
if self.entry:
|
|
self.entry.emit_msg(log_msg, warning)
|
|
return
|
|
|
|
if warning:
|
|
self.config.log.warning(log_msg)
|
|
else:
|
|
self.config.log.info(log_msg)
|
|
|
|
def dump_section(self, start_new=True):
|
|
"""
|
|
Dumps section contents to arrays/hashes intended for that purpose.
|
|
"""
|
|
|
|
if self.entry:
|
|
self.entry.dump_section(start_new)
|
|
|
|
# TODO: rename it to store_declaration after removal of kernel-doc.pl
|
|
def output_declaration(self, dtype, name, **args):
|
|
"""
|
|
Stores the entry into an entry array.
|
|
|
|
The actual output and output filters will be handled elsewhere
|
|
"""
|
|
|
|
# The implementation here is different than the original kernel-doc:
|
|
# instead of checking for output filters or actually output anything,
|
|
# it just stores the declaration content at self.entries, as the
|
|
# output will happen on a separate class.
|
|
#
|
|
# For now, we're keeping the same name of the function just to make
|
|
# easier to compare the source code of both scripts
|
|
|
|
args["declaration_start_line"] = self.entry.declaration_start_line
|
|
args["type"] = dtype
|
|
args["warnings"] = self.entry.warnings
|
|
|
|
# TODO: use colletions.OrderedDict to remove sectionlist
|
|
|
|
sections = args.get('sections', {})
|
|
sectionlist = args.get('sectionlist', [])
|
|
|
|
# Drop empty sections
|
|
# TODO: improve empty sections logic to emit warnings
|
|
for section in ["Description", "Return"]:
|
|
if section in sectionlist:
|
|
if not sections[section].rstrip():
|
|
del sections[section]
|
|
sectionlist.remove(section)
|
|
|
|
self.entries.append((name, args))
|
|
|
|
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
|
|
|
|
def reset_state(self, ln):
|
|
"""
|
|
Ancillary routine to create a new entry. It initializes all
|
|
variables used by the state machine.
|
|
"""
|
|
|
|
self.entry = KernelEntry(self.config, ln)
|
|
|
|
# State flags
|
|
self.state = state.NORMAL
|
|
self.inline_doc_state = state.INLINE_NA
|
|
|
|
def push_parameter(self, ln, decl_type, param, dtype,
|
|
org_arg, declaration_name):
|
|
"""
|
|
Store parameters and their descriptions at self.entry.
|
|
"""
|
|
|
|
if self.entry.anon_struct_union and dtype == "" and param == "}":
|
|
return # Ignore the ending }; from anonymous struct/union
|
|
|
|
self.entry.anon_struct_union = False
|
|
|
|
param = KernRe(r'[\[\)].*').sub('', param, count=1)
|
|
|
|
if dtype == "" and param.endswith("..."):
|
|
if KernRe(r'\w\.\.\.$').search(param):
|
|
# For named variable parameters of the form `x...`,
|
|
# remove the dots
|
|
param = param[:-3]
|
|
else:
|
|
# Handles unnamed variable parameters
|
|
param = "..."
|
|
|
|
if param not in self.entry.parameterdescs or \
|
|
not self.entry.parameterdescs[param]:
|
|
|
|
self.entry.parameterdescs[param] = "variable arguments"
|
|
|
|
elif dtype == "" and (not param or param == "void"):
|
|
param = "void"
|
|
self.entry.parameterdescs[param] = "no arguments"
|
|
|
|
elif dtype == "" and param in ["struct", "union"]:
|
|
# Handle unnamed (anonymous) union or struct
|
|
dtype = param
|
|
param = "{unnamed_" + param + "}"
|
|
self.entry.parameterdescs[param] = "anonymous\n"
|
|
self.entry.anon_struct_union = True
|
|
|
|
# Handle cache group enforcing variables: they do not need
|
|
# to be described in header files
|
|
elif "__cacheline_group" in param:
|
|
# Ignore __cacheline_group_begin and __cacheline_group_end
|
|
return
|
|
|
|
# Warn if parameter has no description
|
|
# (but ignore ones starting with # as these are not parameters
|
|
# but inline preprocessor statements)
|
|
if param not in self.entry.parameterdescs and not param.startswith("#"):
|
|
self.entry.parameterdescs[param] = self.undescribed
|
|
|
|
if "." not in param:
|
|
if decl_type == 'function':
|
|
dname = f"{decl_type} parameter"
|
|
else:
|
|
dname = f"{decl_type} member"
|
|
|
|
self.emit_msg(ln,
|
|
f"{dname} '{param}' not described in '{declaration_name}'")
|
|
|
|
# Strip spaces from param so that it is one continuous string on
|
|
# parameterlist. This fixes a problem where check_sections()
|
|
# cannot find a parameter like "addr[6 + 2]" because it actually
|
|
# appears as "addr[6", "+", "2]" on the parameter list.
|
|
# However, it's better to maintain the param string unchanged for
|
|
# output, so just weaken the string compare in check_sections()
|
|
# to ignore "[blah" in a parameter string.
|
|
|
|
self.entry.parameterlist.append(param)
|
|
org_arg = KernRe(r'\s\s+').sub(' ', org_arg)
|
|
self.entry.parametertypes[param] = org_arg
|
|
|
|
def save_struct_actual(self, actual):
|
|
"""
|
|
Strip all spaces from the actual param so that it looks like
|
|
one string item.
|
|
"""
|
|
|
|
actual = KernRe(r'\s*').sub("", actual, count=1)
|
|
|
|
self.entry.struct_actual += actual + " "
|
|
|
|
def create_parameter_list(self, ln, decl_type, args,
|
|
splitter, declaration_name):
|
|
"""
|
|
Creates a list of parameters, storing them at self.entry.
|
|
"""
|
|
|
|
# temporarily replace all commas inside function pointer definition
|
|
arg_expr = KernRe(r'(\([^\),]+),')
|
|
while arg_expr.search(args):
|
|
args = arg_expr.sub(r"\1#", args)
|
|
|
|
for arg in args.split(splitter):
|
|
# Strip comments
|
|
arg = KernRe(r'\/\*.*\*\/').sub('', arg)
|
|
|
|
# Ignore argument attributes
|
|
arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
|
|
|
|
# Strip leading/trailing spaces
|
|
arg = arg.strip()
|
|
arg = KernRe(r'\s+').sub(' ', arg, count=1)
|
|
|
|
if arg.startswith('#'):
|
|
# Treat preprocessor directive as a typeless variable just to fill
|
|
# corresponding data structures "correctly". Catch it later in
|
|
# output_* subs.
|
|
|
|
# Treat preprocessor directive as a typeless variable
|
|
self.push_parameter(ln, decl_type, arg, "",
|
|
"", declaration_name)
|
|
|
|
elif KernRe(r'\(.+\)\s*\(').search(arg):
|
|
# Pointer-to-function
|
|
|
|
arg = arg.replace('#', ',')
|
|
|
|
r = KernRe(r'[^\(]+\(\*?\s*([\w\[\]\.]*)\s*\)')
|
|
if r.match(arg):
|
|
param = r.group(1)
|
|
else:
|
|
self.emit_msg(ln, f"Invalid param: {arg}")
|
|
param = arg
|
|
|
|
dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg)
|
|
self.save_struct_actual(param)
|
|
self.push_parameter(ln, decl_type, param, dtype,
|
|
arg, declaration_name)
|
|
|
|
elif KernRe(r'\(.+\)\s*\[').search(arg):
|
|
# Array-of-pointers
|
|
|
|
arg = arg.replace('#', ',')
|
|
r = KernRe(r'[^\(]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*\)')
|
|
if r.match(arg):
|
|
param = r.group(1)
|
|
else:
|
|
self.emit_msg(ln, f"Invalid param: {arg}")
|
|
param = arg
|
|
|
|
dtype = KernRe(r'([^\(]+\(\*?)\s*' + re.escape(param)).sub(r'\1', arg)
|
|
|
|
self.save_struct_actual(param)
|
|
self.push_parameter(ln, decl_type, param, dtype,
|
|
arg, declaration_name)
|
|
|
|
elif arg:
|
|
arg = KernRe(r'\s*:\s*').sub(":", arg)
|
|
arg = KernRe(r'\s*\[').sub('[', arg)
|
|
|
|
args = KernRe(r'\s*,\s*').split(arg)
|
|
if args[0] and '*' in args[0]:
|
|
args[0] = re.sub(r'(\*+)\s*', r' \1', args[0])
|
|
|
|
first_arg = []
|
|
r = KernRe(r'^(.*\s+)(.*?\[.*\].*)$')
|
|
if args[0] and r.match(args[0]):
|
|
args.pop(0)
|
|
first_arg.extend(r.group(1))
|
|
first_arg.append(r.group(2))
|
|
else:
|
|
first_arg = KernRe(r'\s+').split(args.pop(0))
|
|
|
|
args.insert(0, first_arg.pop())
|
|
dtype = ' '.join(first_arg)
|
|
|
|
for param in args:
|
|
if KernRe(r'^(\*+)\s*(.*)').match(param):
|
|
r = KernRe(r'^(\*+)\s*(.*)')
|
|
if not r.match(param):
|
|
self.emit_msg(ln, f"Invalid param: {param}")
|
|
continue
|
|
|
|
param = r.group(1)
|
|
|
|
self.save_struct_actual(r.group(2))
|
|
self.push_parameter(ln, decl_type, r.group(2),
|
|
f"{dtype} {r.group(1)}",
|
|
arg, declaration_name)
|
|
|
|
elif KernRe(r'(.*?):(\w+)').search(param):
|
|
r = KernRe(r'(.*?):(\w+)')
|
|
if not r.match(param):
|
|
self.emit_msg(ln, f"Invalid param: {param}")
|
|
continue
|
|
|
|
if dtype != "": # Skip unnamed bit-fields
|
|
self.save_struct_actual(r.group(1))
|
|
self.push_parameter(ln, decl_type, r.group(1),
|
|
f"{dtype}:{r.group(2)}",
|
|
arg, declaration_name)
|
|
else:
|
|
self.save_struct_actual(param)
|
|
self.push_parameter(ln, decl_type, param, dtype,
|
|
arg, declaration_name)
|
|
|
|
def check_sections(self, ln, decl_name, decl_type, sectcheck, prmscheck):
|
|
"""
|
|
Check for errors inside sections, emitting warnings if not found
|
|
parameters are described.
|
|
"""
|
|
|
|
sects = sectcheck.split()
|
|
prms = prmscheck.split()
|
|
err = False
|
|
|
|
for sx in range(len(sects)): # pylint: disable=C0200
|
|
err = True
|
|
for px in range(len(prms)): # pylint: disable=C0200
|
|
prm_clean = prms[px]
|
|
prm_clean = KernRe(r'\[.*\]').sub('', prm_clean)
|
|
prm_clean = attribute.sub('', prm_clean)
|
|
|
|
# ignore array size in a parameter string;
|
|
# however, the original param string may contain
|
|
# spaces, e.g.: addr[6 + 2]
|
|
# and this appears in @prms as "addr[6" since the
|
|
# parameter list is split at spaces;
|
|
# hence just ignore "[..." for the sections check;
|
|
prm_clean = KernRe(r'\[.*').sub('', prm_clean)
|
|
|
|
if prm_clean == sects[sx]:
|
|
err = False
|
|
break
|
|
|
|
if err:
|
|
if decl_type == 'function':
|
|
dname = f"{decl_type} parameter"
|
|
else:
|
|
dname = f"{decl_type} member"
|
|
|
|
self.emit_msg(ln,
|
|
f"Excess {dname} '{sects[sx]}' description in '{decl_name}'")
|
|
|
|
def check_return_section(self, ln, declaration_name, return_type):
|
|
"""
|
|
If the function doesn't return void, warns about the lack of a
|
|
return description.
|
|
"""
|
|
|
|
if not self.config.wreturn:
|
|
return
|
|
|
|
# Ignore an empty return type (It's a macro)
|
|
# Ignore functions with a "void" return type (but not "void *")
|
|
if not return_type or KernRe(r'void\s*\w*\s*$').search(return_type):
|
|
return
|
|
|
|
if not self.entry.sections.get("Return", None):
|
|
self.emit_msg(ln,
|
|
f"No description found for return value of '{declaration_name}'")
|
|
|
|
def dump_struct(self, ln, proto):
|
|
"""
|
|
Store an entry for an struct or union
|
|
"""
|
|
|
|
type_pattern = r'(struct|union)'
|
|
|
|
qualifiers = [
|
|
"__attribute__",
|
|
"__packed",
|
|
"__aligned",
|
|
"____cacheline_aligned_in_smp",
|
|
"____cacheline_aligned",
|
|
]
|
|
|
|
definition_body = r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) + ")?"
|
|
struct_members = KernRe(type_pattern + r'([^\{\};]+)(\{)([^\{\}]*)(\})([^\{\}\;]*)(\;)')
|
|
|
|
# Extract struct/union definition
|
|
members = None
|
|
declaration_name = None
|
|
decl_type = None
|
|
|
|
r = KernRe(type_pattern + r'\s+(\w+)\s*' + definition_body)
|
|
if r.search(proto):
|
|
decl_type = r.group(1)
|
|
declaration_name = r.group(2)
|
|
members = r.group(3)
|
|
else:
|
|
r = KernRe(r'typedef\s+' + type_pattern + r'\s*' + definition_body + r'\s*(\w+)\s*;')
|
|
|
|
if r.search(proto):
|
|
decl_type = r.group(1)
|
|
declaration_name = r.group(3)
|
|
members = r.group(2)
|
|
|
|
if not members:
|
|
self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!")
|
|
return
|
|
|
|
if self.entry.identifier != declaration_name:
|
|
self.emit_msg(ln,
|
|
f"expecting prototype for {decl_type} {self.entry.identifier}. Prototype was for {decl_type} {declaration_name} instead\n")
|
|
return
|
|
|
|
args_pattern = r'([^,)]+)'
|
|
|
|
sub_prefixes = [
|
|
(KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', re.S | re.I), ''),
|
|
(KernRe(r'\/\*\s*private:.*', re.S | re.I), ''),
|
|
|
|
# Strip comments
|
|
(KernRe(r'\/\*.*?\*\/', re.S), ''),
|
|
|
|
# Strip attributes
|
|
(attribute, ' '),
|
|
(KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '),
|
|
(KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '),
|
|
(KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '),
|
|
(KernRe(r'\s*__packed\s*', re.S), ' '),
|
|
(KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),
|
|
(KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '),
|
|
(KernRe(r'\s*____cacheline_aligned', re.S), ' '),
|
|
|
|
# Unwrap struct_group macros based on this definition:
|
|
# __struct_group(TAG, NAME, ATTRS, MEMBERS...)
|
|
# which has variants like: struct_group(NAME, MEMBERS...)
|
|
# Only MEMBERS arguments require documentation.
|
|
#
|
|
# Parsing them happens on two steps:
|
|
#
|
|
# 1. drop struct group arguments that aren't at MEMBERS,
|
|
# storing them as STRUCT_GROUP(MEMBERS)
|
|
#
|
|
# 2. remove STRUCT_GROUP() ancillary macro.
|
|
#
|
|
# The original logic used to remove STRUCT_GROUP() using an
|
|
# advanced regex:
|
|
#
|
|
# \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;
|
|
#
|
|
# with two patterns that are incompatible with
|
|
# Python re module, as it has:
|
|
#
|
|
# - a recursive pattern: (?1)
|
|
# - an atomic grouping: (?>...)
|
|
#
|
|
# I tried a simpler version: but it didn't work either:
|
|
# \bSTRUCT_GROUP\(([^\)]+)\)[^;]*;
|
|
#
|
|
# As it doesn't properly match the end parenthesis on some cases.
|
|
#
|
|
# So, a better solution was crafted: there's now a NestedMatch
|
|
# class that ensures that delimiters after a search are properly
|
|
# matched. So, the implementation to drop STRUCT_GROUP() will be
|
|
# handled in separate.
|
|
|
|
(KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('),
|
|
(KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP('),
|
|
(KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct \1 \2; STRUCT_GROUP('),
|
|
(KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('),
|
|
|
|
# Replace macros
|
|
#
|
|
# TODO: use NestedMatch for FOO($1, $2, ...) matches
|
|
#
|
|
# it is better to also move those to the NestedMatch logic,
|
|
# to ensure that parenthesis will be properly matched.
|
|
|
|
(KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S), r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'),
|
|
(KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S), r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'),
|
|
(KernRe(r'DECLARE_BITMAP\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'),
|
|
(KernRe(r'DECLARE_HASHTABLE\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'unsigned long \1[1 << ((\2) - 1)]'),
|
|
(KernRe(r'DECLARE_KFIFO\s*\(' + args_pattern + r',\s*' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'),
|
|
(KernRe(r'DECLARE_KFIFO_PTR\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\2 *\1'),
|
|
(KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + args_pattern + r',\s*' + args_pattern + r'\)', re.S), r'\1 \2[]'),
|
|
(KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + args_pattern + r'\)', re.S), r'dma_addr_t \1'),
|
|
(KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + args_pattern + r'\)', re.S), r'__u32 \1'),
|
|
]
|
|
|
|
# Regexes here are guaranteed to have the end limiter matching
|
|
# the start delimiter. Yet, right now, only one replace group
|
|
# is allowed.
|
|
|
|
sub_nested_prefixes = [
|
|
(re.compile(r'\bSTRUCT_GROUP\('), r'\1'),
|
|
]
|
|
|
|
for search, sub in sub_prefixes:
|
|
members = search.sub(sub, members)
|
|
|
|
nested = NestedMatch()
|
|
|
|
for search, sub in sub_nested_prefixes:
|
|
members = nested.sub(search, sub, members)
|
|
|
|
# Keeps the original declaration as-is
|
|
declaration = members
|
|
|
|
# Split nested struct/union elements
|
|
#
|
|
# This loop was simpler at the original kernel-doc perl version, as
|
|
# while ($members =~ m/$struct_members/) { ... }
|
|
# reads 'members' string on each interaction.
|
|
#
|
|
# Python behavior is different: it parses 'members' only once,
|
|
# creating a list of tuples from the first interaction.
|
|
#
|
|
# On other words, this won't get nested structs.
|
|
#
|
|
# So, we need to have an extra loop on Python to override such
|
|
# re limitation.
|
|
|
|
while True:
|
|
tuples = struct_members.findall(members)
|
|
if not tuples:
|
|
break
|
|
|
|
for t in tuples:
|
|
newmember = ""
|
|
maintype = t[0]
|
|
s_ids = t[5]
|
|
content = t[3]
|
|
|
|
oldmember = "".join(t)
|
|
|
|
for s_id in s_ids.split(','):
|
|
s_id = s_id.strip()
|
|
|
|
newmember += f"{maintype} {s_id}; "
|
|
s_id = KernRe(r'[:\[].*').sub('', s_id)
|
|
s_id = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', s_id)
|
|
|
|
for arg in content.split(';'):
|
|
arg = arg.strip()
|
|
|
|
if not arg:
|
|
continue
|
|
|
|
r = KernRe(r'^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)')
|
|
if r.match(arg):
|
|
# Pointer-to-function
|
|
dtype = r.group(1)
|
|
name = r.group(2)
|
|
extra = r.group(3)
|
|
|
|
if not name:
|
|
continue
|
|
|
|
if not s_id:
|
|
# Anonymous struct/union
|
|
newmember += f"{dtype}{name}{extra}; "
|
|
else:
|
|
newmember += f"{dtype}{s_id}.{name}{extra}; "
|
|
|
|
else:
|
|
arg = arg.strip()
|
|
# Handle bitmaps
|
|
arg = KernRe(r':\s*\d+\s*').sub('', arg)
|
|
|
|
# Handle arrays
|
|
arg = KernRe(r'\[.*\]').sub('', arg)
|
|
|
|
# Handle multiple IDs
|
|
arg = KernRe(r'\s*,\s*').sub(',', arg)
|
|
|
|
r = KernRe(r'(.*)\s+([\S+,]+)')
|
|
|
|
if r.search(arg):
|
|
dtype = r.group(1)
|
|
names = r.group(2)
|
|
else:
|
|
newmember += f"{arg}; "
|
|
continue
|
|
|
|
for name in names.split(','):
|
|
name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name).strip()
|
|
|
|
if not name:
|
|
continue
|
|
|
|
if not s_id:
|
|
# Anonymous struct/union
|
|
newmember += f"{dtype} {name}; "
|
|
else:
|
|
newmember += f"{dtype} {s_id}.{name}; "
|
|
|
|
members = members.replace(oldmember, newmember)
|
|
|
|
# Ignore other nested elements, like enums
|
|
members = re.sub(r'(\{[^\{\}]*\})', '', members)
|
|
|
|
self.create_parameter_list(ln, decl_type, members, ';',
|
|
declaration_name)
|
|
self.check_sections(ln, declaration_name, decl_type,
|
|
self.entry.sectcheck, self.entry.struct_actual)
|
|
|
|
# Adjust declaration for better display
|
|
declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration)
|
|
declaration = KernRe(r'\}\s+;').sub('};', declaration)
|
|
|
|
# Better handle inlined enums
|
|
while True:
|
|
r = KernRe(r'(enum\s+\{[^\}]+),([^\n])')
|
|
if not r.search(declaration):
|
|
break
|
|
|
|
declaration = r.sub(r'\1,\n\2', declaration)
|
|
|
|
def_args = declaration.split('\n')
|
|
level = 1
|
|
declaration = ""
|
|
for clause in def_args:
|
|
|
|
clause = clause.strip()
|
|
clause = KernRe(r'\s+').sub(' ', clause, count=1)
|
|
|
|
if not clause:
|
|
continue
|
|
|
|
if '}' in clause and level > 1:
|
|
level -= 1
|
|
|
|
if not KernRe(r'^\s*#').match(clause):
|
|
declaration += "\t" * level
|
|
|
|
declaration += "\t" + clause + "\n"
|
|
if "{" in clause and "}" not in clause:
|
|
level += 1
|
|
|
|
self.output_declaration(decl_type, declaration_name,
|
|
struct=declaration_name,
|
|
definition=declaration,
|
|
parameterlist=self.entry.parameterlist,
|
|
parameterdescs=self.entry.parameterdescs,
|
|
parametertypes=self.entry.parametertypes,
|
|
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose)
|
|
|
|
def dump_enum(self, ln, proto):
|
|
"""
|
|
Stores an enum inside self.entries array.
|
|
"""
|
|
|
|
# Ignore members marked private
|
|
proto = KernRe(r'\/\*\s*private:.*?\/\*\s*public:.*?\*\/', flags=re.S).sub('', proto)
|
|
proto = KernRe(r'\/\*\s*private:.*}', flags=re.S).sub('}', proto)
|
|
|
|
# Strip comments
|
|
proto = KernRe(r'\/\*.*?\*\/', flags=re.S).sub('', proto)
|
|
|
|
# Strip #define macros inside enums
|
|
proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
|
|
|
|
members = None
|
|
declaration_name = None
|
|
|
|
r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
|
|
if r.search(proto):
|
|
declaration_name = r.group(2)
|
|
members = r.group(1).rstrip()
|
|
else:
|
|
r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
|
|
if r.match(proto):
|
|
declaration_name = r.group(1)
|
|
members = r.group(2).rstrip()
|
|
|
|
if not members:
|
|
self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
|
|
return
|
|
|
|
if self.entry.identifier != declaration_name:
|
|
if self.entry.identifier == "":
|
|
self.emit_msg(ln,
|
|
f"{proto}: wrong kernel-doc identifier on prototype")
|
|
else:
|
|
self.emit_msg(ln,
|
|
f"expecting prototype for enum {self.entry.identifier}. Prototype was for enum {declaration_name} instead")
|
|
return
|
|
|
|
if not declaration_name:
|
|
declaration_name = "(anonymous)"
|
|
|
|
member_set = set()
|
|
|
|
members = KernRe(r'\([^;]*?[\)]').sub('', members)
|
|
|
|
for arg in members.split(','):
|
|
if not arg:
|
|
continue
|
|
arg = KernRe(r'^\s*(\w+).*').sub(r'\1', arg)
|
|
self.entry.parameterlist.append(arg)
|
|
if arg not in self.entry.parameterdescs:
|
|
self.entry.parameterdescs[arg] = self.undescribed
|
|
self.emit_msg(ln,
|
|
f"Enum value '{arg}' not described in enum '{declaration_name}'")
|
|
member_set.add(arg)
|
|
|
|
for k in self.entry.parameterdescs:
|
|
if k not in member_set:
|
|
self.emit_msg(ln,
|
|
f"Excess enum value '%{k}' description in '{declaration_name}'")
|
|
|
|
self.output_declaration('enum', declaration_name,
|
|
enum=declaration_name,
|
|
parameterlist=self.entry.parameterlist,
|
|
parameterdescs=self.entry.parameterdescs,
|
|
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose)
|
|
|
|
def dump_declaration(self, ln, prototype):
|
|
"""
|
|
Stores a data declaration inside self.entries array.
|
|
"""
|
|
|
|
if self.entry.decl_type == "enum":
|
|
self.dump_enum(ln, prototype)
|
|
return
|
|
|
|
if self.entry.decl_type == "typedef":
|
|
self.dump_typedef(ln, prototype)
|
|
return
|
|
|
|
if self.entry.decl_type in ["union", "struct"]:
|
|
self.dump_struct(ln, prototype)
|
|
return
|
|
|
|
self.output_declaration(self.entry.decl_type, prototype,
|
|
entry=self.entry)
|
|
|
|
def dump_function(self, ln, prototype):
|
|
"""
|
|
Stores a function of function macro inside self.entries array.
|
|
"""
|
|
|
|
func_macro = False
|
|
return_type = ''
|
|
decl_type = 'function'
|
|
|
|
# Prefixes that would be removed
|
|
sub_prefixes = [
|
|
(r"^static +", "", 0),
|
|
(r"^extern +", "", 0),
|
|
(r"^asmlinkage +", "", 0),
|
|
(r"^inline +", "", 0),
|
|
(r"^__inline__ +", "", 0),
|
|
(r"^__inline +", "", 0),
|
|
(r"^__always_inline +", "", 0),
|
|
(r"^noinline +", "", 0),
|
|
(r"^__FORTIFY_INLINE +", "", 0),
|
|
(r"__init +", "", 0),
|
|
(r"__init_or_module +", "", 0),
|
|
(r"__deprecated +", "", 0),
|
|
(r"__flatten +", "", 0),
|
|
(r"__meminit +", "", 0),
|
|
(r"__must_check +", "", 0),
|
|
(r"__weak +", "", 0),
|
|
(r"__sched +", "", 0),
|
|
(r"_noprof", "", 0),
|
|
(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +", "", 0),
|
|
(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +", "", 0),
|
|
(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +", "", 0),
|
|
(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)", r"\1, \2", 0),
|
|
(r"__attribute_const__ +", "", 0),
|
|
|
|
# It seems that Python support for re.X is broken:
|
|
# At least for me (Python 3.13), this didn't work
|
|
# (r"""
|
|
# __attribute__\s*\(\(
|
|
# (?:
|
|
# [\w\s]+ # attribute name
|
|
# (?:\([^)]*\))? # attribute arguments
|
|
# \s*,? # optional comma at the end
|
|
# )+
|
|
# \)\)\s+
|
|
# """, "", re.X),
|
|
|
|
# So, remove whitespaces and comments from it
|
|
(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+", "", 0),
|
|
]
|
|
|
|
for search, sub, flags in sub_prefixes:
|
|
prototype = KernRe(search, flags).sub(sub, prototype)
|
|
|
|
# Macros are a special case, as they change the prototype format
|
|
new_proto = KernRe(r"^#\s*define\s+").sub("", prototype)
|
|
if new_proto != prototype:
|
|
is_define_proto = True
|
|
prototype = new_proto
|
|
else:
|
|
is_define_proto = False
|
|
|
|
# Yes, this truly is vile. We are looking for:
|
|
# 1. Return type (may be nothing if we're looking at a macro)
|
|
# 2. Function name
|
|
# 3. Function parameters.
|
|
#
|
|
# All the while we have to watch out for function pointer parameters
|
|
# (which IIRC is what the two sections are for), C types (these
|
|
# regexps don't even start to express all the possibilities), and
|
|
# so on.
|
|
#
|
|
# If you mess with these regexps, it's a good idea to check that
|
|
# the following functions' documentation still comes out right:
|
|
# - parport_register_device (function pointer parameters)
|
|
# - atomic_set (macro)
|
|
# - pci_match_device, __copy_to_user (long return type)
|
|
|
|
name = r'[a-zA-Z0-9_~:]+'
|
|
prototype_end1 = r'[^\(]*'
|
|
prototype_end2 = r'[^\{]*'
|
|
prototype_end = fr'\(({prototype_end1}|{prototype_end2})\)'
|
|
|
|
# Besides compiling, Perl qr{[\w\s]+} works as a non-capturing group.
|
|
# So, this needs to be mapped in Python with (?:...)? or (?:...)+
|
|
|
|
type1 = r'(?:[\w\s]+)?'
|
|
type2 = r'(?:[\w\s]+\*+)+'
|
|
|
|
found = False
|
|
|
|
if is_define_proto:
|
|
r = KernRe(r'^()(' + name + r')\s+')
|
|
|
|
if r.search(prototype):
|
|
return_type = ''
|
|
declaration_name = r.group(2)
|
|
func_macro = True
|
|
|
|
found = True
|
|
|
|
if not found:
|
|
patterns = [
|
|
rf'^()({name})\s*{prototype_end}',
|
|
rf'^({type1})\s+({name})\s*{prototype_end}',
|
|
rf'^({type2})\s*({name})\s*{prototype_end}',
|
|
]
|
|
|
|
for p in patterns:
|
|
r = KernRe(p)
|
|
|
|
if r.match(prototype):
|
|
|
|
return_type = r.group(1)
|
|
declaration_name = r.group(2)
|
|
args = r.group(3)
|
|
|
|
self.create_parameter_list(ln, decl_type, args, ',',
|
|
declaration_name)
|
|
|
|
found = True
|
|
break
|
|
if not found:
|
|
self.emit_msg(ln,
|
|
f"cannot understand function prototype: '{prototype}'")
|
|
return
|
|
|
|
if self.entry.identifier != declaration_name:
|
|
self.emit_msg(ln,
|
|
f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead")
|
|
return
|
|
|
|
prms = " ".join(self.entry.parameterlist)
|
|
self.check_sections(ln, declaration_name, "function",
|
|
self.entry.sectcheck, prms)
|
|
|
|
self.check_return_section(ln, declaration_name, return_type)
|
|
|
|
if 'typedef' in return_type:
|
|
self.output_declaration(decl_type, declaration_name,
|
|
function=declaration_name,
|
|
typedef=True,
|
|
functiontype=return_type,
|
|
parameterlist=self.entry.parameterlist,
|
|
parameterdescs=self.entry.parameterdescs,
|
|
parametertypes=self.entry.parametertypes,
|
|
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose,
|
|
func_macro=func_macro)
|
|
else:
|
|
self.output_declaration(decl_type, declaration_name,
|
|
function=declaration_name,
|
|
typedef=False,
|
|
functiontype=return_type,
|
|
parameterlist=self.entry.parameterlist,
|
|
parameterdescs=self.entry.parameterdescs,
|
|
parametertypes=self.entry.parametertypes,
|
|
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose,
|
|
func_macro=func_macro)
|
|
|
|
def dump_typedef(self, ln, proto):
|
|
"""
|
|
Stores a typedef inside self.entries array.
|
|
"""
|
|
|
|
typedef_type = r'((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
|
|
typedef_ident = r'\*?\s*(\w\S+)\s*'
|
|
typedef_args = r'\s*\((.*)\);'
|
|
|
|
typedef1 = KernRe(r'typedef' + typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
|
|
typedef2 = KernRe(r'typedef' + typedef_type + typedef_ident + typedef_args)
|
|
|
|
# Strip comments
|
|
proto = KernRe(r'/\*.*?\*/', flags=re.S).sub('', proto)
|
|
|
|
# Parse function typedef prototypes
|
|
for r in [typedef1, typedef2]:
|
|
if not r.match(proto):
|
|
continue
|
|
|
|
return_type = r.group(1).strip()
|
|
declaration_name = r.group(2)
|
|
args = r.group(3)
|
|
|
|
if self.entry.identifier != declaration_name:
|
|
self.emit_msg(ln,
|
|
f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
|
|
return
|
|
|
|
decl_type = 'function'
|
|
self.create_parameter_list(ln, decl_type, args, ',', declaration_name)
|
|
|
|
self.output_declaration(decl_type, declaration_name,
|
|
function=declaration_name,
|
|
typedef=True,
|
|
functiontype=return_type,
|
|
parameterlist=self.entry.parameterlist,
|
|
parameterdescs=self.entry.parameterdescs,
|
|
parametertypes=self.entry.parametertypes,
|
|
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose)
|
|
return
|
|
|
|
# Handle nested parentheses or brackets
|
|
r = KernRe(r'(\(*.\)\s*|\[*.\]\s*);$')
|
|
while r.search(proto):
|
|
proto = r.sub('', proto)
|
|
|
|
# Parse simple typedefs
|
|
r = KernRe(r'typedef.*\s+(\w+)\s*;')
|
|
if r.match(proto):
|
|
declaration_name = r.group(1)
|
|
|
|
if self.entry.identifier != declaration_name:
|
|
self.emit_msg(ln,
|
|
f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
|
|
return
|
|
|
|
self.output_declaration('typedef', declaration_name,
|
|
typedef=declaration_name,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines,
|
|
purpose=self.entry.declaration_purpose)
|
|
return
|
|
|
|
self.emit_msg(ln, "error: Cannot parse typedef!")
|
|
|
|
@staticmethod
|
|
def process_export(function_set, line):
|
|
"""
|
|
process EXPORT_SYMBOL* tags
|
|
|
|
This method doesn't use any variable from the class, so declare it
|
|
with a staticmethod decorator.
|
|
"""
|
|
|
|
# Note: it accepts only one EXPORT_SYMBOL* per line, as having
|
|
# multiple export lines would violate Kernel coding style.
|
|
|
|
if export_symbol.search(line):
|
|
symbol = export_symbol.group(2)
|
|
function_set.add(symbol)
|
|
return
|
|
|
|
if export_symbol_ns.search(line):
|
|
symbol = export_symbol_ns.group(2)
|
|
function_set.add(symbol)
|
|
|
|
def process_normal(self, ln, line):
|
|
"""
|
|
STATE_NORMAL: looking for the /** to begin everything.
|
|
"""
|
|
|
|
if not doc_start.match(line):
|
|
return
|
|
|
|
# start a new entry
|
|
self.reset_state(ln)
|
|
self.entry.in_doc_sect = False
|
|
|
|
# next line is always the function name
|
|
self.state = state.NAME
|
|
|
|
def process_name(self, ln, line):
|
|
"""
|
|
STATE_NAME: Looking for the "name - description" line
|
|
"""
|
|
|
|
if doc_block.search(line):
|
|
self.entry.new_start_line = ln
|
|
|
|
if not doc_block.group(1):
|
|
self.entry.section = self.section_intro
|
|
else:
|
|
self.entry.section = doc_block.group(1)
|
|
|
|
self.entry.identifier = self.entry.section
|
|
self.state = state.DOCBLOCK
|
|
return
|
|
|
|
if doc_decl.search(line):
|
|
self.entry.identifier = doc_decl.group(1)
|
|
self.entry.is_kernel_comment = False
|
|
|
|
decl_start = str(doc_com) # comment block asterisk
|
|
fn_type = r"(?:\w+\s*\*\s*)?" # type (for non-functions)
|
|
parenthesis = r"(?:\(\w*\))?" # optional parenthesis on function
|
|
decl_end = r"(?:[-:].*)" # end of the name part
|
|
|
|
# test for pointer declaration type, foo * bar() - desc
|
|
r = KernRe(fr"^{decl_start}([\w\s]+?){parenthesis}?\s*{decl_end}?$")
|
|
if r.search(line):
|
|
self.entry.identifier = r.group(1)
|
|
|
|
# Test for data declaration
|
|
r = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)")
|
|
if r.search(line):
|
|
self.entry.decl_type = r.group(1)
|
|
self.entry.identifier = r.group(2)
|
|
self.entry.is_kernel_comment = True
|
|
else:
|
|
# Look for foo() or static void foo() - description;
|
|
# or misspelt identifier
|
|
|
|
r1 = KernRe(fr"^{decl_start}{fn_type}(\w+)\s*{parenthesis}\s*{decl_end}?$")
|
|
r2 = KernRe(fr"^{decl_start}{fn_type}(\w+[^-:]*){parenthesis}\s*{decl_end}$")
|
|
|
|
for r in [r1, r2]:
|
|
if r.search(line):
|
|
self.entry.identifier = r.group(1)
|
|
self.entry.decl_type = "function"
|
|
|
|
r = KernRe(r"define\s+")
|
|
self.entry.identifier = r.sub("", self.entry.identifier)
|
|
self.entry.is_kernel_comment = True
|
|
break
|
|
|
|
self.entry.identifier = self.entry.identifier.strip(" ")
|
|
|
|
self.state = state.BODY
|
|
|
|
# if there's no @param blocks need to set up default section here
|
|
self.entry.section = SECTION_DEFAULT
|
|
self.entry.new_start_line = ln + 1
|
|
|
|
r = KernRe("[-:](.*)")
|
|
if r.search(line):
|
|
# strip leading/trailing/multiple spaces
|
|
self.entry.descr = r.group(1).strip(" ")
|
|
|
|
r = KernRe(r"\s+")
|
|
self.entry.descr = r.sub(" ", self.entry.descr)
|
|
self.entry.declaration_purpose = self.entry.descr
|
|
self.state = state.BODY_MAYBE
|
|
else:
|
|
self.entry.declaration_purpose = ""
|
|
|
|
if not self.entry.is_kernel_comment:
|
|
self.emit_msg(ln,
|
|
f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
|
|
self.state = state.NORMAL
|
|
|
|
if not self.entry.declaration_purpose and self.config.wshort_desc:
|
|
self.emit_msg(ln,
|
|
f"missing initial short description on line:\n{line}")
|
|
|
|
if not self.entry.identifier and self.entry.decl_type != "enum":
|
|
self.emit_msg(ln,
|
|
f"wrong kernel-doc identifier on line:\n{line}")
|
|
self.state = state.NORMAL
|
|
|
|
if self.config.verbose:
|
|
self.emit_msg(ln,
|
|
f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
|
|
warning=False)
|
|
|
|
return
|
|
|
|
# Failed to find an identifier. Emit a warning
|
|
self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
|
|
|
|
def process_body(self, ln, line):
|
|
"""
|
|
STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
|
|
"""
|
|
|
|
if self.state == state.BODY_WITH_BLANK_LINE:
|
|
r = KernRe(r"\s*\*\s?\S")
|
|
if r.match(line):
|
|
self.dump_section()
|
|
self.entry.section = SECTION_DEFAULT
|
|
self.entry.new_start_line = ln
|
|
self.entry.contents = ""
|
|
|
|
if doc_sect.search(line):
|
|
self.entry.in_doc_sect = True
|
|
newsection = doc_sect.group(1)
|
|
|
|
if newsection.lower() in ["description", "context"]:
|
|
newsection = newsection.title()
|
|
|
|
# Special case: @return is a section, not a param description
|
|
if newsection.lower() in ["@return", "@returns",
|
|
"return", "returns"]:
|
|
newsection = "Return"
|
|
|
|
# Perl kernel-doc has a check here for contents before sections.
|
|
# the logic there is always false, as in_doc_sect variable is
|
|
# always true. So, just don't implement Wcontents_before_sections
|
|
|
|
# .title()
|
|
newcontents = doc_sect.group(2)
|
|
if not newcontents:
|
|
newcontents = ""
|
|
|
|
if self.entry.contents.strip("\n"):
|
|
self.dump_section()
|
|
|
|
self.entry.new_start_line = ln
|
|
self.entry.section = newsection
|
|
self.entry.leading_space = None
|
|
|
|
self.entry.contents = newcontents.lstrip()
|
|
if self.entry.contents:
|
|
self.entry.contents += "\n"
|
|
|
|
self.state = state.BODY
|
|
return
|
|
|
|
if doc_end.search(line):
|
|
self.dump_section()
|
|
|
|
# Look for doc_com + <text> + doc_end:
|
|
r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:\.]+\*/')
|
|
if r.match(line):
|
|
self.emit_msg(ln, f"suspicious ending line: {line}")
|
|
|
|
self.entry.prototype = ""
|
|
self.entry.new_start_line = ln + 1
|
|
|
|
self.state = state.PROTO
|
|
return
|
|
|
|
if doc_content.search(line):
|
|
cont = doc_content.group(1)
|
|
|
|
if cont == "":
|
|
if self.entry.section == self.section_context:
|
|
self.dump_section()
|
|
|
|
self.entry.new_start_line = ln
|
|
self.state = state.BODY
|
|
else:
|
|
if self.entry.section != SECTION_DEFAULT:
|
|
self.state = state.BODY_WITH_BLANK_LINE
|
|
else:
|
|
self.state = state.BODY
|
|
|
|
self.entry.contents += "\n"
|
|
|
|
elif self.state == state.BODY_MAYBE:
|
|
|
|
# Continued declaration purpose
|
|
self.entry.declaration_purpose = self.entry.declaration_purpose.rstrip()
|
|
self.entry.declaration_purpose += " " + cont
|
|
|
|
r = KernRe(r"\s+")
|
|
self.entry.declaration_purpose = r.sub(' ',
|
|
self.entry.declaration_purpose)
|
|
|
|
else:
|
|
if self.entry.section.startswith('@') or \
|
|
self.entry.section == self.section_context:
|
|
if self.entry.leading_space is None:
|
|
r = KernRe(r'^(\s+)')
|
|
if r.match(cont):
|
|
self.entry.leading_space = len(r.group(1))
|
|
else:
|
|
self.entry.leading_space = 0
|
|
|
|
# Double-check if leading space are realy spaces
|
|
pos = 0
|
|
for i in range(0, self.entry.leading_space):
|
|
if cont[i] != " ":
|
|
break
|
|
pos += 1
|
|
|
|
cont = cont[pos:]
|
|
|
|
# NEW LOGIC:
|
|
# In case it is different, update it
|
|
if self.entry.leading_space != pos:
|
|
self.entry.leading_space = pos
|
|
|
|
self.entry.contents += cont + "\n"
|
|
return
|
|
|
|
# Unknown line, ignore
|
|
self.emit_msg(ln, f"bad line: {line}")
|
|
|
|
def process_inline(self, ln, line):
|
|
"""STATE_INLINE: docbook comments within a prototype."""
|
|
|
|
if self.inline_doc_state == state.INLINE_NAME and \
|
|
doc_inline_sect.search(line):
|
|
self.entry.section = doc_inline_sect.group(1)
|
|
self.entry.new_start_line = ln
|
|
|
|
self.entry.contents = doc_inline_sect.group(2).lstrip()
|
|
if self.entry.contents != "":
|
|
self.entry.contents += "\n"
|
|
|
|
self.inline_doc_state = state.INLINE_TEXT
|
|
# Documentation block end */
|
|
return
|
|
|
|
if doc_inline_end.search(line):
|
|
if self.entry.contents not in ["", "\n"]:
|
|
self.dump_section()
|
|
|
|
self.state = state.PROTO
|
|
self.inline_doc_state = state.INLINE_NA
|
|
return
|
|
|
|
if doc_content.search(line):
|
|
if self.inline_doc_state == state.INLINE_TEXT:
|
|
self.entry.contents += doc_content.group(1) + "\n"
|
|
if not self.entry.contents.strip(" ").rstrip("\n"):
|
|
self.entry.contents = ""
|
|
|
|
elif self.inline_doc_state == state.INLINE_NAME:
|
|
self.emit_msg(ln,
|
|
f"Incorrect use of kernel-doc format: {line}")
|
|
|
|
self.inline_doc_state = state.INLINE_ERROR
|
|
|
|
def syscall_munge(self, ln, proto): # pylint: disable=W0613
|
|
"""
|
|
Handle syscall definitions
|
|
"""
|
|
|
|
is_void = False
|
|
|
|
# Strip newlines/CR's
|
|
proto = re.sub(r'[\r\n]+', ' ', proto)
|
|
|
|
# Check if it's a SYSCALL_DEFINE0
|
|
if 'SYSCALL_DEFINE0' in proto:
|
|
is_void = True
|
|
|
|
# Replace SYSCALL_DEFINE with correct return type & function name
|
|
proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
|
|
|
|
r = KernRe(r'long\s+(sys_.*?),')
|
|
if r.search(proto):
|
|
proto = KernRe(',').sub('(', proto, count=1)
|
|
elif is_void:
|
|
proto = KernRe(r'\)').sub('(void)', proto, count=1)
|
|
|
|
# Now delete all of the odd-numbered commas in the proto
|
|
# so that argument types & names don't have a comma between them
|
|
count = 0
|
|
length = len(proto)
|
|
|
|
if is_void:
|
|
length = 0 # skip the loop if is_void
|
|
|
|
for ix in range(length):
|
|
if proto[ix] == ',':
|
|
count += 1
|
|
if count % 2 == 1:
|
|
proto = proto[:ix] + ' ' + proto[ix + 1:]
|
|
|
|
return proto
|
|
|
|
def tracepoint_munge(self, ln, proto):
|
|
"""
|
|
Handle tracepoint definitions
|
|
"""
|
|
|
|
tracepointname = None
|
|
tracepointargs = None
|
|
|
|
# Match tracepoint name based on different patterns
|
|
r = KernRe(r'TRACE_EVENT\((.*?),')
|
|
if r.search(proto):
|
|
tracepointname = r.group(1)
|
|
|
|
r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
|
|
if r.search(proto):
|
|
tracepointname = r.group(1)
|
|
|
|
r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
|
|
if r.search(proto):
|
|
tracepointname = r.group(2)
|
|
|
|
if tracepointname:
|
|
tracepointname = tracepointname.lstrip()
|
|
|
|
r = KernRe(r'TP_PROTO\((.*?)\)')
|
|
if r.search(proto):
|
|
tracepointargs = r.group(1)
|
|
|
|
if not tracepointname or not tracepointargs:
|
|
self.emit_msg(ln,
|
|
f"Unrecognized tracepoint format:\n{proto}\n")
|
|
else:
|
|
proto = f"static inline void trace_{tracepointname}({tracepointargs})"
|
|
self.entry.identifier = f"trace_{self.entry.identifier}"
|
|
|
|
return proto
|
|
|
|
def process_proto_function(self, ln, line):
|
|
"""Ancillary routine to process a function prototype"""
|
|
|
|
# strip C99-style comments to end of line
|
|
r = KernRe(r"\/\/.*$", re.S)
|
|
line = r.sub('', line)
|
|
|
|
if KernRe(r'\s*#\s*define').match(line):
|
|
self.entry.prototype = line
|
|
elif line.startswith('#'):
|
|
# Strip other macros like #ifdef/#ifndef/#endif/...
|
|
pass
|
|
else:
|
|
r = KernRe(r'([^\{]*)')
|
|
if r.match(line):
|
|
self.entry.prototype += r.group(1) + " "
|
|
|
|
if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(line):
|
|
# strip comments
|
|
r = KernRe(r'/\*.*?\*/')
|
|
self.entry.prototype = r.sub('', self.entry.prototype)
|
|
|
|
# strip newlines/cr's
|
|
r = KernRe(r'[\r\n]+')
|
|
self.entry.prototype = r.sub(' ', self.entry.prototype)
|
|
|
|
# strip leading spaces
|
|
r = KernRe(r'^\s+')
|
|
self.entry.prototype = r.sub('', self.entry.prototype)
|
|
|
|
# Handle self.entry.prototypes for function pointers like:
|
|
# int (*pcs_config)(struct foo)
|
|
|
|
r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
|
|
self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
|
|
|
|
if 'SYSCALL_DEFINE' in self.entry.prototype:
|
|
self.entry.prototype = self.syscall_munge(ln,
|
|
self.entry.prototype)
|
|
|
|
r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
|
|
if r.search(self.entry.prototype):
|
|
self.entry.prototype = self.tracepoint_munge(ln,
|
|
self.entry.prototype)
|
|
|
|
self.dump_function(ln, self.entry.prototype)
|
|
self.reset_state(ln)
|
|
|
|
def process_proto_type(self, ln, line):
|
|
"""Ancillary routine to process a type"""
|
|
|
|
# Strip newlines/cr's.
|
|
line = KernRe(r'[\r\n]+', re.S).sub(' ', line)
|
|
|
|
# Strip leading spaces
|
|
line = KernRe(r'^\s+', re.S).sub('', line)
|
|
|
|
# Strip trailing spaces
|
|
line = KernRe(r'\s+$', re.S).sub('', line)
|
|
|
|
# Strip C99-style comments to the end of the line
|
|
line = KernRe(r"\/\/.*$", re.S).sub('', line)
|
|
|
|
# To distinguish preprocessor directive from regular declaration later.
|
|
if line.startswith('#'):
|
|
line += ";"
|
|
|
|
r = KernRe(r'([^\{\};]*)([\{\};])(.*)')
|
|
while True:
|
|
if r.search(line):
|
|
if self.entry.prototype:
|
|
self.entry.prototype += " "
|
|
self.entry.prototype += r.group(1) + r.group(2)
|
|
|
|
self.entry.brcount += r.group(2).count('{')
|
|
self.entry.brcount -= r.group(2).count('}')
|
|
|
|
self.entry.brcount = max(self.entry.brcount, 0)
|
|
|
|
if r.group(2) == ';' and self.entry.brcount == 0:
|
|
self.dump_declaration(ln, self.entry.prototype)
|
|
self.reset_state(ln)
|
|
break
|
|
|
|
line = r.group(3)
|
|
else:
|
|
self.entry.prototype += line
|
|
break
|
|
|
|
def process_proto(self, ln, line):
|
|
"""STATE_PROTO: reading a function/whatever prototype."""
|
|
|
|
if doc_inline_oneline.search(line):
|
|
self.entry.section = doc_inline_oneline.group(1)
|
|
self.entry.contents = doc_inline_oneline.group(2)
|
|
|
|
if self.entry.contents != "":
|
|
self.entry.contents += "\n"
|
|
self.dump_section(start_new=False)
|
|
|
|
elif doc_inline_start.search(line):
|
|
self.state = state.INLINE
|
|
self.inline_doc_state = state.INLINE_NAME
|
|
|
|
elif self.entry.decl_type == 'function':
|
|
self.process_proto_function(ln, line)
|
|
|
|
else:
|
|
self.process_proto_type(ln, line)
|
|
|
|
def process_docblock(self, ln, line):
|
|
"""STATE_DOCBLOCK: within a DOC: block."""
|
|
|
|
if doc_end.search(line):
|
|
self.dump_section()
|
|
self.output_declaration("doc", self.entry.identifier,
|
|
sectionlist=self.entry.sectionlist,
|
|
sections=self.entry.sections,
|
|
section_start_lines=self.entry.section_start_lines)
|
|
self.reset_state(ln)
|
|
|
|
elif doc_content.search(line):
|
|
self.entry.contents += doc_content.group(1) + "\n"
|
|
|
|
def parse_export(self):
|
|
"""
|
|
Parses EXPORT_SYMBOL* macros from a single Kernel source file.
|
|
"""
|
|
|
|
export_table = set()
|
|
|
|
try:
|
|
with open(self.fname, "r", encoding="utf8",
|
|
errors="backslashreplace") as fp:
|
|
|
|
for line in fp:
|
|
self.process_export(export_table, line)
|
|
|
|
except IOError:
|
|
return None
|
|
|
|
return export_table
|
|
|
|
def parse_kdoc(self):
|
|
"""
|
|
Open and process each line of a C source file.
|
|
The parsing is controlled via a state machine, and the line is passed
|
|
to a different process function depending on the state. The process
|
|
function may update the state as needed.
|
|
|
|
Besides parsing kernel-doc tags, it also parses export symbols.
|
|
"""
|
|
|
|
cont = False
|
|
prev = ""
|
|
prev_ln = None
|
|
export_table = set()
|
|
|
|
try:
|
|
with open(self.fname, "r", encoding="utf8",
|
|
errors="backslashreplace") as fp:
|
|
for ln, line in enumerate(fp):
|
|
|
|
line = line.expandtabs().strip("\n")
|
|
|
|
# Group continuation lines on prototypes
|
|
if self.state == state.PROTO:
|
|
if line.endswith("\\"):
|
|
prev += line.rstrip("\\")
|
|
cont = True
|
|
|
|
if not prev_ln:
|
|
prev_ln = ln
|
|
|
|
continue
|
|
|
|
if cont:
|
|
ln = prev_ln
|
|
line = prev + line
|
|
prev = ""
|
|
cont = False
|
|
prev_ln = None
|
|
|
|
self.config.log.debug("%d %s%s: %s",
|
|
ln, state.name[self.state],
|
|
state.inline_name[self.inline_doc_state],
|
|
line)
|
|
|
|
# This is an optimization over the original script.
|
|
# There, when export_file was used for the same file,
|
|
# it was read twice. Here, we use the already-existing
|
|
# loop to parse exported symbols as well.
|
|
#
|
|
# TODO: It should be noticed that not all states are
|
|
# needed here. On a future cleanup, process export only
|
|
# at the states that aren't handling comment markups.
|
|
self.process_export(export_table, line)
|
|
|
|
# Hand this line to the appropriate state handler
|
|
if self.state == state.NORMAL:
|
|
self.process_normal(ln, line)
|
|
elif self.state == state.NAME:
|
|
self.process_name(ln, line)
|
|
elif self.state in [state.BODY, state.BODY_MAYBE,
|
|
state.BODY_WITH_BLANK_LINE]:
|
|
self.process_body(ln, line)
|
|
elif self.state == state.INLINE: # scanning for inline parameters
|
|
self.process_inline(ln, line)
|
|
elif self.state == state.PROTO:
|
|
self.process_proto(ln, line)
|
|
elif self.state == state.DOCBLOCK:
|
|
self.process_docblock(ln, line)
|
|
except OSError:
|
|
self.config.log.error(f"Error: Cannot open file {self.fname}")
|
|
|
|
return export_table, self.entries
|