xref: /linux/tools/lib/python/feat/parse_features.py (revision 72c395024dac5e215136cbff793455f065603b06)

#!/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.
    """

    #: 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