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