projects/linux·blob master · refs

1782 lines · 65.0 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
835 #
836 # Expand macro-based declarations, like context_lock_struct(),
837 # into a plain struct/union declaration before splitting it,
838 # as dump_var() and dump_function() already do.
839 #
840 proto = self.xforms.apply("struct", proto)
841 struct_parts = self.split_struct_proto(proto)
842 if not struct_parts:
843 self.emit_msg(ln, f"{proto} error: Cannot parse struct or union!")
844 return
845 decl_type, declaration_name, members = struct_parts
846
847 if self.entry.identifier != declaration_name:
848 self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
849 f"Prototype was for {decl_type} {declaration_name} instead")
850 return
851
852 #
853 # Deal with embedded struct and union members, and drop enums entirely.
854 #
855 declaration = members
856 members = self.rewrite_struct_members(members)
857 members = re.sub(r'(\{[^\{\}]*\})', '', members)
858 #
859 # Output the result and we are done.
860 #
861 self.create_parameter_list(ln, decl_type, members, ';',
862 declaration_name)
863 self.check_sections(ln, declaration_name, decl_type)
864 self.output_declaration(decl_type, declaration_name,
865 source=source,
866 definition=self.format_struct_decl(declaration),
867 purpose=self.entry.declaration_purpose)
868
869 def dump_enum(self, ln, proto, source):
870 """
871 Store an ``enum`` inside self.entries array.
872 """
873 #
874 # Strip preprocessor directives. Note that this depends on the
875 # trailing semicolon we added in process_proto_type().
876 #
877 source = source
878 proto = trim_private_members(proto)
879 proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;', flags=re.S).sub('', proto)
880 #
881 # Parse out the name and members of the enum. Typedef form first.
882 #
883 r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
884 if r.search(proto):
885 declaration_name = r.group(2)
886 members = r.group(1)
887 #
888 # Failing that, look for a straight enum
889 #
890 else:
891 r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
892 if r.match(proto):
893 declaration_name = r.group(1)
894 members = r.group(2)
895 #
896 # OK, this isn't going to work.
897 #
898 else:
899 self.emit_msg(ln, f"{proto}: error: Cannot parse enum!")
900 return
901 #
902 # Make sure we found what we were expecting.
903 #
904 if self.entry.identifier != declaration_name:
905 if self.entry.identifier == "":
906 self.emit_msg(ln,
907 f"{proto}: wrong kernel-doc identifier on prototype")
908 else:
909 self.emit_msg(ln,
910 f"expecting prototype for enum {self.entry.identifier}. "
911 f"Prototype was for enum {declaration_name} instead")
912 return
913
914 if not declaration_name:
915 declaration_name = "(anonymous)"
916 #
917 # Parse out the name of each enum member, and verify that we
918 # have a description for it.
919 #
920 member_set = set()
921 members = KernRe(r'\([^;)]*\)').sub('', members)
922 for arg in members.split(','):
923 arg = KernRe(r'^\s*(\w+).*').sub(r'\1', arg)
924 if not arg.strip():
925 continue
926
927 self.entry.parameterlist.append(arg)
928 if arg not in self.entry.parameterdescs:
929 self.entry.parameterdescs[arg] = self.undescribed
930 self.emit_msg(ln,
931 f"Enum value '{arg}' not described in enum '{declaration_name}'")
932 member_set.add(arg)
933 #
934 # Ensure that every described member actually exists in the enum.
935 #
936 for k in self.entry.parameterdescs:
937 if k not in member_set:
938 self.emit_msg(ln,
939 f"Excess enum value '@{k}' description in '{declaration_name}'")
940
941 self.output_declaration('enum', declaration_name,
942 source=source,
943 purpose=self.entry.declaration_purpose)
944
945 def dump_var(self, ln, proto, source):
946 """
947 Store variables that are part of kAPI.
948 """
949 VAR_ATTRIBS = [
950 "extern",
951 "const",
952 ]
953 OPTIONAL_VAR_ATTR = r"^(?:\b(?:" +"|".join(VAR_ATTRIBS) +r")\b\s*)*"
954
955 #
956 # Store the full prototype before modifying it
957 #
958 source = source
959 full_proto = proto
960 declaration_name = None
961
962 #
963 # Handle macro definitions
964 #
965 macro_prefixes = [
966 KernRe(r"DEFINE_[\w_]+\s*\(([\w_]+)\)"),
967 ]
968
969 for r in macro_prefixes:
970 match = r.search(proto)
971 if match:
972 declaration_name = match.group(1)
973 break
974
975 #
976 # Drop comments and macros to have a pure C prototype
977 #
978 if not declaration_name:
979 proto = self.xforms.apply("var", proto)
980
981 proto = proto.rstrip()
982
983 #
984 # Variable name is at the end of the declaration
985 #
986
987 default_val = None
988
989 r= KernRe(OPTIONAL_VAR_ATTR + r"\s*[\w_\s]*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?")
990 if r.match(proto):
991 if not declaration_name:
992 declaration_name = r.group(1)
993
994 default_val = r.group(2)
995 else:
996 r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_\s]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
997
998 if r.match(proto):
999 default_val = r.group(1)
1000 if not declaration_name:
1001 self.emit_msg(ln,f"{proto}: can't parse variable")
1002 return
1003
1004 if default_val:
1005 default_val = default_val.lstrip("=").strip()
1006
1007 self.output_declaration("var", declaration_name,
1008 source=source,
1009 full_proto=full_proto,
1010 default_val=default_val,
1011 purpose=self.entry.declaration_purpose)
1012
1013 def dump_declaration(self, ln, prototype, source):
1014 """
1015 Store a data declaration inside self.entries array.
1016 """
1017
1018 if self.entry.decl_type == "enum":
1019 self.dump_enum(ln, prototype, source)
1020 elif self.entry.decl_type == "typedef":
1021 self.dump_typedef(ln, prototype, source)
1022 elif self.entry.decl_type in ["union", "struct"]:
1023 self.dump_struct(ln, prototype, source)
1024 elif self.entry.decl_type == "var":
1025 self.dump_var(ln, prototype, source)
1026 else:
1027 # This would be a bug
1028 self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
1029
1030 def dump_function(self, ln, prototype, source):
1031 """
1032 Store a function or function macro inside self.entries array.
1033 """
1034
1035 source = source
1036 found = func_macro = False
1037 return_type = ''
1038 decl_type = 'function'
1039
1040 #
1041 # If we have a macro, remove the "#define" at the front.
1042 #
1043 new_proto = KernRe(r"^#\s*define\s+").sub("", prototype)
1044 if new_proto != prototype:
1045 prototype = new_proto
1046 #
1047 # Dispense with the simple "#define A B" case here; the key
1048 # is the space after the name of the symbol being defined.
1049 # NOTE that the seemingly misnamed "func_macro" indicates a
1050 # macro *without* arguments.
1051 #
1052 r = KernRe(r'^(\w+)\s+')
1053 if r.search(prototype):
1054 return_type = ''
1055 declaration_name = r.group(1)
1056 func_macro = True
1057 found = True
1058 else:
1059 #
1060 # Apply the initial transformations.
1061 #
1062 prototype = self.xforms.apply("func", prototype)
1063
1064 # Yes, this truly is vile. We are looking for:
1065 # 1. Return type (may be nothing if we're looking at a macro)
1066 # 2. Function name
1067 # 3. Function parameters.
1068 #
1069 # All the while we have to watch out for function pointer parameters
1070 # (which IIRC is what the two sections are for), C types (these
1071 # regexps don't even start to express all the possibilities), and
1072 # so on.
1073 #
1074 # If you mess with these regexps, it's a good idea to check that
1075 # the following functions' documentation still comes out right:
1076 # - parport_register_device (function pointer parameters)
1077 # - atomic_set (macro)
1078 # - pci_match_device, __copy_to_user (long return type)
1079
1080 name = r'\w+'
1081 type1 = r'(?:[\w\s]+)?'
1082 type2 = r'(?:[\w\s]+\*+)+'
1083 #
1084 # Attempt to match first on (args) with no internal parentheses; this
1085 # lets us easily filter out __acquires() and other post-args stuff. If
1086 # that fails, just grab the rest of the line to the last closing
1087 # parenthesis.
1088 #
1089 proto_args = r'\(([^\(]*|.*)\)'
1090 #
1091 # (Except for the simple macro case) attempt to split up the prototype
1092 # in the various ways we understand.
1093 #
1094 if not found:
1095 patterns = [
1096 rf'^()({name})\s*{proto_args}',
1097 rf'^({type1})\s+({name})\s*{proto_args}',
1098 rf'^({type2})\s*({name})\s*{proto_args}',
1099 ]
1100
1101 for p in patterns:
1102 r = KernRe(p)
1103 if r.match(prototype):
1104 return_type = r.group(1)
1105 declaration_name = r.group(2)
1106 args = r.group(3)
1107 self.create_parameter_list(ln, decl_type, args, ',',
1108 declaration_name)
1109 found = True
1110 break
1111 #
1112 # Parsing done; make sure that things are as we expect.
1113 #
1114 if not found:
1115 self.emit_msg(ln,
1116 f"cannot understand function prototype: '{prototype}'")
1117 return
1118 if self.entry.identifier != declaration_name:
1119 self.emit_msg(ln, f"expecting prototype for {self.entry.identifier}(). "
1120 f"Prototype was for {declaration_name}() instead")
1121 return
1122 self.check_sections(ln, declaration_name, "function")
1123 self.check_return_section(ln, declaration_name, return_type)
1124 #
1125 # Store the result.
1126 #
1127 self.output_declaration(decl_type, declaration_name,
1128 source=source,
1129 typedef=('typedef' in return_type),
1130 functiontype=return_type,
1131 purpose=self.entry.declaration_purpose,
1132 func_macro=func_macro)
1133
1134
1135 def dump_typedef(self, ln, proto, source):
1136 """
1137 Store a ``typedef`` inside self.entries array.
1138 """
1139 #
1140 # We start by looking for function typedefs.
1141 #
1142 typedef_type = r'typedef((?:\s+[\w*]+\b){0,7}\s+(?:\w+\b|\*+))\s*'
1143 typedef_ident = r'\*?\s*(\w\S+)\s*'
1144 typedef_args = r'\s*\((.*)\);'
1145
1146 source = source
1147
1148 typedef1 = KernRe(typedef_type + r'\(' + typedef_ident + r'\)' + typedef_args)
1149 typedef2 = KernRe(typedef_type + typedef_ident + typedef_args)
1150
1151 # Parse function typedef prototypes
1152 for r in [typedef1, typedef2]:
1153 if not r.match(proto):
1154 continue
1155
1156 return_type = r.group(1).strip()
1157 declaration_name = r.group(2)
1158 args = r.group(3)
1159
1160 if self.entry.identifier != declaration_name:
1161 self.emit_msg(ln,
1162 f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
1163 return
1164
1165 self.create_parameter_list(ln, 'function', args, ',', declaration_name)
1166
1167 self.output_declaration('function', declaration_name,
1168 source=source,
1169 typedef=True,
1170 functiontype=return_type,
1171 purpose=self.entry.declaration_purpose)
1172 return
1173 #
1174 # Not a function, try to parse a simple typedef.
1175 #
1176 r = KernRe(r'typedef.*\s+(\w+)\s*;')
1177 if r.match(proto):
1178 declaration_name = r.group(1)
1179
1180 if self.entry.identifier != declaration_name:
1181 self.emit_msg(ln,
1182 f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
1183 return
1184
1185 self.output_declaration('typedef', declaration_name,
1186 source=source,
1187 purpose=self.entry.declaration_purpose)
1188 return
1189
1190 self.emit_msg(ln, "error: Cannot parse typedef!")
1191
1192 @staticmethod
1193 def process_export(function_set, line):
1194 """
1195 process ``EXPORT_SYMBOL*`` tags
1196
1197 This method doesn't use any variable from the class, so declare it
1198 with a staticmethod decorator.
1199 """
1200
1201 # We support documenting some exported symbols with different
1202 # names. A horrible hack.
1203 suffixes = [ '_noprof' ]
1204
1205 # Note: it accepts only one EXPORT_SYMBOL* per line, as having
1206 # multiple export lines would violate Kernel coding style.
1207
1208 if export_symbol.search(line):
1209 symbol = export_symbol.group(2)
1210 elif export_symbol_ns.search(line):
1211 symbol = export_symbol_ns.group(2)
1212 else:
1213 return False
1214 #
1215 # Found an export, trim out any special suffixes
1216 #
1217 for suffix in suffixes:
1218 # Be backward compatible with Python < 3.9
1219 if symbol.endswith(suffix):
1220 symbol = symbol[:-len(suffix)]
1221 function_set.add(symbol)
1222 return True
1223
1224 def process_normal(self, ln, line, source):
1225 """
1226 STATE_NORMAL: looking for the ``/**`` to begin everything.
1227 """
1228
1229 if not doc_start.match(line):
1230 return
1231
1232 # start a new entry
1233 self.reset_state(ln)
1234
1235 # next line is always the function name
1236 self.state = state.NAME
1237
1238 def process_name(self, ln, line, source):
1239 """
1240 STATE_NAME: Looking for the "name - description" line
1241 """
1242 #
1243 # Check for a DOC: block and handle them specially.
1244 #
1245 if doc_block.search(line):
1246
1247 if not doc_block.group(1):
1248 self.entry.begin_section(ln, "Introduction")
1249 else:
1250 self.entry.begin_section(ln, doc_block.group(1))
1251
1252 self.entry.identifier = self.entry.section
1253 self.state = state.DOCBLOCK
1254 #
1255 # Otherwise we're looking for a normal kerneldoc declaration line.
1256 #
1257 elif doc_decl.search(line):
1258 self.entry.identifier = doc_decl.group(1)
1259
1260 # Test for data declaration
1261 if doc_begin_data.search(line):
1262 self.entry.decl_type = doc_begin_data.group(1)
1263 self.entry.identifier = doc_begin_data.group(2)
1264 #
1265 # Look for a function description
1266 #
1267 elif doc_begin_func.search(line):
1268 self.entry.identifier = doc_begin_func.group(1)
1269 self.entry.decl_type = "function"
1270 #
1271 # We struck out.
1272 #
1273 else:
1274 self.emit_msg(ln,
1275 f"This comment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-doc.rst\n{line}")
1276 self.state = state.NORMAL
1277 return
1278 #
1279 # OK, set up for a new kerneldoc entry.
1280 #
1281 self.state = state.BODY
1282 self.entry.identifier = self.entry.identifier.strip(" ")
1283 # if there's no @param blocks need to set up default section here
1284 self.entry.begin_section(ln + 1)
1285 #
1286 # Find the description portion, which *should* be there but
1287 # isn't always.
1288 # (We should be able to capture this from the previous parsing - someday)
1289 #
1290 r = KernRe("[-:](.*)")
1291 if r.search(line):
1292 self.entry.declaration_purpose = trim_whitespace(r.group(1))
1293 self.state = state.DECLARATION
1294 else:
1295 self.entry.declaration_purpose = ""
1296
1297 if not self.entry.declaration_purpose and self.config.wshort_desc:
1298 self.emit_msg(ln,
1299 f"missing initial short description on line:\n{line}")
1300
1301 if not self.entry.identifier and self.entry.decl_type != "enum":
1302 self.emit_msg(ln,
1303 f"wrong kernel-doc identifier on line:\n{line}")
1304 self.state = state.NORMAL
1305
1306 if self.config.verbose:
1307 self.emit_msg(ln,
1308 f"Scanning doc for {self.entry.decl_type} {self.entry.identifier}",
1309 warning=False)
1310 #
1311 # Failed to find an identifier. Emit a warning
1312 #
1313 else:
1314 self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
1315
1316 def is_new_section(self, ln, line):
1317 """
1318 Helper function to determine if a new section is being started.
1319 """
1320 if doc_sect.search(line):
1321 self.state = state.BODY
1322 #
1323 # Pick out the name of our new section, tweaking it if need be.
1324 #
1325 newsection = doc_sect.group(1)
1326 if newsection.lower() == 'description':
1327 newsection = 'Description'
1328 elif newsection.lower() == 'context':
1329 newsection = 'Context'
1330 self.state = state.SPECIAL_SECTION
1331 elif newsection.lower() in ["@return", "@returns",
1332 "return", "returns"]:
1333 newsection = "Return"
1334 self.state = state.SPECIAL_SECTION
1335 elif newsection[0] == '@':
1336 self.state = state.SPECIAL_SECTION
1337 #
1338 # Initialize the contents, and get the new section going.
1339 #
1340 newcontents = doc_sect.group(2)
1341 if not newcontents:
1342 newcontents = ""
1343 self.dump_section()
1344 self.entry.begin_section(ln, newsection)
1345 self.entry.leading_space = None
1346
1347 self.entry.add_text(newcontents.lstrip())
1348 return True
1349 return False
1350
1351 def is_comment_end(self, ln, line):
1352 """
1353 Helper function to detect (and effect) the end of a kerneldoc comment.
1354 """
1355 if doc_end.search(line):
1356 self.dump_section()
1357
1358 # Look for doc_com + <text> + doc_end:
1359 r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/')
1360 if r.match(line):
1361 self.emit_msg(ln, f"suspicious ending line: {line}")
1362
1363 self.entry.prototype = ""
1364 self.entry.new_start_line = ln + 1
1365
1366 self.state = state.PROTO
1367 return True
1368 return False
1369
1370
1371 def process_decl(self, ln, line, source):
1372 """
1373 STATE_DECLARATION: We've seen the beginning of a declaration.
1374 """
1375 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1376 return
1377 #
1378 # Look for anything with the " * " line beginning.
1379 #
1380 if doc_content.search(line):
1381 cont = doc_content.group(1)
1382 #
1383 # A blank line means that we have moved out of the declaration
1384 # part of the comment (without any "special section" parameter
1385 # descriptions).
1386 #
1387 if cont == "":
1388 self.state = state.BODY
1389 #
1390 # Otherwise we have more of the declaration section to soak up.
1391 #
1392 else:
1393 self.entry.declaration_purpose = \
1394 trim_whitespace(self.entry.declaration_purpose + ' ' + cont)
1395 else:
1396 # Unknown line, ignore
1397 self.emit_msg(ln, f"bad line: {line}")
1398
1399
1400 def process_special(self, ln, line, source):
1401 """
1402 STATE_SPECIAL_SECTION: a section ending with a blank line.
1403 """
1404 #
1405 # If we have hit a blank line (only the " * " marker), then this
1406 # section is done.
1407 #
1408 if KernRe(r"\s*\*\s*$").match(line):
1409 self.entry.begin_section(ln, dump = True)
1410 self.state = state.BODY
1411 return
1412 #
1413 # Not a blank line, look for the other ways to end the section.
1414 #
1415 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1416 return
1417 #
1418 # OK, we should have a continuation of the text for this section.
1419 #
1420 if doc_content.search(line):
1421 cont = doc_content.group(1)
1422 #
1423 # If the lines of text after the first in a special section have
1424 # leading white space, we need to trim it out or Sphinx will get
1425 # confused. For the second line (the None case), see what we
1426 # find there and remember it.
1427 #
1428 if self.entry.leading_space is None:
1429 r = KernRe(r'^(\s+)')
1430 if r.match(cont):
1431 self.entry.leading_space = len(r.group(1))
1432 else:
1433 self.entry.leading_space = 0
1434 #
1435 # Otherwise, before trimming any leading chars, be *sure*
1436 # that they are white space. We should maybe warn if this
1437 # isn't the case.
1438 #
1439 for i in range(0, self.entry.leading_space):
1440 if cont[i] != " ":
1441 self.entry.leading_space = i
1442 break
1443 #
1444 # Add the trimmed result to the section and we're done.
1445 #
1446 self.entry.add_text(cont[self.entry.leading_space:])
1447 else:
1448 # Unknown line, ignore
1449 self.emit_msg(ln, f"bad line: {line}")
1450
1451 def process_body(self, ln, line, source):
1452 """
1453 STATE_BODY: the bulk of a kerneldoc comment.
1454 """
1455 if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1456 return
1457
1458 if doc_content.search(line):
1459 cont = doc_content.group(1)
1460 self.entry.add_text(cont)
1461 else:
1462 # Unknown line, ignore
1463 self.emit_msg(ln, f"bad line: {line}")
1464
1465 def process_inline_name(self, ln, line, source):
1466 """STATE_INLINE_NAME: beginning of docbook comments within a prototype."""
1467
1468 if doc_inline_sect.search(line):
1469 self.entry.begin_section(ln, doc_inline_sect.group(1))
1470 self.entry.add_text(doc_inline_sect.group(2).lstrip())
1471 self.state = state.INLINE_TEXT
1472 elif doc_inline_end.search(line):
1473 self.dump_section()
1474 self.state = state.PROTO
1475 elif doc_content.search(line):
1476 self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
1477 self.state = state.PROTO
1478
1479 #
1480 # Don't let it add partial comments at the code, as breaks the
1481 # logic meant to remove comments from prototypes.
1482 #
1483 self.process_proto_type(ln, "/**\n" + line, source)
1484 # else ... ??
1485
1486 def process_inline_text(self, ln, line, source):
1487 """STATE_INLINE_TEXT: docbook comments within a prototype."""
1488
1489 if doc_inline_end.search(line):
1490 self.dump_section()
1491 self.state = state.PROTO
1492 elif doc_content.search(line):
1493 self.entry.add_text(doc_content.group(1))
1494 # else ... ??
1495
1496 def syscall_munge(self, ln, proto): # pylint: disable=W0613
1497 """
1498 Handle syscall definitions.
1499 """
1500
1501 is_void = False
1502
1503 # Strip newlines/CR's
1504 proto = re.sub(r'[\r\n]+', ' ', proto)
1505
1506 # Check if it's a SYSCALL_DEFINE0
1507 if 'SYSCALL_DEFINE0' in proto:
1508 is_void = True
1509
1510 # Replace SYSCALL_DEFINE with correct return type & function name
1511 proto = KernRe(r'SYSCALL_DEFINE.*\(').sub('long sys_', proto)
1512
1513 r = KernRe(r'long\s+(sys_.*?),')
1514 if r.search(proto):
1515 proto = KernRe(',').sub('(', proto, count=1)
1516 elif is_void:
1517 proto = KernRe(r'\)').sub('(void)', proto, count=1)
1518
1519 # Now delete all of the odd-numbered commas in the proto
1520 # so that argument types & names don't have a comma between them
1521 count = 0
1522 length = len(proto)
1523
1524 if is_void:
1525 length = 0 # skip the loop if is_void
1526
1527 for ix in range(length):
1528 if proto[ix] == ',':
1529 count += 1
1530 if count % 2 == 1:
1531 proto = proto[:ix] + ' ' + proto[ix + 1:]
1532
1533 return proto
1534
1535 def tracepoint_munge(self, ln, proto):
1536 """
1537 Handle tracepoint definitions.
1538 """
1539
1540 tracepointname = None
1541 tracepointargs = None
1542
1543 # Match tracepoint name based on different patterns
1544 r = KernRe(r'TRACE_EVENT\((.*?),')
1545 if r.search(proto):
1546 tracepointname = r.group(1)
1547
1548 r = KernRe(r'DEFINE_SINGLE_EVENT\((.*?),')
1549 if r.search(proto):
1550 tracepointname = r.group(1)
1551
1552 r = KernRe(r'DEFINE_EVENT\((.*?),(.*?),')
1553 if r.search(proto):
1554 tracepointname = r.group(2)
1555
1556 if tracepointname:
1557 tracepointname = tracepointname.lstrip()
1558
1559 r = KernRe(r'TP_PROTO\((.*?)\)')
1560 if r.search(proto):
1561 tracepointargs = r.group(1)
1562
1563 if not tracepointname or not tracepointargs:
1564 self.emit_msg(ln,
1565 f"Unrecognized tracepoint format:\n{proto}\n")
1566 else:
1567 proto = f"static inline void trace_{tracepointname}({tracepointargs})"
1568 self.entry.identifier = f"trace_{self.entry.identifier}"
1569
1570 return proto
1571
1572 def process_proto_function(self, ln, line, source):
1573 """Ancillary routine to process a function prototype."""
1574
1575 # strip C99-style comments to end of line
1576 line = KernRe(r"//.*$", re.S).sub('', line)
1577 #
1578 # Soak up the line's worth of prototype text, stopping at { or ; if present.
1579 #
1580 if KernRe(r'\s*#\s*define').match(line):
1581 self.entry.prototype = line
1582 elif not line.startswith('#'): # skip other preprocessor stuff
1583 r = KernRe(r'([^\{]*)')
1584 if r.match(line):
1585 self.entry.prototype += r.group(1) + " "
1586 #
1587 # If we now have the whole prototype, clean it up and declare victory.
1588 #
1589 if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(line):
1590 # strip comments and surrounding spaces
1591 self.entry.prototype = KernRe(r'/\*.*\*/').sub('', self.entry.prototype).strip()
1592 #
1593 # Handle self.entry.prototypes for function pointers like:
1594 # int (*pcs_config)(struct foo)
1595 # by turning it into
1596 # int pcs_config(struct foo)
1597 #
1598 r = KernRe(r'^(\S+\s+)\(\s*\*(\S+)\)')
1599 self.entry.prototype = r.sub(r'\1\2', self.entry.prototype)
1600 #
1601 # Handle special declaration syntaxes
1602 #
1603 if 'SYSCALL_DEFINE' in self.entry.prototype:
1604 self.entry.prototype = self.syscall_munge(ln,
1605 self.entry.prototype)
1606 else:
1607 r = KernRe(r'TRACE_EVENT|DEFINE_EVENT|DEFINE_SINGLE_EVENT')
1608 if r.search(self.entry.prototype):
1609 self.entry.prototype = self.tracepoint_munge(ln,
1610 self.entry.prototype)
1611 #
1612 # ... and we're done
1613 #
1614 self.dump_function(ln, self.entry.prototype, source)
1615 self.reset_state(ln)
1616
1617 def process_proto_type(self, ln, line, source):
1618 """
1619 Ancillary routine to process a type.
1620 """
1621
1622 # Strip C99-style comments and surrounding whitespace
1623 line = KernRe(r"//.*$", re.S).sub('', line).strip()
1624 if not line:
1625 return # nothing to see here
1626
1627 # To distinguish preprocessor directive from regular declaration later.
1628 if line.startswith('#'):
1629 line += ";"
1630 #
1631 # Split the declaration on any of { } or ;, and accumulate pieces
1632 # until we hit a semicolon while not inside {brackets}
1633 #
1634 r = KernRe(r'(.*?)([{};])')
1635 for chunk in r.split(line):
1636 if chunk: # Ignore empty matches
1637 self.entry.prototype += chunk
1638 #
1639 # This cries out for a match statement ... someday after we can
1640 # drop Python 3.9 ...
1641 #
1642 if chunk == '{':
1643 self.entry.brcount += 1
1644 elif chunk == '}':
1645 self.entry.brcount -= 1
1646 elif chunk == ';' and self.entry.brcount <= 0:
1647 self.dump_declaration(ln, self.entry.prototype, source)
1648 self.reset_state(ln)
1649 return
1650 #
1651 # We hit the end of the line while still in the declaration; put
1652 # in a space to represent the newline.
1653 #
1654 self.entry.prototype += ' '
1655
1656 def process_proto(self, ln, line, source):
1657 """STATE_PROTO: reading a function/whatever prototype."""
1658
1659 if doc_inline_oneline.search(line):
1660 self.entry.begin_section(ln, doc_inline_oneline.group(1))
1661 self.entry.add_text(doc_inline_oneline.group(2))
1662 self.dump_section()
1663
1664 elif doc_inline_start.search(line):
1665 self.state = state.INLINE_NAME
1666
1667 elif self.entry.decl_type == 'function':
1668 self.process_proto_function(ln, line, source)
1669
1670 else:
1671 self.process_proto_type(ln, line, source)
1672
1673 def process_docblock(self, ln, line, source):
1674 """STATE_DOCBLOCK: within a ``DOC:`` block."""
1675
1676 if doc_end.search(line):
1677 self.dump_section()
1678 self.output_declaration("doc", self.entry.identifier,
1679 source=source)
1680 self.reset_state(ln)
1681
1682 elif doc_content.search(line):
1683 self.entry.add_text(doc_content.group(1))
1684
1685 def parse_export(self):
1686 """
1687 Parses ``EXPORT_SYMBOL*`` macros from a single Kernel source file.
1688 """
1689
1690 export_table = set()
1691
1692 try:
1693 with open(self.fname, "r", encoding="utf8",
1694 errors="backslashreplace") as fp:
1695
1696 for line in fp:
1697 self.process_export(export_table, line)
1698
1699 except IOError:
1700 return None
1701
1702 return export_table
1703
1704 #: The state/action table telling us which function to invoke in each state.
1705 state_actions = {
1706 state.NORMAL: process_normal,
1707 state.NAME: process_name,
1708 state.BODY: process_body,
1709 state.DECLARATION: process_decl,
1710 state.SPECIAL_SECTION: process_special,
1711 state.INLINE_NAME: process_inline_name,
1712 state.INLINE_TEXT: process_inline_text,
1713 state.PROTO: process_proto,
1714 state.DOCBLOCK: process_docblock,
1715 }
1716
1717 def parse_kdoc(self):
1718 """
1719 Open and process each line of a C source file.
1720 The parsing is controlled via a state machine, and the line is passed
1721 to a different process function depending on the state. The process
1722 function may update the state as needed.
1723
1724 Besides parsing kernel-doc tags, it also parses export symbols.
1725 """
1726
1727 prev = ""
1728 prev_ln = None
1729 export_table = set()
1730 self.state = state.NORMAL
1731 source = ""
1732
1733 try:
1734 with open(self.fname, "r", encoding="utf8",
1735 errors="backslashreplace") as fp:
1736 for ln, line in enumerate(fp):
1737
1738 line = line.expandtabs().strip("\n")
1739
1740 # Group continuation lines on prototypes
1741 if self.state == state.PROTO:
1742 if line.endswith("\\"):
1743 prev += line.rstrip("\\")
1744 if not prev_ln:
1745 prev_ln = ln
1746 continue
1747
1748 if prev:
1749 ln = prev_ln
1750 line = prev + line
1751 prev = ""
1752 prev_ln = None
1753
1754 self.config.log.debug("%d %s: %s",
1755 ln, state.name[self.state],
1756 line)
1757
1758 if self.store_src:
1759 if source and self.state == state.NORMAL:
1760 source = ""
1761 elif self.state != state.NORMAL:
1762 source += line + "\n"
1763
1764 # This is an optimization over the original script.
1765 # There, when export_file was used for the same file,
1766 # it was read twice. Here, we use the already-existing
1767 # loop to parse exported symbols as well.
1768 #
1769 if (self.state != state.NORMAL) or \
1770 not self.process_export(export_table, line):
1771 prev_state = self.state
1772 # Hand this line to the appropriate state handler
1773 self.state_actions[self.state](self, ln, line, source)
1774 if prev_state == state.NORMAL and self.state != state.NORMAL:
1775 source += line + "\n"
1776
1777 self.emit_unused_warnings()
1778
1779 except OSError:
1780 self.config.log.error(f"Error: Cannot open file {self.fname}")
1781
1782 return export_table, self.entries