From a87df90504fef4d789d8e958a28c7f57f5995c4d Mon Sep 17 00:00:00 2001 From: Robert Schmidt Date: Fri, 31 May 2024 09:00:13 +0200 Subject: [PATCH] Add documentation for physical simulators --- doc/README.md | 1 + doc/TESTBenches.md | 1 + doc/physical-simulators.md | 135 +++++++++++++++++++++++++++++++++++++ 3 files changed, 137 insertions(+) create mode 100644 doc/physical-simulators.md diff --git a/doc/README.md b/doc/README.md index 1c4413a8a5..c4957566b7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -51,6 +51,7 @@ There is some general information in the [OpenAirInterface Gitlab Wiki](https:// - [How to use the positioning reference signal (PRS)](./RUN_NR_PRS.md) - [How to use device-to-device communication (D2D, 4G)](./d2d_emulator_setup.txt) - [How to run with E2 agent](../openair2/E2AP/README.md) +- [How to run the physical simulators](./physical-simulators.md) Legacy unmaintained files: - [`L2NFAPI_NOS1.md`](./L2NFAPI_NOS1.md), [`L2NFAPI_S1.md`](./L2NFAPI_S1.md): diff --git a/doc/TESTBenches.md b/doc/TESTBenches.md index 9ea8534faa..028736d195 100644 --- a/doc/TESTBenches.md +++ b/doc/TESTBenches.md @@ -169,6 +169,7 @@ information on how the images are built. ~4G-LTE ~5G-NR - cluster (`Asterix-OC-oaicicd-session` resource), tests in OpenShift Cluster - unitary simulators (`nr_dlsim`, etc.) + - see [`./physical-simulators.md`](./physical-simulators.md) for an overview - [RAN-RF-Sim-Test-4G](https://jenkins-oai.eurecom.fr/job/RAN-RF-Sim-Test-4G/) ~4G-LTE - obelix (eNB, lteUE, OAI EPC) diff --git a/doc/physical-simulators.md b/doc/physical-simulators.md new file mode 100644 index 0000000000..f52b2e371d --- /dev/null +++ b/doc/physical-simulators.md @@ -0,0 +1,135 @@ +This document describes the physical simulators, also called "unitary +simulators", or short "physims". + +[[_TOC_]] + +# Introduction + +There are several unitary simulations for the physical layer, testing +individual L1 transport/control channels using Monte-Carlo simulations, for +instance: + +- `nr_pucchsim` for 5G PUCCH, +- `nr_dlsim` for 5G DLSCH/PDSCH, +- `nr_prachsim` for 5G PRACH, +- `dlsim` for 4G DLSCH/PDSCH, etc. + +These simulators constitute the starting point for testing any new code in the +PHY layer, and are required tests to be performed before committing any new +code to the repository, in the sense that all of these should compile and +execute correctly. They provide estimates of the transport block error rates +and HARQ thoughput, DCI error rates, etc. The simulators reside in +`openair1/SIMULATION/LTE_PHY` and `openair1/SIMULATION/NR_PHY`. For instance, +`nr_dlsim` is built from `openair1/SIMULATION/NR_PHY/dlsim.c`. + +Further unitary simulation of the coding subsystem components also exists in +`openair1/PHY/CODING/TESTBENCH`, e.g., `ldpctest` for encoding/decoding of +LDPC. + +These are the simulators known to work properly and tested in CI: +- 4G: `dlsim`, `ulsim` +- 5G: `nr_dlsim`, `nr_ulsim`, `nr_dlschsim`, `nr_ulschsim`, `ldpctest`, + `nr_pbchsim`, `nr_prachsim`, `nr_pucchsim`, `polartest`, `smallblocktest`, + `nr_psbchsim` (sidelink) + +# How to run + +You first have to build simulators: + +```bash +cd openairinterface5g/ +. oaienv # important for the run_exec_autotests.bash script +cd cmake_targets/ +./build_oai --ninja -P +``` + +This builds the simulators in the default build directory `ran_build/build` +(all paths given here are relative to `cmake_targets/` in the root of +`openairinterface5g/`). To run all simulators in this default build directory +of above `build_oai` invocation, run the `run_exec_autotests.bash` script: +```bash +autotests/run_exec_autotests.bash +``` + +This runs all simulations as defined in `autotests/test_case_list.xml`. + +To run a group of tests, you can specify the group using `-g`. You can also +specify the build directory, after building the simulators, which, for the +default directory, is: + +```bash +autotests/run_exec_autotests.bash -g "nr_dlsim.basic" -d ran_build/build/ +``` + +This will run the `nr_dlsim.basic` group, as listed in +`autotests/test_case_list.xml`. + +## How to interpret the output + +From the output, you can see the invoked tests, its parameters, and the log files. +Example: + +``` +[user@oai cmake_targets]$ autotests/run_exec_autotests.bash -g "nr_dlsim.basic" -d ran_build/build/ +[...] +Test case nr_dlsim.basic match found in group +name = nr_dlsim.basic +Description = nr_dlsim Test cases. (Test1: 106 PRB), + (Test2: 217 PRB), + (Test3: 273 PRB), + (Test4: HARQ test 25% TP 4 rounds), + (Test5: HARQ test 33% TP 3 rounds), + (Test6: HARQ test 50% TP 2 rounds), + (Test7: 25 PRBs, 15 kHz SCS) +main_exec = ran_build/build//nr_dlsim +main_exec_args = -n100 -R106 -b106 -s5 + -n100 -R217 -b217 -s5 + -n100 -R273 -b273 -s5 + -n100 -s1 -S2 -t25 + -n100 -s1 -S2 -t33 + -n100 -s5 -S7 -t50 + -n100 -m0 -e0 -R25 -b25 -i 2 1 0 +search_expr_true = PDSCH test OK +search_expr_false = segmentation fault|assertion|exiting|fatal +tags = test1 test2 test3 test4 test5 test6 test7 +nruns = 3 +i = PDSCH test OK +Test1: 106 PRB +Executing test case nr_dlsim.basic.test1, Run Index = 1, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_1 +Executing test case nr_dlsim.basic.test1, Run Index = 2, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_2 +Executing test case nr_dlsim.basic.test1, Run Index = 3, Execution Log file = /home/oai/openairinterface5g/cmake_targets/autotests/log/nr_dlsim.basic/test.nr_dlsim.basic.test1.run_3 +[...] +nr_dlsim.basic.test1 RUN = 1 Result = PASS +nr_dlsim.basic.test1 RUN = 2 Result = PASS +nr_dlsim.basic.test1 RUN = 3 Result = PASS +execution nr_dlsim.basic.test1 {Test1: 106 PRB} Run_Result = " Run_1 =PASS Run_2 =PASS Run_3 =PASS" Result = PASS +``` + +You see: +- the `Description` of the test cases (here, 7 tests) +- the executable that is used, and the parameters (`main_exec` and + `main_exec_args`), for instance `-n100 -R106 -b106 -s5` for `Test1` +- what is the condition for a successful test +- where are the log files +- if the tests passed or not `PASS`, otherwise `FAIL` and a summary for the + three runs. + +## How to change the parameters + +You can modify the parameters in `autotests/test_case_list.xml`. To learn about +their meaning, run the simulator manually with flag `-h` ("help"). For +instance, for the above run, it would be + +```bash +ran_build/build/nr_dlsim -h +``` + +## How to change the code + +You can modify the source files to adapt to your needs. For instance, for +`nr_dlsim` above, refer to file `openair1/SIMULATION/NR_PHY/dlsim.c`. + +# CI + +These tests are run in this pipeline: +[RAN-PhySim-Cluster](https://jenkins-oai.eurecom.fr/job/RAN-PhySim-Cluster/).