xdevsm 0.1.1__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.
Files changed (101) hide show
  1. {xdevsm-0.1.1 → xdevsm-0.1.8}/PKG-INFO +123 -3
  2. {xdevsm-0.1.1 → xdevsm-0.1.8}/README.md +122 -2
  3. xdevsm-0.1.8/VERSION +1 -0
  4. {xdevsm-0.1.1 → xdevsm-0.1.8}/pyproject.toml +4 -1
  5. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/__init__.py +1 -0
  6. xdevsm-0.1.8/src/xdevsm/_latrec/stages.py +25 -0
  7. xdevsm-0.1.8/src/xdevsm/_latrec/writer.py +267 -0
  8. xdevsm-0.1.8/src/xdevsm/decorators/ccc/ccc_control.py +48 -0
  9. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/ccc/ccc_frame.py +9 -7
  10. xdevsm-0.1.8/src/xdevsm/decorators/ccc/ccc_rrm_policy_control.py +67 -0
  11. xdevsm-0.1.8/src/xdevsm/decorators/control.py +378 -0
  12. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/dApp/control/dapp_prb_mask_control.py +12 -2
  13. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/dApp/report/dapp_report.py +34 -25
  14. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/kpm/kpm_frame.py +11 -11
  15. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/no_op_dec.py +1 -1
  16. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_connected_mode_mobility.py +2 -2
  17. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_radio_bearer_control.py +2 -2
  18. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_radio_resource_alloc_control.py +2 -2
  19. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/rc/rc_report_frame.py +5 -3
  20. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/report.py +153 -42
  21. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/handlers/xDevSM_rmr_xapp.py +136 -33
  22. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/001-enable-indication-msg-free.patch +11 -0
  23. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/002-add-control-ack-decode.patch +128 -0
  24. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/003-add-control-failure-decode.patch +103 -0
  25. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/004-size-control-request-buffer.patch +18 -0
  26. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/README.md +99 -0
  27. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/__init__.py +16 -0
  28. xdevsm-0.1.8/src/xdevsm/ricxappframe_patches/__main__.py +103 -0
  29. xdevsm-0.1.8/src/xdevsm/sm_framework/lib/libdapp_sm.so +0 -0
  30. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libkpm_sm.so +0 -0
  31. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/library_wrapper.py +1 -1
  32. xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc/ccc_decoder.py +136 -0
  33. xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc/ccc_encoder.py +219 -0
  34. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/ccc/constants.py +12 -0
  35. xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlAck.py +102 -0
  36. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlHdr.py +5 -0
  37. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlOut.py +15 -1
  38. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlReq.py +15 -1
  39. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/e3/DAppE3CtrlPayload.py +10 -1
  40. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/e3/DAppE3IndPayload.py +29 -0
  41. xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/e3/SpectrumApplyOutcome.py +46 -0
  42. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppIndicationHdr.py +31 -0
  43. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmIndicationMsg.py +40 -40
  44. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/MeasData.py +22 -22
  45. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlReq.py +6 -9
  46. xdevsm-0.1.8/src/xdevsm/utils/__init__.py +0 -0
  47. xdevsm-0.1.8/src/xdevsm/utils/ack_route.py +170 -0
  48. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/utils/constants.py +3 -1
  49. xdevsm-0.1.8/src/xdevsm/utils/log_config.py +196 -0
  50. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/utils/utility.py +34 -7
  51. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/utils/xapp_sub.py +1 -1
  52. xdevsm-0.1.1/VERSION +0 -1
  53. xdevsm-0.1.1/src/xdevsm/decorators/control.py +0 -265
  54. xdevsm-0.1.1/src/xdevsm/sm_framework/lib/libdapp_sm.so +0 -0
  55. xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/ccc/ccc_decoder.py +0 -66
  56. xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/ccc/ccc_encoder.py +0 -84
  57. xdevsm-0.1.1/src/xdevsm/utils/lat_profile.py +0 -47
  58. {xdevsm-0.1.1 → xdevsm-0.1.8}/.gitignore +0 -0
  59. {xdevsm-0.1.1 → xdevsm-0.1.8}/LICENSE +0 -0
  60. {xdevsm-0.1.1/src/xdevsm/decorators → xdevsm-0.1.8/src/xdevsm/_latrec}/__init__.py +0 -0
  61. {xdevsm-0.1.1/src/xdevsm/decorators/ccc → xdevsm-0.1.8/src/xdevsm/decorators}/__init__.py +0 -0
  62. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/decorators/base.py +0 -0
  63. {xdevsm-0.1.1/src/xdevsm/decorators/dApp → xdevsm-0.1.8/src/xdevsm/decorators/ccc}/__init__.py +0 -0
  64. {xdevsm-0.1.1/src/xdevsm/decorators/dApp/control → xdevsm-0.1.8/src/xdevsm/decorators/dApp}/__init__.py +0 -0
  65. {xdevsm-0.1.1/src/xdevsm/decorators/dApp/report → xdevsm-0.1.8/src/xdevsm/decorators/dApp/control}/__init__.py +0 -0
  66. {xdevsm-0.1.1/src/xdevsm/decorators/kpm → xdevsm-0.1.8/src/xdevsm/decorators/dApp/report}/__init__.py +0 -0
  67. {xdevsm-0.1.1/src/xdevsm/decorators/rc → xdevsm-0.1.8/src/xdevsm/decorators/kpm}/__init__.py +0 -0
  68. {xdevsm-0.1.1/src/xdevsm/handlers → xdevsm-0.1.8/src/xdevsm/decorators/rc}/__init__.py +0 -0
  69. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/handlers/I_xDevSM_xapp.py +0 -0
  70. {xdevsm-0.1.1/src/xdevsm/sm_framework → xdevsm-0.1.8/src/xdevsm/handlers}/__init__.py +0 -0
  71. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/handlers/config.py +0 -0
  72. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/README.md +0 -0
  73. {xdevsm-0.1.1/src/xdevsm/sm_framework/lib → xdevsm-0.1.8/src/xdevsm/sm_framework}/__init__.py +0 -0
  74. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran → xdevsm-0.1.8/src/xdevsm/sm_framework/lib}/__init__.py +0 -0
  75. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libkpm_sm_2_01.so +0 -0
  76. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/librc_1_03.so +0 -0
  77. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/lib/libsm_framework.so +0 -0
  78. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/ByteArray.py +0 -0
  79. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/ccc → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran}/__init__.py +0 -0
  80. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/dapp → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/ccc}/__init__.py +0 -0
  81. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/dapp/control → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp}/__init__.py +0 -0
  82. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/control/DAppControlMsg.py +0 -0
  83. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/dapp/e3 → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/control}/__init__.py +0 -0
  84. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/dapp/report → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/e3}/__init__.py +0 -0
  85. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/enums.py +0 -0
  86. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppActionDef.py +0 -0
  87. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppEvTrigger.py +0 -0
  88. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppFunctionDef.py +0 -0
  89. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/dapp/report/DAppIndicationMsg.py +0 -0
  90. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/kpm → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/dapp/report}/__init__.py +0 -0
  91. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmFunctionDef.py +0 -0
  92. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/KpmIndicationHdr.py +0 -0
  93. {xdevsm-0.1.1/src/xdevsm/sm_framework/py_oran/rc → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/kpm}/__init__.py +0 -0
  94. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/enums.py +0 -0
  95. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/kpm/function_definition_builder.py +0 -0
  96. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlHdr.py +0 -0
  97. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCControlMsg.py +0 -0
  98. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/RCFunctionDef.py +0 -0
  99. {xdevsm-0.1.1/src/xdevsm/utils → xdevsm-0.1.8/src/xdevsm/sm_framework/py_oran/rc}/__init__.py +0 -0
  100. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/enums.py +0 -0
  101. {xdevsm-0.1.1 → xdevsm-0.1.8}/src/xdevsm/sm_framework/py_oran/rc/rc_report_codec.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: xdevsm
3
- Version: 0.1.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. Other Sources
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. Other Sources
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 = ["src/xdevsm/sm_framework/lib/*.so"]
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,7 @@ _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",
26
27
  "XappRcReportFrame": "xdevsm.decorators.rc.rc_report_frame:XappRcReportFrame",
27
28
  "RadioBearerControl": "xdevsm.decorators.rc.rc_radio_bearer_control:RadioBearerControl",
28
29
  "RadioResourceAllocationControl": "xdevsm.decorators.rc.rc_radio_resource_alloc_control:RadioResourceAllocationControl",
@@ -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()