diff --git a/doc/RRC/rrc-dev.md b/doc/RRC/rrc-dev.md new file mode 100644 index 0000000000..d511421b01 --- /dev/null +++ b/doc/RRC/rrc-dev.md @@ -0,0 +1,318 @@ +This document contains documentation for the 5G RRC layer, destined towards +developers. It explains the basic working of the RRC, and various UE procedure +schemes (connection, reestablishment, handover) including their interworking +with other layers. + +User documentation, such as general configuration options, are described in [a +separate page](./rrc-usage.md). + +[[_TOC_]] + +# General + +5G RRC is basically an ITTI message queue with associated handlers. It +sequentially reads received ITTI messages and handles them through the function +`rrc_gnb_task()` (constituing the thread entry point function). In this +function, one can see three main groups of messages in a big switch statement: + +- NGAP (messages starting with `NGAP_`) +- F1AP (messages starting with `F1AP_`) +- E1AP (messages starting with `E1AP_`) + +For each message, a corresponding handler is called. The messages are roughly +named according to the 3GPP specification messages, so it should already be +possible to find the message in the switch based on a message name in the spec. + +Note that RRC is inherently single-threaded, and processes messages in a FIFO +order. + +# Sequence Diagrams of UE procedures + +The following section presents a number of common UE procedures for connection +establishment&control, bearer establishment, etc. The intention is to help +developers find specific functions within RRC in the context of these +procedures. For more information on message handlers at F1 and E1 layers, +please refer to the respective [F1 documentation](../F1AP/F1-design.md) and [E1 +documentation](../E1AP/E1-design.md). + +For more information on these procedures, please also refer to 3GPP TS 38.401 +(NG-RAN Architecture Description) and O-RAN.WG5.C.1-v11 (NR C-plane profile). + +A lot of the following diagrams would show an exchange between CU-CP, DU, and +UE, in which the CU-CP forwards an "RRC Message" to the UE via an F1AP DL RRC +Message Transfer through the DU, and correspondingly receives the "RRC Message +Answer", as follows: + +```mermaid +sequenceDiagram + participant ue as UE + participant du as DU + participant cucp as CU-CP + cucp->>du: F1AP DL RRC Msg Transfer (RRC Message) + du->>ue: RRC Message + ue->>du: RRC Message Answer + du->>cucp: F1AP UL RRC Msg Transfer (RRC Message Answer) +``` + +To better utilize horizontal space, these exchanges have been collapsed as +follows, but should be read as the above exchange: + +```mermaid +sequenceDiagram + participant ue as UE + participant du as DU + participant cucp as CU-CP + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Message) + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Message Answer) +``` + +## Initial connection setup/Registration + +This sequence diagram shows the principal steps for an initial UE connection. +This can either happen through a _Registration Request_ (e.g., UE connects +"from flight mode"), or a _Service Request_ (i.e., UE connects after leaving +coverage). Both requests are handled similarly by the gNB, and basically +distinguish themselves, from the point of view of the gNB, by having PDU +sessions in the NGAP Initial Context Setup Request present (Service Request) or +not (Registration Request, with following PDU Session Resource Setup Request +procedure). + +```mermaid +sequenceDiagram + participant ue as UE + participant du as DU + participant cucp as CU-CP + participant cuup as CU-UP + participant amf as AMF + + ue->>du: Msg1/Preamble + du->>ue: Msg2/RAR + ue->>cucp: F1AP Initial UL RRC Msg Tr (RRC Setup Req, in Msg3) + Note over cucp: rrc_handle_RRCSetupRequest() + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Setup, in Msg4) + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Setup Complete) + Note over cucp: rrc_handle_RRCSetupComplete() +%% TODO: when is RRC connected? + cucp->>amf: NGAP Initial UE Message (NAS Registration/Service Req) + Note over amf,ue: NAS Authentication Procedure (see 24.501) + Note over amf,ue: NAS Security Procedure (see 24.501) + amf->>cucp: NGAP Initial Context Setup Req + Note over cucp: rrc_gNB_process_NGAP_INITIAL_CONTEXT_SETUP_REQ() + Note over cucp: rrc_gNB_generate_SecurityModeCommand() + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Security Mode Command) + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Security Mode Complete) + Note over cucp: rrc_gNB_decode_dcch() (inline) + opt No UE Capabilities present + Note over cucp: rrc_gNB_generate_UECapabilityEnquiry() + cucp->>ue: F1AP DL RRC Msg Transfer (RRC UE Capability Enquiry) + ue->>cucp: F1AP UL RRC Msg Transfer (RRC UE Capability Information) + Note over cucp: handle_ueCapabilityInformation() + end + opt PDU Sessions in NGAP Initial Context Setup Req present + Note over cucp: trigger_bearer_setup() + cucp->>cuup: E1AP Bearer Context Setup Req + cuup->>cucp: E1AP Bearer Context Setup Resp + Note over cucp: rrc_gNB_process_e1_bearer_context_setup_resp() + cucp->>du: F1AP UE Context Setup Req + du->>cucp: F1AP UE Context Setup Resp + Note over cucp: rrc_CU_process_ue_context_setup_response() + Note over cucp: e1_send_bearer_updates() + cucp->>cuup: E1AP Bearer Context Modification Req + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Reconfiguration) + cuup->>cucp: E1AP Bearer Context Modification Resp + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Reconfiguration Complete) + Note over cucp: handle_rrcReconfigurationComplete() + end + Note over cucp: rrc_gNB_send_NGAP_INITIAL_CONTEXT_SETUP_RESP() + cucp->>amf: NGAP Initial Context Setup Resp (NAS Registration/Service Complete) +``` + +Note that if no PDU session is present in the NGAP Initial UE Context Setup +Req, no F1AP UE Context Setup will be observed during this initial phase. + +If there is no PDU session set up during NGAP Initial Context Setup Req, the UE +typically requests a PDU session(s) through a NAS procedure, which is basically +the same code paths as the above optional PDU Session setup during an NGAP +Initial Context Setup procedure: + +```mermaid +sequenceDiagram + participant ue as UE + participant du as DU + participant cucp as CU-CP + participant cuup as CU-UP + participant amf as AMF + + ue->>cucp: F1AP UL RRC Msg Transfer (RRC UL Information Transfer) + cucp->>amf: NGAP UL NAS Transport (NAS PDU Session Establishment Req) + amf->>cucp: NGAP PDU Session Resource Setup Req (NAS PDU Session Establishment Accept) + Note over cucp: rrc_gNB_process_NGAP_PDUSESSION_SETUP_REQ() + Note over cucp: trigger_bearer_setup() + cucp->>cuup: E1AP Bearer Context Setup Req + cuup->>cucp: E1AP Bearer Context Setup Resp + Note over cucp: rrc_gNB_process_e1_bearer_context_setup_resp() + cucp->>du: F1AP UE Context Setup Req + du->>cucp: F1AP UE Context Setup Resp + Note over cucp: rrc_CU_process_ue_context_setup_response() + Note over cucp: e1_send_bearer_updates() + cucp->>cuup: E1AP Bearer Context Modification Req + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Reconfiguration + NAS PDU Session Establishment Accept) + cuup->>cucp: E1AP Bearer Context Modification Resp + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Reconfiguration Complete) + Note over cucp: handle_rrcReconfigurationComplete() + Note over cucp: rrc_gNB_send_NGAP_PDUSESSION_SETUP_RESP() + cucp->>amf: NGAP PDU Session Resource Setup Resp +``` + +## Reestablishment + +The following sequence diagram shows the principal steps during a +reestablishment request. When handling the RRC Reestablishment Request at the +CU-CP, it notably checks if this UE is already known, if the UE is still at the +same DU as it used to be previously (might change because of, or despite +handover), and other validation checks. If all checks pass, the CU-CP continues +with the reestablishment procedure; if any check fails, the CU-CP tries to +release the old UE at the AMF, and continues with the "normal" connection setup +(registration/service request) described above. + +```mermaid +sequenceDiagram + participant ue as UE + participant du as DU + participant cucp as CU-CP + participant cuup as CU-UP + participant amf as AMF + + ue->>du: Msg1/Preamble + du->>ue: Msg2/RAR + ue->>du: Msg3 w/ RRC Reestabishment Request (old C-RNTI/PCI) + Note over du: DU creates UE context for new RNTI + du->>cucp: F1AP Initial UL RRC Msg Tr (RRC Reestab Req, in Msg3) + Note over cucp: rrc_handle_RRCReestablishmentRequest() + alt UE known and at the original DU + Note over cucp: rrc_gNB_generate_RRCReestablishment()
SRB1 PDCP reestablishment + cucp->>du: F1AP DL RRC Msg Tr (old gNB-DU-UE ID) + Note over du: Reuse configuration of and delete old UE
(in dl_rrc_message_transfer()) + du->>ue: RRC Reestablishment + ue->>du: RRC Reestablishment Complete + du->>cucp: F1AP UL RRC Msg Tr (RRC Reestab Complete) + Note over cucp: handle_rrcReestablishmentComplete() + Note over cucp: cuup_notify_reestablishment() + cucp->>cuup: E1AP Bearer Context Modification Req + cucp->>ue: F1AP DL RRC Msg Transfer (RRC Reconfiguration) + cuup->>cucp: E1AP Bearer Context Modification Resp + ue->>cucp: F1AP UL RRC Msg Transfer (RRC Reconfiguration Complete) + Note over cucp: handle_rrcReestablishmentComplete() + else Fallback* + cucp->>amf: NGAP UE Context Release Request + Note over cucp: rrc_gNB_generate_RRCSetup() + Note over ue,amf: Continue with connection setup (registration/service request) + end +``` + +## Handover + +The basic handover (HO) structure is as follows. In order to support various +handover "message passing implementation" (F1AP, NGAP, XnAP), RRC employs +callbacks to signal HO Accept (`ho_req_ack()`), HO Success (`ho_success()`), +and HO Cancel (`ho_cancel()`). These can be used to trigger the corresponding +functionality based on mentioned "message passing implementation". + +The following sequence diagram shows the basic functional execution of a +successful handover in the case of an F1 handover. Note the callbacks as +mentioned above: + +```mermaid +sequenceDiagram + participant ue as UE + participant sdu as source DU + participant tdu as target DU + participant cucp as CU-CP + participant cuup as CU-UP + + Note over ue,sdu: UE active on source DU + alt HO triggered through A3 event + ue->>sdu: RRC Measurement Report + sdu->>cucp: F1AP UL RRC Msg Transfer (RRC Measurement Report) + Note over cucp: Handover decision (A3 event trigger) + else Manual Trigger + Note over cucp: Handover decision (e.g., telnet) + end + Note over cucp: nr_rrc_trigger_f1_ho() ("on source CU") + Note over cucp: nr_initiate_handover() ("on target CU") + cucp->>tdu: F1AP UE Context Setup Req + Note over tdu: Create UE context + tdu->>cucp: F1AP UE Context Setup Resp (incl. CellGroupConfig) + Note over cucp: rrc_CU_process_ue_context_setup_response() ("on target CU") + Note over cucp: cuup_notify_reestablishment() + cucp->>cuup: E1AP Bearer Context Modification Req + cucp-->>cucp: callback: ho_req_ack() + Note over cucp: nr_rrc_f1_ho_acknowledge() ("on source CU") + cucp->>sdu: F1AP Context Modification Req (RRC Reconfiguration) + cuup->>cucp: E1AP Bearer Context Modification Resp + sdu->>ue: RRC Reconfiguration + sdu->>cucp: F1AP Context Modification Resp + Note over sdu: Stop scheduling UE + Note over ue: Resync + Note over ue,tdu: RA (Msg1 + Msg2) + ue->>tdu: RRC Reconfiguration Complete + tdu->>cucp: F1AP UL RRC Msg Transfer (RRC Reconfiguration Complete) + Note over cucp: handle_rrcReconfigurationComplete() ("on target CU") + cucp-->>cucp: callback: ho_success() + Note over cucp: nr_rrc_f1_ho_complete() ("on source CU") + cucp->>sdu: F1AP UE Context Release Command + sdu->>cucp: F1AP UE Context Release Complete + Note over ue,tdu: UE active on target DU +``` + +# Structures + +## Cells + +OAI 5G RRC does not actually handle multiple cells as of now, but multiple DUs, +each being limited to one cell. + +Cell-related data is stored in `nr_rrc_du_container_t`, and kept in a tree +indexed by the SCTP association ID. + +## CU-UPs + +CU-UP information is stored in `nr_rrc_cuup_container_t`, and kept in a tree +indexed by the SCTP association ID. + +## Transactions + +The RRC keeps track of ongoing transaction (RRC procedures) through a per-UE +array `xids`, which is indexed with a transaction ID `xid` in `[0,3]` to keep +track of ongoing transactions. Upon RRC Reconfiguration Complete, these IDs are +deleted. + +Note that while 38.331 requires only one RRC transaction to happen at a time, +the 5G RRC does not actually ensure this; it only tries to prevent it by +chaining of transactions and some checks. For instance, the Security Mode +procedure is followed by a UE capability procedure, and some procedures are not +executed if others are ongoing (ex.: handover if there is reconfiguratio). +However, it might be possible to trigger a procedure while another is ongoing. + +As of now, no queueing mechanims exists to ensure only one operation is +ongoing, which would likely also simplify the code. + +## Handover + +Handover-related data is stored in a per-UE structure of type +`nr_handover_context_t`. It is a pointer and only set during handover +operation. This data structure has in turn two pointers, one to the source CU +(`nr_ho_source_cu_t`), and one to the target CU (`nr_ho_target_cu_t`). In F1, +both are present. In N2 and Xn, only one pointer is supposed to be set a the +corresponding CU. + +`nr_ho_source_cu_t` contains notably a function pointer `ho_cancel` for +handover cancel. `nr_ho_target_cu_t` contains function pointers `ho_req_ack` +for handover request acknowledge and `ho_success` for handover success. As can +be seen in the sequence diagram above, either the "target CU" or "source CU" +needs to do an operation, and a "switch" from target to source CU is done using +these function pointers. For instance, in F1, the handover request acknowledge +function pointers merely calls another (RRC) function which triggers a +reconfiguration. In the case of N2, the handover request acknowledge function +pointer should trigger the NGAP Handover Request Acknowledge, and the handover +success function pointer should trigger the NGAP Handover Success message. diff --git a/doc/RRC/rrc-usage.md b/doc/RRC/rrc-usage.md new file mode 100644 index 0000000000..668c106a0d --- /dev/null +++ b/doc/RRC/rrc-usage.md @@ -0,0 +1,99 @@ +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](./rrc-dev.md). + +[[_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](../F1-design.md) and [E1AP page](../E1AP/E1-design.md). + +# 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-DU) assoc_id 8: nrCellID 12345678, PCI 0, SSB ARFCN 641280 + TDD: band 78 ARFCN 640008 SCS 30 (kHz) PRB 106 +``` + +i.e., an index (`[1]`), the DU ID and it's name, the SCTP association ID +(`assoc_id 8`, cf. UE information), and DU specific information for the cell +(cell ID, physical cell identity/PCI, the SSB frequency in ARFCN notation, the +band and Point A ARFCN, subcarrier spacing/SCS, and the number of resource +blocks/PRB). Only one cell per DU is supported. + +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](../F1-design.md) for information about the F1 split. +See [E1 documentation](../E1AP/E1-design.md) 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 + +- `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: false): enable the use of the SDAP layer. If + deactivated, a transparent SDAP header is prepended to packets, but no + further processing is being done. + +### UE-specific configuration + +- `um_on_default_drb` (default: false): use RLC UM instead of RLC AM on default + bearers +- `drbs` (default: 0): the number of DRBs to allocate for a UE, only useful for + do-ra or phy-test testing + +### Neighbor-gNB configuration + + TBD + +Refer to the [handover tutorial](../handover-tutorial.md) for more information.