Implementation of the E3 Agent for dApps and E3AP (no service models) (#204)
These changes introduce an E3 Agent for dApps in the OAI codebase. dApps
are real-time microservices designed to operate within the O-RAN
ecosystem, enabling sub-10 ms Artificial Intelligence (AI) routines in
the Radio Access Network (RAN).
The E3 Agent enables spectrum sensing, frequency-domain signal logging,
and dynamic PRB (Physical Resource Block) policies through IPC/ZMQ
communication with dApps or xApps.
The dApps are designed for co-location with the CU/DU, where it can
interact directly with user-plane data to enable different network
management scenarios such as optimizing network slicing, scheduling, and
resource management. A python library for the creation of the dApps is
available here [1].
Additional information about dApps:
- Paper on the dApp architecture [2]
- dApp framework presentation [3]
- Tutorial on dApp deployment on OAI [4]
As agreed in the original MR [5], this PR includes only the agent lifecycle,
configuration parsing, build plumbing, and the nr-softmodem init/destroy
hook.
It registers zero service models, so it builds and runs as an idle
agent. Concrete service models (e.g. spectrum sensing) and the PHY/MAC
hooks that drive them follow in later PRs.
Opt-in and dependencies
- Gated behind the E3_AGENT CMake option (OFF by default) / the
--build-e3 build flag. The default build is unaffected — e3ap is only
compiled and linked into nr-softmodem when E3_AGENT=ON.
- When enabled, requires the external libe3 library [6] (vendor-neutral
E3AP C++ lib), discovered via pkg_check_modules(CLIBE3 REQUIRED
libe3). It is not vendored.
Install libe3 (Debian/Ubuntu):
git clone https://github.com/wineslab/libe3 && cd libe3
./build_libe3 -I # installs deps: build-essential cmake pkg-config libzmq3-dev asn1c nlohmann-json3-dev libsctp-dev ...
./build_libe3 --install # release build + installation
Build & test
Tested in RFsim: the gNB initializes the E3 agent, opens its setup
socket (/tmp/dapps/setup), registers zero service models, and runs
without crashing. Configuration
The agent reads an optional E3Configuration section from the gNB config
file (parsed only when E3_AGENT=ON). If absent, it falls back to
built-in defaults (posix/ipc).
E3Configuration : {
link = "zmq"; # posix | zmq
transport = "ipc"; # tcp | sctp | ipc
};
The same parameters can be overridden on the command line (no
config-file edit required):
sudo ./nr-softmodem -O <gnb.conf> ... --E3Configuration.link zmq --E3Configuration.transport ipc
Validated link/transport combinations: (zmq,ipc) (zmq,tcp) (posix,tcp)
(posix,sctp) (posix,ipc).
Notes
- I have added a new log component E3AP specific for the ops performed
by the E3 Agent.
- This PR ships no gNB config file; the E3Configuration block / CLI
override above is the documented way to enable the agent. Example
configs follow in the next PRs.
[1] https://pypi.org/project/dapps/
[2] https://arxiv.org/pdf/2501.16502
[3] https://openrangym.com/o-ran-frameworks/dapps
[4] https://openrangym.com/tutorials/dapps-oai
[5] https://gitlab.eurecom.fr/oai/openairinterface5g/-/merge_requests/3361
[6] https://github.com/wineslab/libe3
Reviewed-by: Teodora Vladić <teodora.vladic@openairinterface.org>
Reviewed-by: Sagar Arora <sagar.arora@openairinterface.org>
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Introduce the E3_AGENT CMake option (default OFF) and the matching
--build-e3 flag in build_oai so the E3 agent for O-RAN dApps can be
compiled opt-in. Gate the E3AP subdirectory and the nr-softmodem
linkage behind the option, and register an E3AP log component
together with its legacy T-tracer message IDs.
The E3 interface (nGRG) lets the gNB exchange real-time reports and
controls with external dApps. Keeping it behind a build flag leaves
the default CI build unchanged and avoids pulling in the external
libe3 dependency unless the agent is explicitly requested.
Signed-off-by: Andrea Lacava <thecave003@gmail.com>
- make internal links relative where applicable
- delete link to the wiki, as the documentation is in the main repo, not
the wiki
- remove some "example in oai code" as the examples either don't exist,
or are not in that place, and we can reasonably expect people to grep
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Preparatory changes for LDPC CUDA integration
This changeset is preparatory work to merge LDPC CUDA offload in !4097.
Notably, it includes changes for cleaning up some defines, updates to
the LDPC interface, and CI specific changes to prepare for the other MR.
The goal is to merge changes in a first step such that, in a second
step, only the actual LDPC CUDA implementation and ancillary changes
(CUDA memory allocations, CI files, ...) need to be merged.
Reviewed-By: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
A later commit (for LDPC CUDA) will reuse add_physim_test(), but is in a
completely different location than the existing physim test definitions.
Hence, move it to global scope for later reuse.
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Use the current OAI CI default UHD version. Update the documentation to
show how to install a recent version.
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
The existing patch (generated through sed) works also in UHD versions
beyond 4.8, so allow to use that.
Further, since sed is confusing, store the patch directly. Update the
dockerfiles so that docker copies the right file for UHD 4.8.
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Also, for UHD install from packages, add the right version for both
Ubuntu 24 and Ubuntu 26: in U24, use the currently recommended 4.8, and
bump to latest in U26.
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
The CI does not use installation of UHD from package, hence this
mechanism is not needed (and should not be, anyway).
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
fix(nrLDPC_coding): Remove ldpc_xdma
Arguments for removing:
- There are no resources to maintain it. Including no machine with the
board.
- There is no clue that someone is actually using it.
- The library is not standard/cannot be generalized. It was designed for
a specific solution and cannot be used for another.
- The standard AAL (BBDev or other) should be privileged for LDPC offload
to a hardware accelerator.
ZMQ radio
This is a zmq radio implementation that attempts to integrate NR UE with
the ocudu project.
OAI integration status:
This can currently be used to connect OAI gnb and OAI UE.
Compilation:
cmake --build . --target nr-softmodem nr-uesoftmodem ldpc params_libconfig zmq_radio
Running
- gNB command:
sudo ./nr-softmodem -O ../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --gNBs.[0].min_rxtxtime 6 --device.name zmq_radio --zmq.[0].tx_channels tcp://127.0.0.1:4556 --zmq.[0].rx_channels tcp://127.0.0.1:4557
- UE command:
sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3619200000 --ssb 516 --device.name zmq_radio --zmq.[0].tx_channels tcp://127.0.0.1:4557 --zmq.[0].rx_channels tcp://127.0.0.1:4556
A new CI testcase for 2x2 configuration was added.
OCUDU integration status:
The OAI NR UE enters RRC Connected state.
For more details, please refer to the description of MR !3975.
Arguments for removing:
1. There are no resources to maintain it.
Including no machine with the board.
2. There is no clue that someone is actually using it.
3. AAL is privileged for LDPC offload to a hardware accelerator.
7.2 FHI with XRAN K release
Purpose:
Implement the O-RAN 7.2 Fronthaul interface using O-RAN Software Community's
XRAN release K. The new features of the release K can be leveraged and it is
compatible with DPDK version 24.11.4.
For more details please refer to the MR !3444 description.
* create the xran forked repo as a cmake external project - easier to maintain and track the changes
we applied to the original repo
* add xran_DOWNLOAD option - clones and builds latest supported K release
* update the FHI README for K release
Signed-off-by: Teodora Vladić <teodora.vladic@openairinterface.org>
Functionality existed to print all output of asn1c on error, but the
form
asn1c || cat X
makes the command exit with a 0 exit code (success). Fix by explicitly
returning non-zero exit code in this case:
asn1c || ( cat X && false )
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Both do practically the same. Harmonize them into one while guaranteeing
backwards compatibility.
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
This fixes two problem:
1. an omitted --build-lib library could yield strange grep errors. For
instance, calling build_oai --build-lib --cmake-opt OPTION passed
"--cmake-opt" to grep, that does not know this option. Handle by
explicitly separating options and search pattern through --.
2. Even with this fixed, set -e triggered an exit because grep exits
with non-zero error code. Remove set -e to have the error handling
code pass.
With set -e removed, properly check that the build passes.
Update a log line to make it clearer.
Assisted-by: Claude:claude-sonnet-4-6
Signed-off-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Extend UICC configuration parsing to provide: routing_indicator,
protection_scheme, home_network_public_key, and home_network_public_key_id.
Use the protection_scheme value to decide what SUCI Profile Scheme to
apply during SUCI generation. Add support for Profile Scheme A which
provides ECIES-based encryption using Curve25519 and X9.63 KDF as outlined
in TS 33.501 Section C.3.4.1 Profile A.
When a configuration file specifies an unsupported Profile Scheme,
the NAS layer triggers a fatal error. This occurs either because
Profile Scheme B is unimplemented or the build uses OpenSSL < 3.0,
which lacks Curve25519 and X9.63 KDF support, ensuring users are
informed of the incompatibility.
- all RAN code, CI code, configuration files, dockerfiles, in CSSL v1.0
- all deployment code (openshift, charts, ancillary files like shell
scripts), in MIT
- documentation in CC-BY-4.0
- exceptions might apply and are listed in NOTICE
- there is a new LICENSES folder with all licenses
- CONTRIBUTIONS.md has been updated accordingly
For automated changes based on OAI PL v1.1:
perl -i~ -0pe 's/\/\*.*Licensed to the OpenAirInterface.*openairinterface.org\n#?/\/*\n * SPDX-License-Identifier: LicenseRef-CSSL-1.0\n/s' **/*.{c,h,cpp}
perl -i~ -0pe 's/\/\*.*Licensed to the OpenAirInterface.*openairinterface.org\n#?/\/*\n * SPDX-License-Identifier: LicenseRef-CSSL-1.0\n/s' **/*.ts
perl -i~ -0pe 's/<!--.*Licensed to the OpenAirInterface.*openairinterface.org\n.*-->/<!-- SPDX-License-Identifier: LicenseRef-CSSL-1.0 -->/s' **/*.xml
The rest (cmake, files with missing license, cmake) manually.
Remove the \file directive, as it is always superfluous because the
current file is implicit [1]:
> If the file name is omitted (i.e. the line after \file is left blank)
> then the documentation block that contains the \file command will belong
> to the file it is located in.
Author names and e-mails are not relevant for us: it can always be
inferred from git blame, and is often outdated.
Eurecom code has been contributed and was under OAI PL v1.0/v1.1.
For the cpack package contact: put generic email address that is
independent of an individual and that will remain reachable.
[1] https://www.doxygen.nl/manual/commands.html#cmdfile
Remove old CUDA LDPC implementation
A new implementation is under way in !3955. To simplify the MR, remove the old
LDPC CUDA implementation in a first step.
* Option to build ldpc_cuda was remaining in the build script
* Build script option to build ldpc_cuda was still used in CI
* Mentions of ldpc_cuda were remaining in the documentation
Note: In the documentation, the example of ldpctest usage that was
loading ldpc_cuda was replaced by an example in which it is loading
ldpc_orig even though this is pointless as it makes ldpctest compare
ldpc_orig with ldpc_orig. On the other hand, it is the only library
other than the default ldpc that uses the former interface.
Remove OSD, some scripts, oaisim references
The README says:
It is just generating the XML file and it is placing it in
$(OPENAIR_TARGETS)/SIMU/EXAMPLE/OSD/WEBXML/ or http://localhost/xmlfile/
so that the oaisim could pars and run the simulation/emulation
oaisim does not exist anymore, and corresponding simulation cannot be done.
Also, it requires XAMPP and similar technologies, that I think nobody uses
in the context of OAI.
Remove also most references to oaisim.
Remove some scripts that are likely not used by anybody, or straight useless.
1. Remove modifications done in the following xran functions:
process_mbuf_batch();
xran_process_srs_sym().
=> not even used with OAI 7.2 interface.
2. Also, remove xran_fs_get_num_dl_sym_sp() and xran_fs_get_num_ul_sym_sp() introduced in the same MR.
3. Remove LiteOnIgnoreUPSectionIdEnable parameter. Instead, use RunSlotPrbMapBySymbolEnable in a simple way
for xran_process_rx_sym() function.
Explanation: The xran expects UL UP packets with the same section IDs as indicated per UL CP message.
However, the section IDs of received packets are 3 for mixed slot and 13 for UL slot.
Ubuntu 20 is EOL [1] unless people pay for support. Therefore, remove it
from build_helper. People can still use it, but might need to install a
more recent cmake version (which the next commit will upgrade). The rest
should be the same.
[1] https://ubuntu.com/about/release-cycle
Prior to this commit, constants NB_ANTENNAS_RX/TX are provided on the
command line to each compiler invocation. This has the drawback (1) that
also files that don't need that get the constants, and (2) it is not
easy to find them using ctags or similar, as the only definition is in
CMakeLists.txt (where it is not found).
In this commit, use cmake configure_file() to write a header file with
these constants. The file will be generated during cmake invocation, and
written to <build-dir>/common/cmake_defs.h. The relevant files that
need this definition will pick it from the header.
This has been used previously also in a commit to write git information.
See-also: 8bffd1666d ("Avoid complete rebuild on cmake run with git info change")
[FHI72] Remove support for xran E release
All the use cases we tested with E release are working end-to-end with F release.
The near future plan is to support K release which is ongoing in the MR !3444.
All the use cases we tested so far, are supported with xran F release.
Therefore, we can proceed with removing the support with E release.
In addition, our plan is to bring the support for K release which is ongoing activity in
the MR https://gitlab.eurecom.fr/oai/openairinterface5g/-/merge_requests/3444.
