From f6021c0cc4dae017452c7e962dec75a484f1e6dd Mon Sep 17 00:00:00 2001 From: Thecave3 Date: Fri, 6 Nov 2026 19:19:31 -0500 Subject: [PATCH] docs: say that peers adapt to a libe3 agent, and that a response code can be proposed A libe3 RAN agent serves one link and one encoding, set in its E3Config (#85). The interop page said the limit was libe3's to fix, so that one RAN could not face Aerial and OCUDU at once. Agents with different configurations can run at the same time, each with its own ports or endpoints and ran_identifier, and the multi-RAN topology job in CI runs two of them. A RAN with peers on different links or encodings creates one agent for each, and that wiring belongs to the RAN application, not to the library. The page now says so, and that mixed links in one RAN have not been run because SCTP is off in CI. For E3-ResponseCode (#115) the page already asked OCUDU to close its enumeration. It now adds that if OCUDU needs a third code it can propose it on the page, and libe3 is open to adding the extension marker together with the code as one wire change, and to reading an unknown value as a refusal. The ledger gets a documentation row. No code, no grammar and no VERSION change. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 --- docs/interop.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/interop.md b/docs/interop.md index ddd809cf..e4385ff7 100644 --- a/docs/interop.md +++ b/docs/interop.md @@ -50,9 +50,13 @@ No peer is run in CI. What CI does check is messages the peers wrote, and the by | OCUDU | SCTP | ASN.1 | dApp | Source. SCTP is off by default in libe3 (`LIBE3_ENABLE_SCTP`) and nothing in CI uses it ([#81](https://github.com/wineslab/libe3/issues/81)). OCUDU's libe3-compatible mode is the 0.1.3 grammar ([#89](https://github.com/wineslab/libe3/issues/89)) | | OAI | ASN.1 or JSON, chosen at runtime by the `encoding` option of the gNB's E3 configuration (`asn1`, `json` or `protobuf`) | Same | OAI runs the RAN side, libe3 the library underneath | Source. Upstream OAI accepts only `libe3>=0.0.10, <0.2.0`, so it needs a rebuild for anything since 0.2.0 | -A libe3 RAN agent serves one link and one encoding at a time -([#85](https://github.com/wineslab/libe3/issues/85)), so it cannot face Aerial (ZMQ, JSON) and -OCUDU (SCTP, ASN.1) at once. +A libe3 RAN agent serves one link and one encoding, set in its `E3Config` +([#85](https://github.com/wineslab/libe3/issues/85)). Agents with different configurations can run at +the same time, each with its own ports or endpoints and `ran_identifier`: the multi-RAN topology job +in CI runs two this way. A RAN that has peers on different links or encodings, such as Aerial (ZMQ, +JSON) and OCUDU (SCTP, ASN.1), creates one agent for each. That wiring belongs to the RAN +application, not to the library, and a peer uses the agent set up for it. Mixed links in one RAN have +not been run: SCTP is off in CI ([#81](https://github.com/wineslab/libe3/issues/81)). Defaults when nothing is set: setup, subscriber and publisher ports 9990, 9999 and 9991, and the IPC endpoints under `/tmp/dapps/` (`E3Config` in `include/libe3/types.hpp`). @@ -608,7 +612,7 @@ the differences in the first two rows are pinned. | No `dAppReport` or `xAppControlAction`, and no `sequenceId` ([#116](https://github.com/wineslab/libe3/issues/116)) | Add both messages with the mandatory `sequenceId` libe3 0.2.0 uses | The E2-E3 loop needs them; OCUDU has the messages and lacks the id | | The dApp manager refuses a second subscription before it sends it ("limit one subscription per agent for now"), and the agent adds a subscription for every request, with no check for an existing one ([#97](https://github.com/wineslab/libe3/issues/97)) | Return the existing subscription in the agent on a repeat, as libe3 does | libe3 proposes the idempotent form. An agent that adds one per request gives a dApp that retries subscriptions it did not ask for, with ids it cannot tell apart | | Keeps a quiet subscribed dApp alive and sends a `releaseMessage` when it drops one ([#90](https://github.com/wineslab/libe3/issues/90), [#91](https://github.com/wineslab/libe3/issues/91), [#93](https://github.com/wineslab/libe3/issues/93)) | Agree one idle rule with OCUDU. libe3 now sends a `releaseMessage` before it drops a dApp for 1800 s of silence, and counts only what the dApp sends. Drop a quiet dApp that has subscriptions too | A dApp that crashed with a subscription stays in Aerial's agent, with its service model running, until a release arrives. A dApp that only watches for a release never notices OCUDU closing the association | -| ZMQ and JSON only ([#85](https://github.com/wineslab/libe3/issues/85)) | Nothing now. libe3's one-agent-one-link limit is libe3's to fix | One libe3 RAN cannot serve Aerial and OCUDU at once | +| ZMQ and JSON only ([#85](https://github.com/wineslab/libe3/issues/85)) | Nothing in libe3 or in Aerial. A RAN that serves Aerial and OCUDU runs one agent for each | Each peer talks to an agent configured for its link and encoding | ## OCUDU: what to change to align @@ -622,7 +626,7 @@ what it has where the row says so. | dApp ids `1..100` are reserved for libe3-compatible peers, handed out by adapters ([#99](https://github.com/wineslab/libe3/issues/99)) | Accept `1..65535` from libe3-compatible peers and drop the partition and the adapters | libe3 now hands out ids up to 65535, lowest free first, and echoes any non-zero message id | | The libe3-compatible mode keeps libe3's `UTF8String` setup strings and clamps `subscriptionTime` to 3600 ([#108](https://github.com/wineslab/libe3/issues/108), [#113](https://github.com/wineslab/libe3/issues/113)) | Adopt `OCTET STRING` names and versions and the new bounds; the clamp goes | libe3 now has OCUDU's own types and bounds, so the two grammars agree on these fields | | The native module puts the timestamp after the extension marker, `{ id, msg, ..., timestamp }` ([#114](https://github.com/wineslab/libe3/issues/114)) | Put it in the root, `{ id, timestamp OPTIONAL, msg }`, as libe3 and its own libe3-compatible codec do; libe3 keeps its order | That is the layout OAI already runs. Measured on a stamped PDU in a Release build, the extension placement adds 2 bytes (14 to 16 for a `releaseMessage`, 274 to 276 for a 256 byte indication) and about 70 ns to encode and 50 ns to decode, which is small, so the reason is the deployed layout, not speed | -| `E3-ResponseCode` is extensible, `{ positive, negative, ... }` ([#115](https://github.com/wineslab/libe3/issues/115)) | Close it, as libe3 and Aerial's schema have it. If a third code is ever needed, agree it on this page first | With asn1c an unknown extension value decodes as `positive`, so a peer that does not know a new code would read a refusal as success. Neither side has a third code today | +| `E3-ResponseCode` is extensible, `{ positive, negative, ... }` ([#115](https://github.com/wineslab/libe3/issues/115)) | Close it, as libe3 and Aerial's schema have it. If OCUDU needs a third code, propose it here: libe3 is open to adding the extension marker together with the code, as one wire change, and to reading an unknown value as a refusal | With asn1c an unknown extension value decodes as `positive`, so a peer that does not know a new code would read a refusal as success. That is why libe3's type is closed until a code exists. Neither side has a third code today | | The wire guide describes libe3's `E3-PDU` with the timestamp before `msg` and its `E3-ResponseCode` as "deliberately closed", and libe3's limits as 0.1.3's | Update the libe3 rows to 0.2.x | It is the reference an implementer reads | | Compiles libe3's grammar with a different asn1c, so Setup encodes differently and the two cannot share a process ([#109](https://github.com/wineslab/libe3/issues/109)) | Build libe3's grammar with the asn1c commit `build_libe3` pins, then compare Setup again. With `OCTET STRING` setup strings the `UTF8String` part of the difference should be gone | Same bytes from the same grammar | | One SCTP association per dApp, one PDU per SCTP message; payload protocol id, streams and buffers differ ([#104](https://github.com/wineslab/libe3/issues/104) to [#107](https://github.com/wineslab/libe3/issues/107)) | Open. libe3 uses three associations and a length-prefixed stream, and will propose one mapping on those issues | No change to either side is made here | @@ -646,6 +650,7 @@ the same PR as the change. Newest first. | Change | PR | Kind | Who has to act | Status | |---|---|---|---|---| | `E3-ControlResponse` is the answer to a dApp control and to an xApp control. `E3-MessageAck` stays at index 10 of the PDU choice, marked DEPRECATED TO BE REMOVED, and libe3 sends none. Both controls get an optional `requestAck`, an extension addition written only when true. The response has OCUDU's fields and order without `fragmentIndex`, `fragmentCount` and `payloadBytes`, and `controlOutcome` of 1..32768 bytes. It takes index 11 of the PDU choice, as in OCUDU's grammar. The RAN answers a control it refuses itself (no setup, unknown function, unknown control id, no running Service Model) whether it asked or not, and a Service Model through `respond_to_control` only when the control asked. An xApp control that asks is answered by the dApp. A dApp reads only the responses that name it. JSON: type `controlResponse`, `controlOutcome` nested, `requestAck` only when true. Protobuf: `ControlResponse`, case 14. API: `respond_to_control`, `send_control_response`, `set_control_response_handler`, `e3_service_model_emit_control_response`, `e3_agent_set_control_response_handler`, `request_ack` on the two sends and `out_message_id` on `send_xapp_control` are new; the ack's helpers and handlers stay, deprecated. VERSION 0.5.0 ([#111](https://github.com/wineslab/libe3/issues/111)) | [#149](https://github.com/wineslab/libe3/pull/149) | ASN.1 wire, JSON and Protobuf, C++ API, C API, libe3py, behavior | libe3, OAI's E3 agent and the dApp library rebuilt together. Measured in a Linux container: libe3 0.4.3 refuses 0.5.0's response with `DECODE_FAILED`, so an unmatched dApp hears nothing where it heard an ack, and every earlier vector keeps its bytes. A Service Model that answered a control with the ack helpers should answer with `respond_to_control` or `e3_service_model_emit_control_response`: a message ack still goes out, and a libe3 dApp still reads it, but it is deprecated and no new code should send it. A dApp that sent controls and read nothing back sees negative responses for refusals now, as events, and no positive answer unless it sets `requestAck`. OCUDU's libe3-compatible mode re-vendors the grammar. Native OCUDU is unaffected and still not byte-compatible with libe3 for this message (outcome length, response code; measured, not run against its agent) | unmerged | +| The interop page says that a libe3 RAN agent serves one link and one encoding, that agents with different configurations can run at the same time, and that a RAN with Aerial and OCUDU peers runs one for each ([#85](https://github.com/wineslab/libe3/issues/85)). It says that OCUDU can propose a third `E3-ResponseCode` on the page, and that libe3 is open to adding the extension marker with it ([#115](https://github.com/wineslab/libe3/issues/115)) | | Documentation | Nobody. libe3 does not change. A RAN application that serves both stacks creates the agents | unmerged | | The `periodicity` of a libe3 RAN's subscription response is the least time its Service Model keeps between two indications, in microseconds, and is present only when the SM reports it through the new `ServiceModel::granted_periodicity()`. A value of 0, or above 60000000, is left out. It was the periodicity of the request, whatever the SM did with it ([#119](https://github.com/wineslab/libe3/issues/119)) | | Behavior, C++ API | A dApp that read the response's periodicity as the one it asked for sees none now (`E3Event.periodicity` is -1 in libe3py), until the SM reports one. An SM that keeps an interval overrides the hook. OAI's SMs go through the C API, which has no hook yet, so OAI dApps see none. A C++ Service Model built against an older header is rebuilt. ASN.1, JSON and Protobuf are unchanged and so is the C API: the bytes of a response lose a field that is optional | unmerged | | A libe3 RAN answers a repeated subscription (same dApp, same RAN function) with the subscription it holds: the same identifier and the telemetry and control lists and interval it stores. It answered with the lists and interval of the repeat, which it had dropped ([#97](https://github.com/wineslab/libe3/issues/97)) | | Behavior | A dApp that subscribed again to change lists or the interval and read them from the response sees the old ones now, and has to delete the subscription and subscribe again. Nothing on the wire, in the C API or in libe3py, and nothing to rebuild in OAI's E3 agent | unmerged | | After a release, a lost link, or a setup that no RAN answered or that the RAN refused, a libe3 dApp registers again by itself every `reconnect_interval_ms` (default 1000, `0` never), with a new dApp id and none of its old subscriptions, as Aerial's manager does. `release()` and `stop()` end it. The setup response handler runs on every setup, so the application learns it is back there and subscribes again ([#121](https://github.com/wineslab/libe3/issues/121)) | | Behavior | A dApp that waited for the program to call `stop()` then `start()` now registers by itself; one that does so too races with the library, so set `reconnect_interval_ms` to 0 or leave it to the library. The Python dApp framework has to subscribe again on the setup response event. OAI's E3 agent and the dApp library rebuilt together with the new `E3Config`. Nothing on the wire | unmerged |