remoteRF-server 1.7.22__tar.gz → 1.7.23__tar.gz

{remoterf_server-1.7.22 → remoterf_server-1.7.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remoteRF-server
-Version: 1.7.22
+Version: 1.7.23
 Summary: RemoteRF server-side control package
 License: GPL-3.0-or-later
 Classifier: Programming Language :: Python :: 3
@@ -10,7 +10,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: remoterf-federation-core==0.22.0
-Requires-Dist: remoterf-device-core==0.1.6
+Requires-Dist: remoterf-device-core==0.1.7
 Requires-Dist: grpcio<2.0.0,>=1.81.1
 Requires-Dist: protobuf<7.0.0,>=6.33.5
 Requires-Dist: numpy

{remoterf_server-1.7.22 → remoterf_server-1.7.23}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "remoteRF-server"
-version = "1.7.22"
+version = "1.7.23"
 description = "RemoteRF server-side control package"
 license = { text = "GPL-3.0-or-later" }
 requires-python = ">=3.10"
 dependencies = [
     "remoterf-federation-core==0.22.0",
-    "remoterf-device-core==0.1.6",
+    "remoterf-device-core==0.1.7",
   "grpcio>=1.81.1,<2.0.0",
   "protobuf>=6.33.5,<7.0.0",
   "numpy",
@@ -60,3 +60,4 @@ where = ["src"]
 
 [tool.setuptools.package-data]
 "remoteRF_server.common.grpc" = ["*.proto"]
+"remoteRF_server.adapters.oai" = ["integration.json"]

remoterf_server-1.7.23/src/remoteRF_server/adapters/oai/__init__.py

@@ -0,0 +1,115 @@
+"""gNB-only OAI scaffold; this adapter TRANSMITS (gNB).
+
+The operator-supplied executable and configuration are not managed by this
+adapter; the operator installs and reviews them.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+import time
+
+
+SERIAL = re.compile(r"[A-Za-z0-9]{1,64}")
+EXTRA_ARGS = ()
+READY_MARKER = "ALL RUs ready"
+STARTUP_TIMEOUT = 25.0
+
+
+def serial_selector(value):
+    if type(value) is not dict or set(value) != {"serial"} or type(value["serial"]) is not str:
+        raise ValueError("one explicit USRP serial is required")
+    if not SERIAL.fullmatch(value["serial"]):
+        raise ValueError("invalid USRP serial")
+    return value["serial"]
+
+
+def _operator_file(name):
+    value = os.environ.get(name)
+    path = Path(value) if value is not None else Path()
+    if value is None or not path.is_absolute() or not path.is_file():
+        raise RuntimeError(f"{name} must name an absolute existing regular file")
+    return str(path)
+
+
+class OAI:
+    def __init__(self, context):
+        self._context = context
+        self._process_id = None
+        self._ready = False
+        self._stopped = False
+
+    def validate(self, profile, configuration):
+        if profile != "gnb" or type(configuration) is not dict or configuration:
+            raise ValueError("unsupported gNB configuration")
+        return {}
+
+    def _process(self):
+        rows = self._context.processes.snapshot()["processes"]
+        row = next((row for row in rows if row["id"] == self._process_id), None)
+        if row is None or row["returncode"] is not None:
+            raise RuntimeError("OAI gNB process is no longer running")
+        return row
+
+    def start(self, profile, configuration):
+        self.validate(profile, configuration)
+        serial = serial_selector(self._context.selector)
+        processes = self._context.processes
+        work_dir = Path(self._context.work_dir)
+        if processes is None or not work_dir.is_absolute():
+            raise RuntimeError("owned process supervision is required")
+        if self._process_id is not None or self._stopped:
+            raise RuntimeError("OAI gNB has already started or stopped")
+        if self._context.cancelled.is_set():
+            raise RuntimeError("OAI gNB was cancelled")
+
+        softmodem = _operator_file("REMOTERF_OAI_SOFTMODEM")
+        conf = _operator_file("REMOTERF_OAI_GNB_CONF")
+        env = {"LANG": "C.UTF-8", "LC_ALL": "C.UTF-8"}
+        if "UHD_IMAGES_DIR" in os.environ:
+            env["UHD_IMAGES_DIR"] = os.environ["UHD_IMAGES_DIR"]
+
+        # EXTRA_ARGS, READY_MARKER, and sdr_addrs require verification against the pinned OAI build.
+        argv = [softmodem, "-O", conf, *EXTRA_ARGS,
+                "--RUs.[0].sdr_addrs", f"serial={serial}"]
+        self._process_id = processes.launch(
+            argv, env=env, cwd=work_dir, required_while_running=True)
+        deadline = time.monotonic() + STARTUP_TIMEOUT
+        while time.monotonic() < deadline:
+            if self._context.cancelled.is_set():
+                raise RuntimeError("OAI gNB was cancelled")
+            self._process()
+            tail = processes.log_tail(self._process_id, "stdout")[-65536:]
+            if READY_MARKER in tail.decode("utf-8", errors="replace"):
+                self._ready = True
+                return
+            time.sleep(0.1)
+        raise RuntimeError("OAI gNB did not reach readiness")
+
+    def status(self):
+        if self._stopped:
+            return {"ready": False, "stopped": True}
+        if not self._ready:
+            return {"ready": False}
+        self._process()
+        return {"ready": True}
+
+    def call(self, action, parameters):
+        if action != "health" or type(parameters) is not dict or parameters:
+            raise ValueError("health accepts no parameters")
+        return self.status()
+
+    def stop(self):
+        if self._stopped:
+            return
+        if self._context.processes is None:
+            self._stopped = True
+            return
+        if not self._context.processes.stop(timeout=10.0):
+            raise RuntimeError("OAI gNB cleanup could not be verified")
+        self._stopped = True
+
+
+def create_adapter(context):
+    return OAI(context)

remoterf_server-1.7.23/src/remoteRF_server/adapters/oai/integration.json

@@ -0,0 +1 @@
+{"id":"org.remoterf.oai","version":"0.1.0","contract_version":"0.1","factory":"remoteRF_server.adapters.oai:create_adapter","device_types":["usrp"],"profiles":["gnb"],"actions":["health"]}

{remoterf_server-1.7.22 → remoterf_server-1.7.23}/src/remoteRF_server/server/device_manager.py

@@ -43,6 +43,9 @@ from ..host import host_tunnel_server as hts
 
 logger = logging.getLogger(__name__)
 
+from remoterf_device_core.hardware_access import AccessTable
+hardware_access = AccessTable()
+
 _state_lock = threading.RLock()
 _reservation_end_callbacks: list = []
 # token -> (gid, salt, hsh): see reservation_bridge_token()
@@ -926,23 +929,56 @@ def _start_host_reservation(device: VirtualDevice) -> None:
 
 
 def _prepare_for_holder(device_id: int, held: Tuple[str, str]) -> None:
-    """A reservation started: ready the device (a PoE Pluto boots) before the
-    holder's first call, which waits on io_lock for this same boot meanwhile."""
+    """Prepare only after verified previous release and for the current holder."""
+    from remoterf_device_core.integrations import IntegrationError
     with _state_lock:
         st = _devices.get(int(device_id))
     if st is None:
         return
+    retry = lambda: _prepare_for_holder(device_id, held)
     with st.io_lock:
-        _reset_locked(st)  # a back-to-back predecessor's power-down comes first
         with _state_lock:
             if _devices.get(int(device_id)) is not st or (st.salt, st.hsh) != held:
-                return  # the reservation is already over: leave the device off
+                return
+        if _native_cleanup_pending(device_id):
+            _after_native_cleanup(device_id, "prepare", retry)
+            return
         try:
-            st.dev.prepare_for_holder()
+            with hardware_access.native(device_id):
+                _reset_locked(st)
+                st.dev.prepare_for_holder()
+        except IntegrationError as exc:
+            if exc.code != "device_owned":
+                raise
+            _after_native_cleanup(device_id, "prepare", retry)
         except Exception as exc:
             print(f"Warning: preparing {st.name or st.ident} for its reservation failed: {exc}")
 
 
+_deferred_native_hooks = {}
+
+
+def _after_native_cleanup(gid, kind, action):
+    from remoterf_device_core.native_lifetime import submit_cleanup
+    key = (int(gid), kind)
+    with _state_lock:
+        already = key in _deferred_native_hooks
+        _deferred_native_hooks[key] = action
+    if already:
+        return
+    def run():
+        with _state_lock:
+            latest = _deferred_native_hooks.pop(key)
+        latest()
+    submit_cleanup(lambda: not _native_cleanup_pending(gid), run)
+
+
+def _native_cleanup_pending(gid):
+    # Import lazily: device inventory is loaded before the session runtime.
+    from .dynamic_v2 import session_manager
+    return session_manager.cleanup_pending(gid) or hardware_access.blocked(gid)
+
+
 def _reset_locked(st: _DeviceState) -> None:
     """Under st.io_lock: drop what the last reservation left on the device
     (buffers, streamers, a running transmitter) before anyone else drives it."""
@@ -958,11 +994,26 @@ def _reset_locked(st: _DeviceState) -> None:
 
 
 def _reset_if_pending(device_id: int) -> None:
+    from remoterf_device_core.integrations import IntegrationError
     with _state_lock:
         st = _devices.get(int(device_id))
-    if st is not None:
-        with st.io_lock:
-            _reset_locked(st)
+    if st is None:
+        return
+    retry = lambda: _reset_if_pending(device_id)
+    with st.io_lock:
+        with _state_lock:
+            if _devices.get(int(device_id)) is not st:
+                return
+        if _native_cleanup_pending(device_id):
+            _after_native_cleanup(device_id, "reset", retry)
+            return
+        try:
+            with hardware_access.native(device_id):
+                _reset_locked(st)
+        except IntegrationError as exc:
+            if exc.code != "device_owned":
+                raise
+            _after_native_cleanup(device_id, "reset", retry)
 
 
 def reservation_bridge_token(device_id: int, expect=None) -> str:
@@ -1013,6 +1064,8 @@ def get_local_device_context(device_id: int) -> dict[str, Any] | None:
             "ident": st.ident,
             "name": st.name,
             "reserved": bool(st.salt or st.hsh),
+            "io_lock": st.io_lock,
+            "prepare": lambda: _reset_if_pending(int(device_id)),
         }
 
 
@@ -1086,7 +1139,8 @@ def device_is_available(device_id: int) -> bool:
         st = _devices.get(int(device_id))
         if not st or not _is_connected(st):
             return False
-        return (st.salt == "") and (st.hsh == "")
+        available = (st.salt == "") and (st.hsh == "")
+    return available and not hardware_access.blocked(device_id) and not _native_cleanup_pending(device_id)
 
 def get_device_by_id(device_id: int):
     _sync_host_devices()
@@ -1370,8 +1424,11 @@ def acquire_device(api_token: str) -> Iterator[Tuple[int, object]]:
 
     lock.acquire()
     try:
-        _reset_locked(st)
-        yield int(gid), dev
+        with hardware_access.native(gid):
+            if _native_cleanup_pending(gid):
+                raise RuntimeError("previous native cleanup is still in progress")
+            _reset_locked(st)
+            yield int(gid), dev
     finally:
         lock.release()
 
@@ -1398,8 +1455,11 @@ def acquire_device_by_gid(gid: int) -> Iterator[Tuple[int, object]]:
 
     lock.acquire()
     try:
-        _reset_locked(st)
-        yield int(gid), dev
+        with hardware_access.native(gid):
+            if _native_cleanup_pending(gid):
+                raise RuntimeError("previous native cleanup is still in progress")
+            _reset_locked(st)
+            yield int(gid), dev
     finally:
         lock.release()
 
@@ -1476,6 +1536,19 @@ _reload_lock = threading.Lock()
 
 
 def _reload_devices_locked(on_device=None) -> None:
+    from .dynamic_v2 import session_manager
+    session_manager.integrations.validate_inventory(_load_device_records())
+    with _state_lock:
+        gids = [gid for gid, st in _devices.items() if st.origin == "local" and st.dev is not None]
+    with hardware_access.maintenance(gids):
+        for gid in gids:
+            session_manager.close_gid(gid)
+        if any(session_manager.cleanup_pending(gid) for gid in gids):
+            raise RuntimeError("native cleanup is still in progress; retry reload after it finishes")
+        _reload_devices_unfenced(on_device)
+
+
+def _reload_devices_unfenced(on_device=None) -> None:
     # ponytail: reconnects every local device, not just the changed one;
     # diff against the current table if a reload mid-session ever hurts.
     records = _load_device_records()
@@ -1510,7 +1583,10 @@ def _reload_devices_locked(on_device=None) -> None:
 
         if on_device is not None:
             on_device(int(gid), name)
-        dev, ident2, dtype2 = _connect_from_record(rec)
+        if hardware_access.gate(gid).snapshot()['owner'] is not None:
+            dev, ident2, dtype2 = _connect_from_record(rec, connect=False)
+        else:
+            dev, ident2, dtype2 = _connect_from_record(rec)
 
         tmp_info[int(gid)] = name
         if ident:
@@ -1573,14 +1649,49 @@ def _close_schema(schema) -> bool:
 
 
 def close_local_devices() -> int:
-    """Release server-owned native handles during an orderly shutdown."""
+    """Request inventory cleanup, returning the number completed within 0.5s.
+
+    A stuck driver must not prevent attempts for other devices or close an
+    inventory handle while a native call/application still owns the hardware.
+    """
+    from remoterf_device_core.native_lifetime import submit_cleanup
+    from remoterf_device_core.integrations import IntegrationError
     with _state_lock:
-        schemas = [
-            state.dev
-            for state in _devices.values()
+        states = [
+            (gid, state)
+            for gid, state in _devices.items()
             if state.origin == "local" and state.dev is not None
         ]
-    return sum(_close_schema(schema) for schema in schemas)
+    completed = []
+    jobs = []
+    def close(gid, state):
+        try:
+            with state.io_lock:
+                if _native_cleanup_pending(gid):
+                    _after_native_cleanup(gid, "shutdown", lambda: close(gid, state))
+                    return
+                with hardware_access.gate(gid).maintenance():
+                    completed.append(_close_schema(state.dev))
+        except IntegrationError:
+            # Admission changed between readiness and execution. Retain
+            # this schema and retry only after the new owner has drained.
+            _after_native_cleanup(gid, "shutdown", lambda: close(gid, state))
+
+    for gid, state in states:
+        if getattr(state.dev, "device", None) is None:
+            continue
+        def schedule(gid=gid, state=state):
+            return submit_cleanup(lambda: not _native_cleanup_pending(gid)
+                                  and not hardware_access.gate(gid).snapshot()["active_native"],
+                                  lambda: close(gid, state))
+        try:
+            jobs.append(schedule())
+        except Exception:
+            logger.exception("could not schedule inventory cleanup for device %s", gid)
+    deadline = time.monotonic() + 0.5
+    for job in jobs:
+        job.done.wait(max(0.0, deadline - time.monotonic()))
+    return sum(completed)
 
 def set_pluto(ip: str = "192.168.2.1"):
     # kept for compatibility (no-op)

{remoterf_server-1.7.22 → remoterf_server-1.7.23}/src/remoteRF_server/server/diag.py

@@ -162,6 +162,13 @@ def _run_one(row: dict, init: dict, display: _Display, log_fd: int, left_after:
     typical = [_typical(t[1], st.dev) for t in mod.TESTS] + ([restore_s[0]] if teardown else [])
     started_at = time.monotonic()
     ran = False
+    access = []
+    access_lock = threading.Lock()
+
+    def release_access():
+        with access_lock:
+            if access:
+                access.pop().__exit__(None, None, None)
 
     def step(i: int, name: str, timeout: float, fn, step_ctx: dict) -> bool:
         """Run one test; True when it timed out."""
@@ -204,6 +211,9 @@ def _run_one(row: dict, init: dict, display: _Display, log_fd: int, left_after:
         if reason:
             row["status"] = f"skipped: {reason}"
             return
+        ticket = dm.hardware_access.native(gid)
+        ticket.__enter__()
+        access.append(ticket)
         ran = True
         dm._reset_locked(st)
         halted = None
@@ -232,6 +242,7 @@ def _run_one(row: dict, init: dict, display: _Display, log_fd: int, left_after:
 
                 def _release(_f, fs=wedged):
                     if all(f.done() for f in fs):
+                        release_access()
                         dm.diag_release(gid)
 
                 for f in wedged:
@@ -239,6 +250,7 @@ def _run_one(row: dict, init: dict, display: _Display, log_fd: int, left_after:
                 row["tests"].append({"name": "release", "status": "fail",
                                      "detail": "a test is still running; clients stay refused until it ends"})
             else:
+                release_access()
                 dm.diag_release(gid)
             st.io_lock.release()
             _flush_all()