Skip to content

Commit 83453f0

Browse files
committed
core: report the interval the SM keeps, not the one the dApp asked for
The periodicity of a subscription response was the periodicity of the request (#119). Nothing checked that the Service Model delivered at that rate, so a dApp could be told 500 and get indications every 1000. Aerial's agent returns the requested value too, but it also skips an indication that comes sooner, so there the number is true; here it was not. The response now has a periodicity only when the SM reports one through granted_periodicity(), in microseconds, as the least time it keeps between two indications. An SM that does not override it, one that says 0, and one that says more than the grammar carries (60000000) give a response without it, which reads as "not reported". A repeat of a subscription asks the SM with the periodicity the subscription holds, not the one of the repeat. The telemetry and control lists are unchanged by this commit. No grammar changes and the C API is unchanged. The bytes of a response lose a field that is optional, so an older decoder reads it as before. libe3py's E3Event.periodicity is -1 where it was the requested value. OAI's SMs go through the C API, which has no hook yet, so they report none. Specification and guide: 02 and 03 define the interval as the least time between two indications that the E3 Agent keeps, say that it is not a copy of the request and that a missing one is "not reported", and that the RAN function identifier is for information; 05 gets the row; the encoding clause, the Protobuf grammar and the code comments say the same; the guide gets the row and its pointers; the Word edition is rebuilt. The interop page defines the field in "Granted values" and in the table of field contracts, with what Aerial's agent does, and gets a ledger row. Tests: against four SMs, one without the hook, one that keeps a floor of 1000, one that says 0 and one that says 70000000, on ASN.1 and on JSON: the response has no periodicity, 1000 for a request of 500 and again for a repeat that asks for 9000, none, and none, and the last response is still delivered. The #97 test no longer reads the periodicity from the response, which its SM does not report; it asks the RAN what the subscription holds. The new test fails on the code before this commit. Assisted-by: Claude:claude-sonnet-5-5 Signed-off-by: Thecave3 <thecave003@gmail.com>
1 parent 224df33 commit 83453f0

14 files changed

Lines changed: 293 additions & 51 deletions

‎docs/e3ap/02-ie-mapping.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ Table: E3-SubscriptionResponse
161161
| `cause` | O | | E3-Cause | Why the E3 Agent refused the request. It is present only when the response code is "negative". This field is an extension addition. |
162162
| `detail` | O | | E3-Text | Text for the cause. This field is an extension addition. |
163163
| `ranFunctionIdentifier` | O | | INTEGER (1 to 65535) | The RAN function that the grant is for. This field is an extension addition. |
164-
| `periodicity` | O | 0 to 60000000 | INTEGER | The interval that the E3 Agent grants, in microseconds. Same unit and range as in the request. This field is an extension addition. |
164+
| `periodicity` | O | 0 to 60000000 | INTEGER | The least time, in microseconds, that the E3 Agent keeps between two indications of the subscription. Same unit and range as in the request. It is not a copy of the request: the E3 Agent reports it only when it keeps such an interval, and a missing value means that it does not report one. This field is an extension addition. |
165165

166166
## E3-SubscriptionDelete
167167

‎docs/e3ap/03-procedure-flow.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ starts the service model of the RAN function if the dApp is its first subscriber
114114

115115
The SUBSCRIPTION RESPONSE message has `responseCode` "positive" and holds
116116
`subscriptionId`. It also lists the telemetry identifiers and control identifiers that
117-
the E3 Agent grants, the RAN function identifier and the interval that it grants.
117+
the E3 Agent grants, the RAN function identifier and the interval that it keeps.
118118
The dApp keeps the subscription identifier. A grant list that is missing means that
119119
the E3 Agent does not report the grant. A grant list that is empty means that it
120120
grants nothing.
@@ -128,8 +128,13 @@ message and then a new SUBSCRIPTION REQUEST message. That is the only way that a
128128
known E3 Agents handle alike. A second request that the E3 Agent refuses leaves the
129129
existing subscription as it was.
130130

131-
The E3 Agent sends the interval in microseconds. The value 0 means one indication for
132-
each event. A missing interval means that the service model sets the rate.
131+
The interval in the response is in microseconds. It is the least time that the E3 Agent
132+
keeps between two indications of the subscription. Indications can be further apart,
133+
because the E3 Agent sends them when it has data. It is not a copy of the interval in the
134+
request: a service model that keeps a larger interval reports that one. A missing
135+
interval means that the E3 Agent does not report one, which does not mean that it keeps
136+
none. The value 0 means that it keeps none and is sent as a missing interval. The RAN
137+
function identifier in the response is for information, and a dApp shall not depend on it.
133138

134139
### Unsuccessful operation
135140

‎docs/e3ap/04-encoding.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -312,7 +312,7 @@ E3 DEFINITIONS AUTOMATIC TAGS ::= BEGIN
312312
cause E3-Cause OPTIONAL,
313313
detail E3-Text OPTIONAL,
314314
ranFunctionIdentifier INTEGER (1..65535) OPTIONAL,
315-
-- Granted interval, same unit and range as the request.
315+
-- Least microseconds the E3 Agent keeps between two indications. Absent: not reported.
316316
periodicity INTEGER (0..60000000) OPTIONAL
317317
}
318318

‎docs/e3ap/05-semantics-and-constraints.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ Table: Absent, zero and empty
4949
| `periodicity` 0 | one indication for each event |
5050
| Granted list absent | the E3 Agent does not report the grant |
5151
| Granted list present and empty | the E3 Agent grants nothing |
52+
| `periodicity` absent in a response | the E3 Agent does not report an interval. It may still keep one |
5253
| `sequenceId` absent on a dApp control | the dApp decided on its own. No procedure is behind it |
5354
| `timestamp` absent | no producer reference |
5455

239 Bytes
Binary file not shown.

‎docs/e3ap/integrator-guide.md‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ the endpoints.
2929
| Field | Default | Notes |
3030
|---|---|---|
3131
| `role` | RAN | `E3Role::DAPP` for a dApp |
32-
| `ran_identifier` | empty | an empty value is sent as `unknown` (`e3_interface.cpp:149`) |
32+
| `ran_identifier` | empty | an empty value is sent as `unknown` (`e3_interface.cpp:152`) |
3333
| `dapp_name`, `dapp_version`, `vendor` | `libe3-dapp`, `0.0.0`, empty | empty vendor is sent as `unknown` |
34-
| `e3ap_version` | `1.0.0` | sent in every SETUP REQUEST and SETUP RESPONSE. `init()` returns `INVALID_PARAM` if it is not 1 to 32 octets (`e3_interface.cpp:239-250`) |
34+
| `e3ap_version` | `1.0.0` | sent in every SETUP REQUEST and SETUP RESPONSE. `init()` returns `INVALID_PARAM` if it is not 1 to 32 octets (`e3_interface.cpp:242-253`) |
3535
| `link_layer` | ZMQ | POSIX if the build has no ZeroMQ |
3636
| `transport_layer` | IPC | SCTP only with `LIBE3_ENABLE_SCTP` |
3737
| `setup_port`, `subscriber_port`, `publisher_port` | 9990, 9999, 9991 | `subscriber_*` is the channel into the E3 Agent. `publisher_*` is the channel out of it |
@@ -50,7 +50,7 @@ in the connectors.
5050
| Claim | Code pointer |
5151
|---|---|
5252
| Version string `1.0.0` | `include/libe3/types.hpp:475` |
53-
| The RAN does not check the dApp's version | `e3_interface.cpp:970` (`handle_setup_request` only logs it) |
53+
| The RAN does not check the dApp's version | `e3_interface.cpp:973` (`handle_setup_request` only logs it) |
5454
| E3 Agent binds the three ZeroMQ sockets | `src/connector/zmq_connector.cpp:130-141`, `201-218`, `265-272` |
5555
| dApp connects: REQ, SUB, PUB | `zmq_connector.cpp:356-367`, `449-470`, `484-492` |
5656
| dApp waits 200 ms after connecting the PUB socket (slow joiner) | `zmq_connector.cpp:505` |
@@ -66,32 +66,32 @@ in the connectors.
6666

6767
| Claim | Code pointer |
6868
|---|---|
69-
| Setup on the E3 Agent: decode, register, build the list, answer | `src/core/e3_interface.cpp:561-609`, `964-1076` |
70-
| Negative reply for garbage or a wrong PDU type, with the cause protocolError | `e3_interface.cpp:1078-1112` |
71-
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions | `e3_interface.cpp:993-1034`, `src/core/sm_registry.cpp:35-57` |
72-
| Encode failure of the SETUP RESPONSE ends the process | `e3_interface.cpp:1059-1065` |
73-
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each | `e3_interface.cpp:1472-1555` |
74-
| A negative response still gives "success" to the dApp | `e3_interface.cpp:1544`, `1717-1720` |
75-
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause | `e3_interface.cpp:925-958`, `1114-1201` |
69+
| Setup on the E3 Agent: decode, register, build the list, answer | `src/core/e3_interface.cpp:564-612`, `967-1079` |
70+
| Negative reply for garbage or a wrong PDU type, with the cause protocolError | `e3_interface.cpp:1081-1115` |
71+
| RAN function list limits: data 1 to 32768 octets, 256 identifiers, 64 functions | `e3_interface.cpp:996-1037`, `src/core/sm_registry.cpp:35-57` |
72+
| Encode failure of the SETUP RESPONSE ends the process | `e3_interface.cpp:1062-1068` |
73+
| Setup on the dApp: 5 attempts, 4 receives of 500 ms each | `e3_interface.cpp:1481-1564` |
74+
| A negative response still gives "success" to the dApp | `e3_interface.cpp:1553`, `1726-1729` |
75+
| Subscription: the registration, the RAN function, the lists and every identifier are checked, and a refusal carries a cause | `e3_interface.cpp:928-961`, `1117-1210` |
7676
| Repeat returns the existing identifier. Renewal after expiry keeps the identifier | `subscription_manager.cpp:187-205` |
77-
| A new subscription is answered with the request lists and interval. A repeat is answered with the lists and interval the E3 Agent holds | `e3_interface.cpp:1155-1158`, `1178-1192` |
78-
| Subscription expiry sweep every 250 ms | `e3_interface.cpp:40`, `822-846` |
79-
| Subscription delete | `e3_interface.cpp:1203-1244` |
80-
| The dApp keeps its own deadline from the response | `e3_interface.cpp:1758-1768` |
81-
| Service model starts with the first subscriber and stops with the last | `subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:2021-2035` |
82-
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause | `e3_interface.cpp:1246-1309` |
83-
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes | `e3_interface.cpp:1256-1269`, `examples/sm_simple/simple_service_model.hpp:167` |
84-
| The dApp handles every MESSAGE ACK, with no dApp filter | `e3_interface.cpp:1826-1840` |
85-
| dApp report goes through a queue of 1024 and a worker | `e3_interface.cpp:687-717`, `800-821`, `1311-1319` |
86-
| A report with `sequence_id` 0 is refused with `INVALID_PARAM` | `e3_interface.cpp:1971` |
77+
| The response lists the request lists for a new subscription and the lists the E3 Agent holds for a repeat. Its interval is the one the service model reports with `granted_periodicity()`, and none when it reports 0, nothing, or more than 60000000 | `e3_interface.cpp:1158-1161`, `1181-1201`; `sm_interface.hpp:92-108` |
78+
| Subscription expiry sweep every 250 ms | `e3_interface.cpp:40`, `825-849` |
79+
| Subscription delete | `e3_interface.cpp:1212-1253` |
80+
| The dApp keeps its own deadline from the response | `e3_interface.cpp:1767-1777` |
81+
| Service model starts with the first subscriber and stops with the last | `subscription_manager.cpp:238-241`, `376-378`, `535-554`; `e3_interface.cpp:2030-2044` |
82+
| dApp control: the registration, the RAN function, the control identifier and a running service model are checked. Otherwise a negative MESSAGE ACK with a cause | `e3_interface.cpp:1255-1318` |
83+
| The core sends a MESSAGE ACK only to refuse a control. The service model answers for the controls it takes | `e3_interface.cpp:1265-1278`, `examples/sm_simple/simple_service_model.hpp:167` |
84+
| The dApp handles every MESSAGE ACK, with no dApp filter | `e3_interface.cpp:1835-1849` |
85+
| dApp report goes through a queue of 1024 and a worker | `e3_interface.cpp:690-720`, `803-824`, `1320-1328` |
86+
| A report with `sequence_id` 0 is refused with `INVALID_PARAM` | `e3_interface.cpp:1980` |
8787
| xApp control from the E3 Agent has no check of `sequence_id` | `src/core/e3_agent.cpp:234-255` |
88-
| Release from the dApp: unregister, free identifiers, stop service models | `e3_interface.cpp:1321-1344`; `subscription_manager.cpp:84-138` |
89-
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time | `e3_interface.cpp:1442-1462`; `subscription_manager.cpp:403-410`, `422-434` |
90-
| RELEASE from the E3 Agent: the dApp clears its session | `e3_interface.cpp:1679-1712` |
91-
| Message identifiers: one counter, 1 to 4294967295 | `e3_interface.cpp:167-174` |
92-
| A request identifier of 0 is replaced | `e3_interface.cpp:189-196` |
88+
| Release from the dApp: unregister, free identifiers, stop service models | `e3_interface.cpp:1330-1353`; `subscription_manager.cpp:84-138` |
89+
| RELEASE from the E3 Agent to a dApp that sent nothing for `dapp_idle_timeout_s` (default 1800 s, 0 is off): queued first, then the removal a release from the dApp gets. Only what the dApp sends resets the time | `e3_interface.cpp:1451-1471`; `subscription_manager.cpp:403-410`, `422-434` |
90+
| RELEASE from the E3 Agent: the dApp clears its session | `e3_interface.cpp:1688-1721` |
91+
| Message identifiers: one counter, 1 to 4294967295 | `e3_interface.cpp:170-177` |
92+
| A request identifier of 0 is replaced | `e3_interface.cpp:192-199` |
9393
| The timestamp is set in the `Pdu` constructor | `types.hpp:426-437` |
94-
| Outbound queue of 128 places, 10 ms pop | `e3_interface.cpp:265`, `738-798`; `include/libe3/lockfree_queue.hpp:55` |
94+
| Outbound queue of 128 places, 10 ms pop | `e3_interface.cpp:268`, `741-801`; `include/libe3/lockfree_queue.hpp:55` |
9595

9696
### Encoding and framing (chapter 04)
9797

@@ -102,9 +102,9 @@ in the connectors.
102102
| The dApp sends unframed | `posix_connector.cpp:681`, `798` |
103103
| The E3 Agent reads one raw `recv()` of up to 60000 octets | `posix_connector.cpp:355`, `537` |
104104
| Per-peer send timeout 500 ms | `posix_connector.cpp:41`, `181` |
105-
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp | `posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1370-1389` |
106-
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins | `e3_interface.cpp:652`, `1346-1368` |
107-
| A dApp that lost the E3 Agent registers again every `reconnect_interval_ms` (default 1000, 0 is off), with a new identifier and no subscriptions. `release()` and `stop()` end it | `e3_interface.cpp:1391-1440` |
105+
| A POSIX E3 Agent removes a dApp whose connection closed, if the dApp had sent a message that names it on that connection. ZeroMQ cannot tell its peers apart, so there the idle time removes the dApp | `posix_connector.cpp:515`, `556`, `565-574`, `584-592`; `e3_interface.cpp:1379-1398` |
106+
| A POSIX E3 Agent binds a dApp identifier to the connection that first named it, and drops a later message that names it on another connection. A dApp that has not spoken yet is not bound: the first message wins | `e3_interface.cpp:655`, `1355-1377` |
107+
| A dApp that lost the E3 Agent registers again every `reconnect_interval_ms` (default 1000, 0 is off), with a new identifier and no subscriptions. `release()` and `stop()` end it | `e3_interface.cpp:1400-1449` |
108108
| ASN.1 encoder buffer of 65536 octets | `src/encoder/asn1_encoder.hpp:39` |
109109
| An empty RAN function list is omitted | `src/encoder/asn1_encoder.cpp:315` |
110110
| A zero timestamp is left out in APER and Protobuf | `asn1_encoder.cpp:233-243` |

‎docs/interop.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,12 @@ third and fourth were hex strings; see the ledger.
7979
**Granted values.** A subscription response carries `telemetryIdentifierList`,
8080
`controlIdentifierList`, `ranFunctionIdentifier` and `periodicity` when the RAN reports them.
8181
Absent means not reported; an empty list means none granted. libe3 also reads Aerial's
82-
`telemetryGrantedList` and `controlGrantedList` as aliases.
82+
`telemetryGrantedList` and `controlGrantedList` as aliases. The `periodicity` of a response is
83+
the least time the RAN keeps between two indications of the subscription, in microseconds: Aerial's
84+
agent returns the value it was asked for and skips an indication that comes sooner, and a libe3 Service
85+
Model says what it keeps. A libe3 RAN does not echo the request, so a response without
86+
`periodicity` means the RAN did not say, not that it keeps none. `ranFunctionIdentifier` is for
87+
information and a dApp already has it from its own request. OCUDU's response carries neither.
8388

8489
**The `timestamp` key** is written on every message. It is not in Aerial's schema. Aerial's parsers
8590
read by key, so it is expected to be ignored (not run).
@@ -94,6 +99,7 @@ Where one field means different things to different peers. Add a row when a fiel
9499
| `periodicity` range | 0 to 60000000 over ASN.1; any `uint32` over JSON and Protobuf | 0 and up, no maximum | 0 to 60000 |
95100
| `periodicity` 0 | every event | as fast as possible, every SRS slot | every event |
96101
| `periodicity` default when unset | the Service Model's own rate | 100000 | not stated |
102+
| `periodicity` in a subscription response | the least time the Service Model keeps between two indications, when it says so; absent otherwise | the requested value (100000 when none), which the agent also uses as a gate | not carried |
97103
| dApp id and subscription id | 1..65535; the RAN hands out the lowest free one | counts up from 1, no cap | dApp ids 1..100 reserved for libe3-compatible peers, 101..65535 native |
98104
| Message id | 1..4294967295; a peer's id in a setup request is echoed unless it is 0 | one counter from 1, shared by every message type | 1..4294967295 (its libe3-compatible codec: 1..1000) |
99105
| Setup names (`dAppName`, `vendor`, `ranIdentifier`) | `OCTET STRING`, 1..64 bytes over ASN.1; any length over JSON and Protobuf | JSON string | `OCTET STRING`, 1..64 bytes |
@@ -566,6 +572,7 @@ the same PR as the change. Newest first.
566572

567573
| Change | PR | Kind | Who has to act | Status |
568574
|---|---|---|---|---|
575+
| 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 |
569576
| 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 |
570577
| 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 |
571578
| A POSIX libe3 RAN (TCP, SCTP, IPC) removes a dApp whose connection closes without a release, at once and with nothing sent, if the dApp had sent a message that names it on that connection. It also binds a dApp id to the connection that first named it and drops a later message that names it on another connection, so one dApp can no longer release or control another ([#93](https://github.com/wineslab/libe3/issues/93)) | | Behavior | A dApp that relied on naming another dApp's id from its own connection on POSIX is now dropped. A dApp that closes before its first message, and every ZeroMQ dApp, are still left to the idle time. OAI's E3 agent and the dApp library rebuilt together with the new `E3Connector`, which gains two virtual functions. Nothing on the wire | unmerged |

‎include/libe3/sm_interface.hpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,8 +99,8 @@ class ServiceModel {
9999
*
100100
* @param requested_us Periodicity the dApp asked for, in microseconds. 0 when
101101
* it asked for none or for one indication per event.
102-
* @return Microseconds between two indications, or std::nullopt when the SM
103-
* keeps no interval or does not say.
102+
* @return Microseconds between two indications. std::nullopt or 0 when the SM
103+
* keeps no interval or does not say; the response then has none.
104104
*/
105105
virtual std::optional<uint32_t> granted_periodicity(uint32_t requested_us) const {
106106
(void)requested_us;

0 commit comments

Comments
 (0)