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