doc: add a Git guide (commit signing, branch management, rerere) (#202)
Adds doc/git-guide.md, a single entry point for the practical Git
knowledge needed to contribute to OAI: commit signing setup (DCO +
verified commits), branch management (including fixup commits and
--autosquash), submodules, recovering from mistakes, and reusing
conflict resolutions with git rerere.
This started as a rerere-only guide. Review discussion (@luispereira106,
@rorsc, @sgarg00) converged on a broader scope: the Git how-tos are
scattered across the documentation (signing in CONTRIBUTING.md, branch
management in code-style-contrib.md), and configuring commit signing in
particular was reported as hard to get right. This PR consolidates the
how-tos in one guide while the policy documents stay authoritative for
the rules.
Single commit (review rounds squashed per the linear-history policy):
- New doc/git-guide.md with sections on commit signing (moved from
CONTRIBUTING.md, led by a copy-pasteable SSH recipe), branch
management (moved from code-style-contrib.md; git switch,
fixup/--autosquash, --fixup=amend:), submodules (unintended
pointer-update pitfall), recovering from mistakes
(restore/reset/reflog), and git rerere.
- CONTRIBUTING.md keeps the normative DCO/Verified requirements and
links to the guide; code-style-contrib.md keeps the workflow policy
and links to the guide; doc/README.md lists the guide under Developer
tools.
- Cross-references (not moved, since they are coupled to their own
docs): clang-format.md pre-commit hook, GET_SOURCES.md branch/tag
model, doc_best_practices.md docs: commit prefix.
- Small typo fix in the T tracer addconsoletrace.md documentation.
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Reviewed-by: Francesco Mani <email@francescomani.it>
Reviewed-by: Shubhika Garg <shubhika.garg@openairinterface.org>
O-RU first fix pass (#260)
Added several fixes requested in the original PR
- simplify code
- add example config files & test procedure
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
fix(zmq): speedup zmq radio (#149)
- Utilize ZMQ "zero-copy" inteface on TX
- Skip one memcpy in RX
- Use AVX-512 optimized cf_t <-> c16_t conversion loops in tx and rx
- Parallelize TX and RX polling threads for faster execution
Closes: #118
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Handle invalid input in nr_get_E (#281)
This PR prevents the function nr_get_E to crash with an assertion for
invalid input by handling the scenario with an error code
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
xran: fixes for FDD operation (#270)
Two fixes in the xran fronthaul found while bringing up an FDD cell
(Band n1, 10 MHz). Verified on a Band n1 FDD 10 MHz cell using Keysight
RUsim/UEsim, End-to-end UE attach and traffic work.
- Derive TTI from the configured numerology instead of a hardcoded 20
slots per frame: xran_fh_tx_send_slot() assumed 30 kHz SCS. Compute
slots_per_frame as 10 << mu from the fronthaul config (mu_number[0]
for K release, frame_conf.nNumerology for F release), so the TTI is
correct for any numerology. With the original code, PRACH was not
working properly.
- Fix DL transmission in FDD mode: the TDD DL/guard slot check skipped
every DL slot in FDD, where no TDD pattern exists and all slots carry
DL. The check is now only applied when the frame duplex type is not
FDD. Without this, no DL traffic was sent.
Reviewed-by: Teodora Vladić <teodora.vladic@openairinterface.org>
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Add doc/git-guide.md, a single entry point for the practical Git
knowledge needed to contribute to OAI, consolidating the how-tos
that were scattered across the documentation:
- Setting up commit signing: moved from CONTRIBUTING.md, which keeps
the normative DCO/Verified requirements and links to the guide; led
by a compact SSH recipe, with the allowed_signers troubleshooting
and a note on repository-level configuration for shared servers.
- Managing your own branch: moved from code-style-contrib.md, which
keeps the workflow policy and links to the guide; mentions git
switch and covers fixup commits with git rebase --autosquash,
including the --fixup=amend:<commit> variant.
- Working with submodules: the update command and the unintended
submodule-pointer-update pitfall seen in past PRs.
- Recovering from mistakes: git restore --staged, git restore,
git reset --soft/--hard, and git reflog.
- Reusing conflict resolutions with git rerere: enabling, typical
flow, inspecting, seeding from existing history, sharing the cache,
and caveats, clarifying that contribution branches must keep a
linear history while forks may carry merge commits.
The guide is referenced from doc/README.md (Developer tools),
code-style-contrib.md, and CONTRIBUTING.md. Guidance coupled to its
own document is cross-linked instead of moved: clang-format.md
(pre-commit hook), GET_SOURCES.md (branch and tag model), and
doc_best_practices.md (docs: commit prefix).
Also fix a typo in the T tracer addconsoletrace documentation.
Signed-off-by: Andrea Lacava <thecave003@gmail.com>
Previously, is_tdd_ul_symbol() and is_tdd_dl_symbol() returned true
unconditionally in FDD. This is correct for UL/DL presence (in FDD,
every symbol carries both UL and DL), but it breaks logic that relies
on the TDD property that a UL symbol is not a DL symbol (and vice
versa), e.g. the computation of the last DL symbol in mixed slots. In
FDD, this assumption does not hold, leading to incorrect behavior.
Remove the FDD shortcut from the TDD symbol helpers so they strictly
answer the TDD question, and make the FDD case explicit at each
function call (nFrameDuplexType != XRAN_FDD && ...). This harmonizes
the TDD and FDD paths: in FDD, no slot/symbol is skipped on RX or TX,
and guard-slot handling only applies to TDD.
Signed-off-by: Karim Boutiba <karim.boutiba@openairinterface.org>
The TTI computation in xran_fh_tx_send_slot() assumed 20 slots per
frame (30 kHz SCS only). Compute slots_per_frame as 10 << mu from the
fronthaul configuration instead, so the TTI is correct for any numerology.
Signed-off-by: Karim Boutiba <karim.boutiba@openairinterface.org>
To run the test with OAI UE and vrtsim, use the following commands, assuming
the executables are in the build directory.
OAI O-RU:
./nr-oru -O ../targets/PROJECTS/GENERIC-NR-5GC/CONF/ru.band77.mu1.106rb.1x1.conf --device.name vrtsim --vrtsim.role server
OAI 7.2 gNB:
./nr-softmodem -O ../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.band77.mu1.106rb.fhi.1x1.conf
OAI NR UE:
./nr-uesoftmodem -C 4049760000 -r 106 --numerology 1 --ssb 516 --device.name vrtsim
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Replace the single polling thread that handled all channels
with separate, dedicated polling threads per TX and RX channel.
This avoids calling `zmq_poll` across all sockets simultaneously,
reduces lock contention, and enables concurrent socket operations
on multiple antennas.
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Add `TxRxSamplesSIMD` to validate the correctness of the new ZMQ
device transmit and receive paths with int16 complex samples.
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Optimize the TX path by converting int16 complex samples to float
complex format directly into ZMQ message buffers using SIMD. Queue
these ZMQ messages (`zmq_msg_t`) directly, avoiding temporary internal
copying and enabling ZMQ's zero-copy interface during actual transmit
in the polling thread.
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Optimize the RX path by converting float complex samples received on ZMQ
to int16 complex format using SIMD right inside the polling thread. This
allows storing int16 complex (c16_t) samples directly inside the overflow_buffer,
skipping a temporary float buffer allocation and a memcpy in the receive function.
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Add a performance benchmark `BenchmarkThroughput` to measure the sample rate capacity
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
This update allows automatic discovery of target platform when building xran.
Supproted platforms: armv8 and x86_64 with avx512
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Make xran_DOWNLOAD ON by default - this simplifies work in the most common
usecase and still allows to overwrite xran directory with xran_LOCATION.
Signed-off-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
ci: Speedup fhi72 dockerfiles (#261)
Move "COPY . ." down in 7.2 dockerfiles. This layer doesn't cache well
due to changes in docker context, moving it down allows docker builder
to cache other layers that are not affected by the context.
Reviewed-by: Jaroslava Fiedlerova <jaroslava.fiedlerova@openairinterface.org>
Fix PSS correlation peak value and average value on the OAI UE logs (#274)
These metrics are very helpful to properly adjust the USRP gains on the OAI UE. There was a regression in the code, this commit just gets it showing properly again.
Current develop:
[NR_PHY] Starting sync detection
[PHY] [UE thread Synch] Running Initial Synch
[NR_PHY] Starting cell search with center freq: 3619200000, bandwidth: 106. Scanning for 1 number of GSCN.
[NR_PHY] Scanning GSCN: 0, with SSB offset: 516, SSB Freq: 0.000000
[PHY] Initial sync: pbch decoded sucessfully, ssb index 0
[PHY] pbch rx ok. rsrp:51 dB/RE, adjust_rxgain:-1 dB
[NR_PHY] Cell Detected with GSCN: 0, SSB SC offset: 516, SSB Ref: 0.000000, PSS Corr peak: 0 dB, PSS Corr Average: 0
This PR:
[PHY] SSB position provided
[NR_PHY] Starting sync detection
[PHY] [UE thread Synch] Running Initial Synch
[NR_PHY] Starting cell search with center freq: 3619200000, bandwidth: 106. Scanning for 1 number of GSCN.
[NR_PHY] Scanning GSCN: 0, with SSB offset: 516, SSB Freq: 0.000000
[PHY] Initial sync: pbch decoded sucessfully, ssb index 0
[PHY] pbch rx ok. rsrp:51 dB/RE, adjust_rxgain:-1 dB
[NR_PHY] Cell Detected with GSCN: 0, SSB SC offset: 516, SSB Ref: 0.000000, PSS Corr peak: 99 dB, PSS Corr Average: 61
Reviewed-by: Sakthivel Velumani <s.velumani@northeastern.edu>
Enforce N_PRB=2^x3^y5^z in SC-FDMA uplink scheduler (#247)
With SC-FDMA, the scheduler in uplink needs to schedule N_PRB=2^x3^y5^z.
Not enforcing it may lead to unwanted UE behavior like retransmissions
and re-establishments.
TS38.211 - 6.3.1.4
Reviewed-by: Francesco Mani <email@francescomani.it>
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
RRC fixes (#225)
- Hardens NR RRC re-establishment handling on the gNB and UE:
re-establishment requests with invalid PCI/C-RNTI or incomplete UE
context are rejected or fall back to RRCSetup per TS 38.33.
- Fixes an invalid post-release connected state after PDU session
teardown
- Stops gNB process aborts when a UE sends spare RRC establishment-cause
values.
- Fix RRCSetup fallback: the UE MAC layer is reset before bearer
teardown on RRCSetup fallback to avoid scheduler use of released RLC
entities.
Closes: #127Closes: #128Closes: #148
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Reviewed-by: Francesco Mani <email@francescomani.it>
These metrics are very helpful to properly adjust the USRP gains on the OAI UE.
There was a regression in the code, this commit just gets it showing properly again
Signed-off-by: Luis Pereira <lpereira@allbesmart.pt>
Integration: 2026.w27
- #227 Cleanup: NGAP reconnection debug log
- #233 fix: proper SA/NSA mode detection
- #239 Fix function init_context_sss_nr()
- #256 ci: Move test pcaps to github
- #244 fix(zmq): Fix clang compiler warnings in zmq radio
- #220 fix(NR_UE): gate half-frame PBCH mirror on caller-provided ssb_period
- #257 [FHI72] Update the xran K release tag due to the PR https://github.com/openairinterface/o-du-phy/pull/3
- #192 DLSIM test for type0 PDSCH frequency allocation
- #238 minorfix(imscope): moving alignas from struct type to atomic variable
- #255 ci: Speedup unit test dockerfile
- #217 NAS: refactor Identity Request handler and enforce spec-compliant security checks
- #243 Clean up openair0_device, remove eth_params usage in L2/L3
- #204 Implementation of the E3 Agent for dApps and E3AP (no service models)
- #258 NR UE: add assert for reserved bits per symbol not multiple of Qm
- #253 CI: Collect amariue logs, update eNB configs
- #203 CI: Add label check and signature verification in GitHub Actions
Closes: #219Closes: #82
CI: Add label check and signature verification in GitHub Actions (#203)
- Update contributing guidelines for signing of commits
- Check for unsigned commits in the github actions workflow
- Skip CI when no mandatory CI label present on the PR
- Always remove retrigger-ci label when present - Like post-always or
post-cleanup
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Reviewed-by: Sagar Arora <sagar.arora@openairinterface.org>
Reviewed-by: Shubhika Garg <shubhika.garg@openairinterface.org>
- The require-maintainer-approval job was being skipped on push event
when upstream jobs (verify-signed-commits and check-labels) were skipped,
even though detect-changes job successfully marked protected files as changed.
- GitHub Actions may skip dependent jobs due to upstream skipped states before
evaluating custom conditions.
- Adding always() ensures the job condition is evaluated regardless of
the status of upstream jobs, while still enforcing the rule that the job
only runs when protected_files_changed == true.
Signed-off-by: Shubhika Garg <shubhika.garg@openairinterface.org>
The executor machine for this test is currently unavailable. The test
will be re-enabled once the replacement machine is configured.
Signed-off-by: Jaroslava Fiedlerova <jaroslava.fiedlerova@openairinterface.org>
NR UE: add assert for reserved bits per symbol not multiple of Qm (#258)
map_overlapped_ack() divides num_reserved_bits_on_sym by Qm to get the
number of reserved REs. Add assertion to catch cases where the reserved
bit count is not a multiple of Qm, which would indicate a bug in the
upstream UCI-on-PUSCH mapping.
This is a follow-up of comment after PR #221
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
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>
Add the E3 agent lifecycle on top of libe3: configuration mapping,
agent creation/init/start, dApp report and status-change handlers,
and xApp control and subscription-query helpers. Wire e3_init() and
e3_destroy() into nr-softmodem under the E3_AGENT guard.
The agent registers no concrete service models: service models (such
as spectrum sensing) live in their own modules and register
themselves, keeping the framework decoupled from any specific use
case.
Signed-off-by: Andrea Lacava <thecave003@gmail.com>
Add the E3AP CMake target, which links the external libe3 library
discovered via pkg-config, and the E3Configuration parser that reads
the link and transport selection from the gNB configuration file and
validates the supported link/transport combinations.
libe3 is kept external and is only required when E3_AGENT is enabled.
Signed-off-by: Andrea Lacava <thecave003@gmail.com>
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>
Clean up openair0_device, remove eth_params usage in L2/L3 (#243)
This PR has three goals
- Remove the usage of eth_params in L2/L3 code, and replace with
tailored data structures for IP connectivity where necessary
- Remove many of the includes of common_lib.h where possible
- Slightly clean up openair0_device and in particular move fields to
eth_state_t where appropriate
Reviewed-by: Bartosz Podrygajlo <bartosz.podrygajlo@openairinterface.org>
Reviewed-by: Teodora Vladić <teodora.vladic@openairinterface.org>
NAS: refactor Identity Request handler and enforce spec-compliant security checks (#217)
Align UE Identity Request handling with TS 24.501 by checking the NAS
security header and rejecting unprotected non-SUCI requests.
Also, refactor Identity Response identity selection based on the
requested identity types, add to a helper and handle unavailable
identities in the UE context.
Closes: #82
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
Reviewed-By: Rakesh Mundlamuri <rakesh.mundlamuri@openairinterface.org
ci: Speedup unit test dockerfile (#255)
Use docker cache, reduce the number of installed apt packages and reduce
compilation scope.
Reviewed-by: Robert Schmidt <robert.schmidt@openairinterface.org>
A UE RRCSetupRequest with establishmentCause in the spare range (10–15)
could abort nr-softmodem: RRC asserted on cause >= NGAP_RRC_CAUSE_LAST,
and cause 11 failed NGAP ASN.1 encode when passed through by index.
NR RRC (TS 38.331) and NGAP RRCEstablishmentCause (TS 38.413 §9.3.1.111)
do not share one integer namespace: spare values must not be sent
as NGAP causes.
Remove the RRC AssertFatal on causes. When building
InitialUEMessage, map RRC indices 0–9 to the matching NGAP cause
and map anything else to notAvailable, as specified for unmapped UE
causes.
Changes:
- Drop establishment-cause range AssertFatal in rrc_gNB_send_NGAP_NAS_FIRST_REQ
- Add rrc2ngap_establishment_cause() and use it for InitialUEMessage RRCEstablishmentCause
- Remove redundant DevCheck on establishment_cause in ngap_gNB_handle_nas_first_req
- Adopt mapping logic in rrc_gNB_send_NGAP_NAS_FIRST_REQ
Closes: #127
Signed-off-by: Guido Casati <guido.casati@openairinterface.org>
When the gNB answers RRCReestablishmentRequest with RRCSetup (TS 38.331
clause 5.3.3.4 fallback), the UE must release all bearers except SRB0 before
applying the new masterCellGroup. CONFIG_RESET was queued after RLC release,
so the MAC slot thread kept polling LCID 1 from a stale lc_ordered_list while
the RLC entity was already NULL.
Queue NR_MAC_RRC_CONFIG_RESET (RRC_SETUP_REESTAB_RESUME) first, then release
PDCP, RLC, and SDAP. On the MAC thread, clear lc_ordered_list except SRB0
before release_mac_configuration() so the UL scheduler stops looping released
logical channels until CONFIG_CG re-adds SRB1.
Changes:
- rrc_UE.c: move CONFIG_RESET to the start of nr_rrc_rrcsetup_fallback()
- config_ue.c: drop non-SRB0 lc_ordered_list entries on RRC_SETUP_REESTAB_RESUME
Closes: #128
Signed-off-by: Guido Casati <guido.casati@openairinterface.org>
