maki/openairinterface5g
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/e1-issue-712' into integration_2024_w04

Browse Source
This commit is contained in:
Jaroslava Fiedlerova
2024-01-26 10:15:56 +01:00
parent a0de76ca96 f3f8e8403b
commit 3cc671897d
14 changed files with 508 additions and 214 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/BUILD.md
+2
View File
@@ -63,6 +63,8 @@ Calling the `build_oai` script with the `-h` option gives the list of all availa
- `--ninja` is to use the `ninja` build tool, which speeds up compilation.
- `-c` is to clean the workspace and force a complete rebuild.
`build_oai` also provides various options to enable runtime error checkers, i.e. sanitizers in order to find various types of bugs in the codebase and eventually enhance the stability of the OAI softmodems. Refer to [sanitizers.md](./dev_tools/sanitizers.md) for more details.
## Installing dependencies
Install all dependencies by issuing the `-I` option. To install furthermore libraries for optional libraries, use the `--install-optional-packages` option. The `-I` option will also install dependencies for an SDR when paired with `-w`. For instance, in order to install all dependencies and the ones for USRP, run:
doc/E1-design.md
+62 -13
View File
@@ -17,17 +17,22 @@ connection setup only in split-mode, the rest is the same for CU):
sequenceDiagram
participant c as CUCP
participant u as CUUP
u->c: SCTP connection setup (in split mode)
u->>c: E1AP Setup Request
Note over c: Execute rrc_gNB_process_e1_setup_req()
c->>u: E1AP Setup Response
Note over c,u: E1 Setup Procedure
u->c: SCTP connection setup (in split mode)
u->>c: E1 Setup Request
Note over c: Execute rrc_gNB_process_e1_setup_req()
c->>u: E1 Setup Response
c-->>u: E1 Setup Failure
Note over c,u: E1 Bearer Context Setup Procedure
Note over c: Receives PDU session setup request from AMF
c->>u: Bearer Context Setup Request
Note over u: Execute e1_bearer_context_setup()<br/>Configure DRBs and create GTP Tunnels for F1-U and N3
u->>c: Bearer Context Setup Response
Note over c: Execute rrc_gNB_process_e1_setup_req()<br/>Sends F1-U UL TNL info to DU and receives DL TNL info
Note over c,u: E1 Bearer Context Modification (CU-CP Initiated) Procedure
c->>u: Bearer Context Modification Request
Note over u: Execute e1_bearer_context_modif()<br/>Updates GTP Tunnels with received info
u->>c: Bearer Context Modification Response
@@ -40,19 +45,63 @@ sequenceDiagram
Note over c: Execute rrc_gNB_process_e1_bearer_context_release_cplt()
```
The files that implement the callback towards these handlers are in
- `cucp_cuup_direct.c`: integrated CU (for CP=>UP messages)
- `cucp_cuup_e1ap.c`: E1 split mode (for CP=>UP messages)
- `cuup_cucp_direct.c`: integrated CU (for UP=>CP messages)
- `cuup_cucp_e1ap.c`: E1 split mode (for UP=>CP messages)
The implementation of callbacks towards these handlers is distributed across the following file, depending on the operating mode:
| Mode | CP=>UP messages |UP=>CP messages |
| --------------| --------------------|--------------------|
| Integrated CU | `cucp_cuup_direct.c`|`cuup_cucp_direct.c`|
| E1 Split | `cucp_cuup_e1ap.c` |`cuup_cucp_e1ap.c` |
As long as concerns E1 Interface Management Procedures, the code flow of request messages towards northbound looks like this:
```mermaid
sequenceDiagram
participant r as RRC
participant c as CUCP
participant u as CUUP
Note over u: E1AP_CUUP_task (SCTP Handler)
Note over u: ASN1 encoder
u->>c: e.g. E1 Setup Request (SCTP)
Note over c: E1AP_CUCP_task (SCTP Handler)
Note over c: ASN1 decoder
c->>r: E1AP_SETUP_REQ (ITTI)
Note over r: TASK_RRC_GNB (RRC Handler)
r->>c: E1AP_SETUP_RESP (ITTI)
Note over c: E1AP_CUCP_task (E1AP Callback)
Note over c: ASN1 encoder
c->>u: e.g. E1 Setup Response/Failure
Note over u: E1AP_CUUP_task (SCTP Handler)
Note over u: ASN1 decoder
```
# 2. Running the E1 Split
The setup is assuming that all modules are running on the same machine. The user can refer to the [F1 design document](./F1-design.md) for local deployment of the DU.
## 2.1 Configuration File
The gNB is started based on the node type that is specified in the configuration file. To start a gNB instance in CUCP or CUUP, the `tr_s_preference` should be set to "f1" and the config member `E1_INTERFACE` should be present in the config file. The `type` parameter within the `E1_INTERFACE` should be set to `cp`, and executable `nr-softmodem` should be used to run a CU-CP. The type should be `up` and executable `nr-cuup` should be used to run the CU-UP. Further, there are the parameters `ipv4_cucp` and `ipv4_cuup` to specify the IP addresses of the respective network functions.
The gNB is started based on the node type that is specified in the configuration file. The following parameters must be configured accordingly.
For CUCP, a typical `E1_INTERFACE` config looks like
On either CUCP and CUUP:
* The southbound transport preference `gNBs.[0].tr_s_preference` set to `f1`
* config section `E1_INTERFACE` should be present
On the CU-CP:
* `type` parameter within the `E1_INTERFACE` should be set to `cp`
On the CU-UP:
* `type` parameter within the `E1_INTERFACE` should be set to `up`
Executables:
* executable `nr-softmodem` to run a CU-CP
* executable `nr-cuup` to run the CU-UP
In the `E1_INTERFACE` configuration section, the parameters `ipv4_cucp` and `ipv4_cuup` must be configured to specify the IP addresses of the respective network functions.
For CUCP, a typical `E1_INTERFACE` config looks like:
```
E1_INTERFACE =
(
@@ -64,7 +113,7 @@ E1_INTERFACE =
)
```
For CUUP, it is
For CUUP, it is:
```
E1_INTERFACE =
(
@@ -77,7 +126,7 @@ E1_INTERFACE =
```
One could take an existing CU configuration file and add the above parameters to run the gNB as CUCP or CUUP.
The CUUP uses the IP address specified in `local_s_address` for F1-U and `GNB_IPV4_ADDRESS_FOR_NGU` for N3 links. Note that `local_s_address` is under `gNBs` and `GNB_IPV4_ADDRESS_FOR_NGU` is part of the `NETWORK_INTERFACES` config member.
The CUUP uses the IP address specified in `gNBs.[0].local_s_address` for F1-U and `GNB_IPV4_ADDRESS_FOR_NGU` for N3 links. Note that `local_s_address` is under `gNBs` and `GNB_IPV4_ADDRESS_FOR_NGU` is part of the `NETWORK_INTERFACES` config member.
Alternatively, you can use the config files `ci-scripts/conf_files/gnb-cucp.sa.f1.conf` and `ci-scripts/conf_files/gnb-cuup.sa.f1.conf`.
doc/F1-design.md
+6 -6
View File
@@ -20,15 +20,15 @@ The F1 interface is the functional split of 3GPP between the CU (centralized
unit: PDCP, RRC, SDAP) and the DU (distributed unit: RLC, MAC, PHY). It is
standardized in TS 38.470 - 38.473 for 5G NR. No equivalent for 4G exists.
We assume that each DU handles only one cell. Multiple DUs connected to one CU
We assume that each DU handles only one cell. Multiple DUs connected to one CU
are supported. Mobility over F1 is not yet supported.
# Control plane status (F1-C)
## Implementation Status
Note that OAI uses F1 "internally". That means, that even if you run a
monolithic gNB, the internal information exchange uses F1. You can therefore
Note that OAI uses F1 "internally". That means, that even **if you run a
monolithic gNB, the internal information exchange uses F1**. You can therefore
expect that everything working in a monolithic deployment should also work in
F1. The current implementation is based on R16.3.
@@ -118,13 +118,13 @@ see [this `docker-compose` file](../ci-scripts/yaml_files/5g_f1_rfsimulator/dock
The rules to decide if a config triggers a start of a DU, CU, or monolithic
gNB, are, in order:
1. If the `MACRLCs` section lists `f1` as northbound transport preference
1. If the `MACRLCs` section lists `f1` as **northbound transport preference**
(`tr_n_preference`), it is a DU.
2. If the `gNBs` section lists `f1` as a southound transport preference
2. If the `gNBs` section lists `f1` as a **southound transport preference**
(`tr_s_preference`), it is a CU.
3. It is a (monolithic) gNB.
## Configuration of F1 IP/port information
## Local network deployment of F1
For a local deployment, you should update the following fields.
We assume that the CU will bind on `192.168.70.129` towards the core,
doc/FEATURE_SET.md
+13 -5
View File
@@ -191,22 +191,30 @@ Furthermore, the gNB and UE support
## gNB F1AP
- Integration of F1AP messages and procedures for the control plane exchanges between the CU and DU entities according to 38.473 Rel. 16
- F1 Setup request/response
- F1 Setup request/response/failure
- F1 DL/UL RRC message transfer
- F1 Initial UL RRC message transfer
- F1 UE Context setup request/response
- F1 UE Context modification request/response
- F1 UE Context release
- F1 UE Context modification required
- F1 UE Context release req/cmd/complete
- F1 gNB CU configuration update
- Interface with RRC
- Interface with gtp-u (tunnel creation/handling for F1-U interface)
## gNB E1AP
- Integration of E1AP messages and procedures for exchange between CU-CP and CU-UP according to 38.463 Rel. 16
- gNB-CU-UP E1 Setup Setup request/response
- E1 Bearer Context Setup
- Integration of E1AP messages and procedures for exchange between CU-CP and CU-UP according to TS 38.463 Rel. 16
- E1 Setup (gNB-CU-UP initiated)
- E1 Setup Request
- E1 Setup Response
- E1 Setup Failure
- E1 Bearer Context Setup (gNB-CU-CP initiated)
- E1 Bearer Context Setup Request
- E1 Bearer Context Setup Response
- Bearer Context Modification (gNB-CU-CP initiated)
- E1 Bearer Context Modification Request
- E1 Bearer Context Modification Response
- Interface with RRC and PDCP
## gNB GTP-U
doc/README.md
+1
View File
@@ -21,6 +21,7 @@
- [BUILD.md](./BUILD.md): how to build the sources
- [cross-compile.md](./cross-compile.md): how to cross-compile OAI for ARM
- [clang-format.md](./clang-format.md): how to format the code
- [sanitizers.md](./dev_tools/sanitizers.md): how to run with ASan/UBSan/MemSAN/TSan
- [environment-variables.md](./environment-variables.md): the environment variables used by OAI
There is some general information in the [OpenAirInterface Gitlab Wiki](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/home)
doc/dev_tools/sanitizers.md
+63
View File
@@ -0,0 +1,63 @@
<table style="border-collapse: collapse; border: none;">
<tr style="border-collapse: collapse; border: none;">
<td style="border-collapse: collapse; border: none;">
<a href="http://www.openairinterface.org/">
<img src="./../images/oai_final_logo.png" alt="" border=3 height=50 width=150>
</img>
</a>
</td>
<td style="border-collapse: collapse; border: none; vertical-align: center;">
<b><font size = "5">OAI Build Procedures</font></b>
</td>
</tr>
</table>
[[_TOC_]]
# Sanitize options in `build_oai`
The `build_oai` script provides various [Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) to add run-time instrumentation to the code and enable runtime error checkers, i.e. sanitizers, in order to help find various types of bugs in the codebase and eventually enhance the stability of the OAI softmodems. The following sanitizers can be enabled using different build options:
## Address Sanitizer (ASAN)
[Address Sanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) is enabled using the `--sanitize-address` option or its shorthand `-fsanitize=address`. It serves as a fast memory error detector and helps detect issues like out-of-bounds accesses, use-after-free bugs, and memory leaks.
### Run OAI Softmodem with ASAN on
It is necessary to add the envinronment variable `LD_LIBRARY_PATH` to the run command, e.g.:
```
cd cmake_targets/ran_build/build
sudo LD_LIBRARY_PATH=. ./nr-softmodem ...
```
## Undefined Behavior Sanitizer (UBSAN)
[Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) (UBSAN) is a runtime undefined behavior checker. It uses compile-time instrumentation to catch undefined behavior by inserting code that performs specific checks before operations that may cause it. UBSAN can be activated with the `--sanitize-undefined` option or `-fsanitize=undefined`.
UBSAN offers a range of suboptions that enable precise checks for various types of undefined behavior at runtime. These suboptions can be set by tweaking the [CMakeLists.txt](../../CMakeLists.txt) file. Here is an overview of some key suboptions:
* `-fsanitize=shift`: Enables checks for the result of shift operations, with suboptions for base and exponent.
* `-fsanitize=integer-divide-by-zero`: Detects integer division by zero.
* `-fsanitize=null`: Enables pointer checking, issuing an error message when dereferencing a NULL pointer or binding a reference to a NULL pointer.
* `-fsanitize=signed-integer-overflow`: Detects signed integer overflow.
* `-fsanitize=bounds`: Instruments array bounds, detecting various out-of-bounds accesses.
* `-fsanitize=alignment`: Checks the alignment of pointers when dereferenced or when a reference is bound to an insufficiently aligned target.
* `-fsanitize=object-size`: Checks out-of-bounds pointer accesses.
* `-fsanitize=float-divide-by-zero`: Detects floating-point division by zero.
## Memory Sanitizer
To enable [Memory Sanitizer](https://clang.llvm.org/docs/MemorySanitizer.html), use the `--sanitize-memory` option or `-fsanitize=memory`. It requires clang and is incompatible with ASAN and UBSAN. Building with this option helps catch issues related to uninitialized memory reads.
To build with Memory Sanitizer, use the following command:
```
CC=/usr/bin/clang CXX=/usr/bin/clang++ ./build_oai ... --sanitize-memory
```
## Thread Sanitizer
[Thread Sanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html) can be activated using the `--sanitize-thread` option or `-fsanitize=thread`. This sanitizer helps identify data races and other threading-related issues in the code.
# Summary of Sanitizer Options
- `--sanitize`: Shortcut for using both ASAN and UBSAN.
- `--sanitize-address` or `-fsanitize=address`: Enable ASAN on all targets.
- `--sanitize-undefined` or `-fsanitize=undefined`: Enable UBSAN on all targets.
- `--sanitize-memory` or `-fsanitize=memory`: Enable Memory Sanitizer on all targets (requires clang).
- `--sanitize-thread` or `-fsanitize=thread`: Enable Thread Sanitizer on all targets.