rrc-usage.md

This document describes the basic functioning of the 5G RRC layer, describes the periodic output, and explains the various configuration options that influence its behavior.

Developer documentation, such as UE connection control flow, reestablishment, or handover, are described in a separate page.

[[TOC]]

General

The RRC layer controls the basic connection setup of UEs as well as additional procedures. It is the fundamental building block of OAI's CU-CP, and interacts with lower layers (DU, basically MAC and RLC) through F1AP messages, and with the CU-UP through E1AP messages. More information can be found in the respective F1AP page and E1AP page.

Periodic output and interpretation

Similarly to the scheduler, the RRC periodically prints information about connected UEs and DUs into file nrRRC_stats.log in the current working directory of the executable running the RRC (typically, nr-softmodem). The output lists first all UEs that are currently connected, and then all DUs, in order.

For each UE, it prints:

UE 0 CU UE ID 1 DU UE ID 40352 RNTI 9da0 random identity c0f1ac9824000000:
    last RRC activity: 5 seconds ago
    PDU session 0 ID 10 status established
    associated DU:  DU assoc ID 8

where UE 0 is the UE index, CU UE ID and DU UE IDs are the IDs used to exchange over F1 (cf. scheduler logs). Further, it shows RNTI, when the last RRC activity happened, the status of PDU sessions and which DU is associated (through the SCTP association ID).

For each DU, it prints:

1 connected DUs
[1] DU ID 3584 (gNB-OAI) integrated DU-CU: 1 cell
  [1] nrCellID 12345678, PCI 0, Mode TDD, SSB ARFCN 641280
      TDD: band 78 ARFCN 640008 SCS 30 (kHz) PRB 106

The output shows:

• Total number of connected DUs
• For each DU: an index ([1]), the DU ID and name, connection type (either integrated DU-CU for monolithic deployments or assoc_id X for split deployments), and the number of cells served by this DU
• For each cell served by the DU: a cell index ([1]), the NR Cell ID, Physical Cell ID (PCI), operating mode (TDD or FDD), and SSB ARFCN
• Cell-specific frequency information: for TDD mode, the band, Point A ARFCN, subcarrier spacing (SCS), and number of resource blocks (PRB); for FDD mode, separate DL and UL frequency information

The RRC enables the support of multiple cells per DU (though currently each DU typically serves one cell in practice).

As of now, it does not print information about connected CU-UPs or AMFs.

Configuration of the RRC

Split-related options (when running in a CU or CU-CP)

See F1 documentation for information about the F1 split. See E1 documentation for information about the E1 split.

RRC-specific configuration options

In the gNBs section of the gNB/CU/CU-CP configuration file is the RRC-specific configuration

cell-specific options

Note that some SIBS are configured at the CU and some at the DU; please consult the MAC configuration as well for SIB configuration.

• gNB_ID and gNB_name: ID and name of the gNB
• tracking_area_code: the current tracking area code in the range [0x0001, 0xfffd]
• plmn: the PLMN, which is a list of entries consisting of:
  • mcc: mobile country code
  • mnc: mobile network code
  • mnc_length: length of mobile network code, allowed values: 2, 3
  • snssaiList: list of NSSAI (network selection slice assistence information, "slice ID"), which itself consists in
    • sst: slice service type, in [1,255]
    • sd (default 0xffffff): slice differentiator, in [0,0xffffff], 0xffffff is a reserved value and means "no SD" Note that: SST=1, no SD is "eMBB"; SST=2, no SD is "URLLC"; SST=3, no SD is "mMTC"
• enable_sdap (default: true): enable the use of the SDAP layer. If deactivated, a transparent SDAP header is prepended to packets, but no further processing is being done.
• cu_sibs (default: []) list of SIBs to give to the DU for transmission. Currently supported:
  • SIB2: serving-cell reselection parameters (configured in sib2_config)
  • SIB3: intra-frequency neighbour cell list (neighbours on the same SSB ARFCN as the serving cell)
  • SIB4: inter-frequency carriers + neighbour lists, grouped per (absoluteFrequencySSB, subcarrierSpacing). Per-frequency fields (e.g. cellReselectionPriority, threshX_HighP, threshX_LowP, q_OffsetFreq) come from frequency_list

Example activation:

cu_sibs = ( 2, 3, 4 );

SIB2 is configured per-gNB in sib2_config (see below). SIB3/SIB4 are derived from the neighbour configuration:

• neighbour_list / neighbour_cell_configuration: neighbour identity + per-neighbour offsets (q_OffsetCell, etc.)
• frequency_list: per-frequency SIB4 reselection parameters (priority/thresholds/q_OffsetFreq)

Example gNBs.[0].sib2_config:

cu_sibs = ( 2 );

sib2_config : {
  q_Hyst                   = 0;
  cellReselectionPriority  = 0;
  threshServingLowP        = 0;
  threshServingLowQ        = 4;
  s_NonIntraSearchP        = 10;
  s_NonIntraSearchQ        = 8;
  q_RxLevMin               = -56;
  q_QualMin                = -18;
  s_IntraSearchP           = 22;
  s_IntraSearchQ           = 20;
  t_ReselectionNR          = 1;
  deriveSSB_IndexFromCell  = 1;

  speed_t_Evaluation       = 0;
  speed_t_HystNormal       = 0;
  speed_n_CellChangeMedium = 1;
  speed_n_CellChangeHigh   = 2;
  speed_sf_Medium          = 1;
  speed_sf_High            = 0;
};

SIB3/SIB4 and measurement gaps

This section summarizes how SIB3/SIB4 and measurement gaps relate in NR and how OAI currently implements them.

From 3GPP TS 38.331:

• SIB3 carries intra-frequency reselection information (intraFreqNeighCellList).
• SIB4 carries inter-frequency reselection information (interFreqCarrierFreqList and per-carrier neighbour lists).
• MeasGapConfig is part of dedicated MeasConfig (typically sent in RRCReconfiguration) and controls measurement gaps in connected mode.

In other words:

• SIB3/SIB4 are broadcast SI for idle/inactive (RRC_IDLE / RRC_INACTIVE) reselection behavior: UE performs autonomous cell reselection using broadcast SI (SIB3 for intra-frequency, SIB4 for inter-frequency).
• MeasGapConfig is a dedicated UE measurement behavior and applies to connected mode (RRC_CONNECTED): the network configures what the UE measures and reports (periodic and event-based, e.g., A3), and those reports are used by CU-CP mobility logic (including handover decisions).

MeasGap does not depend on SIB3/SIB4, however they share the same underlying neighbour/frequency data model, which is the common source of serving + neighbour frequency information (see also Neighbor-gNB configuration):

• SIB3/SIB4 generation is done on the CU-CP side (inside rrc_gNB_du.c) from neighbour/frequency configuration and serving-cell MTC-derived ARFCN.
• Measurement-gap configuration also starts from the same neighbour/frequency model: CU uses neighbour fields (frequency/PCI/band) to build UE MeasConfig measurement objects, then DU derives/encodes gap parameters from CU-provided timing (meas_timing_config) and returns meas_gap_config for CU forwarding in dedicated RRCReconfiguration.

Detailed implementation flow and sequence diagrams are documented in rrc-dev.md.

UE-specific configuration

• um_on_default_drb (default: false): use RLC UM instead of RLC AM on default bearers

Neighbor-gNB configuration

Refer to the handover tutorial for detailed information about gNB neighbors and handover procedures.

Configuration structure and key semantics

The neighbour configuration is a 2-level structure:

• Outer list: neighbour_list
  • Key: nr_cellid of the serving cell
  • One entry per serving cell
• Inner list: neighbour_cell_configuration
  • Actual neighbour cells for that serving cell
  • Contains neighbour fields such as gNB_ID, neighbour nr_cellid, physical_cellId, frequency, PLMN, etc.

This same core configuration model is reused by multiple RRC procedures.

• SIB3/SIB4 generation: uses neighbour identity/frequency/offset fields to derive intra/inter-frequency SI.
• Connected-mode measurement config: uses neighbour frequency/PCI/band fields to build UE MeasConfig measurement objects.
• Handover-related procedures: reuse neighbour identity fields (e.g., cell ID/PCI/PLMN TAC, gNB ID) for target selection and for populating target-cell information carried in NGAP handover messages.

Conceptually, for each serving cell the RRC keeps:

• A per-frequency table (inter_freqs): one entry per (absoluteFrequencySSB, subcarrierSpacing) used for SIB4, containing the SIB4 per-frequency fields (priority, thresholds, q_OffsetFreq, q_RxLevMin, t_ReselectionNR).
• A per-neighbour list (neighbour_cells): one entry per neighbour, with identity (cell ID, PCI, PLMN, TAC), frequency (absoluteFrequencySSB, subcarrierSpacing, band), and SIB3/SIB4 per-neighbour offsets (q_OffsetCell, q_RxLevMinOffsetCell, q_QualMinOffsetCell).
• A link from neighbours to frequencies: each neighbour implicitly points to the matching inter_freqs entry via its (absoluteFrequencySSB, subcarrierSpacing); if no such frequency exists, it is treated as having no SIB4 per-frequency configuration.

Notes:

• In neighbour_list, only nr_cellid is used as the key for lookup.
• physical_cellId belongs to neighbour-cell entries in neighbour_cell_configuration (inner list).
• nr_cellid entries in neighbour_list should be unique to avoid ambiguous lookup.
• Intra-frequency neighbours (SIB3) are derived only from the per-cell neighbour_cell_configuration on the serving carrier.

At configuration time (gnb_config.c), neighbours are parsed into neighbour_cells, per-neighbour SIB3/SIB4 offsets are validated, and a per-frequency array inter_freqs is built by grouping neighbours by (absoluteFrequencySSB, subcarrierSpacing) and in-range SIB4 per-frequency fields (cellReselectionPriority, threshX_HighP/L, q_OffsetFreq) across neighbours on the same ARFCN. At SIB4 build time, the RRC uses inter_freqs to create one InterFreqCarrierFreqInfo per ARFCN for inter-frequency carriers (ARFCN different from the serving SSB ARFCN) and attaches all neighbours whose inter_freq_idx points to that frequency entry.

Required configuration parameters

To define a neighbour cell in the configuration file, the following parameters are required:

• gNB_ID - identifier of the neighbour gNB (e.g., 0xe01)
• nr_cellid - cell identifier of the neighbour cell (e.g., 11111111)
• physical_cellId - physical cell ID for radio identification (e.g., 1)
• absoluteFrequencySSB - SSB frequency in ARFCN notation (e.g., 643296)
• subcarrierSpacing - numerology index: 0=15kHz, 1=30kHz, 2=60kHz, 3=120kHz
• band - 3GPP frequency band number (e.g., 78 for 3.5GHz)
• plmn - PLMN configuration object with:
  • mcc - mobile country code (3 digits, e.g., 001)
  • mnc - mobile network code (2-3 digits, e.g., 01)
  • mnc_length - number of digits in MNC (must be 2 or 3)
• tracking_area_code - tracking area identifier (e.g., 1)

Example configuration structure:

# Per-frequency SIB4 configuration (one entry per ARFCN), shared by all cells
frequency_list = (
  {
    absoluteFrequencySSB = 643296;
    subcarrierSpacing    = 1;    # 30 kHz
    band                 = 78;

    frequency_config = (
      {
        cellReselectionPriority = 5;
        threshX_HighP = 10;
        threshX_LowP = 6;
        q_OffsetFreq = 0;
        # Optional: threshX_HighQ, threshX_LowQ, etc.
      }
    );
  }
);

# Per-cell neighbour configuration; neighbours reference frequency_list via ARFCN/SCS
neighbour_list = (
  {
    nr_cellid = 12345678;

    neighbour_cell_configuration = (
      {
        gNB_ID = 0xe01;
        nr_cellid = 11111111;
        physical_cellId = 1;
        absoluteFrequencySSB = 643296;   # ARFCN used to look up matching entry in frequency_list
        subcarrierSpacing = 1;           # 30 kHz
        band = 78;
        plmn = { mcc = 001; mnc = 01; mnc_length = 2 };
        tracking_area_code = 1;

        # Example per-neighbour offsets (SIB3/SIB4)
        q_OffsetCell = 0;
        q_RxLevMinOffsetCell = -1;
        q_QualMinOffsetCell = -1;
      }
    );
  }
);

Refer to the handover tutorial for complete examples and detailed setup instructions.