2 # SPDX-License-Identifier: GPL-2.0
23 # Regular expressions used to parse kernel-doc markups at KernelDoc class.
43 #         @{section-name}:
61 type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
71                         r'(\w+)\s*(?:\(\w*\))?\s*' +	# name and optional "(...)"
72                         r'(?:[-:].*)?$',		# description (not captured)
83     (KernRe(r"__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)", flags=re.I | re.S, cache=False), ' '),
96     # __struct_group(TAG, NAME, ATTRS, MEMBERS...)
97     # which has variants like: struct_group(NAME, MEMBERS...)
115     #   - a recursive pattern: (?1)
116     #   - an atomic grouping: (?>...)
147             re.S), r'unsigned long \1[1 << ((\2) - 1)]'),
234     NAME          = 1        # looking for function name  variable in state
237     SPECIAL_SECTION = 4      # doc section ending with a blank line
243     name = [  variable in state
245         "NAME",
296     # TODO: rename to emit_message after removal of kernel-doc.pl
331         name = self.section
334         if type_param.match(name):
335             name = type_param.group(1)
337             self.parameterdescs[name] = contents
338             self.parameterdesc_start_lines[name] = self.new_start_line
343             if name in self.sections and self.sections[name] != "":
344                 # Only warn on user-specified duplicate section names
345                 if name != SECTION_DEFAULT:
347                                   f"duplicate section name '{name}'")
348                 # Treat as a new paragraph - add a blank line
349                 self.sections[name] += '\n' + contents
351                 self.sections[name] = contents
352                 self.section_start_lines[name] = self.new_start_line
355 #        self.config.log.debug("Section: %s : %s", name, pformat(vars(self)))
374     undescribed = "-- undescribed --"
425     # TODO: rename it to store_declaration after removal of kernel-doc.pl
426     def output_declaration(self, dtype, name, **args):  argument
433         item = KdocItem(name, self.fname, dtype,
449         self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
487                 if len(param) > 3: # there is a name provided, use that
488                     param = param[:-3]
559             # The pointer-to-function case.
564                            r'([\w\[\].]*)'    # Capture the name and possible [array]
574             # The array-of-pointers case.  Dig the parameter name out from the middle
579                            r'([\w.]*?)'			# The actual pointer name
613                     # For pointers, shift the star(s) from the variable name to the
625                         if dtype != "":  # Skip unnamed bit-fields
667     # Split apart a structure prototype; returns (struct|union, name, members) or None
701         # trick is in the ^{ below - it prevents a match of an outer struct/union
705                                 r'([^\{\};]+)' 	    # 1: possible name
715                 dtype, name, lbr, content, rbr, rest, semi = t
717                 # Pass through each field name, normalizing the form and formatting.
723                     # Remove bitfield/array/pointer info, getting the bare name.
733                         # Look for (type)(*name)(args) - pointer to function
737                             dtype, name, extra = r.group(1), r.group(2), r.group(3)
738                             # Pointer-to-function
741                                 newmember += f"{dtype}{name}{extra}; "
743                                 newmember += f"{dtype}{s_id}.{name}{extra}; "
745                         # Otherwise a non-function member.
755                             # Look for a normal decl - "type name[,name...]"
759                                 for name in r.group(2).split(','):
760                                     name = KernRe(r'^\s*\**(\S+)\s*').sub(r'\1', name)
763                                         newmember += f"{r.group(1)} {name}; "
765                                         newmember += f"{r.group(1)} {s_id}.{name}; "
774             # End of the tuple loop - search again and see if there are outer members
791         # Format inline enums with each member on its own line.
798         # for each line.
807                     level -= 1
868         # Parse out the name and members of the enum.  Typedef form first.
894                               f"{proto}: wrong kernel-doc identifier on prototype")
904         # Parse out the name of each enum member, and verify that we
965             # is the space after the name of the symbol being defined.
978         # 2. Function name
988         # - parport_register_device (function pointer parameters)
989         # - atomic_set (macro)
990         # - pci_match_device, __copy_to_user (long return type)
992         name = r'\w+'
997         # lets us easily filter out __acquires() and other post-args stuff.  If
998         # that fails, just grab the rest of the line to the last closing
1008                 rf'^()({name})\s*{proto_args}',
1009                 rf'^({type1})\s+({name})\s*{proto_args}',
1010                 rf'^({type2})\s*({name})\s*{proto_args}',
1100     def process_export(function_set, line):  argument
1112         # Note: it accepts only one EXPORT_SYMBOL* per line, as having
1115         if export_symbol.search(line):
1117         elif export_symbol_ns.search(line):
1127                 symbol = symbol[:-len(suffix)]
1131     def process_normal(self, ln, line):  argument
1136         if not doc_start.match(line):
1142         # next line is always the function name
1143         self.state = state.NAME
1145     def process_name(self, ln, line):  argument
1147         STATE_NAME: Looking for the "name - description" line
1152         if doc_block.search(line):
1162         # Otherwise we're looking for a normal kerneldoc declaration line.
1164         elif doc_decl.search(line):
1168             if doc_begin_data.search(line):
1174             elif doc_begin_func.search(line):
1182 …ment starts with '/**', but isn't a kernel-doc comment. Refer to Documentation/doc-guide/kernel-do…
1195             # (We should be able to capture this from the previous parsing - someday)
1197             r = KernRe("[-:](.*)")
1198             if r.search(line):
1206                               f"missing initial short description on line:\n{line}")
1210                               f"wrong kernel-doc identifier on line:\n{line}")
1221             self.emit_msg(ln, f"Cannot find identifier on line:\n{line}")
1226     def is_new_section(self, ln, line):  argument
1227         if doc_sect.search(line):
1230             # Pick out the name of our new section, tweaking it if need be.
1261     def is_comment_end(self, ln, line):  argument
1262         if doc_end.search(line):
1266             r = KernRe(r'\s*\*\s*[a-zA-Z_0-9:.]+\*/')
1267             if r.match(line):
1268                 self.emit_msg(ln, f"suspicious ending line: {line}")
1278     def process_decl(self, ln, line):  argument
1282         if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1285         # Look for anything with the " * " line beginning.
1287         if doc_content.search(line):
1290             # A blank line means that we have moved out of the declaration
1303             # Unknown line, ignore
1304             self.emit_msg(ln, f"bad line: {line}")
1307     def process_special(self, ln, line):  argument
1309         STATE_SPECIAL_SECTION: a section ending with a blank line
1312         # If we have hit a blank line (only the " * " marker), then this
1315         if KernRe(r"\s*\*\s*$").match(line):
1320         # Not a blank line, look for the other ways to end the section.
1322         if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1327         if doc_content.search(line):
1332             # confused.  For the second line (the None case), see what we
1355             # Unknown line, ignore
1356             self.emit_msg(ln, f"bad line: {line}")
1358     def process_body(self, ln, line):  argument
1362         if self.is_new_section(ln, line) or self.is_comment_end(ln, line):
1365         if doc_content.search(line):
1369             # Unknown line, ignore
1370             self.emit_msg(ln, f"bad line: {line}")
1372     def process_inline_name(self, ln, line):  argument
1375         if doc_inline_sect.search(line):
1379         elif doc_inline_end.search(line):
1382         elif doc_content.search(line):
1383             self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
1387     def process_inline_text(self, ln, line):  argument
1390         if doc_inline_end.search(line):
1393         elif doc_content.search(line):
1411         # Replace SYSCALL_DEFINE with correct return type & function name
1420         # Now delete all of the odd-numbered commas in the proto
1444         # Match tracepoint name based on different patterns
1473     def process_proto_function(self, ln, line):  argument
1476         # strip C99-style comments to end of line
1477         line = KernRe(r"//.*$", re.S).sub('', line)
1479         # Soak up the line's worth of prototype text, stopping at { or ; if present.
1481         if KernRe(r'\s*#\s*define').match(line):
1482             self.entry.prototype = line
1483         elif not line.startswith('#'):   # skip other preprocessor stuff
1485             if r.match(line):
1490         if '{' in line or ';' in line or KernRe(r'\s*#\s*define').match(line):
1518     def process_proto_type(self, ln, line):  argument
1521         # Strip C99-style comments and surrounding whitespace
1522         line = KernRe(r"//.*$", re.S).sub('', line).strip()
1523         if not line:
1527         if line.startswith('#'):
1528             line += ";"
1534         for chunk in r.split(line):
1544                     self.entry.brcount -= 1
1550         # We hit the end of the line while still in the declaration; put
1555     def process_proto(self, ln, line):  argument
1558         if doc_inline_oneline.search(line):
1563         elif doc_inline_start.search(line):
1567             self.process_proto_function(ln, line)
1570             self.process_proto_type(ln, line)
1572     def process_docblock(self, ln, line):  argument
1575         if doc_end.search(line):
1580         elif doc_content.search(line):
1594                 for line in fp:
1595                     self.process_export(export_table, line)
1608         state.NAME:			process_name,
1620         Open and process each line of a C source file.
1621         The parsing is controlled via a state machine, and the line is passed
1625         Besides parsing kernel-doc tags, it also parses export symbols.
1635                 for ln, line in enumerate(fp):
1637                     line = line.expandtabs().strip("\n")
1641                         if line.endswith("\\"):
1642                             prev += line.rstrip("\\")
1649                             line = prev + line
1654                                           ln, state.name[self.state],
1655                                           line)
1659                     # it was read twice. Here, we use the already-existing
1663                        not self.process_export(export_table, line):
1664                         # Hand this line to the appropriate state handler
1665                         self.state_actions[self.state](self, ln, line)