--- /dev/null
+from docs_conf.conf import *
+linkcheck_ignore = [
+ 'http://localhost.*',
+ 'http://127.0.0.1.*',
+ 'https://gerrit.o-ran-sc.org.*'
+]
+#extensions = ['sphinx.ext.autosectionlabel']
+#intersphinx_mapping = {}
+#intersphinx_mapping['ric-app-hw'] = ('https://o-ran-sc-doc.readthedocs.io/projects/o-ran-sc-ric-app-hw/en/%s' % 'latest')
--- /dev/null
+---
+project_cfg: oran
+project: ric-app-hw
--- /dev/null
+-- ASN1START
+-- **************************************************************
+-- E2SM-HelloWorld
+-- Information Element Definitions
+--
+-- **************************************************************
+
+E2SM-HelloWorld-IEs { }
+
+DEFINITIONS AUTOMATIC TAGS ::=
+
+BEGIN
+
+-- **************************************************************
+--
+-- Lists
+--
+-- **************************************************************
+
+maxofRANParameters INTEGER ::= 255
+
+-- E2 Service model IEs
+
+-- ---------------------------------------------------
+-- Event Trigger Definition OCTET STRING contents
+-- ---------------------------------------------------
+
+-- E2SM-HelloWorld-EventTriggerDefinition IE
+E2SM-HelloWorld-EventTriggerDefinition ::= CHOICE{
+ eventDefinition-Format1 E2SM-HelloWorld-EventTriggerDefinition-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-eventTriggerDefinition IE Format 1
+E2SM-HelloWorld-EventTriggerDefinition-Format1 ::= SEQUENCE{
+ triggerNature HW-TriggerNature,
+ ...
+}
+
+-- ---------------------------------------------------
+-- Action Definition OCTET STRING contents
+-- ---------------------------------------------------
+E2SM-HelloWorld-ActionDefinition ::= CHOICE{
+ actionDefinition-Format1 E2SM-HelloWorld-ActionDefinition-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-actionDefinition IE used for Action Format 1
+E2SM-HelloWorld-ActionDefinition-Format1 ::= SEQUENCE{
+ ranParameter-List SEQUENCE (SIZE(1..maxofRANParameters)) OF RANparameter-Item OPTIONAL,
+ ...
+}
+
+
+
+-- ---------------------------------------------------
+-- Indication Header OCTET STRING contents
+-- ---------------------------------------------------
+
+E2SM-HelloWorld-IndicationHeader ::= CHOICE{
+ indicationHeader-Format1 E2SM-HelloWorld-IndicationHeader-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-indicationHeader Format 1
+E2SM-HelloWorld-IndicationHeader-Format1 ::= SEQUENCE{
+ indicationHeaderParam HW-Header,
+ ...
+}
+
+-- ---------------------------------------------------
+-- Indication Message OCTET STRING contents
+-- ---------------------------------------------------
+
+-- E2SM-HelloWorld-indicationMessage IE
+E2SM-HelloWorld-IndicationMessage ::= CHOICE{
+ indicationMessage-Format1 E2SM-HelloWorld-IndicationMessage-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-IndicationMessage Format 1
+E2SM-HelloWorld-IndicationMessage-Format1 ::= SEQUENCE{
+ indicationMsgParam HW-Message,
+ ...
+}
+
+
+-- ---------------------------------------------------
+-- Call Process ID
+-- ---------------------------------------------------
+
+-- Not defined in this E2SM
+
+-- ---------------------------------------------------
+-- Control Header OCTET STRING contents
+-- ---------------------------------------------------
+
+-- E2SM-HelloWorld-ControlHeader
+E2SM-HelloWorld-ControlHeader ::= CHOICE{
+ controlHeader-Format1 E2SM-HelloWorld-ControlHeader-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-ControlHeader Format 1
+E2SM-HelloWorld-ControlHeader-Format1 ::= SEQUENCE{
+ controlHeaderParam HW-Header,
+ ...
+}
+
+
+-- ---------------------------------------------------
+-- Control Message OCTET STRING contents
+-- ---------------------------------------------------
+
+-- E2SM-HelloWorld-ControlMessage
+E2SM-HelloWorld-ControlMessage ::= CHOICE{
+ controlMessage-Format1 E2SM-HelloWorld-ControlMessage-Format1,
+ ...
+}
+
+-- E2SM-HelloWorld-controlMessage Format 1
+E2SM-HelloWorld-ControlMessage-Format1 ::= SEQUENCE{
+ controlMsgParam HW-Message,
+ ...
+}
+
+-- ---------------------------------------------------
+-- commmon IEs
+-- ---------------------------------------------------
+
+-- A
+-- B
+-- C
+-- D
+-- E
+-- F
+-- G
+-- H
+
+HW-Header ::= INTEGER
+
+HW-Message ::= OCTET STRING
+
+HW-TriggerNature ::= ENUMERATED{
+ now,
+ onchange,
+ ...
+}
+-- I
+-- J
+-- K
+-- L
+-- M
+-- N
+-- O
+-- P
+-- Q
+-- R
+
+
+RANparameter-Item ::= SEQUENCE {
+ ranParameter-ID RANparameter-ID,
+ ranParameter-Name RANparameter-Name,
+ ranParameter-Test RANparameter-Test,
+ ranParameter-Value RANparameter-Value,
+ ...
+}
+
+
+RANparameter-ID ::= INTEGER (0..maxofRANParameters)
+
+RANparameter-Name ::= OCTET STRING
+
+RANparameter-Test ::= ENUMERATED{
+ equal,
+ greaterthan,
+ lessthan,
+ contains,
+ present,
+ ...
+}
+
+RANparameter-Value ::= OCTET STRING
+
+-- S
+-- T
+-- U
+-- V
+-- W
+-- X
+-- Y
+-- Z
+
+END
+-- ASN1STOP
+
+
+
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T
+
+
+Welcome to O-RAN SC HelloWorld xAPP Documentation
+========================================================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ overview.rst
+ release-notes.rst
+ installation-guide.rst
+ user-guide.rst
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T
+
+
+Installation Guide
+==================
+
+.. contents::
+ :depth: 3
+ :local:
+
+Abstract
+--------
+
+This document describes how to install the HelloWorld (HW) xAPP.
+
+Version history
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+| 2020-05-19 |1.0.0 |Shraboni Jana | Bronze Release |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+
+
+Introduction
+------------
+
+This document provides guidelines on how to install and configure the HW xAPP in various environments/operating modes.
+The audience of this document is assumed to have good knowledge in RIC Platform.
+
+
+Preface
+-------
+The HW xAPP can be run directly as a Linux binary, as a docker image, or in a pod in a Kubernetes environment. The first
+two can be used for testing/evaluation. The last option is how an xAPP is deployed in the RAN Intelligent Controller environment.
+This document covers all three methods.
+
+
+
+
+Software Installation and Deployment
+------------------------------------
+The build process assumes a Linux environment with a gcc (>= 4.0) compatible compiler and has been tested on Ubuntu. For building docker images,
+the Docker environment must be present in the system.
+
+
+Build Process
+~~~~~~~~~~~~~
+The HW xAPP can be either tested as a Linux binary or as a docker image.
+ 1. **Linux binary**:
+ The HW xAPP may be compiled and invoked directly. Pre-requisite software packages that must be installed prior to compiling are documented in the Dockerfile in the repository. README file in the repository mentions the steps to be followed to make "hw-xapp-main" binary.
+
+ 2. **Docker Image**: From the root of the repository, run *docker --no-cache build -t <image-name> ./* .
+
+
+Deployment
+~~~~~~~~~~
+**Invoking xAPP docker container directly** (not in RIC Kubernetes env.):
+ xAPP descriptor(config-file.json) is available say under directory /home/test-config, the docker image can be invoked as *docker run --net host -it --rm -v "/home/test-config:/opt/ric/config" --name "HW-xAPP" <image>*.
+
+
+Testing
+--------
+
+Unit tests for various modules of the HW xAPP are under the *test/* repository. HW xAPP uses Google Test Framework for unit testing. Currently, the unit tests must be compiled and executed in a Linux environment (*make* in test directory) and Docker Image(*docker build -f Dockerfile-Unit-Tests .*). All software packages required for compiling the HW xAPP must be installed (as listed in the Dockerfile-Unit-Tests) for linux binary.
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T
+
+
+
+
+HelloWorld xAPP Overview
+================================
+
+The HelloWorld(HW) xAPP repository contains open-source code for a prototype xAPP for near real-time
+RAN Intelligent Controller. The HW xAPP aims to provide basic implementation of :
+
+-E2, A1 interfaces interactions.
+
+-Read-write operations into a persistent storage.
+
+-xAPP Configuration management.
+
+-RMR & A1 Healthcheck
+
+
+The HW xAPP code is intended to follow xAPP C++ Framework to implement the prototype.
+
+
+
+
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T
+
+
+Release Notes
+=============
+
+
+This document provides the release notes for the Bronze Release of the HelloWorld (HW) xAPP.
+
+.. contents::
+ :depth: 3
+ :local:
+
+
+Version history
+---------------
+
++--------------------+--------------------+--------------------+--------------------+
+| **Date** | **Ver.** | **Author** | **Comment** |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+| 2020-21-05 | 1.0.0 | Shraboni Jana | First draft |
+| | | | |
++--------------------+--------------------+--------------------+--------------------+
+
+
+
+Summary
+-------
+
+The Bronze release of the HW xAPP demonstrates E2 and A1 interface interactions, persistent storage read-write, RMR and A1 healthcheck.
+HW xAPP uses its HelloWorld E2SM (can be found at hw/src/xapp-asn/e2sm/) for ASN PDUs.
+
+
+Release Data
+------------
+
++--------------------------------------+--------------------------------------+
+| **Project** | RAN Intelligent Controller |
+| | |
++--------------------------------------+--------------------------------------+
+| **Repo/commit-ID** | ric-app/hw |
+| | |
++--------------------------------------+--------------------------------------+
+| **Release designation** | Bronze |
+| | |
++--------------------------------------+--------------------------------------+
+| **Release date** | 2020-21-05 |
+| | |
++--------------------------------------+--------------------------------------+
+| **Purpose of the delivery** | open-source Hello World xAPP |
+| | |
+| | |
++--------------------------------------+--------------------------------------+
+
+Components
+----------
+
+- *src/* contains the main source code. Under that directory :
+
+ + *xapp.hpp, xapp.cc* is generic class which implements all the xAPP functionalities for xapp developer to pick and choose.
+ + *xapp-utils/* contains generic classes for - persistent data management, configuration management, RMR send/receive etc.
+ + *xapp-asn/* contains generic classes for generating/processing ASN1 E2AP and E2SM messages.
+ + *xapp-mgmt/* contains code specific xapp management of subscriptions and received messages.
+
+- *test/* contains unit tests showing how to use various components.
+
+
+
+
+Limitations
+-----------
+- The HW xAPP doesn't have any usecase in particular to display SDL capabilities and hence incorporated only in unit tests.
+
+- The subscription process assumes, on sending subscription request results in valid subscription response.
+
+- The HW xAPP doesn't address any RIC usecase in particular.
--- /dev/null
+sphinx
+sphinx-rtd-theme
+sphinxcontrib-httpdomain
+recommonmark
+lfdocs-conf
--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. Copyright (C) 2020 AT&T
+
+============================================================================================
+HelloWorld xAPP (C++)
+============================================================================================
+--------------------------------------------------------------------------------------------
+User's Guide
+--------------------------------------------------------------------------------------------
+
+Introduction
+============================================================================================
+
+The RIC platform provides set of functions that the xAPPs can use to accomplish their tasks.
+The HW xAPP is envisioned to provide xAPP developers, examples of implementing these sets of functions.
+Note, HW xAPP does not address/implement any RIC Usecases.
+
+HelloWorld xAPP Features
+============================================================================================
+
+RIC Platform provides many APIs and libraries to aid the development of xAPPs. All xAPPs will have some custom
+processing functional logic core to the xApp and some additional non-functional platform related processing using
+these APIs and libraries. HW xAPP attempts to show the usage of such additional platform processing using RIC platform APIs and libraries.
+
+
+The Hello World xApp demonstrates how an xApp uses the A1, and E2 interfaces and persistent database read-write operations.
+The following paragraphs cover the various steps involved to create an HelloWorld xApp instance, setting its configuration,
+retrieving R-NIB data, sending subscription, connecting SDL, RME & A1 Healthcheck and usage of "Hello World SM"
+
+HelloWorld Creation
+============================================================================================
+
+The creation of the xApp instance is as simple as invoking
+the object's constructor with two required parameters:
+
+
+HW xAPP, may choose to create following objects for obtaining desired set of functionalities provided under xapp-utils:
+
+XappRmr
+--------------------------------------------------------------------------------------------
+An xAPP can have the capability of receiving and sending rmr messages. This is achieved by creating an XappRmr object. The constructor of xAPPRMR object requires xAPP developer to provide
+xAPP's listening port and developer configurable number of attempts need to be made to send the message. The key functionalities of the class being :
+
+1. Setting RMR initial context: ...xapp_rmr_init(...)
+
+2. Sending RMR message: ...xapp_rmr_send(xapp_rmr_header, void*)
+
+3. Receiving RMR message: ...xapp_rmr_receive(msghandler,...)
+
+The RMR Header can be defined using xapp_rmr_header :
+::
+
+ typedef struct{
+ struct timespec ts;
+ int32_t message_type; //mandatory
+ int32_t state;
+ int32_t payload_length; //mandatory
+ unsigned char sid[RMR_MAX_SID];
+ unsigned char src[RMR_MAX_SRC];
+ unsigned char meid[RMR_MAX_MEID];
+
+ } xapp_rmr_header;
+
+Except for message type and payload length, its developers prerogative to use remaining header information.
+The XappMsgHandler (msghandler) instance in xapp_rmr_receive function handles received messages. The handling of messages is based on
+the usecase catered by a xAPP. Hence, XappMsgHandler class used in HW xAPP is not very comprehensive and addresses only Healthcheck Messages.
+
+XappSettings
+-------------------------------------------------------------------------------------------
+An xAPP has the capability to use environment variables or xapp-descriptor information as its configuration settings
+creating XappSettings object, whose key functions being :
+
+1. Loading Default Settings: ...loadDefaultSettings()
+
+2. Loading Environment Variables: ...loadEnvVarSettings()
+
+3. Loading Command Line Settings: ...loadCmdlineSettings(argc, argv)
+
+XappSDL
+--------------------------------------------------------------------------------------------
+An xAPP can have the capability to read and write into a persistent storage (key-value store) creating XappSDL object.
+for a namespace. The key functionalities available currently are:
+
+
+1. Getting Data from SDL: ... get_data(...);
+
+2. Setting Data to SDL: ... set_data(...);
+
+The HW xAPP can be instantiationed as following:
+::
+
+ HW_Xapp = Xapp(XappRmr object, XappSettings object,...);
+
+
+HelloWorld E2 and A1 Message Handling
+============================================================================================
+Helper Objects
+--------------------------------------------------------------------------------------------
+HW xAPP creates wrapper datastructures mirroring ASN and JSON messages. These datastructures facilitate processing of
+E2 and A1 messages in the xAPP. A sample helper object for A1 Health Check message being:
+::
+
+ struct a1_policy_helper{
+ std::string operation;
+ std::string policy_type_id;
+ std::string policy_instance_id;
+ std::string handler_id;
+ std::string status;
+ };
+
+And a sample E2AP Control datastructure:
+::
+
+ struct ric_control_helper{
+ ric_control_helper(void):req_id(1), req_seq_no(1), func_id(0), action_id(1), control_ack(-1), cause(0), sub_cause(0), control_status(1), control_msg(0), control_msg_size(0), control_header(0), control_header_size(0), call_process_id(0), call_process_id_size(0){};
+ long int req_id, req_seq_no, func_id, action_id, control_ack, cause, sub_cause, control_status;
+
+ unsigned char* control_msg;
+ size_t control_msg_size;
+
+ unsigned char* control_header;
+ size_t control_header_size;
+
+ unsigned char *call_process_id;
+ size_t call_process_id_size;
+
+ };
+
+As mentioned, these datastructures are very much tied to the message specifications.
+
+
+
+ASN Encoding/Decoding
+--------------------------------------------------------------------------------------------
+RIC platform provided ASN1C (modified) library is used for processing ASN1 messages. HW xAPP, for each
+ASN message type, uses a class which is responsible for handling a particular message type.
+The class encapsulates, the APIs and datastructures used in ASN1C using helper objects. For example:
+::
+
+ class ric_control_response{
+ ...
+ bool encode_e2ap_control_response(..., ric_control_helper &);
+ bool set_fields(..., ric_control_helper &);
+ bool get_fields(..., ric_control_helper &);
+ ...
+ }
+
+Note, the helper objects and message type processing classes can be found under xapp-asn subdirectories.
+
+E2AP Subscription
+--------------------------------------------------------------------------------------------
+In HW xAPP, we consider sunny-side scenario, in which for a E2AP subscription request sent, it is assumed,
+that HW xAPP will be receiving E2AP subscription response. Handling advanced subscription (class SubscriptionHandler) flows is out of the
+scope of HW xAPP. Current form of class SubscriptionHandler has following key functionalities:
+
+1. manage_subscription_request(...)
+
+2. manage_subscription_response(...)
+
+
+The manage_subscription_request function waits for the response for a specified time for subscription response
+and if no response is received within a specified time, gives a time out error message. A subscription message
+is created using ASN Encodong/Decoding and Helper classes. (Refer test_sub.h). HW xAPP sends the subscriptions based
+on the gNodeB IDs received from RNIB. Please refer following function in xapp.* for RNIB transactions: set_rnib_gnblist(...)
+
+
+E2SM Subscription, Indication, Control
+--------------------------------------------------------------------------------------------
+HellowWorld E2SM (e2sm-HelloWorld-v001.asn) is an example E2SM available in the docs directory. The Helper and
+encoding/decoding classes are in xapp-asn/e2sm. Sample code for control message E2SM:
+::
+
+ //ControlHeader
+ unsigned char header_buf[128];
+ size_t header_buf_len = 128;
+
+ //ControlMessage
+ unsigned char msg_buf[128];
+ size_t msg_buf_len = 128;
+
+ bool res;
+
+ e2sm_control_helper e2sm_cntrldata; //helper object
+ e2sm_control e2sm_cntrl; //encoding/decoding object
+
+ unsigned char msg[20] = "HelloWorld";
+
+ e2sm_cntrldata.header = 1001;
+ e2sm_cntrldata.message = msg;
+ e2sm_cntrldata.message_len = strlen((const char*)e2sm_cntrldata.message);
+
+
+ // Encode the control header
+ res = e2sm_cntrl.encode_control_header(&header_buf[0], &header_buf_len, e2sm_cntrldata);
+ if(!res)
+ std::cout << e2sm_cntrl.get_error() << std::endl;
+
+ // Encode the control message
+ res = e2sm_cntrl.encode_control_message(&msg_buf[0], &msg_buf_len, e2sm_cntrldata);
+ if(!res)
+ std::cout << e2sm_cntrl.get_error() << std::endl;
+
+
+RMR and A1 Healtcheck
+--------------------------------------------------------------------------------------------
+On receiving health check request message types (A1_HEALTHCHECK_REQ, RMR_HEALTHCHECK_REQ), HW xAPP sends RMR
+response (A1_HEALTHCHECK_RES, RMR_HEALTHCHECK_RESP) adding appropriate responses using RMR Return to Sender
+functionality.
--- /dev/null
+# This work is licensed under a Creative Commons Attribution 4.0 International License.
+# SPDX-License-Identifier: CC-BY-4.0
+# Copyright (C) 2020 AT&T Intellectual Property
+# documentation only
+
+[tox]
+minversion = 2.0
+envlist =
+ docs,
+ docs-linkcheck,
+skipsdist = true
+
+[testenv:docs]
+basepython = python3
+deps =
+ sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+
+commands =
+ sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+ echo "Generated docs available in {toxinidir}/docs/_build/html"
+whitelist_externals = echo
+
+[testenv:docs-linkcheck]
+basepython = python3
+deps = sphinx
+ sphinx-rtd-theme
+ sphinxcontrib-httpdomain
+ recommonmark
+ lfdocs-conf
+commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
Code Review / ric-app / hw.git / commitdiff
