dapps 0.3.0__tar.gz → 0.3.1__tar.gz

{dapps-0.3.0 → dapps-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.3.0
+Version: 0.3.1
 Summary: A library for creating and connecting dApps to Open RAN units.
 Keywords: dApps,O-RAN,5G,cellular,networks
 Author-Email: Andrea Lacava <thecave003@gmail.com>

dapps-0.3.1/VERSION

@@ -0,0 +1 @@
+0.3.1

{dapps-0.3.0 → dapps-0.3.1}/src/e3interface/e3_interface.py

@@ -90,6 +90,9 @@ class E3Interface:
             # Guards the three callback dicts above: caller-thread add_/remove_*
             # vs. inbound-thread iteration in the _handle_* dispatchers.
             self._callback_lock = threading.Lock()
+            # Source of the report correlation ids (see schedule_report).
+            self._report_seq = 0
+            self._report_seq_lock = threading.Lock()
             self.stop_event = threading.Event()
             # Subscription-response correlation. The wire is fire-and-forget, so a
             # queued request is NOT an accepted one — a queue put() succeeding
@@ -336,7 +339,7 @@ class E3Interface:
                         case "report":
                             rc = self.agent.send_report(
                                 data["ranFunctionId"], data["reportData"],
-                                data.get("sequenceId", 0))
+                                data["sequenceId"])
                         case "release":
                             rc = self.agent.release()
                         case _:
@@ -467,12 +470,28 @@ class E3Interface:
             'latSeq': latrec.ctx(),
         }))
 
-    def schedule_report(self, dappId: int, ranFunctionId: int, reportData: bytes):
+    def _next_report_sequence_id(self) -> int:
+        """Next correlation id for a report: 1..4294967295, wrapping to 1 (0 is not a valid id)."""
+        with self._report_seq_lock:
+            self._report_seq = self._report_seq % 0xFFFFFFFF + 1
+            return self._report_seq
+
+    def schedule_report(self, dappId: int, ranFunctionId: int, reportData: bytes,
+                        sequenceId: int = 0) -> int:
+        """Queue a report and return its correlation id.
+
+        The id is mandatory on the wire (E3-SequenceID, 1..4294967295) and travels on to the
+        xApp. Pass the one you want, or leave it at 0 to get the next one from this interface.
+        """
+        if not sequenceId:
+            sequenceId = self._next_report_sequence_id()
         self.outbound_queue.put(('report', {
             'ranFunctionId': ranFunctionId,
             'reportData': reportData,
+            'sequenceId': sequenceId,
             'latSeq': latrec.ctx(),
         }))
+        return sequenceId
 
     def add_subscription_callback(self, dapp_id: int, callback):
         with self._callback_lock:

{dapps-0.3.0 → dapps-0.3.1}/src/e3interface/libe3_agent.py

@@ -247,7 +247,7 @@ class Libe3Agent:
     ) -> int:
         """Send a subscribe request.
 
-        Returns the assigned request id (a positive int, 1..1000) on success —
+        Returns the assigned request id (a positive int) on success —
         so the caller can correlate the SubscriptionResponse (which echoes
         ``request_id``) back to this call — or a negative libe3 ErrorCode on
         failure.
@@ -275,11 +275,12 @@ class Libe3Agent:
         return self._session.send_control(int(ran_function_id), int(control_id), bytes(action_data),
                                           int(sequence_id))
 
-    def send_report(self, ran_function_id: int, report_data: bytes, sequence_id: int = 0) -> int:
+    def send_report(self, ran_function_id: int, report_data: bytes, sequence_id: int) -> int:
         """Send a report to the RAN.
 
         ``sequence_id`` is the correlation id this dApp assigns to the detection;
-        it travels to the xApp on the resulting E2 indication. 0 means unset.
+        it travels to the xApp on the resulting E2 indication. It is mandatory on the
+        wire (1..4294967295); 0 is not valid and is refused with a negative ErrorCode.
         """
         return self._session.send_report(int(ran_function_id), bytes(report_data), int(sequence_id))
 

{dapps-0.3.0 → dapps-0.3.1}/src/spectrum/policy.py

@@ -3,7 +3,8 @@
 A policy decides which PRBs the gNB must stop using. The dApp feeds it one
 :class:`Observation` per detector run and sends the PRB blacklist it returns.
 Everything else (E3 connection, subscriptions, DC-leakage guard, control
-reconciliation and rate limiting) stays in :class:`spectrum.spectrum_dapp.SpectrumSharingDApp`.
+reconciliation, which sends a control only when the set changed) stays in
+:class:`spectrum.spectrum_dapp.SpectrumSharingDApp`.
 
 Write a policy by subclassing :class:`Policy`::
 
@@ -62,9 +63,9 @@ class Observation:
 class Policy(ABC):
     """Base class of a PRB-blocking policy.
 
-    The dApp calls :meth:`update` once per observation (roughly every 20 ms with the
-    default gNB settings). It returns the set of PRB indices to block; PRBs that are
-    not returned are released. State between calls lives on ``self``;
+    The dApp calls :meth:`update` once per observation (every few milliseconds, about
+    6.7 ms nominal, depending on how fast the gNB runs). It returns the set of PRB
+    indices to block; PRBs that are not returned are released. State between calls lives on ``self``;
     ``self.history`` holds the last ``history_len`` observations, the current one last.
     """
 

{dapps-0.3.0 → dapps-0.3.1}/src/spectrum/spectrum_dapp.py

@@ -755,11 +755,11 @@ class SpectrumSharingDApp(DApp):
         Spectrum-DAppControlData envelope.
 
         Drives the gNB's per-MAC prb_block_state_t via set_prb_block_mask():
-        each PRB in ``blocked_prbs`` gets every UL symbol marked occupied,
-        so downstream scheduling treats it as unavailable.
+        each PRB in ``blocked_prbs`` gets every UL symbol marked occupied and is
+        withheld from DL scheduling too, so the gNB uses it in neither direction.
 
         Args:
-            blocked_prbs: List of PRB indices to block on the UL
+            blocked_prbs: List of PRB indices to block (UL and DL)
             update_sampling: Whether to include the updated sampling threshold
             validity_period: How long this block is valid in seconds (optional)
 
@@ -1747,10 +1747,10 @@ class SpectrumSharingDApp(DApp):
         # mask-of-slot-N applied to IQ-of-slot-N+k → UE energy bleeding
         # into "sensing" cells.
         #
-        # Threshold matches the gNB ring TTL: 64 rows × 2 buffers = 128
-        # slots × ~0.5 ms/slot at 30 kHz SCS ≈ 64 ms safety budget. We use
-        # 50 ms as a conservative cutoff. If breached, treat the IQ as
-        # untrustworthy and skip the slot.
+        # The bound comes from the ring depth in the shm header (see
+        # _shm_staleness_ns): 16 rows × 2 buffers = 32 slots × 0.5 ms/slot at
+        # 30 kHz SCS = 16 ms. Until the header is read a fixed 50 ms is used.
+        # If breached, treat the IQ as untrustworthy and skip the slot.
         if p.timestamp_ns > 0:
             lag_ns = t.recv_ns - p.timestamp_ns
             stale_ns = self._shm_staleness_ns()

{dapps-0.3.0 → dapps-0.3.1}/tests/test_latrec_stamps.py

@@ -47,6 +47,8 @@ def _iface():
     iface.subscription_callbacks = {}
     iface.xapp_control_callbacks = {}
     iface._callback_lock = threading.Lock()
+    iface._report_seq = 0
+    iface._report_seq_lock = threading.Lock()
     iface.stop_event = threading.Event()
     iface.outbound_queue = queue.Queue()
     return iface

{dapps-0.3.0 → dapps-0.3.1}/tests/test_outbound_send_result.py

@@ -42,7 +42,7 @@ def _drain(rc, msg, data, caplog):
 
 
 CONTROL = {"ranFunctionId": 1, "controlId": 1, "actionData": b"x"}
-REPORT = {"ranFunctionId": 1, "reportData": b"x"}
+REPORT = {"ranFunctionId": 1, "reportData": b"x", "sequenceId": 1}
 
 
 @pytest.mark.parametrize("msg,data", [("control", CONTROL), ("report", REPORT)])

dapps-0.3.1/tests/test_report_sequence_id.py

@@ -0,0 +1,51 @@
+"""A report always carries a non-zero correlation id: E3-SequenceID is 1..4294967295 on the wire."""
+import os
+import queue
+import sys
+import threading
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from e3interface.e3_interface import E3Interface
+
+
+def _iface():
+    iface = object.__new__(E3Interface)
+    iface.outbound_queue = queue.Queue()
+    iface._report_seq = 0
+    iface._report_seq_lock = threading.Lock()
+    return iface
+
+
+def test_a_report_gets_the_next_non_zero_id():
+    iface = _iface()
+    ids = [iface.schedule_report(1, 1, b"x") for _ in range(3)]
+    assert ids == [1, 2, 3]
+    queued = [iface.outbound_queue.get_nowait()[1]["sequenceId"] for _ in range(3)]
+    assert queued == ids
+
+
+def test_an_id_given_by_the_caller_is_kept():
+    iface = _iface()
+    assert iface.schedule_report(1, 1, b"x", sequenceId=77) == 77
+    assert iface.outbound_queue.get_nowait()[1]["sequenceId"] == 77
+
+
+def test_the_id_wraps_to_1_and_never_reaches_0():
+    iface = _iface()
+    iface._report_seq = 0xFFFFFFFE
+    assert iface.schedule_report(1, 1, b"x") == 0xFFFFFFFF
+    assert iface.schedule_report(1, 1, b"x") == 1
+
+
+def test_ids_are_unique_across_threads():
+    iface = _iface()
+    out = []
+
+    def work():
+        out.extend(iface.schedule_report(1, 1, b"x") for _ in range(500))
+
+    threads = [threading.Thread(target=work) for _ in range(4)]
+    [t.start() for t in threads]
+    [t.join() for t in threads]
+    assert len(set(out)) == 2000

dapps-0.3.0/VERSION

@@ -1 +0,0 @@
-0.3.0