docs: replace the E3SM-L1-KPM specification with the draft of version 2 by aferaudo · Pull Request #134 · wineslab/libe3

aferaudo · 2026-11-03T03:07:08Z

Summary

Replaces the E3SM-L1-KPM specification in docs/e3sm/l1-kpm/ (four telemetry identifiers) with a draft for the uplink layer 1. It keeps RAN function 2 and version 1, since no version of the service model has been released yet. The Word edition is O-RAN.XXX.TS.E3SM-L1-KPM-R000-v00.01.docx. A dApp that works on the uplink layer 1 also needs the PUSCH and SRS data of each slot. The draft defines:
- 79 PUSCH and SRS telemetry identifiers, plus validSymbolMask (ID 1000);
- slot, cell and UE scopes;
- a timestamp (ID 4) on the monotonic clock of the E3 Agent host, as for every payload that points into shared memory, while ID 78 gives the time of the slot in TAI;
- cell and UE selection through control identifier 1;
- a normative shared memory region (Annex A);
- the ASN.1 (APER) grammar and the JSON form;
- size limits, and a rule to split an oversized indication;
- a complete APER and JSON exchange (Annex B);
- the open items (Annex C).
The draft follows the clause layout of the E2 service models. The text of the earlier chapters 01 to 06 is folded into its clauses, and Annex C lists where existing E3 Agents differ from the draft. The integrator guide stays, and its links point to the clauses and Annex C items of the draft.
tools/oran_docx now:
- builds in a container (tools/oran_docx/Dockerfile), so the contents have page numbers on every host;
- embeds Markdown images as numbered figures;
- boxes code blocks in the PL style;
- leaves HTML anchors out;
- names O-RAN Work Group X, Real-Time Distributed Applications (dApps), on the cover and in the Foreword (DEFAULT_GROUP, applied by make_template.py). The optional group field of docx.json names another work group: E2SM-DAPP, an E2 service model, keeps O-RAN Work Group 3, Near-Real-time RAN Intelligent Controller.
All four Word editions are numbered O-RAN.XXX.TS.*, where XXX holds the place of the group name until the naming is agreed.
Names NVIDIA and Northeastern University in the change history of E3SM-L1-KPM. Updates the L1-KPM row of docs/e3sm/README.md and the link text in the Spectrum specification. Adds the PNG figure to REUSE.toml.

The PR is one commit, 1cb9182, co-authored by Thecave3.

Type of change

Linked issue

No issue yet: this is a draft for discussion. Related issues:

[Interop]: RAN function ids collide, and a function entry does not say which schema it uses #87: RAN function identifiers, and which schema a function entry uses. The earlier text and the draft both use RAN function 2.
[Interop]: OCUDU's E3AP has optional fields that libe3's lacks: bulk data by reference, service-model subscription data and instance identifiers #112: service model subscription data in E3AP. Today the spec uses control identifier 1 for it.
[Interop]: libe3 limits an E3AP payload to 32 KiB and OCUDU fragments up to 16 MiB and negotiates the limit in Setup #110: payload size and fragmentation. The spec splits an indication instead.
[Interop]: Granted periodicity in the subscription response needs one definition across libe3, OCUDU and Aerial #119: the meaning of granted values.

Twin-repo coordination

libe3 is paired with dapps and dApp-openairinterface5g. We do not accept patches that break or reduce compatibility with the twin repositories.

This PR does not change the E3 wire protocol or public ABI, OR a paired PR exists in each affected twin repo (link below).
This PR does not change the wire format or a behavior a peer (OAI, Aerial, OCUDU) can observe, OR I added a row to the change ledger in docs/interop.md.

Paired PR(s): none. This is a specification only, with no code. An implementation of the draft will need paired PRs.

Checks run

All on the tree of 1cb9182:

I checked the grammar against the tables of clauses 7 and 8 (80 identifiers).
I ran the worst cases through APER in both directions with asn1tools, including the out-of-range values the codec has to refuse.
Annex B is the output of the generator, at version 1 and with a monotonic ID 4, against main's messages/asn1/V1/e3ap-1.0.0.asn1.
The four Word editions are built in the container of tools/oran_docx/Dockerfile.
- All four pass OOXML schema validation against tools/oran_docx/template.docx.
- A rebuild of the E2SM-DAPP edition gives the text of the committed file, apart from the spaces around the line break of the cover.
- The L1-KPM PDF (LibreOffice, 54 pages) shows Figure 5-1 and a table of contents with page numbers.
- They have not been opened in Microsoft Word.
reuse lint passes, and a strict Doxygen build (LIBE3_DOCS_STRICT=ON, Doxygen 1.9.8, Ubuntu 24.04, same options as docs.yml) shows 0 warnings in the changed files. Both ran locally in a container.
scripts/check_commit_trailers.py --base origin/main --head HEAD passes.

Open points for review

Copyright. tools/oran_docx/template.docx still gives every Word edition the O-RAN ALLIANCE copyright page and footers, and its Modal verbs clause speaks of O-RAN deliverables. Should both go?
Clause layout. The draft follows the E2 service models (clauses 5 to 9 and annexes). CONTRIBUTING.md and docs/e3sm/README.md still describe the six chapters of the other E3 specifications. A separate PR can align them and move E3AP, Spectrum and E2SM-DAPP to the same layout.

🤖 Generated with Claude Code

github-actions · 2026-11-03T03:13:14Z

CI report — `1cb9182` — ✅ all checks passed

Workflow	Result	Time	Run
Commit policy	✅ success (steps skipped — no code changes)	0m19s	#220
Docs	✅ success	0m26s	#25
Build libe3py wheels	⏭️ not started (no changed file matches its `paths` filter)	—	—
E2E dApp Integration	⏭️ not started (no changed file matches its `paths` filter)	—	—
E2E Topologies (multi-dApp / multi-RAN)	⏭️ not started (no changed file matches its `paths` filter)	—	—
Full-loop Latency Benchmark	⏭️ not started (no changed file matches its `paths` filter)	—	—
latrec portability	⏭️ not started (no changed file matches its `paths` filter)	—	—
MPMC Queue Benchmark	⏭️ not started (no changed file matches its `paths` filter)	—	—
Unit Tests	⏭️ not started (no changed file matches its `paths` filter)	—	—

Docs

Doxygen warnings

0 warning(s) in the files this pull request changes, which fail the check; 403 more elsewhere, which do not. The full list is in the job log and the doxygen-warnings artifact of the Docs workflow.

Gaps in files this pull request does not change, by file:

Warnings	File
53	`include/libe3/types.hpp`
37	`include/libe3/sm_interface.hpp`
35	`include/libe3/e3_connector.hpp`
34	`include/libe3/e3_agent.hpp`
32	`include/libe3/e3_interface.hpp`
29	`include/libe3/c_api.h`
19	`src/c_api.cpp`
17	`include/libe3/logger.hpp`
17	`swig/libe3_swig.hpp`
17	`swig/e3_dapp_session.hpp`

Ready to merge (fast-forward only)

A maintainer can land the reviewed commits with:

git fetch origin
git checkout main && git merge --ff-only 1cb9182344b6984c691e3baf8e8ad2f676a6b6f7 && git push origin main

Head: 1cb9182344b6984c691e3baf8e8ad2f676a6b6f7 (branch docs/e3sm-l1-kpm-v2). If --ff-only fails as non-fast-forward, the branch must be rebased on the latest main.

One comment per PR, rewritten in place once every workflow for 1cb9182 finished.

Thecave3

Not exhaustive review.

I think we need to agree on the common structure as otherwise this will drift. Each SM in O-RAN usually have the previous skeleton and I'd like to have the current one integrated with these changes rather than completely removed.

Thecave3 · 2026-11-04T16:05:09Z

+    {"clause": "B", "title": "Example message exchange", "file": "annex-b-examples.md", "informative": true},
+    {"clause": "C", "title": "Open items", "file": "annex-c-open-items.md", "informative": true}
  ],
-  "history": [["2026-11", "R000 v00.01", "First version", "Northeastern University"]]


Done. The change history names Northeastern University again.

Thecave3 · 2026-11-04T16:05:55Z

@@ -1,18 +1,24 @@
 {
-  "number": "O-RAN.WG3.TS.E3SM-L1KPM-R000-v00.01",


This naming should be agreed across all the docs. I'd keep it as provvisory

All four editions are now O-RAN.XXX.TS.*: E3AP, E2SM-DAPP, Spectrum and O-RAN.XXX.TS.E3SM-L1KPM-R000-v00.01. XXX stands in for the group until we agree on the naming. CONTRIBUTING and the tool's README say so.

Thecave3 · 2026-11-04T16:06:49Z

Why this has been completely removed? Can be amended and included?

The content of 01 to 06 is folded into the clauses of the draft, and the clause layout stays as it is. Text that the draft already states is left alone. Details that fit the draft are added where they belong: 6.5, 6.6.1, 6.6.3, 7.3.5, 8.7.1, 9, A.1, A.4 and A.6.1. Where the existing E3 Agents do something else, Annex C says so. Items C.3, C.4, C.8, C.9, C.13, C.14 and C.16 take the earlier findings on their topic, C.17 to C.27 are new, and C.5 keeps the old Protocol Buffers messages.

Thecave3 · 2026-11-04T16:07:30Z

The general part should be a different one

5.1 now introduces the two services, telemetry and control, as the E2 service models do. The table of E3AP procedures is now Table 4-1 in 4.3 "Relation to E3AP".

Thecave3 · 2026-11-04T16:11:38Z

 |---|---|---|---|---|
 | E3SM Spectrum | 1 | Sensing telemetry, PRB blacklist control, sensing policy control, dApp reports and xApp controls for spectrum sharing | [spectrum/](spectrum/README.md) | `O-RAN.WG3.TS.E3SM-SPEC-R000-v00.01.docx` |
-| E3SM L1-KPM | 2 | Telemetry from the physical layer: a reference to the IQ samples of each uplink slot | [l1-kpm/](l1-kpm/README.md) | `O-RAN.WG3.TS.E3SM-L1KPM-R000-v00.01.docx` |
+| E3SM L1-KPM (draft) | 2 | Telemetry from the uplink layer 1: the PUSCH and SRS data of each uplink slot (79 telemetry identifiers and the valid symbol mask), selection of cells and UEs, and a shared memory layout for the large arrays | [l1-kpm/](l1-kpm/README.md) | `E3SM-L1-KPM-R000-v00.01.docx` |


Do not change versions

The service model is version 1 everywhere: 4.4, 7.2, 8.2.2.1, the grammar comment, 8.6.3 and Annex B. In Annex B step 2, both dumps were re-encoded with asn1tools, and only the version octet changes. The paragraph on versions 1 and 2 is gone from docs/e3sm/README.md.

aferaudo · 2026-11-04T20:13:25Z

edc03fb rebuilds the Word edition with tools/oran_docx/build_docx.py docs/e3sm/l1-kpm alone, so anyone can now rebuild it from the repository. The text of every clause is the same as before. Problems with the builder and the template that this shows:

Figures are not supported. build_docx.py has no image support. Figure 5-1 of clause 5.4 (figures/message-flow.png) comes out as the plain line "!Message flow of E3SM-L1-KPM over E3AP", with no image and no "Figure 5-1" caption. The template has the figure styles (TH, TF), but the builder does not use them.
The WG3 front matter should be deleted. The template names O-RAN WG3 in three places:
- the cover: "Technical Specification" and "O-RAN Work Group 3 Near-Real-time RAN Intelligent Controller";
- the Foreword: "This Technical Specification (TS) has been produced by WG3 of the O-RAN ALLIANCE";
- the Modal verbs clause: "NOT allowed in O-RAN deliverables".
These specifications are not O-RAN deliverables.
The O-RAN ALLIANCE copyright is still there. The copyright page and both footers ("O-RAN ALLIANCE e.V. Your use is subject to the copyright statement on the cover page of this specification.") come from the template. This is open point 4.
The file names still carry WG3. CONTRIBUTING.md (step 1) and tools/oran_docx/README.md ask for O-RAN.WG3.TS.*.docx. The E3AP, E2SM-DAPP and Spectrum editions use that name and number. Deleting WG3 means renaming those three files as well.
Code blocks do not use the template's code style. ASN.1, JSON and hexadecimal dumps are written as plain 8 pt Courier New lines, without the template's PL style and without shading or a border. In Word they are hard to tell apart from the text around them.
Page numbers need LibreOffice. Without soffice and pdftotext on the build host, the table of contents has no page numbers. Word fills them in when you select the table and press F9. The edition in edc03fb has none.
Two statements in the description no longer hold. Under "Checks run", the sentence "Its PDF text contains no working group name" was true of the previous edition only. Open point 1 is now settled the other way round: the edition is the builder's output, with items 1 and 2 above.

Thecave3 · 2026-11-05T02:29:48Z

@aferaudo, on your comment about the Word builder (edc03fb rebuilds the Word edition with tools/oran_docx/build_docx.py docs/e3sm/l1-kpm alone …):

Thanks for the list. In the order of your points:

Figures: an image on a line of its own is now a picture with a "Figure 5-1: …" caption, in the TH and TF styles, numbered per clause like the tables. PNG and JPEG work.
and 3. The O-RAN front matter and copyright stay for now.
The file names are now O-RAN.XXX.TS.* (see the thread on docx.json).
Code blocks use the PL style, inside one shaded and bordered box.
tools/oran_docx/Dockerfile builds with LibreOffice, so every table of contents has page numbers. Built in it, the E3AP edition comes out byte for byte as committed. CONTRIBUTING step 4 now uses it.
The PR description predates these commits. The status comment on this PR says where it no longer holds.

The builder also printed the <a id="…"></a> lines of E2SM-DAPP as text, and now leaves them out. All four editions were rebuilt.

Thecave3 · 2026-11-05T02:29:49Z

Status of this PR

The branch is rebased on main (53fd479). On top of Angelo's four commits, which are unchanged, there are eleven new ones.

Word builder (tools/oran_docx, five commits): these cover Angelo's list.
- A container build, so every table of contents has page numbers.
- HTML anchors left out of the Word text.
- Figures with numbered captions.
- Code blocks in the PL style, in one box.
- The four Word editions renumbered O-RAN.XXX.TS.* and rebuilt.
Specification (six commits):
- The earlier chapters are folded into the clauses of the draft. Annex C, items C.17 to C.27, lists where the existing E3 Agents differ.
- The service model stays at version 1.
- Northeastern University is back in the change history.
- Clause 5.1 introduces the services, and the E3AP procedure table is now Table 4-1 in 4.3.
- The integrator guide points to the new clauses and items.
- A check of the 267 paragraphs, list items and table rows of the earlier chapters against the draft found a few missing details, which are now added.

The description above predates these commits. Where they differ, this comment applies:

The specification is version 1, not version 2, and the earlier chapters are folded in rather than replaced.
The Word edition is the output of build_docx.py, built in the container. Open point 1 of the description is settled, and the edition has Figure 5-1.
The edition keeps the O-RAN front matter, so "Its PDF text contains no working group name" no longer holds.
Annex B step 2 was re-encoded with asn1tools for version 1. Only the version octet changed, and the other steps are as described.

Checks run locally: Docs (0 Doxygen warnings in the changed files), REUSE, and the commit trailer policy all pass, and every relative link under docs/ resolves. CI will run on this push.

Still open:

Clause layout. L1-KPM follows the layout of the E2 service models. We still need to agree on one structure for all the service models.
Clock of timestamp (C.8). The draft says realtime UTC. The existing E3 Agents and docs/e3sm/README.md say monotonic.
Front matter. The cover, Foreword and copyright stay those of the O-RAN template for now.
Implementations. The existing E3 Agents implement the earlier form (C.18, C.25, C.27). Moving them to the draft needs paired PRs in the twin repositories.
Mermaid diagrams. In the E3AP and E2SM-DAPP Word editions they are still a placeholder line.

@aferaudo, please review the folded text, mainly Annex C, and the L1-KPM Word edition. Once points 1 to 3 are settled, the PR can land as a fast-forward merge.

…nk layer 1 The E3SM-L1-KPM specification in docs/e3sm/l1-kpm had four telemetry identifiers: a reference to the IQ samples of each uplink slot, the time, the frame and the slot. A dApp that works on the uplink layer 1 also needs the PUSCH and SRS data that the receiver produces for each slot. The folder now holds a draft that defines all of it for RAN function 2. The service model stays at version 1, since no version of it has been released. * 79 telemetry identifiers on a PUSCH path and an SRS path, and the valid symbol mask (ID 1000). IDs 80 to 999 are reserved. * Each value has a slot, cell or UE scope. An indication carries the cells and the UEs that have data in the slot. * The timestamp (ID 4) is on the monotonic clock of the E3 Agent host, as docs/e3sm/README.md asks of a payload that points into shared memory. ID 78 gives the time of the slot in TAI, and the E3AP timestamps stay on the realtime clock. * Six large arrays stay in a shared memory region and the indication refers to them. Annex A (normative) fixes the region: a 200 octet header, ping-pong buffers and the row formats. * Control identifier 1 selects cells and UEs, because the E3AP SUBSCRIPTION REQUEST has no field for the service model. * The information elements have an ASN.1 grammar for APER and a JSON form, with size limits and a rule to split an indication that exceeds them. * Annex B is a complete exchange in APER and JSON. Annex C lists the open items. The clause layout follows the E2 service models: services, RAN function description, elements, error handling and annexes. The E3AP procedure table is in clause 4.3. The text of the earlier chapters is folded into these clauses. Where the existing E3 Agents differ from the draft, Annex C says so, and clause C.5 keeps their Protocol Buffers messages. The integrator guide stays. It points at the clauses and items of the draft, and its code notes N.1 to N.9 hold the findings about the code only. tools/oran_docx builds every Word edition the same way: * A Dockerfile (Ubuntu 24.04, LibreOffice, pdftotext, the Liberation fonts) gives the table of contents its page numbers on every host. CONTRIBUTING.md builds in it. * Markdown images become numbered figures, code blocks are boxed in the PL style, and lines that hold only HTML anchors are left out. * The template names O-RAN Work Group X, Real-Time Distributed Applications (dApps), on the cover and in the Foreword: the DEFAULT_GROUP of build_docx.py, which make_template.py applies. The optional docx.json field group names another work group. E2SM-DAPP is an E2 service model and keeps O-RAN Work Group 3, Near-Real-time RAN Intelligent Controller. The four Word editions are numbered O-RAN.XXX.TS.*, where XXX holds the place of the group until the naming is agreed, and E3SM-L1-KPM is O-RAN.XXX.TS.E3SM-L1-KPM-R000-v00.01. All four are built in the container. The change history of E3SM-L1-KPM names NVIDIA and Northeastern University. docs/e3sm/README.md and the link from the Spectrum specification use the name E3SM-L1-KPM, and REUSE.toml covers the PNG figure. Co-authored-by: Thecave3 <thecave003@gmail.com> Signed-off-by: Thecave3 <thecave003@gmail.com> Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

aferaudo added the asn1 ASN.1 (APER) encoding label Nov 3, 2026

aferaudo force-pushed the docs/e3sm-l1-kpm-v2 branch from 065fc44 to af188c2 Compare November 3, 2026 03:19

aferaudo changed the title ~~docs: add the draft E3SM-L1-KPM version 2 specification~~ docs: replace the E3SM-L1-KPM specification with the draft of version 2 Nov 3, 2026

Thecave3 mentioned this pull request Nov 3, 2026

ci: treat tools/e3sm_l1kpm_v2/ as documentation tooling in the code-change gate #135

Merged

aferaudo mentioned this pull request Nov 4, 2026

[Feature]: Generate a service model's JSON code from its ASN.1 grammar (JER in libe3's asn1c build) #137

Open

aferaudo force-pushed the docs/e3sm-l1-kpm-v2 branch from a0af9f5 to a39bc6c Compare November 4, 2026 15:09

aferaudo marked this pull request as ready for review November 4, 2026 15:19

aferaudo requested a review from Thecave3 as a code owner November 4, 2026 15:19

Thecave3 requested changes Nov 4, 2026

View reviewed changes

Thecave3 reviewed Nov 4, 2026

View reviewed changes

Thecave3 force-pushed the docs/e3sm-l1-kpm-v2 branch from c86e31c to 80dc37d Compare November 5, 2026 02:29

aferaudo force-pushed the docs/e3sm-l1-kpm-v2 branch from 2b622b7 to b31f650 Compare November 5, 2026 19:14

aferaudo force-pushed the docs/e3sm-l1-kpm-v2 branch from b31f650 to 1cb9182 Compare November 5, 2026 19:17

Thecave3 approved these changes Nov 5, 2026

View reviewed changes

Thecave3 merged commit 1cb9182 into main Nov 5, 2026
7 checks passed

Thecave3 deleted the docs/e3sm-l1-kpm-v2 branch November 5, 2026 19:26

		@@ -1,18 +1,24 @@
		{
		"number": "O-RAN.WG3.TS.E3SM-L1KPM-R000-v00.01",

Conversation

aferaudo commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of change

Linked issue

Twin-repo coordination

Checks run

Open points for review

Uh oh!

github-actions Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI report — 1cb9182 — ✅ all checks passed

Doxygen warnings

Ready to merge (fast-forward only)

Uh oh!

Thecave3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aferaudo commented Nov 4, 2026

Uh oh!

Thecave3 commented Nov 5, 2026

Uh oh!

Thecave3 commented Nov 5, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aferaudo commented Nov 3, 2026 •

edited

Loading

github-actions Bot commented Nov 3, 2026 •

edited

Loading

CI report — `1cb9182` — ✅ all checks passed