Add 5G RRC documentation
This commit is contained in:
Robert Schmidt
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user