src/README.md

   1 #==================================================================================
   2
   3 #        Copyright (c) 2018-2019 AT&T Intellectual Property.
   4 #
   5 #   Licensed under the Apache License, Version 2.0 (the "License");
   6 #   you may not use this file except in compliance with the License.
   7 #   You may obtain a copy of the License at
   8 #
   9 #       http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 #   Unless required by applicable law or agreed to in writing, software
  12 #   distributed under the License is distributed on an "AS IS" BASIS,
  13 #   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 #   See the License for the specific language governing permissions and
  15 #   limitations under the License.
  16 #==================================================================================
  17
  18
  19 This document gives an overview of the base class of a simple xAPP class. It is used to build the adm-ctrl-xapp executable
  20
  21 Pre-requisitis : nanomsg libraries, nng libraries and ric messaging library + header must be installed and visible on standard library/include paths (via LD_LIBRARY_PATH, LIBRARY_PATH, CPATH)
  22
  23 Usage Guidelines :
  24 The base XaPP class is defined in xapp_utils.hpp.  An XaPP class object  can be instantiated in a number of ways :
  25
  26 1. XaPP(char *app_name, char *protocol, int message_size) : where
  27         - app_name points to a char array to identify this xapp (e.g "my_app_1")
  28         - protocol points to a char array to specify the protocol/port on  which this xAPP listens for messages (e.g "tcp:4561")
  29         - message_size is the maximum size of messages allowed to send ..
  30
  31         In this invocation, the number of listener threads (invoked when XaPP.Start() is called) is determined automatically based on hardware
  32
  33
  34 2. XaPP(char *app_name, char *protocol, int message_size, int num_threads) : (RECOMMENDED)    where
  35         - app_name points to a char array to identify this xapp (e.g "my_app_1")
  36         - protocol points to a char array to specify the protocol/port on  which this xAPP listens for messages (e.g "tcp:4561")
  37         - message_size is the maximum size of messages allowed to send ..
  38         - num_threads is the number of threads to invoke on which the XaPP listens for and processes messages
  39
  40
  41 3. The XaPP object can start listening to messages using the Start function, with two variants :
  42
  43         - XaPP.Start(message_handler) : in this invocation, any message received by the XaPP is passed on the message_handler function which must have the signature bool *(rmr_mbuf_t *).
  44         If the message handler wishes to respond, it must modify the message buffer in place and respond with a true value, else respond with false.
  45
  46         - XaPP.Start(message_handler, error_handler) : in this invocation, the user can specify an error_handler function, which must have the signature void *(rmr_mubf_t *) if the sending of a message (processed by message_handler) fails.
  47
  48
  49 4. The XaPP object can be used to send messages using the Send function with two variants :
  50         - XaPP.Send(int message_type, int message_length, void *message_payload)
  51         - XaPP.Send(rmr_mbuf_t * message);
  52         They return true if message was sent successfuly and false if not
  53
  54
  55 If the XaPP is started with multiple listening threads, they all share the same RMR context and invoke the same message handler/error handler user functions. Hence these are expected to be thread safe. Since all threads will listen to RMR, there is no gaurantee on which thread receives which message.
  56
  57
  58 ASN1 PDU Processing
  59 -------------------
  60
  61 1. The basic X2AP builder class (which is responsible for encoding/decoding and setting the X2AP-ELEMENTARY-PROCEDURE) is in x2ap_pdu_builder.hpp
  62 2. Any other IE  requires own code for processing. Currently ResourceStatusRequest builder is under ResourceStatuRequest_builder.hpp and ResourceStatusResponse builder under ResourceStatusResponse_builder.hpp
  63
  64
  65
  66 --- The adm-ctrl-xapp is a basic example to demonstrate RMR. The adm-ctrl-xapp just uses the basic xAPP class but with message processing done by message_processing.cc.
  67
  68 It receives ResourceStatusRequest message over RMR (message type defined in RMR_services.h), decodes it, extracts elements and responds with a ResourceStatusResponse message (message type defined in RMR_services.h). As an example for verification, it subtracts 1 from the received enb1 and enb2 ids before inserting in response ...