docs/user-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 User Guide
   5 ***********
   6
   7 This is the user guide for H release of O-DU/l2.
   8 Follow installation-guide to get all the dependencies ready.
   9
  10 .. contents::
  11    :depth: 3
  12    :local:
  13
  14
  15 A. Execution:
  16 -------------
  17
  18 I. Execution - On locally compiling O-DU High Source Code
  19 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  20
  21 1. Assign virtual IP addresses as follows:
  22
  23    a. ifconfig <interface name>:ODU "192.168.130.81"
  24    b. ifconfig <interface name>:CU_STUB "192.168.130.82"
  25    c. ifconfig <interface name>:RIC_STUB "192.168.130.80"
  26
  27 PS: If O1 interface is enabled, IPs should match those configured in "startup_config.xml"
  28     ( Refer Installation Guide - "Setting up Netconf server" )
  29
  30 2. Execute CU Stub:
  31
  32    a. Navigate to CU execution folder
  33
  34       - cd <O-DU High Directory>/l2/bin/cu_stub
  35
  36    b. Run CU Stub binary
  37
  38       - ./cu_stub
  39
  40 3. Execute RIC Stub:
  41
  42    a. Navigate to RIC execution folder
  43
  44       - cd <O-DU High Directory>/l2/bin/ric_stub
  45
  46    b. Run RIC Stub binary
  47
  48       - ./ric_stub
  49
  50 4. Execute O-DU High:
  51
  52    a. Navigate to ODU execution folder
  53
  54       - cd <O-DU High Directory>/l2/bin/odu
  55
  56    b. Run ODU binary
  57
  58       - ./odu
  59
  60 PS: CU stub and RIC stub must be run (in no particular sequence) before ODU.
  61     In case O1 is enabled and SMO is not available run section D to start the stack.
  62
  63 II. Execution - Using Docker Images
  64 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  65
  66 The call flow between O-DU High and CU Stub can be achieved by executing docker containers.
  67
  68 - Pull the last built docker images:
  69     -   docker pull nexus3.o-ran-sc.org:10004/o-ran-sc/o-du-l2:8.0.1
  70     -   docker pull nexus3.o-ran-sc.org:10004/o-ran-sc/o-du-l2-cu-stub:
  71
  72 - Run CU Stub docker:
  73     - docker run -it --privileged --net=host --entrypoint bash
  74       nexus3.o-ran-sc.org:10004/o-ran-sc/o-du-l2-cu-stub:8.0.1
  75     - ./cu_stub
  76
  77 - Run ODU docker:
  78     - docker run -it --privileged --net=host --entrypoint bash
  79       nexus3.o-ran-sc.org:10004/o-ran-sc/o-du-l2:8.0.1
  80     - ./odu
  81
  82
  83 B. Pairwise testing with Intel O-DU Low:
  84 -----------------------------------------
  85
  86 This section describes the changes required in compilation and execution of O-DU High binaries to successfully integrate
  87 with Intel O-DU Low in radio mode.
  88
  89
  90 I. Pre-requisites
  91 ^^^^^^^^^^^^^^^^^^
  92
  93    1. Install O-DU High as per installation-guide .
  94
  95    2. Clone O-DU Low code in <O-DU Low Directory> from
  96
  97       a. https://gerrit.o-ran-sc.org/r/admin/repos/o-du/phy and,
  98
  99       b. https://github.com/intel/FlexRAN
 100
 101    3. Install O-DU Low as per https://docs.o-ran-sc.org/projects/o-ran-sc-o-du-phy/en/latest/index.html .
 102
 103
 104 II. Compilation
 105 ^^^^^^^^^^^^^^^^
 106
 107    1. Build ODU :
 108
 109       a. Create folder <O-DU High Directory>/l2/src/wls_lib. Copy wls_lib.h from <O-DU Low Directory>/phy/wls_lib/ to
 110          <O-DU High Directory>/l2/src/wls_lib.
 111
 112       b. Create folder <O-DU High Directory>/l2/src/dpdk_lib. Copy following files from
 113          <O-DU Low Directory>/dpdk-19.11/x86_64-native-linuxapp-gcc/include/ to <O-DU High Directory>/l2/src/dpdk_lib.
 114
 115          - rte_branch_prediction.h
 116          - rte_common.h
 117          - rte_config.h
 118          - rte_dev.h
 119          - rte_log.h
 120          - rte_pci_dev_feature_defs.h
 121          - rte_bus.h
 122          - rte_compat.h
 123          - rte_debug.h
 124          - rte_eal.h
 125          - rte_os.h
 126          - rte_per_lcore.h
 127
 128       c. Navigate to build folder
 129
 130          - cd <O-DU High Directory>/l2/build/odu
 131
 132       d. Build ODU Binary:
 133
 134          - make odu PHY=INTEL_L1 MACHINE=BIT64 MODE=FDD
 135
 136
 137 III. Execution
 138 ^^^^^^^^^^^^^^^
 139
 140    1. Execute O-DU Low:
 141
 142       a. Setup environment:
 143
 144          - cd <O-DU Low Directory>/phy/
 145          - source ./setupenv.sh
 146
 147       b. Run O-DU Low binary :
 148
 149          - cd <O-DU Low Directory>/FlexRAN/l1/bin/nr5g/gnb/l1
 150          - To run in radio mode : ./l1.sh -xran
 151          - L1 is up when following prints are seen on console:
 152
 153                 | Non BBU threads in application
 154                 | \==================================================================
 155                 | nr5g_gnb_phy2mac_api_proc_stats_thread: [PID: 8659] binding on [CPU 0] [PRIO: 0] [POLICY: 1]
 156                 | wls_rx_handler (non-rt):                [PID: 8663] binding on [CPU 0]
 157                 | \==================================================================
 158
 159                 PHY>welcome to application console
 160
 161    2. Execute FAPI Translator:
 162
 163       a. Setup environment:
 164
 165          - cd <O-DU Low Directory>/phy/
 166          - source ./setupenv.sh
 167
 168       b. Run FAPI translator binary:
 169
 170          - cd <O-DU Low Directory>/phy/fapi_5g/bin/
 171          - ./oran_5g_fapi --cfg=oran_5g_fapi.cfg
 172
 173    3. Execute CU Stub and RIC Stub:
 174
 175       a. Run steps in sections A.I.1 through A.I.3 .
 176
 177    4. Execute DU:
 178
 179       a. DU execution folder
 180
 181          - cd <O-DU High Directory>/l2/bin/odu
 182
 183       b. Export WLS library path
 184
 185          - export LD_LIBRARY_PATH=<O-DU Low Directory>/phy/wls_lib/lib:$LD_LIBRARY_PATH
 186
 187       c. Run ODU binary
 188
 189          - ./odu
 190
 191
 192 C. Message Flow:
 193 ----------------
 194
 195 O-DU High opens WLS interface during bring up. Message exchanges can begin once the interface is ready.
 196 Following diagram shows P5 messages exchanged with O-DU Low in timer mode.
 197
 198 .. figure:: O-DU_High_Low_Flow.PNG
 199   :width: 600
 200   :alt: Figure 16 O-DU High - O-DU Low Message Flow Diagram
 201
 202   Figure 16 - O-DU High - O-DU Low Message Flow Diagram
 203
 204 Note: UL IQ-Sample request and response are needed by Intel O-DU Low in timer mode(testing mode) only. Code changes for
 205 these are guarded under INTEL_TIMER_MODE flag which can be enabled using compilation option "PHY_MODE=TIMER", as
 206 mentioned in section B.I.1.d .
 207
 208 D. Push cell and slice configuration over O1 using netopeer-cli
 209 ---------------------------------------------------------------
 210    When O-DU High is run with O1 enabled it waits for initial cell configuration to be pushed by SMO before starting the stack. In case the SMO is not available then these configurations can be pushed via netopeer-cli as follows:
 211
 212       | $cd l2/build/config
 213       | $netopeer2-cli
 214       |  > connect --login netconf
 215       |  Interactive SSH Authentication
 216       |  Type your password:
 217       |  Password: netconf!
 218       |  > edit-config --target candidate --config=cellConfig.xml
 219       |  > OK
 220       |  > commit
 221       |  > OK
 222       |  > edit-config --target candidate --config=rrmPolicy.xml
 223       |  > OK
 224       |  > commit
 225       |  > OK
 226
 227    For pushing these configurations in subsequent runs please edit cellConfig.xml and rrmPolicy.xml and increment number in the <id> tag to a new value e.g.
 228
 229     <id>rrm-2</id
 230
 231 E. How to execute the Health Check using netopeer-cli : get alarm-list
 232 -----------------------------------------------------------------------
 233
 234    In case the SMO is not available the alarm list can be checked using netopeer-cli as follows:
 235
 236      |  netopeer2-cli
 237      |  > connect --login netconf
 238      |  Interactive SSH Authentication
 239      |  Type your password:
 240      |  Password: netconf!
 241      |  > get --filter-xpath /o-ran-sc-odu-alarm-v1\:odu/alarms
 242      |  DATA
 243      |  <odu xmlns=\"urn\:o-ran\:odu\:alarm\:1.0\">
 244      |    <alarms>
 245      |      <alarm>
 246      |        <alarm-id>1009</alarm-id>
 247      |        <alarm-text>cell id  [1] is up</alarm-text>
 248      |        <severity>2</severity>
 249      |        <status>Active</status>
 250      |        <additional-info>cell UP</additional-info>
 251      |      </alarm>
 252      |    </alarms>
 253      |  </odu>
 254
 255 The XML output is a list of active alarms in the O-DU High system.
 256