@@ -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:
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.
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
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`.
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=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:
[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.
