labgrid-boardkit 0.1.0__py3-none-any.whl

labgrid_boardkit/fixtures.py

@@ -0,0 +1,77 @@
+"""pytest fixtures + hooks shared across all board test suites.
+
+Auto-loaded via the ``pytest11`` entry point in
+``pyproject.toml``. No per-board conftest.py needed for these.
+"""
+
+import os
+import traceback
+from pathlib import Path
+
+import pytest
+
+from labgrid_boardkit.strategies.fastboot import FastbootFlashStrategy
+from labgrid_boardkit.strategies.sdmux import SdMuxBootStrategy
+from labgrid_boardkit.strategies.tftp import TftpBootStrategy
+
+
+def pytest_configure(config):
+    """Auto-set ``--lg-env``.
+
+    Resolution order:
+    1. Skip if user already passed ``--lg-env``.
+    2. ``BOARD`` env var → ``$BOARD/client.yaml`` (or ``env.yaml``) rel to cwd.
+    3. Walk upward from each CLI arg looking for ``client.yaml`` / ``env.yaml``.
+    """
+    if config.getoption("--lg-env", default=None):
+        return
+
+    board = os.environ.get("BOARD")
+    if board:
+        for candidate in (Path(board) / "client.yaml", Path(board) / "env.yaml"):
+            if candidate.is_file():
+                config.option.lg_env = str(candidate.resolve())
+                return
+
+    for arg in config.args:
+        for p in Path(arg).resolve().parents:
+            for candidate in (p / "client.yaml", p / "env.yaml"):
+                if candidate.is_file():
+                    config.option.lg_env = str(candidate)
+                    return
+
+
+def _transition(strategy, target, state: str):
+    try:
+        strategy.transition(state)
+    except Exception as e:
+        traceback.print_exc()
+        pytest.exit(f"Transition into {state} boot shell failed: {e}", returncode=3)
+    return target.get_driver("ShellDriver")
+
+
+@pytest.fixture(scope="module")
+def tftp(strategy, target):
+    if not isinstance(strategy, TftpBootStrategy):
+        pytest.skip("board does not use TFTP boot strategy")
+    return _transition(strategy, target, "tftp")
+
+
+@pytest.fixture(scope="module")
+def sd(strategy, target):
+    if not isinstance(strategy, SdMuxBootStrategy):
+        pytest.skip("board does not use SD-mux boot strategy")
+    return _transition(strategy, target, "sd")
+
+
+@pytest.fixture(scope="module")
+def fastboot(strategy, target):
+    if not isinstance(strategy, FastbootFlashStrategy):
+        pytest.skip("board does not use fastboot flash strategy")
+    return _transition(strategy, target, "shell")
+
+
+@pytest.fixture(scope="module")
+def shell(strategy, target):
+    """Generic shell fixture: transitions to the ``shell`` state (qemu)."""
+    return _transition(strategy, target, "shell")

labgrid_boardkit/helpers.py

@@ -0,0 +1,58 @@
+# Helper functions for the labgrid-boardkit test suites and strategies
+
+import re
+
+default_bootargs = (
+    "console=tty1 "
+    "console=ttyS0,115200 "
+    "consoleblank=0 "
+    "earlycon=sbi "
+    "fsck.fix=yes "
+    "fsck.repair=yes "
+    "loglevel=7 "
+    "net.ifnames=0 "
+    "no_console_suspend "
+    "plymouth.ignore-serial-consoles "
+    "rootwait "
+    "rw "
+    "splash "
+    "systemd.journald.storage=volatile "
+)
+
+default_serverip = "192.168.40.166"
+
+
+def kernel_version_in(version: str, uname: str) -> bool:
+    """True if the kernel recipe's version (as CI takes it from the deployed
+    kernel's file name, e.g. "7.4-rc1") is the one ``uname`` reports. The
+    kernel always has a sublevel, so an rc reports "7.4.0-rc1"."""
+    return version in uname or re.sub(r"^(\d+\.\d+)(?=-|$)", r"\1.0", version) in uname
+
+
+def uboot_stage(strategy):
+    if strategy.staged:
+        return
+    strategy.target.activate(strategy.tftp)
+
+    for name, image in strategy.target.env.config.get_images().items():
+        if name.startswith("tftp-"):
+            strategy.tftp.stage(image)
+
+    strategy.target.deactivate(strategy.tftp)
+    strategy.staged = True
+
+
+def uboot_set_server_ip(strategy, serverip=default_serverip):
+    strategy.uboot.run("setenv autoload no")
+    # run_check: a failed dhcp/tftpboot should fail here, not as a confusing
+    # boot timeout later.
+    strategy.uboot.run_check("dhcp", timeout=10)
+    strategy.uboot.run(f"setenv serverip {serverip}")
+
+
+def uboot_set_bootargs(strategy, bootargs=default_bootargs):
+    strategy.uboot.run(f"setenv bootargs {bootargs}")
+
+
+def uboot_tftpboot_file(strategy, loadaddr, board_name, file_name):
+    strategy.uboot.run_check(f"tftpboot {loadaddr} {board_name}/{file_name}")

labgrid_boardkit/loader.py

@@ -0,0 +1,27 @@
+"""Registry lookup for strategy families.
+
+Strategies are registered as ``labgrid_boardkit.strategies`` entry points in
+``pyproject.toml``. Third-party packages can add families the same way.
+"""
+
+from importlib.metadata import entry_points
+
+
+class UnknownStrategy(KeyError):
+    pass
+
+
+def available_strategies() -> dict[str, str]:
+    """Return {family_name: dotted-path} for every registered strategy."""
+    return {ep.name: ep.value for ep in entry_points(group="labgrid_boardkit.strategies")}
+
+
+def strategy_for(manifest: dict):
+    """Look up a strategy class by ``manifest['strategy']``."""
+    name = manifest.get("strategy")
+    if not name:
+        raise UnknownStrategy("board.yaml is missing top-level 'strategy: <family>' key")
+    eps = {ep.name: ep for ep in entry_points(group="labgrid_boardkit.strategies")}
+    if name not in eps:
+        raise UnknownStrategy(f"strategy {name!r} not registered (available: {sorted(eps)})")
+    return eps[name].load()

labgrid_boardkit/manifest.py

@@ -0,0 +1,53 @@
+"""Load and merge board.yaml manifests.
+
+``inherits:`` in a board.yaml lists paths (relative to the board dir) to
+defaults files. Files are deep-merged in order; the board.yaml wins.
+
+``variants:`` maps a name to overrides describing another way to boot the same
+board, usually for a different Yocto MACHINE (e.g. a mainline-kernel BSP that
+TFTP-boots while the default flashes storage). A variant is deep-merged over
+the base manifest.
+"""
+
+from copy import deepcopy
+from pathlib import Path
+
+import yaml
+
+
+def _read_yaml(path: Path) -> dict:
+    with path.open() as f:
+        return yaml.safe_load(f) or {}
+
+
+def _deep_merge(base: dict, over: dict) -> dict:
+    """Recursively merge ``over`` into ``base``. Lists and scalars are replaced."""
+    out = deepcopy(base)
+    for k, v in over.items():
+        if k in out and isinstance(out[k], dict) and isinstance(v, dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = deepcopy(v)
+    return out
+
+
+def load_board(board_dir: str | Path, variant: str | None = None) -> dict:
+    """Load ``board.yaml`` from a board directory, applying ``inherits:`` defaults
+    and, if given, the named ``variants:`` entry. The result has no ``variants``."""
+    board_dir = Path(board_dir)
+    board_yaml = _read_yaml(board_dir / "board.yaml")
+
+    merged: dict = {}
+    for rel in board_yaml.get("inherits", []):
+        merged = _deep_merge(merged, _read_yaml((board_dir / rel).resolve()))
+    merged = _deep_merge(merged, board_yaml)
+    merged.pop("inherits", None)
+    variants = merged.pop("variants", {})
+    if variant is not None:
+        merged = _deep_merge(merged, variants[variant])
+    return merged
+
+
+def board_variants(board_dir: str | Path) -> list[str]:
+    """Names of the ``variants:`` declared in a board's ``board.yaml``."""
+    return list(_read_yaml(Path(board_dir) / "board.yaml").get("variants", {}))

labgrid_boardkit/ptest/test_ptests.py

@@ -0,0 +1,28 @@
+"""ptest-runner suite for any qemu board, e.g.
+
+uv run pytest --lg-env boards/qemux86-64/env.yaml --pyargs labgrid_boardkit.ptest
+"""
+
+import os
+
+
+class TestPtests:
+    def test_system_booted(self, shell):
+        stdout, stderr, rc = shell.run("echo hello")
+        assert rc == 0
+        assert "hello" in stdout
+
+    def test_kernel_version(self, shell):
+        stdout, stderr, rc = shell.run("uname -r")
+        assert rc == 0
+        assert len(stdout) > 0
+        print(f"Kernel version: {stdout[0]}")
+
+    def test_ptests(self, shell):
+        timeout = int(os.environ.get("PTEST_TIMEOUT", 1200))
+        cmd = "ptest-runner"
+        # ptest-runner kills a ptest silent for this long (its default: 300s)
+        if runner_timeout := os.environ.get("PTEST_RUNNER_TIMEOUT"):
+            cmd += f" -t {int(runner_timeout)}"
+        stdout, stderr, rc = shell.run(cmd, timeout=timeout)
+        assert rc == 0

labgrid_boardkit/render.py

@@ -0,0 +1,147 @@
+"""Render labgrid client.yaml (or env.yaml for qemu) from a board manifest.
+
+Each ``variants:`` entry renders to ``client-<variant>.yaml`` alongside. All
+boards' Yocto MACHINEs are also indexed in ``boards/machines.tsv``, a flat
+table the CI shell steps can read without a YAML parser.
+
+CLI:
+    boardkit-render                       # renders client.yaml for every boards/*/board.yaml under the repo root (cwd)
+    boardkit-render <board_dir> [...]     # renders only the given boards (the index always covers all of them)
+    boardkit-render --check               # non-destructive; exit 1 if any rendered output differs
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, StrictUndefined
+
+from labgrid_boardkit.manifest import board_variants, load_board
+
+_STRATEGY_TO_TEMPLATE = {
+    "tftp": ("client-tftp.yaml.j2", "client.yaml"),
+    "sdmux": ("client-sdmux.yaml.j2", "client.yaml"),
+    "fastboot": ("client-fastboot.yaml.j2", "client.yaml"),
+    "qemu": ("client-qemu.yaml.j2", "env.yaml"),
+}
+
+INDEX_NAME = "machines.tsv"
+INDEX_COLUMNS = (
+    "machine",
+    "board",
+    "variant",
+    "strategy",
+    "remote_place",
+    "tftp_subdir",
+    "initramfs",
+    "nightly",
+    "client",
+    "image_dir",
+)
+
+
+def _env() -> Environment:
+    return Environment(
+        loader=PackageLoader("labgrid_boardkit", "templates"),
+        undefined=StrictUndefined,
+        keep_trailing_newline=True,
+    )
+
+
+def _template(board_dir: Path, manifest: dict, variant: str | None) -> tuple[str, str]:
+    """Return ``(template_name, output_file_name)`` for a manifest."""
+    strategy = manifest.get("strategy")
+    if strategy not in _STRATEGY_TO_TEMPLATE:
+        raise ValueError(f"{board_dir}: unknown strategy {strategy!r}")
+    template_name, out_name = _STRATEGY_TO_TEMPLATE[strategy]
+    if variant is not None:
+        out_name = out_name.replace(".yaml", f"-{variant}.yaml")
+    return template_name, out_name
+
+
+def render(board_dir: str | Path, variant: str | None = None) -> tuple[Path, str]:
+    """Return ``(output_path, rendered_yaml_text)`` for a board or one of its variants."""
+    board_dir = Path(board_dir)
+    manifest = load_board(board_dir, variant)
+    template_name, out_name = _template(board_dir, manifest, variant)
+    tmpl = _env().get_template(template_name)
+    return board_dir / out_name, tmpl.render(manifest=manifest)
+
+
+def render_index(board_dirs: list[Path]) -> str:
+    """Return the tab-separated MACHINE index: one row per board and variant."""
+    lines = ["\t".join(INDEX_COLUMNS)]
+    for board_dir in board_dirs:
+        manifests = [(v, load_board(board_dir, v)) for v in [None, *board_variants(board_dir)]]
+        # CI boots a machine's first row unless asked for a boot_method, so a
+        # variant marked `default: true` goes ahead of the board's other rows.
+        defaults = [m.get("yocto_machine") for v, m in manifests if v and m.get("default")]
+        if len(defaults) != len(set(defaults)):
+            raise ValueError(f"{board_dir}: more than one default variant for a yocto_machine")
+        manifests.sort(key=lambda vm: not (vm[0] and vm[1].get("default")))
+        for variant, m in manifests:
+            tftp = m.get("tftp", {})
+            row = {
+                "machine": m.get("yocto_machine"),
+                "board": board_dir.name,
+                "variant": variant,
+                "strategy": m.get("strategy"),
+                "remote_place": m.get("remote_place"),
+                "tftp_subdir": tftp.get("subdir", board_dir.name),
+                # "fit": kernel, DTB and initramfs come bundled in one FIT image.
+                "initramfs": (
+                    "fit"
+                    if tftp.get("kernel") == "fitImage"
+                    else "yes"
+                    if "initramfs" in tftp
+                    else "no"
+                ),
+                "nightly": "no" if m.get("exclude_from_nightly") else "yes",
+                "client": _template(board_dir, m, variant)[1],
+                "image_dir": m["fastboot"]["image_dir"] if m["strategy"] == "fastboot" else None,
+            }
+            lines.append("\t".join(str(row[c] or "-") for c in INDEX_COLUMNS))
+    return "\n".join(lines) + "\n"
+
+
+def _find_boards(root: Path) -> list[Path]:
+    return [p.parent for p in sorted(root.glob("*/board.yaml"))]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Render labgrid client.yaml from board.yaml")
+    parser.add_argument("board_dirs", nargs="*", type=Path)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Exit non-zero if any rendered output differs from the on-disk file.",
+    )
+    args = parser.parse_args(argv)
+
+    root = args.board_dirs[0].parent if args.board_dirs else Path.cwd() / "boards"
+    all_boards = _find_boards(root)
+    board_dirs = args.board_dirs or all_boards
+    if not board_dirs:
+        print("no boards found", file=sys.stderr)
+        return 2
+
+    outputs = [render(bd, v) for bd in board_dirs for v in [None, *board_variants(bd)]]
+    outputs.append((root / INDEX_NAME, render_index(all_boards)))
+
+    diffs = 0
+    for out_path, rendered in outputs:
+        if args.check:
+            existing = out_path.read_text() if out_path.exists() else ""
+            if existing != rendered:
+                diffs += 1
+                print(f"DIFF  {out_path}")
+            else:
+                print(f"ok    {out_path}")
+        else:
+            out_path.write_text(rendered)
+            print(f"wrote {out_path}")
+    return 1 if (args.check and diffs) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

labgrid_boardkit/schema/board.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/threexc/labgrid-boardkit/board.schema.json",
+  "title": "labgrid-boardkit board manifest",
+  "type": "object",
+  "required": ["name", "strategy", "arch"],
+  "additionalProperties": true,
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "arch": { "type": "string" },
+    "description": { "type": "string" },
+    "strategy": { "enum": ["tftp", "sdmux", "fastboot", "qemu"] },
+    "remote_place": { "type": "string" },
+    "image_source": { "type": "string" },
+    "yocto_machine": { "type": "string" },
+    "exclude_from_nightly": { "type": "boolean" },
+    "default": {
+      "type": "boolean",
+      "description": "Set in a variant: CI boots this variant, not the base board, for its yocto_machine unless a workflow's boot_method says otherwise."
+    },
+    "inherits": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths to defaults.yaml files, merged in order (later overrides earlier). board.yaml wins."
+    },
+    "boot": {
+      "type": "object",
+      "properties": {
+        "method": { "type": "string" },
+        "bootargs": { "type": "string" },
+        "kernel_addr": { "type": "string" },
+        "dtb_addr": { "type": "string" },
+        "ramdisk_addr": { "type": "string" }
+      }
+    },
+    "tftp": {
+      "type": "object",
+      "properties": {
+        "subdir": { "type": "string" },
+        "kernel": { "type": "string" },
+        "dtb": { "type": "string" },
+        "initramfs": { "type": "string" }
+      }
+    },
+    "uboot": { "type": "object" },
+    "shell": {
+      "type": "object",
+      "properties": {
+        "username": { "type": "string" },
+        "password": { "type": ["string", "null"] },
+        "prompt": { "type": "string" },
+        "login_prompt": { "type": "string" }
+      }
+    },
+    "image": {
+      "type": "object",
+      "properties": {
+        "label": { "type": "string" },
+        "path": { "type": "string" }
+      }
+    },
+    "tools": { "type": "object" },
+    "buttons": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Relay-driven buttons, each exported as <name>-<button>-gpio-1"
+    },
+    "fastboot": {
+      "type": "object",
+      "properties": {
+        "image_dir": { "type": "string" },
+        "recovery_button": { "type": "string" },
+        "reset_button": { "type": "string" },
+        "stage": { "type": "array", "items": { "type": "string" } },
+        "flash": {
+          "type": "object",
+          "additionalProperties": { "type": ["string", "null"] },
+          "description": "Partition name to image file, in flash order. null skips a partition (a variant dropping one of the base board's)."
+        },
+        "press_time": { "type": "number" },
+        "power_on_delay": { "type": "number" },
+        "continue_delay": { "type": "number" },
+        "stage_retries": { "type": "integer" }
+      }
+    },
+    "qemu": {
+      "type": "object",
+      "properties": {
+        "binary": { "type": "string" },
+        "machine": { "type": "string" },
+        "cpu": { "type": "string" },
+        "memory": { "type": ["integer", "string"] },
+        "virtio_bus": { "enum": ["mmio", "pci"] },
+        "accel": { "type": "array", "items": { "type": "string" } },
+        "ssh_port": { "type": "integer" },
+        "telnet_port": { "type": "integer" }
+      }
+    },
+    "images": { "type": "object" },
+    "strategy_class": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "strategy": { "const": "tftp" } }, "required": ["strategy"] },
+      "then": {
+        "required": ["boot", "tftp"],
+        "properties": {
+          "boot": {
+            "required": ["bootargs", "kernel_addr"]
+          },
+          "tftp": {
+            "required": ["subdir", "kernel"]
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "strategy": { "const": "sdmux" } }, "required": ["strategy"] },
+      "then": {
+        "required": ["image"],
+        "properties": {
+          "image": { "required": ["label", "path"] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "strategy": { "const": "fastboot" } }, "required": ["strategy"] },
+      "then": {
+        "required": ["fastboot", "buttons"],
+        "properties": {
+          "fastboot": { "required": ["image_dir", "recovery_button", "reset_button", "flash"] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "strategy": { "const": "qemu" } }, "required": ["strategy"] },
+      "then": {
+        "required": ["qemu", "images"],
+        "properties": {
+          "qemu": { "required": ["binary", "machine"] }
+        }
+      }
+    }
+  ]
+}

labgrid_boardkit/strategies/__init__.py

@@ -0,0 +1,25 @@
+"""labgrid-boardkit strategy families.
+
+Import the family classes from here or (preferred at scale) resolve them by
+name via ``labgrid_boardkit.loader.strategy_for(manifest)``, which consults
+the ``labgrid_boardkit.strategies`` entry-point registry declared in ``pyproject.toml``.
+"""
+
+from labgrid_boardkit.strategies.base import BoardStrategy
+from labgrid_boardkit.strategies.fastboot import FastbootFlashStrategy, FastbootStatus
+from labgrid_boardkit.strategies.qemu import ExternalQemuStrategy, QemuBootStrategy, QemuStatus
+from labgrid_boardkit.strategies.sdmux import SdMuxBootStrategy, SdMuxStatus
+from labgrid_boardkit.strategies.tftp import TftpBootStrategy, TftpStatus
+
+__all__ = [
+    "BoardStrategy",
+    "ExternalQemuStrategy",
+    "FastbootFlashStrategy",
+    "FastbootStatus",
+    "QemuBootStrategy",
+    "QemuStatus",
+    "SdMuxBootStrategy",
+    "SdMuxStatus",
+    "TftpBootStrategy",
+    "TftpStatus",
+]

labgrid_boardkit/strategies/base.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import attr
+from labgrid.strategy.common import Strategy
+
+from labgrid_boardkit.manifest import load_board
+
+
+@attr.s(eq=False)
+class BoardStrategy(Strategy):
+    """Base for all labgrid-boardkit strategies.
+
+    Two ways to attach a manifest to a strategy instance:
+
+    1. **Per-board subclass** (default): the concrete subclass sets ``manifest``
+       as a class attribute, typically ``manifest = load_board(Path(__file__).parent)``.
+
+    2. **``manifest_path`` kwarg** (zero-Python boards): pass ``manifest_path``
+       from labgrid ``client.yaml``. The base ``__attrs_post_init__`` loads it.
+       Path is resolved absolute or relative to cwd.
+
+    Family subclasses (tftp, sdmux, ...) must call ``super().__attrs_post_init__()``.
+    """
+
+    manifest_path = attr.ib(default=None)
+
+    manifest: dict = {}
+
+    def __attrs_post_init__(self):
+        super().__attrs_post_init__()
+        if self.manifest_path is not None:
+            self.manifest = load_board(Path(self.manifest_path))