[Issue Id-ODUHIGH-457] Fixes related to memory leak
[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    g. Install the yang modules and load initial configuration
59
60    $cd l2/build/scripts
61    $sudo ./load_yang.sh
62
63    h. Install additional 3GPP yang models.
64
65       Download following 3GPP REL17 YANG models
66       https://forge.3gpp.org/rep/sa5/MnS/tree/Rel17-draft/yang-models
67
68    $cd l2/build/yang
69
70    _3gpp-common-top.yang
71    _3gpp-5g-common-yang-types.yang
72    _3gpp-common-yang-types.yang
73    _3gpp-common-managed-element.yang
74    _3gpp-common-measurements.yang
75    _3gpp-common-subscription-control.yang
76    _3gpp-common-fm.yang
77    _3gpp-common-trace.yang
78    _3gpp-common-managed-function.yang
79    _3gpp-nr-nrm-gnbdufunction.yang
80    _3gpp-nr-nrm-nrcelldu.yang
81    _3gpp-nr-nrm-rrmpolicy.yang
82
83    Note :There are some corrections required in _3gpp-common-trace.yang and _3gpp-common-trace.yang yang model. Please follow these steps.
84
85    $cd l2/build/yang
86    $sed -i -e 's/"IMMEDIATE_MDT"/"IMMEDIATE_MDT_ONLY"/g' _3gpp-common-trace.yang
87    $sed -i -e 's/"TRACE"/"TRACE_ONLY"/g' _3gpp-common-trace.yang
88
89    Install all the downloaded yang models.
90
91    $cd l2/build/yang
92    $sysrepoctl -i      _3gpp-common-yang-types.yang
93    $sysrepoctl -i      _3gpp-common-top.yang
94    $sysrepoctl -i      _3gpp-common-measurements.yang
95    $sysrepoctl -i      _3gpp-common-trace.yang
96    $sysrepoctl -i      _3gpp-common-managed-function.yang
97    $sysrepoctl -i      _3gpp-common-subscription-control.yang
98    $sysrepoctl -i      _3gpp-common-fm.yang
99    $sysrepoctl -i      _3gpp-common-managed-element.yang
100    $sysrepoctl -i      _3gpp-5g-common-yang-types.yang
101    $sysrepoctl -i      _3gpp-nr-nrm-rrmpolicy.yang
102    $sysrepoctl -i      _3gpp-nr-nrm-gnbdufunction.yang
103    $sysrepoctl -i      _3gpp-nr-nrm-nrcelldu.yang
104
105
106 3. Start Netopeer2-server:
107    $cd l2/build/scripts
108    $sudo ./netopeer-server.sh start
109
110
111 D. How to Clean and Build:
112 --------------------------
113 1. Build commands:
114    a. odu       - Builds all components of ODU
115    b. cu_stub   - Builds all CU Stub
116    c. ric_stub  - Builds all RIC_Stub
117    d. clean_odu - clean up ODU
118    e. clean_cu  - clean up CU Stub
119    f. clean_ric - clean up RIC Stub
120    g. clean_all - cleanup everything
121    h. options:
122       i.   MACHINE=BIT64/BIT32 - Specify underlying machine type. Default is BIT32
123       ii.  NODE=TEST_STUB      - Specify if it is a test node. Mandatory for cu_stub/ric_stub. Must not be used for odu
124       iii. MODE=FDD/TDD        - Specify duplex mode. Default is FDD
125       iv.  PHY=INTEL_L1        - Specify type of phy. If not specified, PHY stub is used
126       v.   PHY_MODE=TIMER      - Specify mode of phy. Used only if PHY=INTEL_L1. Default is radio mode
127       vi.  O1_ENABLE=YES       - Specify if O1 interface is enabled. If not specified, it is disabled 
128
129 2. Building ODU binary:
130    a. Build folder
131          cd l2/build/odu
132    b. Building ODU binary
133          make odu MACHINE=<refer section D.1.h>  MODE=<refer section D.1.h>
134    c. Cleaning ODU binary
135          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
136
137 3. Building CU Stub binary:
138    a. Build folder
139          cd l2/build/odu
140    b. Building CU Stub binary
141          make cu_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
142    c. Cleaning CU Stub binary
143          make clean_cu NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
144
145 4. Building RIC Stub binary:
146    a. Build folder
147          cd l2/build/odu
148    b. Building RIC Stub binary
149          make ric_stub NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
150    c. Cleaning RIC Stub binary
151          make clean_ric NODE=<refer section D.1.h> MACHINE=<refer section D.1.h> MODE=<refer section D.1.h>
152
153 5. Cleaning ODU, CU Stub and RIC Stub:
154       make clean_all
155
156
157 E. How to Clean and Build with O1 interface enabled (Requires pre-requisite steps in section C)
158 ------------------------------------------------------------------------------------------------
159
160 1. Building ODU binary:
161    a. Build folder
162          cd l2/build/odu
163    b. Building ODU binary
164          make odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
165    c. Cleaning ODU binary
166          make clean_odu MACHINE=<refer section D.1.h> MODE=<refer section D.1.h> O1_ENABLE=<refer section D.1.h>
167
168 2. Building CU Stub binary:
169    a. Build folder
170          cd l2/build/odu
171    b. Building CU Stub binary
172          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>
173    c. Cleaning CU Stub binary
174          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>
175
176 3. Building RIC Stub binary:
177    a. Build folder
178          cd l2/build/odu
179    b. Building RIC Stub binary
180          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>
181    c. Cleaning RIC Stub binary
182          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>
183
184 4. Cleaning ODU, CU Stub and RIC Stub:
185       make clean_all
186
187
188 F. How to execute:
189 ------------------
190 1. Assign virtual IP addresses as follows:
191    a. ifconfig <interface name>:ODU "192.168.130.81"
192    b. ifconfig <interface name>:CU_STUB "192.168.130.82"
193    c. ifconfig <interface name>:RIC_STUB "192.168.130.80"
194
195 PS: If O1 interface is enabled, IP should match those configured in step C.2.a.
196
197 2. Execute CU Stub:
198    a. CU execution folder:
199         cd l2/bin/cu_stub
200    b. Run CU Stub binary:
201         ./cu_stub
202
203 3. Execute RIC Stub:
204    a. RIC execution folder:
205         cd l2/bin/ric_stub
206    b. Run RIC Stub binary:
207         ./ric_stub
208
209 4. Execute DU:
210    a. DU execution folder:
211         cd l2/bin/odu
212    b. Run ODU binary:
213         ./odu
214
215 PS: CU stub and RIC stub must be run (in no particular sequence) before ODU
216
217
218 G. How to test with Intel L1:
219 -----------------------------
220
221 I. Compilation
222    1. Build ODU :
223       a. Create folder l2/src/wls_lib. Copy wls_lib.h from <intel_directory>/phy/wls_lib/ to l2/src/wls_lib.
224       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.
225                 rte_branch_prediction.h
226                 rte_common.h
227                 rte_config.h
228                 rte_dev.h
229                 rte_log.h
230                 rte_pci_dev_feature_defs.h
231                 rte_bus.h
232                 rte_compat.h
233                 rte_debug.h
234                 rte_eal.h
235                 rte_os.h
236                 rte_per_lcore.h
237       c. Build folder
238                 cd l2/build/odu
239       d. Build ODU Binary:
240                           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>
241
242    2. Build CU Stub and RIC Stub:
243       a. Execute steps in sections D.3 and D.4
244
245 II. Execution
246     1. Refer to below link for assumptions, dependencies, pre-requisites etc for ODU-Low execution
247        https://docs.o-ran-sc.org/projects/o-ran-sc-o-du-phy/en/latest/
248
249     2. Execute L1:
250        a. Setup environment:
251                 cd <intel_directory>/phy/
252                 source ./setupenv.sh
253        b. Run L1 binary :
254                 cd <intel_directory>/FlexRAN/l1/bin/nr5g/gnb/l1
255                 To run 
256                         i.  In timer mode : ./l1.sh -e
257                         ii. In radio mode : ./l1.sh -xran
258                 L1 is up when console prints follow:
259
260                    Non BBU threads in application
261                    ===========================================================================================================
262                    nr5g_gnb_phy2mac_api_proc_stats_thread: [PID:   8659] binding on [CPU  0] [PRIO:  0] [POLICY:  1]
263                    wls_rx_handler (non-rt):                [PID:   8663] binding on [CPU  0]
264                    ===========================================================================================================
265                  
266                    PHY>welcome to application console
267
268     3. Execute FAPI Translator:
269        a. Setup environment:
270                 cd <intel_directory>/phy/
271                 source ./setupenv.sh
272        b. Run FAPI translator binary:
273                 cd <intel_directory>/phy/fapi_5g/bin/
274                 ./oran_5g_fapi --cfg=oran_5g_fapi.cfg
275
276     4. Execute CU Stub and RIC Stub:
277        a. Run steps in sections E.1-E.3
278
279     5. Execute DU:
280        a. DU execution folder
281                 cd l2/bin/odu
282        b. Export WLS library path
283                 export LD_LIBRARY_PATH=<intel_directory>/phy/wls_lib/lib:$LD_LIBRARY_PATH
284        c. Run ODU binary
285                 ./odu
286
287
288 H. How to execute the Health Check : get alarm-list
289 ----------------------------------------------------
290    
291    Steps:
292
293    1. Start Netconf netopeer client 
294    
295    2. Connect to the server with 
296
297         user: netconf
298         pwd:  netconf!
299
300    3. Send a Netconf get request for alarms xpath
301
302    Here are the steps as executed in the terminal 
303
304       $netopeer2-cli
305        > connect --login netconf
306        Interactive SSH Authentication
307        Type your password:
308        Password:
309        > get --filter-xpath /o-ran-sc-odu-alarm-v1:odu/alarms
310        DATA
311        <odu xmlns="urn:o-ran:odu:alarm:1.0">
312          <alarms>
313            <alarm>
314              <alarm-id>1009</alarm-id>
315              <alarm-text>cell id  [1] is up</alarm-text>
316              <severity>2</severity>
317              <status>Active</status>
318              <additional-info>cell UP</additional-info>
319            </alarm>
320          </alarms>
321        </odu>
322
323    The XML output is a list of active alarms in the O-DU High system.
324
325 I. Push cell and slice configuration over O1 using netopeer-cli
326 ---------------------------------------------------------------
327    When O-DU High is run with O1 enabled it waits for cell configuration to be pushed by SMO. In case the SMO is not available then these configurations can be pushed via netopeer-cli as follows.
328    1. Follow step H.1 and H.2.
329    2. update cellConfig.xml and rrmPolicy.xml.
330       $cd l2/build/config
331       $edit-config --target candidate --config=cellConfig.xml
332       $edit-config --target candidate --config=rrmPolicy.xml
333
334
335 J. Troubleshooting Netconf server issues
336 ----------------------------------------
337    In case the Netconf server and sysrepo breaks down, run the following steps:
338
339    $cd l2/build/scripts
340    $sudo ./troubleshoot_netconf.sh cleanup
341    execute section C.2.f, C.3 again