Merge remote-tracking branch 'origin/update-split-doc-runmodem' into integration_2026_w14 (!3948)

Update doc: split RUNMODEM.md, clarify USRP-specific workarounds

This reworks the documentation:
- split up RUNMODEM.md into separate documents for gNB, UE, NTN
- explains USRP workaround and patches
- makes a standalone UE doc file that explains UE-specific configuration
  & modes
- better explains physical simulators
- adds a document on tracy
- cleanup

doc/BUILD.md

@@ -2,9 +2,9 @@
 
 # OAI Build Procedures
 
-[[_TOC_]]
+This page describes how to build OAI.
 
-This page is valid on tags starting from **`2019.w09`**.
+[[_TOC_]]
 
 ## Overview
 
@@ -12,7 +12,11 @@ The [OAI EPC](https://github.com/OPENAIRINTERFACE/openair-epc-fed/blob/master/do
 
 OAI softmodem sources, which aim to implement 3GPP compliant UEs, eNodeB and gNodeB can be downloaded from the Eurecom [gitlab repository](./GET_SOURCES.md).
 
-Sources come with a build script [build_oai](../cmake_targets/build_oai) located at the root of the `openairinterface5g/cmake_targets` directory. This script is developed to build the oai binaries (executables,shared libraries) for different hardware platforms, and use cases.
+The historically convential way to build OAI is
+[build_oai](../cmake_targets/build_oai) located at the root of the
+`openairinterface5g/cmake_targets` directory. This script is developed to build
+the oai binaries (executables,shared libraries) for different hardware
+platforms, and use cases, and is a wrapper on top of `cmake`.
 
 The main oai binaries, which are tested by the Continuous Integration process are:
 
@@ -39,6 +43,81 @@ The oai softmodem supports many use cases, and new ones are regularly added. Mos
 - s1, noS1
 - all simulators as the rfsimulator, the L2 simulator, with exception of PHY simulators, which are distinct executables. 
 
+## Dependencies
+
+TODO.
+
+## Running `cmake` directly
+
+As mentioned, `build_oai` is a wrapper on top of `cmake`. It is therefore
+possible, and now recommended, to run `cmake` directly. To build all of OAI in
+a default install:
+
+```
+cd openairinterface5g
+mkdir build
+cd build
+cmake .. -GNinja
+ninja
+```
+
+Alternatively, let cmake generate the directory:
+
+```
+cd openairinterface5g
+cmake -B build -G Ninja
+cmake --build build
+```
+
+To build additional libraries, e.g., telnetsrv, do the following:
+```bash
+cmake .. -GNinja -DENABLE_TELNETSRV=ON
+ninja telnetsrv
+```
+
+A list of all libraries can be seen using `ccmake ..` or `cmake-gui ..`.
+
+The default target directory of `build_oai` is the following, for historical
+reasons:
+```bash
+cd openairinterface5g/cmake_targets/ran_build/build
+cmake ../../.. -GNinja
+ccmake ../../..
+cmake-gui ../../..
+```
+
+You can of course use all standard cmake/ninja/make commands in this directory,
+assuming you already build with `build_oai`. For instance, to compile sources
+after modifying the code, do
+```
+cd cmake_targets/ran_build/build
+ninja
+```
+
+### cmake presets
+
+CMake presets are common project configure options. See [here](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html).
+
+Configure presets:
+
+ - `default`: Configure compilation with default options
+ - `tests`: Same as above but `ENABLE_TESTS` and `SANITIZE_ADDRESS` is ON
+
+Build presets:
+
+ - `5gdefault`: Build the software for NR rfsimulator test
+ - `default`: same as 5gdefault
+ - `4gdefault`: Build the software for LTE rfsimulator test
+ - `tests`: build all unit tests
+
+To configure using configuration preset:
+
+    cmake --preset <preset_name>
+
+To build using a build preset:
+
+    cmake --build --preset <preset_name>
+
 ## Running `build_oai`
 
 ### List of options
@@ -176,60 +255,6 @@ Some libraries have further dependencies and might not build on every system:
 - `websrv`: npm and others
 - `ldpc_aal`: DPDK with patch
 
-## Running `cmake` directly
-
-`build_oai` is a wrapper on top of `cmake`. It is therefore possible to run `cmake` directly. An example using `ninja`: to build all "main targets" for 5G, excluding additional libraries:
-```
-cd openairinterface5g
-mkdir build && cd build
-cmake .. -GNinja && ninja nr-softmodem nr-uesoftmodem nr-cuup params_libconfig coding rfsimulator ldpc
-```
-
-To build additional libraries, e.g., telnetsrv, do the following:
-```bash
-cmake .. -GNinja -DENABLE_TELNETSRV=ON && ninja telnetsrv
-```
-
-A list of all libraries can be seen using `ccmake ..` or `cmake-gui ..`.
-
-It is currently not possible to build all targets in the form of `cmake ..
--GNinja && ninja`: currently, SDRs are always exposed, even if you don't have
-the dependencies, and some targets are simply broken. Again, `build_oai` list
-all targets that it builds, and you can use them with `ninja`
-
-The default target directory of `build_oai` is the following, for historical reasons:
-```bash
-cd openairinterface5g/cmake_targets/ran_build/build
-cmake ../../.. -GNinja
-ccmake ../../..
-cmake-gui ../../..
-```
-You can of course use all standard cmake/ninja/make commands in this directory.
-
-### cmake presets
-
-CMake presets are common project configure options. See [here](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html).
-
-Configure presets:
-
- - `default`: Configure compilation with default options
- - `tests`: Same as above but ENABLE_TESTS and SANITIZE_ADDRESS is ON
-
-Build presets:
-
- - `5gdefault`: Build the software for NR rfsimulator test
- - `default`: same as 5gdefault
- - `4gdefault`: Build the software for LTE rfsimulator test
- - `tests`: build all unit tests
-
-To configure using configuration preset:
-
-    cmake --preset <preset_name>
-
-To build using a build preset:
-
-    cmake --build --preset <preset_name>
-
 ## Cross Compile
 
 If you want to use cross-compiler on x86 platform for aarch64 version, please refer the [cross-compile.md](./cross-compile.md) for more information.

doc/NR_SA_Tutorial_COTS_UE.md

@@ -201,7 +201,7 @@ With devices like the USRP N300 and especially the X300, there is noise in the D
 There are two possible solution that can be enabled in OAI:
 
 * `--tune-offset`: it consists in shifting away the operational bandwidth to avoid the center frequency
-* `ul_prbblacklist`: can be used to define specific PRBs that should not be used for uplink scheduling
+* `gNBs.[0].ul_prbblacklist`: can be used to define specific PRBs that should not be used for uplink scheduling
 
 A spectrum clean from the noisy PRBs will eventually result in an enhanced UL throughput.
 

doc/NR_SA_Tutorial_OAI_nrUE.md

@@ -179,39 +179,23 @@ uicc0 = {
 }
 ```
 
-| **Parameter** | **Description** | **Default Value** |
-|---------------|-----------------|-------------------|
-| **IMSI** | Unique identifier for the UE within the mobile network. Used by the network to identify the UE during authentication. It ensures that the UE is correctly identified by the network. | 001010000000001 |
-| **key** | Cryptographic key shared between the UE and the network, used for encryption during the authentication process. | `fec86ba6eb707ed08905757b1bb44b8f` |
-| **OPC** | Operator key for the Milenage Authentication and Key Agreement algorithm used for encryption during the authentication process. | Ensures secure communication between the UE and the network by matching the encryption keys. | `C42449363BBAD02B66D16BC975D77CC1` |
-| **DNN** | _Deprecated_: Specifies the name of the data network the UE wishes to connect to, similar to an APN in 4G networks. | `oai` |
-| **NSSAI** | _Deprecated_: Allows the UE to select the appropriate network slice, which provides different QoS. | `1` |
-| **pdu_sessions** | list of PDU sessions to request | empty array (no PDU session) |
+Further information about the meaning of these parameters is described in the
+[dedicated nrUE configuration page](./runmodem-nrue.md).
 
-Note that DNN and NSSAI parameters are deprecated, and `pdu_sessions` should be
-used. If the `pdu_sessions` array is present, DNN and NSSAI are ignored.
-
-Each element within the `pdu_sessions` array takes the following parameters.
-Multiple PDU sessions can be requested.
-
-| **Parameter** | **Description** | **Default Value** |
-|---------------|-----------------|-------------------|
-| `id`          | ID of the PDU session to request | index of the current element (1..16) |
-| `type`        | Type of the PDU session to request (allowed: `IPv4`, `IPv6`, `IPv4v6`, `Ethernet` | `IPv4` |
-| `dnn`         | Specifies the name of the data network the UE wishes to connect to | `oai` |
-| `nssai_sst`   | Slice Service Type to request (1=eMBB, 2=URLLC, 3=mMTC) | `1` |
-| `nssai_sd`   | Slice Differentiator to request | `0xffffff` (meaning "no SD") |
-
-The UE configuration must match the one of the network's AMF. The nrUE can connect by default to OAI CN5G with no need to provide the configuration file.
-
-When running the `nr-uesoftmodem`, one can specify the nrUE configuration file using the `-O` option. E.g.:
+The UE configuration must match the one of the network's AMF. When running the
+`nr-uesoftmodem`, one can specify the nrUE configuration file using the `-O`
+option. E.g.:
 
 ```bash
 sudo ./nr-uesoftmodem --rfsim --rfsimulator.[0].serveraddr 127.0.0.1 -r 106 --numerology 1 --band 78 -C 3619200000 -O ~/nrue.uicc.conf
 ```
-The CL option `--uicc0.imsi`  can override the IMSI value in the configuration file if necessary (e.g. when running multiple UEs): `--uicc0.imsi  001010000000001`.
 
-More details available at [ci-scripts/yaml_files/5g_rfsimulator/README.md](../ci-scripts/yaml_files/5g_rfsimulator/README.md).
+The command line option `--uicc0.imsi`  can override the IMSI value in the
+configuration file if necessary (e.g. when running multiple UEs): `--uicc0.imsi
+001010000000001`.
+
+More details can also be found at
+[ci-scripts/yaml_files/5g_rfsimulator/README.md](../ci-scripts/yaml_files/5g_rfsimulator/README.md).
 
 **Note:** From tag `2024.w45`, OAI nrUE runs by default in standalone (SA) mode.  
 In earlier versions the default mode was non-standalone (NSA).  

doc/README.md

@@ -18,10 +18,6 @@ Beware if you previously pulled the `develop` branch that your repository may be
 - [FEATURE_SET.md](./FEATURE_SET.md): lists supported features
 - [GET_SOURCES.md](./GET_SOURCES.md): how to download the sources
 - [BUILD.md](./BUILD.md): how to build the sources
-- [code-style-contrib.md](./code-style-contrib.md): overall working practices, code style, and review process
-- [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
 - [tuning_and_security.md](./tuning_and_security.md): performance and security considerations
 
@@ -34,20 +30,21 @@ There is some general information in the [OpenAirInterface Gitlab Wiki](https://
     * [OAI gNB with COTS UE](./NR_SA_Tutorial_COTS_UE.md)
     * [OAI NR-UE](./NR_SA_Tutorial_OAI_nrUE.md)
     * [Multiple OAI NR-UE with RFsimulator](./NR_SA_Tutorial_OAI_multi_UE.md)
-- [RUNMODEM.md](./RUNMODEM.md): Generic information on how to
+- [RUNMODEM.md](./RUNMODEM.md): Information on how to run the gNB
     * Run simulators
     * Run with hardware
-    * Specific OAI modes (phy-test, do-ra, noS1)
     * (5G) Using SDAP and custom DRBs
     * IF setups and arbitrary frequencies
     * MIMO
+- [nrUE-specific configuration and modes](./runmodem-nrue.md)
+    * Specific OAI modes (phy-test, do-ra, noS1)
 - [How to run OAI with O-RAN 7.2 FHI](./ORAN_FHI7.2_Tutorial.md)
 - [How to run a 5G-NSA setup](./TESTING_OAI_NSA_COTS_UE.md)
 - [How to run a 4G setup using L1 simulator](./L1SIM.md) _Note: we recommend the RFsimulator_
 - [How to use the L2 simulator](./L2NFAPI.md)
 - [How to use the OAI channel simulator](../openair1/SIMULATION/TOOLS/DOC/channel_simulation.md)
+- [How to run an NTN setup](./ntn-configuration.md)
 - [How to use GPU-accelerated channel simulation](../openair1/SIMULATION/TOOLS/DOC/gpu_acceleration.md)
-- [How to use multiple BWPs](./RUN_NR_multiple_BWPs.md)
 - [How to run OAI-VNF and OAI-PNF](./nfapi.md): how to run the FAPI/nFAPI split,
   including some general remarks on FAPI/nFAPI.
 - [How to use the positioning reference signal (PRS)](./RUN_NR_PRS.md)
@@ -133,7 +130,13 @@ The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
 
 ## Developer tools
 
+- [code-style-contrib.md](./code-style-contrib.md): overall working practices, code style, and review process
+- [cross-compile.md](./cross-compile.md): how to cross-compile OAI for ARM
+- [clang-format.md](./clang-format.md): how to format the code. See also the
+  next entry for an error detection tool.
 - [formatting](../tools/formatting/README.md) is a clang-format error detection tool
+- [sanitizers.md](./dev_tools/sanitizers.md): how to run with ASan/UBSan/MemSAN/TSan
 - [iwyu](../tools/iwyu/README.md) is a tool to detect `#include` errors
 - [docker-dev-env](../tools/docker-dev-env/README.md) is a ubuntu24 docker development environment
+- [performance analysis with tracy](./dev_tools/tracy.md)
 - [doc_best_practices.md](./doc_best_practices.md): overall best practices for writing documentations

doc/TESTING_OAI_NSA_COTS_UE.md

 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-STATUS 2020/10/15 : added External Resources section and links  
+# How to run an NSA setup with eNB/gNB
 
-**Table of Contents**
+This page details how to run an non-standalone (NSA) setup, using an eNB and
+gNB (both OAI). It might be outdated, but still contains valuable information.
 
 [[_TOC_]]
 
@@ -227,6 +228,7 @@ Execute:
 
 ```
 
+You should see the X2 messages in Wireshark and at the eNB.
 
 ## Test Case
 

doc/dev_tools/tracy.md

+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+# Performance analysis with the Tracy profiler
+
+[[_TOC_]]
+
+## Overview
+
+From the Tracy manual:
+
+> Tracy is a real-time, nanosecond resolution hybrid frame and sampling
+> profiler that you can use for remote or embedded telemetry of games and other
+> applications. It can profile CPU, GPU, memory allocations, locks, context
+> switches, [...]
+
+- Sources are on [Github](https://github.com/wolfpld/tracy)
+- There is a [web demo](https://tracy.nereid.pl/)
+- You can [watch an intro video](https://youtu.be/ghXk3Bk5F2U?t=37)
+- You can [read the manual](https://github.com/wolfpld/tracy/releases/download/v0.13.1/tracy.pdf)
+
+## OAI Integration
+
+To enable Tracy, compile `-DTRACY_ENABLE=ON` in cmake. Note that `build_oai`
+has no native switch, but you can use `--cmake-opt -DTRACY_ENABLE=ON` instead.
+
+Furthermore, you will need the Tracy profiler:
+
+- Windows hosts: There is a precompiled `tracy-profiler.exe` on Github
+- Linux hosts: Compile tracy-profiler from source as described in the manual.
+
+Start the OAI executable you want to profile. Then, open the profiler, and
+click on connect to connect to the executable.
+
+It is also possible to collect data from within docker containers:
+
+- Open port 8086.
+- To collect CPU data, make sure that you run docker with `--privileged --mount
+  "type=bind,source=/sys/kernel/debug,target=/sys/kernel/debug,readonly" --user
+  0:0 --pid=host` or provide the corresponding options in docker-compose.
+
+## Instrumentation
+
+Instrumentation is done via the header `common/instrumentation.h`. A couple of
+places in OAI have been instrumented already, search for the macros mentioned
+in `common/instrumentation.h`.
+
+In short, main features already in use:
+
+- Measure specific code regions by surrounding them with `TracyCZone(ctx, true);`
+  and `TracyCZoneEnd(ctx);`.
+- Record individual "Tracy frames" (in the OAI context, that's likely one 4G/5G
+  slot) with `TracyCFrameMark;`
+- Plot values using `TracyCPlot(name, val);`
+
+More information about these macros can be found in the manual.
+
+Make sure to link `utils` into the static library you are modifying to get
+tracy header definitions.

doc/physical-simulators.md

@@ -19,6 +19,7 @@ Physims are essential for:
 * Debugging and evaluating new PHY code in isolation
 * Regression testing
 * Ensuring correctness before merging new contributions into the repository
+* Performance measurements
 
 These tests are run automatically as part of the following
 pipelines:
@@ -54,9 +55,11 @@ Example:
 openair1/SIMULATION/NR_PHY/dlsim.c
 ```
 
+The actual tests are defined in `openair1/SIMULATION/tests/CMakeLists.txt`.
+
 ## How to Run Simulators Using `ctest`
 
-### Option 1: Using CMake
+### Option 1: Using CMake (Recommended)
 
 Build the simulators and tests using the dedicated cmake option, then run
 `ctest` which will run all registered tests.
@@ -102,6 +105,65 @@ parallel, type
 
     ctest -L nr_ulschsim -j 4
 
+Or you run all 5G tests that `-R` pattern-match on a `dl` pattern:
+
+    ctest -R nr_dl
+
+Or you can see the test parameters that would be run for `nr_ulsim` without
+actually running the tests
+
+    ctest -R nr_ulsim -N -V
+
+Note that the lines `Test command:` show the actual shell code that will be
+executed. For increased flexibility, tests are run indirectly through a cmake
+script `openair1/SIMULATION/tests/RunTimedTest.cmake` that not only runs the
+test, but can also analyze its output. The actual command is passed via a
+variable `TEST_CMD` that lists the executable and parameters as a semicolon
+(`;`) delimited list. See further below for an example of how to read this.
+
+## Performance evaluation
+
+Some simulators, notably `nr_dlsim` and `nr_ulsim`, provide the possibility to
+show performance metrics via option `-P`.
+
+To discover predefined tests, you can search for test cases that define `-P`
+like so (note the leading `;` to limit to the test case executable command line
+as `-P` is also used by the cmake scripts themselves):
+
+     $ ctest -N -V | grep Test\ command: | grep -- ';-P' | tail -n1
+     213: Test command: /usr/bin/cmake "-DTEST_CMD=/home/richie/oai/build/nr_ulsim;-P;-n300;-b14;-I15;-i;0,1;-g;C,l;-t70;-u;1;-m16;-R106;-r106;-U;1,1,1,2;-W2;-y2;-z4;-s11.2;-S11.2" "-DCHECK_SCRIPT=/home/richie/oai/openair1/SIMULATION/tests/analyze-timing.sh" "-P" "/home/richie/oai/openair1/SIMULATION/tests/RunTimedTest.cmake"
+
+From this, we see that the tests can be run like so, in the same directory as
+cmake:
+
+    ./nr_ulsim -P -n300 -b14 -I15 -i 0,1 -g C,l -t70 -u 1 -m16 -R106 -r106 -U 1,1,1,2 -W2 -y2 -z4 -s11.2 -S11.2
+
+After invoking the tests, you should see processing times for UE TX and gNB RX:
+
+```
+UE TX
+|__ PHY_PROC_TX                            246.01 us (300 trials)		( 73.80 total [ms])
+
+[...]
+
+gNB RX
+Total PHY proc rx                           2587.88 us (300 trials)
+ Statistics std=301.10, median=0.00, q1=0.00, q3=0.00 µs (on 0 trials)
+|__ RX PUSCH time                          875.68 us (300 trials)		(262.70 total [ms])
+```
+
+You can see average per-trial processing time in micro-seconds, and the total
+test times for the 300 trials (`-n`) in milliseconds.
+
+Use `grep` to find the places where these stats are printed, and to see which
+variable in the stacks traces the measurement. For `RX PUSCH time`, we can
+identify the variable `rx_pusch_stats`:
+
+```
+$ git grep -n 'RX PUSCH time' ../
+../openair1/SIMULATION/NR_PHY/ulsim.c:1714:      printStatIndent(&gNB->rx_pusch_stats, "RX PUSCH time");
+```
+
 ## Adding a New Physim Test
 
 To define a new test or modify existing ones, update the following file:

openair1/SIMULATION/tests/CMakeLists.txt

@@ -42,6 +42,7 @@ function(add_physim_test test_name test_description test_exec)
     ENVIRONMENT "LD_LIBRARY_PATH=.;TEST_DESCRIPTION=${test_description}"
   )
   set_tests_properties(${test_name} PROPERTIES CHECK_COUNT 0)
+  add_dependencies(tests ${test_exec})
 endfunction()
 
 function(check_threshold testname threshold condition)

radio/USRP/README.md

@@ -15,6 +15,20 @@ Example files can be found in the `ci-scripts/conf_files/` directory with a
 `usrp` in the name, for instance
 [`gnb.sa.band78.106prb.usrpn310.ddsuu-2x2.conf`](../../ci-scripts/conf_files/gnb.sa.band78.106prb.usrpn310.ddsuu-2x2.conf).
 
+## Build
+
+The OAI USRP driver in leverages the [USRP Hardware
+Driver](https://github.com/EttusResearch/uhd) to interface with a USRP.
+`build_oai` has support for installing UHD from package manager (Ubuntu) or from
+source (other distributions or on request). See [`BUILD.md`](./BUILD.md) for
+more information.
+
+Note that OAI comes with a patch for UHD as found in `cmake_targets/tools/`.
+This patch is automatically applied when building UHD from source with
+`build_oai`, and improves the TX/RX switching times of UHD. If you cannot apply
+this patch, the `--continuous-tx` option can be an alternative as described
+further below.
+
 ## Configuration
 
 The USRP can be configured in the RU section of the config file. The field
@@ -95,6 +109,45 @@ RUs = (
 
 Hint: You cannot see TX/RX spread over multiple USRPs, if you use `internal` as a refrence of the clock and time source.
 
-Furthur information about synchronization on the USRP N3xx devices can be found here: https://kb.ettus.com/Using_Ethernet-Based_Synchronization_on_the_USRP%E2%84%A2_N3xx_Devices
+Furthur information about synchronization on the USRP N3xx devices can be found
+[in the knowledge base article "Using Ethernet-Based
+Synchronization"](https://kb.ettus.com/Using_Ethernet-Based_Synchronization_on_the_USRP%E2%84%A2_N3xx_Devices).
 
 When combining this with the multi USRP feature you can create a distributed antenna array with only 1 channel used at each USRP.
+
+## Further considerations
+
+### TX/RX switching times
+
+When using TDD (e.g., in 5G/NR band n78), the USRP has to frequently switch
+between TX and RX directions. Certain USRPs, e.g., B210, might be too slow for
+this, which can result in degraded radio link performance, especially in 5G/NR
+operation. In order to get a good performance, there are two workarounds:
+
+1. At runtime: you can use the `--continuous-tx` options at gNB/nrUE. This will
+   continuously send TX samples, also when the current link direction is to
+   receive, and we found this to improve the radio link.
+2. At compile/build time: apply the UHD patch described further above, which
+   obliveates the need for `--continuous-tx`.
+
+### Three-quarter sampling
+
+Not all sampling rates can be used with (a) given master sampling rate(s) of a
+USRP. Depending on the bandwidth, you might employ (or not) three-quarter
+sampling using option `-E`. As a basic rule of thump, 40MHz on B210 needs `-E`,
+whereas most other bandwidths on USRPs do not (bu there are exceptions).
+
+### Noise on DC carrier
+
+Some USRPs have noise on the DC carrier, which can degrade the radio signal.
+There are two workarounds:
+
+1. Use the `--tune-offset` parameter, which shifts the operating frequency of
+   the USRP to avoid the use of the DC carrier.
+2. `--tune-offset` has a maximum shift frequency. If half the bandwidth is
+   larger than `--tune-offset`, the DC carrier will still lie within the
+   carrier. In this case, you can also mask these RBs by using
+   `gNBs.[0].ul_prbblacklist` in the configuration file.
+
+You can also find more information on this in the [5G/NR gNB with COTS UE
+tutorial](./NR_SA_Tutorial_COTS_UE.md).