--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+
+API-Docs
+========
+
+This is the API-docs for Cherry relase o-du/l2.
+
+.. contents::
+ :depth: 3
+ :local:
+
+
+Introduction
+-----------------
+This document lists the APIs implemented between various modules of ODU-High and their functionality.
+These are in line with ORAN-WG8.AAD-v2.05.00, hereafter referred to as AAD Spec.
+
+API Functions
+-------------
+1. RLC-MAC Interface
+
+ - AAD Spec : section 9.2.1
+
+ A. RLC to MAC
+
+ a. Data Transfer(DL) : Transfers DL data to MAC as per Section 9.2.1.1 of the AAD Spec
+
+ b. Buffer Status Reporting(DL) : Reports DL data volume pending in the RLC entity, as per Section 9.2.1.4 of the
+ AAD Spec
+
+ B. MAC to RLC
+
+ a. Data Transfer(UL) : Transfers UL data to RLC as per Section 9.2.1.2 of the AAD Spec
+ b. Schedule Result Reporting (DL) : Reports DL schedule result to RLC as per Section 9.2.1.3 of the AAD Spec
+
+2. MAC-Scheduler Interface
+
+ - AAD Spec : section 9.2.2
+
+ A. MAC to Scheduler
+
+ a. Air Interface Time : Sends timing information over air interface in terms of SFN and slo, as per Section
+ 9.2.2.1.1 of the AAD Spec
+
+ b. Cell Configuration Request : MAC provides SCH the cell configuration as per Section 9.2.2.2.1 of the AAD Spec
+
+ c. Add UE Configuration Request : MAC provides SCH the configuration/capabilities of a UE as per Section 9.2.2.2.3
+ of the AAD Spec
+
+ d. Modify UE Reconfiguration Request : MAC provides SCH the re-configuration of UE, also used to
+ add/release/modify existing bearers, as per Section 9.2.2.2.4 of the AAD Spec
+
+ e. RACH Indication : MAC receives the RACH Indication and share the contents with SCH as per Section 9.2.2.2.10 of
+ the AAD Spec
+
+ f. DL RLC Buffer Status Information : Reports data volume per LC when it is received at MAC as per Section
+ 9.2.2.2.14 of the AAD Spec
+
+ g. UL Buffer Status Report Indication : On reception and decoding of received BSR from the UE, MAC provides SCH
+ buffer status report for UL scheduling, as per Section 9.2.2.2.16 of the AAD Spec
+
+ B. Scheduler to MAC
+
+ a. Cell Configuration Response - Response to cell configuration request from MAC, as per Section 9.2.2.3.1 of the
+ AAD Spec
+
+ b. UE Reconfiguration Response - Response to UE reconfiguration request from MAC, as per Section 9.2.2.3.3 of the
+ AAD Spec
+
+ c. DL Scheduling Information - Provides scheduling information for a given slot for downlink data, as per Section
+ 9.2.2.3.5 of the AAD spec.
+
+ d. UL Scheduling Information - Provides scheduled information for MAC to form the UL_TTI.request towards O-DU Low,
+ as per Section 9.2.2.3.6 of the AAD Spec.
+
+ e. RAR Information - Informs MAC of uplink scheduling and Msg3 scheduling information, as per Section 9.2.2.3.7 of
+ the AAD Spec.
+
+ f. Downlink Control Channel Information - Provides DCI scheduling information for a given slot on PDCCH, as per
+ Section 9.2.2.3.8 of the AAD Spec
+
+ g. Downlink Broadcast Allocation - Provides DCI and DL data scheduling information for SIB1 for a given slot for
+ Broadcast Channel, as per Section 9.2.2.3.9 of the AAD Spec.
+
+3. DU APP - MAC Interface
+
+ - AAD Spec : section 9.2.3
+
+ A. DU APP to MAC
+
+ a. Cell Start - Commands MAC to start cell at L1 and to start broadcasting system information, as per Section
+ 9.2.3.1 of the AAD Spec.
+
+ b. UE Create Request - Adds UE information at MAC as per Section 9.2.3.3 of the AAD Spec.
+
+ c. UE Reconfiguration Request - Reconfigure UE information for a UE already added at MAC, as per Section 9.2.3.5
+ of the AAD Spec.
+
+ d. DL CCCH Indication - Sends DL CCCH Message to MAC to be sent to UE, as per Section 9.2.3.16 of the AAD Spec.
+
+ B. MAC to DU APP
+
+ a. UE Create Response - Response to UE Create Request from DU Manager as per Section 9.2.3.4 of the AAD Spec.
+
+ b. UE Reconfiguration Response - Response to UE Reconfiguration Request from DU APP as per Section 9.2.3.6 of the
+ AAD Spec.
+
+ c. UL-CCCH Indication - Sends the UL CCCH Message received from UE to DU APP as per Section 9.2.3.15 of AAD Spec.
+
+4. DU APP - RLC Interface
+
+ - AAD Spec : section 9.2.4
+
+ A. DU APP to RLC
+
+ a. UE Create - Adds UE associated RLC entity and related information as per Section 9.2.4.1 of the AAD Spec.
+
+ b. UE Reconfiguration - Reconfigures the UE associated RLC entity previously added at RLC, as per Section 9.2.4.1
+ of the AAD Spec.
+
+ c. DL RRC Message Transfer - Requests RLC to deliver RRC message from CU to the UE, as per Section 9.2.4.3 of the
+ AAD Spec.
+
+ B. RLC to DU APP
+
+ a. UL RRC Message Tranfer - Delivers RRC Message from UE to CU as per Section 9.2.4.4 of the AAD spec.
+
+ b. RRC Message Delivery Report - Informs DU Manager on failed/successful delivery of a DL RRC message to UE, as
+ per Section 9.2.4.5 of the AAD Spec.
+
+Additional APIs
+----------------
+
+These APIs are not defined in the AAD Spec but were implemented in O-DU High to achieve UE attach.
+
+1. DU APP - MAC Interface
+
+ A. DU APP to MAC
+
+ a. Cell Configuration Request - Configures cell information at MAC
+
+ B. MAC to DU APP
+
+ a. Cell Configuration Response - Response to Cell Configuration Request from DU APP
+
+2. DU APP - RLC Interface
+
+ A. RLC to DU APP
+
+ a. UE Create Response - Response to UE Create Request from DU APP
+
+ b. UE Reconfiguration Response - Response to UE Recofiguration Request from DU APP
+
+ c. DL RRC Message Response - Informs DU APP if a DL RRC Message was successfuly processed at RLC and sent to MAC.
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) <optionally add copywriters name>
+
+
+User Guide
+==========
+
+This is the user guide for Cherry release of O-DU/l2.
+
+.. contents::
+ :depth: 3
+ :local:
+
+A. Compilation:
+---------------
+
+1. Build O-DU High:
+
+ a. Build folder
+
+ - cd <rsys_directory>/l2/build/odu
+
+ b. Build O-DU High binary
+
+ - make odu MACHINE=BIT64 MODE=FDD
+
+ c. Clean O-DU High binary
+
+ - make clean_odu MACHINE=BIT64 MODE=FDD
+
+2. Build CU Stub :
+
+ a. Build folder
+
+ - cd <rsys_directory>/l2/build/odu
+
+ b. Build CU Stub binary
+
+ - make cu_stub NODE=TEST_STUB MACHINE=BIT64 MODE=FDD
+
+ c. Clean CU Stub binary
+
+ - make clean_cu NODE=TEST_STUB MACHINE=BIT64 MODE=FDD
+
+3. Build RIC Stub :
+
+ a. Build folder
+
+ - cd <rsys_directory>/l2/build/odu
+
+ b. Build RIC Stub binary
+
+ - make ric_stub NODE=TEST_STUB MACHINE=BIT64 MODE=FDD
+
+ c. Clean RIC Stub binary
+
+ - make clean_ric NODE=TEST_STUB MACHINE=BIT64 MODE=FDD
+
+4. Clean ODU, CU Stub and RIC Stub together
+
+ a. make clean_all
+
+
+B. Execution:
+-------------
+
+1. Assign virtual IP addresses as follows:
+
+ a. ifconfig <interface name>:ODU "192.168.130.81"
+ b. ifconfig <interface name>:CU_STUB "192.168.130.82"
+ c. ifconfig <interface name>:RIC_STUB "192.168.130.80"
+
+2. Execute CU Stub:
+
+ a. CU execution folder
+
+ - cd <rsys_directory>/l2/bin/cu_stub
+
+ b. Run CU Stub binary
+
+ - ./cu_stub
+
+3. Execute RIC Stub:
+
+ a. RIC execution folder
+
+ - cd <rsys_directory>/l2/bin/ric_stub
+
+ b. Run RIC Stub binary
+
+ - ./ric_stub
+
+4. Execute DU:
+
+ a. DU execution folder
+
+ - cd <rsys_directory>/l2/bin/odu
+
+ b. Run ODU binary
+
+ - ./odu
+
+PS: CU stub and RIC stub must be run (in no particular sequence) before ODU
+
+
+C. Testing with Intel O-DU Low:
+-------------------------------
+
+I. Compilation
+^^^^^^^^^^^^^^
+
+ 1. Build ODU :
+
+ a. Create folder <rsys_directory>/l2/src/wls_lib. Copy wls_lib.h from <intel_directory>/phy/wls_lib/ to
+ <rsys_directory>/l2/src/wls_lib.
+
+ b. Create folder <rsys_directory>/l2/src/dpdk_lib. Copy following files from
+ <intel_directory>/dpdk-19.11/x86_64-native-linuxapp-gcc/include/ to <rsys_directory>/l2/src/dpdk_lib.
+
+ - rte_branch_prediction.h
+ - rte_common.h
+ - rte_config.h
+ - rte_dev.h
+ - rte_log.h
+ - rte_pci_dev_feature_defs.h
+ - rte_bus.h
+ - rte_compat.h
+ - rte_debug.h
+ - rte_eal.h
+ - rte_os.h
+ - rte_per_lcore.h
+
+ c. Build folder
+
+ - cd <rsys_directory>/l2/build/odu
+
+ d. Build ODU Binary:
+
+ - make odu PHY=INTEL_L1 PHY_MODE=TIMER MACHINE=BIT64 MODE=FDD
+
+ 2. Build CU Stub and RIC Stub:
+
+ a. Execute steps in sections A.2 and A.3.
+
+II. Execution
+^^^^^^^^^^^^^
+
+ 1. Execute O-DU Low:
+
+ a. Setup environment:
+
+ - cd <intel_directory>/phy/
+ - source ./setupenv.sh
+
+ b. Run O-DU Low binary :
+
+ - cd <intel_directory>/FlexRAN/l1/bin/nr5g/gnb/l1
+ - To run in timer mode : ./l1.sh -e
+ - L1 is up when following prints are seen on console:
+
+ | Non BBU threads in application
+ | \==================================================================
+ | nr5g_gnb_phy2mac_api_proc_stats_thread: [PID: 8659] binding on [CPU 0] [PRIO: 0] [POLICY: 1]
+ | wls_rx_handler (non-rt): [PID: 8663] binding on [CPU 0]
+ | \==================================================================
+
+ PHY>welcome to application console
+
+ 2. Execute FAPI Translator:
+
+ a. Setup environment:
+
+ - cd <intel_directory>/phy/
+ - source ./setupenv.sh
+
+ b. Run FAPI translator binary:
+
+ - cd <intel_directory>/phy/fapi_5g/bin/
+ - ./oran_5g_fapi --cfg=oran_5g_fapi.cfg
+
+ 3. Execute CU Stub and RIC Stub:
+
+ a. Run steps in sections B.1-B.3.
+
+ 4. Execute DU:
+
+ a. DU execution folder
+
+ - cd <rsys_directory>/l2/bin/odu
+
+ b. Export WLS library path
+
+ - export LD_LIBRARY_PATH=<intel_directory>/phy/wls_lib/lib:$LD_LIBRARY_PATH
+
+ c. Run ODU binary
+
+ - ./odu
+
+
+D. Message Flow:
+----------------
+
+O-DU High opens WLS interface during bring up. Message exchanges can begin once the interface is ready.
+Following diagram shows P5 messages exchange with O-DU Low in timer mode.
+
+.. figure:: L1-L2_Message_Flow.jpg
+ :width: 600
+ :alt: Figure 1 O-DU High - O-DU Low Message Flow Diagram
+
+ Figure 1 - O-DU High - O-DU Low Message Flow Diagram
+
+Note: UL IQ-Sample request and response are needed by Intel O-DU Low in timer mode(testing mode) only. Code changes for
+these are guarded under INTEL_TIMER_MODE flag which can be enabled using compilation option "PHY_MODE=TIMER", as mention
+in section C.I.1.d .