Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
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=C0301,C0302,R0904,R0912,R0913,R0914,R0915,R0917,R1702
6
7"""
8kdoc_parser
9===========
10
11Read a C language source or header FILE and extract embedded
12documentation comments
13"""
14
15import sys
16import re
17from pprint import pformat
18
19from kdoc.kdoc_re import NestedMatch, KernRe
20from kdoc.kdoc_item import KdocItem
21
22#
23# Regular expressions used to parse kernel-doc markups at KernelDoc class.
24#
25# Let's declare them in lowercase outside any class to make it easier to
26# convert from the Perl script.
27#
28# As those are evaluated at the beginning, no need to cache them
29#
30
31# Allow whitespace at end of comment start.
32doc_start = KernRe(r'^/\*\*\s*$', cache=False)
33
34doc_end = KernRe(r'\*/', cache=False)
35doc_com = KernRe(r'\s*\*\s*', cache=False)
36doc_com_body = KernRe(r'\s*\* ?', cache=False)
37doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
38
39# @params and a strictly limited set of supported section names
40# Specifically:
41# Match @word:
42# @...:
43# @{section-name}:
44# while trying to not match literal block starts like "example::"
45#
46known_section_names = 'description|context|returns?|notes?|examples?'
47known_sections = KernRe(known_section_names, flags = re.I)
48doc_sect = doc_com + \
49 KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
50 flags=re.I, cache=False)
51
52doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
53doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False)
54doc_inline_sect = KernRe(r'\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)', cache=False)
55doc_inline_end = KernRe(r'^\s*\*/\s*$', cache=False)
56doc_inline_oneline = KernRe(r'^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$', cache=False)
57
58export_symbol = KernRe(r'^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*', cache=False)
59export_symbol_ns = KernRe(r'^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*"\S+"\)\s*', cache=False)
60
61type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
62
63#
64# Tests for the beginning of a kerneldoc block in its various forms.
65#
66doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
67doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)", cache = False)
68doc_begin_func = KernRe(str(doc_com) + # initial " * '
69 r"(?:\w+\s*\*\s*)?" + # type (not captured)
70 r'(?:define\s+)?' + # possible "define" (not captured)
71 r'(\w+)\s*(?:\(\w*\))?\s*' + # name and optional "(...)"
72 r'(?:[-:].*)?$', # description (not captured)
73 cache = False)
74
75#
76# Here begins a long set of transformations to turn structure member prefixes
77# and macro invocations into something we can parse and generate kdoc for.
78#
79struct_args_pattern = r'([^,)]+)'
80
81struct_xforms = [
82 # Strip attributes
83 (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=re.I | re.S, cache=False), ' '),
84 (KernRe(r'\s*__aligned\s*\([^;]*\)', re.S), ' '),
85 (KernRe(r'\s*__counted_by\s*\([^;]*\)', re.S), ' '),
86 (KernRe(r'\s*__counted_by_(le|be)\s*\([^;]*\)', re.S), ' '),
87 (KernRe(r'\s*__packed\s*', re.S), ' '),
88 (KernRe(r'\s*CRYPTO_MINALIGN_ATTR', re.S), ' '),
89 (KernRe(r'\s*__private', re.S), ' '),
90 (KernRe(r'\s*__rcu', re.S), ' '),
91 (KernRe(r'\s*____cacheline_aligned_in_smp', re.S), ' '),
92 (KernRe(r'\s*____cacheline_aligned', re.S), ' '),
93 (KernRe(r'\s*__cacheline_group_(begin|end)\([^\)]+\);'), ''),
94 #
95 # Unwrap struct_group macros based on this definition:
96 # __struct_group(TAG, NAME, ATTRS, MEMBERS...)
97 # which has variants like: struct_group(NAME, MEMBERS...)
98 # Only MEMBERS arguments require documentation.
99 #
100 # Parsing them happens on two steps:
101 #
102 # 1. drop struct group arguments that aren't at MEMBERS,
103 # storing them as STRUCT_GROUP(MEMBERS)
104 #
105 # 2. remove STRUCT_GROUP() ancillary macro.
106 #
107 # The original logic used to remove STRUCT_GROUP() using an
108 # advanced regex:
109 #
110 # \bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)\))[^;]*;
111 #
112 # with two patterns that are incompatible with
113 # Python re module, as it has:
114 #
115 # - a recursive pattern: (?1)
116 # - an atomic grouping: (?>...)
117 #
118 # I tried a simpler version: but it didn't work either:
119 # \bSTRUCT_GROUP\(([^\)]+)\)[^;]*;
120 #
121 # As it doesn't properly match the end parenthesis on some cases.
122 #
123 # So, a better solution was crafted: there's now a NestedMatch
124 # class that ensures that delimiters after a search are properly
125 # matched. So, the implementation to drop STRUCT_GROUP() will be
126 # handled in separate.
127 #
128 (KernRe(r'\bstruct_group\s*\(([^,]*,)', re.S), r'STRUCT_GROUP('),
129 (KernRe(r'\bstruct_group_attr\s*\(([^,]*,){2}', re.S), r'STRUCT_GROUP('),
130 (KernRe(r'\bstruct_group_tagged\s*\(([^,]*),([^,]*),', re.S), r'struct \1 \2; STRUCT_GROUP('),
131 (KernRe(r'\b__struct_group\s*\(([^,]*,){3}', re.S), r'STRUCT_GROUP('),
132 #
133 # Replace macros
134 #
135 # TODO: use NestedMatch for FOO($1, $2, ...) matches
136 #
137 # it is better to also move those to the NestedMatch logic,
138 # to ensure that parentheses will be properly matched.
139 #
140 (KernRe(r'__ETHTOOL_DECLARE_LINK_MODE_MASK\s*\(([^\)]+)\)', re.S),
141 r'DECLARE_BITMAP(\1, __ETHTOOL_LINK_MODE_MASK_NBITS)'),
142 (KernRe(r'DECLARE_PHY_INTERFACE_MASK\s*\(([^\)]+)\)', re.S),
143 r'DECLARE_BITMAP(\1, PHY_INTERFACE_MODE_MAX)'),
144 (KernRe(r'DECLARE_BITMAP\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)',
145 re.S), r'unsigned long \1[BITS_TO_LONGS(\2)]'),
146 (KernRe(r'DECLARE_HASHTABLE\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern + r'\)',
147 re.S), r'unsigned long \1[1 << ((\2) - 1)]'),
148 (KernRe(r'DECLARE_KFIFO\s*\(' + struct_args_pattern + r',\s*' + struct_args_pattern +
149 r',\s*' + struct_args_pattern + r'\)', re.S), r'\2 *\1'),
150 (KernRe(r'DECLARE_KFIFO_PTR\s*\(' + struct_args_pattern + r',\s*' +
151 struct_args_pattern + r'\)', re.S), r'\2 *\1'),
152 (KernRe(r'(?:__)?DECLARE_FLEX_ARRAY\s*\(' + struct_args_pattern + r',\s*' +
153 struct_args_pattern + r'\)', re.S), r'\1 \2[]'),
154 (KernRe(r'DEFINE_DMA_UNMAP_ADDR\s*\(' + struct_args_pattern + r'\)', re.S), r'dma_addr_t \1'),
155 (KernRe(r'DEFINE_DMA_UNMAP_LEN\s*\(' + struct_args_pattern + r'\)', re.S), r'__u32 \1'),
156]
157#
158# Regexes here are guaranteed to have the end delimiter matching
159# the start delimiter. Yet, right now, only one replace group
160# is allowed.
161#
162struct_nested_prefixes = [
163 (re.compile(r'\bSTRUCT_GROUP\('), r'\1'),
164]
165
166#
167# Transforms for function prototypes
168#
169function_xforms = [
170 (KernRe(r"^static +"), ""),
171 (KernRe(r"^extern +"), ""),
172 (KernRe(r"^asmlinkage +"), ""),
173 (KernRe(r"^inline +"), ""),
174 (KernRe(r"^__inline__ +"), ""),
175 (KernRe(r"^__inline +"), ""),
176 (KernRe(r"^__always_inline +"), ""),
177 (KernRe(r"^noinline +"), ""),
178 (KernRe(r"^__FORTIFY_INLINE +"), ""),
179 (KernRe(r"__init +"), ""),
180 (KernRe(r"__init_or_module +"), ""),
181 (KernRe(r"__deprecated +"), ""),
182 (KernRe(r"__flatten +"), ""),
183 (KernRe(r"__meminit +"), ""),
184 (KernRe(r"__must_check +"), ""),
185 (KernRe(r"__weak +"), ""),
186 (KernRe(r"__sched +"), ""),
187 (KernRe(r"_noprof"), ""),
188 (KernRe(r"__always_unused *"), ""),
189 (KernRe(r"__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +"), ""),
190 (KernRe(r"__(?:re)?alloc_size\s*\(\s*\d+\s*(?:,\s*\d+\s*)?\) +"), ""),
191 (KernRe(r"__diagnose_as\s*\(\s*\S+\s*(?:,\s*\d+\s*)*\) +"), ""),
192 (KernRe(r"DECL_BUCKET_PARAMS\s*\(\s*(\S+)\s*,\s*(\S+)\s*\)"), r"\1, \2"),
193 (KernRe(r"__attribute_const__ +"), ""),
194 (KernRe(r"__attribute__\s*\(\((?:[\w\s]+(?:\([^)]*\))?\s*,?)+\)\)\s+"), ""),
195]
196
197#
198# Apply a set of transforms to a block of text.
199#
200def apply_transforms(xforms, text):
201 for search, subst in xforms:
202 text = search.sub(subst, text)
203 return text
204
205#
206# A little helper to get rid of excess white space
207#
208multi_space = KernRe(r'\s\s+')
209def trim_whitespace(s):
210 return multi_space.sub(' ', s.strip())
211
212#
213# Remove struct/enum members that have been marked "private".
214#
215def trim_private_members(text):
216 #
217 # First look for a "public:" block that ends a private region, then
218 # handle the "private until the end" case.
219 #
220 text = KernRe(r'/\*\s*private:.*?/\*\s*public:.*?\*/', flags=re.S).sub('', text)
221 text = KernRe(r'/\*\s*private:.*', flags=re.S).sub('', text)
222 #
223 # We needed the comments to do the above, but now we can take them out.
224 #
225 return KernRe(r'\s*/\*.*?\*/\s*', flags=re.S).sub('', text).strip()
226
227class state:
228 """
229 State machine enums
230 """
231
232 # Parser states
233 NORMAL = 0 # normal code
234 NAME = 1 # looking for function name
235 DECLARATION = 2 # We have seen a declaration which might not be done
236 BODY = 3 # the body of the comment
237 SPECIAL_SECTION = 4 # doc section ending with a blank line
238 PROTO = 5 # scanning prototype
239 DOCBLOCK = 6 # documentation block
240 INLINE_NAME = 7 # gathering doc outside main block
241 INLINE_TEXT = 8 # reading the body of inline docs
242
243 name = [
244 "NORMAL",
245 "NAME",
246 "DECLARATION",
247 "BODY",
248 "SPECIAL_SECTION",
249 "PROTO",
250 "DOCBLOCK",
251 "INLINE_NAME",
252 "INLINE_TEXT",
253 ]
254
255
256SECTION_DEFAULT = "Description" # default section
257
258class KernelEntry:
259
260 def __init__(self, config, fname, ln):
261 self.config = config
262 self.fname = fname
263
264 self._contents = []
265 self.prototype = ""
266
267 self.warnings = []
268
269 self.parameterlist = []
270 self.parameterdescs = {}
271 self.parametertypes = {}
272 self.parameterdesc_start_lines = {}
273
274 self.section_start_lines = {}
275 self.sections = {}
276
277 self.anon_struct_union = False
278
279 self.leading_space = None
280
281 self.fname = fname
282
283 # State flags
284 self.brcount = 0
285 self.declaration_start_line = ln + 1
286
287 #
288 # Management of section contents
289 #
290 def add_text(self, text):
291 self._contents.append(text)
292
293 def contents(self):
294 return '\n'.join(self._contents) + '\n'
295
296 # TODO: rename to emit_message after removal of kernel-doc.pl
297 def emit_msg(self, ln, msg, *, warning=True):
298 """Emit a message"""
299
300 log_msg = f"{self.fname}:{ln} {msg}"
301
302 if not warning:
303 self.config.log.info(log_msg)
304 return
305
306 # Delegate warning output to output logic, as this way it
307 # will report warnings/info only for symbols that are output
308
309 self.warnings.append(log_msg)
310 return
311
312 #
313 # Begin a new section.
314 #
315 def begin_section(self, line_no, title = SECTION_DEFAULT, dump = False):
316 if dump:
317 self.dump_section(start_new = True)
318 self.section = title
319 self.new_start_line = line_no
320
321 def dump_section(self, start_new=True):
322 """
323 Dumps section contents to arrays/hashes intended for that purpose.
324 """
325 #
326 # If we have accumulated no contents in the default ("description")
327 # section, don't bother.
328 #
329 if self.section == SECTION_DEFAULT and not self._contents:
330 return
331 name = self.section
332 contents = self.contents()
333
334 if type_param.match(name):
335 name = type_param.group(1)
336
337 self.parameterdescs[name] = contents
338 self.parameterdesc_start_lines[name] = self.new_start_line
339
340 self.new_start_line = 0
341
342 else:
343 if name in self.sections and self.sections[name] != "":
344 # Only warn on user-specified duplicate section names
345 if name != SECTION_DEFAULT:
346 self.emit_msg(self.new_start_line,
347 f"duplicate section name '{name}'")
348 # Treat as a new paragraph - add a blank line
349 self.sections[name] += '\n' + contents
350 else:
351 self.sections[name] = contents
352 self.section_start_lines[name] = self.new_start_line
353 self.new_start_line = 0
354
355# self.config.log.debug("Section: %s : %s", name, pformat(vars(self)))
356
357 if start_new:
358 self.section = SECTION_DEFAULT
359 self._contents = []
360
361python_warning = False
362
363class KernelDoc:
364 """
365 Read a C language source or header FILE and extract embedded
366 documentation comments.
367 """
368
369 # Section names
370
371 section_context = "Context"
372 section_return = "Return"
373
374 undescribed = "-- undescribed --"
375
376 def __init__(self, config, fname):
377 """Initialize internal variables"""
378
379 self.fname = fname
380 self.config = config
381
382 # Initial state for the state machines
383 self.state = state.NORMAL
384
385 # Store entry currently being processed
386 self.entry = None
387
388 # Place all potential outputs into an array
389 self.entries = []
390
391 #
392 # We need Python 3.7 for its "dicts remember the insertion
393 # order" guarantee
394 #
395 global python_warning
396 if (not python_warning and
397 sys.version_info.major == 3 and sys.version_info.minor < 7):
398
399 self.emit_msg(0,
400 'Python 3.7 or later is required for correct results')
401 python_warning = True
402
403 def emit_msg(self, ln, msg, *, warning=True):
404 """Emit a message"""
405
406 if self.entry:
407 self.entry.emit_msg(ln, msg, warning=warning)
408 return
409
410 log_msg = f"{self.fname}:{ln} {msg}"
411
412 if warning:
413 self.config.log.warning(log_msg)
414 else:
415 self.config.log.info(log_msg)
416
417 def dump_section(self, start_new=True):
418 """
419 Dumps section contents to arrays/hashes intended for that purpose.
420 """
421
422 if self.entry:
423 self.entry.dump_section(start_new)
424
425 # TODO: rename it to store_declaration after removal of kernel-doc.pl
426 def output_declaration(self, dtype, name, **args):
427 """
428 Stores the entry into an entry array.
429
430 The actual output and output filters will be handled elsewhere
431 """
432
433 item = KdocItem(name, self.fname, dtype,
434 self.entry.declaration_start_line, **args)
435 item.warnings = self.entry.warnings
436
437 # Drop empty sections
438 # TODO: improve empty sections logic to emit warnings
439 sections = self.entry.sections
440 for section in ["Description", "Return"]:
441 if section in sections and not sections[section].rstrip():
442 del sections[section]
443 item.set_sections(sections, self.entry.section_start_lines)
444 item.set_params(self.entry.parameterlist, self.entry.parameterdescs,
445 self.entry.parametertypes,
446 self.entry.parameterdesc_start_lines)
447 self.entries.append(item)
448
449 self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
450
451 def reset_state(self, ln):
452 """
453 Ancillary routine to create a new entry. It initializes all
454 variables used by the state machine.
455 """
456
457 #
458 # Flush the warnings out before we proceed further
459 #
460 if self.entry and self.entry not in self.entries:
461 for log_msg in self.entry.warnings:
462 self.config.log.warning(log_msg)
463
464 self.entry = KernelEntry(self.config, self.fname, ln)
465
466 # State flags
467 self.state = state.NORMAL
468
469 def push_parameter(self, ln, decl_type, param, dtype,
470 org_arg, declaration_name):
471 """
472 Store parameters and their descriptions at self.entry.
473 """
474
475 if self.entry.anon_struct_union and dtype == "" and param == "}":
476 return # Ignore the ending }; from anonymous struct/union
477
478 self.entry.anon_struct_union = False
479
480 param = KernRe(r'[\[\)].*').sub('', param, count=1)
481
482 #
483 # Look at various "anonymous type" cases.
484 #
485 if dtype == '':
486 if param.endswith("..."):
487 if len(param) > 3: # there is a name provided, use that
488 param = param[:-3]
489 if not self.entry.parameterdescs.get(param):
490 self.entry.parameterdescs[param] = "variable arguments"
491
492 elif (not param) or param == "void":
493 param = "void"
494 self.entry.parameterdescs[param] = "no arguments"
495
496 elif param in ["struct", "union"]:
497 # Handle unnamed (anonymous) union or struct
498 dtype = param
499 param = "{unnamed_" + param + "}"
500 self.entry.parameterdescs[param] = "anonymous\n"
501 self.entry.anon_struct_union = True
502
503 # Warn if parameter has no description
504 # (but ignore ones starting with # as these are not parameters
505 # but inline preprocessor statements)
506 if param not in self.entry.parameterdescs and not param.startswith("#"):
507 self.entry.parameterdescs[param] = self.undescribed
508
509 if "." not in param:
510 if decl_type == 'function':
511 dname = f"{decl_type} parameter"
512 else:
513 dname = f"{decl_type} member"
514
515 self.emit_msg(ln,
516 f"{dname} '{param}' not described in '{declaration_name}'")
517
518 # Strip spaces from param so that it is one continuous string on
519 # parameterlist. This fixes a problem where check_sections()
520 # cannot find a parameter like "addr[6 + 2]" because it actually
521 # appears as "addr[6", "+", "2]" on the parameter list.
522 # However, it's better to maintain the param string unchanged for
523 # output, so just weaken the string compare in check_sections()
524 # to ignore "[blah" in a parameter string.
525
526 self.entry.parameterlist.append(param)
527 org_arg = KernRe(r'\s\s+').sub(' ', org_arg)
528 self.entry.parametertypes[param] = org_arg
529
530
531 def create_parameter_list(self, ln, decl_type, args,
532 splitter, declaration_name):
533 """
534 Creates a list of parameters, storing them at self.entry.
535 """
536
537 # temporarily replace all commas inside function pointer definition
538 arg_expr = KernRe(r'(\([^\),]+),')
539 while arg_expr.search(args):
540 args = arg_expr.sub(r"\1#", args)
541
542 for arg in args.split(splitter):
543 # Ignore argument attributes
544 arg = KernRe(r'\sPOS0?\s').sub(' ', arg)
545
546 # Strip leading/trailing spaces
547 arg = arg.strip()
548 arg = KernRe(r'\s+').sub(' ', arg, count=1)
549
550 if arg.startswith('#'):
551 # Treat preprocessor directive as a typeless variable just to fill
552 # corresponding data structures "correctly". Catch it later in
553 # output_* subs.
554
555 # Treat preprocessor directive as a typeless variable
556 self.push_parameter(ln, decl_type, arg, "",
557 "", declaration_name)
558 #
559 # The pointer-to-function case.
560 #
561 elif KernRe(r'\(.+\)\s*\(').search(arg):
562 arg = arg.replace('#', ',')
563 r = KernRe(r'[^\(]+\(\*?\s*' # Everything up to "(*"
564 r'([\w\[\].]*)' # Capture the name and possible [array]
565 r'\s*\)') # Make sure the trailing ")" is there
566 if r.match(arg):
567 param = r.group(1)
568 else:
569 self.emit_msg(ln, f"Invalid param: {arg}")
570 param = arg
571 dtype = arg.replace(param, '')
572 self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name)
573 #
574 # The array-of-pointers case. Dig the parameter name out from the middle
575 # of the declaration.
576 #
577 elif KernRe(r'\(.+\)\s*\[').search(arg):
578 r = KernRe(r'[^\(]+\(\s*\*\s*' # Up to "(" and maybe "*"
579 r'([\w.]*?)' # The actual pointer name
580 r'\s*(\[\s*\w+\s*\]\s*)*\)') # The [array portion]
581 if r.match(arg):
582 param = r.group(1)
583 else:
584 self.emit_msg(ln, f"Invalid param: {arg}")
585 param = arg
586 dtype = arg.replace(param, '')
587 self.push_parameter(ln, decl_type, param, dtype, arg, declaration_name)
588 elif arg:
589 #
590 # Clean up extraneous spaces and split the string at commas; the first
591 # element of the resulting list will also include the type information.
592 #
593 arg = KernRe(r'\s*:\s*').sub(":", arg)
594 arg = KernRe(r'\s*\[').sub('[', arg)
595 args = KernRe(r'\s*,\s*').split(arg)
596 args[0] = re.sub(r'(\*+)\s*', r' \1', args[0])
597 #
598 # args[0] has a string of "type a". If "a" includes an [array]
599 # declaration, we want to not be fooled by any white space inside
600 # the brackets, so detect and handle that case specially.
601 #
602 r = KernRe(r'^([^[\]]*\s+)(.*)$')
603 if r.match(args[0]):
604 args[0] = r.group(2)
605 dtype = r.group(1)
606 else:
607 # No space in args[0]; this seems wrong but preserves previous behavior
608 dtype = ''
609
610 bitfield_re = KernRe(r'(.*?):(\w+)')
611 for param in args:
612 #
613 # For pointers, shift the star(s) from the variable name to the
614 # type declaration.
615 #
616 r = KernRe(r'^(\*+)\s*(.*)')
617 if r.match(param):
618 self.push_parameter(ln, decl_type, r.group(2),
619 f"{dtype} {r.group(1)}",
620 arg, declaration_name)
621 #
622 # Perform a similar shift for bitfields.
623 #
624 elif bitfield_re.search(param):
625 if dtype != "": # Skip unnamed bit-fields
626 self.push_parameter(ln, decl_type, bitfield_re.group(1),
627 f"{dtype}:{bitfield_re.group(2)}",
628 arg, declaration_name)
629 else:
630 self.push_parameter(ln, decl_type, param, dtype,
631 arg, declaration_name)
632
633 def check_sections(self, ln, decl_name, decl_type):
634 """
635 Check for errors inside sections, emitting warnings if not found
636 parameters are described.
637 """
638 for section in self.entry.sections:
639 if section not in self.entry.parameterlist and \
640 not known_sections.search(section):
641 if decl_type == 'function':
642 dname = f"{decl_type} parameter"
643 else:
644 dname = f"{decl_type} member"
645 self.emit_msg(ln,
646 f"Excess {dname} '{section}' description in '{decl_name}'")
647
648 def check_return_section(self, ln, declaration_name, return_type):
649 """
650 If the function doesn't return void, warns about the lack of a
651 return description.
652 """
653
654 if not self.config.wreturn:
655 return
656
657 # Ignore an empty return type (It's a macro)
658 # Ignore functions with a "void" return type (but not "void *")
659 if not return_type or KernRe(r'void\s*\w*\s*$').search(return_type):
660 return
661
662 if not self.entry.sections.get("Return", None):
663 self.emit_msg(ln,
664 f"No description found for return value of '{declaration_name}'")
665
666 #
667 # Split apart a structure prototype; returns (struct|union, name, members) or None
668 #
669 def split_struct_proto(self, proto):
670 type_pattern = r'(struct|union)'
671 qualifiers = [
672 "__attribute__",
673 "__packed",
674 "__aligned",
675 "____cacheline_aligned_in_smp",
676 "____cacheline_aligned",
677 ]
678 definition_body = r'\{(.*)\}\s*' + "(?:" + '|'.join(qualifiers) + ")?"
679
680 r = KernRe(type_pattern + r'\s+(\w+)\s*' + definition_body)
681 if r.search(proto):
682 return (r.group(1), r.group(2), r.group(3))
683 else:
684 r = KernRe(r'typedef\s+' + type_pattern + r'\s*' + definition_body + r'\s*(\w+)\s*;')
685 if r.search(proto):
686 return (r.group(1), r.group(3), r.group(2))
687 return None
688 #
689 # Rewrite the members of a structure or union for easier formatting later on.
690 # Among other things, this function will turn a member like:
691 #
692 # struct { inner_members; } foo;
693 #
694 # into:
695 #
696 # struct foo; inner_members;
697 #
698 def rewrite_struct_members(self, members):
699 #
700 # Process struct/union members from the most deeply nested outward. The
701 # trick is in the ^{ below - it prevents a match of an outer struct/union
702 # until the inner one has been munged (removing the "{" in the process).
703 #
704 struct_members = KernRe(r'(struct|union)' # 0: declaration type
705 r'([^\{\};]+)' # 1: possible name
706 r'(\{)'
707 r'([^\{\}]*)' # 3: Contents of declaration
708 r'(\})'
709 r'([^\{\};]*)(;)') # 5: Remaining stuff after declaration
710 tuples = struct_members.findall(members)
711 while tuples:
712 for t in tuples:
713 newmember = ""
714 oldmember = "".join(t) # Reconstruct the original formatting
715 dtype, name, lbr, content, rbr, rest, semi = t
716 #
717 # Pass through each field name, normalizing the form and formatting.
718 #
719 for s_id in rest.split(','):
720 s_id = s_id.strip()
721 newmember += f"{dtype} {s_id}; "
722 #
723 # Remove bitfield/array/pointer info, getting the bare name.
724 #
725 s_id = KernRe(r'[:\[].*').sub('', s_id)
726 s_id = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', s_id)
727 #
728 # Pass through the members of this inner structure/union.
729 #
730 for arg in content.split(';'):
731 arg = arg.strip()
732 #
733 # Look for (type)(*name)(args) - pointer to function
734 #
735 r = KernRe(r'^([^\(]+\(\*?\s*)([\w.]*)(\s*\).*)')
736 if r.match(arg):
737 dtype, name, extra = r.group(1), r.group(2), r.group(3)
738 # Pointer-to-function
739 if not s_id:
740 # Anonymous struct/union
741 newmember += f"{dtype}{name}{extra}; "
742 else:
743 newmember += f"{dtype}{s_id}.{name}{extra}; "
744 #
745 # Otherwise a non-function member.
746 #
747 else:
748 #
749 # Remove bitmap and array portions and spaces around commas
750 #
751 arg = KernRe(r':\s*\d+\s*').sub('', arg)
752 arg = KernRe(r'\[.*\]').sub('', arg)
753 arg = KernRe(r'\s*,\s*').sub(',', arg)
754 #
755 # Look for a normal decl - "type name[,name...]"
756 #
757 r = KernRe(r'(.*)\s+([\S+,]+)')
758 if r.search(arg):
759 for name in r.group(2).split(','):
760 name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name)
761 if not s_id:
762 # Anonymous struct/union
763 newmember += f"{r.group(1)} {name}; "
764 else:
765 newmember += f"{r.group(1)} {s_id}.{name}; "
766 else:
767 newmember += f"{arg}; "
768 #
769 # At the end of the s_id loop, replace the original declaration with
770 # the munged version.
771 #
772 members = members.replace(oldmember, newmember)
773 #
774 # End of the tuple loop - search again and see if there are outer members
775 # that now turn up.
776 #
777 tuples = struct_members.findall(members)
778 return members
779
780 #
781 # Format the struct declaration into a standard form for inclusion in the
782 # resulting docs.
783 #
784 def format_struct_decl(self, declaration):
785 #
786 # Insert newlines, get rid of extra spaces.
787 #
788 declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration)
789 declaration = KernRe(r'\}\s+;').sub('};', declaration)
790 #
791 # Format inline enums with each member on its own line.
792 #
793 r = KernRe(r'(enum\s+\{[^\}]+),([^\n])')
794 while r.search(declaration):
795 declaration = r.sub(r'\1,\n\2', declaration)
796 #
797 # Now go through and supply the right number of tabs
798 # for each line.
799 #
800 def_args = declaration.split('\n')
801 level = 1
802 declaration = ""
803 for clause in def_args:
804 clause = KernRe(r'\s+').sub(' ', clause.strip(), count=1)
805 if clause:
806 if '}' in clause and level > 1:
807 level -= 1
808 if not clause.startswith('#'):
809 declaration += "\t" * level
810 declaration += "\t" + clause + "\n"
811 if "{" in clause and "}" not in clause:
812 level += 1
813 return declaration
814
815
816 def dump_struct(self, ln, proto):
817 """
818 Store an entry for a struct or union
819 """
820 #
821 # Do the basic parse to get the pieces of the declaration.
822 #
823 struct_parts = self.split_struct_proto(proto)
824 if not struct_parts:
825 self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!")
826 return
827 decl_type, declaration_name, members = struct_parts
828
829 if self.entry.identifier != declaration_name:
830 self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
831 f"Prototype was for {decl_type} {declaration_name} instead\n")
832 return
833 #
834 # Go through the list of members applying all of our transformations.
835 #
836 members = trim_private_members(members)
837 members = apply_transforms(struct_xforms, members)
838
839 nested = NestedMatch()
840 for search, sub in struct_nested_prefixes:
841 members = nested.sub(search, sub, members)
842 #
843 # Deal with embedded struct and union members, and drop enums entirely.
844 #
845 declaration = members
846 members = self.rewrite_struct_members(members)
847 members = re.sub(r'(\{[^\{\}]*\})', '', members)
848 #
849 # Output the result and we are done.
850 #
851 self.create_parameter_list(ln, decl_type, members, ';',
852 declaration_name)
853 self.check_sections(ln, declaration_name, decl_type)
854 self.output_declaration(decl_type, declaration_name,
855 definition=self.format_struct_decl(declaration),
856 purpose=self.entry.declaration_purpose)
857
858 def dump_enum(self, ln, proto):
859 """
860 Stores an enum inside self.entries array.
861 """
862 #
863 # Strip preprocessor directives. Note that this depends on the
864 # trailing semicolon we added in process_proto_type().
865 #
866 proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
867 #
868 # Parse out the name and members of the enum. Typedef form first.
869 #
870 r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
871 if r.search(proto):
872 declaration_name = r.group(2)
873 members = trim_private_members(r.group(1))
874 #
875 # Failing that, look for a straight enum
876 #
877 else:
878 r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
879 if r.match(proto):
880 declaration_name = r.group(1)
881 members = trim_private_members(r.group(2))
882 #
883 # OK, this isn't going to work.
884 #
885 else:
886 self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
887 return
888 #
889 # Make sure we found what we were expecting.
890 #
891 if self.entry.identifier != declaration_name:
892 if self.entry.identifier == "":
893 self.emit_msg(ln,
894 f"{proto}: wrong kernel-doc identifier on prototype")
895 else:
896 self.emit_msg(ln,
897 f"expecting prototype for enum {self.entry.identifier}. "
898 f"Prototype was for enum {declaration_name} instead")
899 return
900
901 if not declaration_name:
902 declaration_name = "(anonymous)"
903 #
904 # Parse out the name of each enum member, and verify that we
905 # have a description for it.
906 #
907 member_set = set()
908 members = KernRe(r'\([^;)]*\)').sub('', members)
909 for arg in members.split(','):
910 if not arg:
911 continue
912 arg = KernRe(r'^\s*(\w+).*').sub(r'\1', arg)
913 self.entry.parameterlist.append(arg)
914 if arg not in self.entry.parameterdescs:
915 self.entry.parameterdescs[arg] = self.undescribed
916 self.emit_msg(ln,
917 f"Enum value '{arg}' not described in enum '{declaration_name}'")
918 member_set.add(arg)
919 #
920 # Ensure that every described member actually exists in the enum.
921 #
922 for k in self.entry.parameterdescs:
923 if k not in member_set:
924 self.emit_msg(ln,
925 f"Excess enum value '@{k}' description in '{declaration_name}'")
926
927 self.output_declaration('enum', declaration_name,
928 purpose=self.entry.declaration_purpose)
929
930 def dump_declaration(self, ln, prototype):
931 """
932 Stores a data declaration inside self.entries array.
933 """
934
935 if self.entry.decl_type == "enum":
936 self.dump_enum(ln, prototype)
937 elif self.entry.decl_type == "typedef":
938 self.dump_typedef(ln, prototype)
939 elif self.entry.decl_type in ["union", "struct"]:
940 self.dump_struct(ln, prototype)
941 else:
942 # This would be a bug
943 self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
944
945 def dump_function(self, ln, prototype):
946 """
947 Stores a function or function macro inside self.entries array.
948 """
949
950 found = func_macro = False
951 return_type = ''
952 decl_type = 'function'
953 #
954 # Apply the initial transformations.
955 #
956 prototype = apply_transforms(function_xforms, prototype)
957 #
958 # If we have a macro, remove the "#define" at the front.
959 #
960 new_proto = KernRe(r"^#\s*define\s+").sub("", prototype)
961 if new_proto != prototype:
962 prototype = new_proto
963 #
964 # Dispense with the simple "#define A B" case here; the key
965 # is the space after the name of the symbol being defined.
966 # NOTE that the seemingly misnamed "func_macro" indicates a
967 # macro *without* arguments.
968 #
969 r = KernRe(r'^(\w+)\s+')
970 if r.search(prototype):
971 return_type = ''
972 declaration_name = r.group(1)
973 func_macro = True
974 found = True
975
976 # Yes, this truly is vile. We are looking for:
977 # 1. Return type (may be nothing if we're looking at a macro)
978 # 2. Function name
979 # 3. Function parameters.
980 #
981 # All the while we have to watch out for function pointer parameters
982 # (which IIRC is what the two sections are for), C types (these
983 # regexps don't even start to express all the possibilities), and
984 # so on.
985 #
986 # If you mess with these regexps, it's a good idea to check that
987 # the following functions' documentation still comes out right:
988 # - parport_register_device (function pointer parameters)
989 # - atomic_set (macro)
990 # - pci_match_device, __copy_to_user (long return type)
991
992 name = r'\w+'
993 type1 = r'(?:[\w\s]+)?'
994 type2 = r'(?:[\w\s]+\*+)+'
995 #
996 # Attempt to match first on (args) with no internal parentheses; this
997 # lets us easily filter out __acquires() and other post-args stuff. If
998 # that fails, just grab the rest of the line to the last closing
999 # parenthesis.
1000 #
1001 proto_args = r'\(([^\(]*|.*)\)'
1002 #
1003 # (Except for the simple macro case) attempt to split up the prototype
1004 # in the various ways we understand.
1005 #
1006 if not found:
1007 patterns = [
1008 rf'^()({name})\s*{proto_args}',
1009 rf'^({type1})\s+({name})\s*{proto_args}',
1010 rf'^({type2})\s*({name})\s*{proto_args}',
1011 ]
1012
1013 for p in patterns:
1014 r = KernRe(p)
1015 if r.match(prototype):
1016 return_type = r.group(1)
1017 declaration_name = r.group(2)
1018 args = r.group(3)
1019 self.create_parameter_list(ln, decl_type, args, ',',
1020 declaration_name)
1021 found = True
1022 break
1023 #
1024 # Parsing done; make sure that things are as we expect.
1025 #
1026 if not found:
1027 self.emit_msg(ln,
1028 f"cannot understand function prototype: '{prototype}'")
1029 return
1030 if self.entry.identifier != declaration_name:
1031 self.emit_msg(ln, f"expecting prototype for {self.entry.identifier}(). "
1032 f"Prototype was for {declaration_name}() instead")
1033 return
1034 self.check_sections(ln, declaration_name, "function")
1035 self.check_return_section(ln, declaration_name, return_type)
1036 #
1037 # Store the result.
1038 #
1039 self.output_declaration(decl_type, declaration_name,
1040 typedef=('typedef' in return_type),
1041 functiontype=return_type,
1042 purpose=self.entry.declaration_purpose,
1043 func_macro=func_macro)
1044
1045
1046 def dump_typedef(self, ln, proto):
1047 """
1048 Stores a typedef inside self.entries array.
1049 """
1050 #
1051 # We start by looking for function typedefs.
1052 #
1053 typedef_type = r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
1054 typedef_ident = r'\*?\s*(\w\S+)\s*'
1055 typedef_args = r'\s*\((.*)\);'
1056
1057 typedef1 = KernRe(typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
1058 typedef2 = KernRe(typedef_type + typedef_ident + typedef_args)
1059
1060 # Parse function typedef prototypes
1061 for r in [typedef1, typedef2]:
1062 if not r.match(proto):
1063 continue
1064
1065 return_type = r.group(1).strip()
1066 declaration_name = r.group(2)
1067 args = r.group(3)
1068
1069 if self.entry.identifier != declaration_name:
1070 self.emit_msg(ln,
1071 f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
1072 return
1073
1074 self.create_parameter_list(ln, 'function', args, ',', declaration_name)
1075
1076 self.output_declaration('function', declaration_name,
1077 typedef=True,
1078 functiontype=return_type,
1079 purpose=self.entry.declaration_purpose)
1080 return
1081 #
1082 # Not a function, try to parse a simple typedef.
1083 #
1084 r = KernRe(r'typedef.*\s+(\w+)\s*;')
1085 if r.match(proto):
1086 declaration_name = r.group(1)
1087
1088 if self.entry.identifier != declaration_name:
1089 self.emit_msg(ln,
1090 f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
1091 return
1092
1093 self.output_declaration('typedef', declaration_name,
1094 purpose=self.entry.declaration_purpose)
1095 return
1096
1097 self.emit_msg(ln, "error: Cannot parse typedef!")
1098
1099 @staticmethod
1100 def process_export(function_set, line):
1101 """
1102 process EXPORT_SYMBOL* tags
1103
1104 This method doesn't use any variable from the class, so declare it
1105 with a staticmethod decorator.
1106 """
1107
1108 # We support documenting some exported symbols with different
1109 # names. A horrible hack.
1110 suffixes = [ '_noprof' ]
1111
1112 # Note: it accepts only one EXPORT_SYMBOL* per line, as having
1113 # multiple export lines would violate Kernel coding style.
1114
1115 if export_symbol.search(line):
1116 symbol = export_symbol.group(2)
1117 elif export_symbol_ns.search(line):
1118 symbol = export_symbol_ns.group(2)
1119 else:
1120 return False
1121 #
1122 # Found an export, trim out any special suffixes
1123 #
1124 for suffix in suffixes:
1125 # Be backward compatible with Python < 3.9
1126 if symbol.endswith(suffix):
1127 symbol = symbol[:-len(suffix)]
1128 function_set.add(symbol)
1129 return True
1130
1131 def process_normal(self, ln, line):
1132 """
1133 STATE_NORMAL: looking for the /** to begin everything.
1134 """
1135
1136 if not doc_start.match(line):
1137 return
1138
1139 # start a new entry
1140 self.reset_state(ln)
1141
1142 # next line is always the function name
1143 self.state = state.NAME
1144
1145 def process_name(self, ln, line):
1146 """
1147 STATE_NAME: Looking for the "name - description" line
1148 """
1149 #
1150 # Check for a DOC: block and handle them specially.
1151 #
1152 if doc_block.search(line):
1153
1154 if not doc_block.group(1):
1155 self.entry.begin_section(ln, "Introduction")
1156 else:
1157 self.entry.begin_section(ln, doc_block.group(1))
1158
1159 self.entry.identifier = self.entry.section
1160 self.state = state.DOCBLOCK
1161 #
1162 # Otherwise we're looking for a normal kerneldoc declaration line.
1163 #
1164 elif doc_decl.search(line):
1165 self.entry.identifier = doc_decl.group(1)
1166
1167 # Test for data declaration
1168 if doc_begin_data.search(line):
1169 self.entry.decl_type = doc_begin_data.group(1)
1170 self.entry.identifier = doc_begin_data.group(2)
1171 #
1172 # Look for a function description
1173 #
1174 elif doc_begin_func.search(line):
1175 self.entry.identifier = doc_begin_func.group(1)
1176 self.entry.decl_type = "function"
1177 #
1178 # We struck out.
1179 #
1180 else:
1181 self.emit_msg(ln,
1182 f"This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst\n{line}")
1183 self.state = state.NORMAL
1184 return
1185 #
1186 # OK, set up for a new kerneldoc entry.
1187 #
1188 self.state = state.BODY
1189 self.entry.identifier = self.entry.identifier.strip(" ")
1190 # if there's no @param blocks need to set up default section here
1191 self.entry.begin_section(ln + 1)
1192 #
1193 # Find the description portion, which *should* be there but
1194 # isn't always.
1195 # (We should be able to capture this from the previous parsing - someday)
1196 #
1197 r = KernRe("[-:](.*)")
1198 if r.search(line):
1199 self.entry.declaration_purpose = trim_whitespace(r.group(1))
1200 self.state = state.DECLARATION
1201 else:
1202 self.entry.declaration_purpose = ""
1203
1204 if not self.entry.declaration_purpose and self.config.wshort_desc:
1205 self.emit_msg(ln,
1206 f"missing initial short description on line:\n{line}")
1207
1208 if not self.entry.identifier and self.entry.decl_type != "enum":
1209 self.emit_msg(ln,
1210 f"wrong kernel-doc identifier on line:\n{line}")
1211 self.state = state.NORMAL
1212
1213 if self.config.verbose:
1214 self.emit_msg(ln,
1215 f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
1216 warning=False)
1217 #
1218 # Failed to find an identifier. Emit a warning
1219 #
1220 else:
1221 self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
1222
1223 #
1224 # Helper function to determine if a new section is being started.
1225 #
1226 def is_new_section(self, ln, line):
1227 if doc_sect.search(line):
1228 self.state = state.BODY
1229 #
1230 # Pick out the name of our new section, tweaking it if need be.
1231 #
1232 newsection = doc_sect.group(1)
1233 if newsection.lower() == 'description':
1234 newsection = 'Description'
1235 elif newsection.lower() == 'context':
1236 newsection = 'Context'
1237 self.state = state.SPECIAL_SECTION
1238 elif newsection.lower() in ["@return", "@returns",
1239 "return", "returns"]:
1240 newsection = "Return"
1241 self.state = state.SPECIAL_SECTION
1242 elif newsection[0] == '@':
1243 self.state = state.SPECIAL_SECTION
1244 #
1245 # Initialize the contents, and get the new section going.
1246 #
1247 newcontents = doc_sect.group(2)
1248 if not newcontents:
1249 newcontents = ""
1250 self.dump_section()
1251 self.entry.begin_section(ln, newsection)
1252 self.entry.leading_space = None
1253
1254 self.entry.add_text(newcontents.lstrip())
1255 return True
1256 return False
1257
1258 #
1259 # Helper function to detect (and effect) the end of a kerneldoc comment.
1260 #
1261 def is_comment_end(self, ln, line):
1262 if doc_end.search(line):
1263 self.dump_section()
1264
1265 # Look for doc_com + <text> + doc_end:
1266 r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/')
1267 if r.match(line):
1268 self.emit_msg(ln, f"suspicious ending line: {line}")
1269
1270 self.entry.prototype = ""
1271 self.entry.new_start_line = ln + 1
1272
1273 self.state = state.PROTO
1274 return True
1275 return False
1276
1277
1278 def process_decl(self, ln, line):
1279 """
1280 STATE_DECLARATION: We've seen the beginning of a declaration
1281 """
1282 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1283 return
1284 #
1285 # Look for anything with the " * " line beginning.
1286 #
1287 if doc_content.search(line):
1288 cont = doc_content.group(1)
1289 #
1290 # A blank line means that we have moved out of the declaration
1291 # part of the comment (without any "special section" parameter
1292 # descriptions).
1293 #
1294 if cont == "":
1295 self.state = state.BODY
1296 #
1297 # Otherwise we have more of the declaration section to soak up.
1298 #
1299 else:
1300 self.entry.declaration_purpose = \
1301 trim_whitespace(self.entry.declaration_purpose + ' ' + cont)
1302 else:
1303 # Unknown line, ignore
1304 self.emit_msg(ln, f"bad line: {line}")
1305
1306
1307 def process_special(self, ln, line):
1308 """
1309 STATE_SPECIAL_SECTION: a section ending with a blank line
1310 """
1311 #
1312 # If we have hit a blank line (only the " * " marker), then this
1313 # section is done.
1314 #
1315 if KernRe(r"\s*\*\s*$").match(line):
1316 self.entry.begin_section(ln, dump = True)
1317 self.state = state.BODY
1318 return
1319 #
1320 # Not a blank line, look for the other ways to end the section.
1321 #
1322 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1323 return
1324 #
1325 # OK, we should have a continuation of the text for this section.
1326 #
1327 if doc_content.search(line):
1328 cont = doc_content.group(1)
1329 #
1330 # If the lines of text after the first in a special section have
1331 # leading white space, we need to trim it out or Sphinx will get
1332 # confused. For the second line (the None case), see what we
1333 # find there and remember it.
1334 #
1335 if self.entry.leading_space is None:
1336 r = KernRe(r'^(\s+)')
1337 if r.match(cont):
1338 self.entry.leading_space = len(r.group(1))
1339 else:
1340 self.entry.leading_space = 0
1341 #
1342 # Otherwise, before trimming any leading chars, be *sure*
1343 # that they are white space. We should maybe warn if this
1344 # isn't the case.
1345 #
1346 for i in range(0, self.entry.leading_space):
1347 if cont[i] != " ":
1348 self.entry.leading_space = i
1349 break
1350 #
1351 # Add the trimmed result to the section and we're done.
1352 #
1353 self.entry.add_text(cont[self.entry.leading_space:])
1354 else:
1355 # Unknown line, ignore
1356 self.emit_msg(ln, f"bad line: {line}")
1357
1358 def process_body(self, ln, line):
1359 """
1360 STATE_BODY: the bulk of a kerneldoc comment.
1361 """
1362 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1363 return
1364
1365 if doc_content.search(line):
1366 cont = doc_content.group(1)
1367 self.entry.add_text(cont)
1368 else:
1369 # Unknown line, ignore
1370 self.emit_msg(ln, f"bad line: {line}")
1371
1372 def process_inline_name(self, ln, line):
1373 """STATE_INLINE_NAME: beginning of docbook comments within a prototype."""
1374
1375 if doc_inline_sect.search(line):
1376 self.entry.begin_section(ln, doc_inline_sect.group(1))
1377 self.entry.add_text(doc_inline_sect.group(2).lstrip())
1378 self.state = state.INLINE_TEXT
1379 elif doc_inline_end.search(line):
1380 self.dump_section()
1381 self.state = state.PROTO
1382 elif doc_content.search(line):
1383 self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
1384 self.state = state.PROTO
1385 # else ... ??
1386
1387 def process_inline_text(self, ln, line):
1388 """STATE_INLINE_TEXT: docbook comments within a prototype."""
1389
1390 if doc_inline_end.search(line):
1391 self.dump_section()
1392 self.state = state.PROTO
1393 elif doc_content.search(line):
1394 self.entry.add_text(doc_content.group(1))
1395 # else ... ??
1396
1397 def syscall_munge(self, ln, proto): # pylint: disable=W0613
1398 """
1399 Handle syscall definitions
1400 """
1401
1402 is_void = False
1403
1404 # Strip newlines/CR's
1405 proto = re.sub(r'[\r\n]+', ' ', proto)
1406
1407 # Check if it's a SYSCALL_DEFINE0
1408 if 'SYSCALL_DEFINE0' in proto:
1409 is_void = True
1410
1411 # Replace SYSCALL_DEFINE with correct return type & function name
1412 proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
1413
1414 r = KernRe(r'long\s+(sys_.*?),')
1415 if r.search(proto):
1416 proto = KernRe(',').sub('(', proto, count=1)
1417 elif is_void:
1418 proto = KernRe(r'\)').sub('(void)', proto, count=1)
1419
1420 # Now delete all of the odd-numbered commas in the proto
1421 # so that argument types & names don't have a comma between them
1422 count = 0
1423 length = len(proto)
1424
1425 if is_void:
1426 length = 0 # skip the loop if is_void
1427
1428 for ix in range(length):
1429 if proto[ix] == ',':
1430 count += 1
1431 if count % 2 == 1:
1432 proto = proto[:ix] + ' ' + proto[ix + 1:]
1433
1434 return proto
1435
1436 def tracepoint_munge(self, ln, proto):
1437 """
1438 Handle tracepoint definitions
1439 """
1440
1441 tracepointname = None
1442 tracepointargs = None
1443
1444 # Match tracepoint name based on different patterns
1445 r = KernRe(r'TRACE_EVENT\((.*?),')
1446 if r.search(proto):
1447 tracepointname = r.group(1)
1448
1449 r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
1450 if r.search(proto):
1451 tracepointname = r.group(1)
1452
1453 r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
1454 if r.search(proto):
1455 tracepointname = r.group(2)
1456
1457 if tracepointname:
1458 tracepointname = tracepointname.lstrip()
1459
1460 r = KernRe(r'TP_PROTO\((.*?)\)')
1461 if r.search(proto):
1462 tracepointargs = r.group(1)
1463
1464 if not tracepointname or not tracepointargs:
1465 self.emit_msg(ln,
1466 f"Unrecognized tracepoint format:\n{proto}\n")
1467 else:
1468 proto = f"static inline void trace_{tracepointname}({tracepointargs})"
1469 self.entry.identifier = f"trace_{self.entry.identifier}"
1470
1471 return proto
1472
1473 def process_proto_function(self, ln, line):
1474 """Ancillary routine to process a function prototype"""
1475
1476 # strip C99-style comments to end of line
1477 line = KernRe(r"//.*$", re.S).sub('', line)
1478 #
1479 # Soak up the line's worth of prototype text, stopping at { or ; if present.
1480 #
1481 if KernRe(r'\s*#\s*define').match(line):
1482 self.entry.prototype = line
1483 elif not line.startswith('#'): # skip other preprocessor stuff
1484 r = KernRe(r'([^\{]*)')
1485 if r.match(line):
1486 self.entry.prototype += r.group(1) + " "
1487 #
1488 # If we now have the whole prototype, clean it up and declare victory.
1489 #
1490 if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(line):
1491 # strip comments and surrounding spaces
1492 self.entry.prototype = KernRe(r'/\*.*\*/').sub('', self.entry.prototype).strip()
1493 #
1494 # Handle self.entry.prototypes for function pointers like:
1495 # int (*pcs_config)(struct foo)
1496 # by turning it into
1497 # int pcs_config(struct foo)
1498 #
1499 r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
1500 self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
1501 #
1502 # Handle special declaration syntaxes
1503 #
1504 if 'SYSCALL_DEFINE' in self.entry.prototype:
1505 self.entry.prototype = self.syscall_munge(ln,
1506 self.entry.prototype)
1507 else:
1508 r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
1509 if r.search(self.entry.prototype):
1510 self.entry.prototype = self.tracepoint_munge(ln,
1511 self.entry.prototype)
1512 #
1513 # ... and we're done
1514 #
1515 self.dump_function(ln, self.entry.prototype)
1516 self.reset_state(ln)
1517
1518 def process_proto_type(self, ln, line):
1519 """Ancillary routine to process a type"""
1520
1521 # Strip C99-style comments and surrounding whitespace
1522 line = KernRe(r"//.*$", re.S).sub('', line).strip()
1523 if not line:
1524 return # nothing to see here
1525
1526 # To distinguish preprocessor directive from regular declaration later.
1527 if line.startswith('#'):
1528 line += ";"
1529 #
1530 # Split the declaration on any of { } or ;, and accumulate pieces
1531 # until we hit a semicolon while not inside {brackets}
1532 #
1533 r = KernRe(r'(.*?)([{};])')
1534 for chunk in r.split(line):
1535 if chunk: # Ignore empty matches
1536 self.entry.prototype += chunk
1537 #
1538 # This cries out for a match statement ... someday after we can
1539 # drop Python 3.9 ...
1540 #
1541 if chunk == '{':
1542 self.entry.brcount += 1
1543 elif chunk == '}':
1544 self.entry.brcount -= 1
1545 elif chunk == ';' and self.entry.brcount <= 0:
1546 self.dump_declaration(ln, self.entry.prototype)
1547 self.reset_state(ln)
1548 return
1549 #
1550 # We hit the end of the line while still in the declaration; put
1551 # in a space to represent the newline.
1552 #
1553 self.entry.prototype += ' '
1554
1555 def process_proto(self, ln, line):
1556 """STATE_PROTO: reading a function/whatever prototype."""
1557
1558 if doc_inline_oneline.search(line):
1559 self.entry.begin_section(ln, doc_inline_oneline.group(1))
1560 self.entry.add_text(doc_inline_oneline.group(2))
1561 self.dump_section()
1562
1563 elif doc_inline_start.search(line):
1564 self.state = state.INLINE_NAME
1565
1566 elif self.entry.decl_type == 'function':
1567 self.process_proto_function(ln, line)
1568
1569 else:
1570 self.process_proto_type(ln, line)
1571
1572 def process_docblock(self, ln, line):
1573 """STATE_DOCBLOCK: within a DOC: block."""
1574
1575 if doc_end.search(line):
1576 self.dump_section()
1577 self.output_declaration("doc", self.entry.identifier)
1578 self.reset_state(ln)
1579
1580 elif doc_content.search(line):
1581 self.entry.add_text(doc_content.group(1))
1582
1583 def parse_export(self):
1584 """
1585 Parses EXPORT_SYMBOL* macros from a single Kernel source file.
1586 """
1587
1588 export_table = set()
1589
1590 try:
1591 with open(self.fname, "r", encoding="utf8",
1592 errors="backslashreplace") as fp:
1593
1594 for line in fp:
1595 self.process_export(export_table, line)
1596
1597 except IOError:
1598 return None
1599
1600 return export_table
1601
1602 #
1603 # The state/action table telling us which function to invoke in
1604 # each state.
1605 #
1606 state_actions = {
1607 state.NORMAL: process_normal,
1608 state.NAME: process_name,
1609 state.BODY: process_body,
1610 state.DECLARATION: process_decl,
1611 state.SPECIAL_SECTION: process_special,
1612 state.INLINE_NAME: process_inline_name,
1613 state.INLINE_TEXT: process_inline_text,
1614 state.PROTO: process_proto,
1615 state.DOCBLOCK: process_docblock,
1616 }
1617
1618 def parse_kdoc(self):
1619 """
1620 Open and process each line of a C source file.
1621 The parsing is controlled via a state machine, and the line is passed
1622 to a different process function depending on the state. The process
1623 function may update the state as needed.
1624
1625 Besides parsing kernel-doc tags, it also parses export symbols.
1626 """
1627
1628 prev = ""
1629 prev_ln = None
1630 export_table = set()
1631
1632 try:
1633 with open(self.fname, "r", encoding="utf8",
1634 errors="backslashreplace") as fp:
1635 for ln, line in enumerate(fp):
1636
1637 line = line.expandtabs().strip("\n")
1638
1639 # Group continuation lines on prototypes
1640 if self.state == state.PROTO:
1641 if line.endswith("\\"):
1642 prev += line.rstrip("\\")
1643 if not prev_ln:
1644 prev_ln = ln
1645 continue
1646
1647 if prev:
1648 ln = prev_ln
1649 line = prev + line
1650 prev = ""
1651 prev_ln = None
1652
1653 self.config.log.debug("%d %s: %s",
1654 ln, state.name[self.state],
1655 line)
1656
1657 # This is an optimization over the original script.
1658 # There, when export_file was used for the same file,
1659 # it was read twice. Here, we use the already-existing
1660 # loop to parse exported symbols as well.
1661 #
1662 if (self.state != state.NORMAL) or \
1663 not self.process_export(export_table, line):
1664 # Hand this line to the appropriate state handler
1665 self.state_actions[self.state](self, ln, line)
1666
1667 except OSError:
1668 self.config.log.error(f"Error: Cannot open file {self.fname}")
1669
1670 return export_table, self.entries