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