[Epic-ID: ODUHIGH-516][Task-ID: ODUHIGH-528] RIC Subscription Request
[o-du/l2.git] / 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