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