From f5501ed72568f524d2707364a55da2d095d7b056 Mon Sep 17 00:00:00 2001 From: Shubhika Garg Date: Thu, 18 Sep 2025 21:08:09 +0200 Subject: [PATCH] docs: enhance readability of Notes, Cautions, Issues, and Attention sections - Standardized appearance of Notes, Cautions, Issues, and Attention blocks for better clarity --- doc/L1SIM.md | 4 ++-- doc/L2NFAPI.md | 8 ++++---- doc/L2NFAPI_NOS1.md | 11 ++++++----- doc/L2NFAPI_S1.md | 11 ++++++----- doc/NR_NFAPI_archi.md | 3 +-- doc/RUNMODEM.md | 2 +- doc/RUN_NR_PRS.md | 2 +- doc/TESTBenches.md | 8 ++++---- doc/TESTING_OAI_NSA_COTS_UE.md | 2 +- doc/UnitTests.md | 2 +- doc/data_recording.md | 2 +- doc/nfapi.md | 12 ++++++------ doc/time_management.md | 4 ++-- doc/tuning_and_security.md | 2 +- 14 files changed, 37 insertions(+), 36 deletions(-) diff --git a/doc/L1SIM.md b/doc/L1SIM.md index a78d3c328a..d315ea9c23 100644 --- a/doc/L1SIM.md +++ b/doc/L1SIM.md @@ -12,7 +12,7 @@ -**Note: unless you know what you are doing, you likely do not need this! +> **Note: Unless you know what you are doing, you likely do not need this!** Rather, you are probably looking for the [RFsimulator](../radio/rfsimulator/README.md)!** @@ -20,7 +20,7 @@ oaisim has been scraped and replaced by the same programs that are used for the real-time operation, `lte-softmodem` and `lte-uesoftmodem`. This uses the IF4p5 fronthaul protocol to achieve the communication. -Context: oaisim used to be a simulation mode inside OAI to emulate an eNB and +> Context: oaisim used to be a simulation mode inside OAI to emulate an eNB and multiple UEs. [[_TOC_]] diff --git a/doc/L2NFAPI.md b/doc/L2NFAPI.md index 282e6eeedf..5577e4821f 100644 --- a/doc/L2NFAPI.md +++ b/doc/L2NFAPI.md @@ -18,11 +18,11 @@ This simulator allows to test L2 and above Layers using the nFAPI interface. The UE executable is able to "simulate" multiple UEs in order to stimulate the scheduler in the eNB. -**This simulator is available starting the `v1.0.0` release on the `master` branch.** +> **This simulator is available starting the `v1.0.0` release on the `master` branch.** -**2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** +> **2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** -**2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** +> **2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** Currently the Continuous Integration process is validating this simulator the following way: @@ -38,7 +38,7 @@ Normally it should be fine to run both executables on the same host using the `l 2. [No S1 -- eNB and UE on 2 hosts](L2NFAPI_NOS1.md) -**2022/03/08: Starting the `2022.w01` tag on the `develop` branch, the L2 nFAPI simulation is using a proxy.** +> **2022/03/08: Starting the `2022.w01` tag on the `develop` branch, the L2 nFAPI simulation is using a proxy.** ### EpiSci's Documentation A more detailed tutorial is available on the [EpiSci GitHub Repository](https://github.com/EpiSci/oai-lte-5g-multi-ue-proxy#readme). diff --git a/doc/L2NFAPI_NOS1.md b/doc/L2NFAPI_NOS1.md index 1c11dd0d71..e71e34e27d 100644 --- a/doc/L2NFAPI_NOS1.md +++ b/doc/L2NFAPI_NOS1.md @@ -12,9 +12,9 @@ -**2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** +> **2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** -**2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** +> **2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** **Table of Contents** @@ -33,7 +33,7 @@ Example of L2 nFAPI Simulator testing environment: -Note that the IP addresses are indicative and need to be adapted to your environment. +> Note that the IP addresses are indicative and need to be adapted to your environment. # 2. Retrieve the OAI eNB-UE source code # @@ -115,7 +115,7 @@ You can repeat the operation for as many users you want to test with. # 4. Setup of the Configuration files # -**CAUTION: both proposed configuration files resides in the ci-scripts realm. You can copy them but you CANNOT push any modification on these 2 files as part of an MR without informing the CI team.** +> **CAUTION: both proposed configuration files resides in the ci-scripts realm. You can copy them but you CANNOT push any modification on these 2 files as part of an MR without informing the CI team.** ## 4.1. The eNB Configuration file ## @@ -143,7 +143,8 @@ MACRLCs = ( ); ``` -If you are testing more than 16 UEs, a proper setting on the RUs is necessary. **Note that this part is NOT present in the original configuration file**. +If you are testing more than 16 UEs, a proper setting on the RUs is necessary. +> **Note that this part is NOT present in the original configuration file**. ``` RUs = ( diff --git a/doc/L2NFAPI_S1.md b/doc/L2NFAPI_S1.md index ed0ac907db..77555fd7dd 100644 --- a/doc/L2NFAPI_S1.md +++ b/doc/L2NFAPI_S1.md @@ -12,9 +12,9 @@ -**2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** +> **2022/03/08: CAUTION, THIS TUTORIAL IS NO LONGER VALID on the `develop` branch after the `2022.w01` tag.** -**2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** +> **2022/03/08: CAUTION, THE LAST VALID TAG on `develop` branch is `2021.w51_c`.** **Table of Contents** @@ -32,7 +32,7 @@ Example of L2 nFAPI Simulator testing environment: -Note that the IP addresses are indicative and need to be adapted to your environment. +> Note that the IP addresses are indicative and need to be adapted to your environment. # 2. Prepare the EPC # @@ -120,7 +120,7 @@ You can repeat the operation for as many users you want to test with. # 5. Setup of the Configuration files # -**CAUTION: both proposed configuration files resides in the ci-scripts realm. You can copy them but you CANNOT push any modification on these 2 files as part of an MR without informing the CI team.** +> **CAUTION: both proposed configuration files resides in the ci-scripts realm. You can copy them but you CANNOT push any modification on these 2 files as part of an MR without informing the CI team.** ## 5.1. The eNB Configuration file ## @@ -148,7 +148,8 @@ MACRLCs = ( ); ``` -If you are testing more than 16 UEs, a proper setting on the RUs is necessary. **Note that this part is NOT present in the original configuration file**. +If you are testing more than 16 UEs, a proper setting on the RUs is necessary. +> **Note that this part is NOT present in the original configuration file**. ``` RUs = ( diff --git a/doc/NR_NFAPI_archi.md b/doc/NR_NFAPI_archi.md index 8e6647f73c..f7b3e50994 100644 --- a/doc/NR_NFAPI_archi.md +++ b/doc/NR_NFAPI_archi.md @@ -55,8 +55,7 @@ These loops are autonomous in their thread waiting incoming message. ## P7 interface main loop -- Note: As explained before, the P7 reception loop is the same as the P5 messages when not using socket-based - communication +> **Note:** As explained before, the P7 reception loop is the same as the P5 messages when not using socket-based communication In this case, when the P5 interface receives appropriate message, it starts the p7 interface by launching a thread diff --git a/doc/RUNMODEM.md b/doc/RUNMODEM.md index d9730c1f27..fb803f82ed 100644 --- a/doc/RUNMODEM.md +++ b/doc/RUNMODEM.md @@ -419,7 +419,7 @@ iperf -uc 10.0.1.2 -B 10.0.1.1 -i1 -t10 -b1M ``` to send data from the gNB down to the UE. -Note that this does not work if both interfaces are on the same host. We +> Note that this does not work if both interfaces are on the same host. We recommend to use two different hosts, or at least network namespaces, to route traffic through the gNB/UE tunnel. diff --git a/doc/RUN_NR_PRS.md b/doc/RUN_NR_PRS.md index 4fedf1f063..bfff5b4cbf 100644 --- a/doc/RUN_NR_PRS.md +++ b/doc/RUN_NR_PRS.md @@ -52,7 +52,7 @@ prs_config = ( To TURN OFF PRS, set `NumPRSResources=0` in gNB `prs_config` section. nrUE config has `Active_gNBs` to specify number of active gNBs transmitting PRS signal simultaneously. Find the help string for PRS parameters in `openair2/COMMON/prs_nr_paramdef.h`

# gNB in `phy-test` mode -Note that `numactl` is only needed if you run on a NUMA architecture with more than 1 CPU. In this case it should be installed on Linux using command `sudo apt-get install -y numactl` +> Note that `numactl` is only needed if you run on a NUMA architecture with more than 1 CPU. In this case it should be installed on Linux using command `sudo apt-get install -y numactl` Also check the numa nodes USRP’s are connected to, using the following command: diff --git a/doc/TESTBenches.md b/doc/TESTBenches.md index 8674103a1a..42558449b3 100644 --- a/doc/TESTBenches.md +++ b/doc/TESTBenches.md @@ -28,8 +28,8 @@ | rocket | Rocket | gNB (n77) | B210 (31F8010) | | raspix | Raspix | COTS UE | Quectel RM520N | -Note: The available resources, and their current usage, is indicated here: -- [Lockable resources of jenkins-oai](https://jenkins-oai.eurecom.fr/lockable-resources/): +> **Note:** The available resources, and their current usage, is indicated here: +> - [Lockable resources of jenkins-oai](https://jenkins-oai.eurecom.fr/lockable-resources/): "New" Jenkins, i.e., with RAN-Container-Parent ## Testbenches @@ -348,7 +348,7 @@ right image (Ubuntu or RHEL)! #### Core dump in a file -**This is not recommended, as files could pile up and fill the system disk +> **This is not recommended, as files could pile up and fill the system disk completely!** Prefer another method further down. If the core pattern is a path: it should at least include the time in the @@ -371,7 +371,7 @@ sudo coredumpctl dump > /tmp/coredump #### Core dump via abrt (automatic bug reporting tool) -TBD: use the documentation page for the moment. +> TBD: use the documentation page for the moment. #### Core dump via apport diff --git a/doc/TESTING_OAI_NSA_COTS_UE.md b/doc/TESTING_OAI_NSA_COTS_UE.md index f53e7fe9a1..d045189d50 100644 --- a/doc/TESTING_OAI_NSA_COTS_UE.md +++ b/doc/TESTING_OAI_NSA_COTS_UE.md @@ -37,7 +37,7 @@ Our code might not work with all 5G phones yet, but we are constantly improving * Simcom SIMCOM8200EA * Quectel RM500Q-GL -Note1: In the version we have at Eurecom, you need to set the PLMN to 50501, and you also need to change the firmware to "11.0.0 (RD1A.201105.003.B1, Nov 2020, EU carriers)" (see [Factory Images for Nexus and Pixel Devices](https://developers.google.com/android/images)) +> **Note1:** In the version we have at Eurecom, you need to set the PLMN to 50501, and you also need to change the firmware to "11.0.0 (RD1A.201105.003.B1, Nov 2020, EU carriers)" (see [Factory Images for Nexus and Pixel Devices](https://developers.google.com/android/images)) ## Repository diff --git a/doc/UnitTests.md b/doc/UnitTests.md index 76cfe7bee1..408e7db619 100644 --- a/doc/UnitTests.md +++ b/doc/UnitTests.md @@ -75,7 +75,7 @@ if(ENABLE_TESTS) endif() ``` -Note that this might get more complicated, e.g., typically you will have to +> Note that this might get more complicated, e.g., typically you will have to link some library into the executable with `target_link_libraries()`, or pass some option to the test program. diff --git a/doc/data_recording.md b/doc/data_recording.md index 8d4680a4cf..546eed44af 100644 --- a/doc/data_recording.md +++ b/doc/data_recording.md @@ -230,7 +230,7 @@ Run NR gNB Softmodem in RF Simulation: ``` sudo ./cmake_targets/ran_build/build/nr-softmodem -O ./targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.band78.sa.fr1.106PRB.1x1.usrpx410_3300MHz.conf --gNBs.[0].min_rxtxtime 6 --rfsim --rfsimulator.serveraddr server --phy-test -d --T_stdout 2 --T_nowait ``` -Note: User needs to change the name of gNB config file to your gNB config file. +> **Note:** User needs to change the name of gNB config file to your gNB config file. It is worth mentioning that the possible values for T-tracer control options - --T_stdout option: default 1 diff --git a/doc/nfapi.md b/doc/nfapi.md index 5f2d8a35da..e7972014ca 100644 --- a/doc/nfapi.md +++ b/doc/nfapi.md @@ -72,7 +72,7 @@ If the type is `VNF`, you have to modify the `MACRLCs.tr_s_preference` - `MACRLCs.local_s_portd` (local south port for control): VNF's P5 local port - `MACRLCs.remote_s_portd` (remote south port for data): PNF's P7 remote port -Note that any L1-specific section (`L1s`, `RUs`, +> Note that any L1-specific section (`L1s`, `RUs`, RFsimulator-specific/IF7.2-specific configuration or other radios, if necessary) will be ignored and can be deleted. @@ -86,7 +86,7 @@ If the type is `PNF`, you have to modify modify the `L1s.tr_n_preference` - `L1s.local_n_portd` (local north port for data): PNF's P7 local port - `L1s.remote_n_portd` (remote north port for data): VNF's P7 remote port -Note that this file should contain additional, L1-specific sections (`L1s`, +> Note that this file should contain additional, L1-specific sections (`L1s`, `RUs` RFsimulator-specific/IF7.2-specific configuration or other radios, if necessary). @@ -111,7 +111,7 @@ can proceed as follows: `pnf.conf`, or provide them on the command line for the PNF. - to run, proceed as described in the quick start above. -Note: all L1-specific options have to be passed to the PNF, and remaining +> **Note:** all L1-specific options have to be passed to the PNF, and remaining options to the VNF. ## Transport mechanisms between VNF and PNF @@ -123,8 +123,8 @@ other: The socket type may be changed by editing `nfapi_pnf_config_create()` and `nfapi_vnf_config_create()`, in both of which `_this->sctp = ;` indicate whether SCTP or regular sockets are to be used. Note: The - value of `_this->sctp` **must** be the same on the VNF and PNF. + 1>;` indicate whether SCTP or regular sockets are to be used. + > **Note:** The value of `_this->sctp` **must** be the same on the VNF and PNF. 2. Intel WLS Lib, which uses DPDK to achieve a shared memory communication between components. 3. nvIPC, which is used exclusively for the NVIDIA Aerial L1. Thus, it is only applicable for the VNF. @@ -244,7 +244,7 @@ Run the O-DU over GDB sudo -E gdb -ex run --readnever --args ./odu/odu -Note: If you see the following prompt in GDB +> **Note:** If you see the following prompt in GDB This GDB supports auto-downloading debuginfo from the following URLs: diff --git a/doc/time_management.md b/doc/time_management.md index c6424b3847..b03173e05e 100644 --- a/doc/time_management.md +++ b/doc/time_management.md @@ -153,11 +153,11 @@ time_management = { } ``` -Note that the time management module is flexible. It's possible to +> Note that the time management module is flexible. It's possible to configure more complex setups. For example the time source can be a gNB and several UEs can be connected as client. -One could also write a simple program acting as a time source and distributing +> One could also write a simple program acting as a time source and distributing time to everyone (one or several gNB, several UEs). ## Programming API diff --git a/doc/tuning_and_security.md b/doc/tuning_and_security.md index 7e415e783d..ce3405df1a 100644 --- a/doc/tuning_and_security.md +++ b/doc/tuning_and_security.md @@ -75,7 +75,7 @@ considerations. Rather, consider giving specific capabilities as outlined below. Read `capabilities(7)` (`man 7 capabilities`) for more information on each of the below capabilities. -Note that we tested this using 5G executables; 4G should work, but have not +> Note that we tested this using 5G executables; 4G should work, but have not been tested as extensively. If in doubt, run eNB/lteUE using `sudo`. The below comments on capabilities apply in general as well; however, 4G executable might not warn about missing capabilities or just fail.