#!/usr/bin/env python3 # pylint: disable=R0902,R0911,R0912,R0914,R0915 # Copyright(c) 2025: Mauro Carvalho Chehab . # SPDX-License-Identifier: GPL-2.0 """ Library to parse the Linux Feature files and produce a ReST book. """ import os import re import sys from glob import iglob class ParseFeature: """ Parses Documentation/features, allowing to generate ReST documentation from it. """ h_name = "Feature" h_kconfig = "Kconfig" h_description = "Description" h_subsys = "Subsystem" h_status = "Status" h_arch = "Architecture" # Sort order for status. Others will be mapped at the end. status_map = { "ok": 0, "TODO": 1, "N/A": 2, # The only missing status is "..", which was mapped as "---", # as this is an special ReST cell value. Let it get the # default order (99). } def __init__(self, prefix, debug=0, enable_fname=False): """ Sets internal variables """ self.prefix = prefix self.debug = debug self.enable_fname = enable_fname self.data = {} # Initial maximum values use just the headers self.max_size_name = len(self.h_name) self.max_size_kconfig = len(self.h_kconfig) self.max_size_description = len(self.h_description) self.max_size_desc_word = 0 self.max_size_subsys = len(self.h_subsys) self.max_size_status = len(self.h_status) self.max_size_arch = len(self.h_arch) self.max_size_arch_with_header = self.max_size_arch + self.max_size_arch self.description_size = 1 self.msg = "" def emit(self, msg="", end="\n"): self.msg += msg + end def parse_error(self, fname, ln, msg, data=None): """ Displays an error message, printing file name and line """ if ln: fname += f"#{ln}" print(f"Warning: file {fname}: {msg}", file=sys.stderr, end="") if data: data = data.rstrip() print(f":\n\t{data}", file=sys.stderr) else: print("", file=sys.stderr) def parse_feat_file(self, fname): """Parses a single arch-support.txt feature file""" if os.path.isdir(fname): return base = os.path.basename(fname) if base != "arch-support.txt": if self.debug: print(f"ignoring {fname}", file=sys.stderr) return subsys = os.path.dirname(fname).split("/")[-2] self.max_size_subsys = max(self.max_size_subsys, len(subsys)) feature_name = "" kconfig = "" description = "" comments = "" arch_table = {} if self.debug > 1: print(f"Opening {fname}", file=sys.stderr) if self.enable_fname: full_fname = os.path.abspath(fname) self.emit(f".. FILE {full_fname}") with open(fname, encoding="utf-8") as f: for ln, line in enumerate(f, start=1): line = line.strip() match = re.match(r"^\#\s+Feature\s+name:\s*(.*\S)", line) if match: feature_name = match.group(1) self.max_size_name = max(self.max_size_name, len(feature_name)) continue match = re.match(r"^\#\s+Kconfig:\s*(.*\S)", line) if match: kconfig = match.group(1) self.max_size_kconfig = max(self.max_size_kconfig, len(kconfig)) continue match = re.match(r"^\#\s+description:\s*(.*\S)", line) if match: description = match.group(1) self.max_size_description = max(self.max_size_description, len(description)) words = re.split(r"\s+", line)[1:] for word in words: self.max_size_desc_word = max(self.max_size_desc_word, len(word)) continue if re.search(r"^\\s*$", line): continue if re.match(r"^\s*\-+\s*$", line): continue if re.search(r"^\s*\|\s*arch\s*\|\s*status\s*\|\s*$", line): continue match = re.match(r"^\#\s*(.*)$", line) if match: comments += match.group(1) continue match = re.match(r"^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$", line) if match: arch = match.group(1) status = match.group(2) self.max_size_status = max(self.max_size_status, len(status)) self.max_size_arch = max(self.max_size_arch, len(arch)) if status == "..": status = "---" arch_table[arch] = status continue self.parse_error(fname, ln, "Line is invalid", line) if not feature_name: self.parse_error(fname, 0, "Feature name not found") return if not subsys: self.parse_error(fname, 0, "Subsystem not found") return if not kconfig: self.parse_error(fname, 0, "Kconfig not found") return if not description: self.parse_error(fname, 0, "Description not found") return if not arch_table: self.parse_error(fname, 0, "Architecture table not found") return self.data[feature_name] = { "where": fname, "subsys": subsys, "kconfig": kconfig, "description": description, "comments": comments, "table": arch_table, } self.max_size_arch_with_header = self.max_size_arch + len(self.h_arch) def parse(self): """Parses all arch-support.txt feature files inside self.prefix""" path = os.path.expanduser(self.prefix) if self.debug > 2: print(f"Running parser for {path}") example_path = os.path.join(path, "arch-support.txt") for fname in iglob(os.path.join(path, "**"), recursive=True): if fname != example_path: self.parse_feat_file(fname) return self.data def output_arch_table(self, arch, feat=None): """ Output feature(s) for a given architecture. """ title = f"Feature status on {arch} architecture" self.emit("=" * len(title)) self.emit(title) self.emit("=" * len(title)) self.emit() self.emit("=" * self.max_size_subsys + " ", end="") self.emit("=" * self.max_size_name + " ", end="") self.emit("=" * self.max_size_kconfig + " ", end="") self.emit("=" * self.max_size_status + " ", end="") self.emit("=" * self.max_size_description) self.emit(f"{self.h_subsys:<{self.max_size_subsys}} ", end="") self.emit(f"{self.h_name:<{self.max_size_name}} ", end="") self.emit(f"{self.h_kconfig:<{self.max_size_kconfig}} ", end="") self.emit(f"{self.h_status:<{self.max_size_status}} ", end="") self.emit(f"{self.h_description:<{self.max_size_description}}") self.emit("=" * self.max_size_subsys + " ", end="") self.emit("=" * self.max_size_name + " ", end="") self.emit("=" * self.max_size_kconfig + " ", end="") self.emit("=" * self.max_size_status + " ", end="") self.emit("=" * self.max_size_description) sorted_features = sorted(self.data.keys(), key=lambda x: (self.data[x]["subsys"], x.lower())) for name in sorted_features: if feat and name != feat: continue arch_table = self.data[name]["table"] if not arch in arch_table: continue self.emit(f"{self.data[name]['subsys']:<{self.max_size_subsys}} ", end="") self.emit(f"{name:<{self.max_size_name}} ", end="") self.emit(f"{self.data[name]['kconfig']:<{self.max_size_kconfig}} ", end="") self.emit(f"{arch_table[arch]:<{self.max_size_status}} ", end="") self.emit(f"{self.data[name]['description']}") self.emit("=" * self.max_size_subsys + " ", end="") self.emit("=" * self.max_size_name + " ", end="") self.emit("=" * self.max_size_kconfig + " ", end="") self.emit("=" * self.max_size_status + " ", end="") self.emit("=" * self.max_size_description) return self.msg def output_feature(self, feat): """ Output a feature on all architectures """ title = f"Feature {feat}" self.emit("=" * len(title)) self.emit(title) self.emit("=" * len(title)) self.emit() if not feat in self.data: return if self.data[feat]["subsys"]: self.emit(f":Subsystem: {self.data[feat]['subsys']}") if self.data[feat]["kconfig"]: self.emit(f":Kconfig: {self.data[feat]['kconfig']}") desc = self.data[feat]["description"] desc = desc[0].upper() + desc[1:] desc = desc.rstrip(". \t") self.emit(f"\n{desc}.\n") com = self.data[feat]["comments"].strip() if com: self.emit("Comments") self.emit("--------") self.emit(f"\n{com}\n") self.emit("=" * self.max_size_arch + " ", end="") self.emit("=" * self.max_size_status) self.emit(f"{self.h_arch:<{self.max_size_arch}} ", end="") self.emit(f"{self.h_status:<{self.max_size_status}}") self.emit("=" * self.max_size_arch + " ", end="") self.emit("=" * self.max_size_status) arch_table = self.data[feat]["table"] for arch in sorted(arch_table.keys()): self.emit(f"{arch:<{self.max_size_arch}} ", end="") self.emit(f"{arch_table[arch]:<{self.max_size_status}}") self.emit("=" * self.max_size_arch + " ", end="") self.emit("=" * self.max_size_status) return self.msg def matrix_lines(self, desc_size, max_size_status, header): """ Helper function to split element tables at the output matrix """ if header: ln_marker = "=" else: ln_marker = "-" self.emit("+" + ln_marker * self.max_size_name + "+", end="") self.emit(ln_marker * desc_size, end="") self.emit("+" + ln_marker * max_size_status + "+") def output_matrix(self): """ Generates a set of tables, groped by subsystem, containing what's the feature state on each architecture. """ title = "Feature status on all architectures" self.emit("=" * len(title)) self.emit(title) self.emit("=" * len(title)) self.emit() desc_title = f"{self.h_kconfig} / {self.h_description}" desc_size = self.max_size_kconfig + 4 if not self.description_size: desc_size = max(self.max_size_description, desc_size) else: desc_size = max(self.description_size, desc_size) desc_size = max(self.max_size_desc_word, desc_size, len(desc_title)) notcompat = "Not compatible" self.max_size_status = max(self.max_size_status, len(notcompat)) min_status_size = self.max_size_status + self.max_size_arch + 4 max_size_status = max(min_status_size, self.max_size_status) h_status_per_arch = "Status per architecture" max_size_status = max(max_size_status, len(h_status_per_arch)) cur_subsys = None for name in sorted(self.data.keys(), key=lambda x: (self.data[x]["subsys"], x.lower())): if not cur_subsys or cur_subsys != self.data[name]["subsys"]: if cur_subsys: self.emit() cur_subsys = self.data[name]["subsys"] title = f"Subsystem: {cur_subsys}" self.emit(title) self.emit("=" * len(title)) self.emit() self.matrix_lines(desc_size, max_size_status, 0) self.emit(f"|{self.h_name:<{self.max_size_name}}", end="") self.emit(f"|{desc_title:<{desc_size}}", end="") self.emit(f"|{h_status_per_arch:<{max_size_status}}|") self.matrix_lines(desc_size, max_size_status, 1) lines = [] descs = [] cur_status = "" line = "" arch_table = sorted(self.data[name]["table"].items(), key=lambda x: (self.status_map.get(x[1], 99), x[0].lower())) for arch, status in arch_table: if status == "---": status = notcompat if status != cur_status: if line != "": lines.append(line) line = "" line = f"- **{status}**: {arch}" elif len(line) + len(arch) + 2 < max_size_status: line += f", {arch}" else: lines.append(line) line = f" {arch}" cur_status = status if line != "": lines.append(line) description = self.data[name]["description"] while len(description) > desc_size: desc_line = description[:desc_size] last_space = desc_line.rfind(" ") if last_space != -1: desc_line = desc_line[:last_space] descs.append(desc_line) description = description[last_space + 1:] else: desc_line = desc_line[:-1] descs.append(desc_line + "\\") description = description[len(desc_line):] if description: descs.append(description) while len(lines) < 2 + len(descs): lines.append("") for ln, line in enumerate(lines): col = ["", ""] if not ln: col[0] = name col[1] = f"``{self.data[name]['kconfig']}``" else: if ln >= 2 and descs: col[1] = descs.pop(0) self.emit(f"|{col[0]:<{self.max_size_name}}", end="") self.emit(f"|{col[1]:<{desc_size}}", end="") self.emit(f"|{line:<{max_size_status}}|") self.matrix_lines(desc_size, max_size_status, 0) return self.msg def list_arch_features(self, arch, feat): """ Print a matrix of kernel feature support for the chosen architecture. """ self.emit("#") self.emit(f"# Kernel feature support matrix of the '{arch}' architecture:") self.emit("#") # Sort by subsystem, then by feature name (case‑insensitive) for name in sorted(self.data.keys(), key=lambda n: (self.data[n]["subsys"].lower(), n.lower())): if feat and name != feat: continue feature = self.data[name] arch_table = feature["table"] status = arch_table.get(arch, "") status = " " * ((4 - len(status)) // 2) + status self.emit(f"{feature['subsys']:>{self.max_size_subsys + 1}}/ ", end="") self.emit(f"{name:<{self.max_size_name}}: ", end="") self.emit(f"{status:<5}| ", end="") self.emit(f"{feature['kconfig']:>{self.max_size_kconfig}} ", end="") self.emit(f"# {feature['description']}") return self.msg