labgrid-boardkit 0.1.0__tar.gz

labgrid_boardkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trevor Gamblin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

labgrid_boardkit-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: labgrid-boardkit
+Version: 0.1.0
+Summary: Board manifests, boot strategies, fixtures and test suites for labgrid
+Author: Trevor Gamblin
+Author-email: Trevor Gamblin <tgamblin@baylibre.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: jinja2
+Requires-Dist: jsonschema
+Requires-Dist: labgrid>=26.0
+Requires-Dist: pytest
+Requires-Dist: pyyaml
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/threexc/labgrid-boardkit
+Description-Content-Type: text/markdown
+
+# labgrid-boardkit
+
+Board manifests, boot strategies, pytest fixtures and test suites for
+[labgrid](https://github.com/labgrid-project/labgrid).
+
+Describe a board once in a `board.yaml` manifest, and labgrid-boardkit
+generates its labgrid `client.yaml` and drives it through a reusable boot
+strategy family:
+
+| Family     | Boots via                                   |
+|------------|---------------------------------------------|
+| `tftp`     | U-Boot `tftpboot` (kernel, DTB, initramfs/FIT) |
+| `sdmux`    | an SD card image written through a USB-SD-Mux |
+| `fastboot` | images flashed to eMMC/NOR over fastboot    |
+| `qemu`     | QEMU, no hardware needed                    |
+
+## Install
+
+```
+pip install labgrid-boardkit
+```
+
+## Usage
+
+Lay out your boards as `boards/<name>/board.yaml`. Shared settings can go in
+a file listed under `inherits:`. For example (`tests/fixtures/boards/` has one
+board per family, plus a shared `families/` file and a variant):
+
+```yaml
+name: example-qemu
+yocto_machine: qemuriscv64
+strategy: qemu
+arch: riscv64
+description: QEMU RISC-V virt machine, no hardware needed
+
+boot:
+  bootargs: root=/dev/vda rw console=ttyS0
+
+qemu:
+  binary: qemu-system-riscv64
+  machine: virt
+  cpu: rv64
+  memory: 2048
+  ssh_port: 2222
+  telnet_port: 2323
+
+images:
+  bios: /srv/images/example-qemu/fw_jump.elf
+  kernel: /srv/images/example-qemu/Image
+  ext4: /srv/images/example-qemu/rootfs.ext4
+
+shell:
+  username: root
+```
+
+From the directory that contains `boards/`:
+
+```
+boardkit-validate          # check every boards/*/board.yaml against the schema
+boardkit-render            # write each board's client.yaml/env.yaml and boards/machines.tsv
+boardkit-render --check    # exit 1 if any rendered file is out of date (for CI)
+```
+
+Installing the package also registers a pytest plugin. It picks `--lg-env`
+from `$BOARD` or the nearest `client.yaml`, and provides the `tftp`, `sd` and
+`fastboot` fixtures. Generic on-target suites ship with the package:
+
+```
+BOARD=boards/my-board pytest --pyargs labgrid_boardkit.tests
+pytest --lg-env boards/example-qemu/env.yaml --pyargs labgrid_boardkit.ptest
+```
+
+## Adding a strategy family
+
+Families are found through the `labgrid_boardkit.strategies` entry-point
+group, so another package can add one without changing this one:
+
+```toml
+[project.entry-points."labgrid_boardkit.strategies"]
+myfamily = "my_package.strategies:MyBootStrategy"
+```
+
+## Development
+
+```
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```

labgrid_boardkit-0.1.0/README.md

@@ -0,0 +1,88 @@
+# labgrid-boardkit
+
+Board manifests, boot strategies, pytest fixtures and test suites for
+[labgrid](https://github.com/labgrid-project/labgrid).
+
+Describe a board once in a `board.yaml` manifest, and labgrid-boardkit
+generates its labgrid `client.yaml` and drives it through a reusable boot
+strategy family:
+
+| Family     | Boots via                                   |
+|------------|---------------------------------------------|
+| `tftp`     | U-Boot `tftpboot` (kernel, DTB, initramfs/FIT) |
+| `sdmux`    | an SD card image written through a USB-SD-Mux |
+| `fastboot` | images flashed to eMMC/NOR over fastboot    |
+| `qemu`     | QEMU, no hardware needed                    |
+
+## Install
+
+```
+pip install labgrid-boardkit
+```
+
+## Usage
+
+Lay out your boards as `boards/<name>/board.yaml`. Shared settings can go in
+a file listed under `inherits:`. For example (`tests/fixtures/boards/` has one
+board per family, plus a shared `families/` file and a variant):
+
+```yaml
+name: example-qemu
+yocto_machine: qemuriscv64
+strategy: qemu
+arch: riscv64
+description: QEMU RISC-V virt machine, no hardware needed
+
+boot:
+  bootargs: root=/dev/vda rw console=ttyS0
+
+qemu:
+  binary: qemu-system-riscv64
+  machine: virt
+  cpu: rv64
+  memory: 2048
+  ssh_port: 2222
+  telnet_port: 2323
+
+images:
+  bios: /srv/images/example-qemu/fw_jump.elf
+  kernel: /srv/images/example-qemu/Image
+  ext4: /srv/images/example-qemu/rootfs.ext4
+
+shell:
+  username: root
+```
+
+From the directory that contains `boards/`:
+
+```
+boardkit-validate          # check every boards/*/board.yaml against the schema
+boardkit-render            # write each board's client.yaml/env.yaml and boards/machines.tsv
+boardkit-render --check    # exit 1 if any rendered file is out of date (for CI)
+```
+
+Installing the package also registers a pytest plugin. It picks `--lg-env`
+from `$BOARD` or the nearest `client.yaml`, and provides the `tftp`, `sd` and
+`fastboot` fixtures. Generic on-target suites ship with the package:
+
+```
+BOARD=boards/my-board pytest --pyargs labgrid_boardkit.tests
+pytest --lg-env boards/example-qemu/env.yaml --pyargs labgrid_boardkit.ptest
+```
+
+## Adding a strategy family
+
+Families are found through the `labgrid_boardkit.strategies` entry-point
+group, so another package can add one without changing this one:
+
+```toml
+[project.entry-points."labgrid_boardkit.strategies"]
+myfamily = "my_package.strategies:MyBootStrategy"
+```
+
+## Development
+
+```
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```

labgrid_boardkit-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["uv_build>=0.7,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "labgrid-boardkit"
+version = "0.1.0"
+description = "Board manifests, boot strategies, fixtures and test suites for labgrid"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Framework :: Pytest",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "jinja2",
+    "jsonschema",
+    "labgrid>=26.0",
+    "pytest",
+    "pyyaml",
+]
+
+[[project.authors]]
+name = "Trevor Gamblin"
+email = "tgamblin@baylibre.com"
+
+[project.urls]
+Repository = "https://github.com/threexc/labgrid-boardkit"
+
+[project.scripts]
+boardkit-validate = "labgrid_boardkit.validate:main"
+boardkit-render = "labgrid_boardkit.render:main"
+
+[project.entry-points.pytest11]
+labgrid_boardkit = "labgrid_boardkit.fixtures"
+
+[project.entry-points."labgrid_boardkit.strategies"]
+tftp = "labgrid_boardkit.strategies.tftp:TftpBootStrategy"
+sdmux = "labgrid_boardkit.strategies.sdmux:SdMuxBootStrategy"
+fastboot = "labgrid_boardkit.strategies.fastboot:FastbootFlashStrategy"
+qemu = "labgrid_boardkit.strategies.qemu:QemuBootStrategy"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]
+ignore = ["E501"]
+
+[dependency-groups]
+dev = ["ruff>=0.14"]

labgrid_boardkit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["uv_build>=0.7,<0.14"]
+build-backend = "uv_build"
+
+[project]
+name = "labgrid-boardkit"
+version = "0.1.0"
+description = "Board manifests, boot strategies, fixtures and test suites for labgrid"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Trevor Gamblin", email = "tgamblin@baylibre.com" }]
+requires-python = ">=3.11"
+classifiers = [
+    "Framework :: Pytest",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "jinja2",
+    "jsonschema",
+    "labgrid>=26.0",
+    "pytest",
+    "pyyaml",
+]
+
+[project.urls]
+Repository = "https://github.com/threexc/labgrid-boardkit"
+
+[project.scripts]
+boardkit-validate = "labgrid_boardkit.validate:main"
+boardkit-render = "labgrid_boardkit.render:main"
+
+# Auto-loaded into any pytest run inside this venv:
+[project.entry-points.pytest11]
+labgrid_boardkit = "labgrid_boardkit.fixtures"
+
+# Strategy family registry. Add a line here to expose a new family; third-party
+# packages register in the same group.
+[project.entry-points."labgrid_boardkit.strategies"]
+tftp = "labgrid_boardkit.strategies.tftp:TftpBootStrategy"
+sdmux = "labgrid_boardkit.strategies.sdmux:SdMuxBootStrategy"
+fastboot = "labgrid_boardkit.strategies.fastboot:FastbootFlashStrategy"
+qemu = "labgrid_boardkit.strategies.qemu:QemuBootStrategy"
+
+[tool.pytest.ini_options]
+# src/labgrid_boardkit/{tests,ptest} are on-target suites needing labgrid
+# hardware or QEMU; run those with `pytest --pyargs labgrid_boardkit.tests`.
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]

labgrid_boardkit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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