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