From: lal.harshita Date: Mon, 23 Nov 2020 12:11:06 +0000 (+0530) Subject: Added user-guide.rst and api-docs.rst X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=3d0f5dbfe97d8b58d6f2963bfd1b457ea990162e;hp=514d4c21e79d37636005186dd9ac5510742b7618;p=o-du%2Fl2.git Added user-guide.rst and api-docs.rst Change-Id: I872d3d942f0094f7d39782d0e703f5382cacc67c Signed-off-by: lal.harshita --- diff --git a/docs/L1-L2_Message_Flow.jpg b/docs/L1-L2_Message_Flow.jpg new file mode 100644 index 000000000..bbcd10853 Binary files /dev/null and b/docs/L1-L2_Message_Flow.jpg differ diff --git a/docs/api-docs.rst b/docs/api-docs.rst new file mode 100644 index 000000000..c36e1e58b --- /dev/null +++ b/docs/api-docs.rst @@ -0,0 +1,158 @@ +.. 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. + diff --git a/docs/index.rst b/docs/index.rst index 0a80ad9f8..f81a70b7a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,8 @@ Welcome to O-RAN SC O-DU-L2 Documentation :caption: Contents: overview.rst + api-docs.rst + user-guide.rst release-notes.rst diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 000000000..afe00cbc6 --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,215 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) + + +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 /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 /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 /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 :ODU "192.168.130.81" + b. ifconfig :CU_STUB "192.168.130.82" + c. ifconfig :RIC_STUB "192.168.130.80" + +2. Execute CU Stub: + + a. CU execution folder + + - cd /l2/bin/cu_stub + + b. Run CU Stub binary + + - ./cu_stub + +3. Execute RIC Stub: + + a. RIC execution folder + + - cd /l2/bin/ric_stub + + b. Run RIC Stub binary + + - ./ric_stub + +4. Execute DU: + + a. DU execution folder + + - cd /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 /l2/src/wls_lib. Copy wls_lib.h from /phy/wls_lib/ to + /l2/src/wls_lib. + + b. Create folder /l2/src/dpdk_lib. Copy following files from + /dpdk-19.11/x86_64-native-linuxapp-gcc/include/ to /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 /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 /phy/ + - source ./setupenv.sh + + b. Run O-DU Low binary : + + - cd /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 /phy/ + - source ./setupenv.sh + + b. Run FAPI translator binary: + + - cd /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 /l2/bin/odu + + b. Export WLS library path + + - export LD_LIBRARY_PATH=/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 .