Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
5d30b21
Bind the E3SM spectrum report timestamp and add the E2SM-DAPP origin-…
Thecave3 Aug 28, 2026
305be22
Add the reference Python latrec writer
Thecave3 Aug 22, 2026
183a75d
Replace [LAT] log markers with latrec stamps at B3/B5/B6
Thecave3 Aug 22, 2026
5f886c0
Key ring sizing off the role, and add a per-thread ring accessor
aferaudo Aug 28, 2026
13640f4
Move the stamp sites onto tls_ring, and fix B6's aux
aferaudo Aug 28, 2026
201af9c
Bump VERSION to 0.1.2
Thecave3 Aug 28, 2026
fabeead
Fix binary corruption of E2AP indication payloads in get_c_byte_array…
aferaudo Aug 31, 2026
eb0d8b9
Bump to version 0.1.3
aferaudo Aug 31, 2026
7b71ba4
Decode the E2AP indication once per message, not once per decorator f…
Thecave3 Sep 1, 2026
aa1ebd4
Configure logging from the xApp descriptor (#19)
aferaudo Sep 1, 2026
389f460
Give the dispatcher ownership of the inbound RMR buffer, and free the…
Thecave3 Sep 3, 2026
fb24c2b
Match the Spectrum control ctypes layout (#25)
melkael Sep 3, 2026
430f224
Add per-gNB subscription cleanup (#27)
melkael Sep 3, 2026
3fbd839
fix(report): detect a DELETE that submgr rejected, and get the decode…
aferaudo Sep 7, 2026
bf0f550
Bump to version 0.1.6
aferaudo Sep 7, 2026
e40ed52
feat(dapp): carry the procedure sequence id through an outbound control
Thecave3 Sep 3, 2026
2788f5d
feat(dapp): decode the RIC Control Acknowledge down to the apply outcome
Thecave3 Sep 3, 2026
4048c2f
feat(spectrum): bind the apply-outcome decoder
Thecave3 Sep 3, 2026
d089cff
refactor(dapp): move sequence_id onto the dApp control class
Thecave3 Sep 11, 2026
920b8e1
Carry the ricxappframe patches xDevSM depends on
aferaudo Sep 14, 2026
66f1137
Decode the control acknowledge through ricxappframe, not a second E2A…
aferaudo Sep 14, 2026
196f53f
control: carry the sending gNB's id on the decoded acknowledge
reshma2015 Sep 15, 2026
b127937
control: let the decoded acknowledge actually hold the meid
reshma2015 Sep 18, 2026
be563d6
Remove comments from _with_meid method
reshma2015 Sep 21, 2026
d3df5db
Clean up comments in DAppControlAck.py
reshma2015 Sep 21, 2026
f21bc7a
Remove the comment on the control failure ack path
aferaudo Sep 21, 2026
57f24e7
Rebuild libkpm_sm.so without the per-indication debug output
aferaudo Sep 13, 2026
08b09b1
increased log level to debug
aferaudo Sep 25, 2026
54b5934
control: route control acks by an id of our own (#39)
aferaudo Sep 28, 2026
ed8abc3
control: free the SM-encoded control header and message (#41)
aferaudo Oct 5, 2026
2cb302b
rc: left-align the NR Cell Identity in the handover NR CGI (#45)
aferaudo Oct 16, 2026
c9f7d37
ccc: add the cell-level O-RRMPolicyRatio control (#49)
pietrbr Nov 16, 2026
c475516
ci: pin the PR head test job to ubuntu-24.04
aferaudo Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
# Owners are auto-requested for review on PRs that touch matching files.
# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-security/customizing-your-repository/about-code-owners

# Default owners for everything in the repo (primary maintainer first).
* @aferaudo @leonardobonati @Ninjabippo1205 @Noemi2001 @Thecave3
# Default owner for everything in the repo.
* @aferaudo
4 changes: 3 additions & 1 deletion .github/workflows/commit-trailers.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,9 @@ jobs:
name: PR head installs and tests
needs: changes
if: github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'
runs-on: ubuntu-latest
# Not ubuntu-latest: from 26.04 (glibc >= 2.41) dlopen refuses the bundled SM libraries, which
# need an executable stack. shortcut: pinned to 24.04 until the libraries are rebuilt without it.
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v6
with:
Expand Down
124 changes: 122 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ The architecture separates three main layers:
| **KPM (Key Performance Measurement)** | Measurement Actions | • Common Condition-based Measurement, UE-level Measurement |
| **RC (RAN Control)** | Control Actions | • QoS Flow Mapping Configuration<br>• Slice-level PRB Quota Action (only monolithic gNBs)<br>• Connected Mode Mobility Control |
| **CCC (Cell Configuration and Control)** | Report Actions | • Cell-level RAN Configuration Reporting (REPORT Style 2, periodic event trigger) — e.g. `O-NRCellDU` attributes |
| **CCC (Cell Configuration and Control)** | Control Actions | • Cell-level `O-RRMPolicyRatio` control (CONTROL Style 2): per-slice min, max, and dedicated PRB ratios, tested on OCUDU |
---

## Installation
Expand Down Expand Up @@ -98,7 +99,7 @@ Base class implementing the RMR communication layer. It provides generic `send()

| Method | Description |
| -------------------------------- | --------------------------------------------------------------------------------- |
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. |
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. Must **not** free `sbuf` — see [inbound buffer ownership](#inbound-buffer-ownership). |
| `send(self, *args, **kwargs)` | Sends a message via RMR after encoding. Input depends on the underlying E2SM. |
| `terminate()` | Gracefully stops the xApp. |
| `get_ran_function_description(json_ran_info)` | Uses the `sm_framework` to decode the RAN function description depending on the SM. |
Expand All @@ -117,9 +118,30 @@ Extends `BasexDevSMXapp` to provide additional functionality specific to the xDe
| `register_handler(handler)` | Registers callback handlers. |
| `register_shutdown(handler)` | Registers a shutdown handler for cleanup tasks. |
| `get_ran_info()` | Returns E2 node-related encoded information. |
| `rmr_free(sbuf)` | Frees an RMR message buffer. Overrides `ricxappframe`'s so that freeing the message currently being dispatched is idempotent — see below. |

This class is used as the base class for wrapper components.

### Inbound buffer ownership

`ricxappframe` allocates a fresh 4 KiB C buffer for every message it receives and
transfers ownership to the caller; it never frees it. **xDevSM owns that buffer**:
`xDevSMRMRXapp` releases it once the handler chain has returned, whether the chain
returned normally or raised.

What this means when writing a handler:

- **Do not free `sbuf`.** It is released for you. Handlers written against xDevSM ≤ 0.1.3
that call `xapp.rmr_free(sbuf)` keep working — `rmr_free` makes the first release of
the in-flight buffer win and the framework's own a no-op — but new code should not.
Freeing the *same* buffer twice is still a double free, as it always was.
- **`rmr_rts` before returning is fine.** Returning to sender does not free the buffer,
and the release happens after your handler returns.
- **Do not retain `sbuf` past `handle()`.** It is invalid once the chain returns. The
decoded payload is already in `summary` as Python objects, which are safe to keep.
- Buffers you allocate yourself are yours to free; `rmr_free` passes those straight
through.

---

## 4. BaseXDevSMWrapper
Expand Down Expand Up @@ -213,6 +235,41 @@ ccc_xapp.subscribe_arfcn_bw_bwps(gnb=selected_gnb, ran_period_ms=1000)

> ℹ️ The indication callback signature is `handler(ind_hdr, ind_msg, meid, sub_id)`. Iterate the reported cells/structures with `ind_msg.cells()` / `ind_msg.iter_structures()`.

### CccRrmPolicyRatioControl

`CccRrmPolicyRatioControl` sends the E2SM-CCC cell-level control (CONTROL Style 2, Header Format 1, Message Format 2) for the `O-RRMPolicyRatio` structure. It sets the PRB share of a slice in one cell, so it needs no UE ID. It extends `xAppControlService` and uses `send_policies()` instead of `send()`, because the JSON encoding has no ASN.1 function definition.

* `find_ccc_function_id(json_ran_info)` returns the CCC RAN function ID from the e2mgr information of the E2 node. It accepts the OID `1.3.6.1.4.1.53148.1.1.2.4` and the OID `1.3.6.1.4.1.53148.1.6.2.4` that OCUDU announces.
* `send_policies()` checks every slice, then sends all slices in one control, so the cell applies them together. A control for two or more slices is larger than 1 KB and needs the xDevSM ricxappframe patches (patch 004).
* Each slice needs `dedicated_ratio <= min_ratio <= max_ratio`, and the `min_ratio` of the slices in one call must sum to at most 100 (TS 28.541). `dedicated_ratio` defaults to 0.
* The Old Values of each slice carry its resource type and member, so the E2 node can find the policy to change. They leave out the old ratios, which the xApp does not read.
* Known OCUDU limits: it reads `rRMPolicyDedicatedRatio` 0 as missing and fails the control (pass `dedicated_ratio=1` or more), and it applies only the min and max ratios, only to slices in `cell_cfg: slicing`.
* The callbacks of `register_control_ack_suc_callback()` and `register_control_ack_fail_callback()` receive a `CccControlAck` for a RIC Control Acknowledge or Failure. Its `outcome` is a `CccControlOutcome`, the JSON E2SM-CCC Control Outcome of the message. `outcome.structures()` lists each structure with `applied`, its `applied_values` (the currentValuesOfAttributes) or its `failure_reason`. A failure also carries `cause`, the E2AP Cause as (choice, value). A message that does not decode reaches the callback as the RMR summary. Decoding needs the xDevSM ricxappframe patches (`python -m xdevsm.ricxappframe_patches`).

```python
from xdevsm import CccRrmPolicyRatioControl
from xdevsm.sm_framework.py_oran.ccc.ccc_decoder import find_ccc_function_id
from xdevsm.sm_framework.py_oran.ccc.ccc_encoder import RrmPolicySlice

gnb, gnb_info = xapp_gen.get_selected_e2node_info(None)
ctrl = CccRrmPolicyRatioControl(xapp_gen,
logger=xapp_gen.logger,
server=xapp_gen.server,
xapp_name=xapp_gen.get_xapp_name(),
rmr_port=xapp_gen.rmr_port,
http_port=xapp_gen.http_port,
mrc=xapp_gen._mrc,
pltnamespace=xapp_gen.get_pltnamespace(),
app_namespace=xapp_gen.get_app_namespace(),
mcc="001", mnc="01",
nci=0x3954000, # 36-bit NR Cell Identity
function_id=find_ccc_function_id(gnb_info))
xapp_gen.register_handler(ctrl.handle)
ctrl.send_policies(gnb.inventory_name,
[RrmPolicySlice(sst=1, sd="000001", min_ratio=1, max_ratio=10, dedicated_ratio=1)],
resource_type="PRB_DL")
```

---
## 7. xAppReportService

Expand Down Expand Up @@ -363,7 +420,70 @@ To support a new Service Model (E2SM):

---

## 12. Other Sources
## 12. Latency instrumentation (latrec)

xDevSM can record per-stage latency data for the E2AP/E2SM-DAPP legs it owns
(indication decode, control encode, and the E2AP framing/send around it),
using **latrec**, the ring-recorder format shared with
[libe3](https://github.com/wineslab/libe3) and the rest of the E2/E3 stack.
It is off by default.

- **Enable** by setting `LATREC_DIR` to a writable directory before starting
the xApp process. Each stamping thread writes one `<role>.<tid>.latrec`
ring file there (role `xdevsm`).
- **Size** the rings with `LATREC_ENTRIES_LOG2_XDEVSM` (or the stack-wide
`LATREC_ENTRIES_LOG2`), as a power-of-two exponent between 12 and 28;
the default is 18, i.e. 256K records ≈ 8 MiB per thread.
- **Disable** by leaving `LATREC_DIR` unset. Every stamp site then costs a
module-level check and a no-op call — tens of nanoseconds, no locks and no
allocation, but not literally zero. Run `scripts/latrec_bench.py` to
measure both paths on your own hardware; it reports enabled and disabled
cost side by side.
- The writer (`xdevsm._latrec.writer`) is a self-contained, pure-Python
module with no `xdevsm`-specific dependencies, so it can be reused as-is
by other pure-Python components that need the same mechanism.
- Rings are read with libe3's own tooling (`tools/latrec_reader.py` /
`tools/latrec2csv.py`); the stage identifiers this package stamps mirror
`libe3/include/libe3/latrec.h` (see `xdevsm/_latrec/stages.py`).

## 13. Logging

The framework configures the xApp's logger from the `controls` block of the xApp
descriptor (the JSON at `CONFIG_FILE`), so verbosity and destination are set
externally rather than in code. Each key can be overridden by an environment
variable, which lets a Deployment change them without rebuilding the image.

| `controls` key | Env override | Values | Default |
| -------------- | ------------ | ------ | ------- |
| `log_level` | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
| `log_stdout` | `LOG_STDOUT` | boolean | `true` |
| `log_file` | `LOG_FILE` | path; empty means no file | unset |

```json
{
"controls": {
"log_level": "ERROR",
"log_stdout": false,
"log_file": "/tmp/xapp.log"
}
}
```

- Precedence is **environment → `controls` → default**. An unrecognised level
falls back to `INFO` rather than raising, so a typo in a descriptor cannot
stop an xApp from starting.
- `ERROR` is the quietest setting available — `mdclogpy`'s severity enum has no
`OFF`.
- Settings are applied in `xDevSMRMRXapp.__init__` before the routing table,
HTTP server and subscriptions are set up, so `log_level` governs the startup
logs too.
- With `log_stdout` false, the container writes nothing to stdout, so
`kubectl logs` is empty and `log_file` becomes the only record — point it at a
mounted volume if it needs to outlive the pod.
- The logger is shared with `ricxappframe`, so these settings cover its output
as well as this framework's.

## 14. Other Sources

A detailed step-by-step tutorial for setting up a deployment to begin working with xDevSM is available [here](https://openrangym.com/tutorials/xdevsm-tutorial).

Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.1.1
0.1.8
5 changes: 4 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,10 @@ pattern = "^(?P<version>\\d+\\.\\d+\\.\\d+)"
packages = ["src/xdevsm"]
# The prebuilt Service Model encoders are shipped as package data; declare them as
# build artifacts so they are always included regardless of VCS-ignore rules.
artifacts = ["src/xdevsm/sm_framework/lib/*.so"]
artifacts = [
"src/xdevsm/sm_framework/lib/*.so",
"src/xdevsm/ricxappframe_patches/*.patch",
]


[tool.hatch.build.targets.sdist]
Expand Down
85 changes: 85 additions & 0 deletions scripts/latrec_bench.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: Apache-2.0
"""Measure the per-stamp cost of the reference Python latrec writer
(xdevsm._latrec.writer), both enabled and disabled, at whatever rate the
caller chooses.

Both paths matter: enabled tells you what a capture costs, disabled tells you
what every xApp pays for carrying the instrumentation with tracing off, which
is how they run in production.

Run this on the actual deployment host/pod, not just a dev machine -- the
issue-#6 data-taking checklist calls for the cost "at the deployed message
rate", and container CPU limits/noisy-neighbour scheduling can move these
numbers well past what a bare dev laptop reports.

Usage:
python3 scripts/latrec_bench.py [N] # times both paths
LATREC_DIR=/some/dir python3 scripts/latrec_bench.py [N]
"""
import os
import statistics
import subprocess
import sys
import tempfile
import time

sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))


def _percentiles(samples, label):
samples.sort()
return (f"{label}: mean={statistics.mean(samples):.0f}ns "
f"p50={samples[len(samples) // 2]}ns "
f"p99={samples[int(len(samples) * 0.99)]}ns "
f"p99.9={samples[int(len(samples) * 0.999)]}ns")


def _time_stamps(n, role="bench"):
"""One full stamp site, as the decorators call it."""
from xdevsm._latrec import writer

r = writer.tls_ring(role)
samples = []
for _ in range(n):
t0 = time.perf_counter_ns()
seq = writer.seq_next()
writer.ctx_set(seq)
r.stamp(seq, 0x60, aux=128)
samples.append(time.perf_counter_ns() - t0)
writer.flush_rings()
return samples


def main() -> None:
n = int(sys.argv[1]) if len(sys.argv) > 1 else 200_000

if os.environ.get("_LATREC_BENCH_CHILD"):
# Re-exec'd with LATREC_DIR unset: the writer samples it at import,
# so the disabled path can only be timed in a fresh interpreter.
print(_percentiles(_time_stamps(n), "disabled (LATREC_DIR unset) "), flush=True)
return

own_tmp = None
if not os.environ.get("LATREC_DIR"):
own_tmp = tempfile.TemporaryDirectory()
os.environ["LATREC_DIR"] = own_tmp.name

from xdevsm._latrec import writer

print(f"N={n}", flush=True)
print(_percentiles(_time_stamps(n), "enabled (seq+ctx+stamp) "), flush=True)
print(f"raw clock_gettime cost (from ring header): "
f"{writer.measure_clock_ns()}ns", flush=True)

env = {k: v for k, v in os.environ.items() if k != "LATREC_DIR"}
env["_LATREC_BENCH_CHILD"] = "1"
subprocess.run([sys.executable, os.path.abspath(__file__), str(n)],
env=env, check=True)

if own_tmp is not None:
own_tmp.cleanup()


if __name__ == "__main__":
main()
1 change: 1 addition & 0 deletions src/xdevsm/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"BaseXDevSMWrapper": "xdevsm.decorators.base:BaseXDevSMWrapper",
"XappKpmFrame": "xdevsm.decorators.kpm.kpm_frame:XappKpmFrame",
"XappCccFrame": "xdevsm.decorators.ccc.ccc_frame:XappCccFrame",
"CccRrmPolicyRatioControl": "xdevsm.decorators.ccc.ccc_rrm_policy_control:CccRrmPolicyRatioControl",
"XappRcReportFrame": "xdevsm.decorators.rc.rc_report_frame:XappRcReportFrame",
"RadioBearerControl": "xdevsm.decorators.rc.rc_radio_bearer_control:RadioBearerControl",
"RadioResourceAllocationControl": "xdevsm.decorators.rc.rc_radio_resource_alloc_control:RadioResourceAllocationControl",
Expand Down
Empty file.
25 changes: 25 additions & 0 deletions src/xdevsm/_latrec/stages.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
"""xDevSM's mirror of the subset of libe3's shared stage catalog this
framework stamps: the E2AP and E2SM-DAPP codec boxes on the Path-B loop
(B3/B5/B6 in libe3's docs/path-b-e2-e3-loop.md).

Source of truth: libe3/include/libe3/latrec.h (branch feat/latency-tracing).
These are shared, cross-repo identifiers -- do not renumber locally. A value
that drifts from libe3's header breaks the join with every other
component's rings silently (no runtime check catches it on this side).

XAPP_PROCESS_DONE (0x62, B4's exit) is deliberately not stamped by this
package: B4 is the researcher's own xApp callback, not the framework.
"""

# Ring role for this package's threads: rings are <role>.<tid>.latrec, and
# libe3's converter already maps the "xdevsm" role onto its xapp component.
LATREC_ROLE = "xdevsm"

DECODE_E2AP_BEGIN = 0x5A
DECODE_E2AP_DONE = 0x5B
DECODE_E2SM_BEGIN = 0x60
DECODE_E2SM_DONE = 0x61
ENCODE_E2SM_BEGIN = 0x63
ENCODE_E2SM_DONE = 0x64
ENCODE_E2AP_BEGIN = 0x58
ENCODE_E2AP_DONE = 0x59
Loading
Loading