xdevsm 0.1.0__tar.gz → 0.1.8__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {xdevsm-0.1.0 → xdevsm-0.1.8}/PKG-INFO +123 -3
- {xdevsm-0.1.0 → xdevsm-0.1.8}/README.md +122 -2
- xdevsm-0.1.8/VERSION +1 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/pyproject.toml +4 -1
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/__init__.py +2 -0
- xdevsm-0.1.8/src/xdevsm/_latrec/stages.py +25 -0
- xdevsm-0.1.8/src/xdevsm/_latrec/writer.py +267 -0
- xdevsm-0.1.8/src/xdevsm/decorators/ccc/ccc_control.py +48 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/ccc/ccc_frame.py +9 -7
- xdevsm-0.1.8/src/xdevsm/decorators/ccc/ccc_rrm_policy_control.py +67 -0
- xdevsm-0.1.8/src/xdevsm/decorators/control.py +378 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/dApp/control/dapp_prb_mask_control.py +12 -2
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/dApp/report/dapp_report.py +34 -25
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/kpm/kpm_frame.py +11 -11
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/no_op_dec.py +1 -1
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_connected_mode_mobility.py +2 -2
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_radio_bearer_control.py +2 -2
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_radio_resource_alloc_control.py +2 -2
- xdevsm-0.1.8/src/xdevsm/decorators/rc/rc_report_frame.py +110 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/report.py +153 -42
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/handlers/xDevSM_rmr_xapp.py +136 -33
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/001-enable-indication-msg-free.patch +11 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/002-add-control-ack-decode.patch +128 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/003-add-control-failure-decode.patch +103 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/004-size-control-request-buffer.patch +18 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/README.md +99 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/__init__.py +16 -0
- xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/__main__.py +103 -0
- xdevsm-0.1.8/src/xdevsm/sm_framework/lib/libdapp_sm.so +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libkpm_sm.so +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/library_wrapper.py +1 -1
- xdevsm-0.1.8/src/xdevsm/sm_framework/lib/librc_1_03.so +0 -0
- xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc/ccc_decoder.py +136 -0
- xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc/ccc_encoder.py +219 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/ccc/constants.py +12 -0
- xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlAck.py +102 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlHdr.py +5 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlOut.py +15 -1
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlReq.py +15 -1
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/e3/DAppE3CtrlPayload.py +10 -1
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/e3/DAppE3IndPayload.py +29 -0
- xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/e3/SpectrumApplyOutcome.py +46 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppIndicationHdr.py +31 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmIndicationMsg.py +40 -40
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/MeasData.py +22 -22
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlReq.py +6 -9
- xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/rc/rc_report_codec.py +194 -0
- xdevsm-0.1.8/src/xdevsm/utils/__init__.py +0 -0
- xdevsm-0.1.8/src/xdevsm/utils/ack_route.py +170 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/utils/constants.py +3 -1
- xdevsm-0.1.8/src/xdevsm/utils/log_config.py +196 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/utils/utility.py +34 -7
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/utils/xapp_sub.py +1 -1
- xdevsm-0.1.0/VERSION +0 -1
- xdevsm-0.1.0/src/xdevsm/decorators/control.py +0 -265
- xdevsm-0.1.0/src/xdevsm/sm_framework/lib/libdapp_sm.so +0 -0
- xdevsm-0.1.0/src/xdevsm/sm_framework/lib/librc_1_03.so +0 -0
- xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/ccc/ccc_decoder.py +0 -66
- xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/ccc/ccc_encoder.py +0 -84
- xdevsm-0.1.0/src/xdevsm/utils/lat_profile.py +0 -47
- {xdevsm-0.1.0 → xdevsm-0.1.8}/.gitignore +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/LICENSE +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators → xdevsm-0.1.8/src/xdevsm/_latrec}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/ccc → xdevsm-0.1.8/src/xdevsm/decorators}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/decorators/base.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/dApp → xdevsm-0.1.8/src/xdevsm/decorators/ccc}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/dApp/control → xdevsm-0.1.8/src/xdevsm/decorators/dApp}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/dApp/report → xdevsm-0.1.8/src/xdevsm/decorators/dApp/control}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/kpm → xdevsm-0.1.8/src/xdevsm/decorators/dApp/report}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/decorators/rc → xdevsm-0.1.8/src/xdevsm/decorators/kpm}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/handlers → xdevsm-0.1.8/src/xdevsm/decorators/rc}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/handlers/I_xDevSM_xapp.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework → xdevsm-0.1.8/src/xdevsm/handlers}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/handlers/config.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/README.md +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/lib → xdevsm-0.1.8/src/xdevsm/sm_framework}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran → xdevsm-0.1.8/src/xdevsm/sm_framework/lib}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libkpm_sm_2_01.so +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libsm_framework.so +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/ByteArray.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/ccc → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/dapp → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/dapp/control → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlMsg.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/dapp/e3 → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/control}/__init__.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/dapp/report → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/e3}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/enums.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppActionDef.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppEvTrigger.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppFunctionDef.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppIndicationMsg.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/kpm → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/report}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmFunctionDef.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmIndicationHdr.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/sm_framework/py_oran/rc → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/kpm}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/enums.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/function_definition_builder.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlHdr.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlMsg.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCFunctionDef.py +0 -0
- {xdevsm-0.1.0/src/xdevsm/utils → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/rc}/__init__.py +0 -0
- {xdevsm-0.1.0 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/enums.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: xdevsm
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.8
|
|
4
4
|
Summary: An SDK framework for building O-RAN xApps over E2 Service Models (KPM, RC, CCC).
|
|
5
5
|
Project-URL: Homepage, https://openrangym.com/tutorials/xdevsm-tutorial
|
|
6
6
|
Project-URL: Package, https://pypi.org/project/xdevsm/
|
|
@@ -51,6 +51,7 @@ The architecture separates three main layers:
|
|
|
51
51
|
| **KPM (Key Performance Measurement)** | Measurement Actions | • Common Condition-based Measurement, UE-level Measurement |
|
|
52
52
|
| **RC (RAN Control)** | Control Actions | • QoS Flow Mapping Configuration<br>• Slice-level PRB Quota Action (only monolithic gNBs)<br>• Connected Mode Mobility Control |
|
|
53
53
|
| **CCC (Cell Configuration and Control)** | Report Actions | • Cell-level RAN Configuration Reporting (REPORT Style 2, periodic event trigger) — e.g. `O-NRCellDU` attributes |
|
|
54
|
+
| **CCC (Cell Configuration and Control)** | Control Actions | • Cell-level `O-RRMPolicyRatio` control (CONTROL Style 2): per-slice min, max, and dedicated PRB ratios, tested on OCUDU |
|
|
54
55
|
---
|
|
55
56
|
|
|
56
57
|
## Installation
|
|
@@ -125,7 +126,7 @@ Base class implementing the RMR communication layer. It provides generic `send()
|
|
|
125
126
|
|
|
126
127
|
| Method | Description |
|
|
127
128
|
| -------------------------------- | --------------------------------------------------------------------------------- |
|
|
128
|
-
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. |
|
|
129
|
+
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. Must **not** free `sbuf` — see [inbound buffer ownership](#inbound-buffer-ownership). |
|
|
129
130
|
| `send(self, *args, **kwargs)` | Sends a message via RMR after encoding. Input depends on the underlying E2SM. |
|
|
130
131
|
| `terminate()` | Gracefully stops the xApp. |
|
|
131
132
|
| `get_ran_function_description(json_ran_info)` | Uses the `sm_framework` to decode the RAN function description depending on the SM. |
|
|
@@ -144,9 +145,30 @@ Extends `BasexDevSMXapp` to provide additional functionality specific to the xDe
|
|
|
144
145
|
| `register_handler(handler)` | Registers callback handlers. |
|
|
145
146
|
| `register_shutdown(handler)` | Registers a shutdown handler for cleanup tasks. |
|
|
146
147
|
| `get_ran_info()` | Returns E2 node-related encoded information. |
|
|
148
|
+
| `rmr_free(sbuf)` | Frees an RMR message buffer. Overrides `ricxappframe`'s so that freeing the message currently being dispatched is idempotent — see below. |
|
|
147
149
|
|
|
148
150
|
This class is used as the base class for wrapper components.
|
|
149
151
|
|
|
152
|
+
### Inbound buffer ownership
|
|
153
|
+
|
|
154
|
+
`ricxappframe` allocates a fresh 4 KiB C buffer for every message it receives and
|
|
155
|
+
transfers ownership to the caller; it never frees it. **xDevSM owns that buffer**:
|
|
156
|
+
`xDevSMRMRXapp` releases it once the handler chain has returned, whether the chain
|
|
157
|
+
returned normally or raised.
|
|
158
|
+
|
|
159
|
+
What this means when writing a handler:
|
|
160
|
+
|
|
161
|
+
- **Do not free `sbuf`.** It is released for you. Handlers written against xDevSM ≤ 0.1.3
|
|
162
|
+
that call `xapp.rmr_free(sbuf)` keep working — `rmr_free` makes the first release of
|
|
163
|
+
the in-flight buffer win and the framework's own a no-op — but new code should not.
|
|
164
|
+
Freeing the *same* buffer twice is still a double free, as it always was.
|
|
165
|
+
- **`rmr_rts` before returning is fine.** Returning to sender does not free the buffer,
|
|
166
|
+
and the release happens after your handler returns.
|
|
167
|
+
- **Do not retain `sbuf` past `handle()`.** It is invalid once the chain returns. The
|
|
168
|
+
decoded payload is already in `summary` as Python objects, which are safe to keep.
|
|
169
|
+
- Buffers you allocate yourself are yours to free; `rmr_free` passes those straight
|
|
170
|
+
through.
|
|
171
|
+
|
|
150
172
|
---
|
|
151
173
|
|
|
152
174
|
## 4. BaseXDevSMWrapper
|
|
@@ -240,6 +262,41 @@ ccc_xapp.subscribe_arfcn_bw_bwps(gnb=selected_gnb, ran_period_ms=1000)
|
|
|
240
262
|
|
|
241
263
|
> ℹ️ The indication callback signature is `handler(ind_hdr, ind_msg, meid, sub_id)`. Iterate the reported cells/structures with `ind_msg.cells()` / `ind_msg.iter_structures()`.
|
|
242
264
|
|
|
265
|
+
### CccRrmPolicyRatioControl
|
|
266
|
+
|
|
267
|
+
`CccRrmPolicyRatioControl` sends the E2SM-CCC cell-level control (CONTROL Style 2, Header Format 1, Message Format 2) for the `O-RRMPolicyRatio` structure. It sets the PRB share of a slice in one cell, so it needs no UE ID. It extends `xAppControlService` and uses `send_policies()` instead of `send()`, because the JSON encoding has no ASN.1 function definition.
|
|
268
|
+
|
|
269
|
+
* `find_ccc_function_id(json_ran_info)` returns the CCC RAN function ID from the e2mgr information of the E2 node. It accepts the OID `1.3.6.1.4.1.53148.1.1.2.4` and the OID `1.3.6.1.4.1.53148.1.6.2.4` that OCUDU announces.
|
|
270
|
+
* `send_policies()` checks every slice, then sends all slices in one control, so the cell applies them together. A control for two or more slices is larger than 1 KB and needs the xDevSM ricxappframe patches (patch 004).
|
|
271
|
+
* Each slice needs `dedicated_ratio <= min_ratio <= max_ratio`, and the `min_ratio` of the slices in one call must sum to at most 100 (TS 28.541). `dedicated_ratio` defaults to 0.
|
|
272
|
+
* The Old Values of each slice carry its resource type and member, so the E2 node can find the policy to change. They leave out the old ratios, which the xApp does not read.
|
|
273
|
+
* Known OCUDU limits: it reads `rRMPolicyDedicatedRatio` 0 as missing and fails the control (pass `dedicated_ratio=1` or more), and it applies only the min and max ratios, only to slices in `cell_cfg: slicing`.
|
|
274
|
+
* The callbacks of `register_control_ack_suc_callback()` and `register_control_ack_fail_callback()` receive a `CccControlAck` for a RIC Control Acknowledge or Failure. Its `outcome` is a `CccControlOutcome`, the JSON E2SM-CCC Control Outcome of the message. `outcome.structures()` lists each structure with `applied`, its `applied_values` (the currentValuesOfAttributes) or its `failure_reason`. A failure also carries `cause`, the E2AP Cause as (choice, value). A message that does not decode reaches the callback as the RMR summary. Decoding needs the xDevSM ricxappframe patches (`python -m xdevsm.ricxappframe_patches`).
|
|
275
|
+
|
|
276
|
+
```python
|
|
277
|
+
from xdevsm import CccRrmPolicyRatioControl
|
|
278
|
+
from xdevsm.sm_framework.py_oran.ccc.ccc_decoder import find_ccc_function_id
|
|
279
|
+
from xdevsm.sm_framework.py_oran.ccc.ccc_encoder import RrmPolicySlice
|
|
280
|
+
|
|
281
|
+
gnb, gnb_info = xapp_gen.get_selected_e2node_info(None)
|
|
282
|
+
ctrl = CccRrmPolicyRatioControl(xapp_gen,
|
|
283
|
+
logger=xapp_gen.logger,
|
|
284
|
+
server=xapp_gen.server,
|
|
285
|
+
xapp_name=xapp_gen.get_xapp_name(),
|
|
286
|
+
rmr_port=xapp_gen.rmr_port,
|
|
287
|
+
http_port=xapp_gen.http_port,
|
|
288
|
+
mrc=xapp_gen._mrc,
|
|
289
|
+
pltnamespace=xapp_gen.get_pltnamespace(),
|
|
290
|
+
app_namespace=xapp_gen.get_app_namespace(),
|
|
291
|
+
mcc="001", mnc="01",
|
|
292
|
+
nci=0x3954000, # 36-bit NR Cell Identity
|
|
293
|
+
function_id=find_ccc_function_id(gnb_info))
|
|
294
|
+
xapp_gen.register_handler(ctrl.handle)
|
|
295
|
+
ctrl.send_policies(gnb.inventory_name,
|
|
296
|
+
[RrmPolicySlice(sst=1, sd="000001", min_ratio=1, max_ratio=10, dedicated_ratio=1)],
|
|
297
|
+
resource_type="PRB_DL")
|
|
298
|
+
```
|
|
299
|
+
|
|
243
300
|
---
|
|
244
301
|
## 7. xAppReportService
|
|
245
302
|
|
|
@@ -390,7 +447,70 @@ To support a new Service Model (E2SM):
|
|
|
390
447
|
|
|
391
448
|
---
|
|
392
449
|
|
|
393
|
-
## 12.
|
|
450
|
+
## 12. Latency instrumentation (latrec)
|
|
451
|
+
|
|
452
|
+
xDevSM can record per-stage latency data for the E2AP/E2SM-DAPP legs it owns
|
|
453
|
+
(indication decode, control encode, and the E2AP framing/send around it),
|
|
454
|
+
using **latrec**, the ring-recorder format shared with
|
|
455
|
+
[libe3](https://github.com/wineslab/libe3) and the rest of the E2/E3 stack.
|
|
456
|
+
It is off by default.
|
|
457
|
+
|
|
458
|
+
- **Enable** by setting `LATREC_DIR` to a writable directory before starting
|
|
459
|
+
the xApp process. Each stamping thread writes one `<role>.<tid>.latrec`
|
|
460
|
+
ring file there (role `xdevsm`).
|
|
461
|
+
- **Size** the rings with `LATREC_ENTRIES_LOG2_XDEVSM` (or the stack-wide
|
|
462
|
+
`LATREC_ENTRIES_LOG2`), as a power-of-two exponent between 12 and 28;
|
|
463
|
+
the default is 18, i.e. 256K records ≈ 8 MiB per thread.
|
|
464
|
+
- **Disable** by leaving `LATREC_DIR` unset. Every stamp site then costs a
|
|
465
|
+
module-level check and a no-op call — tens of nanoseconds, no locks and no
|
|
466
|
+
allocation, but not literally zero. Run `scripts/latrec_bench.py` to
|
|
467
|
+
measure both paths on your own hardware; it reports enabled and disabled
|
|
468
|
+
cost side by side.
|
|
469
|
+
- The writer (`xdevsm._latrec.writer`) is a self-contained, pure-Python
|
|
470
|
+
module with no `xdevsm`-specific dependencies, so it can be reused as-is
|
|
471
|
+
by other pure-Python components that need the same mechanism.
|
|
472
|
+
- Rings are read with libe3's own tooling (`tools/latrec_reader.py` /
|
|
473
|
+
`tools/latrec2csv.py`); the stage identifiers this package stamps mirror
|
|
474
|
+
`libe3/include/libe3/latrec.h` (see `xdevsm/_latrec/stages.py`).
|
|
475
|
+
|
|
476
|
+
## 13. Logging
|
|
477
|
+
|
|
478
|
+
The framework configures the xApp's logger from the `controls` block of the xApp
|
|
479
|
+
descriptor (the JSON at `CONFIG_FILE`), so verbosity and destination are set
|
|
480
|
+
externally rather than in code. Each key can be overridden by an environment
|
|
481
|
+
variable, which lets a Deployment change them without rebuilding the image.
|
|
482
|
+
|
|
483
|
+
| `controls` key | Env override | Values | Default |
|
|
484
|
+
| -------------- | ------------ | ------ | ------- |
|
|
485
|
+
| `log_level` | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
|
|
486
|
+
| `log_stdout` | `LOG_STDOUT` | boolean | `true` |
|
|
487
|
+
| `log_file` | `LOG_FILE` | path; empty means no file | unset |
|
|
488
|
+
|
|
489
|
+
```json
|
|
490
|
+
{
|
|
491
|
+
"controls": {
|
|
492
|
+
"log_level": "ERROR",
|
|
493
|
+
"log_stdout": false,
|
|
494
|
+
"log_file": "/tmp/xapp.log"
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
- Precedence is **environment → `controls` → default**. An unrecognised level
|
|
500
|
+
falls back to `INFO` rather than raising, so a typo in a descriptor cannot
|
|
501
|
+
stop an xApp from starting.
|
|
502
|
+
- `ERROR` is the quietest setting available — `mdclogpy`'s severity enum has no
|
|
503
|
+
`OFF`.
|
|
504
|
+
- Settings are applied in `xDevSMRMRXapp.__init__` before the routing table,
|
|
505
|
+
HTTP server and subscriptions are set up, so `log_level` governs the startup
|
|
506
|
+
logs too.
|
|
507
|
+
- With `log_stdout` false, the container writes nothing to stdout, so
|
|
508
|
+
`kubectl logs` is empty and `log_file` becomes the only record — point it at a
|
|
509
|
+
mounted volume if it needs to outlive the pod.
|
|
510
|
+
- The logger is shared with `ricxappframe`, so these settings cover its output
|
|
511
|
+
as well as this framework's.
|
|
512
|
+
|
|
513
|
+
## 14. Other Sources
|
|
394
514
|
|
|
395
515
|
A detailed step-by-step tutorial for setting up a deployment to begin working with xDevSM is available [here](https://openrangym.com/tutorials/xdevsm-tutorial).
|
|
396
516
|
|
|
@@ -24,6 +24,7 @@ The architecture separates three main layers:
|
|
|
24
24
|
| **KPM (Key Performance Measurement)** | Measurement Actions | • Common Condition-based Measurement, UE-level Measurement |
|
|
25
25
|
| **RC (RAN Control)** | Control Actions | • QoS Flow Mapping Configuration<br>• Slice-level PRB Quota Action (only monolithic gNBs)<br>• Connected Mode Mobility Control |
|
|
26
26
|
| **CCC (Cell Configuration and Control)** | Report Actions | • Cell-level RAN Configuration Reporting (REPORT Style 2, periodic event trigger) — e.g. `O-NRCellDU` attributes |
|
|
27
|
+
| **CCC (Cell Configuration and Control)** | Control Actions | • Cell-level `O-RRMPolicyRatio` control (CONTROL Style 2): per-slice min, max, and dedicated PRB ratios, tested on OCUDU |
|
|
27
28
|
---
|
|
28
29
|
|
|
29
30
|
## Installation
|
|
@@ -98,7 +99,7 @@ Base class implementing the RMR communication layer. It provides generic `send()
|
|
|
98
99
|
|
|
99
100
|
| Method | Description |
|
|
100
101
|
| -------------------------------- | --------------------------------------------------------------------------------- |
|
|
101
|
-
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. |
|
|
102
|
+
| `handle(xapp, summary, sbuf)` | Method called by the `ricxappframe`. Entry point for processing received messages (`Indication` and `RIC CONTROL ` Messages`). Should be overridden by subclasses. Must **not** free `sbuf` — see [inbound buffer ownership](#inbound-buffer-ownership). |
|
|
102
103
|
| `send(self, *args, **kwargs)` | Sends a message via RMR after encoding. Input depends on the underlying E2SM. |
|
|
103
104
|
| `terminate()` | Gracefully stops the xApp. |
|
|
104
105
|
| `get_ran_function_description(json_ran_info)` | Uses the `sm_framework` to decode the RAN function description depending on the SM. |
|
|
@@ -117,9 +118,30 @@ Extends `BasexDevSMXapp` to provide additional functionality specific to the xDe
|
|
|
117
118
|
| `register_handler(handler)` | Registers callback handlers. |
|
|
118
119
|
| `register_shutdown(handler)` | Registers a shutdown handler for cleanup tasks. |
|
|
119
120
|
| `get_ran_info()` | Returns E2 node-related encoded information. |
|
|
121
|
+
| `rmr_free(sbuf)` | Frees an RMR message buffer. Overrides `ricxappframe`'s so that freeing the message currently being dispatched is idempotent — see below. |
|
|
120
122
|
|
|
121
123
|
This class is used as the base class for wrapper components.
|
|
122
124
|
|
|
125
|
+
### Inbound buffer ownership
|
|
126
|
+
|
|
127
|
+
`ricxappframe` allocates a fresh 4 KiB C buffer for every message it receives and
|
|
128
|
+
transfers ownership to the caller; it never frees it. **xDevSM owns that buffer**:
|
|
129
|
+
`xDevSMRMRXapp` releases it once the handler chain has returned, whether the chain
|
|
130
|
+
returned normally or raised.
|
|
131
|
+
|
|
132
|
+
What this means when writing a handler:
|
|
133
|
+
|
|
134
|
+
- **Do not free `sbuf`.** It is released for you. Handlers written against xDevSM ≤ 0.1.3
|
|
135
|
+
that call `xapp.rmr_free(sbuf)` keep working — `rmr_free` makes the first release of
|
|
136
|
+
the in-flight buffer win and the framework's own a no-op — but new code should not.
|
|
137
|
+
Freeing the *same* buffer twice is still a double free, as it always was.
|
|
138
|
+
- **`rmr_rts` before returning is fine.** Returning to sender does not free the buffer,
|
|
139
|
+
and the release happens after your handler returns.
|
|
140
|
+
- **Do not retain `sbuf` past `handle()`.** It is invalid once the chain returns. The
|
|
141
|
+
decoded payload is already in `summary` as Python objects, which are safe to keep.
|
|
142
|
+
- Buffers you allocate yourself are yours to free; `rmr_free` passes those straight
|
|
143
|
+
through.
|
|
144
|
+
|
|
123
145
|
---
|
|
124
146
|
|
|
125
147
|
## 4. BaseXDevSMWrapper
|
|
@@ -213,6 +235,41 @@ ccc_xapp.subscribe_arfcn_bw_bwps(gnb=selected_gnb, ran_period_ms=1000)
|
|
|
213
235
|
|
|
214
236
|
> ℹ️ The indication callback signature is `handler(ind_hdr, ind_msg, meid, sub_id)`. Iterate the reported cells/structures with `ind_msg.cells()` / `ind_msg.iter_structures()`.
|
|
215
237
|
|
|
238
|
+
### CccRrmPolicyRatioControl
|
|
239
|
+
|
|
240
|
+
`CccRrmPolicyRatioControl` sends the E2SM-CCC cell-level control (CONTROL Style 2, Header Format 1, Message Format 2) for the `O-RRMPolicyRatio` structure. It sets the PRB share of a slice in one cell, so it needs no UE ID. It extends `xAppControlService` and uses `send_policies()` instead of `send()`, because the JSON encoding has no ASN.1 function definition.
|
|
241
|
+
|
|
242
|
+
* `find_ccc_function_id(json_ran_info)` returns the CCC RAN function ID from the e2mgr information of the E2 node. It accepts the OID `1.3.6.1.4.1.53148.1.1.2.4` and the OID `1.3.6.1.4.1.53148.1.6.2.4` that OCUDU announces.
|
|
243
|
+
* `send_policies()` checks every slice, then sends all slices in one control, so the cell applies them together. A control for two or more slices is larger than 1 KB and needs the xDevSM ricxappframe patches (patch 004).
|
|
244
|
+
* Each slice needs `dedicated_ratio <= min_ratio <= max_ratio`, and the `min_ratio` of the slices in one call must sum to at most 100 (TS 28.541). `dedicated_ratio` defaults to 0.
|
|
245
|
+
* The Old Values of each slice carry its resource type and member, so the E2 node can find the policy to change. They leave out the old ratios, which the xApp does not read.
|
|
246
|
+
* Known OCUDU limits: it reads `rRMPolicyDedicatedRatio` 0 as missing and fails the control (pass `dedicated_ratio=1` or more), and it applies only the min and max ratios, only to slices in `cell_cfg: slicing`.
|
|
247
|
+
* The callbacks of `register_control_ack_suc_callback()` and `register_control_ack_fail_callback()` receive a `CccControlAck` for a RIC Control Acknowledge or Failure. Its `outcome` is a `CccControlOutcome`, the JSON E2SM-CCC Control Outcome of the message. `outcome.structures()` lists each structure with `applied`, its `applied_values` (the currentValuesOfAttributes) or its `failure_reason`. A failure also carries `cause`, the E2AP Cause as (choice, value). A message that does not decode reaches the callback as the RMR summary. Decoding needs the xDevSM ricxappframe patches (`python -m xdevsm.ricxappframe_patches`).
|
|
248
|
+
|
|
249
|
+
```python
|
|
250
|
+
from xdevsm import CccRrmPolicyRatioControl
|
|
251
|
+
from xdevsm.sm_framework.py_oran.ccc.ccc_decoder import find_ccc_function_id
|
|
252
|
+
from xdevsm.sm_framework.py_oran.ccc.ccc_encoder import RrmPolicySlice
|
|
253
|
+
|
|
254
|
+
gnb, gnb_info = xapp_gen.get_selected_e2node_info(None)
|
|
255
|
+
ctrl = CccRrmPolicyRatioControl(xapp_gen,
|
|
256
|
+
logger=xapp_gen.logger,
|
|
257
|
+
server=xapp_gen.server,
|
|
258
|
+
xapp_name=xapp_gen.get_xapp_name(),
|
|
259
|
+
rmr_port=xapp_gen.rmr_port,
|
|
260
|
+
http_port=xapp_gen.http_port,
|
|
261
|
+
mrc=xapp_gen._mrc,
|
|
262
|
+
pltnamespace=xapp_gen.get_pltnamespace(),
|
|
263
|
+
app_namespace=xapp_gen.get_app_namespace(),
|
|
264
|
+
mcc="001", mnc="01",
|
|
265
|
+
nci=0x3954000, # 36-bit NR Cell Identity
|
|
266
|
+
function_id=find_ccc_function_id(gnb_info))
|
|
267
|
+
xapp_gen.register_handler(ctrl.handle)
|
|
268
|
+
ctrl.send_policies(gnb.inventory_name,
|
|
269
|
+
[RrmPolicySlice(sst=1, sd="000001", min_ratio=1, max_ratio=10, dedicated_ratio=1)],
|
|
270
|
+
resource_type="PRB_DL")
|
|
271
|
+
```
|
|
272
|
+
|
|
216
273
|
---
|
|
217
274
|
## 7. xAppReportService
|
|
218
275
|
|
|
@@ -363,7 +420,70 @@ To support a new Service Model (E2SM):
|
|
|
363
420
|
|
|
364
421
|
---
|
|
365
422
|
|
|
366
|
-
## 12.
|
|
423
|
+
## 12. Latency instrumentation (latrec)
|
|
424
|
+
|
|
425
|
+
xDevSM can record per-stage latency data for the E2AP/E2SM-DAPP legs it owns
|
|
426
|
+
(indication decode, control encode, and the E2AP framing/send around it),
|
|
427
|
+
using **latrec**, the ring-recorder format shared with
|
|
428
|
+
[libe3](https://github.com/wineslab/libe3) and the rest of the E2/E3 stack.
|
|
429
|
+
It is off by default.
|
|
430
|
+
|
|
431
|
+
- **Enable** by setting `LATREC_DIR` to a writable directory before starting
|
|
432
|
+
the xApp process. Each stamping thread writes one `<role>.<tid>.latrec`
|
|
433
|
+
ring file there (role `xdevsm`).
|
|
434
|
+
- **Size** the rings with `LATREC_ENTRIES_LOG2_XDEVSM` (or the stack-wide
|
|
435
|
+
`LATREC_ENTRIES_LOG2`), as a power-of-two exponent between 12 and 28;
|
|
436
|
+
the default is 18, i.e. 256K records ≈ 8 MiB per thread.
|
|
437
|
+
- **Disable** by leaving `LATREC_DIR` unset. Every stamp site then costs a
|
|
438
|
+
module-level check and a no-op call — tens of nanoseconds, no locks and no
|
|
439
|
+
allocation, but not literally zero. Run `scripts/latrec_bench.py` to
|
|
440
|
+
measure both paths on your own hardware; it reports enabled and disabled
|
|
441
|
+
cost side by side.
|
|
442
|
+
- The writer (`xdevsm._latrec.writer`) is a self-contained, pure-Python
|
|
443
|
+
module with no `xdevsm`-specific dependencies, so it can be reused as-is
|
|
444
|
+
by other pure-Python components that need the same mechanism.
|
|
445
|
+
- Rings are read with libe3's own tooling (`tools/latrec_reader.py` /
|
|
446
|
+
`tools/latrec2csv.py`); the stage identifiers this package stamps mirror
|
|
447
|
+
`libe3/include/libe3/latrec.h` (see `xdevsm/_latrec/stages.py`).
|
|
448
|
+
|
|
449
|
+
## 13. Logging
|
|
450
|
+
|
|
451
|
+
The framework configures the xApp's logger from the `controls` block of the xApp
|
|
452
|
+
descriptor (the JSON at `CONFIG_FILE`), so verbosity and destination are set
|
|
453
|
+
externally rather than in code. Each key can be overridden by an environment
|
|
454
|
+
variable, which lets a Deployment change them without rebuilding the image.
|
|
455
|
+
|
|
456
|
+
| `controls` key | Env override | Values | Default |
|
|
457
|
+
| -------------- | ------------ | ------ | ------- |
|
|
458
|
+
| `log_level` | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
|
|
459
|
+
| `log_stdout` | `LOG_STDOUT` | boolean | `true` |
|
|
460
|
+
| `log_file` | `LOG_FILE` | path; empty means no file | unset |
|
|
461
|
+
|
|
462
|
+
```json
|
|
463
|
+
{
|
|
464
|
+
"controls": {
|
|
465
|
+
"log_level": "ERROR",
|
|
466
|
+
"log_stdout": false,
|
|
467
|
+
"log_file": "/tmp/xapp.log"
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
- Precedence is **environment → `controls` → default**. An unrecognised level
|
|
473
|
+
falls back to `INFO` rather than raising, so a typo in a descriptor cannot
|
|
474
|
+
stop an xApp from starting.
|
|
475
|
+
- `ERROR` is the quietest setting available — `mdclogpy`'s severity enum has no
|
|
476
|
+
`OFF`.
|
|
477
|
+
- Settings are applied in `xDevSMRMRXapp.__init__` before the routing table,
|
|
478
|
+
HTTP server and subscriptions are set up, so `log_level` governs the startup
|
|
479
|
+
logs too.
|
|
480
|
+
- With `log_stdout` false, the container writes nothing to stdout, so
|
|
481
|
+
`kubectl logs` is empty and `log_file` becomes the only record — point it at a
|
|
482
|
+
mounted volume if it needs to outlive the pod.
|
|
483
|
+
- The logger is shared with `ricxappframe`, so these settings cover its output
|
|
484
|
+
as well as this framework's.
|
|
485
|
+
|
|
486
|
+
## 14. Other Sources
|
|
367
487
|
|
|
368
488
|
A detailed step-by-step tutorial for setting up a deployment to begin working with xDevSM is available [here](https://openrangym.com/tutorials/xdevsm-tutorial).
|
|
369
489
|
|
xdevsm-0.1.8/VERSION
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
0.1.8
|
|
@@ -62,7 +62,10 @@ pattern = "^(?P<version>\\d+\\.\\d+\\.\\d+)"
|
|
|
62
62
|
packages = ["src/xdevsm"]
|
|
63
63
|
# The prebuilt Service Model encoders are shipped as package data; declare them as
|
|
64
64
|
# build artifacts so they are always included regardless of VCS-ignore rules.
|
|
65
|
-
artifacts = [
|
|
65
|
+
artifacts = [
|
|
66
|
+
"src/xdevsm/sm_framework/lib/*.so",
|
|
67
|
+
"src/xdevsm/ricxappframe_patches/*.patch",
|
|
68
|
+
]
|
|
66
69
|
|
|
67
70
|
|
|
68
71
|
[tool.hatch.build.targets.sdist]
|
|
@@ -23,6 +23,8 @@ _LAZY = {
|
|
|
23
23
|
"BaseXDevSMWrapper": "xdevsm.decorators.base:BaseXDevSMWrapper",
|
|
24
24
|
"XappKpmFrame": "xdevsm.decorators.kpm.kpm_frame:XappKpmFrame",
|
|
25
25
|
"XappCccFrame": "xdevsm.decorators.ccc.ccc_frame:XappCccFrame",
|
|
26
|
+
"CccRrmPolicyRatioControl": "xdevsm.decorators.ccc.ccc_rrm_policy_control:CccRrmPolicyRatioControl",
|
|
27
|
+
"XappRcReportFrame": "xdevsm.decorators.rc.rc_report_frame:XappRcReportFrame",
|
|
26
28
|
"RadioBearerControl": "xdevsm.decorators.rc.rc_radio_bearer_control:RadioBearerControl",
|
|
27
29
|
"RadioResourceAllocationControl": "xdevsm.decorators.rc.rc_radio_resource_alloc_control:RadioResourceAllocationControl",
|
|
28
30
|
"ConnectedModeMobilityControl": "xdevsm.decorators.rc.rc_connected_mode_mobility:ConnectedModeMobilityControl",
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""xDevSM's mirror of the subset of libe3's shared stage catalog this
|
|
2
|
+
framework stamps: the E2AP and E2SM-DAPP codec boxes on the Path-B loop
|
|
3
|
+
(B3/B5/B6 in libe3's docs/path-b-e2-e3-loop.md).
|
|
4
|
+
|
|
5
|
+
Source of truth: libe3/include/libe3/latrec.h (branch feat/latency-tracing).
|
|
6
|
+
These are shared, cross-repo identifiers -- do not renumber locally. A value
|
|
7
|
+
that drifts from libe3's header breaks the join with every other
|
|
8
|
+
component's rings silently (no runtime check catches it on this side).
|
|
9
|
+
|
|
10
|
+
XAPP_PROCESS_DONE (0x62, B4's exit) is deliberately not stamped by this
|
|
11
|
+
package: B4 is the researcher's own xApp callback, not the framework.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
# Ring role for this package's threads: rings are <role>.<tid>.latrec, and
|
|
15
|
+
# libe3's converter already maps the "xdevsm" role onto its xapp component.
|
|
16
|
+
LATREC_ROLE = "xdevsm"
|
|
17
|
+
|
|
18
|
+
DECODE_E2AP_BEGIN = 0x5A
|
|
19
|
+
DECODE_E2AP_DONE = 0x5B
|
|
20
|
+
DECODE_E2SM_BEGIN = 0x60
|
|
21
|
+
DECODE_E2SM_DONE = 0x61
|
|
22
|
+
ENCODE_E2SM_BEGIN = 0x63
|
|
23
|
+
ENCODE_E2SM_DONE = 0x64
|
|
24
|
+
ENCODE_E2AP_BEGIN = 0x58
|
|
25
|
+
ENCODE_E2AP_DONE = 0x59
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
"""Reference Python latrec writer -- a per-writer mmap ring recorder.
|
|
2
|
+
|
|
3
|
+
WIRE-FORMAT CONTRACT. Byte-identical to the C ``latrec_hdr`` / ``latrec_rec``
|
|
4
|
+
layout libe3 writes, so the RAN, the dApps, the E2 agent and any xApp
|
|
5
|
+
framework produce one comparable capture and the offline converter
|
|
6
|
+
(libe3's ``tools/latrec_reader.py`` / ``latrec2csv.py``) reads every ring the
|
|
7
|
+
same way. This module has no dependency on libe3's build (no SWIG binding
|
|
8
|
+
available here), so the format is mirrored by hand. Two things must not
|
|
9
|
+
drift from libe3/include/libe3/latrec.h:
|
|
10
|
+
- the on-disk layout below (magic, version, 4 KiB header, 32-byte records);
|
|
11
|
+
- the stage ids a caller passes to ``stamp()`` -- a cross-repo namespace
|
|
12
|
+
owned by libe3's catalog, not by this module.
|
|
13
|
+
|
|
14
|
+
This module is intentionally catalog-agnostic: it knows nothing about which
|
|
15
|
+
stage ids mean what. Callers own their own mirror of the relevant subset of
|
|
16
|
+
libe3's catalog (see e.g. ``xdevsm._latrec.stages``) and pass raw ints.
|
|
17
|
+
|
|
18
|
+
Env-gated by ``LATREC_DIR``: every ``stamp()`` is a no-op when it is unset.
|
|
19
|
+
This mirrors libe3's own directory-selection knob, but -- unlike libe3/
|
|
20
|
+
flexric's C build-flag gate -- a pure-Python package has no separate build
|
|
21
|
+
for "traced" vs "untraced", so the runtime env var is the only gate
|
|
22
|
+
available here.
|
|
23
|
+
|
|
24
|
+
Record: 32 B = sc(u64: seq:48 | cpu:8 | stage:8), t_ns(u64, written LAST ==
|
|
25
|
+
valid), aux(u64), aux2(u64). The cpu byte is left 0: CPython has no
|
|
26
|
+
``os.sched_getcpu()`` before 3.13, and reading it per stamp any other way
|
|
27
|
+
costs more than the stamp.
|
|
28
|
+
|
|
29
|
+
One caveat against libe3's C writer: it publishes t_ns with an explicit
|
|
30
|
+
release store (``LATREC_STORE_RELEASE``), and Python has no equivalent --
|
|
31
|
+
``struct.pack_into`` is a plain memcpy. Writing t_ns last is therefore
|
|
32
|
+
ordered by the hardware alone: guaranteed on x86-64 (TSO), not on aarch64.
|
|
33
|
+
That only matters to a *live* reader racing the writer; the offline
|
|
34
|
+
capture-then-convert workflow these rings are built for reads a quiescent
|
|
35
|
+
file, where the ordering is moot.
|
|
36
|
+
|
|
37
|
+
This module is meant to be adopted as-is by other pure-Python components in
|
|
38
|
+
this stack (e.g. spear-dApp) once they need the same mechanism -- keep it
|
|
39
|
+
free of any project-specific imports so reuse is a straight copy, not a
|
|
40
|
+
rewrite.
|
|
41
|
+
"""
|
|
42
|
+
import atexit
|
|
43
|
+
import mmap
|
|
44
|
+
import os
|
|
45
|
+
import struct
|
|
46
|
+
import threading
|
|
47
|
+
import time
|
|
48
|
+
|
|
49
|
+
HDR_LEN = 4096
|
|
50
|
+
MAGIC = 0x31524C41 # "ALR1"
|
|
51
|
+
VERSION = 2
|
|
52
|
+
_REC_SIZE = 32
|
|
53
|
+
_HDR = struct.Struct("<IIQQQQ64s") # v1 prefix; offsets frozen
|
|
54
|
+
_HDR_V2 = struct.Struct("<IIQQ") # rec_size, clock_ns_per_call, t1_mono, t1_real
|
|
55
|
+
_V2_OFF = 104
|
|
56
|
+
|
|
57
|
+
# Sampled once, at import, for tls_ring()'s fast path only -- the stamp sites
|
|
58
|
+
# are on the message hot path, and re-deriving "is tracing on" per stamp is
|
|
59
|
+
# what made the disabled path cost anything at all. LatRec() and ring() still
|
|
60
|
+
# read os.environ per call, so they stay configurable at runtime (the tests
|
|
61
|
+
# rely on that); tls_ring() is the one that must be free when off, and
|
|
62
|
+
# LATREC_DIR is a process-level knob set before start, never mid-run.
|
|
63
|
+
_DIR = os.environ.get("LATREC_DIR") or None
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _mono_ns() -> int:
|
|
67
|
+
return time.clock_gettime_ns(time.CLOCK_MONOTONIC)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _real_ns() -> int:
|
|
71
|
+
return time.clock_gettime_ns(time.CLOCK_REALTIME)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def measure_clock_ns() -> int:
|
|
75
|
+
"""Mean cost of one _mono_ns(), recorded in the header so a reader can
|
|
76
|
+
discount it. The Python call overhead dominates, so this is much larger
|
|
77
|
+
than the C writers report -- which is the point of recording it."""
|
|
78
|
+
iters = 1000
|
|
79
|
+
t0 = _mono_ns()
|
|
80
|
+
for _ in range(iters):
|
|
81
|
+
_mono_ns()
|
|
82
|
+
return max(0, (_mono_ns() - t0) // iters)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _entries_log2(role: str, fallback: int) -> int:
|
|
86
|
+
"""LATREC_ENTRIES_LOG2_<ROLE> (role uppercased, non-alphanumerics as '_'),
|
|
87
|
+
else LATREC_ENTRIES_LOG2, else the caller's fallback -- the same knobs the
|
|
88
|
+
C writers honour, so one environment sizes every ring in a capture."""
|
|
89
|
+
key = "".join(c.upper() if c.isalnum() else "_" for c in role)
|
|
90
|
+
for var in (f"LATREC_ENTRIES_LOG2_{key}", "LATREC_ENTRIES_LOG2"):
|
|
91
|
+
v = os.environ.get(var)
|
|
92
|
+
if v:
|
|
93
|
+
try:
|
|
94
|
+
n = int(v)
|
|
95
|
+
except ValueError:
|
|
96
|
+
continue
|
|
97
|
+
if 12 <= n <= 28:
|
|
98
|
+
return n
|
|
99
|
+
return fallback
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
_counter = 0
|
|
103
|
+
_counter_lock = threading.Lock()
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def seq_next() -> int:
|
|
107
|
+
"""Next value of the process-wide sequence counter (starts at 1)."""
|
|
108
|
+
global _counter
|
|
109
|
+
with _counter_lock:
|
|
110
|
+
_counter += 1
|
|
111
|
+
return _counter
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
_ctx = threading.local()
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def ctx_set(seq: int) -> None:
|
|
118
|
+
"""Bind ``seq`` to the current thread, so a later stage on the same
|
|
119
|
+
synchronous call chain can pick it up without an explicit parameter --
|
|
120
|
+
the same role libe3's ``latrec_ctx_set()`` / flexric's
|
|
121
|
+
``fx_latrec_ctx_set()`` play in C."""
|
|
122
|
+
_ctx.seq = seq
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def ctx_get() -> int:
|
|
126
|
+
"""The seq last bound on this thread via ``ctx_set()``, or 0 if none."""
|
|
127
|
+
return getattr(_ctx, "seq", 0)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
class LatRec:
|
|
131
|
+
"""One ring per instance. A writer may stamp from a couple of threads, so
|
|
132
|
+
a lock guards the index bump; each record still has exactly one writer,
|
|
133
|
+
and t_ns is stored last so a reader never sees a half-written record."""
|
|
134
|
+
|
|
135
|
+
def __init__(self, name: str, entries_log2: int = 18, role: str = None):
|
|
136
|
+
self.enabled = False
|
|
137
|
+
self._mm = None
|
|
138
|
+
d = os.environ.get("LATREC_DIR")
|
|
139
|
+
if not d:
|
|
140
|
+
return
|
|
141
|
+
os.makedirs(d, exist_ok=True)
|
|
142
|
+
# Sized by role, named <role>.<tid>: a key derived from the full name
|
|
143
|
+
# would carry a thread id no one can predict, so it could never be set.
|
|
144
|
+
entries = 1 << _entries_log2(role or name, entries_log2)
|
|
145
|
+
length = HDR_LEN + entries * _REC_SIZE
|
|
146
|
+
path = os.path.join(d, f"{name}.latrec")
|
|
147
|
+
# Built under a temporary name and renamed once the header is written:
|
|
148
|
+
# rename() is atomic, so a <name>.latrec always carries a valid header.
|
|
149
|
+
tmp = path + ".part"
|
|
150
|
+
fd = os.open(tmp, os.O_CREAT | os.O_RDWR | os.O_TRUNC, 0o644)
|
|
151
|
+
try:
|
|
152
|
+
os.ftruncate(fd, length)
|
|
153
|
+
self._mm = mmap.mmap(fd, length)
|
|
154
|
+
finally:
|
|
155
|
+
os.close(fd)
|
|
156
|
+
self._mm[:HDR_LEN] = b"\x00" * HDR_LEN
|
|
157
|
+
now_m, now_r = _mono_ns(), _real_ns()
|
|
158
|
+
_HDR.pack_into(self._mm, 0, MAGIC, VERSION, entries, 0,
|
|
159
|
+
now_m, now_r, name.encode()[:63])
|
|
160
|
+
_HDR_V2.pack_into(self._mm, _V2_OFF, _REC_SIZE, measure_clock_ns(),
|
|
161
|
+
now_m, now_r)
|
|
162
|
+
os.rename(tmp, path)
|
|
163
|
+
self._mask = entries - 1
|
|
164
|
+
self._idx = 0
|
|
165
|
+
self._lock = threading.Lock()
|
|
166
|
+
self.enabled = True
|
|
167
|
+
|
|
168
|
+
def stamp(self, seq: int, stage: int, aux: int = 0, aux2: int = 0) -> None:
|
|
169
|
+
if not self.enabled:
|
|
170
|
+
return
|
|
171
|
+
sc = (seq & 0x0000FFFFFFFFFFFF) | ((stage & 0xFF) << 56)
|
|
172
|
+
with self._lock:
|
|
173
|
+
off = HDR_LEN + (self._idx & self._mask) * _REC_SIZE
|
|
174
|
+
self._idx += 1
|
|
175
|
+
mm = self._mm
|
|
176
|
+
struct.pack_into("<Q", mm, off + 0, sc)
|
|
177
|
+
struct.pack_into("<Q", mm, off + 16, aux & 0xFFFFFFFFFFFFFFFF)
|
|
178
|
+
struct.pack_into("<Q", mm, off + 24, aux2 & 0xFFFFFFFFFFFFFFFF)
|
|
179
|
+
struct.pack_into("<Q", mm, off + 8, _mono_ns()) # last -> marks valid
|
|
180
|
+
|
|
181
|
+
def heartbeat(self) -> None:
|
|
182
|
+
"""Publish the write count and a fresh clock pair. Records are valid
|
|
183
|
+
without this (t_ns != 0); it fills in what a reader needs to tell a
|
|
184
|
+
wrapped ring from a partly filled one."""
|
|
185
|
+
if not self.enabled or self._mm is None:
|
|
186
|
+
return
|
|
187
|
+
struct.pack_into("<Q", self._mm, 16, self._idx) # rec_count
|
|
188
|
+
struct.pack_into("<QQ", self._mm, _V2_OFF + 8, _mono_ns(), _real_ns())
|
|
189
|
+
|
|
190
|
+
def close(self) -> None:
|
|
191
|
+
if not self.enabled or self._mm is None:
|
|
192
|
+
return
|
|
193
|
+
self.heartbeat()
|
|
194
|
+
try:
|
|
195
|
+
self._mm.flush()
|
|
196
|
+
finally:
|
|
197
|
+
self._mm.close()
|
|
198
|
+
self._mm = None
|
|
199
|
+
self.enabled = False
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
_rings = {}
|
|
203
|
+
_rings_lock = threading.Lock()
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def ring(name: str, entries_log2: int = 18, role: str = None) -> "LatRec":
|
|
207
|
+
"""Get-or-create a process-wide named ring (e.g. ``xdevsm.12345``)."""
|
|
208
|
+
with _rings_lock:
|
|
209
|
+
r = _rings.get(name)
|
|
210
|
+
if r is None:
|
|
211
|
+
r = LatRec(name, entries_log2, role)
|
|
212
|
+
_rings[name] = r
|
|
213
|
+
return r
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
_DISABLED = LatRec.__new__(LatRec)
|
|
217
|
+
_DISABLED.enabled = False
|
|
218
|
+
_DISABLED._mm = None
|
|
219
|
+
|
|
220
|
+
_tls = threading.local()
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def tls_ring(role: str, entries_log2: int = 18) -> "LatRec":
|
|
224
|
+
"""This thread's ring for ``role``, named ``<role>.<tid>`` as libe3 does.
|
|
225
|
+
|
|
226
|
+
The per-thread cache keeps a stamp site off the process-wide ring lock,
|
|
227
|
+
and the LATREC_DIR check keeps it off everything else when tracing is off.
|
|
228
|
+
"""
|
|
229
|
+
if _DIR is None:
|
|
230
|
+
return _DISABLED
|
|
231
|
+
r = getattr(_tls, "ring", None)
|
|
232
|
+
if r is None:
|
|
233
|
+
r = ring(f"{role}.{threading.get_ident()}", entries_log2, role)
|
|
234
|
+
_tls.ring = r
|
|
235
|
+
return r
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def flush_rings() -> None:
|
|
239
|
+
"""Refresh rec_count and the closing clock pair on every open ring.
|
|
240
|
+
|
|
241
|
+
Without this a reader sees rec_count == 0 and cannot tell a wrapped ring
|
|
242
|
+
from a partly filled one, nor fit mono->real across the run. Idempotent,
|
|
243
|
+
so a shutdown path and the atexit hook can both call it.
|
|
244
|
+
"""
|
|
245
|
+
with _rings_lock:
|
|
246
|
+
for r in _rings.values():
|
|
247
|
+
r.heartbeat()
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
atexit.register(flush_rings)
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def _heartbeat_loop(interval: float) -> None:
|
|
254
|
+
while True:
|
|
255
|
+
time.sleep(interval)
|
|
256
|
+
flush_rings()
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def start_heartbeat(interval: float = 1.0) -> None:
|
|
260
|
+
"""Publish rec_count periodically, so a ring survives a SIGKILL with its
|
|
261
|
+
write count intact. No-op when tracing is off; safe to call more than once.
|
|
262
|
+
"""
|
|
263
|
+
if _DIR is None or getattr(start_heartbeat, "_started", False):
|
|
264
|
+
return
|
|
265
|
+
start_heartbeat._started = True
|
|
266
|
+
threading.Thread(target=_heartbeat_loop, args=(interval,),
|
|
267
|
+
name="latrec-heartbeat", daemon=True).start()
|