Something went wrong. Try again.
(I'm so sorry!) Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508#!/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 osimport reimport sys
from glob import iglob
class ParseFeature: """ Parses Documentation/features, allowing to generate ReST documentation from it. """
#: feature header string. h_name = "Feature"
#: Kernel config header string. h_kconfig = "Kconfig"
#: description header string. h_description = "Description"
#: subsystem header string. h_subsys = "Subsystem"
#: status header string. h_status = "Status"
#: architecture header string. 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"): """Helper function to append a new message for feature output."""
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