Refactor SDAP adaptation work for QoS
This MR is an adaptation of the code introduced in !2703.
The goal is a cleanup and functional refactor of the SDAP/PDCP
integration, that is:
- centralize SDAP configuration logic
- simplify entity creation
- improve robustness of role-based SDAP handling
- prepare the codebase for clean support of DRB reconfiguration and
teardown flows
More concretely:
1. New sdap_config_t and get_sdap_Config()
- Introduced an internal struct sdap_config_t to abstract SDAP config
input
- Centralized SDAP config parsing into new get_sdap_Config() function
that translates ASN.1 NR_SDAP_Config into this internal
representation. This is called during RRC triggered
(re)configuration procedures.
- Enable mapping of number of QoS flows > 1
2. Unified role handling with bitmasks
- Added a bitmask-based entity_role field to track SDAP directions:
SDAP_UL_RX, SDAP_UL_TX, SDAP_DL_RX, SDAP_DL_TX: header presence was
determined by simple direction (UE vs gNB) and individual
is_sdap_rx/tx() checks, however nr_sdap_rx_entity behaves
differently depending on the direction of the RX entity (DL/UL),
therefore this change can help enable a more accurate SDAP header
handling across directions and node types.
- Replaces old helpers is_sdap_rx() / is_sdap_tx() with internal
checks against the role bitfield
- QFI-to-DRB mapping is now annotated with direction for both data and
control PDUs
3. Simplified DRB and SDAP setup
- add_drb() in PDCP API now delegates SDAP config processing cleanly
- new_nr_sdap_entity() is used consistently to register a fresh SDAP
context for the UE and PDU session.
- Also, re-use and reconfigure existing SDAP entity if already
exists.
- logging has been added to trace mapped QFIs from RRC and resulting
table entries
4. Improved QFI-to-DRB management
- Refactored nr_sdap_qfi2drb_map_update() to register QFIs based on
parsed config
- Ensures control PDUs are correctly routed even after reconfiguration
- Extended nr_sdap_ue_qfi2drb_config: perform UL QoS flow to DRB
mapping configuration for a SDAP entity has already been established
according to TS 37.324, 5.3 QoS flow to DRB Mapping, 5.3.1
Configuration Procedures. Handle both UL QoS Flows mapping rules to
add and to remove. QFIs will now be properly unmapped if specified
via mappedQoS_FlowsToRelease, this might prevent stale QFI mappings
from being used incorrectly.
- nr_sdap_qfi2drb() and sdap_map_ctrl_pdu() now strictly fallback to
default_drb only if a QFI mapping is missing. Missing default DRB
now triggers LOG_E() (previously silent or misrouted to DRB 0).
5. Other cleanup
- Remove dependencies from legacy rb_id_t
This commit refactors the SDAP entity QoS flow to DRB mapping functionality
to improve code organization and enhance maintainability.
Key changes:
- Split nr_sdap_qfi2drb_map_update into focused functions:
* nr_sdap_add_qos_flows_to_drb: handles QFI addition to DRB
* nr_sdap_rm_qos_flows_from_drb: handles QFI removal from DRB
* nr_sdap_ue_control_pdu_config: handles UE control PDU generation
- Consolidate add/modify logic into reusable nr_sdap_addmod_entity function
- Remove entity existence checking and updating from new_nr_sdap_entity:
this function should only add SDAP entities
- Improve function separation of concerns: do SDAP entity add or update
separately and improve modularity by splitting operations in self
contained functions
- At SDAP creation, do only add of QFI to DRB mapping
- rename new_nr_sdap_entity to nr_sdap_add_entity for function naming consinstency
* use get_sdap_Config to process sdap_Config
* move SDAP config logic to the scope where it is relevant
* add SDAP entity direcly in RRC, not from PDCP
* replaced nr_pdcp_add_drbs with single add_drb call: it was no longer
efficient to keep it in the new logic. The addMod list can be looped directly in RRC.
* add specific function to add bearers from addMod list in E1, NSA, and UE
Initialize NCC=0 on NGAP Initial Context Setup (3GPP TS 33.501 §6.9.2.1.1)
The nhcc should be initialized to 0 upon Initial Context Setup.
Also, remove unused kgnb_ncc: nh_ncc is already there.
Closes#1008
Prevent assertion in ngap_gNB_nas_uplink() due to uninitialized selected_plmn_identity:
the selected_plmn_identity field was not being set during N2 handover,
causing the assertion ((plmn->mnc_digit_length == 3) || (plmn->mnc_digit_length == 2))
to fail when processing subsequent NAS messages. The issue is that the Serving PLMN
is not stored by RRC. During N2 mobility, RRC can get this info from GUAMI.
When receiving the Handover Request the target gNB knows from GUAMI
which serving PLMN is the AMF belonging to. In current design, allowed PLMNs
are stored in rrc.configuration. The incoming PLMN needs to be validate
against the PLMNs in the list, then stored in the UE context as Serving PLMN.
This change adds PLMN validation when processing handover requests from the source gNB.
The validation is needed because:
- Target gNB must verify that the PLMN from the GUAMI in the handover request
is allowed by its configuration before accepting the handover to prevent handover
to unsupported PLMNs.
- When PLMN validation fails, the target gNB now properly sends NGAP_HANDOVER_FAILURE
- UE Context must store serving PLMN for later use
This commit is removing the storage of selected PLMN in NGAP UE context.
We store the Serving PLMN in the RRC UE context instead.
The Selected PLMN is the PLMN that the UE chose (or was directed to) for registration
and it is sent in the RRCSetupComplete. This is different from the selected
PLMN mentioned in the NG INITIAL UE MESSAGE for network sharing.
Selected PLMN: determines which core network and AMF the UE is registered with
GUAMI = Identifies the serving AMF and includes the PLMN of that AMF
Serving PLMN: the PLMN that is currently serving the UE (e.g. contained in GUAMI)
The AMF’s PLMN may match the selected PLMN, or not (especially in network sharing or roaming).
Regardless, the UE always have a Serving PLMN.
Initial UE message does not have a TAI IE per se, but TAI is a mandatory
member of the mandatory UserLocationInformation CHOICE.
NR CGI is also mandatory and carried inside UserLocationInformation:
in network sharing, the PLMN ID in TAI takes on additional
significance: RAN is shared but CN are different, so in this case PLMN in TAI is
needed for the AMF route the message to the correct operator’s core.
If network sharing applies (e.g., shared RAN between PLMN-A and PLMN-B):
the UE or network may select PLMN-B instead, and that PLMN identity
is included in the Initial UE Message’s TAI IE.
Conclusion:
1) UE always sends the selected PLMN during the registration,
regardless of whether it is shared or not.
2) Selected PLMN Identity is an actual IE sent in the RRCSetupComplete
while in NGAP there's no Selected PLMN Identity IE, only PLMN Identity
IEs in both TAI and NR CGI. It is a subtle difference.
3) The serving PLMN of the UE needs to be stored in RRC UE Context for
later use in NAS procedures. e.g. at initial registration it matches
the Selected PLMN
4) No need to store PLMN in NGAP UE Context, params are passed by RRC
5) TAI and NR CGI, which contain the PLMN identity, are mandatory in
UserLocationInformation IE CHOICE, and should reflect current status
Changes
- Initial UE Message: pass UE-selected PLMN and NR cell id from RRC to NGAP
- Uplink NAS Transport: use PLMN, TAC, and cell id provided by the message;
- Build NR CGI from gNB ID + cell id
- Store UE-selected PLMN only in RRC UE context at NAS_FIRST_REQ for later
Uplink NAS, stop storing PLMN in NGAP UE context
CI: Upgrade HO setup to use an attenuator
The goal of this MR is to upgrade HO CI setup to include a digital attenuator
that will allow us to trigger handover by attenuating the signals on the DUs.
- Add band mismatch check in valid_du_in_neighbour_configs function
- Ensures neighbor cell band matches serving cell band
- Prevents invalid neighbor configurations for handover
- Simplify do_nrMeasurementReport_SA API (encoder allocates local report)
- Adopt asn1cCalloc consistently
- Minor init cleanup for UL_DCCH message struct
- Add to common/utils/nr/nr_common remove from NR_MAC_UE/nr_ue_procedures.c
- Adopt in asn1_msg.c for MeasurementReport: this solves the following assert:
Assertion (enc_rval.encoded > 0) failed!
In do_nrMeasurementReport_SA() /oai-ran/openair2/RRC/NR/MESSAGES/asn1_msg.c:898
ASN1 message encoding failed (MeasResultServMOList, 18446744073709551615)!
Motivation: unify RSRP-to-index mapping across layers and fix NR RRC MeasurementReport
encoding failures due to out-of-range values by reusing the validated mapping.
Note NR_RSRP-Range.c constraint:
{ APC_CONSTRAINED, 7, 7, 0, 127 } /* (0..127) */
Split monolithic e1_send_bearer_updates into three focused functions:
- e1_send_bearer_updates(): DRB setup from F1 UE Context Modification Response
- e1_request_pdcp_status(): Request PDCP status during inter-CU handover
- e1_notify_pdcp_status(): Notify CU-UP with PDCP status during handover
Extract common helpers:
- append_e1_drb_mod_req(): Common DRB-to-mod for bearer request logic
- e1_send_bearer_modification_request(): Common sending step
Bug fixes:
- Fix loop bounds (i < n instead of i == n)
- Fix array access bounds checking
- Fix DRB ID consistency
Memory management:
- Add missing free_e1ap_context_mod_request calls
- Improve error handling with early returns
In the process:
- Simplify cuup_notify_reestablishment with FOR_EACH_SEQ_ARR loop
- Adopted all callers to use new consolidated functions
Improves maintainability and eliminates complex conditional logic.
Replace field-by-field assignment with struct copy for plmn_identity.
Both source and destination use identical plmn_id_t type, making
this change safe and more maintainable.
- Reduces lines of code
- More readable and less error-prone
- Single memory copy operation instead of multiple field assignments
- Add missing handover context cleanup in rrc_CU_process_ue_context_release_complete
- Fix 16-byte handover context leak in N2 handover source gNB trigger path
AddressSanitizer backtrace:
Direct leak of 16 byte(s) in 1 object(s) allocated from:
/#0 0x7fee67cb4a57 in __interceptor_calloc ../../../../src/libsanitizer/asan/asan_malloc_linux.cpp:154
/#1 0x58059e33454b in calloc_or_fail /home/guido/repo/openairinterface5g/develop/common/utils/utils.h:74
/#2 0x58059e33454b in alloc_ho_ctx /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB_mobility.c:47
/#3 0x58059e339e4d in nr_rrc_trigger_n2_ho /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB_mobility.c:556
/#4 0x58059e33ae93 in nr_HO_N2_trigger_telnet /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB_mobility.c:611
Root cause: Handover context allocated in N2 handover source gNB trigger path (nr_rrc_trigger_n2_ho)
for any successful N2 handover but not properly freed in all handover completion scenarios.
The UE context release complete handler was missing cleanup for handover context.
Solution: refactor handover context cleanup
- Move nr_rrc_finalize_ho() call to rrc_delete_ue_data() for centralized cleanup
- Remove redundant nr_rrc_finalize_ho() calls from handover failure paths:
* rrc_CU_process_ue_context_release_request() - UE not deleted yet
* invalidate_du_connections() - UE will be deleted later
- Keep nr_rrc_finalize_ho() calls in handover success paths where UE continues operating
- Ensures handover context is cleaned up exactly once when UE is actually deleted
- Prevents potential double-free and use-after-free issues in handover cleanup
This centralizes all UE data cleanup in rrc_delete_ue_data() and ensures
handover context is properly managed throughout the UE lifecycle and cleaned up
when UE delete happens.
- Replace heap allocation with stack allocation for seq_arr_t structures
- Use proper seq_arr_free() with free functions for ASN.1 structures
- Remove unnecessary malloc/free calls for sequence containers
- Improve memory safety and performance with automatic cleanup
Fixes 128-byte memory leak:
Direct leak of 128 byte(s) in 2 object(s) allocated from:
/#0 0x7e7f39ab4a57 in __interceptor_calloc ../../../../src/libsanitizer/asan/asan_malloc_linux.cpp:154
/#1 0x56df8b07312d in SEQUENCE_decode_uper /home/guido/repo/openairinterface5g/develop/cmake_targets/ran_build/build/openair2/RRC/LTE/MESSAGES/constr_SEQUENCE_uper.c:37
/#2 0x56df8b056551 in uper_decode /home/guido/repo/openairinterface5g/develop/cmake_targets/ran_build/build/openair2/RRC/LTE/MESSAGES/uper_decoder.c:83
/#3 0x56df8a896b1b in get_nr_mtc /home/guido/repo/openairinterface5g/develop/openair2/LAYER2/NR_MAC_gNB/nr_radio_config.c:4216
/#4 0x56df8a82feb8 in ue_context_setup_request /home/guido/repo/openairinterface5g/develop/openair2/LAYER2/NR_MAC_gNB/mac_rrc_dl_handler.c:635
/#5 0x56df8a66a298 in nr_initiate_handover /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB_mobility.c:218
/#6 0x56df8a6720af in nr_rrc_trigger_n2_ho_target /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB_mobility.c:526
/#7 0x56df8a5cf338 in rrc_gNB_process_e1_bearer_context_setup_resp /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB.c:2633
/#8 0x56df8a5d28ab in rrc_gnb_task /home/guido/repo/openairinterface5g/develop/openair2/RRC/NR/rrc_gNB.c:3012
/#9 0x7e7f38494ac2 in start_thread nptl/pthread_create.c:442
- Add early check for existing UE context by AMF UE NGAP ID at beginning of rrc_gNB_process_Handover_Request
- Add dedicated function to get UE context by AMF UE NGAP ID: rrc_gNB_get_ue_context_by_amf_ue_ngap_id()
- Send handover failure with appropriate cause if UE context already exists
- Remove redundant ho_context NULL check that could never be true for newly created UE contexts
- Prevents duplicate handover processing and resource leaks
Add check for cu_exists_f1_ue_data() before calling cu_get_f1_ue_data()
to prevent assertion failure when telnet command 'ci fetch_du_by_ue_id'
is used for UEs that have been handed over via N2 (and no longer have
F1 UE data).
This fixes the crash:
Assertion (ret == HASH_TABLE_OK && data != ((void *)0)) failed!
In get_hashtable_data() /oai-ran/openair2/F1AP/f1ap_ids.c:36
element for ue_id 1 not found
The function now returns NULL gracefully when F1 UE data is not available.
Co-authored-by: Guido Casati <hello@guidocasati.com>
- Add proper cleanup of allocated ASN.1 structures in all return paths
- Fix early returns that were leaking NR_HandoverPreparationInformation
- Fix early returns that were leaking NR_RRCReconfiguration
- Add cleanup at end of successful function execution
This prevents memory leaks when processing handover preparation information
during N2 handover procedures.
- Add UE context cleanup before sending handover failure message
- Prevents memory/resource leak when PDU session establishment fails during handover
- UE context was created but never cleaned up on failure path
This fixes a bug where UE contexts would accumulate over time
when handovers failed after context creation.
- Fixed incorrect log messages that said 'PCI=%lu' when printing nr_cell_id
- Now prints both NR Cell ID and PCI when DU is found
- Provides better debugging information for handover requests
- Replace simple counter-based DRB ID assignment with actual DRB ID lookup
- Add nested loop to iterate through DRBs for each PDU session to be release
- Improve logic flow with early continue for non-matching PDU sessions
This ensures DRB release list contains correct DRB IDs that correspond to actual DRB entities
* There is no IE corresponding to PDU sessions failed to release
in the PDU SESSION RESOURCE RELEASE RESPONSE message. This was removed
and the corresponding code was refactored and cleaned up.
* In the Release Command handler, only established PDU Session are set to be
released. The Response message is filled accordingly.
Motivation:
The previous architecture had several issues:
- Duplicate DRB generation logic in generateDRB() and generateDRB_ASN1()
- Embedded SDAP/PDCP configs in drb_t created tight coupling
- No clear separation between RRC internal state and ASN.1 encoding
- Maintenance burden due to duplicated configuration logic
New Architecture:
- drb_t now only stores DRB-specific data (ID, PDU session ID, PDCP config)
- SDAP configuration moved to PDU session level (following PDCP design pattern)
- ASN.1 encoding helpers (nr_rrc_build_*_config_ie()) handle conversion
- Single source of truth for DRB creation in RRC via nr_rrc_add_drb()
Key changes:
- Store nr_sdap_configuration_t per PDU session
- Simplified drb_t structure: removed embedded SDAP/PDCP configs, added pdusession_id
- New helper: nr_rrc_build_sdap_config_ie()
- Updated createDRBlist() to use new helper functions and proper DRB ID lookup
- Refactored trigger_bearer_setup() to use nr_rrc_add_drb() and fill_e1_drb_to_setup()
- Removed generateDRB() and generateDRB_ASN1() functions
- Updated set_bearer_context_pdcp_config() to return config by value
- Added SDAP configuration header file for type definitions
This eliminates code duplication, improves maintainability, and creates
a cleaner separation between RRC state management and ASN.1 encoding.
- Move QoS-related enums and structures from ngap_messages_types.h to 5g_platform_types.h
- Replace ngap_* QoS types with generic qos_* types for better reusability
- Update field names from allocation_retention_priority to arp for consistency
- Update all references across RRC and NGAP modules to use new type names
- Remove duplicate QoS type definitions from NGAP-specific header
This improves code organization by centralizing QoS parameter definitions
in a common platform types header and eliminates NGAP-specific naming
in favor of more generic, reusable type definitions.
The maximum number of QoS flows is 64.
- Replace QOSFLOW_MAX_VALUE with MAX_QOS_FLOWS constant
- Move MAX_QOS_FLOWS definition to common/platform_constants.h
- Remove duplicate QOSFLOW_MAX_VALUE definition from ngap_messages_types.h
This improves maintainability by centralizing the QoS flow limit constant
and eliminates duplicate definitions across different header files.
- Limit scope of get_default_rbconfig function: from asn1_msg.c/.h to rrc_gNB_nsa.c where it's used
- Create new rrc_gNB_asn1.c/h files for ASN.1 utility functions: they can be used in other RRC files
- Add nr_rrc_build_pdcp_config_ie function for building PDCP configuration IEs
- Update get_default_rbconfig to use the new PDCP config builder
- Add rrc_gNB_asn1.c to CMakeLists.txt build configuration
The previous DRB management relied on a fixed-size array (established_drbs[MAX_DRBS_PER_UE])
and manual status tracking using DRB_ACTIVE/INACTIVE flags. This approach was inefficient,
and made assumptions about DRB ID allocation that do not generalize well
to dynamic procedures like bearer modification or removal.
* Replace fixed-size array established_drbs[] with dynamic
seq_arr_t *drbs in gNB_RRC_UE_t
* Refactor get_drb() and added nr_rrc_add_drb() with clean abstractions
using find and seq_arr lib
* Updated all DRB-related logic (e.g., generateDRB,
F1AP/E1AP tunnel config, reestablishment, mobility) to use seq_arr.
* Removed status field and DRB_ACTIVE/INACTIVE logic: list presence implies active
* DRB ID allocation now tracked via seq_arr size : simplifies DRB management and
avoids DRB ID–indexed assumptions: code assumed DRB IDs mapped directly to
array indices: established_drbs[drb_id - 1]. This could break when:
DRB IDs are not sequential, DRBs are removed and re-added, or there are gaps in IDs
The RRC PDU Session struct is converted from a fixed-size array
to a dynamically sized seq_arr. This improves flexibility and
simplifies session management by eliminating arbitrary size limits
and enabling dynamic addition/removal of PDU sessions.
Helper functions and loops have been adapted to use the seq_arr API.
This change is a step toward more robust and maintainable handling
of PDU sessions in the gNB RRC layer.
The "status" state machine remains untouched in this commit and
is refactored in a later commit.
Also:
* add macro to push to seq_arr and return the new element
* move initialization of xid (RRC PDU Session struct) to
find_pduSession (temporary, will be finalized in a later
commit) since with the new seq_arr design the initialization
is no longer possible in the UE context generation (also
does not belong to it, initialize when adding a new PDU Session)
- Process all PDU sessions in handover request instead of only the first one
- Add DevAssert for bounds checking on nb_of_pdusessions
- Fix logic error where multiple PDU sessions were ignored in handover scenarios
Previously, the RRC layer was incorrectly allocating stack memory for the ho_required_transfer field and passing it to NGAP, however it was not used. The IE is mandatory but contains only 1 optional IE, therefore is encoded in the NG message with empty content.
Changes:
- Remove unnecessary ho_required_transfer field from pdusession_resource_t definition, the IE is encoded anyway with empty content. If Direct Forwarding Path Availability is needed at any stage in the future it can be added to pdusession_resource_t and filled in RRC.
- Add clarifying comment about empty HandoverRequiredTransfer structure
N2 handover
This MR introduces full support for N2 handover, covering handover
decision, preparation, execution, and notification between source and
target NG-RAN nodes.
Key features:
1. Handover Decision & Preparation:
- Implement N2 handover decision based on UE measurement reports.
- Generate the Handover Preparation Information message, including
RRCReconfiguration.
- Send Handover Required message from the source NG-RAN to the AMF.
2. Handover Execution:
- Decode and handle the Handover Request on the target NG-RAN.
- Process the Handover Command on the source gNB, triggering
RRCReconfiguration.
- Initiate Handover Notify after successful completion.
3 NGAP & RRC Enhancements:
- Implement NGAP encoding/decoding functions for Handover Required,
Handover Request, Handover Command, Handover Failure, and Handover
Notify (3GPP TS 38.413).
- Adds NG-RAN Status Transfer support (UL/DL) for PDCP COUNT
preservation during mobility:
- support for NGAP Uplink and Downlink RAN Status Transfer messages
(TS 38.413 §9.2.3.13-14) to enable proper PDCP COUNT value
transfer during handover or recovery: NGAP encoding/decoding for
RAN Status Transfer, PDCP helpers to extract and apply COUNT (HFN
+ SN) per DRB. This aligns with TS 38.300 §9.2.3.2.1 and TS 23.502
§4.9.1.3.3, ensuring PDCP status preservation in AM.
4. Testing:
- Introduce a Telnet command to manually trigger N2 handover using UE
ID and neighbor PCI.
- Add configuration file for testing N2 handover with a target gNB.
This commit completes the NGAP Mobility Management procedure for N2 handover.
Upon failure on source gNB the Handover Cancel message is sent to the AMF which
in return responds with an ack.
Upon reception of NG RAN Status at the target CU-CP, send PDCP Status
via E1 Bearer Context Modification to the target CU-UP and update PDCP Count
upon reception of the message.
For the sake of simplicity, re-used and extended legacy e1_send_bearer_updates.
Further refactoring is not addressed in this commit.
Once fetched the PDCP Status from the PDCP entity over E1, the CU-CP triggers
the NG RAN Status Transfer procedure to transfer the PDCP Status to the target
CU.
This commit is also introducing the RRC callback.
Chieh-Chun Chen