doc: boards: extensions: Add Sphinx directive for board supported hardware

Introduce a new directive for displaying hardware features supported by
a board, using information available in the devicetree.

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

doc/_extensions/zephyr/domain/__init__.py

@@ -53,6 +53,8 @@
 from zephyr.doxybridge import DoxygenGroupDirective
 from zephyr.gh_utils import gh_link_get_url
 
+from .binding_types import BINDING_TYPES
+
 __version__ = "0.2.0"
 
 
@@ -67,6 +69,16 @@
 
 logger = logging.getLogger(__name__)
 
+BINDING_TYPE_TO_DOCUTILS_NODE = {}
+for key, value in BINDING_TYPES.items():
+    if isinstance(value, tuple):
+        # For abbreviations with explanations
+        abbr, explanation = value
+        BINDING_TYPE_TO_DOCUTILS_NODE[key] = nodes.abbreviation(abbr, abbr, explanation=explanation)
+    else:
+        # For simple text
+        BINDING_TYPE_TO_DOCUTILS_NODE[key] = nodes.Text(value)
+
 
 class CodeSampleNode(nodes.Element):
     pass
@@ -685,6 +697,7 @@ def run(self):
             board_node = BoardNode(id=board_name)
             board_node["full_name"] = board["full_name"]
             board_node["vendor"] = vendors.get(board["vendor"], board["vendor"])
+            board_node["supported_features"] = board["supported_features"]
             board_node["archs"] = board["archs"]
             board_node["socs"] = board["socs"]
             board_node["image"] = board["image"]
@@ -716,6 +729,106 @@ def run(self):
             return [nodes.paragraph(text="Board catalog is only available in HTML.")]
 
 
+class BoardSupportedHardwareDirective(SphinxDirective):
+    """A directive for showing the supported hardware features of a board."""
+
+    has_content = False
+    required_arguments = 0
+    optional_arguments = 0
+
+    def run(self):
+        env = self.env
+        docname = env.docname
+
+        matcher = NodeMatcher(BoardNode)
+        board_nodes = list(self.state.document.traverse(matcher))
+        if not board_nodes:
+            logger.warning(
+                "board-supported-hw directive must be used in a board documentation page.",
+                location=(docname, self.lineno),
+            )
+            return []
+
+        board_node = board_nodes[0]
+        supported_features = board_node["supported_features"]
+
+        if not supported_features:
+            return []
+
+        # Create the table structure
+        table = nodes.table(classes=["colwidths-given"])
+        tgroup = nodes.tgroup(cols=3)
+
+        tgroup += nodes.colspec(colwidth=20, classes=["col-1"])
+        tgroup += nodes.colspec(colwidth=50)
+        tgroup += nodes.colspec(colwidth=30)
+
+        # Create header row
+        thead = nodes.thead()
+        row = nodes.row()
+        headers = ["Type", "Description", "Compatible"]
+        for header in headers:
+            row += nodes.entry("", nodes.paragraph(text=header))
+        thead += row
+        tgroup += thead
+
+        # Create table body
+        tbody = nodes.tbody()
+
+        def feature_sort_key(feature):
+            if feature == "cpu":
+                return (0, feature)
+            return (1, feature)
+
+        sorted_features = sorted(supported_features.keys(), key=feature_sort_key)
+
+        for feature in sorted_features:
+            items = list(supported_features[feature].items())
+            num_items = len(items)
+
+            for i, (key, value) in enumerate(items):
+                row = nodes.row()
+
+                # Add type column only for first row of a feature
+                if i == 0:
+                    type_entry = nodes.entry(morerows=num_items - 1)
+                    type_entry += nodes.paragraph(
+                        "",
+                        "",
+                        BINDING_TYPE_TO_DOCUTILS_NODE.get(feature, nodes.Text(feature)).deepcopy(),
+                    )
+                    row += type_entry
+
+                row += nodes.entry("", nodes.paragraph(text=value))
+
+                # Create compatible xref
+                xref = addnodes.pending_xref(
+                    "",
+                    refdomain="std",
+                    reftype="dtcompatible",
+                    reftarget=key,
+                    refexplicit=False,
+                    refwarn=True,
+                )
+                xref += nodes.literal(text=key)
+                row += nodes.entry("", nodes.paragraph("", "", xref))
+
+                tbody += row
+
+        tgroup += tbody
+        table += tgroup
+
+        note = nodes.admonition()
+        note += nodes.title(text="Note")
+        note["classes"].append("note")
+        note += nodes.paragraph(
+            text="The list of supported hardware features was automatically "
+            "generated using information from the Devicetree."
+        )
+
+        return [table, note]
+
+
 class ZephyrDomain(Domain):
     """Zephyr domain"""
 
@@ -734,6 +847,7 @@ class ZephyrDomain(Domain):
         "code-sample-category": CodeSampleCategoryDirective,
         "board-catalog": BoardCatalogDirective,
         "board": BoardDirective,
+        "board-supported-hw": BoardSupportedHardwareDirective,
     }
 
     object_types: dict[str, ObjType] = {

doc/_extensions/zephyr/domain/binding_types.py

@@ -0,0 +1,138 @@
+"""
+Zephyr Binding Types
+###################
+
+SPDX-FileCopyrightText: Copyright (c) 2025 The Linux Foundation
+SPDX-License-Identifier: Apache-2.0
+
+This module contains the mapping of binding types to their human-readable names and descriptions.
+Each entry can be either:
+- A string representing the human-readable name
+- A tuple of (abbreviation, full name) for cases where an abbreviation exists
+"""
+
+BINDING_TYPES = {
+    # zephyr-keep-sorted-start /^    "/
+    "acpi": ("ACPI", "Advanced Configuration and Power Interface"),
+    "adc": ("ADC", "Analog to Digital Converter"),
+    "alh": ("ALH", "Audio Link Hub"),
+    "arc": "ARC architecture",
+    "arm": "ARM architecture",
+    "audio": "Audio",
+    "auxdisplay": "Auxiliary Display",
+    "battery": "Battery",
+    "base": "Base",
+    "bluetooth": "Bluetooth",
+    "cache": "Cache",
+    "can": ("CAN", "Controller Area Network"),
+    "charger": "Charger",
+    "clock": "Clock control",
+    "coredump": "Core dump",
+    "counter": "Counter",
+    "cpu": "CPU",
+    "crypto": "Cryptographic accelerator",
+    "dac": ("DAC", "Digital to Analog Converter"),
+    "dai": ("DAI", "Digital Audio Interface"),
+    "debug": "Debug",
+    "dfpmcch": "DFPMCCH",
+    "dfpmccu": "DFPMCCU",
+    "disk": "Disk",
+    "display": "Display",
+    "display/panel": "Display panel",
+    "dma": ("DMA", "Direct Memory Access"),
+    "dsa": ("DSA", "Distributed Switch Architecture"),
+    "edac": ("EDAC", "Error Detection and Correction"),
+    "espi": ("eSPI", "Enhanced Serial Peripheral Interface"),
+    "ethernet": "Ethernet",
+    "firmware": "Firmware",
+    "flash_controller": "Flash controller",
+    "fpga": ("FPGA", "Field Programmable Gate Array"),
+    "fs": "File system",
+    "fuel-gauge": "Fuel gauge",
+    "gnss": ("GNSS", "Global Navigation Satellite System"),
+    "gpio": ("GPIO", "General Purpose Input/Output"),
+    "haptics": "Haptics",
+    "hda": ("HDA", "High Definition Audio"),
+    "hdlc_rcp_if": "IEEE 802.15.4 HDLC RCP interface",
+    "hwinfo": "Hardware information",
+    "hwspinlock": "Hardware spinlock",
+    "i2c": ("I2C", "Inter-Integrated Circuit"),
+    "i2s": ("I2S", "Inter-IC Sound"),
+    "i3c": ("I3C", "Improved Inter-Integrated Circuit"),
+    "ieee802154": "IEEE 802.15.4",
+    "iio": ("IIO", "Industrial I/O"),
+    "input": "Input",
+    "interrupt-controller": "Interrupt controller",
+    "ipc": ("IPC", "Inter-Processor Communication"),
+    "ipm": ("IPM", "Inter-Processor Mailbox"),
+    "kscan": "Keyscan",
+    "led": ("LED", "Light Emitting Diode"),
+    "led_strip": ("LED", "Light Emitting Diode"),
+    "lora": "LoRa",
+    "mbox": "Mailbox",
+    "mdio": ("MDIO", "Management Data Input/Output"),
+    "memory-controllers": "Memory controller",
+    "memory-window": "Memory window",
+    "mfd": ("MFD", "Multi-Function Device"),
+    "mhu": ("MHU", "Mailbox Handling Unit"),
+    "net": "Networking",
+    "mipi-dbi": ("MIPI DBI", "Mobile Industry Processor Interface Display Bus Interface"),
+    "mipi-dsi": ("MIPI DSI", "Mobile Industry Processor Interface Display Serial Interface"),
+    "misc": "Miscellaneous",
+    "mm": "Memory management",
+    "mmc": ("MMC", "MultiMediaCard"),
+    "mmu_mpu": ("MMU / MPU", "Memory Management Unit / Memory Protection Unit"),
+    "modem": "Modem",
+    "mspi": "Multi-bit SPI",
+    "mtd": ("MTD", "Memory Technology Device"),
+    "wireless": "Wireless network",
+    "options": "Options",
+    "ospi": "Octal SPI",
+    "pcie": ("PCIe", "Peripheral Component Interconnect Express"),
+    "peci": ("PECI", "Platform Environment Control Interface"),
+    "phy": "PHY",
+    "pinctrl": "Pin control",
+    "pm_cpu_ops": "Power management CPU operations",
+    "power": "Power management",
+    "power-domain": "Power domain",
+    "ppc": "PPC architecture",
+    "ps2": ("PS/2", "Personal System/2"),
+    "pwm": ("PWM", "Pulse Width Modulation"),
+    "qspi": "Quad SPI",
+    "regulator": "Regulator",
+    "reserved-memory": "Reserved memory",
+    "reset": "Reset controller",
+    "retained_mem": "Retained memory",
+    "retention": "Retention",
+    "riscv": "RISC-V architecture",
+    "rng": ("RNG", "Random Number Generator"),
+    "rtc": ("RTC", "Real Time Clock"),
+    "sd": "SD",
+    "sdhc": "SDHC",
+    "sensor": "Sensors",
+    "serial": "Serial controller",
+    "shi": ("SHI", "Secure Hardware Interface"),
+    "sip_svc": ("SIP", "Service in Platform"),
+    "smbus": ("SMBus", "System Management Bus"),
+    "sound": "Sound",
+    "spi": ("SPI", "Serial Peripheral Interface"),
+    "sram": "SRAM",
+    "stepper": "Stepper",
+    "syscon": "System controller",
+    "tach": "Tachometer",
+    "tcpc": ("TCPC", "USB Type-C Port Controller"),
+    "test": "Test",
+    "timer": "Timer",
+    "timestamp": "Timestamp",
+    "usb": "USB",
+    "usb-c": "USB Type-C",
+    "uac2": "USB Audio Class 2",
+    "video": "Video",
+    "virtualization": "Virtualization",
+    "w1": "1-Wire",
+    "watchdog": "Watchdog",
+    "wifi": "Wi-Fi",
+    "xen": "Xen",
+    "xspi": ("XSPI", "Expanded Serial Peripheral Interface"),
+    # zephyr-keep-sorted-stop
+}

doc/_scripts/gen_boards_catalog.py

@@ -20,6 +20,59 @@
 logger = logging.getLogger(__name__)
 
 
+class DeviceTreeUtils:
+    _compat_description_cache = {}
+
+    @classmethod
+    def get_first_sentence(cls, text):
+        """Extract the first sentence from a text block (typically a node description).
+
+        Args:
+            text: The text to extract the first sentence from.
+
+        Returns:
+            The first sentence found in the text, or the entire text if no sentence
+            boundary is found.
+        """
+        # Split the text into lines
+        lines = text.splitlines()
+
+        # Trim leading and trailing whitespace from each line and ignore completely blank lines
+        lines = [line.strip() for line in lines]
+
+        if not lines:
+            return ""
+
+        # Case 1: Single line followed by blank line(s) or end of text
+        if len(lines) == 1 or (len(lines) > 1 and lines[1] == ""):
+            first_line = lines[0]
+            # Check for the first period
+            period_index = first_line.find(".")
+            # If there's a period, return up to the period; otherwise, return the full line
+            return first_line[: period_index + 1] if period_index != -1 else first_line
+
+        # Case 2: Multiple contiguous lines, treat as a block
+        block = " ".join(lines)
+        period_index = block.find(".")
+        # If there's a period, return up to the period; otherwise, return the full block
+        return block[: period_index + 1] if period_index != -1 else block
+
+    @classmethod
+    def get_cached_description(cls, node):
+        """Get the cached description for a devicetree node.
+
+        Args:
+            node: A devicetree node object with matching_compat and description attributes.
+
+        Returns:
+            The cached description for the node's compatible, creating it if needed.
+        """
+        return cls._compat_description_cache.setdefault(
+            node.matching_compat,
+            cls.get_first_sentence(node.description)
+        )
+
+
 def guess_file_from_patterns(directory, patterns, name, extensions):
     for pattern in patterns:
         for ext in extensions:
@@ -121,7 +174,10 @@ def run_twister_cmake_only(outdir):
         sys.executable,
         f"{ZEPHYR_BASE}/scripts/twister",
         "-T", "samples/hello_world/",
-        "--all",
+        # "--all",
+        "-p", "wio_terminal",
+        "-p", "reel_board",
+        "-p", "native_posix",
         "-M",
         "--cmake-only",
         "-j9",
@@ -219,7 +275,10 @@ def get_catalog(generate_hw_features=False):
                 for node in okay_nodes:
                     binding_path = Path(node.binding_path)
                     binding_type = binding_path.relative_to(ZEPHYR_BASE / "dts/bindings").parts[0]
-                    target_features.setdefault(binding_type, set()).add(node.matching_compat)
+                    description = DeviceTreeUtils.get_cached_description(node)
+                    target_features.setdefault(binding_type, {}).setdefault(
+                        node.matching_compat, description
+                    )
 
 
                 # for now we do the union of all supported features for all of board's targets but

doc/_static/css/custom.css

@@ -1190,3 +1190,13 @@ li>a.code-sample-link.reference.internal.current {
     text-overflow: ellipsis;
     max-width:80%;
 }
+
+/* TEMPORARY */
+#supported-features>div>table>tbody>tr>td>p {
+    white-space: normal;
+}
+
+#supported-features td {
+    background-color: var(--table-row-odd-background-color);
+    border-left-width: 1px;
+}