Bouncer/docs/user-guide.rst

   1 # ==================================================================================
   2 # Copyright (c) 2020 HCL Technologies Limited.
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 # http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 # ==================================================================================
  16
  17
  18 ============================================================================================
  19 Bouncer xAPP (C++)
  20 ============================================================================================
  21 --------------------------------------------------------------------------------------------
  22 User's Guide
  23 --------------------------------------------------------------------------------------------
  24
  25 Introduction
  26 ============================================================================================
  27
  28 The RIC platform provides set of functions that the xAPPs can use to accomplish their tasks.
  29 The Bouncer xAPP is envisioned to provide xAPP developers, examples of implementing these sets of functions.
  30
  31 Bouncer xAPP Features
  32 ============================================================================================
  33
  34 RIC Platform provides many APIs and libraries to aid the development of xAPPs. All xAPPs will have some custom
  35 processing functional logic core to the xApp and some additional non-functional platform related processing using
  36 these APIs and libraries. Bouncer xAPP attempts to show the usage of such additional platform processing using RIC platform APIs and libraries.
  37
  38
  39 The Bouncer xApp demonstrates how an xApp uses E2 interfaces and near-ric platform for the RIC Benchmarking implementation.
  40 The following paragraphs cover the various steps involved to create an Bouncer xApp instance, setting its configuration,
  41 retrieving R-NIB data, sending subscription, connecting SDL, and usage of "Bouncer SM"
  42
  43 Bouncer Creation
  44 ============================================================================================
  45
  46 The creation of the xApp instance is as simple as invoking
  47 the object's constructor with two required parameters:
  48
  49
  50 Bouncer xAPP, may choose to create following objects for obtaining desired set of functionalities provided under xapp-utils:
  51
  52 XappRmr
  53 --------------------------------------------------------------------------------------------
  54 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
  55 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 :
  56
  57 1. Setting RMR initial context: ...xapp_rmr_init(...)
  58
  59 2. Sending RMR message: ...xapp_rmr_send(xapp_rmr_header, void*)
  60
  61 3. Receiving RMR message: ...xapp_rmr_receive(msghandler,...)
  62
  63 The RMR Header can be defined using xapp_rmr_header :
  64 ::
  65
  66         typedef struct{
  67                         struct timespec ts;
  68                         int32_t message_type; //mandatory
  69                         int32_t state;
  70                         int32_t payload_length; //mandatory
  71                         unsigned char sid[RMR_MAX_SID];
  72                         unsigned char src[RMR_MAX_SRC];
  73                         unsigned char meid[RMR_MAX_MEID];
  74
  75                 }  xapp_rmr_header;
  76
  77 Except for message type and payload length, its developers prerogative to use remaining header information.
  78 The XappMsgHandler (msghandler) instance in xapp_rmr_receive function handles received messages. The handling of messages is based on
  79 the usecase catered by a xAPP. Hence, XappMsgHandler class used in Bouncer xAPP is not very comprehensive and addresses only Healthcheck Messages.
  80
  81 XappSettings
  82 -------------------------------------------------------------------------------------------
  83 An xAPP has the capability to use environment variables or xapp-descriptor information as its configuration settings
  84 creating XappSettings object, whose key functions being :
  85
  86 1. Loading Default Settings: ...loadDefaultSettings()
  87
  88 2. Loading Environment Variables: ...loadEnvVarSettings()
  89
  90 3. Loading Command Line Settings: ...loadCmdlineSettings(argc, argv)
  91
  92
  93
  94 Bouncer E2 Message Handling
  95 ============================================================================================
  96 Helper Objects
  97 --------------------------------------------------------------------------------------------
  98 Bouncer xAPP creates wrapper datastructures mirroring ASN and JSON messages. These datastructures facilitate processing of
  99 E2 messages in the xAPP. A sample  helper object for Health Check message being:
 100 ::
 101
 102         struct a1_policy_helper{
 103                 std::string operation;
 104                 std::string policy_type_id;
 105                 std::string policy_instance_id;
 106                 std::string handler_id;
 107                 std::string status;
 108         };
 109
 110 And a sample E2AP Control datastructure:
 111 ::
 112
 113         struct ric_control_helper{
 114                 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){};
 115                 long int req_id, req_seq_no, func_id, action_id,  control_ack, cause, sub_cause, control_status;
 116
 117                 unsigned char* control_msg;
 118                 size_t control_msg_size;
 119
 120                 unsigned char* control_header;
 121                 size_t control_header_size;
 122
 123                 unsigned char *call_process_id;
 124                 size_t call_process_id_size;
 125
 126         };
 127
 128 As mentioned, these datastructures are very much tied to the message specifications.
 129
 130
 131
 132 ASN Encoding/Decoding
 133 --------------------------------------------------------------------------------------------
 134 RIC platform provided ASN1C (modified) library is used for processing ASN1 messages. Bouncer xAPP, for each
 135 ASN message type, uses a class which is responsible for handling a particular message type.
 136 The class encapsulates, the APIs and datastructures used in ASN1C using helper objects. For example:
 137 ::
 138
 139         class ric_control_response{
 140                 ...
 141                 bool encode_e2ap_control_response(..., ric_control_helper &);
 142                 bool set_fields(..., ric_control_helper &);
 143                 bool get_fields(..., ric_control_helper &);
 144                 ...
 145         }
 146
 147 Note, the helper objects and message type processing classes can be found under xapp-asn subdirectories.
 148
 149 E2AP Subscription
 150 --------------------------------------------------------------------------------------------
 151 In Bouncer xAPP, we consider sunny-side scenario, in which for a E2AP subscription request sent, it is assumed,
 152 that Bouncer xAPP will be receiving E2AP subscription response. Handling advanced subscription (class SubscriptionHandler) flows is out of the
 153 scope of Bouncer xAPP. Current form of class SubscriptionHandler has following key functionalities:
 154
 155 1. manage_subscription_request(...)
 156
 157 2. manage_subscription_response(...)
 158
 159
 160 The manage_subscription_request function waits for the response for a specified time for subscription response
 161 and if no response is received within a specified time, gives a time out error message. A subscription message
 162 is created using ASN Encodong/Decoding and Helper classes. (Refer test_sub.h). Bouncer xAPP sends the subscriptions based
 163 on the gNodeB IDs received from RNIB. Please refer following function in xapp.* for RNIB transactions: set_rnib_gnblist(...)
 164
 165
 166 E2SM Subscription, Indication, Control
 167 --------------------------------------------------------------------------------------------
 168 Bouncer E2SM (e2sm-Bouncer-v001.asn) is an example E2SM available in the docs directory. The Helper and
 169 encoding/decoding classes are in xapp-asn/e2sm. Sample code for control message E2SM:
 170 ::
 171
 172         //ControlHeader
 173         unsigned char header_buf[128];
 174         size_t header_buf_len = 128;
 175
 176         //ControlMessage
 177         unsigned char msg_buf[128];
 178         size_t msg_buf_len = 128;
 179
 180         bool res;
 181
 182         e2sm_control_helper e2sm_cntrldata; //helper object
 183         e2sm_control e2sm_cntrl; //encoding/decoding object
 184
 185         unsigned char msg[20] = "Bouncer";
 186
 187         e2sm_cntrldata.header = 1001;
 188         e2sm_cntrldata.message = msg;
 189         e2sm_cntrldata.message_len = strlen((const char*)e2sm_cntrldata.message);
 190
 191
 192         // Encode the control header
 193         res = e2sm_cntrl.encode_control_header(&header_buf[0], &header_buf_len, e2sm_cntrldata);
 194         if(!res)
 195                 std::cout << e2sm_cntrl.get_error() << std::endl;
 196
 197         // Encode the control message
 198         res = e2sm_cntrl.encode_control_message(&msg_buf[0], &msg_buf_len, e2sm_cntrldata);
 199         if(!res)
 200                 std::cout << e2sm_cntrl.get_error() << std::endl;
 201
 202