You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 83453f0
Browse filesBrowse the repository at this point in the historyBrowse files
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>
|`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. |
162
162
|`detail`| O || E3-Text | Text for the cause. This field is an extension addition. |
163
163
|`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. |
Copy file name to clipboardExpand all lines: docs/e3ap/integrator-guide.md
+29-29Lines changed: 29 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,9 +29,9 @@ the endpoints.
29
29
| Field | Default | Notes |
30
30
|---|---|---|
31
31
|`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`) |
33
33
|`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`) |
35
35
|`link_layer`| ZMQ | POSIX if the build has no ZeroMQ |
36
36
|`transport_layer`| IPC | SCTP only with `LIBE3_ENABLE_SCTP`|
37
37
|`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.
50
50
| Claim | Code pointer |
51
51
|---|---|
52
52
| 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) |
54
54
| E3 Agent binds the three ZeroMQ sockets |`src/connector/zmq_connector.cpp:130-141`, `201-218`, `265-272`|
| dApp waits 200 ms after connecting the PUB socket (slow joiner) |`zmq_connector.cpp:505`|
@@ -66,32 +66,32 @@ in the connectors.
66
66
67
67
| Claim | Code pointer |
68
68
|---|---|
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`|
76
76
| 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 repeatis 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`|
| 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`|
| 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`|
87
87
| 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`|
93
93
| 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`|
95
95
96
96
### Encoding and framing (chapter 04)
97
97
@@ -102,9 +102,9 @@ in the connectors.
102
102
| The dApp sends unframed |`posix_connector.cpp:681`, `798`|
103
103
| The E3 Agent reads one raw `recv()` of up to 60000 octets |`posix_connector.cpp:355`, `537`|
104
104
| 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`|
108
108
| ASN.1 encoder buffer of 65536 octets |`src/encoder/asn1_encoder.hpp:39`|
109
109
| An empty RAN function list is omitted |`src/encoder/asn1_encoder.cpp:315`|
110
110
| A zero timestamp is left out in APER and Protobuf |`asn1_encoder.cpp:233-243`|
Copy file name to clipboardExpand all lines: docs/interop.md
+8-1Lines changed: 8 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -79,7 +79,12 @@ third and fourth were hex strings; see the ledger.
79
79
**Granted values.** A subscription response carries `telemetryIdentifierList`,
80
80
`controlIdentifierList`, `ranFunctionIdentifier` and `periodicity` when the RAN reports them.
81
81
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.
83
88
84
89
**The `timestamp` key** is written on every message. It is not in Aerial's schema. Aerial's parsers
85
90
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
94
99
|`periodicity` range | 0 to 60000000 over ASN.1; any `uint32` over JSON and Protobuf | 0 and up, no maximum | 0 to 60000 |
95
100
|`periodicity` 0 | every event | as fast as possible, every SRS slot | every event |
96
101
|`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 |
97
103
| 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 |
98
104
| 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) |
99
105
| 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.
566
572
567
573
| Change | PR | Kind | Who has to act | Status |
568
574
|---|---|---|---|---|
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 |
569
576
| 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 |
570
577
| 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 |
571
578
| 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 |
0 commit comments