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    g. Install the yang modules and load initial configuration
  59
  60    $cd l2/build/scripts
  61    $sudo ./load_yang.sh
  62
  63    h. To enable Standard Defined VES format:
  64
  65       cd l2/src/o1/ves
  66
  67       Enable the Macro "StdDef" in file VesUtils.h
  68
  69       #define StdDef
  70
  71 3. Start Netopeer2-server:
  72    $cd l2/build/scripts
  73    $sudo ./netopeer-server.sh start
  74
  75
  76 D. How to Clean and Build:
  77 --------------------------
  78 1. Build commands:
  79    a. odu       - Builds all components of ODU
  80    b. cu_stub   - Builds all CU Stub
  81    c. ric_stub  - Builds all RIC_Stub
  82    d. clean_odu - clean up ODU
  83    e. clean_cu  - clean up CU Stub
  84    f. clean_ric - clean up RIC Stub
  85    g. clean_all - cleanup everything
  86    h. options:
  87       i.   MACHINE=BIT64/BIT32 - Specify underlying machine type. Default is BIT32
  88       ii.  NODE=TEST_STUB      - Specify if it is a test node. Mandatory for cu_stub/ric_stub. Must not be used for odu
  89       iii. MODE=FDD/TDD        - Specify duplex mode. Default is FDD
  90       iv.  PHY=INTEL_L1        - Specify type of phy. If not specified, PHY stub is used
  91       v.   PHY_MODE=TIMER      - Specify mode of phy. Used only if PHY=INTEL_L1. Default is radio mode
  92       vi.  O1_ENABLE=YES       - Specify if O1 interface is enabled. If not specified, it is disabled
  93
  94 2. Building ODU binary:
  95    a. Build folder
  96          cd l2/build/odu
  97    b. Building ODU binary
  98          make odu MACHINE=<refer section D.1.h>  MODE=<refer section D.1.h>
  99    c. Cleaning ODU binary
 100          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 101
 102 3. Building CU Stub binary:
 103    a. Build folder
 104          cd l2/build/odu
 105    b. Building CU Stub binary
 106          make cu_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 107    c. Cleaning CU Stub binary
 108          make clean_cu NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 109
 110 4. Building RIC Stub binary:
 111    a. Build folder
 112          cd l2/build/odu
 113    b. Building RIC Stub binary
 114          make ric_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 115    c. Cleaning RIC Stub binary
 116          make clean_ric NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
 117
 118 5. Cleaning ODU, CU Stub and RIC Stub:
 119       make clean_all
 120
 121
 122 E. How to Clean and Build with O1 interface enabled (Requires pre-requisite steps in section C)
 123 ------------------------------------------------------------------------------------------------
 124
 125 1. Building ODU binary:
 126    a. Build folder
 127          cd l2/build/odu
 128    b. Building ODU binary
 129          make odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 130    c. Cleaning ODU binary
 131          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
 132
 133 2. Building CU Stub binary:
 134    a. Build folder
 135          cd l2/build/odu
 136    b. Building CU Stub binary
 137          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>
 138    c. Cleaning CU Stub binary
 139          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>
 140
 141 3. Building RIC Stub binary:
 142    a. Build folder
 143          cd l2/build/odu
 144    b. Building RIC Stub binary
 145          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>
 146    c. Cleaning RIC Stub binary
 147          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>
 148
 149 4. Cleaning ODU, CU Stub and RIC Stub:
 150       make clean_all
 151
 152
 153 F. How to execute:
 154 ------------------
 155 1. Assign virtual IP addresses as follows:
 156    a. ifconfig <interface name>:ODU "192.168.130.81"
 157    b. ifconfig <interface name>:CU_STUB "192.168.130.82"
 158    c. ifconfig <interface name>:RIC_STUB "192.168.130.80"
 159
 160 PS: If O1 interface is enabled, IP should match those configured in step C.2.a.
 161
 162 2. Execute CU Stub:
 163    a. CU execution folder:
 164         cd l2/bin/cu_stub
 165    b. Run CU Stub binary:
 166         ./cu_stub
 167
 168 3. Execute RIC Stub:
 169    a. RIC execution folder:
 170         cd l2/bin/ric_stub
 171    b. Run RIC Stub binary:
 172         ./ric_stub
 173
 174 4. Execute DU:
 175    a. DU execution folder:
 176         cd l2/bin/odu
 177    b. Run ODU binary:
 178         ./odu
 179
 180 PS: CU stub and RIC stub must be run (in no particular sequence) before ODU
 181
 182
 183 G. How to test with Intel L1:
 184 -----------------------------
 185
 186 I. Compilation
 187    1. Build ODU :
 188       a. Create folder l2/src/wls_lib. Copy wls_lib.h from <intel_directory>/phy/wls_lib/ to l2/src/wls_lib.
 189       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.
 190                 rte_branch_prediction.h
 191                 rte_common.h
 192                 rte_config.h
 193                 rte_dev.h
 194                 rte_log.h
 195                 rte_pci_dev_feature_defs.h
 196                 rte_bus.h
 197                 rte_compat.h
 198                 rte_debug.h
 199                 rte_eal.h
 200                 rte_os.h
 201                 rte_per_lcore.h
 202       c. Build folder
 203                 cd l2/build/odu
 204       d. Build ODU Binary:
 205                           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>
 206
 207    2. Build CU Stub and RIC Stub:
 208       a. Execute steps in sections D.3 and D.4
 209
 210 II. Execution
 211     1. Refer to below link for assumptions, dependencies, pre-requisites etc for ODU-Low execution
 212        https://docs.o-ran-sc.org/projects/o-ran-sc-o-du-phy/en/latest/
 213
 214     2. Execute L1:
 215        a. Setup environment:
 216                 cd <intel_directory>/phy/
 217                 source ./setupenv.sh
 218        b. Run L1 binary :
 219                 cd <intel_directory>/FlexRAN/l1/bin/nr5g/gnb/l1
 220                 To run
 221                         i.  In timer mode : ./l1.sh -e
 222                         ii. In radio mode : ./l1.sh -xran
 223                 L1 is up when console prints follow:
 224
 225                    Non BBU threads in application
 226                    ===========================================================================================================
 227                    nr5g_gnb_phy2mac_api_proc_stats_thread: [PID:   8659] binding on [CPU  0] [PRIO:  0] [POLICY:  1]
 228                    wls_rx_handler (non-rt):                [PID:   8663] binding on [CPU  0]
 229                    ===========================================================================================================
 230
 231                    PHY>welcome to application console
 232
 233     3. Execute FAPI Translator:
 234        a. Setup environment:
 235                 cd <intel_directory>/phy/
 236                 source ./setupenv.sh
 237        b. Run FAPI translator binary:
 238                 cd <intel_directory>/phy/fapi_5g/bin/
 239                 ./oran_5g_fapi --cfg=oran_5g_fapi.cfg
 240
 241     4. Execute CU Stub and RIC Stub:
 242        a. Run steps in sections E.1-E.3
 243
 244     5. Execute DU:
 245        a. DU execution folder
 246                 cd l2/bin/odu
 247        b. Export WLS library path
 248                 export LD_LIBRARY_PATH=<intel_directory>/phy/wls_lib/lib:$LD_LIBRARY_PATH
 249        c. Run ODU binary
 250                 ./odu
 251
 252
 253 H. How to execute the Health Check : get alarm-list
 254 ----------------------------------------------------
 255
 256    Steps:
 257
 258    1. Start Netconf netopeer client
 259
 260    2. Connect to the server with
 261
 262         user: netconf
 263         pwd:  netconf!
 264
 265    3. Send a Netconf get request for alarms xpath
 266
 267    Here are the steps as executed in the terminal
 268
 269       $netopeer2-cli
 270        > connect --login netconf
 271        Interactive SSH Authentication
 272        Type your password:
 273        Password:
 274        > get --filter-xpath /o-ran-sc-odu-alarm-v1:odu/alarms
 275        DATA
 276        <odu xmlns="urn:o-ran:odu:alarm:1.0">
 277          <alarms>
 278            <alarm>
 279              <alarm-id>1009</alarm-id>
 280              <alarm-text>cell id  [1] is up</alarm-text>
 281              <severity>2</severity>
 282              <status>Active</status>
 283              <additional-info>cell UP</additional-info>
 284            </alarm>
 285          </alarms>
 286        </odu>
 287
 288    The XML output is a list of active alarms in the O-DU High system.
 289
 290 I. Push cell and slice configuration over O1 using netopeer-cli
 291 ---------------------------------------------------------------
 292    When O-DU High is run with O1 enabled it waits for cell configuration to be pushed by SMO. In case the SMO is not available then these configurations can be pushed via netopeer-cli as follows.
 293    1. Follow step H.1 and H.2.
 294    2. update cellConfig.xml and rrmPolicy.xml.
 295       $cd l2/build/config
 296       $edit-config --target candidate --config=cellConfig.xml
 297       $edit-config --target candidate --config=rrmPolicy.xml
 298
 299
 300 J. Troubleshooting Netconf server issues
 301 ----------------------------------------
 302    In case the Netconf server and sysrepo breaks down, run the following steps:
 303
 304    $cd l2/build/scripts
 305    $sudo ./troubleshoot_netconf.sh cleanup
 306    execute section C.2.f, C.3 again