Add 5G RRC documentation

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()<br />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<br />(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.

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.