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