<!-- SPDX-License-Identifier: CC-BY-4.0 -->

# How to use sanitizers with OAI

[[_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 ...
```

#### Possible problems

On some systems with specific ASan versions, executing a program compiled with
ASan might fail with an error `DEADLYSIGNAL`, or simply a segmentation fault.
Note that since OAI compiles and runs some programs _during compilation_ (for
code generation), typically already the build is impacted.

The issue is related to Address Space Layout Randomization (ASLR) settings
in Linux, a security feature designed to make it more difficult for attackers
to predict the locations of processes in memory.  In this case, it is possible
to avoid the bug by running

```
sudo sysctl vm.mmap_rnd_bits=30
```

which reduces the number of bits for memory mappings used to randomize mmap
base addresses. _This reduces the security of the system._

### 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.
