From: HariomGupta Date: Wed, 9 Dec 2020 14:10:23 +0000 (+0530) Subject: Added details of O1 Module in docs.[Issue-Id: ODUHIGH-256] X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=afa3f9350047a92dca19e04dc5181f368b281b8b;p=o-du%2Fl2.git Added details of O1 Module in docs.[Issue-Id: ODUHIGH-256] Signed-off-by: HariomGupta Change-Id: I9cf301ff80ea8bf297cccf48bc7b9c7e0f9754bf --- diff --git a/docs/ODU-O1-Arch.jpg b/docs/ODU-O1-Arch.jpg new file mode 100644 index 000000000..06c19846d Binary files /dev/null and b/docs/ODU-O1-Arch.jpg differ diff --git a/docs/ODU-O1-GetAlarmListFlow.jpg b/docs/ODU-O1-GetAlarmListFlow.jpg new file mode 100644 index 000000000..cd205078f Binary files /dev/null and b/docs/ODU-O1-GetAlarmListFlow.jpg differ diff --git a/docs/README b/docs/README index 742a102a8..ccceee879 100644 --- a/docs/README +++ b/docs/README @@ -63,10 +63,6 @@ D. How to Clean and Build: cd l2/build/odu b. Building ODU binary make odu MACHINE=BIT64 MODE=FDD - - Build with O1 module enabled: - make odu MACHINE=BIT64 MODE=FDD O1_ENABLE=YES - c. Cleaning ODU binary make clean_odu MACHINE=BIT64 MODE=FDD @@ -89,12 +85,19 @@ D. How to Clean and Build: 4. Cleaning ODU, CU Stub and RIC Stub: make clean_all -5. Building O1 binary: +5. Building ODU binary with O1 interface enabled: a. Build folder + cd l2/build/odu + b. Building ODU with O1 module enabled: + make odu MACHINE=BIT64 MODE=FDD O1_ENABLE=YES + c. Cleaning ODU binary + make clean_odu MACHINE=BIT64 MODE=FDD + + d. Build folder cd l2/build/o1 - b. Building O1 binary + e. Building O1 binary make o1 MACHINE=BIT64 - c. Cleaning O1 binary + f. Cleaning O1 binary make clean_o1 @@ -105,30 +108,30 @@ E. How to execute: b. ifconfig :CU_STUB "192.168.130.82" c. ifconfig :RIC_STUB "192.168.130.80" -2. Execute CU Stub: +2. Execute O1 (only if O-DU is built with O1 interface enabled): + a. O1 execution folder: + cd l2/build/o1/bin/o1 + b. Run O1 binary: + ./o1 + +3. Execute CU Stub: a. CU execution folder: cd l2/bin/cu_stub b. Run CU Stub binary: ./cu_stub -3. Execute RIC Stub: +4. Execute RIC Stub: a. RIC execution folder: cd l2/bin/ric_stub b. Run RIC Stub binary: ./ric_stub -4. Execute DU: +5. Execute DU: a. DU execution folder: cd l2/bin/odu b. Run ODU binary: ./odu -5. Execute O1 - a. O1 execution folder: - cd l2/build/o1/bin/o1 - b. Run O1 binary: - ./o1 - PS: CU stub and RIC stub must be run (in no particular sequence) before ODU If O1 module is enabled it must be run before ODU @@ -196,3 +199,41 @@ II. Execution c. Run ODU binary ./odu + +G. How to execute the Health Check : get alarm-list +---------------------------------------------------- + + Steps: + + 1. Start Netconf netopeer client + + 2. Connect to the server with + + user: netconf + pwd: netconf + + 3. Send a Netconf get request for alarms xpath + + Here are the steps as executed in the terminal + + netopeer2-cli + > connect --login netconf + Interactive SSH Authentication + Type your password: + Password: + > get --filter-xpath /o-ran-sc-odu-alarm-v1:odu/alarms + DATA + + + + 1009 + cell id [1] is up + 2 + Active + cell UP + + + + + The XML output is a list of active alarms in the O-DU High system. + diff --git a/docs/api-docs.rst b/docs/api-docs.rst index f6f623c5f..2071c15e8 100644 --- a/docs/api-docs.rst +++ b/docs/api-docs.rst @@ -154,3 +154,7 @@ Additional APIs c. DL RRC Message Response - Informs DU APP if a DL RRC Message was successfuly processed at RLC and sent to MAC. +3. DU APP - O1 Interface + + a. DU sends alarms to O1 for cell up and cell down events using the alarm interface API + diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index d25404950..6ef573812 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -26,9 +26,9 @@ O-DU High uses C languages. The coding guidelines followed are: .. figure:: LicHeader.jpg :width: 600 - :alt: Figure 6 License Header and Footer + :alt: Figure 8 License Header and Footer - Figure 6 : License Header and Footer + Figure 8 : License Header and Footer O-DU High code --------------- @@ -280,9 +280,9 @@ Here, .. figure:: ModeofCommunication.jpg :width: 600 - :alt: Figure 7 Mode of communication between O-DU High entities + :alt: Figure 9 Mode of communication between O-DU High entities - Figure 7: Mode of communication between O-DU High entities + Figure 9: Mode of communication between O-DU High entities Steps of Communication ++++++++++++++++++++++ @@ -344,9 +344,9 @@ Below figure summarized the above steps of intra O-DU High communication .. figure:: StepsOfCommunication.jpg :width: 600 - :alt: Figure 8 Communication between entities + :alt: Figure 10 Communication between entities - Figure 8: Steps of Communication between O-DU High entities + Figure 10: Steps of Communication between O-DU High entities Communication with Intel O-DU Low @@ -752,3 +752,42 @@ Additional Utility Functions - cnt - number of bytes to be copied - ccnt - number of bytes copied +O1 Module +---------- + +Coding Style +^^^^^^^^^^^^ + +O1 uses GNU C++ language. + +ODU - O1 Communication +^^^^^^^^^^^^^^^^^^^^^^ + +O-DU High and O1 module communicate on a TCP socket. + +O-DU High sends alarm messages in the following structure using Alarm Interface APIs. + + +Alarm Structure + | typedef struct + | { + | MsgHeader msgHeader; /\* Alarm action raise/clear \*/ + | EventType eventType; /\* Alarm event type \*/ + | char objectClassObjectInstance[OBJ_INST_SIZE]; /\* Name of object that raise/clear an alarm \*/ + | char alarmId[ALRM_ID_SIZE]; /\* Alarm Id \*/ + | char alarmRaiseTime[DATE_TIME_SIZE]; /\* Time when alarm is raised \*/ + | char alarmChangeTime[DATE_TIME_SIZE]; /\* Time when alarm is updated \*/ + | char alarmClearTime[DATE_TIME_SIZE]; /\* Time when alarm is cleared \*/ + | char probableCause[TEXT_SIZE]; /\* Probable cause of alarm \*/ + | SeverityLevel perceivedSeverity; /\* Severity level of alarm \*/ + | char rootCauseIndicator[TEXT_SIZE]; /\* Root cause of alarm \*/ + | char additionalText[TEXT_SIZE]; /\* Additional text describing alarm \*/ + | char additionalInfo[TEXT_SIZE]; /\* Any additional information \*/ + | char specificProblem[TEXT_SIZE]; /\* Any specific problem related to alarm \*/ + | }AlarmRecord; + + +O1 - Netconf Communication +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +O1 communicates with the Netconf server using sysrepo and libyang APIs diff --git a/docs/installation-guide.rst b/docs/installation-guide.rst index f2e86be5b..5a4ea45c5 100644 --- a/docs/installation-guide.rst +++ b/docs/installation-guide.rst @@ -24,6 +24,9 @@ Version history | **Date** | **Ver.** | **Author** | **Comment** | | | | | | +--------------------+--------------------+--------------------+--------------------+ +| 2020-12-04 | 1.0.1 | HCL Technologies | Cherry Release | +| | | Ltd. | | ++--------------------+--------------------+--------------------+--------------------+ | 2020-12-04 | 1.0 | Radisys | Cherry Release | | | | | | +--------------------+--------------------+--------------------+--------------------+ @@ -94,6 +97,19 @@ Following libraries are required to compile and execute O-DU High: - Ubuntu : sudo apt-get install -y libpcap-dev - CentOS : sudo yum install -y libpcap-devel +Following libraries are required to compile and execute O1 module: + +- Netconf: + libssh, libyang, libnetconf2, sysrepo, netopeer2 + + Script is provided in the following folder to install these libraries + + - Ubuntu : + + | cd /l2/build/o1 + | sudo ./install_lib.sh + + Cloning code -------------- @@ -118,10 +134,15 @@ Compilation - Clean O-DU High binary make clean_odu MACHINE=BIT64 MODE=FDD + - Build O-DU High binary make odu MACHINE=BIT64 MODE=FDD + + To build with O1 interface enabled: + + make odu MACHINE=BIT64 MODE=FDD O1_ENABLE=YES - Build CU Stub : @@ -151,6 +172,33 @@ Compilation make ric_stub NODE=TEST_STUB MACHINE=BIT64 MODE=FDD +- Build O-DU High with O1 interface enabled: + + - Navigate to o1 Build folder + + cd /l2/build/o1 + + - Clean O1 binary + + make clean_o1 MACHINE=BIT64 + + - Build O1 binary + + make o1 MACHINE=BIT64 + + - Navigate to odu Build folder + + cd /l2/build/odu + + - Clean O-DU High binary + + make clean_odu MACHINE=BIT64 MODE=FDD + + - Build O-DU High binary + + make odu MACHINE=BIT64 MODE=FDD O1_ENABLE=YES + + The above generated images can be found at: @@ -159,3 +207,5 @@ The above generated images can be found at: - CU Stub - /l2/bin/cu_stub - RIC Stub - /l2/bin/ric_stub + +- O1 - /l2/build/o1/bin/o1 diff --git a/docs/overview.rst b/docs/overview.rst index caeffa656..61f8ff8c3 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -98,6 +98,30 @@ O-DU Utility and Common Functions These modules contain platform specific files and support O-DU High functionality and message exchanges. +O1 Module +^^^^^^^^^^ + +.. figure:: ODU-O1-Arch.jpg + :width: 600 + :alt: Figure 2 O1 Architecture + + Figure 2 - O1 Architecture + +As shown in figure 2 the O1 module in O-DU High runs a separate process and communicates with ODU-High process over a TCP interface. O1 module uses API calls for interacting with the Netconf server(Netopeer) and datastore(sysrepo) for providing the Netconf interface. + +O1 architecture has following components: + +- Netconf Manager: Subscribe to Netconf YANG modules and events. Register callback handler methods. + +- Alarm Manager: Stores and manages(add/updated/delete) alarms. + +- TCP server: Receives the alarm messages sent from O-DU High over TCP socket. + +- TCP Client Alarm Interface : Integrates with O-DU High module and provides an interface for sending the alarm messages to O1 module over TCP socket. + +- Netopeer server: Serves the northbound SMO/OAM Netconf requests. + + O-DU-High Interfaces ====================== @@ -108,10 +132,10 @@ This section describes the other modules that O-DU High interfaces with, as show :width: 600 :alt: O-DU High Interfaces - Figure 2 - O-DU High Interfaces + Figure 3 - O-DU High Interfaces -As shown in Figure 2, O-DU High interfaces with the following modules: +As shown in Figure 3, O-DU High interfaces with the following modules: - O-CU: O-DU High communicates with O-CU on the F1AP interface. The control message exchanges are on F1-C while data message exchanges are on F1-U interfaces. The below F1AP messages on F1-C are implemented, as per @@ -204,10 +228,10 @@ This section describes the cell-up procedure within O-DU High. :width: 720 :alt: Cell Up and Broadcast Procedure - Figure 3 - O-DU High Cell Up and Broadcast Procedure + Figure 4 - O-DU High Cell Up and Broadcast Procedure -As seen in the Figure 3, +As seen in the Figure 4, - The DU APP module of O-DU High sends F1 Setup Request to O-CU. This message contains a list of cells that the O-DU High has been configured with. - The O-CU responds with F1 Setup Response. This message contains a list of cells which must be activated. @@ -283,15 +307,39 @@ The above channels are used to achieve the below messages: - RRC Reconfiguration Complete -Figure 4 below depicts the above call flow, inclusive of all interfaces: +Figure 5 below depicts the above call flow, inclusive of all interfaces: .. figure:: UeAttach.png :width: 800 :alt: O-DU High UE Attach Flow - Figure 4 - UE Attach Flow + Figure 5 - UE Attach Flow + + +O1 Netconf get-alarm list procedure +----------------------------------- + +This section describes the *Health Status Retrieval* scenario of O-DU High health-check. It enables a northbound client(SMO) to retrieve the health of the ODU-High based on the last self-check performed. The alarm-list is provided as the response to the request via O1 Netconf interface. + + +.. figure:: ODU-O1-GetAlarmListFlow.jpg + :width: 720 + :alt: Figure 6 O1 get alarm-list flow + + Figure 6 - O1 get alarm-list flow + + +As seen in the Figure 6, + +- On the cell state change from de-active to activate, ODU High process raises a cell up alarm message and sends it over the TCP socket using the TCP client Alarm Interface API. + +- On other side a TCP server, running as a thread, in O1 module receives the cell up alarm message and it passes the alarm information to the Alarm Manager. + +- Alarm Manager stores the alarm data in a list. +- Whenever SMO/OAM requires the current alarm list, it sends a Netconf get request. The request is received by the Netopeer Server and a callback method, registered with the Netconf Manager, is invoked. +- The callback function fetches the alarm list from Alarm Manager and sends it back to the client (SMO/OAM) via Netconf interface. OSC Testcases Supported ========================= diff --git a/docs/release-notes.rst b/docs/release-notes.rst index 61f405bf3..eebe87bf3 100644 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -20,8 +20,8 @@ Version history | **Date** | **Ver.** | **Author** | **Comment** | | | | | | +--------------------+--------------------+--------------------+--------------------+ -| 2020-12-04 | 3.0.0 | Radisys | Cherry Release | -| | | | | +| 2020-12-04 | 3.0.0 | Radisys, HCL | Cherry Release | +| | | Technologies Ltd. | | +--------------------+--------------------+--------------------+--------------------+ | 2020-06-17 | 2.0.0 | Radisys | Bronze Release | | | | | | @@ -318,6 +318,8 @@ System Limitations - O-DU High has not been integrated with O-DU Low and O-CU. +- O-DU High O1 module has not been integrated with SMO/OAM so a Netconf CLI client is used to demo the get alarm-list flow + Known Issues ^^^^^^^^^^^^^ None diff --git a/docs/user-guide.rst b/docs/user-guide.rst index eb5ccfc98..8a1f7b60e 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -24,7 +24,35 @@ I. Execution - On locally compiling O-DU High Source Code b. ifconfig :CU_STUB "192.168.130.82" c. ifconfig :RIC_STUB "192.168.130.80" -2. Execute CU Stub: +2. Execute O1 (only if O-DU is built with O1 interface enabled): + + a. Navigate to O1 build folder + + - cd /l2/build/o1 + + b. Create a new netconf user and install the YANG module + + Switch to root user and run following commands + + | adduser --system netconf && \\ + | echo "netconf:netconf" | chpasswd + + | mkdir -p /home/netconf/.ssh && \\ + | ssh-keygen -A && \\ + | ssh-keygen -t dsa -P '' -f /home/netconf/.ssh/id_dsa && \\ + | cat /home/netconf/.ssh/id_dsa.pub > /home/netconf/.ssh/authorized_keys + + sysrepoctl -i ./yang/o-ran-sc-odu-alarm-v1.yang + + c. Navigate to O1 execution folder + + - cd /l2/build/o1/bin/o1 + + d. Run O1 binary + + - ./o1 + +3. Execute CU Stub: a. Navigate to CU execution folder @@ -34,7 +62,7 @@ I. Execution - On locally compiling O-DU High Source Code - ./cu_stub -3. Execute RIC Stub: +4. Execute RIC Stub: a. Navigate to RIC execution folder @@ -44,7 +72,7 @@ I. Execution - On locally compiling O-DU High Source Code - ./ric_stub -4. Execute O-DU High: +5. Execute O-DU High: a. Navigate to ODU execution folder @@ -54,7 +82,7 @@ I. Execution - On locally compiling O-DU High Source Code - ./odu -PS: CU stub and RIC stub must be run (in no particular sequence) before ODU +PS: CU stub and RIC stub must be run (in no particular sequence) before ODU. If O-DU High is built with O1 interface enabled, the O1 binary must be run before all other binaries. II. Execution - Using Docker Images ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -193,10 +221,50 @@ Following diagram shows P5 messages exchanged with O-DU Low in timer mode. .. figure:: O-DU_High_Low_Flow.jpg :width: 600 - :alt: Figure 1 O-DU High - O-DU Low Message Flow Diagram + :alt: Figure 7 O-DU High - O-DU Low Message Flow Diagram - Figure 5 - O-DU High - O-DU Low Message Flow Diagram + Figure 7 - 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 mentioned in section B.I.1.d . + + +D. Health Check execution: get alarm-list +------------------------------------------- + +To execute the get alarm-list flow, following steps are required to be executed: + + 1. Start Netconf netopeer client + + 2. Connect to the server with + + | user: netconf + | pwd: netconf + + 3. Send a Netconf get request for alarms xpath + +Here are the steps as executed in the terminal + + | netopeer2-cli + | > connect --login netconf + | Interactive SSH Authentication + | Type your password: + | Password: + | > get --filter-xpath /o-ran-sc-odu-alarm-v1\:odu/alarms + | DATA + | + | + | + | 1009 + | cell id [1] is up + | 2 + | Active + | cell UP + | + | + | + +The XML output is a list of active alarms in the O-DU High system. + +Note: Integration with SMO/OAM is not yet done so a Netconf CLI client(netopeer2-cli) is used to connect to the Netconf server and send the get request.