| #!/usr/bin/env python3 |
| # pylint: disable=R0902,R0911,R0912,R0914,R0915 |
| # Copyright(c) 2025: Mauro Carvalho Chehab <mchehab@kernel.org>. |
| # 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 |
