projects/linux·blob uaccess-cleanups · refs

1779 lines · 64.9 KiB

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