--- /dev/null
+# ==================================================================================
+# Copyright (c) 2020 HCL Technologies Limited.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==================================================================================
+
+
+============================================================================================
+Bouncer xAPP (C++)
+============================================================================================
+--------------------------------------------------------------------------------------------
+User's Guide
+--------------------------------------------------------------------------------------------
+
+Introduction
+============================================================================================
+
+The RIC platform provides set of functions that the xAPPs can use to accomplish their tasks.
+The Bouncer xAPP is envisioned to provide xAPP developers, examples of implementing these sets of functions.
+
+Bouncer 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. Bouncer xAPP attempts to show the usage of such additional platform processing using RIC platform APIs and libraries.
+
+
+The Bouncer xApp demonstrates how an xApp uses E2 interfaces and near-ric platform for the RIC Benchmarking implementation.
+The following paragraphs cover the various steps involved to create an Bouncer xApp instance, setting its configuration,
+retrieving R-NIB data, sending subscription, connecting SDL, and usage of "Bouncer SM"
+
+Bouncer Creation
+============================================================================================
+
+The creation of the xApp instance is as simple as invoking
+the object's constructor with two required parameters:
+
+
+Bouncer 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 Bouncer 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)
+
+
+
+Bouncer E2 Message Handling
+============================================================================================
+Helper Objects
+--------------------------------------------------------------------------------------------
+Bouncer xAPP creates wrapper datastructures mirroring ASN and JSON messages. These datastructures facilitate processing of
+E2 messages in the xAPP. A sample helper object for 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. Bouncer 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 Bouncer xAPP, we consider sunny-side scenario, in which for a E2AP subscription request sent, it is assumed,
+that Bouncer xAPP will be receiving E2AP subscription response. Handling advanced subscription (class SubscriptionHandler) flows is out of the
+scope of Bouncer 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). Bouncer 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
+--------------------------------------------------------------------------------------------
+Bouncer E2SM (e2sm-Bouncer-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] = "Bouncer";
+
+ 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;
+
+
Code Review / ric-app / bouncer.git / blobdiff