Skip to content

Sync with the internal repository (0.1.8) - #8

Merged
aferaudo merged 33 commits into
mainfrom
sync/0.1.8
Nov 16, 2026
Merged

aferaudo merged 33 commits into
mainfrom
sync/0.1.8

Conversation

@aferaudo

@aferaudo aferaudo commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Brings main up to the internal repository's main (0.1.1 → 0.1.8). That's 32 replayed commits, with authors, dates and messages unchanged, plus one commit for this repo only.

The changes to .github/workflows/ are left out, so this repository keeps its own workflows. Commits that only touched workflows were dropped. Two old commits were also adjusted, so the branch passes this repo's linear-history rule and trailer policy:

  • the --no-ff merge of Add E2SM-CCC implementation #7 is dropped, because its tree equals its branch tip, and its 5 commits stay in line;
  • #15's GitHub-built Co-authored-by: Claude Opus 5 lines are rewritten to Assisted-by: Claude:claude-opus-5.

The last commit, c475516, pins this repo's PR head test job to ubuntu-24.04. ubuntu-latest (26.04) has a glibc that refuses the bundled SM libraries, because they need an executable stack. The real fix is rebuilding those libraries.

Merge as a fast-forward only, from the command line. The merge buttons rewrite the commits (merge commit, squash, or GitHub's rebase):

git push git@github.com:wineslab/xDevSM.git c475516:main

Merging triggers tag-and-release: tag 0.1.8 and a PyPI release.

🤖 Generated with Claude Code

Thecave3 and others added 30 commits August 28, 2026 16:33
…seq id (#12)

The dApp stamps a producer timestamp on its spectrum report and the gNB relays
the payload without decoding it, so the value reaches the xApp unchanged. Nothing
on the Python side could read it: spectrum_sm_report_t had no such field and
DAppE3IndPayloadWrapper had no getter, so the consumer in
wineslab/spectranet-xapps#36 probes for one and always misses.

Adds the ctypes field and get_timestamp_ns(), and rebuilds libdapp_sm.so from
FlexRIC's develop-dapp, which now carries both #26's E2SM-DAPP envelope
timestamp and #36's origin-seq correlation id (wineslab/spear-flexric#26,
wineslab/spear-flexric#36).

CLOCK_REALTIME, not monotonic: the dApp and the xApp are on different hosts. That
also means a difference against the receiver's clock carries their NTP skew -- a
hop estimate, not an exact transit. It must never be differenced against the
monotonic stamps the RAN puts on its own indications
(Spectrum-SensingIndication, L1KPMIndication), which cannot leave the host.

The field is OPTIONAL on the wire and 0 is the "no producer reference" value, so
the getter returns None for it, and for a payload that is absent or is not a
spectrum report. That matches what FlexRIC#26 now does -- it was mandatory there
at first, with an encoder that refused a zero stamp, which would have rejected a
PDU this side is happy to accept. Both ends now follow the convention libe3
settled on for the E3AP envelope timestamp (wineslab/libe3#58).

Note the OPTIONAL change does not move this struct: it alters the asn1c-generated
type, not the IR that spectrum_sm_report_t mirrors, which stays
{long, uint16_t*, int64_t}.

While rebuilding the .so, found and fixed three E2SM-DAPP envelope ctypes
mirrors that had drifted from the C side:

- DAppIndicationHdr.py's e2sm_dapp_ind_hdr_frmt_1_t/_frmt_2_t were missing
  timestamp_ns and origin_seq. dapp_dec_ind_hdr_asn returns this struct by
  value, and it's actively used by decorators/dApp/report/dapp_report.py, so
  a short mirror does not just miss trailing fields -- ctypes needs the exact
  size to interpret a by-value return at all, and a wrong one misreads the
  whole thing.
- DAppControlOut.py's e2sm_dapp_ctrl_out_frmt_1_t was `_fields_ = []`, since
  the format used to be a genuinely empty SEQUENCE. Also a by-value return
  (dapp_dec_ctrl_out_asn); no live call site right now, but wrong regardless.
- DAppControlHdr.py's e2sm_dapp_ctrl_hdr_frmt_1_t was missing both fields
  too; its wrapper class is commented out (dead code), so this one was
  latent, not active.

Verified past the field-list level: built a tiny C program against the same
libdapp_sm.so to encode a known-value struct, decoded the exact same bytes
through each fixed ctypes mirror, and confirmed every field -- including
timestamp_ns and origin_seq -- reads back exactly what was encoded (done for
the indication-header and control-outcome paths, the two with by-value
returns).

The rebuilt .so is a drop-in: same SONAME, same NEEDED (libc only), and the same
RWE GNU_STACK the deployment images depend on -- they mark the Python
interpreter's stack executable precisely so these libraries load.

A ctypes mirror that drifts from the .so fails silently -- it reads by offset and
validates nothing -- so the new test pins the offsets the C side fixes rather than
just checking the field exists.

No VERSION bump here: #7 (stacked on top of this branch) carries the version
change instead.

Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>

Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
A pure-Python, byte-compatible mirror of libe3's latrec mmap-ring
format (magic/version/header/record layout, atomic rename-into-place,
release-ordered t_ns write), plus a per-thread ctx_set/ctx_get seq
carrier mirroring libe3/flexric's own latrec_ctx() mechanism. Gated by
LATREC_DIR (unset = every stamp a no-op).

This module is intentionally catalog-agnostic (stage ids are passed
in by the caller) and free of any xdevsm-specific imports, so it can
be adopted as-is by other pure-Python components in the stack that
need the same mechanism later.

xdevsm/_latrec/stages.py mirrors the subset of libe3's shared stage
catalog (include/libe3/latrec.h) this package will stamp: the E2AP and
E2SM-DAPP codec boxes on the Path-B loop (B3/B5/B6).

Assisted-by: Claude:claude-sonnet-5
Drop the mdclogpy-based [LAT] markers added in #4 (utils/lat_profile.py
and its 5 call sites): a container log pipeline is neither cheap nor
reliably ordered against the other repositories' latrec rings, and the
point of this change is exactly one recording mechanism, not two.

Stamp the shared libe3 catalog identifiers this framework owns instead,
at the same placements #4 already established (carried over, since
that part of #4 was sound):

- DECODE_E2AP_BEGIN at the top of _dispatch_event -- the earliest point
  under this framework's control on the inbound path. The actual RMR
  receive thread is ricxappframe's own (RmrLoop, feeding a queue
  _dispatch_event's caller drains); that hop is folded into the wire
  segment, the same way an opaque near-RT RIC's own internal relay is.
- DECODE_E2AP_DONE in xAppReportService._handle_indication, right after
  the E2AP envelope decode.
- DECODE_E2SM_BEGIN/DONE bracketing DAppReport.decode_message's E2SM-DAPP
  decode (B3), DONE landing at the handoff to the xApp's own callback
  (B4, out of scope here) rather than mid-decode.
- ENCODE_E2SM_BEGIN/DONE bracketing the SM encode in
  xAppControlService.send (B5).
- ENCODE_E2AP_BEGIN/DONE bracketing send_control_request_rmr (B6);
  DONE now fires once the RMR send returns rather than before it, to
  match the shared catalog's own definition (and flexric's PR #28).

A seq generated at each leg's first stamp is threaded to the rest of
that leg via the new ctx_set/ctx_get (thread-local, single synchronous
call chain per message/control -- no cross-thread handoff exists
within this framework's own code on either leg).

README documents the new LATREC_DIR-gated capability.

Assisted-by: Claude:claude-sonnet-5
_entries_log2() was handed the full ring name, so the sizing knob it
advertises resolved to LATREC_ENTRIES_LOG2_XDEVSM_<tid> -- a key with a
thread id in it, which nothing can set. libe3 keeps the two apart:
latrec_tls_open_as(role) names a ring <role>.<tid> but sizes it from
LATREC_ENTRIES_LOG2_<ROLE> (docs/latrec.md, which also says to prefer the
per-role override). Left as-is, every stamping thread mmapped the 8 MiB
default with no way to turn it down. Take role separately and size from
it: LATREC_ENTRIES_LOG2_XDEVSM=12 now yields 4096 entries, not 262144.

Add tls_ring(role) for the per-thread ring the stamp sites want. It
caches in a threading.local() and short-circuits on a module-level
LATREC_DIR sample, so a stamp no longer formats a name and takes the
process-wide ring lock every call. Disabled, same harness: 201ns -> 57ns
per site, 806ns -> 226ns per inbound message, with no lock and no
allocation left on that path. LatRec() and ring() still read os.environ
per call, so they stay configurable at runtime.

Add flush_rings() and start_heartbeat(). rec_count is what tells a reader
a wrapped ring from a partly filled one, and the t1 clock pair is what
makes mono->real a two-point fit rather than a constant offset; libe3's
header says to refresh both periodically. Only atexit did, which a
SIGKILL skips, so a killed pod left every ring reading rec_count == 0.

measure_clock_ns() becomes public: the bench script wants it and had to
reach through the underscore. The bench now times the disabled path too,
in a re-exec'd child, since LATREC_DIR is sampled at import.

Assisted-by: Claude:claude-opus-5
Swap ring(f"xdevsm.{tid}") for tls_ring(LATREC_ROLE) at all four sites,
so the role is named once in stages.py rather than rebuilt per stamp, and
drop the `import threading` each site only needed to build that name.

ENCODE_E2AP_BEGIN carried no aux, where the catalog says "aux = payload
bytes" -- the value was already in scope one line away. Without it the
e2ap_out leg's payload column is blank for this component alone.

send_control_request_rmr() recovered its seq from ctx_get() alone, which
holds only because send() is its one caller today. It is public on
xAppControlService and its RC subclasses, and on the long-lived RMR
dispatch thread a direct call would adopt whatever seq that thread last
handled -- filing B6 records under an unrelated row rather than showing
an obvious 0. Take an explicit seq, falling back to a fresh one.

Flush rings from terminate(), the shutdown path consumers already wire to
SIGTERM, so the write count does not depend on interpreter teardown
ordering; start the heartbeat for the SIGKILL case.

Tests: pin the eight stage ids against libe3's catalog, since nothing at
runtime catches a value that drifts from it. Cover the role-vs-name
sizing, tls_ring's per-thread identity and its disabled fast path, and
flush_rings() publishing rec_count without a close(). Replace the
LATREC_DIR-unset test's assertion on an unrelated tmp_path, which held
whether or not the code worked.

README: the disabled path is cheap, not free -- say so, and document
LATREC_ENTRIES_LOG2_XDEVSM now that it works.

Assisted-by: Claude:claude-opus-5
Carries the version bump that #12 deliberately skipped (that PR's own
content had no public API change; #12 was left at 0.1.1 on purpose, with
this PR named as the one to carry it forward instead).

Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
…_from_py_byte_string (#15)

* changed dapp library

* new libdap

* Fix binary corruption in get_c_byte_array_from_py_byte_string

The helper round-tripped the E2AP indication header and message through
decode('unicode_escape').encode('latin-1') before copying them into the
ctypes buffer handed to the C service-model decoders.

unicode_escape treats an 0x5C octet as the start of an escape sequence, so
any APER payload containing 0x5C came out shortened and misaligned:
5c 6e -> 0a, 5c 74 -> 09, 5c 78 41 42 -> ab, 5c 75 30 30 34 31 -> 41.
aper_decode then returned != RC_OK and the decoder aborted the xApp on
assert(ret.code == RC_OK) (dapp_sm/dec/dapp_dec_asn.c:285).

ricxappframe already returns real bytes for indication_header and
indication_message, so the conversion was never needed. Copy the payload
verbatim instead, and narrow the bare except so genuine failures are no
longer swallowed into a silent None.

Measured against APER-encoded E2SM-DAPP indication messages, the old
helper corrupted 2.5% of 32 B payloads, 15.8% of 512 B and 41.2% of
1500 B; the new one 0% at every size.

Assisted-by: Claude:claude-opus-5

---------

Assisted-by: Claude:claude-opus-5
…rame (#16)

Frames are stacked as a decorator chain, and every frame's handle() calls
_handle_indication for any RIC_INDICATION before delegating downstream. That
shared handler ran a full IndicationMsg().decode() plus two ctypes buffer copies,
and only then did decode_message compare the function id and discard the message
if it belonged to another frame.

So a chain of RC, CCC, dApp and KPM decoded every indication four times and threw
away three of them -- all on the single thread ricxappframe dispatches
indications from, which is the throughput ceiling for the whole xApp. Measured
against the four-frame chain the data ingestor builds: 5 indications cost 20
decodes before, 5 after.

_decode_e2ap_once caches the decode against the identity of the payload object.
The chain runs synchronously on one thread and hands the same summary dict to
every frame, so summary[RMR_MS_PAYLOAD] is the same object at each hop. The cache
lives in a threading.local rather than in summary itself, which keeps it out of
the dicts callers log and out of summary's lifetime. _handle_indication now
returns on a function id mismatch before any E2SM work, so a frame the indication
is not addressed to does nothing but a dict lookup and an int compare.

Note for latency traces: the DECODE_E2AP_DONE stamp used to fire four times per
sequence number. It now fires once, which is what the stage was meant to measure.

Also demotes the logging that ran per RMR message on that same thread -- about
ten lines per indication, through mdclogpy's unbuffered print(). The worst was
DAppReport.handle formatting the entire RMR summary, payload included, at INFO
for every message. Call sites that format a large object now guard on
utility.debug_enabled(), because mdclogpy filters by level inside log(), after
the caller has already paid for building the string.
* Configure logging from the xApp descriptor

The framework forced Level.DEBUG in xDevSMRMRXapp.__init__, so controls.log_level
could not reach the noisiest part of a run: the xApps lower the level only after
construction, leaving the routing-table write, HTTP server start and subscription
setup logging at DEBUG whatever the descriptor said. One xApp (basic_dapp_sync)
never lowers it at all and so ran at DEBUG for its whole life.

Read log_level, log_stdout and log_file from the descriptor's controls block
instead, each overridable by an env var so a Deployment can change them without
rebuilding an image, and apply them before anything else logs.

log_stdout exists because mdclogpy offers no way to redirect its output --
_output_log is a bare print(). Consumers worked around that by subclassing it to
tee into a file, which put the same class in three xApps and still left stdout
unconditional. Rebinding that one method per instance covers both sinks. The
logger object belongs to ricxappframe and is shared with it, so its class is
left alone; that also means these settings govern ricxappframe's own output.

Resolution is kept in xdevsm/utils/log_config.py, free of mdclogpy: that package
binds inotify and cannot be imported off Linux, so splitting the decision from
its application is what makes the behaviour testable anywhere. Same reasoning as
xdevsm/handlers/config.py staying RMR-free.

Defaults (INFO, stdout on, no file) preserve current effective behaviour for a
descriptor that sets none of the keys.

Assisted-by: Claude:claude-opus-5

* log_config: own the file handle in a LogSink, add a buffering knob

_install_sink opened the log file, captured it in a closure bound to
logger._output_log, and parked the raw handle on the logger as
_xdevsm_log_fp so close_log_file could find it again. The file has a
lifecycle -- something has to flush it on a schedule and close it at
shutdown -- and a free function reaching into an attribute it stashed
earlier is the wrong shape for that.

LogSink owns the handle instead. It is still assigned over the logger's
_output_log rather than subclassing, for the reason the old comment gave:
the logger belongs to ricxappframe and is shared with it, so leaving its
class alone is the least surprising thing to do. But flush() and close()
are now methods on the thing that opened the file.

Adds log_buffering (env LOG_BUFFERING, controls log_buffering), passed
through to open(). The default stays 1, line-buffered, so the file is
readable while the xApp runs. An xApp that logs from a hot path can set a
block size and call flush_log_file() from whatever periodic task it
already runs: the data ingestor logs from the single RMR dispatch thread,
where a write syscall per line was the difference between keeping up with
the indication rate and falling ~1s further behind every second.

resolve_log_buffering is deliberately separate from resolve_log_settings
rather than a fourth element of its tuple. That function answers "where
does output go", which every xApp cares about; this is a performance knob
only a hot-path xApp touches, and keeping it apart leaves the existing
signature and its tests untouched.

42 tests pass: the 31 that existed are unchanged, plus coverage for the
knob's precedence and fallback, deferred writes under block buffering,
flush via the logger, and close being idempotent and safe to flush after.

Assisted-by: Claude:claude-opus-5

* Bump to version 0.1.5

Assisted-by: Claude:claude-opus-5
… control-request send buffer (#20)

* Give the dispatcher ownership of the inbound RMR buffer

ricxappframe's receive loop allocates a fresh 4 KiB C buffer per message
(rmr.helpers.rmr_rcvall_msgs_raw) and transfers ownership to the caller;
neither RmrLoop nor RMRXapp.run frees it. xDevSM did free it, but at the
bottom of the decorator chain, in xDevSMRMRXapp.handle -- which is only
reached if every frame delegates and nothing raises. There is no
try/finally, so any exception in the chain leaked the buffer, as does any
handler that terminates the chain itself (NullDecorator, or an
out-of-tree handler that returns early).

Move the release into _dispatch_event's finally, the one place every
dispatched message passes through and where the chain is known to be
done with sbuf. Verified first that nothing retains it: every frame
reads only `summary`, which ricxappframe materialises as Python objects
in the receive thread before the queue put, and passes sbuf down by
reference.

The release has to be idempotent. Freeing was handle()'s job, and
out-of-tree xApps copied the pattern (spectranet-xapps' A1 policy
handler frees after an rmr_rts), so an unconditional free here would
turn the leak into a double free of a C allocation -- rmr_free_msg only
null-checks the Python pointer object, so that aborts the process rather
than raising. rmr_free now consumes a thread-local one-shot token for
the buffer being dispatched: first free wins, the finally then no-ops.

Two details that are load-bearing:

  - the token is cleared *before* the free, not after. rmr_free_msg
    returns the address to the allocator, and the next rmr_alloc_msg on
    the thread can be handed it straight back; a token still holding
    that address would match the new buffer's free and swallow it,
    trading one leak for another.

  - it is thread-local, not an instance attribute. rmr_free is reached
    from threads that never dispatch -- _BaseXapp.rmr_send frees its own
    send buffer through it, from HTTP handlers, subscription callbacks
    and user timer threads -- and those must neither observe nor clear
    the dispatch thread's token. This also makes compare-and-clear
    atomic without a lock.

Cost matters here, this being the per-indication path: identity-first
comparison keeps ctypes.cast (~1.3us) off it entirely, since the chain
passes the same pointer object all the way down. Measured 484ns per
dispatch for the whole arm/release, against 829ns for the latrec
preamble already two lines above it. An address-compare-plus-lock
variant measured 4391ns.

The tests deliberately do not guard on requires_ricxappframe: importing
ricxappframe.xapp_frame dlopens librmr_si.so, which neither CI nor a
plain pip install provides, so a guarded module never runs anywhere and
a skipped double-free test proves nothing. Nothing under test calls into
RMR, so the three imported ricxappframe modules are stubbed when the
real package is absent, through monkeypatch so nothing else sees them.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Free the control-request send buffer, and retry the send

send_control_request_rmr allocated an RMR buffer and never freed it. RMR
does not take ownership on send -- ricxappframe's own _BaseXapp.rmr_send
frees on both the success and the failure branch -- so every control
request leaked 4 KiB for the lifetime of the xApp. Unlike the inbound
path, nothing anywhere freed this one.

Free it in a finally, keeping the `sbuf = rmr_send_msg(...)` rebind:
that is the pointer RMR hands back for the next send (the same mbuf
re-armed on success, the unsent one on failure) and so the one that has
to be freed. The alloc stays outside the try, since it raises
BadBufferAllocation rather than returning a buffer to release.

While here: retry on a non-zero state as _BaseXapp.rmr_send does, and
log if every attempt fails. A single send attempt dropped the control
request silently on RMR_ERR_RETRY, which on this path means a PRB mask
or RC control that the gNB never hears about and nothing reports. The
retry count is a keyword with the same default as ricxappframe's, so
existing callers are unaffected.

One latrec note: on a failing send ENCODE_E2AP_DONE now spans the
retries rather than a single attempt. That still matches the shared
catalog's definition -- the stamp fires once the RMR send returns -- but
the duration is no longer comparable across a retrying and a
non-retrying send.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Document who owns the inbound RMR buffer

The contract was never written down, which is how an xApp ended up
freeing the buffer itself: the only release used to be inside
xDevSMRMRXapp.handle, so copying that was the reasonable reading. Say
explicitly that xDevSM releases it after the chain returns, that
handlers must not, that pre-0.1.4 handlers which do keep working, and
that rmr_rts before returning is safe.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

* Make @aferaudo the sole code owner

Every PR was auto-requesting review from five people regardless of what
it touched, which spreads the request thin rather than routing it. Route
it to the maintainer instead. Credit for past work stays in CONTRIBUTORS,
which is what records it.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Mirror FlexRIC's timestamp_ns field in spectrum_sm_control_t and stamp outgoing xApp controls. Add ABI layout and empty-control coverage.
… logs off the hot path (#29)

* fix(report): detect a DELETE that submgr rejected

NewSubscriber.Unsubscribe returns urllib3's (data, reason, status); it
does not raise on a 4xx. unsubscribe_gnb discarded that return value
inside a try/except, so only a connection-level failure was ever noticed
and a rejected DELETE was indistinguishable from a successful one.

A subscription submgr refused to delete stays live while the xApp has
already dropped it from subscription_id, so E2Term keeps routing
indications to a consumer that is gone, and nothing on either side will
reconcile it. In the cluster this showed up as HTTP 400 on delete with
the xApp logging nothing at all.

Check the status: 2xx and 404 count as removed (404 means submgr no
longer holds it, which is what the caller wanted), anything else is
logged with the gNB, the subscription id and the reason, stating that
the subscription may still be live.

Also stop reporting a late response for an already-detached gNB as an
error. unsubscribe_gnb detaches local state before the DELETE so a stale
response cannot alias a reconnected node with the same inventory name;
remove_sub_id finding nothing is that design working, not a fault, and
it fired on every reconcile cycle.

Assisted-by: Claude:claude-opus-5

* fix(dapp): move the per-indication decode logs off the INFO path

Three INFO lines ran for every indication on the dispatch thread, so
they survived the log-level fix and kept building strings the level
would otherwise discard.

The header block was also inverted: it printed "format 1" and read
union.frmt_1 when the format was NOT format 1, so a format-2 header was
reported with fields read from the wrong union member, and the format-2
branch was unreachable because the preceding condition had already
matched every non-format-1 case.

Correct the comparison and drop both to debug behind
utility.debug_enabled, matching the guard already used in handle().

Assisted-by: Claude:claude-opus-5
Marks the v2 tag: the unsubscribe DELETE-status detection and the
per-indication decode logs moved off the INFO path (#29). Without a bump
`pip show xdevsm` reports 0.1.5 for both, so an image built from v2
cannot be told apart from one built before it.

Assisted-by: Claude:claude-opus-5
generate_control_req_frmt_1 left the correlation id and timestamp at zero on
every outbound control. The RAN received controls it could not tie to any
procedure, and the E2SM-DAPP fields added for exactly that purpose were dead
on the wire. Both are now set, threaded from xAppControlService.send() so a
caller passes the id of the report it is reacting to. The E2SM-RC decorators
take the argument and ignore it: RC has no such field, and the base class
passes it to every subclass.

Renamed origin_seq to sequence_id throughout, matching the E2SM-DAPP grammar
and libe3's E3AP field, and added get_sequence_id() beside the existing
get_timestamp_ns(). The shipped libdapp_sm.so is rebuilt from the FlexRIC
branch carrying both the rename and the control outcome's new
e3_control_outcome member.

Also seed 12041 and 12042 into the generated routing table. write_routing_table
overwrites the checked-in uta_rtg.rt, which does list them, so an xApp setting
control_ack_request=1 could never receive the answer -- and the failure was
silent, since the send still succeeded.

The spectrum_sm_control_t mirror is left as #25 landed it; this only adds the
note on which clock its timestamp is.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
An xApp asking for control_ack_request=1 received the acknowledge as raw RMR
bytes and could do nothing with it: ricxappframe ships no
control-acknowledge decoder, and the E2SM outcome is an octet string nested
in an APER PDU with nothing safe to hand-parse. The handler was given a
summary dict and a TODO.

FlexRIC now exports the E2AP half as libe2ap_ctrl_ack_dec.so, which this
loads beside libdapp_sm.so; the E2SM half goes through the
DAppControlOutWrapper that was already here and never called. The callback
now receives a DAppControlAck naming the procedure the acknowledge answers
and carrying the Service Model's apply outcome, falling back to the raw
summary for a PDU that does not decode, so an existing handler keeps working.

The two libraries are separate because each links its own asn1c-generated
grammar and no translation unit can include two of them: they ship headers of
the same names declaring differently suffixed types. Loaded side by side as
distinct objects they coexist.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
The gNB tunnels a Spectrum-ApplyOutcomeData inside the E2SM-DAPP control
outcome, saying when it wrote the PRB mask into the MAC and when the first
scheduler tick put it on the air. Decoding belongs to FlexRIC's copy of the
spectrum grammar, which now exports spectrum_sm_dec_apply_outcome(); this is
the ctypes wrapper over it.

Every field is optional and absent reads as None: a rejected control never
installed, and one that installed but never reached a tick has no on-air
instant. Both are real answers rather than decode failures.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
Review feedback: the correlation id is dApp-control semantics, not
something every Service Model's control shares, so it does not belong in
the generic xAppControlService signature.

DAppPrbMaskControl gets a set_sequence_id() setter alongside the existing
set_dapp_id()/set_payload(), and reads self.sequence_id when building the
request. xAppControlService.send()/generate_control_request() go back to
their previous signatures, and the three RC decorators no longer carry a
kwarg they ignored.

Also trims the comments flagged in library_wrapper.py and utility.py.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Andrea Lacava <a.lacava@northeastern.edu>
ricxappframe is a runtime dependency, not a vendored one, so anything xDevSM
needs from it that upstream does not provide has to be applied to the installed
copy at image-build time. Until now that was a sed in one xApp's Dockerfile,
which made the dependency invisible from this side: an image built from any
other Dockerfile silently lost it, and the sed would have matched nothing --
quietly, leaving the leak in place -- had upstream reformatted the line.

Patches now ship inside the package, so they version with the code that depends
on them and every image builder gets the same set. Applied with

    python -m xdevsm.ricxappframe_patches

which resolves site-packages itself, refuses to run against a ricxappframe
other than the pinned 3.2.2, skips patches already applied so an incremental
build is harmless, and fails the build on a patch that does not apply rather
than producing an image whose behaviour differs from what the framework
expects.

001 is the former sed: upstream ships _asn1_free_indicationMsg commented out,
leaking the decoded PDU on every received indication.

002 adds ControlAckMsg / control_ack_msg_t, wrapping two symbols
libriclibe2ap.so already exports but upstream never binds:
e2ap_decode_ric_control_acknowledge_message and
e2ap_free_decoded_ric_control_ack. Upstream already wraps the control *request*
encoder, so this is the missing other half -- without it an xApp that sets
control_ack_request=1 cannot read the answer.

Assisted-by: Claude:claude-opus-5
…P library

The acknowledge needs two layers peeled: the E2AP envelope, then the Service
Model outcome inside it. This carried libe2ap_ctrl_ack_dec.so for the first,
on the grounds that ricxappframe ships no control-acknowledge decoder. That is
true of ricxappframe, but not of the stack: libriclibe2ap.so -- the object
ricxappframe already loads in asn1clib.py -- exports
e2ap_decode_ric_control_acknowledge_message and
e2ap_free_decoded_ric_control_ack, and upstream already wraps the control
request encoder from the same library. Only the wrapper was missing, and it now
ships as a patch (see xdevsm/ricxappframe_patches).

So the library is dropped. Its justification -- that FlexRIC's E2AP grammar and
the Service Model grammars cannot share a translation unit -- holds for
FlexRIC's copy but does not arise here, because this is the same grammar
ricxappframe already uses for indications. Loading a second one would make two
sources of truth for one wire format, and sm_framework/lib is for Service
Models: an E2AP decoder sitting beside them invites exactly that confusion.

decode_control_ack now takes ric_requestor_id and ran_function_id from
ControlAckMsg and hands control_outcome to DAppControlOutWrapper unchanged, so
the E2SM half and everything downstream of it are untouched. An install without
the patch applied degrades to None, which xAppControlService already treats as
"no decode" and answers with the raw RMR summary.

Assisted-by: Claude:claude-opus-5
The decoded acknowledge names the procedure it answers but not the node that
sent it, so a caller keeping per-procedure state cannot key it safely: a
procedure id is assigned by a dApp from its own counter, so two gNBs both
counting from 1 occupy the same id space and collide.

E2AP cannot supply the node. RIC CONTROL ACKNOWLEDGE has no E2 Node ID IE --
E2 is point-to-point per node, so the node is implicit in the SCTP
association and there is nothing in the PDU to decode. The identity lives one
layer down, in the RMR meid the E2 termination stamps on the message:
send_control_request_rmr already sets it on the way out, and report.py
already reads summary['meid'] on the indication path.

So a handler needs both halves, and each arrives from a different place --
the procedure id from the decoded PDU, the gNB from the RMR envelope.
Decoding alone dropped the envelope, which left a caller able to say WHICH
procedure was acknowledged but not BY WHOM. Attached as an attribute rather
than by changing the callback signature, so handlers written against the
decoded object keep working unchanged, and bytes are decoded to str because
that is what the indication path already hands callers.

The FAILURE path now decodes too. It carries the same header, so the
procedure it answers is knowable, and a caller holding per-procedure state
has to release it on a rejection exactly as on a success -- otherwise a
rejected control leaks its entry until a timeout sweeps it.
c5614a7 added _with_meid to attach the sending gNB's id to a decoded
RIC Control Acknowledge, but DAppControlAck declares __slots__ and the
commit did not add 'meid' to it, so the assignment raised AttributeError
on every acknowledge.

That was guarded, except the guard raised too: self.logger is mdclogpy's
Logger, whose debug() takes a single argument, so the %-style call in the
except branch raised TypeError. That escaped _with_meid, propagated out
of the RMR receive thread and killed it -- meaning the FIRST acknowledge
an xApp ever received left it permanently unable to receive another. The
registered callback never ran, and every control the xApp sent from then
on timed out with no diagnostic beyond a traceback on stdout.

Add the 'meid' slot (initialised to None so a handler can read it whether
or not _with_meid has run) and pre-format the debug message.

Measured on the SPEAR testbed against a gNB returning deferred
acknowledges: 0 of 1181 controls acknowledged before, 488 of 598 after.
Removed unnecessary comments explaining the need for attaching the E2 node's ID to the decoded acknowledge.
Removed comments regarding the sending gNB and E2 Node ID handling.
Assisted-by: Claude:claude-opus-5
The bundled KPM v3 decoder wrote to stdout on every indication. Two of
the four call sites were xer_fprint(), which serialises an entire ASN.1
structure to XML: one for the whole E2SM-KPM IndicationMessage in
kpm_dec_ind_msg_asn, one for the UE measurement report list in the
Format-3 decoder, plus a printf per Format-1 decode and another per UE
in the Format-3 loop.

In the data ingestor that is unconditional synchronous I/O on the single
RMR dispatch thread, and when stdout is a pty it is paid at terminal
speed. It flooded the operator's terminal to the point of hiding the
xApp's own logging, with no way to turn it off short of a rebuild.

The top-level xer_fprint also ran before the rval.code check, so a
failed decode still serialised a partially built PDU.

This rebuild also carries a leak fix in the same function: the decode
failure path called free(pdu) alone, which drops only the top-level
struct and abandons every nested member asn_decode had already
allocated. It now matches the success path with
ASN_STRUCT_FREE_CONTENTS_ONLY first. That path is taken once per
malformed or truncated indication, which is what a lossy or delayed E2
link produces.

Built from aferaudo/flexric-sm main (a7d8eb0d) with
  cmake -DCMAKE_BUILD_TYPE=Release -DKPM_VERSION=KPM_V3_00 -DSM_ENCODING_KPM=ASN
on ubuntu:24.04 / gcc 13.3, matching the KPM v03.00 service model the
previous binary was built from.

Assisted-by: Claude:claude-opus-5
xDevSM sent every control with ricInstanceID 0, so E2Term routed the
acks through rtmgr's shared mse|12041|-1 route, which lands on whichever
xApp rtmgr writes last on each push. Each control service now registers
a free id with rtmgr (the xapp-subscription-handle call submgr uses),
keeps it registered, and sends it as ricInstanceID.

Assisted-by: Claude:claude-opus-5-5
* control: free the SM-encoded control header and message

The E2SM-DAPP and E2SM-RC encoders return malloc'd buffers that the
caller owns: dapp_enc_ctrl_hdr_asn, dapp_enc_ctrl_msg_asn and
rc_enc_ctrl_msg_asn allocate 16 KiB each, rc_enc_ctrl_hdr_asn an
exact-size asn_encode_to_new_buffer result. send() copied them with
to_bytes() and dropped them, so every control request leaked both. On
the SpectraNet decision engine that was ~32 KiB per dApp PRB-mask
control, ~5 MiB/min, on course for its 2 GiB limit within hours.

Free both buffers through ByteArray.free once their bytes are copied,
in a finally so a failed copy does not leak them either. dApp and RC
controls share this path.

Assisted-by: Claude:claude-opus-5-5

* removed comments
aferaudo and others added 2 commits October 15, 2026 22:45
The 36-bit NR Cell Identity sits at the top of the NR CGI's last 5 octets
(TS 38.413 9.3.1.7), which is how the gNB decodes it (wineslab/spear-openairinterface5g#116).
ho_handler packed it at the bottom, so cell 12345 reaches the gNB as 771.
* ccc: add the cell-level O-RRMPolicyRatio control

xDevSM had E2SM-CCC only for REPORT. CccRrmPolicyRatioControl sends the
CONTROL Style 2 message (Header Format 1, Message Format 2) that sets
the min, max, and dedicated PRB ratios of a slice in one cell. It needs
no UE ID, unlike the RC slice-level PRB quota, which OCUDU accepts only
with the gnb_du_ue_id of a connected UE on that slice.

- find_ccc_function_id() takes the RAN function ID from the e2mgr info,
  because gNBs assign it at E2 Setup. It accepts the xDevSM CCC OID and
  the OID that OCUDU announces (1.3.6.1.4.1.53148.1.6.2.4).
- send_policies() checks every slice before it sends the first control,
  so an invalid slice cannot leave a policy half applied.
- One slice per message, because OCUDU checks only the first structure.
- The dedicated ratio is at least 1, because OCUDU reads 0 as a missing
  field and fails the control.

Tested on OCUDU release_26_10 with RU05 and three UEs on three slices:
the gNB acknowledged every control, and a 10% max ratio on one slice cut
that UE from 74 to 16 Mbit/s downlink.

Assisted-by: Claude:claude-opus-5-5

* ccc: decode the control outcome of an acknowledge as E2SM-CCC JSON

CccRrmPolicyRatioControl inherited the acknowledge handling of
xAppControlService. With a registered callback, that handling gives
the outcome octets of each RIC Control Acknowledge to
decode_control_ack(), which runs the native E2SM-DAPP decoder
dapp_dec_ctrl_out_asn on them. OCUDU sends a JSON E2SM-CCC Control
Outcome, so the ASN.1 decoder got JSON.

- xAppControlService._decode_ack() is now the decode step of both
  acknowledge handlers. It still calls decode_control_ack(), so the
  E2SM-DAPP services do not change. The hook is the one of the
  develop-ccc-ca branch.
- CccRrmPolicyRatioControl overrides it with decode_ccc_control_ack(),
  which returns a CccControlAck with a CccControlOutcome. The names and
  the shape come from develop-ccc-ca.
- CccControlOutcome reads the fields that OCUDU sends: Format 2
  listOfCellsForControlOutcome, with or without the
  controlOutcomeFormat wrapper, accepted structures with their
  currentValuesOfAttributes, and failed structures with their cause.
- nr_cell_id_of(), with the name and signature of develop-ccc-ca.

The tests use the outcome that convert_to_e2sm_response() and
pack_ric_control_response() of OCUDU build (feature/e2sm_ccc_report).

Assisted-by: Claude:claude-opus-5-5

* ccc: follow E2SM-CCC v08 in the RRMPolicyRatio control, decode failures

Review of the O-RRMPolicyRatio control against O-RAN.WG3.TS.E2SM-CCC-R005-v08.00
and TS 28.541:

- Old Values carry the resource type and member of each slice: the E2
  node finds the instance to change from them (§8.1.5), and the member
  list has at least one entry (§9.3.17). The old ratios are still left
  out, because the xApp does not read them.
- dedicated_ratio defaults to 0 and is sent as given; the 0 -> 1 clamp
  is gone. Each slice needs dedicated <= min <= max, and the min ratios
  of one call sum to at most 100 (TS 28.541).
- sst must be 0..255, mcc 3 digits and mnc 2 or 3 digits, as in the
  E2SM-CCC JSON schema.
- send_policies() sends all slices in one control, so the cell applies
  them together and a failing slice cannot leave half a policy behind.
- xAppControlService._decode_ack() decodes nothing by default and each
  Service Model overrides it. DAppPrbMaskControl keeps the E2SM-DAPP
  decoder; the RC controls give their callbacks the RMR summary again
  instead of a DAppControlAck.
- ricxappframe patch 003 adds ControlFailureMsg, the RICControlFailure
  counterpart of the ControlAckMsg of patch 002. decode_ccc_control_ack()
  reads both, so a failed control reaches the fail callback as a
  CccControlAck with its outcome and its E2AP cause. It needs riclibe2ap
  with the fixed failure decoder (aferaudo/libe2ap_package a10875d on dev).
- The README keeps the OCUDU limits in one bullet.

Assisted-by: Claude:claude-opus-5-5

* ricxappframe: size the control request buffer to the message (patch 004)

ControlRequestMsg.encode() encoded into a fixed 1024-byte buffer, so an E2SM-CCC control for two or more slices failed with 'Could not create payload.', and it returned the whole buffer, so every control went out as 1024 bytes. The buffer now fits the message and encode() returns only the PDU, with its length in bytes (riclibe2ap returns bits). Reported on PR 49.

Assisted-by: Claude:claude-opus-5-5

---------

Co-authored-by: Feraudo <aferaudo34@gmail.com>
Co-authored-by: Angelo Feraudo <33128793+aferaudo@users.noreply.github.com>
ubuntu-latest moved to 26.04 (glibc 2.43), whose dlopen refuses the bundled SM libraries: they need an executable stack because FlexRIC's defer() is a GCC nested function. Pinned until the libraries are rebuilt without it.

Assisted-by: Claude:claude-opus-5-5
@aferaudo
aferaudo requested a review from Noemi2001 November 16, 2026 20:25
@github-actions

Copy link
Copy Markdown

Ready to merge (fast-forward only)

This PR is approved. A maintainer can land the reviewed commits with:

git fetch origin
git checkout main && git merge --ff-only c47551670761153a7ee43644efa55d24e8010b56 && git push origin main

Head: c47551670761153a7ee43644efa55d24e8010b56 (branch sync/0.1.8). If --ff-only fails as non-fast-forward, the branch must be rebased on the latest main.

@aferaudo
aferaudo merged commit c475516 into main Nov 16, 2026
12 checks passed
@aferaudo
aferaudo deleted the sync/0.1.8 branch November 16, 2026 20:40

This branch was successfully deployed

2 active deployments
testpypi — c4755167 Deployed Nov 16, 2026 by aferaudo via Publish to TestPyPI #3
pypi — c4755167 Deployed Nov 16, 2026 by aferaudo via Publish to PyPI #3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants