From ba408242529d33195de3f706c321dc3e92197b91 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 22:55:15 +0100 Subject: [PATCH 1/4] S1: the core opens a board, reads its model, validates and generates The core's first workspace is a board of an EmbLinkRTOS checkout, until the project manifest exists (spec section 8: S1 to S3 work on the boards in the RTOS tree and their generated model). - project.open, close, status: a board directory, boards///, inside a checkout. Opening reads files and runs nothing. A checkout whose emb-hwgen or hw.json is outside the formats the core reads (emb-hwgen 0.x, hw.json schema 0) is refused with unsupported_rtos. - board.list, describe, pins, clocks, memory: the generator's resolved model, read from hw.json; nothing is computed, in the core or the GUI. - project.validate, generate.run, generate.diff: run the checkout's own emb-hwgen, with the core's Python, and turn its lines (HW-002) into diagnostics with the file, the line and the path in the YAML. diff writes nothing. - project.trust: running the generator runs the checkout's code, so it waits until the checkout is trusted (spec section 9). Trust is kept per path in the person's own settings, never in a checkout. - Every method has a command too: emblink-studio-core board list RTOS, project validate BOARD, generate diff BOARD, and the rest. - PyYAML becomes the core's dependency: the generator reads YAML with it. Schemas for every new method are in protocol/. Tests: a fake emb-hwgen with the real interface and output, the protocol end to end, and S1's acceptance against the real nucleo_f446re and pico2_w, with errors made in a copy of the NUCLEO's description found at their lines; CI checks out the RTOS at a pinned commit for it. Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- .github/workflows/ci.yml | 15 +- core/pyproject.toml | 3 +- core/src/emblink_studio_core/cli.py | 89 ++++++- core/src/emblink_studio_core/diagnostics.py | 76 ++++++ core/src/emblink_studio_core/errors.py | 28 +++ core/src/emblink_studio_core/hwmodel.py | 155 ++++++++++++ core/src/emblink_studio_core/rtos.py | 140 +++++++++++ core/src/emblink_studio_core/server.py | 90 ++++++- core/src/emblink_studio_core/trust.py | 74 ++++++ core/src/emblink_studio_core/workspace.py | 247 +++++++++++++++++++ core/tests/conftest.py | 65 ++++- core/tests/fake_hwgen.py | 149 +++++++++++ core/tests/test_diagnostics.py | 87 +++++++ core/tests/test_project_rpc.py | 130 ++++++++++ core/tests/test_rtos_acceptance.py | 121 +++++++++ core/tests/test_workspace.py | 224 +++++++++++++++++ docs/development.md | 9 + docs/specification.md | 6 +- protocol/README.md | 9 + protocol/board.clocks.result.schema.json | 37 +++ protocol/board.describe.result.schema.json | 43 ++++ protocol/board.list.params.schema.json | 13 + protocol/board.list.result.schema.json | 138 +++++++++++ protocol/board.memory.result.schema.json | 52 ++++ protocol/board.pins.result.schema.json | 70 ++++++ protocol/generate.diff.result.schema.json | 95 +++++++ protocol/generate.run.result.schema.json | 133 ++++++++++ protocol/project.close.result.schema.json | 5 + protocol/project.open.params.schema.json | 15 ++ protocol/project.open.result.schema.json | 135 ++++++++++ protocol/project.status.result.schema.json | 135 ++++++++++ protocol/project.trust.result.schema.json | 135 ++++++++++ protocol/project.validate.result.schema.json | 64 +++++ third_party/components.json | 8 + 34 files changed, 2777 insertions(+), 18 deletions(-) create mode 100644 core/src/emblink_studio_core/diagnostics.py create mode 100644 core/src/emblink_studio_core/errors.py create mode 100644 core/src/emblink_studio_core/hwmodel.py create mode 100644 core/src/emblink_studio_core/rtos.py create mode 100644 core/src/emblink_studio_core/trust.py create mode 100644 core/src/emblink_studio_core/workspace.py create mode 100755 core/tests/fake_hwgen.py create mode 100644 core/tests/test_diagnostics.py create mode 100644 core/tests/test_project_rpc.py create mode 100644 core/tests/test_rtos_acceptance.py create mode 100644 core/tests/test_workspace.py create mode 100644 protocol/board.clocks.result.schema.json create mode 100644 protocol/board.describe.result.schema.json create mode 100644 protocol/board.list.params.schema.json create mode 100644 protocol/board.list.result.schema.json create mode 100644 protocol/board.memory.result.schema.json create mode 100644 protocol/board.pins.result.schema.json create mode 100644 protocol/generate.diff.result.schema.json create mode 100644 protocol/generate.run.result.schema.json create mode 100644 protocol/project.close.result.schema.json create mode 100644 protocol/project.open.params.schema.json create mode 100644 protocol/project.open.result.schema.json create mode 100644 protocol/project.status.result.schema.json create mode 100644 protocol/project.trust.result.schema.json create mode 100644 protocol/project.validate.result.schema.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c587e82..3d6f873 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,9 @@ # Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. # # S0's acceptance (spec section 8): build and test on Windows, Linux and macOS; initialize -# succeeds; the notices list is generated. +# succeeds; the notices list is generated. S1's: the core opens the RTOS's nucleo_f446re and +# pico2_w boards and reports the generator's errors with their locations, against the RTOS +# checked out at a pinned commit. name: CI on: @@ -34,7 +36,18 @@ jobs: - run: python -m pip install -e "core[dev]" - run: ruff check core tools - run: ruff format --check core tools + - name: EmbLinkRTOS, for stage S1's acceptance tests + uses: actions/checkout@v7 + with: + repository: EmbLinkOs/EmbLinkRTOS + # The RTOS revision the core is tested against. Raise it with the hw.json and + # diagnostics formats the core supports (core/src/emblink_studio_core/rtos.py). + ref: a2cb045cf27a0f53bc53ce110d3bffc4d381817f + path: rtos + persist-credentials: false - run: python -m pytest core -q + env: + EMBLINK_STUDIO_TEST_RTOS: ${{ github.workspace }}/rtos - name: Notices list and licence check run: python tools/notices.py --components third_party/components.json --pyproject core/pyproject.toml diff --git a/core/pyproject.toml b/core/pyproject.toml index 5b4528a..822e1e0 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -16,7 +16,8 @@ description = "EmbLink Studio Core: the engine behind the EmbLink Studio IDE for license = "Apache-2.0" requires-python = ">=3.11" # Runtime dependencies must also be listed in third_party/components.json (tools/notices.py checks). -dependencies = [] +# PyYAML: the RTOS's generator, which the core runs with its own Python, reads YAML with it. +dependencies = ["PyYAML>=6.0"] [project.optional-dependencies] dev = ["pytest>=8", "jsonschema>=4.21", "ruff>=0.6"] diff --git a/core/src/emblink_studio_core/cli.py b/core/src/emblink_studio_core/cli.py index 96cb023..f6a1104 100644 --- a/core/src/emblink_studio_core/cli.py +++ b/core/src/emblink_studio_core/cli.py @@ -10,17 +10,75 @@ """The `emblink-studio-core` command line. `serve` runs the JSON-RPC server on standard input and output; `--version` prints the -core's version and the protocol it speaks. Every RPC method gains a subcommand as it -lands (spec section 4). +core's version and the protocol it speaks. Every RPC method has a subcommand too +(spec section 4), printing the same result as JSON: + + emblink-studio-core project status BOARD + emblink-studio-core project validate BOARD exit 0 if valid, 2 if not + emblink-studio-core board list RTOS + emblink-studio-core board describe|pins|clocks|memory BOARD + emblink-studio-core generate run BOARD + emblink-studio-core generate diff BOARD exit 0 if up to date, 1 if not + +BOARD is a board directory of an EmbLinkRTOS checkout, such as +~/EmbLinkRTOS/boards/st/nucleo_f446re; RTOS is the checkout. The person running a +command chose to run the checkout's generator, so the command line does not ask for +trust; the IDE does (spec section 9). """ from __future__ import annotations import argparse +import json +import sys +from pathlib import Path +from typing import Any from . import __version__, protocol +def _print(result: Any) -> None: + json.dump(result, sys.stdout, indent=2, ensure_ascii=False) + sys.stdout.write("\n") + + +def _run(args: argparse.Namespace) -> int: + from .rtos import Rtos + from .workspace import Workspace, list_boards + + if args.command == "board" and args.action == "list": + rtos = Rtos.find(Path(args.target).expanduser().resolve()) + if rtos is None: + print(f"{args.target} is not an EmbLinkRTOS checkout.", file=sys.stderr) + return 1 + _print( + { + "rtos": {"root": str(rtos.root), "generator": rtos.check_supported()}, + "boards": list_boards(rtos), + } + ) + return 0 + + workspace = Workspace.open(args.target) + if args.command == "project" and args.action == "status": + _print(workspace.status(trusted=True)) + return 0 + if args.command == "project" and args.action == "validate": + result = workspace.validate() + _print(result) + return 0 if result["valid"] else 2 + if args.command == "board": + _print(getattr(workspace.model(), args.action)()) + return 0 + if args.command == "generate" and args.action == "run": + result = workspace.generate() + _print(result) + return 0 if result["written"] else 2 + result = workspace.diff() + _print(result) + return 0 if result["up_to_date"] else 1 + + def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(prog="emblink-studio-core", description="EmbLink Studio Core") parser.add_argument( @@ -30,11 +88,34 @@ def main(argv: list[str] | None = None) -> int: ) commands = parser.add_subparsers(dest="command", metavar="command") commands.add_parser("serve", help="serve JSON-RPC 2.0 on standard input and output") + + project = commands.add_parser("project", help="a board's status and validation") + project.add_argument("action", choices=["status", "validate"]) + project.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout") + board = commands.add_parser("board", help="the boards of a checkout, and a board's model") + board.add_argument("action", choices=["list", "describe", "pins", "clocks", "memory"]) + board.add_argument( + "target", metavar="BOARD_OR_RTOS", help="the checkout for list, a board directory otherwise" + ) + generate = commands.add_parser( + "generate", help="run the generator, or see what it would change" + ) + generate.add_argument("action", choices=["run", "diff"]) + generate.add_argument("target", metavar="BOARD", help="a board directory of an RTOS checkout") args = parser.parse_args(argv) if args.command == "serve": from .server import serve return serve() - parser.print_help() - return 2 + if args.command is None: + parser.print_help() + return 2 + + from .errors import CoreError + + try: + return _run(args) + except CoreError as exc: + print(exc.message, file=sys.stderr) + return 1 diff --git a/core/src/emblink_studio_core/diagnostics.py b/core/src/emblink_studio_core/diagnostics.py new file mode 100644 index 0000000..f7ebec3 --- /dev/null +++ b/core/src/emblink_studio_core/diagnostics.py @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: diagnostics.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""The generator's diagnostics, as structured records the views can link to a file. + +emb-hwgen 0.x writes one diagnostic per line (the RTOS's rule HW-002): + + boards/st/nucleo_f446re/board.yaml:25: pins.usart2.tx: PA2 af9 is not usart2_tx + warning: soc/st/stm32f4/stm32f4.yaml:17: cpu.mpu: the cortex_m port does not use the MPU yet + +that is, an optional 'warning: ', then the file (relative to the checkout, or absolute +for a board outside it), the line, the node's path in the YAML ('(root)' for the +document) and the message. Each becomes + + {"severity", "message", "file", "line", "path", "source"} + +with the file made absolute, so a view opens it at the line. Lines that are not +diagnostics (the generator's own summary) are dropped; a line in no known form is +kept as a diagnostic with only its message, so nothing the generator says is lost. +When the generator writes JSON diagnostics (asked of the RTOS for S1), they are read +instead and this parser stays for older checkouts. +""" + +from __future__ import annotations + +import re +from pathlib import Path +from typing import Any + +SOURCE = "emb-hwgen" +_LOCATED = re.compile(r"^(?P.+?):(?P\d+): (?P.*)$") +_PATH = re.compile(r"^(?P[^\s:]+): (?P.+)$") + + +def parse(text: str, root: Path) -> list[dict[str, Any]]: + """The diagnostics in emb-hwgen's output `text`; relative files are under `root`.""" + out: list[dict[str, Any]] = [] + for raw in text.splitlines(): + line = raw.strip() + if not line or line.startswith("emb-hwgen"): + continue # blank, or the generator's summary ('emb-hwgen: 8 error(s)') + severity = "error" + if line.startswith("warning: "): + severity = "warning" + line = line[len("warning: ") :] + diagnostic: dict[str, Any] = {"severity": severity, "source": SOURCE} + located = _LOCATED.match(line) + if located is None: + diagnostic["message"] = line + out.append(diagnostic) + continue + file = Path(located["file"]) + diagnostic["file"] = str(file if file.is_absolute() else root / file) + diagnostic["line"] = int(located["line"]) + rest = located["rest"] + with_path = _PATH.match(rest) + if with_path is not None: + diagnostic["path"] = with_path["path"] + diagnostic["message"] = with_path["message"] + else: + diagnostic["message"] = rest + out.append(diagnostic) + return out + + +def counts(diagnostics: list[dict[str, Any]]) -> dict[str, int]: + return { + "errors": sum(1 for d in diagnostics if d["severity"] == "error"), + "warnings": sum(1 for d in diagnostics if d["severity"] == "warning"), + } diff --git a/core/src/emblink_studio_core/errors.py b/core/src/emblink_studio_core/errors.py new file mode 100644 index 0000000..719e5bb --- /dev/null +++ b/core/src/emblink_studio_core/errors.py @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: errors.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""The core's error, shared by the server, the command line and the project code. + +A CoreError carries one of the protocol's error codes (spec section 5, Errors), a +message written for the person, and optional data: the output of the tool that +failed and, where it applies, the file and line. The server answers it as a JSON-RPC +error; the command line prints its message and exits with 1. +""" + +from __future__ import annotations + +from typing import Any + + +class CoreError(Exception): + def __init__(self, code: int, message: str, data: Any = None) -> None: + super().__init__(message) + self.code = code + self.message = message + self.data = data diff --git a/core/src/emblink_studio_core/hwmodel.py b/core/src/emblink_studio_core/hwmodel.py new file mode 100644 index 0000000..759e8b2 --- /dev/null +++ b/core/src/emblink_studio_core/hwmodel.py @@ -0,0 +1,155 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: hwmodel.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""A board's resolved model, read from the hw.json emb-hwgen writes. + +hw.json (schema version 0, hw/schemas/hw.schema.json in the RTOS) holds the board and +its SoC as the generator resolved them, and what it derived: the clock tree, the pins +in use, the devices, the linker regions and partitions. The board.* methods answer +from it (spec section 5: "From the generator's resolved model; nothing computed in +the GUI"), and the core computes nothing either: each view is a selection of hw.json, +its values exactly the generator's. +""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any + +from . import protocol +from .errors import CoreError +from .rtos import SUPPORTED_HW_SCHEMAS + + +class HwModel: + def __init__(self, data: dict[str, Any], path: Path) -> None: + self.data = data + self.path = path + + @classmethod + def load(cls, path: Path) -> HwModel: + try: + data = json.loads(path.read_text(encoding="utf-8")) + except OSError as exc: + raise CoreError(protocol.INVALID_REQUEST, f"Cannot read {path}: {exc}") from exc + except json.JSONDecodeError as exc: + raise CoreError( + protocol.TOOL_FAILED, f"{path} is not valid JSON: {exc}", {"file": str(path)} + ) from exc + version = data.get("schema_version") + if version not in SUPPORTED_HW_SCHEMAS: + raise CoreError( + protocol.UNSUPPORTED_RTOS, + f"{path} is hw.json schema {version}; EmbLink Studio reads schema " + f"{', '.join(map(str, sorted(SUPPORTED_HW_SCHEMAS)))}.", + {"file": str(path)}, + ) + return cls(data, path) + + def _section(self, name: str) -> dict[str, Any]: + value = self.data.get(name) + return value if isinstance(value, dict) else {} + + @property + def board(self) -> dict[str, Any]: + return self._section("board") + + @property + def soc(self) -> dict[str, Any]: + return self._section("soc") + + @property + def derived(self) -> dict[str, Any]: + return self._section("derived") + + def summary(self) -> dict[str, Any]: + """A line about the board, for lists: its name, SoC, CPU and clock.""" + clock = self.derived.get("clock", {}) + cpu = self.soc.get("cpu", {}) + return { + "name": self.board.get("name"), + "vendor": self.board.get("vendor"), + "revision": self.board.get("revision"), + "curated": bool(self.board.get("curated")), + "soc": self.soc.get("part") or self.soc.get("name"), + "family": self.soc.get("family"), + "package": self.soc.get("package"), + "core": cpu.get("core") if isinstance(cpu, dict) else None, + "cpu_hz": clock.get("cpu_hz") if isinstance(clock, dict) else None, + } + + def describe(self) -> dict[str, Any]: + """The board and its chip: what the Board view shows (spec section 7).""" + board_keys = ( + "name", + "vendor", + "revision", + "doc", + "curated", + "console", + "debug_probe", + "leds", + "buttons", + "simulation", + "defaults", + ) + soc_keys = ( + "name", + "part", + "vendor", + "family", + "package", + "curated", + "cpu", + "arch", + "debug", + "interrupts", + "peripherals", + ) + return { + "board": {k: self.board[k] for k in board_keys if k in self.board}, + "soc": {k: self.soc[k] for k in soc_keys if k in self.soc}, + "devices": self.derived.get("devices", []), + "profile": self.derived.get("profile"), + "kconfig": self.derived.get("kconfig", {}), + "generator": self.data.get("generator", {}), + "inputs": self.data.get("inputs", []), + "warnings": self.data.get("warnings", []), + } + + def pins(self) -> dict[str, Any]: + """The pins in use, with their owner, and every pin's alternate functions.""" + gpio = self.soc.get("gpio", {}) + return { + "package": self.soc.get("package"), + "assigned": self.derived.get("pins", []), + "alternate_functions": self.soc.get("alternate_functions", {}), + "ports": gpio.get("ports", {}) if isinstance(gpio, dict) else {}, + } + + def clocks(self) -> dict[str, Any]: + """The clock tree the generator resolved, what the board asked for, the chip's limits.""" + return { + "resolved": self.derived.get("clock", {}), + "requested": self.board.get("clocks", {}), + "oscillators": self.board.get("oscillators", {}), + "limits": self.soc.get("clocks", {}), + "timer": self.derived.get("timer", {}), + } + + def memory(self) -> dict[str, Any]: + """The chip's memory regions, the flash's geometry, the linker's regions, the partitions.""" + memory = self.soc.get("memory", {}) + return { + "regions": memory.get("regions", []) if isinstance(memory, dict) else [], + "flash": self.soc.get("flash", {}), + "linker": self.derived.get("linker", {}), + "partitions": self.derived.get("partitions", []), + } diff --git a/core/src/emblink_studio_core/rtos.py b/core/src/emblink_studio_core/rtos.py new file mode 100644 index 0000000..4f4ed8a --- /dev/null +++ b/core/src/emblink_studio_core/rtos.py @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: rtos.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""An EmbLinkRTOS checkout, and its hardware generator, emb-hwgen (spec section 4). + +The core never carries a copy of the RTOS's tools: it runs the emb-hwgen of the +checkout a board belongs to, as a subprocess, and reads what it writes. It also never +imports the RTOS's code into its own process; the generator's version is read from +its source. + +The Python that runs the generator is the core's own, or EMBLINK_STUDIO_RTOS_PYTHON +when set. The generator's only third-party dependency is PyYAML, which the core +therefore depends on too. + +Supported formats (spec section 4: the core states the range it supports): hw.json +schema version 0, and the diagnostics of emb-hwgen 0.x, one per line as +'file:line: node.path: message' (the RTOS's rule HW-002). A checkout outside that +range is refused with unsupported_rtos. +""" + +from __future__ import annotations + +import os +import re +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path + +from . import protocol +from .errors import CoreError + +HWGEN = Path("hw/gen/emb-hwgen.py") +HWGEN_PACKAGE = Path("hw/gen/emb_hwgen/__init__.py") +SUPPORTED_HW_SCHEMAS = frozenset({0}) +SUPPORTED_GENERATOR_MAJORS = frozenset({0}) +GENERATOR_TIMEOUT_S = 120 + + +def interpreter() -> str: + """The Python that runs the RTOS's tools.""" + return os.environ.get("EMBLINK_STUDIO_RTOS_PYTHON") or sys.executable + + +@dataclass(frozen=True) +class Rtos: + root: Path + + @classmethod + def find(cls, start: Path) -> Rtos | None: + """The checkout `start` is inside of: the nearest directory holding hw/gen/emb-hwgen.py.""" + for directory in (start, *start.parents): + if (directory / HWGEN).is_file(): + return cls(directory) + return None + + def generator(self) -> dict[str, object]: + """emb-hwgen's name, version and the hw.json schema version it writes.""" + try: + source = (self.root / HWGEN_PACKAGE).read_text(encoding="utf-8") + except OSError as exc: + raise CoreError( + protocol.TOOL_MISSING, f"The RTOS checkout at {self.root} has no emb-hwgen package." + ) from exc + version = re.search(r'^VERSION\s*=\s*"([^"]+)"', source, re.M) + schema = re.search(r"^SCHEMA_VERSION\s*=\s*(\d+)", source, re.M) + return { + "name": "emb-hwgen", + "version": version.group(1) if version else "unknown", + "schema_version": int(schema.group(1)) if schema else -1, + } + + def check_supported(self) -> dict[str, object]: + """The generator's facts, or unsupported_rtos when this core cannot read its formats.""" + gen = self.generator() + version = str(gen["version"]) + major = int(version.split(".", 1)[0]) if version.split(".", 1)[0].isdigit() else -1 + if ( + major not in SUPPORTED_GENERATOR_MAJORS + or gen["schema_version"] not in SUPPORTED_HW_SCHEMAS + ): + raise CoreError( + protocol.UNSUPPORTED_RTOS, + f"This RTOS checkout's emb-hwgen {version} writes hw.json schema " + f"{gen['schema_version']}; EmbLink Studio reads emb-hwgen 0.x and hw.json schema " + f"{', '.join(map(str, sorted(SUPPORTED_HW_SCHEMAS)))}.", + {"generator": gen}, + ) + return gen + + def boards(self) -> list[Path]: + """Every board directory of the checkout: boards/// holding board.yaml.""" + return sorted(p.parent for p in (self.root / "boards").glob("*/*/board.yaml")) + + def board_id(self, board_dir: Path) -> str: + """'st/nucleo_f446re' for boards/st/nucleo_f446re.""" + try: + return board_dir.relative_to(self.root / "boards").as_posix() + except ValueError: + return board_dir.name + + def run_hwgen(self, *args: str) -> subprocess.CompletedProcess[str]: + """Runs the checkout's emb-hwgen with `args`, from the checkout's root.""" + script = self.root / HWGEN + if not script.is_file(): + raise CoreError(protocol.TOOL_MISSING, f"emb-hwgen is missing from {self.root}.") + try: + proc = subprocess.run( + [interpreter(), str(script), *args], + cwd=self.root, + capture_output=True, + text=True, + encoding="utf-8", + errors="replace", + timeout=GENERATOR_TIMEOUT_S, + ) + except FileNotFoundError as exc: + raise CoreError( + protocol.TOOL_MISSING, f"The Python that runs the RTOS's tools is missing: {exc}" + ) from exc + except subprocess.TimeoutExpired as exc: + raise CoreError( + protocol.TOOL_FAILED, + f"emb-hwgen did not finish within {GENERATOR_TIMEOUT_S} s.", + {"tool": "emb-hwgen", "args": list(args)}, + ) from exc + if "No module named 'yaml'" in proc.stderr: + raise CoreError( + protocol.TOOL_MISSING, + "The RTOS's generator needs PyYAML in the Python that runs it " + f"({interpreter()}). Install it with: pip install pyyaml", + {"tool": "emb-hwgen", "output": proc.stderr}, + ) + return proc diff --git a/core/src/emblink_studio_core/server.py b/core/src/emblink_studio_core/server.py index 692ad25..9b2718c 100644 --- a/core/src/emblink_studio_core/server.py +++ b/core/src/emblink_studio_core/server.py @@ -9,7 +9,12 @@ # Created: 2026-11-11 """The JSON-RPC server behind `emblink-studio-core serve` (spec sections 4 and 5). -Stage S0 implements the lifecycle only: initialize, initialized, shutdown, exit. +The lifecycle (initialize, initialized, shutdown, exit) and, from stage S1, the +workspace: project.open, close, status, trust and validate; board.list, describe, pins, +clocks and memory, answered from the generator's hw.json; generate.run and diff, which +run the checkout's emb-hwgen. Running the generator needs the checkout trusted first +(spec section 9); everything else only reads files. + Standard output carries protocol traffic and nothing else; the log goes to standard error. Requests before initialize are refused, the exit code is 0 only when exit follows shutdown, and a handler that raises is answered with an internal error instead of @@ -21,22 +26,22 @@ import logging import sys from collections.abc import Callable +from pathlib import Path from typing import Any, BinaryIO from . import __version__, protocol +from .errors import CoreError from .framing import BodyError, FramingError, encode, read_message +from .rtos import Rtos +from .trust import TrustStore +from .workspace import Workspace, list_boards log = logging.getLogger("emblink_studio_core") Handler = Callable[[Any], Any] -class RpcError(Exception): - def __init__(self, code: int, message: str, data: Any = None) -> None: - super().__init__(message) - self.code = code - self.message = message - self.data = data +RpcError = CoreError class Server: @@ -46,9 +51,23 @@ def __init__(self, stdin: BinaryIO, stdout: BinaryIO) -> None: self._initialized = False self._shutdown = False self._exit_code: int | None = None + self._workspace: Workspace | None = None + self._trust = TrustStore() self._requests: dict[str, Handler] = { "initialize": self._initialize, "shutdown": self._shutdown_request, + "project.open": self._project_open, + "project.close": self._project_close, + "project.status": self._project_status, + "project.trust": self._project_trust, + "project.validate": lambda _p: self._trusted().validate(), + "board.list": self._board_list, + "board.describe": lambda _p: self._open().model().describe(), + "board.pins": lambda _p: self._open().model().pins(), + "board.clocks": lambda _p: self._open().model().clocks(), + "board.memory": lambda _p: self._open().model().memory(), + "generate.run": lambda _p: self._trusted().generate(), + "generate.diff": lambda _p: self._trusted().diff(), } self._notifications: dict[str, Handler] = { "initialized": lambda _params: None, @@ -151,6 +170,63 @@ def _initialize(self, params: Any) -> dict[str, Any]: "capabilities": {}, } + # -- the workspace (stage S1) -------------------------------------------------------- + + def _open(self) -> Workspace: + if self._workspace is None: + raise RpcError(protocol.NO_PROJECT, "Open a board first (project.open).") + return self._workspace + + def _trusted(self) -> Workspace: + workspace = self._open() + if not self._trust.is_trusted(workspace.rtos.root): + raise RpcError( + protocol.UNTRUSTED, + f"Running the generator runs code from {workspace.rtos.root}. Trust this " + "checkout first (project.trust).", + {"path": str(workspace.rtos.root)}, + ) + return workspace + + def _status(self) -> dict[str, Any]: + workspace = self._open() + return workspace.status(self._trust.is_trusted(workspace.rtos.root)) + + def _project_open(self, params: Any) -> dict[str, Any]: + if not isinstance(params, dict) or not isinstance(params.get("path"), str): + raise RpcError(protocol.INVALID_PARAMS, "params.path must be a string") + self._workspace = Workspace.open(params["path"]) + log.info("opened %s in %s", self._workspace.id, self._workspace.rtos.root) + return self._status() + + def _project_close(self, _params: Any) -> None: + self._workspace = None + return None + + def _project_status(self, _params: Any) -> dict[str, Any]: + return self._status() + + def _project_trust(self, _params: Any) -> dict[str, Any]: + workspace = self._open() + self._trust.trust(workspace.rtos.root) + log.info("trusted %s", workspace.rtos.root) + return self._status() + + def _board_list(self, params: Any) -> dict[str, Any]: + if isinstance(params, dict) and isinstance(params.get("rtos"), str): + rtos = Rtos.find(Path(params["rtos"]).expanduser().resolve()) + if rtos is None: + raise RpcError( + protocol.TOOL_MISSING, f"{params['rtos']} is not an EmbLinkRTOS checkout." + ) + else: + rtos = self._open().rtos + generator = rtos.check_supported() + return { + "rtos": {"root": str(rtos.root), "generator": generator}, + "boards": list_boards(rtos), + } + def _shutdown_request(self, _params: Any) -> None: self._shutdown = True return None diff --git a/core/src/emblink_studio_core/trust.py b/core/src/emblink_studio_core/trust.py new file mode 100644 index 0000000..5941f34 --- /dev/null +++ b/core/src/emblink_studio_core/trust.py @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: trust.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""Which checkouts the person trusts to run code (spec section 9, Security). + +Opening a board reads its files and runs nothing. Validating and generating run the +checkout's own generator, so they wait until the person trusts that checkout once +with project.trust. Trust is kept per path in the person's own settings, never in a +project or checkout, so a checkout cannot ship its own trust: + + macOS ~/Library/Application Support/EmbLink Studio/trust.json + Windows %APPDATA%/EmbLink Studio/trust.json + others $XDG_CONFIG_HOME/emblink-studio/trust.json (~/.config by default) + +EMBLINK_STUDIO_CONFIG_DIR replaces the directory, for tests. +""" + +from __future__ import annotations + +import json +import os +import sys +import tempfile +from pathlib import Path + + +def config_dir() -> Path: + override = os.environ.get("EMBLINK_STUDIO_CONFIG_DIR") + if override: + return Path(override) + if sys.platform == "darwin": + return Path.home() / "Library" / "Application Support" / "EmbLink Studio" + if sys.platform == "win32": + return Path(os.environ.get("APPDATA", Path.home())) / "EmbLink Studio" + return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "emblink-studio" + + +class TrustStore: + VERSION = 1 + + def __init__(self, directory: Path | None = None) -> None: + self.file = (directory or config_dir()) / "trust.json" + + def _load(self) -> set[str]: + try: + data = json.loads(self.file.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return set() + if not isinstance(data, dict) or data.get("version") != self.VERSION: + return set() + return {p for p in data.get("trusted", []) if isinstance(p, str)} + + @staticmethod + def _key(path: Path) -> str: + return str(path.expanduser().resolve()) + + def is_trusted(self, path: Path) -> bool: + return self._key(path) in self._load() + + def trust(self, path: Path) -> None: + trusted = self._load() | {self._key(path)} + self.file.parent.mkdir(parents=True, exist_ok=True) + body = json.dumps({"version": self.VERSION, "trusted": sorted(trusted)}, indent=2) + # Written whole and renamed into place, so a crash never leaves half a file. + fd, tmp = tempfile.mkstemp(dir=self.file.parent, prefix=".trust-", suffix=".json") + with os.fdopen(fd, "w", encoding="utf-8") as out: + out.write(body + "\n") + os.replace(tmp, self.file) diff --git a/core/src/emblink_studio_core/workspace.py b/core/src/emblink_studio_core/workspace.py new file mode 100644 index 0000000..e1b11cf --- /dev/null +++ b/core/src/emblink_studio_core/workspace.py @@ -0,0 +1,247 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: workspace.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""The workspace the core serves: in stage S1, a board of an EmbLinkRTOS checkout. + +Until the project manifest and the module contract exist (the RTOS's phase E1), +stages S1 to S3 work on what exists: the boards in the RTOS tree and their generated +model (spec section 8). So project.open takes a board directory, boards/// +holding board.yaml, inside a checkout. A directory holding emb-project.yaml is refused +for now with a message that says so; it opens once the project schema is agreed. + +Opening reads files and runs nothing. validate, generate and diff run the checkout's +emb-hwgen and need the checkout trusted (trust.py). The model is re-read from hw.json +whenever the file changes, so a generate, or an edit made outside, shows at once. +""" + +from __future__ import annotations + +import difflib +import tempfile +from pathlib import Path +from typing import Any + +from . import diagnostics, protocol +from .errors import CoreError +from .hwmodel import HwModel +from .rtos import Rtos + +# A diff longer than this is cut, and says so: a view shows it, it is not a patch. +DIFF_LINE_LIMIT = 400 + + +class Workspace: + kind = "board" + + def __init__(self, board_dir: Path, rtos: Rtos, generator: dict[str, object]) -> None: + self.board_dir = board_dir + self.rtos = rtos + self.generator = generator + self._model: HwModel | None = None + self._model_stamp: tuple[int, int] | None = None + + # -- opening ------------------------------------------------------------------------ + + @classmethod + def open(cls, path: str | Path) -> Workspace: + directory = Path(path).expanduser() + if not directory.is_dir(): + raise CoreError(protocol.INVALID_PARAMS, f"{directory} is not a directory.") + directory = directory.resolve() + if (directory / "emb-project.yaml").is_file() and not (directory / "board.yaml").is_file(): + raise CoreError( + protocol.INVALID_PARAMS, + "Projects (emb-project.yaml) open once the project manifest is agreed with the " + "RTOS (phase E1). For now, open a board of an EmbLinkRTOS checkout, such as " + "boards/st/nucleo_f446re.", + ) + if not (directory / "board.yaml").is_file(): + raise CoreError( + protocol.INVALID_PARAMS, + f"{directory} holds no board.yaml. Open a board of an EmbLinkRTOS checkout, " + "such as boards/st/nucleo_f446re.", + ) + rtos = Rtos.find(directory) + if rtos is None: + raise CoreError( + protocol.TOOL_MISSING, + f"{directory} is not inside an EmbLinkRTOS checkout (no hw/gen/emb-hwgen.py " + "above it).", + ) + workspace = cls(directory, rtos, rtos.check_supported()) + if workspace.hw_json.is_file(): + workspace.model() # refuse an unsupported hw.json now, not at the first view + return workspace + + # -- what it is --------------------------------------------------------------------- + + @property + def id(self) -> str: + return self.rtos.board_id(self.board_dir) + + @property + def generated_dir(self) -> Path: + return self.board_dir / "generated" + + @property + def hw_json(self) -> Path: + return self.generated_dir / "hw.json" + + def model(self) -> HwModel: + try: + stat = self.hw_json.stat() + except OSError as exc: + raise CoreError( + protocol.INVALID_REQUEST, + f"The board {self.id} has no generated model yet: generate it first.", + ) from exc + stamp = (stat.st_mtime_ns, stat.st_size) + if self._model is None or stamp != self._model_stamp: + self._model = HwModel.load(self.hw_json) + self._model_stamp = stamp + return self._model + + def status(self, trusted: bool) -> dict[str, Any]: + status: dict[str, Any] = { + "kind": self.kind, + "path": str(self.board_dir), + "id": self.id, + "name": self.board_dir.name, + "rtos": {"root": str(self.rtos.root), "generator": self.generator}, + "trusted": trusted, + "generated": self.hw_json.is_file(), + } + if status["generated"]: + status["board"] = self.model().summary() + return status + + # -- running the generator ---------------------------------------------------------- + + def _board_arg(self) -> str: + try: + return self.board_dir.relative_to(self.rtos.root).as_posix() + except ValueError: + return str(self.board_dir) + + def _diagnostics(self, output: str) -> list[dict[str, Any]]: + return diagnostics.parse(output, self.rtos.root) + + def _failed(self, what: str, proc: Any) -> CoreError: + return CoreError( + protocol.TOOL_FAILED, + f"emb-hwgen {what} failed (exit code {proc.returncode}).", + { + "tool": "emb-hwgen", + "exit_code": proc.returncode, + "output": proc.stderr + proc.stdout, + }, + ) + + def validate(self) -> dict[str, Any]: + """The generator's verdict on the board and its SoC, every diagnostic located.""" + proc = self.rtos.run_hwgen("validate", "--board", self._board_arg()) + if proc.returncode not in (0, 2): + raise self._failed("validate", proc) + found = self._diagnostics(proc.stderr) + return {"valid": proc.returncode == 0, "diagnostics": found, **diagnostics.counts(found)} + + def generate(self) -> dict[str, Any]: + """Writes the board's generated/ and re-reads its model.""" + proc = self.rtos.run_hwgen("generate", "--board", self._board_arg()) + if proc.returncode not in (0, 2): + raise self._failed("generate", proc) + found = self._diagnostics(proc.stderr) + written = proc.returncode == 0 + files = ( + sorted(p.name for p in self.generated_dir.iterdir() if p.is_file()) if written else [] + ) + result: dict[str, Any] = { + "written": written, + "files": files, + "diagnostics": found, + **diagnostics.counts(found), + } + if written: + result["board"] = self.model().summary() + return result + + def diff(self) -> dict[str, Any]: + """Which generated files a generate would change, and how; nothing is written.""" + with tempfile.TemporaryDirectory(prefix="emblink-studio-diff-") as tmp: + proc = self.rtos.run_hwgen("generate", "--board", self._board_arg(), "--out", tmp) + if proc.returncode not in (0, 2): + raise self._failed("generate", proc) + found = self._diagnostics(proc.stderr) + if proc.returncode == 2: + return { + "up_to_date": False, + "files": [], + "diagnostics": found, + **diagnostics.counts(found), + } + fresh = {p.name: p for p in Path(tmp).iterdir() if p.is_file()} + current = ( + {p.name: p for p in self.generated_dir.iterdir() if p.is_file()} + if self.generated_dir.is_dir() + else {} + ) + files = [ + self._file_diff(name, current.get(name), fresh.get(name)) + for name in sorted(set(fresh) | set(current)) + ] + return { + "up_to_date": all(f["status"] == "unchanged" for f in files), + "files": files, + "diagnostics": found, + **diagnostics.counts(found), + } + + @staticmethod + def _file_diff(name: str, have: Path | None, want: Path | None) -> dict[str, Any]: + if want is None: + return {"name": name, "status": "removed"} + if have is None: + return {"name": name, "status": "added"} + old = have.read_text(encoding="utf-8", errors="replace") + new = want.read_text(encoding="utf-8", errors="replace") + if old == new: + return {"name": name, "status": "unchanged"} + lines = list( + difflib.unified_diff( + old.splitlines(True), new.splitlines(True), f"{name} (now)", f"{name} (generated)" + ) + ) + cut = len(lines) > DIFF_LINE_LIMIT + return { + "name": name, + "status": "changed", + "diff": "".join(lines[:DIFF_LINE_LIMIT]), + "truncated": cut, + } + + +def list_boards(rtos: Rtos) -> list[dict[str, Any]]: + """Every board of a checkout, with its summary where its model is generated and readable.""" + out = [] + for board_dir in rtos.boards(): + entry: dict[str, Any] = { + "id": rtos.board_id(board_dir), + "name": board_dir.name, + "path": str(board_dir), + "generated": False, + } + hw_json = board_dir / "generated" / "hw.json" + if hw_json.is_file(): + try: + entry["board"] = HwModel.load(hw_json).summary() + entry["generated"] = True + except CoreError as exc: + entry["problem"] = exc.message + out.append(entry) + return out diff --git a/core/tests/conftest.py b/core/tests/conftest.py index 08f16f3..5b3344a 100644 --- a/core/tests/conftest.py +++ b/core/tests/conftest.py @@ -12,6 +12,11 @@ Builds JSON-RPC messages (`request`, `notification`, `INIT`), frames them (`frames`), runs the core as a real child process the way the desktop does (`run_core`), and loads the protocol's JSON schemas from protocol/ (the `schemas` fixture). + +From stage S1: `fake_rtos` builds a temporary EmbLinkRTOS checkout whose emb-hwgen is +fake_hwgen.py, with one generated board (acme/demo) and one not yet generated +(acme/blank); `config_dir` gives each test its own settings directory, so a test +never reads or writes the person's real trust file. """ from __future__ import annotations @@ -28,6 +33,8 @@ from emblink_studio_core.framing import encode, read_message +TESTS_DIR = Path(__file__).resolve().parent + CORE_SRC = Path(__file__).resolve().parents[1] / "src" PROTOCOL_DIR = Path(__file__).resolve().parents[2] / "protocol" @@ -61,9 +68,11 @@ def read_all(data: bytes) -> list[dict[str, Any]]: return out -def run_core(data: bytes) -> tuple[int, list[dict[str, Any]], str]: +def run_core( + data: bytes, env: dict[str, str] | None = None +) -> tuple[int, list[dict[str, Any]], str]: """Run `python -m emblink_studio_core serve` as the desktop would, feeding it `data`.""" - env = dict(os.environ, PYTHONPATH=str(CORE_SRC)) + env = dict(os.environ, **(env or {}), PYTHONPATH=str(CORE_SRC)) proc = subprocess.run( [sys.executable, "-m", "emblink_studio_core", "serve"], input=data, @@ -77,3 +86,55 @@ def run_core(data: bytes) -> tuple[int, list[dict[str, Any]], str]: @pytest.fixture(scope="session") def schemas() -> dict[str, Any]: return {p.name: json.loads(p.read_text()) for p in PROTOCOL_DIR.glob("*.schema.json")} + + +DEMO_BOARD = """\ +schema_version: 0 +kind: board +name: demo +vendor: acme +soc: acme/acme1.yaml +clocks: + cpu_hz: 48000000 +""" + + +def write_board(root: Path, board_id: str, text: str) -> Path: + board = root / "boards" / board_id + board.mkdir(parents=True, exist_ok=True) + (board / "board.yaml").write_text(text, encoding="utf-8") + return board + + +def hwgen(root: Path, *args: str) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, str(root / "hw/gen/emb-hwgen.py"), *args], + cwd=root, + capture_output=True, + text=True, + check=False, + ) + + +@pytest.fixture +def fake_rtos(tmp_path: Path) -> Path: + """A temporary checkout: acme/demo generated, acme/blank not yet.""" + root = tmp_path / "rtos" + gen = root / "hw" / "gen" + (gen / "emb_hwgen").mkdir(parents=True) + (gen / "emb-hwgen.py").write_text((TESTS_DIR / "fake_hwgen.py").read_text(), encoding="utf-8") + (gen / "emb_hwgen" / "__init__.py").write_text( + '"""The fake generator\'s package."""\n\nVERSION = "0.1.0"\nSCHEMA_VERSION = 0\n', + encoding="utf-8", + ) + write_board(root, "acme/demo", DEMO_BOARD) + write_board(root, "acme/blank", DEMO_BOARD.replace("name: demo", "name: blank")) + assert hwgen(root, "generate", "--board", "boards/acme/demo").returncode == 0 + return root + + +@pytest.fixture +def config_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + directory = tmp_path / "config" + monkeypatch.setenv("EMBLINK_STUDIO_CONFIG_DIR", str(directory)) + return directory diff --git a/core/tests/fake_hwgen.py b/core/tests/fake_hwgen.py new file mode 100755 index 0000000..fbab45e --- /dev/null +++ b/core/tests/fake_hwgen.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: fake_hwgen.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""A stand-in for EmbLinkRTOS's emb-hwgen, for the core's tests. + +The `fake_rtos` fixture installs it as hw/gen/emb-hwgen.py of a temporary checkout. +It has the real tool's interface (validate, and generate --board DIR [--out DIR]), +exit codes (0, and 2 for description errors) and output format (the RTOS's HW-002: +'file:line: node.path: message', warnings prefixed 'warning: '). What it reports is +written in the board.yaml it reads, one instruction per line: + + # error: : an error at this line + # warning: : a warning at this line + # crash a traceback and exit code 3, as a broken generator + # no-yaml PyYAML missing, as the real tool reports it + +generate writes hw.json and hw_config.h from the board's name and cpu_hz lines. +""" + +import argparse +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] + + +def model(text: str, rel: str) -> dict: + name = re.search(r"^name: (\S+)", text, re.M).group(1) + cpu_hz = int(re.search(r"cpu_hz: (\d+)", text).group(1)) + schema = ( + int(re.search(r"^hw_schema: (\d+)", text, re.M).group(1)) if "hw_schema:" in text else 0 + ) + return { + "schema_version": schema, + "generator": {"name": "emb-hwgen", "version": "0.1.0"}, + "inputs": [{"path": f"{rel}/board.yaml", "sha256": "0" * 64}], + "warnings": [], + "board": { + "name": name, + "vendor": "acme", + "revision": "A", + "curated": True, + "doc": "A test board.", + "console": {"device": "uart0", "baud": 115200}, + "leds": [{"name": "user", "gpio": "PA5", "active": "high"}], + "clocks": {"cpu_hz": cpu_hz}, + "oscillators": {"hse": {"hz": 8000000}}, + }, + "soc": { + "name": "acme1", + "part": "ACME1", + "vendor": "acme", + "family": "acme", + "package": "qfn32", + "cpu": {"core": "cortex-m4f"}, + "gpio": {"ports": {"A": 255}}, + "alternate_functions": {"PA0": {"af1": "uart0_tx"}, "PA1": {"af1": "uart0_rx"}}, + "memory": { + "regions": [ + {"name": "flash", "base": 0, "size": 65536, "attrs": ["r", "x"]}, + {"name": "sram", "base": 536870912, "size": 16384, "attrs": ["r", "w"]}, + ] + }, + "flash": {"region": "flash"}, + "clocks": {"max_hz": 200000000}, + "peripherals": [{"name": "uart0", "base": 1073741824, "size": 1024}], + }, + "derived": { + "clock": {"cpu_hz": cpu_hz, "source": "hse", "source_hz": 8000000}, + "pins": [ + { + "pin": "PA0", + "port": "A", + "number": 0, + "mode": "af", + "af": 1, + "gpio": "gpioa", + "owner": "pins.uart0.tx", + "signal": "uart0_tx", + } + ], + "devices": [{"name": "uart0", "class": "uart"}], + "profile": "base", + "kconfig": {"CONFIG_EMB_CM_CPU_HZ": cpu_hz}, + "timer": {"name": "systick"}, + "linker": {"flash": {"origin": 0, "length": 65536}}, + "partitions": [], + }, + } + + +def main() -> int: + parser = argparse.ArgumentParser() + sub = parser.add_subparsers(dest="cmd", required=True) + for cmd in ("validate", "generate"): + p = sub.add_parser(cmd) + p.add_argument("--board", required=True) + p.add_argument("--out") + args = parser.parse_args() + + board = Path(args.board) + board = board if board.is_absolute() else ROOT / board + rel = board.relative_to(ROOT).as_posix() if board.is_relative_to(ROOT) else str(board) + text = (board / "board.yaml").read_text(encoding="utf-8") + errors, warnings = [], [] + for number, line in enumerate(text.splitlines(), 1): + if "# crash" in line: + print("Traceback (most recent call last):\n KeyError: 'pll'", file=sys.stderr) + return 3 + if "# no-yaml" in line: + print("ModuleNotFoundError: No module named 'yaml'", file=sys.stderr) + return 1 + for tag, found in (("# error: ", errors), ("# warning: ", warnings)): + if tag in line: + found.append(f"{rel}/board.yaml:{number}: {line.split(tag, 1)[1]}") + for warning in warnings: + print(f"warning: {warning}", file=sys.stderr) + if errors: + for error in errors: + print(error, file=sys.stderr) + print(f"emb-hwgen: {len(errors)} error(s)", file=sys.stderr) + return 2 + if args.cmd == "validate": + print(f"emb-hwgen: {args.board} is valid") + return 0 + + out = Path(args.out) if args.out else board / "generated" + out.mkdir(parents=True, exist_ok=True) + hw = model(text, rel) + (out / "hw.json").write_text(json.dumps(hw, indent=2, sort_keys=True) + "\n", encoding="utf-8") + (out / "hw_config.h").write_text( + f"/* generated by emb-hwgen */\n#define EMB_CPU_HZ {hw['derived']['clock']['cpu_hz']}\n", + encoding="utf-8", + ) + print(f"emb-hwgen: wrote 2 files to {out}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/core/tests/test_diagnostics.py b/core/tests/test_diagnostics.py new file mode 100644 index 0000000..c46afd0 --- /dev/null +++ b/core/tests/test_diagnostics.py @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: test_diagnostics.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""The generator's lines become located diagnostics (the RTOS's rule HW-002). + +Lines are taken from emb-hwgen's real output: an error with a YAML path, a warning, a +file outside the checkout, the document's root, a Windows drive letter; the summary +is dropped and a line in no known form is kept with its message. +""" + +from pathlib import Path + +from emblink_studio_core import diagnostics + +ROOT = Path("/rtos") + + +def test_an_error_with_its_location(): + [d] = diagnostics.parse( + "boards/st/nucleo_f446re/board.yaml:25: pins.usart2.tx: PA2 af9 is not usart2_tx " + "(PA2 offers af7 usart2_tx)\n", + ROOT, + ) + assert d == { + "severity": "error", + "source": "emb-hwgen", + "file": str(ROOT / "boards/st/nucleo_f446re/board.yaml"), + "line": 25, + "path": "pins.usart2.tx", + "message": "PA2 af9 is not usart2_tx (PA2 offers af7 usart2_tx)", + } + + +def test_a_warning_and_the_summary(): + found = diagnostics.parse( + "warning: soc/st/stm32f4/stm32f4.yaml:17: cpu.mpu: the cortex_m port does not use the " + "MPU yet\n" + "emb-hwgen: /rtos/boards/st/nucleo_f446re is valid\n", + ROOT, + ) + assert len(found) == 1 + assert found[0]["severity"] == "warning" + assert found[0]["path"] == "cpu.mpu" + assert diagnostics.counts(found) == {"errors": 0, "warnings": 1} + + +def test_files_outside_the_checkout_stay_absolute(): + [d] = diagnostics.parse( + "/home/me/boards/st/x/board.yaml:7: name: 'nucleo_f446re' differs from its directory 'x'", + ROOT, + ) + assert d["file"] == "/home/me/boards/st/x/board.yaml" + assert d["path"] == "name" + + +def test_the_document_root(): + [d] = diagnostics.parse( + "warning: boards/rpi/pico2_w/board.yaml:1: (root): uncurated description", ROOT + ) + assert d["path"] == "(root)" + assert d["line"] == 1 + + +def test_a_windows_drive_letter_is_part_of_the_file(): + [d] = diagnostics.parse(r"C:\rtos\boards\x\board.yaml:12: clocks.pll: out of range", ROOT) + assert d["file"].endswith(r"board.yaml") + assert d["line"] == 12 + assert d["path"] == "clocks.pll" + + +def test_a_message_without_a_path(): + [d] = diagnostics.parse("boards/x/board.yaml:3: something is off here", ROOT) + assert d["message"] == "something is off here" + assert "path" not in d + + +def test_an_unknown_line_is_kept(): + found = diagnostics.parse("\nthe generator said something new\nemb-hwgen: 1 error(s)\n", ROOT) + assert found == [ + {"severity": "error", "source": "emb-hwgen", "message": "the generator said something new"} + ] diff --git a/core/tests/test_project_rpc.py b/core/tests/test_project_rpc.py new file mode 100644 index 0000000..328cd5b --- /dev/null +++ b/core/tests/test_project_rpc.py @@ -0,0 +1,130 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: test_project_rpc.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""The S1 methods over JSON-RPC, as the desktop calls them (spec sections 5 and 9). + +Runs the core as a child process against the fake checkout: a call before any board +is open answers no_project; running the generator answers untrusted until the +checkout is trusted; then every method answers, and every result and error matches +its schema in protocol/. Trust is remembered from one core process to the next. +""" + +import jsonschema + +from conftest import INIT, frames, notification, request, run_core + +METHODS = [ + "project.status", + "project.validate", + "board.list", + "board.describe", + "board.pins", + "board.clocks", + "board.memory", + "generate.diff", + "generate.run", +] + + +def by_id(out): + return {m["id"]: m for m in out if "id" in m} + + +def check_result(schemas, method, message): + assert "result" in message, message + jsonschema.validate(message["result"], schemas[f"{method}.result.schema.json"]) + + +def test_a_session_on_a_board(fake_rtos, config_dir, schemas): + board = str(fake_rtos / "boards/acme/demo") + env = {"EMBLINK_STUDIO_CONFIG_DIR": str(config_dir)} + calls = [ + INIT, + request(2, "board.describe"), # nothing open yet + request(3, "project.open", {"path": board}), + request(4, "project.validate"), # not trusted yet + request(5, "generate.run"), + request(6, "project.trust"), + ] + calls += [request(10 + i, m) for i, m in enumerate(METHODS)] + calls += [ + request(30, "project.close"), + request(31, "board.pins"), + request(32, "project.open", {"path": str(fake_rtos / "boards")}), + request(33, "shutdown"), + notification("exit"), + ] + jsonschema.validate(calls[2]["params"], schemas["project.open.params.schema.json"]) + code, out, log = run_core(frames(*calls), env) + assert code == 0, log + answers = by_id(out) + + for msg_id, error in ((2, 1002), (4, 1003), (5, 1003), (31, 1002), (32, -32602)): + assert answers[msg_id]["error"]["code"] == error, answers[msg_id] + jsonschema.validate(answers[msg_id], schemas["error.schema.json"]) + + check_result(schemas, "project.open", answers[3]) + assert answers[3]["result"]["trusted"] is False + check_result(schemas, "project.trust", answers[6]) + assert answers[6]["result"]["trusted"] is True + + for i, method in enumerate(METHODS): + check_result(schemas, method, answers[10 + i]) + assert answers[11]["result"]["valid"] is True + assert [b["id"] for b in answers[12]["result"]["boards"]] == ["acme/blank", "acme/demo"] + assert answers[15]["result"]["resolved"]["cpu_hz"] == 48000000 + assert answers[17]["result"]["up_to_date"] is True + assert answers[18]["result"]["written"] is True + assert answers[30]["result"] is None + jsonschema.validate(answers[30]["result"], schemas["project.close.result.schema.json"]) + + +def test_trust_is_remembered_by_the_next_core(fake_rtos, config_dir): + board = str(fake_rtos / "boards/acme/demo") + env = {"EMBLINK_STUDIO_CONFIG_DIR": str(config_dir)} + run_core( + frames( + INIT, + request(2, "project.open", {"path": board}), + request(3, "project.trust"), + request(4, "shutdown"), + notification("exit"), + ), + env, + ) + _, out, _ = run_core( + frames( + INIT, + request(2, "project.open", {"path": board}), + request(3, "project.validate"), + request(4, "shutdown"), + notification("exit"), + ), + env, + ) + answers = by_id(out) + assert answers[2]["result"]["trusted"] is True + assert answers[3]["result"]["valid"] is True + + +def test_board_list_of_a_checkout_with_nothing_open(fake_rtos, config_dir, schemas): + _, out, _ = run_core( + frames( + INIT, + request(2, "board.list", {"rtos": str(fake_rtos)}), + request(3, "board.list", {"rtos": str(config_dir)}), + request(4, "shutdown"), + notification("exit"), + ), + {"EMBLINK_STUDIO_CONFIG_DIR": str(config_dir)}, + ) + answers = by_id(out) + check_result(schemas, "board.list", answers[2]) + assert len(answers[2]["result"]["boards"]) == 2 + assert answers[3]["error"]["code"] == 1011 diff --git a/core/tests/test_rtos_acceptance.py b/core/tests/test_rtos_acceptance.py new file mode 100644 index 0000000..ef9d515 --- /dev/null +++ b/core/tests/test_rtos_acceptance.py @@ -0,0 +1,121 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: test_rtos_acceptance.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""Stage S1's acceptance, against a real EmbLinkRTOS checkout (spec section 8). + +"Opening the RTOS's nucleo_f446re and pico2_w boards shows their model; validation +reports the generator's errors with their locations." + +EMBLINK_STUDIO_TEST_RTOS names the checkout; CI checks out the RTOS at a pinned commit +for these tests, and they are skipped where it is not set. The model is checked +against the board's own hw.json and the facts of its datasheet; the errors are made +in a copy of the NUCLEO-F446RE's description, inside a copy of the files the +generator reads, and each is expected at its line and its path in the YAML. +""" + +import json +import os +import shutil +from pathlib import Path + +import jsonschema +import pytest + +from emblink_studio_core.workspace import Workspace + +RTOS = os.environ.get("EMBLINK_STUDIO_TEST_RTOS") +pytestmark = pytest.mark.skipif(not RTOS, reason="EMBLINK_STUDIO_TEST_RTOS is not set") + +BOARDS = { + # board: (part, cpu_hz, a pin in use and its signal, the first memory region) + "st/nucleo_f446re": ("STM32F446RE", 180_000_000, ("PA2", "usart2_tx"), "flash"), + "rpi/pico2_w": ("RP2350A", 150_000_000, ("GPIO0", "uart0_tx"), None), +} + + +@pytest.mark.parametrize("board_id", sorted(BOARDS)) +def test_opening_a_board_shows_its_model(board_id, schemas): + part, cpu_hz, (pin, signal), first_region = BOARDS[board_id] + board_dir = Path(RTOS) / "boards" / board_id + hw = json.loads((board_dir / "generated/hw.json").read_text(encoding="utf-8")) + ws = Workspace.open(board_dir) + + status = ws.status(trusted=True) + jsonschema.validate(status, schemas["project.status.result.schema.json"]) + assert status["board"]["soc"] == part + assert status["board"]["cpu_hz"] == cpu_hz + + model = ws.model() + views = { + "describe": model.describe(), + "pins": model.pins(), + "clocks": model.clocks(), + "memory": model.memory(), + } + for name, view in views.items(): + jsonschema.validate(view, schemas[f"board.{name}.result.schema.json"]) + assert views["describe"]["soc"]["part"] == part + assert views["describe"]["devices"] == hw["derived"]["devices"] + assert views["clocks"]["resolved"] == hw["derived"]["clock"] + assert views["pins"]["assigned"] == hw["derived"]["pins"] + assert {p["pin"]: p.get("signal") for p in views["pins"]["assigned"]}[pin] == signal + assert views["memory"]["regions"] == hw["soc"]["memory"]["regions"] + if first_region: + assert views["memory"]["regions"][0]["name"] == first_region + + +@pytest.mark.parametrize("board_id", sorted(BOARDS)) +def test_the_committed_boards_are_valid(board_id, schemas): + result = Workspace.open(Path(RTOS) / "boards" / board_id).validate() + jsonschema.validate(result, schemas["project.validate.result.schema.json"]) + assert result["valid"] is True, result + assert result["errors"] == 0 + for d in result["diagnostics"]: # warnings, each located + assert Path(d["file"]).is_file() + assert d["line"] >= 1 + + +def test_errors_are_reported_where_they_are(tmp_path, schemas): + src = Path(RTOS) + board_rel = Path("boards/st/nucleo_f446re") + hw = json.loads((src / board_rel / "generated/hw.json").read_text(encoding="utf-8")) + # A checkout of just what the generator reads: its own code and the board's inputs. + root = tmp_path / "rtos" + shutil.copytree(src / "hw", root / "hw", ignore=shutil.ignore_patterns("__pycache__")) + for item in hw["inputs"]: + (root / item["path"]).parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(src / item["path"], root / item["path"]) + + board_yaml = root / board_rel / "board.yaml" + text = board_yaml.read_text(encoding="utf-8") + broken = { + "cpu_hz: 180MHz": ("cpu_hz: 900MHz", "clocks.pll"), + "usart2: { tx: PA2.af7": ("usart2: { tx: PA2.af9", "pins.usart2.tx"), + "console: { device: usart2": ("console: { device: usart9", "console.device"), + } + expected = {} + for good, (bad, _path) in broken.items(): + assert good in text, f"the NUCLEO-F446RE's description changed: no '{good}'" + text = text.replace(good, bad) + lines = text.splitlines() + for bad, path in broken.values(): + # clocks.pll is reported at the pll line, the factors that cannot give 900 MHz. + needle = "pll:" if path == "clocks.pll" else bad + expected[path] = next(i for i, line in enumerate(lines, 1) if needle in line) + board_yaml.write_text(text, encoding="utf-8") + + result = Workspace.open(root / board_rel).validate() + jsonschema.validate(result, schemas["project.validate.result.schema.json"]) + assert result["valid"] is False + errors = {d["path"]: d for d in result["diagnostics"] if d["severity"] == "error"} + for path, line in expected.items(): + assert path in errors, (path, sorted(errors)) + assert errors[path]["line"] == line, (path, errors[path]) + assert Path(errors[path]["file"]) == board_yaml.resolve() + assert "PA2 offers af7 usart2_tx" in errors["pins.usart2.tx"]["message"] diff --git a/core/tests/test_workspace.py b/core/tests/test_workspace.py new file mode 100644 index 0000000..8a0b579 --- /dev/null +++ b/core/tests/test_workspace.py @@ -0,0 +1,224 @@ +# SPDX-License-Identifier: Apache-2.0 +# Copyright 2026 Junior Deogracias +# +# This file is part of EmbLink Studio, the IDE for EmbLinkRTOS. +# Licensed under the Apache License, Version 2.0; see the LICENSE file at the repository root. +# +# File: test_workspace.py +# Author: Junior Deogracias +# Created: 2026-11-12 +"""A board of a checkout, opened, read, validated and generated (stage S1). + +Against the fake checkout of conftest.py: what opens and what is refused, and why; +the formats a core supports; the model's views; validation with located diagnostics; +generating, after which the model is re-read; what diff reports for each kind of +change; a broken or incomplete generator; the boards of a checkout; and the trust +store. +""" + +import json + +import pytest + +from conftest import write_board +from emblink_studio_core import protocol +from emblink_studio_core.errors import CoreError +from emblink_studio_core.rtos import Rtos +from emblink_studio_core.trust import TrustStore +from emblink_studio_core.workspace import Workspace, list_boards + + +def error_code(call): + with pytest.raises(CoreError) as caught: + call() + return caught.value.code + + +# -- opening ---------------------------------------------------------------------------- + + +def test_a_generated_board_opens_with_its_model(fake_rtos): + ws = Workspace.open(fake_rtos / "boards/acme/demo") + status = ws.status(trusted=False) + assert status["kind"] == "board" + assert status["id"] == "acme/demo" + assert status["rtos"]["root"] == str(fake_rtos.resolve()) + assert status["rtos"]["generator"] == { + "name": "emb-hwgen", + "version": "0.1.0", + "schema_version": 0, + } + assert status["generated"] is True + assert status["board"]["soc"] == "ACME1" + assert status["board"]["cpu_hz"] == 48000000 + + +def test_a_board_not_generated_yet_opens_without_a_model(fake_rtos): + ws = Workspace.open(fake_rtos / "boards/acme/blank") + assert ws.status(trusted=False)["generated"] is False + assert error_code(ws.model) == protocol.INVALID_REQUEST + + +def test_what_is_refused(fake_rtos, tmp_path): + assert error_code(lambda: Workspace.open(tmp_path / "nothing")) == protocol.INVALID_PARAMS + assert error_code(lambda: Workspace.open(fake_rtos / "boards")) == protocol.INVALID_PARAMS + project = tmp_path / "project" + project.mkdir() + (project / "emb-project.yaml").write_text("schema_version: 0\nkind: project\n") + with pytest.raises(CoreError) as caught: + Workspace.open(project) + assert "phase E1" in caught.value.message + outside = write_board(tmp_path / "elsewhere", "acme/demo", "name: demo\ncpu_hz: 1\n") + assert error_code(lambda: Workspace.open(outside)) == protocol.TOOL_MISSING + + +def test_another_generator_major_is_refused(fake_rtos): + package = fake_rtos / "hw/gen/emb_hwgen/__init__.py" + package.write_text('VERSION = "1.0.0"\nSCHEMA_VERSION = 0\n') + assert ( + error_code(lambda: Workspace.open(fake_rtos / "boards/acme/demo")) + == protocol.UNSUPPORTED_RTOS + ) + + +def test_another_hw_json_schema_is_refused(fake_rtos): + hw_json = fake_rtos / "boards/acme/demo/generated/hw.json" + data = json.loads(hw_json.read_text()) + data["schema_version"] = 7 + hw_json.write_text(json.dumps(data)) + with pytest.raises(CoreError) as caught: + Workspace.open(fake_rtos / "boards/acme/demo") + assert caught.value.code == protocol.UNSUPPORTED_RTOS + assert "schema 7" in caught.value.message + + +# -- the model -------------------------------------------------------------------------- + + +def test_the_views_are_the_generators_values(fake_rtos): + model = Workspace.open(fake_rtos / "boards/acme/demo").model() + hw = json.loads((fake_rtos / "boards/acme/demo/generated/hw.json").read_text()) + describe = model.describe() + assert describe["board"]["name"] == "demo" + assert describe["soc"]["part"] == "ACME1" + assert describe["devices"] == hw["derived"]["devices"] + pins = model.pins() + assert pins["assigned"] == hw["derived"]["pins"] + assert pins["alternate_functions"]["PA0"] == {"af1": "uart0_tx"} + assert model.clocks()["resolved"]["cpu_hz"] == 48000000 + assert [r["name"] for r in model.memory()["regions"]] == ["flash", "sram"] + + +# -- validating and generating ---------------------------------------------------------- + + +def test_a_valid_board(fake_rtos): + result = Workspace.open(fake_rtos / "boards/acme/demo").validate() + assert result == {"valid": True, "diagnostics": [], "errors": 0, "warnings": 0} + + +def test_errors_and_warnings_are_located(fake_rtos): + board = fake_rtos / "boards/acme/demo" + (board / "board.yaml").write_text( + "name: demo\n" + "clocks:\n" + " cpu_hz: 900000000 # error: clocks.cpu_hz: above the 200 MHz the chip allows\n" + "pins: {} # warning: pins: no pin assigned\n" + ) + result = Workspace.open(board).validate() + assert result["valid"] is False + assert (result["errors"], result["warnings"]) == (1, 1) + error = next(d for d in result["diagnostics"] if d["severity"] == "error") + assert error["file"] == str((board / "board.yaml").resolve()) + assert error["line"] == 3 + assert error["path"] == "clocks.cpu_hz" + assert error["message"] == "above the 200 MHz the chip allows" + + +def test_a_crashing_generator_is_a_tool_failure(fake_rtos): + board = fake_rtos / "boards/acme/demo" + (board / "board.yaml").write_text("name: demo\ncpu_hz: 1 # crash\n") + with pytest.raises(CoreError) as caught: + Workspace.open(board).validate() + assert caught.value.code == protocol.TOOL_FAILED + assert "KeyError" in caught.value.data["output"] + + +def test_a_generator_without_pyyaml_says_what_to_install(fake_rtos): + board = fake_rtos / "boards/acme/demo" + (board / "board.yaml").write_text("name: demo\ncpu_hz: 1 # no-yaml\n") + with pytest.raises(CoreError) as caught: + Workspace.open(board).validate() + assert caught.value.code == protocol.TOOL_MISSING + assert "pip install pyyaml" in caught.value.message + + +def test_generate_writes_and_the_model_follows(fake_rtos): + board = fake_rtos / "boards/acme/demo" + ws = Workspace.open(board) + assert ws.model().clocks()["resolved"]["cpu_hz"] == 48000000 + (board / "board.yaml").write_text( + (board / "board.yaml").read_text().replace("48000000", "96000000") + ) + result = ws.generate() + assert result["written"] is True + assert result["files"] == ["hw.json", "hw_config.h"] + assert result["board"]["cpu_hz"] == 96000000 + assert ws.model().clocks()["resolved"]["cpu_hz"] == 96000000 + + +def test_generate_refused_writes_nothing(fake_rtos): + board = fake_rtos / "boards/acme/demo" + before = (board / "generated/hw.json").read_text() + (board / "board.yaml").write_text("name: demo\ncpu_hz: 1 # error: cpu_hz: too slow\n") + result = Workspace.open(board).generate() + assert result["written"] is False + assert result["errors"] == 1 + assert (board / "generated/hw.json").read_text() == before + + +def test_diff_reports_each_kind_of_change(fake_rtos): + board = fake_rtos / "boards/acme/demo" + ws = Workspace.open(board) + assert ws.diff()["up_to_date"] is True + (board / "generated/hw_config.h").write_text("/* edited by hand */\n") + (board / "generated/notes.txt").write_text("not an output\n") + result = ws.diff() + assert result["up_to_date"] is False + by_name = {f["name"]: f for f in result["files"]} + assert by_name["hw.json"]["status"] == "unchanged" + assert by_name["hw_config.h"]["status"] == "changed" + assert "+#define EMB_CPU_HZ 48000000" in by_name["hw_config.h"]["diff"] + assert by_name["notes.txt"]["status"] == "removed" + (board / "generated/hw.json").unlink() + assert {f["name"]: f["status"] for f in ws.diff()["files"]}["hw.json"] == "added" + # diff never writes + assert not (board / "generated/hw.json").exists() + + +def test_the_boards_of_a_checkout(fake_rtos): + boards = list_boards(Rtos.find(fake_rtos)) + assert [b["id"] for b in boards] == ["acme/blank", "acme/demo"] + assert boards[0]["generated"] is False + assert boards[1]["board"]["name"] == "demo" + + +# -- trust ------------------------------------------------------------------------------ + + +def test_trust_is_kept_per_path_and_survives(tmp_path): + store = TrustStore(tmp_path / "config") + checkout = tmp_path / "rtos" + checkout.mkdir() + assert not store.is_trusted(checkout) + store.trust(checkout) + assert TrustStore(tmp_path / "config").is_trusted(checkout / "." / "") + assert not store.is_trusted(tmp_path) + + +def test_a_damaged_trust_file_trusts_nothing(tmp_path): + (tmp_path / "trust.json").write_text("{ not json") + store = TrustStore(tmp_path) + assert not store.is_trusted(tmp_path) + store.trust(tmp_path) + assert store.is_trusted(tmp_path) diff --git a/docs/development.md b/docs/development.md index dabe3a1..2fe9c0a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -24,6 +24,15 @@ core/.venv/bin/pytest core # the core's tests, including the protocol schemas core/.venv/bin/ruff check . && core/.venv/bin/ruff format --check . ``` +The core's acceptance tests run against a real EmbLinkRTOS checkout: set `EMBLINK_STUDIO_TEST_RTOS` to it, as +CI does with the RTOS at a pinned commit; without it they are skipped. + +```sh +EMBLINK_STUDIO_TEST_RTOS=~/EmbLinkRTOS core/.venv/bin/pytest core +core/.venv/bin/emblink-studio-core board list ~/EmbLinkRTOS # every method has a command +core/.venv/bin/emblink-studio-core project validate ~/EmbLinkRTOS/boards/st/nucleo_f446re +``` + Run the application: `build/dev/app/EmbLinkStudio.app/Contents/MacOS/EmbLinkStudio` on macOS, `build/dev/app/EmbLinkStudio` elsewhere. It runs the core from `core/src` with the Python CMake found; set `EMBLINK_STUDIO_CORE` to an installed `emblink-studio-core` to use that instead. diff --git a/docs/specification.md b/docs/specification.md index bdfa1e0..adace92 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -276,7 +276,7 @@ Ten stages, each ending in something usable and demonstrated. S0 is done: CI bui | Stage | Delivers | Accepted when | Needs from the RTOS | Status | | --- | --- | --- | --- | --- | | **S0 Setup** | The EmbLink Studio repository, its licence files and contributor agreement, CI on Windows, Linux and macOS, a Qt application that starts and talks to a stub core | CI builds and tests on all three systems; `initialize` and `shutdown` succeed; the notices list is generated | Nothing | Done | -| **S1 Core foundation** | `emblink-studio-core serve`, `project.open` and `validate`, `board.*` from `hw.json`, `generate.run` | Opening the RTOS's `nucleo_f446re` and `pico2_w` boards shows their model; validation reports the generator's errors with their locations | JSON diagnostics from `emb-hwgen`; a versioned `hw.json` | Not started | +| **S1 Core foundation** | `emblink-studio-core serve`, `project.open` and `validate`, `board.*` from `hw.json`, `generate.run` | Opening the RTOS's `nucleo_f446re` and `pico2_w` boards shows their model; validation reports the generator's errors with their locations | JSON diagnostics from `emb-hwgen`; a versioned `hw.json` | In progress | | **S2 Read-only views** | Board, pin map, clock tree, devices, memory, RTOS, problems | For both boards, a golden test finds every value in the views equal to `hw.json` and to the generator's `board.md` and `build_report.md` | Existing outputs | Not started | | **S3 Editing** | `config.preview`, `apply`, `undo`; pins, devices and threads editable; live diagnostics | A pin conflict is refused with the generator's message; an edit's `git diff` touches only the lines it must; generation stays clean | `system.yaml` (E3) for threads | Not started | | **S4 Build, flash, console** | Toolchain discovery, CMake build, flash by OpenOCD and picotool, serial console | A project is created, built, flashed and seen running on the NUCLEO-F446RE and the Pico 2 W; in CI, on EmbSIM's `nucleo_f446re` | The CMake package (A91) | Not started | @@ -290,8 +290,8 @@ Ten stages, each ending in something usable and demonstrated. S0 is done: CI bui | EmbLink Studio needs | Status in EmbLinkRTOS | First needed | | --- | --- | --- | -| Machine-readable diagnostics from the generator (JSON) | To add, early | S1 | -| A version field in `hw.json` and a published schema for it | To add, early | S1 | +| Machine-readable diagnostics from the generator (JSON) | To add, early. Until then the core reads its documented line format (HW-002) | S1 | +| A version field in `hw.json` and a published schema for it | Exists: `schema_version` and `hw/schemas/hw.schema.json` | S1 | | `hw.json` and the generated outputs for each board | Exists | S1 | | `emb-hwgen generate` and `check` | Exists | S1 | | The CMake package for applications outside the tree | Exists (A91) | S4 | diff --git a/protocol/README.md b/protocol/README.md index 07d4cc8..a601888 100644 --- a/protocol/README.md +++ b/protocol/README.md @@ -7,3 +7,12 @@ for every error response. The core's tests (`core/tests/test_schemas.py`) check message the core sends against them. The protocol is described in the [specification](../docs/specification.md), §5. Protocol version: 0.1.0. A change that breaks an existing client bumps the major version. + +| Method | Since | What it does | +| --- | --- | --- | +| `initialize`, `shutdown` | S0 | The lifecycle | +| `project.open`, `close`, `status` | S1 | A board of an EmbLinkRTOS checkout is the workspace until the project manifest exists | +| `project.trust` | S1 | Lets the checkout run its generator (spec §9); remembered in the person's settings | +| `project.validate` | S1 | The generator's verdict, each diagnostic with its file, line and YAML path | +| `board.list`, `describe`, `pins`, `clocks`, `memory` | S1 | The generator's resolved model, from `hw.json` | +| `generate.run`, `diff` | S1 | Runs the checkout's `emb-hwgen`; `diff` writes nothing | diff --git a/protocol/board.clocks.result.schema.json b/protocol/board.clocks.result.schema.json new file mode 100644 index 0000000..8e7601c --- /dev/null +++ b/protocol/board.clocks.result.schema.json @@ -0,0 +1,37 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.clocks: result", + "type": "object", + "properties": { + "resolved": { + "type": "object", + "properties": { + "cpu_hz": { + "type": "integer" + } + }, + "required": [ + "cpu_hz" + ], + "additionalProperties": true + }, + "requested": { + "type": "object" + }, + "oscillators": { + "type": "object" + }, + "limits": { + "type": "object" + }, + "timer": { + "type": "object" + } + }, + "required": [ + "resolved", + "requested", + "limits" + ], + "additionalProperties": false +} diff --git a/protocol/board.describe.result.schema.json b/protocol/board.describe.result.schema.json new file mode 100644 index 0000000..38cc5ec --- /dev/null +++ b/protocol/board.describe.result.schema.json @@ -0,0 +1,43 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.describe: result", + "type": "object", + "properties": { + "board": { + "type": "object" + }, + "soc": { + "type": "object" + }, + "devices": { + "type": "array" + }, + "profile": { + "type": [ + "string", + "null" + ] + }, + "kconfig": { + "type": "object" + }, + "generator": { + "type": "object" + }, + "inputs": { + "type": "array" + }, + "warnings": { + "type": "array" + } + }, + "required": [ + "board", + "soc", + "devices", + "kconfig", + "generator" + ], + "additionalProperties": false, + "description": "The board and its chip, as hw.json holds them (hw/schemas/hw.schema.json in the RTOS)." +} diff --git a/protocol/board.list.params.schema.json b/protocol/board.list.params.schema.json new file mode 100644 index 0000000..7a16919 --- /dev/null +++ b/protocol/board.list.params.schema.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.list: parameters", + "type": "object", + "properties": { + "rtos": { + "type": "string", + "description": "A checkout; the open workspace's when absent." + } + }, + "required": [], + "additionalProperties": false +} diff --git a/protocol/board.list.result.schema.json b/protocol/board.list.result.schema.json new file mode 100644 index 0000000..ba4d936 --- /dev/null +++ b/protocol/board.list.result.schema.json @@ -0,0 +1,138 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.list: result", + "type": "object", + "properties": { + "rtos": { + "type": "object", + "properties": { + "root": { + "type": "string" + }, + "generator": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "schema_version": { + "type": "integer" + } + }, + "required": [ + "name", + "version", + "schema_version" + ], + "additionalProperties": false + } + }, + "required": [ + "root", + "generator" + ], + "additionalProperties": false + }, + "boards": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "path": { + "type": "string" + }, + "generated": { + "type": "boolean" + }, + "board": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "vendor": { + "type": [ + "string", + "null" + ] + }, + "revision": { + "type": [ + "string", + "null" + ] + }, + "curated": { + "type": "boolean" + }, + "soc": { + "type": [ + "string", + "null" + ] + }, + "family": { + "type": [ + "string", + "null" + ] + }, + "package": { + "type": [ + "string", + "null" + ] + }, + "core": { + "type": [ + "string", + "null" + ] + }, + "cpu_hz": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "name", + "soc", + "cpu_hz" + ], + "additionalProperties": false, + "description": "A board in one line, from its hw.json." + }, + "problem": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "path", + "generated" + ], + "additionalProperties": false + } + } + }, + "required": [ + "rtos", + "boards" + ], + "additionalProperties": false +} diff --git a/protocol/board.memory.result.schema.json b/protocol/board.memory.result.schema.json new file mode 100644 index 0000000..4535021 --- /dev/null +++ b/protocol/board.memory.result.schema.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.memory: result", + "type": "object", + "properties": { + "regions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "base": { + "type": "integer" + }, + "size": { + "type": "integer" + }, + "attrs": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "name", + "base", + "size" + ], + "additionalProperties": true + } + }, + "flash": { + "type": "object" + }, + "linker": { + "type": "object" + }, + "partitions": { + "type": "array" + } + }, + "required": [ + "regions", + "flash", + "linker", + "partitions" + ], + "additionalProperties": false +} diff --git a/protocol/board.pins.result.schema.json b/protocol/board.pins.result.schema.json new file mode 100644 index 0000000..13b7102 --- /dev/null +++ b/protocol/board.pins.result.schema.json @@ -0,0 +1,70 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "board.pins: result", + "type": "object", + "properties": { + "package": { + "type": [ + "string", + "null" + ] + }, + "assigned": { + "type": "array", + "items": { + "type": "object", + "properties": { + "pin": { + "type": "string" + }, + "port": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "mode": { + "type": "string" + }, + "gpio": { + "type": "string" + }, + "owner": { + "type": "string" + }, + "signal": { + "type": "string" + }, + "af": { + "type": "integer" + } + }, + "required": [ + "pin", + "mode", + "owner" + ], + "additionalProperties": true + } + }, + "alternate_functions": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "ports": { + "type": "object" + } + }, + "required": [ + "package", + "assigned", + "alternate_functions", + "ports" + ], + "additionalProperties": false +} diff --git a/protocol/generate.diff.result.schema.json b/protocol/generate.diff.result.schema.json new file mode 100644 index 0000000..8d80cd3 --- /dev/null +++ b/protocol/generate.diff.result.schema.json @@ -0,0 +1,95 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "generate.diff: result", + "type": "object", + "properties": { + "up_to_date": { + "type": "boolean" + }, + "files": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "status": { + "enum": [ + "unchanged", + "changed", + "added", + "removed" + ] + }, + "diff": { + "type": "string" + }, + "truncated": { + "type": "boolean" + } + }, + "required": [ + "name", + "status" + ], + "additionalProperties": false + } + }, + "diagnostics": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "enum": [ + "error", + "warning" + ] + }, + "source": { + "type": "string" + }, + "message": { + "type": "string" + }, + "file": { + "type": "string", + "description": "Absolute path." + }, + "line": { + "type": "integer", + "minimum": 1 + }, + "path": { + "type": "string", + "description": "The node's path in the YAML, such as pins.usart2.tx; (root) for the document." + } + }, + "required": [ + "severity", + "source", + "message" + ], + "additionalProperties": false + } + }, + "errors": { + "type": "integer", + "minimum": 0 + }, + "warnings": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "up_to_date", + "files", + "diagnostics", + "errors", + "warnings" + ], + "additionalProperties": false, + "description": "Which generated files a generate would change, and how; nothing is written." +} diff --git a/protocol/generate.run.result.schema.json b/protocol/generate.run.result.schema.json new file mode 100644 index 0000000..2146b8f --- /dev/null +++ b/protocol/generate.run.result.schema.json @@ -0,0 +1,133 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "generate.run: result", + "type": "object", + "properties": { + "written": { + "type": "boolean" + }, + "files": { + "type": "array", + "items": { + "type": "string" + } + }, + "board": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "vendor": { + "type": [ + "string", + "null" + ] + }, + "revision": { + "type": [ + "string", + "null" + ] + }, + "curated": { + "type": "boolean" + }, + "soc": { + "type": [ + "string", + "null" + ] + }, + "family": { + "type": [ + "string", + "null" + ] + }, + "package": { + "type": [ + "string", + "null" + ] + }, + "core": { + "type": [ + "string", + "null" + ] + }, + "cpu_hz": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "name", + "soc", + "cpu_hz" + ], + "additionalProperties": false, + "description": "A board in one line, from its hw.json." + }, + "diagnostics": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "enum": [ + "error", + "warning" + ] + }, + "source": { + "type": "string" + }, + "message": { + "type": "string" + }, + "file": { + "type": "string", + "description": "Absolute path." + }, + "line": { + "type": "integer", + "minimum": 1 + }, + "path": { + "type": "string", + "description": "The node's path in the YAML, such as pins.usart2.tx; (root) for the document." + } + }, + "required": [ + "severity", + "source", + "message" + ], + "additionalProperties": false + } + }, + "errors": { + "type": "integer", + "minimum": 0 + }, + "warnings": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "written", + "files", + "diagnostics", + "errors", + "warnings" + ], + "additionalProperties": false +} diff --git a/protocol/project.close.result.schema.json b/protocol/project.close.result.schema.json new file mode 100644 index 0000000..772d1fc --- /dev/null +++ b/protocol/project.close.result.schema.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.close: result", + "type": "null" +} diff --git a/protocol/project.open.params.schema.json b/protocol/project.open.params.schema.json new file mode 100644 index 0000000..d73e023 --- /dev/null +++ b/protocol/project.open.params.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.open: parameters", + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "A board directory of an EmbLinkRTOS checkout, boards///." + } + }, + "required": [ + "path" + ], + "additionalProperties": false +} diff --git a/protocol/project.open.result.schema.json b/protocol/project.open.result.schema.json new file mode 100644 index 0000000..3e4c1b3 --- /dev/null +++ b/protocol/project.open.result.schema.json @@ -0,0 +1,135 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.open: result", + "type": "object", + "properties": { + "kind": { + "const": "board", + "description": "In stage S1, a workspace is a board of an RTOS checkout." + }, + "path": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Such as st/nucleo_f446re." + }, + "name": { + "type": "string" + }, + "rtos": { + "type": "object", + "properties": { + "root": { + "type": "string" + }, + "generator": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "schema_version": { + "type": "integer" + } + }, + "required": [ + "name", + "version", + "schema_version" + ], + "additionalProperties": false + } + }, + "required": [ + "root", + "generator" + ], + "additionalProperties": false + }, + "trusted": { + "type": "boolean", + "description": "Whether the checkout may run its generator (spec section 9)." + }, + "generated": { + "type": "boolean", + "description": "Whether generated/hw.json exists." + }, + "board": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "vendor": { + "type": [ + "string", + "null" + ] + }, + "revision": { + "type": [ + "string", + "null" + ] + }, + "curated": { + "type": "boolean" + }, + "soc": { + "type": [ + "string", + "null" + ] + }, + "family": { + "type": [ + "string", + "null" + ] + }, + "package": { + "type": [ + "string", + "null" + ] + }, + "core": { + "type": [ + "string", + "null" + ] + }, + "cpu_hz": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "name", + "soc", + "cpu_hz" + ], + "additionalProperties": false, + "description": "A board in one line, from its hw.json." + } + }, + "required": [ + "kind", + "path", + "id", + "name", + "rtos", + "trusted", + "generated" + ], + "additionalProperties": false +} diff --git a/protocol/project.status.result.schema.json b/protocol/project.status.result.schema.json new file mode 100644 index 0000000..26b27e2 --- /dev/null +++ b/protocol/project.status.result.schema.json @@ -0,0 +1,135 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.status: result", + "type": "object", + "properties": { + "kind": { + "const": "board", + "description": "In stage S1, a workspace is a board of an RTOS checkout." + }, + "path": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Such as st/nucleo_f446re." + }, + "name": { + "type": "string" + }, + "rtos": { + "type": "object", + "properties": { + "root": { + "type": "string" + }, + "generator": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "schema_version": { + "type": "integer" + } + }, + "required": [ + "name", + "version", + "schema_version" + ], + "additionalProperties": false + } + }, + "required": [ + "root", + "generator" + ], + "additionalProperties": false + }, + "trusted": { + "type": "boolean", + "description": "Whether the checkout may run its generator (spec section 9)." + }, + "generated": { + "type": "boolean", + "description": "Whether generated/hw.json exists." + }, + "board": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "vendor": { + "type": [ + "string", + "null" + ] + }, + "revision": { + "type": [ + "string", + "null" + ] + }, + "curated": { + "type": "boolean" + }, + "soc": { + "type": [ + "string", + "null" + ] + }, + "family": { + "type": [ + "string", + "null" + ] + }, + "package": { + "type": [ + "string", + "null" + ] + }, + "core": { + "type": [ + "string", + "null" + ] + }, + "cpu_hz": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "name", + "soc", + "cpu_hz" + ], + "additionalProperties": false, + "description": "A board in one line, from its hw.json." + } + }, + "required": [ + "kind", + "path", + "id", + "name", + "rtos", + "trusted", + "generated" + ], + "additionalProperties": false +} diff --git a/protocol/project.trust.result.schema.json b/protocol/project.trust.result.schema.json new file mode 100644 index 0000000..305c0d9 --- /dev/null +++ b/protocol/project.trust.result.schema.json @@ -0,0 +1,135 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.trust: result", + "type": "object", + "properties": { + "kind": { + "const": "board", + "description": "In stage S1, a workspace is a board of an RTOS checkout." + }, + "path": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Such as st/nucleo_f446re." + }, + "name": { + "type": "string" + }, + "rtos": { + "type": "object", + "properties": { + "root": { + "type": "string" + }, + "generator": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "version": { + "type": "string" + }, + "schema_version": { + "type": "integer" + } + }, + "required": [ + "name", + "version", + "schema_version" + ], + "additionalProperties": false + } + }, + "required": [ + "root", + "generator" + ], + "additionalProperties": false + }, + "trusted": { + "type": "boolean", + "description": "Whether the checkout may run its generator (spec section 9)." + }, + "generated": { + "type": "boolean", + "description": "Whether generated/hw.json exists." + }, + "board": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "vendor": { + "type": [ + "string", + "null" + ] + }, + "revision": { + "type": [ + "string", + "null" + ] + }, + "curated": { + "type": "boolean" + }, + "soc": { + "type": [ + "string", + "null" + ] + }, + "family": { + "type": [ + "string", + "null" + ] + }, + "package": { + "type": [ + "string", + "null" + ] + }, + "core": { + "type": [ + "string", + "null" + ] + }, + "cpu_hz": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "name", + "soc", + "cpu_hz" + ], + "additionalProperties": false, + "description": "A board in one line, from its hw.json." + } + }, + "required": [ + "kind", + "path", + "id", + "name", + "rtos", + "trusted", + "generated" + ], + "additionalProperties": false +} diff --git a/protocol/project.validate.result.schema.json b/protocol/project.validate.result.schema.json new file mode 100644 index 0000000..8f9e3dc --- /dev/null +++ b/protocol/project.validate.result.schema.json @@ -0,0 +1,64 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "project.validate: result", + "type": "object", + "properties": { + "valid": { + "type": "boolean" + }, + "diagnostics": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { + "enum": [ + "error", + "warning" + ] + }, + "source": { + "type": "string" + }, + "message": { + "type": "string" + }, + "file": { + "type": "string", + "description": "Absolute path." + }, + "line": { + "type": "integer", + "minimum": 1 + }, + "path": { + "type": "string", + "description": "The node's path in the YAML, such as pins.usart2.tx; (root) for the document." + } + }, + "required": [ + "severity", + "source", + "message" + ], + "additionalProperties": false + } + }, + "errors": { + "type": "integer", + "minimum": 0 + }, + "warnings": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "valid", + "diagnostics", + "errors", + "warnings" + ], + "additionalProperties": false, + "description": "The generator's verdict on the board and its SoC, every diagnostic located." +} diff --git a/third_party/components.json b/third_party/components.json index 4fbc11b..40ecbd2 100644 --- a/third_party/components.json +++ b/third_party/components.json @@ -23,6 +23,14 @@ "url": "https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System", "source": "https://github.com/githubuser0xFFFF/Qt-Advanced-Docking-System/archive/refs/tags/v5.1.1.tar.gz", "used_by": "the desktop application: docking and layouts" + }, + { + "name": "PyYAML", + "version": "6.0", + "licence": "MIT", + "url": "https://pyyaml.org/", + "source": "https://github.com/yaml/pyyaml", + "used_by": "EmbLink Studio Core: the Python that runs the RTOS's generator, emb-hwgen, which reads YAML with it" } ] } From ba95325ba36a28d9bffef1ecebe40e2cad751b7a Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:04:16 +0100 Subject: [PATCH 2/4] core tests: Windows paths; show the generator's output when it fails Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- core/tests/test_diagnostics.py | 2 +- core/tests/test_rtos_acceptance.py | 13 +++++++++++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/core/tests/test_diagnostics.py b/core/tests/test_diagnostics.py index c46afd0..1c42584 100644 --- a/core/tests/test_diagnostics.py +++ b/core/tests/test_diagnostics.py @@ -55,7 +55,7 @@ def test_files_outside_the_checkout_stay_absolute(): "/home/me/boards/st/x/board.yaml:7: name: 'nucleo_f446re' differs from its directory 'x'", ROOT, ) - assert d["file"] == "/home/me/boards/st/x/board.yaml" + assert d["file"] == str(Path("/home/me/boards/st/x/board.yaml")) assert d["path"] == "name" diff --git a/core/tests/test_rtos_acceptance.py b/core/tests/test_rtos_acceptance.py index ef9d515..391943f 100644 --- a/core/tests/test_rtos_acceptance.py +++ b/core/tests/test_rtos_acceptance.py @@ -27,11 +27,20 @@ import jsonschema import pytest +from emblink_studio_core.errors import CoreError from emblink_studio_core.workspace import Workspace RTOS = os.environ.get("EMBLINK_STUDIO_TEST_RTOS") pytestmark = pytest.mark.skipif(not RTOS, reason="EMBLINK_STUDIO_TEST_RTOS is not set") + +def validate(board_dir): + """The validation, or a failure that shows what the generator printed.""" + try: + return Workspace.open(board_dir).validate() + except CoreError as exc: + pytest.fail(f"{exc.message}\n{(exc.data or {}).get('output', '')}") + BOARDS = { # board: (part, cpu_hz, a pin in use and its signal, the first memory region) "st/nucleo_f446re": ("STM32F446RE", 180_000_000, ("PA2", "usart2_tx"), "flash"), @@ -72,7 +81,7 @@ def test_opening_a_board_shows_its_model(board_id, schemas): @pytest.mark.parametrize("board_id", sorted(BOARDS)) def test_the_committed_boards_are_valid(board_id, schemas): - result = Workspace.open(Path(RTOS) / "boards" / board_id).validate() + result = validate(Path(RTOS) / "boards" / board_id) jsonschema.validate(result, schemas["project.validate.result.schema.json"]) assert result["valid"] is True, result assert result["errors"] == 0 @@ -110,7 +119,7 @@ def test_errors_are_reported_where_they_are(tmp_path, schemas): expected[path] = next(i for i, line in enumerate(lines, 1) if needle in line) board_yaml.write_text(text, encoding="utf-8") - result = Workspace.open(root / board_rel).validate() + result = validate(root / board_rel) jsonschema.validate(result, schemas["project.validate.result.schema.json"]) assert result["valid"] is False errors = {d["path"]: d for d in result["diagnostics"] if d["severity"] == "error"} From f031889aa9fddafd3f6f9f38d4681d0e35f0c6f0 Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:06:46 +0100 Subject: [PATCH 3/4] core tests: format Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- core/tests/test_rtos_acceptance.py | 1 + 1 file changed, 1 insertion(+) diff --git a/core/tests/test_rtos_acceptance.py b/core/tests/test_rtos_acceptance.py index 391943f..a3e54f7 100644 --- a/core/tests/test_rtos_acceptance.py +++ b/core/tests/test_rtos_acceptance.py @@ -41,6 +41,7 @@ def validate(board_dir): except CoreError as exc: pytest.fail(f"{exc.message}\n{(exc.data or {}).get('output', '')}") + BOARDS = { # board: (part, cpu_hz, a pin in use and its signal, the first memory region) "st/nucleo_f446re": ("STM32F446RE", 180_000_000, ("PA2", "usart2_tx"), "flash"), From abdac64ac261f4859ecf30e4e4a345088a16448d Mon Sep 17 00:00:00 2001 From: teo1747 <148846371+teo1747@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:26:32 +0100 Subject: [PATCH 4/4] core acceptance: the clock error on Python 3.12+ only, until the RTOS's generator is fixed Signed-off-by: teo1747 <148846371+teo1747@users.noreply.github.com> --- core/tests/test_rtos_acceptance.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/core/tests/test_rtos_acceptance.py b/core/tests/test_rtos_acceptance.py index a3e54f7..bcba4e7 100644 --- a/core/tests/test_rtos_acceptance.py +++ b/core/tests/test_rtos_acceptance.py @@ -22,6 +22,7 @@ import json import os import shutil +import sys from pathlib import Path import jsonschema @@ -105,10 +106,15 @@ def test_errors_are_reported_where_they_are(tmp_path, schemas): board_yaml = root / board_rel / "board.yaml" text = board_yaml.read_text(encoding="utf-8") broken = { - "cpu_hz: 180MHz": ("cpu_hz: 900MHz", "clocks.pll"), "usart2: { tx: PA2.af7": ("usart2: { tx: PA2.af9", "pins.usart2.tx"), "console: { device: usart2": ("console: { device: usart9", "console.device"), } + # emb-hwgen at the pinned revision formats a Fraction with ':g' while reporting a clock + # error (emb_hwgen/clock.py, _mhz), which Python accepts from 3.12 only, so on 3.11 the + # generator crashes there, and the core says so (tool_failed). Checked on 3.12 and later + # until the RTOS is fixed and the pin raised. + if sys.version_info >= (3, 12): + broken["cpu_hz: 180MHz"] = ("cpu_hz: 900MHz", "clocks.pll") expected = {} for good, (bad, _path) in broken.items(): assert good in text, f"the NUCLEO-F446RE's description changed: no '{good}'"