/*
 * Licensed to the OpenAirInterface (OAI) Software Alliance under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The OpenAirInterface Software Alliance licenses this file to You under
 * the OAI Public License, Version 1.1  (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.openairinterface.org/?page_id=698
 *
 * 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.
 *-------------------------------------------------------------------------------
 * For more information about the OpenAirInterface (OAI) Software Alliance:
 *      contact@openairinterface.org
 */

/*________________________OEPNAIR/OPENAIR0/________________________

 File    : Readme.txt
 Authors : Lusheng Wang
 Company : EURECOM
 Emails  : lusheng.wang@eurecom.fr
________________________________________________________________*/


-----------------
Table of contents
-----------------

The content of this readme is the following:

  1) What is this block about in OpenAirInterface
  2) Organization of the folders and their dependancies
  3) Folders and files description
  4) Makefile targets and how to build
  5) How to use OCG: run a simple experimentation

-------------------------------------------------
1) What is this block about in OpenAirInterface ?
-------------------------------------------------

	This block is called OpenAirInterface Configuration Generation (OCG). Its major function is to parse the XML configuration file and configure an emulation.

	When the user specifies a scenario for emulation from the web portal, the web portal will generate an XML configuration file in the scenario folder of OCG. OCG automatically detects this file and initiates an emulation for it. During the emulation, OCG calls other blocks (such as MobiGen and TrafficGen) and gets feedbacks from them. After the emulation, OCG generates output files in the created folder of the emulation.

	OCG contains the following key modules:

	a) get opt		:	Get options of the OCG command, e.g. "OCG -f" and "OCG -h"
	b) detect file		:	Detect new XML configuration file in the scenario folder
	c) parse filename	:	Parse the filename to get user name and file date
	d) create dir		:	Create directory in the output directory for an emulation
	e) parse XML		:	Parse the XML configuration file
	f) save XML		:	Save the XML configuration file in created directory
	g) call emu		:	Call the emulator
	h) generate report	:	Generate a report to show the states of OCG modules

-----------------------------------------------------
2) Organization of the folders and their dependancies
-----------------------------------------------------

    Folder                 Description
    ------                 -----------
     
    - src/                 contains source files
     
    - include/             contains header files

    - demo/                contains XML configuration files for demo

    - detecting_XML/       contains nothing, but OCG will detect here the XML files generated by the web portal

    - output_folder/       if filename of the XML file can be successfully parsed, OCG creates output folders for users and generates output files for emulations here

    - temp_output_folder/  if filename of the XML file cannot be successfully parsed, OCG generates an output file here

--------------------------------
3) Folders and files description
--------------------------------

    Folder/File                               Description
    -----------                               -----------
     
    - src/OCG.c                               contains the main() function with the FSM of OCG

    - src/OCG_get_opt.c                       contains the get_opt() function

    - src/OCG_detect_file.c                   contains the detect_file() function

    - src/OCG_parse_filename.c                contains the parse_filename() function

    - src/OCG_create_dir.c                    contains the create_dir() function

    - src/OCG_parse_XML.c                     contains the parse_XML() function

    - src/OCG_save_XML.c                      contains the save_XML() function

    - src/OCG_call_emu.c                      contains the call_emu() function

    - src/OCG_generate_report.c           contains the generate_report() function
     
    - include/OCG.h                           header file of main(), contains the data structure of the basic OpenAirInterface Scenario Descriptor (OSD), etc.

    - include/OCG_get_opt.h                   header file of get_opt()

    - include/OCG_detect_file.h               header file of detect_file()

    - include/OCG_parse_filename.h            header file of parse_filename()

    - include/OCG_create_dir.h                header file of create_dir()

    - include/OCG_parse_XML.h                 header file of parse_XML(), contains the declaration of parsing position indicators

    - include/OCG_save_XML.h                  header file of save_XML()

    - include/OCG_call_emu.h                  header file of call_emu()

    - include/OCG_generate_report.h       header file of generate_report()

    - demo/eurecom.20110208110244.xml         contains a demo
    
-------------------------------------
4)  Makefile targets and how to build
-------------------------------------

	CC= gcc
	CFLAGS = -I/usr/include/libxml2
	LIB = -lxml2

	OCG:
		${CC} ${CFLAGS} ${LIB} src/OCG.c src/OCG_get_opt.c src/OCG_detect_file.c src/OCG_parse_filename.c src/OCG_create_dir.c src/OCG_parse_XML.c src/OCG_save_XML.c src/OCG_call_emu.c src/OCG_generate_OCG_report.c -o OCG

---------------------------------------------------------------
6)  How to use OCG: run a simple experimentation
---------------------------------------------------------------

	There are two methods to use the OCG for an emulation:

	a) DEMO mode	:	use command "OCG -f filename" to run a DEMO mode emulation

				The following steps are required for a DEMO mode emulation:

					i)   Put your XML configuration file into the demo/ folder;

					ii)  Change the filename as user_name.file_date.xml;

					iii) Run the emulation with the above command;

					iv)  Check debug information in the shell, which indicates you the directory where OCG generates the outputs.

				To run an existing demo XML file, step i) and ii) are not required. 

				Note that OCG automatically set the path of a demo XML file as demo/, so only filename is required in the command.

	b) USER mode	:	use command "OCG" to start OCG as a daemon

				The following steps are required for a USER mode emulation:

					i)   Run OCG as a daemon with the above command;

					iiA) Configure an emulation scenario through the web portal and press the button to generate an XML file; or

					iiB) Copy your XML file to the detecting_XML/ folder directly;

					iii) Check debug information in the shell, which indicates you the directory where OCG generates the outputs.

				For option iiB), make sure the filename is with the correct format "user_name.file_date.xml". Moreover, make sure the configuration in the XML file is correct.
				For the format of the XML configuration file, refer to "demo/eurecom.20110208110244.xml".


