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