docs/README

   1 A. Directory Structure :
   2 ------------------------
   3 1. l2/build/ : contains files required to compile the code
   4    a. common : contains individual module's makefile
   5    b. odu    : contains main makefile to generate an executable binary
   6    c. scripts: contains scripts for logging, installing netconf libraries and starting netopeer server
   7    d. config : contains the configuration files
   8    e. yang   : contains the YANG modules
   9
  10 2. l2/docs/  : contains README and other configuration files for building docs
  11
  12 3. l2/src/ : contains layer specific source code
  13    a. 5gnrmac  : MAC source code
  14    b. 5gnrrlc  : RLC source code
  15    c. cm       : common, environment and interface files
  16    d. cu_stub  : Stub code for CU
  17    e. du_app   : DU application and F1 code
  18    f. mt       : wrapper functions over OS
  19    g. phy_stub : Stub code for Physical layer
  20    h. rlog     : logging module
  21    i. O1       : O1 module
  22
  23
  24 B. Pre-requisite for Compilation :
  25 ----------------------------------
  26 1. Linux 32-bit/64-bit machine
  27 2. GCC version 4.6.3 and above
  28 3. Install LKSCTP
  29    a. On Ubuntu : sudo apt-get install -y libsctp-dev
  30    b. On CentOS : sudo yum install -y lksctp-tools-devel
  31 4. Install PCAP:
  32    a. On ubuntu : sudo apt-get install -y libpcap-dev
  33    b. On CentOS : sudo yum install -y libpcap-devel
  34
  35
  36 C. Pre-requisite for O1 Interface (Required only if run with O1 interface enabled)
  37 -----------------------------------------------------------------------------------
  38 1. Setup netconf server
  39
  40     a. Add new netconf user (login with root user or use sudo and run following script)
  41        $cd l2/build/scripts
  42        $sudo ./add_netconf_user.sh
  43
  44     b. Install netconf packages.
  45        $chmod +x install_lib_O1.sh
  46        $sudo ./install_lib_O1.sh -c
  47
  48 2. Update the configuration according to your setup.
  49
  50    $cd l2/build/config
  51
  52    a. Open the startup_config.xml and edit the desired IP and Port for CU, DU and RIC.
  53    b. Open the nacm_config.xml and edit the desired user name to provide the access to that user.
  54    c. Open the netconf_server_ipv6.xml and edit the desired netconf server configuration.
  55    d. Open the oamVesConfig.json and edit the details of OAM VES collector.
  56    e. Open the smoVesConfig.json and edit the details of SMO VES collector.
  57    f. Open the netconfConfig.json and edit the details of Netopeer server.
  58
  59 3. Install the yang modules and load initial configuration:
  60
  61    $cd l2/build/scripts
  62    $sudo ./load_yang.sh
  63
  64 4. Start Netopeer2-server:
  65
  66    $cd l2/build/scripts
  67    $sudo ./netopeer-server.sh start
  68
  69 5. In case standard defined VES format is to be enabled (this step is optional):
  70
  71       cd l2/src/o1/ves
  72
  73       Enable the Macro "StdDef" in file VesUtils.h
  74
  75       #define StdDef
  76
  77
  78 D. How to Clean and Build:
  79 --------------------------
  80 1. Build commands:
  81    a. odu       - Builds all components of ODU
  82    b. cu_stub   - Builds all CU Stub
  83    c. ric_stub  - Builds all RIC_Stub
  84    d. clean_odu - clean up ODU
  85    e. clean_cu  - clean up CU Stub
  86    f. clean_ric - clean up RIC Stub
  87    g. clean_all - cleanup everything
  88    h. options:
  89       i.   MACHINE=BIT64/BIT32 - Specify underlying machine type. Default is BIT32
  90       ii.  NODE=TEST_STUB      - Specify if it is a test node. Mandatory for cu_stub/ric_stub. Must not be used for odu
  91       iii. MODE=FDD/TDD        - Specify duplex mode. Default is FDD
  92       iv.  PHY=INTEL_L1        - Specify type of phy. If not specified, PHY stub is used
  93       v.   PHY_MODE=TIMER      - Specify mode of phy. Used only if PHY=INTEL_L1. Default is radio mode
  94       vi.  O1_ENABLE=YES       - Specify if O1 interface is enabled. If not specified, it is disabled
  95
  96 2. Building ODU binary:
  97    a. Build folder
  98          cd l2/build/odu
  99    b. Building ODU binary
 100          make odu MACHINE=<refer section D.1.h>  MODE=<refer section D.1.h>
 101    c. Cleaning ODU binary
 102          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 103
 104 3. Building CU Stub binary:
 105    a. Build folder
 106          cd l2/build/odu
 107    b. Building CU Stub binary
 108          make cu_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 109    c. Cleaning CU Stub binary
 110          make clean_cu NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 111
 112 4. Building RIC Stub binary:
 113    a. Build folder
 114          cd l2/build/odu
 115    b. Building RIC Stub binary
 116          make ric_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 117    c. Cleaning RIC Stub binary
 118          make clean_ric NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 119
 120 5. Cleaning ODU, CU Stub and RIC Stub:
 121       make clean_all
 122
 123
 124 E. How to Clean and Build with O1 interface enabled (Requires pre-requisite steps in section C)
 125 ------------------------------------------------------------------------------------------------
 126
 127 1. Building ODU binary:
 128    a. Build folder
 129          cd l2/build/odu
 130    b. Building ODU binary
 131          make odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 132    c. Cleaning ODU binary
 133          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 134
 135 2. Building CU Stub binary:
 136    a. Build folder
 137          cd l2/build/odu
 138    b. Building CU Stub binary
 139          make cu_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 140    c. Cleaning CU Stub binary
 141          make clean_cu NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 142
 143 3. Building RIC Stub binary:
 144    a. Build folder
 145          cd l2/build/odu
 146    b. Building RIC Stub binary
 147          make ric_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 148    c. Cleaning RIC Stub binary
 149          make clean_ric NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 150
 151 4. Cleaning ODU, CU Stub and RIC Stub:
 152       make clean_all
 153
 154
 155 F. How to execute:
 156 ------------------
 157 1. Assign virtual IP addresses as follows:
 158    a. ifconfig <interface name>:ODU "192.168.130.81"
 159    b. ifconfig <interface name>:CU_STUB "192.168.130.82"
 160    c. ifconfig <interface name>:RIC_STUB "192.168.130.80"
 161
 162 PS: If O1 interface is enabled, IP should match those configured in step C.2.a.
 163
 164 2. Execute CU Stub:
 165    a. CU execution folder:
 166         cd l2/bin/cu_stub
 167    b. Run CU Stub binary:
 168         ./cu_stub
 169
 170 3. Execute RIC Stub:
 171    a. RIC execution folder:
 172         cd l2/bin/ric_stub
 173    b. Run RIC Stub binary:
 174         ./ric_stub
 175
 176 4. Execute DU:
 177    a. DU execution folder:
 178         cd l2/bin/odu
 179    b. Run ODU binary:
 180         ./odu
 181
 182 PS: CU stub and RIC stub must be run (in no particular sequence) before ODU
 183     In case O1 is enabled and SMO is not available run section H to start the stack.
 184
 185 G. How to test with Intel L1:
 186 -----------------------------
 187
 188 I. Compilation
 189    1. Build ODU :
 190       a. Create folder l2/src/wls_lib. Copy wls_lib.h from <intel_directory>/phy/wls_lib/ to l2/src/wls_lib.
 191       b. Create folder l2/src/dpdk_lib. Copy following files from <intel_directory>/dpdk-19.11/x86_64-native-linuxapp-gcc/include/ to l2/sr        c/dpdk_lib.
 192                 rte_branch_prediction.h
 193                 rte_common.h
 194                 rte_config.h
 195                 rte_dev.h
 196                 rte_log.h
 197                 rte_pci_dev_feature_defs.h
 198                 rte_bus.h
 199                 rte_compat.h
 200                 rte_debug.h
 201                 rte_eal.h
 202                 rte_os.h
 203                 rte_per_lcore.h
 204       c. Build folder
 205                 cd l2/build/odu
 206       d. Build ODU Binary:
 207                           make odu PHY=<refer section D.1.h> PHY_MODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 208
 209    2. Build CU Stub and RIC Stub:
 210       a. Execute steps in sections D.3 and D.4
 211
 212 II. Execution
 213     1. Refer to below link for assumptions, dependencies, pre-requisites etc for ODU-Low execution
 214        https://docs.o-ran-sc.org/projects/o-ran-sc-o-du-phy/en/latest/
 215
 216     2. Execute L1:
 217        a. Setup environment:
 218                 cd <intel_directory>/phy/
 219                 source ./setupenv.sh
 220        b. Run L1 binary :
 221                 cd <intel_directory>/FlexRAN/l1/bin/nr5g/gnb/l1
 222                 To run
 223                         i.  In timer mode : ./l1.sh -e
 224                         ii. In radio mode : ./l1.sh -xran
 225                 L1 is up when console prints follow:
 226
 227                    Non BBU threads in application
 228                    ===========================================================================================================
 229                    nr5g_gnb_phy2mac_api_proc_stats_thread: [PID:   8659] binding on [CPU  0] [PRIO:  0] [POLICY:  1]
 230                    wls_rx_handler (non-rt):                [PID:   8663] binding on [CPU  0]
 231                    ===========================================================================================================
 232
 233                    PHY>welcome to application console
 234
 235     3. Execute FAPI Translator:
 236        a. Setup environment:
 237                 cd <intel_directory>/phy/
 238                 source ./setupenv.sh
 239        b. Run FAPI translator binary:
 240                 cd <intel_directory>/phy/fapi_5g/bin/
 241                 ./oran_5g_fapi --cfg=oran_5g_fapi.cfg
 242
 243     4. Execute CU Stub and RIC Stub:
 244        a. Run steps in sections E.1-E.3
 245
 246     5. Execute DU:
 247        a. DU execution folder
 248                 cd l2/bin/odu
 249        b. Export WLS library path
 250                 export LD_LIBRARY_PATH=<intel_directory>/phy/wls_lib/lib:$LD_LIBRARY_PATH
 251        c. Run ODU binary
 252                 ./odu
 253
 254
 255 H. Push cell and slice configuration over O1 using netopeer-cli
 256 ---------------------------------------------------------------
 257    When O-DU High is run with O1 enabled it waits for initial cell configuration to be pushed by SMO before starting the stack. In case the SMO is not available then these configurations can be pushed via netopeer-cli as follows:
 258
 259       $cd l2/build/config
 260       $netopeer2-cli
 261        > connect --login netconf
 262        Interactive SSH Authentication
 263        Type your password:
 264        Password: netconf!
 265        > edit-config --target candidate --config=cellConfig.xml
 266        > OK
 267        > commit
 268        > OK
 269        > edit-config --target candidate --config=rrmPolicy.xml
 270        > OK
 271        > commit
 272        > OK
 273
 274    For pushing these configurations in subsequent runs please edit cellConfig.xml and rrmPolicy.xml and increment number in the <id> tag to a new value e.g.
 275
 276     <id>rrm-2</id
 277
 278
 279 I. How to execute the Health Check using netopeer-cli : get alarm-list
 280 -----------------------------------------------------------------------
 281
 282    In case the SMO is not available the alarm list can be checked using netopeer-cli as follows:
 283
 284       $netopeer2-cli
 285        > connect --login netconf
 286        Interactive SSH Authentication
 287        Type your password:
 288        Password: netconf!
 289        > get --filter-xpath /o-ran-sc-odu-alarm-v1:odu/alarms
 290        DATA
 291        <odu xmlns="urn:o-ran:odu:alarm:1.0">
 292          <alarms>
 293            <alarm>
 294              <alarm-id>1009</alarm-id>
 295              <alarm-text>cell id  [1] is up</alarm-text>
 296              <severity>2</severity>
 297              <status>Active</status>
 298              <additional-info>cell UP</additional-info>
 299            </alarm>
 300          </alarms>
 301        </odu>
 302
 303    The XML output is a list of active alarms in the O-DU High system.
 304
 305
 306 J. Troubleshooting Netconf server issues
 307 ----------------------------------------
 308    In case the Netconf server and sysrepo breaks down, run the following steps:
 309
 310    $cd l2/build/scripts
 311    $sudo ./troubleshoot_netconf.sh cleanup
 312    execute section C.3 and C.4 again