/*******************************************************************************

  OPENAIRINTERFACE 0/1/2/3
  Copyright(c) 1999 - 2011 EURECOM

  This program is free software; you can redistribute it and/or modify it
  under the terms and conditions of the GNU General Public License,
  version 2, as published by the Free Software Foundation.

  This program is distributed in the hope it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.

  You should have received a copy of the GNU General Public License along with
  this program; if not, write to the Free Software Foundation, Inc.,
  51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.

  The full GNU General Public License is included in this distribution in
  the file called "COPYING".

  Contact Information:
  Openair Admin <openair_admin@eurecom.fr>
  Mailing List <openair_tech@eurecom.fr>
  Forums  http://forums.eurecom.fr/openairinterface
  Eurecom, 2229, route des cretes, 06560 Valbonne Sophia Antipolis, France

*******************************************************************************/

/*! \file Readme.doxy
* \brief explain how this block is organized, and how it works 
* \author Lusheng Wang
* \date 2011
* \version 0.1 
* \note This cde is under GNU GENERAL PUBLIC LICENSE, version 2, June 1991
* \warning 
*/ 

/*! \page _readme Readme

The content of this readme is the following: 

  -# What is this block about in OpenAirInterface
  -# Organization of the folders and their dependancies
  -# Folders and files description
  -# Makefile targets and how to build
  -# How to use OCG: run a simple experimentation
  
  
\section _block 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
	

	\image html fsm_flow_chart.png "Finit State Machine of OCG" width=2cm 
  
  
\section  _organization Organization of the folders and their dependancies
    
<table border="1" cellpadding="5" cellspacing="5" width="100%">
<tr><th>Folder</th> <th> Description </th> </tr>
<tr><td width="20%">src/</td><td>contains source files</td></tr>
<tr><td width="20%">include/</td><td>contains header files</td></tr>
<tr><td width="20%">demo/</td><td>contains XML configuration files for demo</td></tr>
<tr><td width="20%">detecting_XML/</td><td>contains nothing, but OCG will detect here the XML files generated by the web portal</td></tr>
<tr><td width="20%">output_folder/</td><td>if filename of the XML file can be successfully parsed, OCG creates output folders for users and generates output files for emulations here</td></tr>
<tr><td width="20%">temp_output_folder/</td><td>if filename of the XML file cannot be successfully parsed, OCG generates an output file here</td></tr>
</table>

    
\section _folders Folders and files description

<table border="1" cellpadding="5" cellspacing="5" width="100%">
<tr><th>Folder/File</th> <th> Description </th> </tr>
<tr><td width="20%">src/OCG.c</td><td>contains the main() function with the FSM of OCG</td></tr>
<tr><td width="20%">src/OCG_get_opt.c</td><td>contains the get_opt() function</td></tr>
<tr><td width="20%">src/OCG_detect_file.c</td><td>contains the detect_file() function</td></tr>
<tr><td width="20%">src/OCG_parse_filename.c</td><td>contains the parse_filename() function</td></tr>
<tr><td width="20%">src/OCG_create_dir.c</td><td>contains the create_dir() function</td></tr>
<tr><td width="20%">src/OCG_parse_XML.c</td><td>contains the parse_XML() function</td></tr>
<tr><td width="20%">src/OCG_save_XML.c</td><td>contains the save_XML() function</td></tr>
<tr><td width="20%">src/OCG_call_emu.c</td><td>contains the call_emu() function</td></tr>
<tr><td width="20%">src/OCG_generate_report.c</td><td>contains the generate_report() function</td></tr>
<tr><td width="20%">include/OCG.h</td><td>header file of main(), contains the data structure of the basic OpenAirInterface Scenario Descriptor (OSD), etc.</td></tr>
<tr><td width="20%">include/OCG_get_opt.h</td><td>header file of get_opt()</td></tr>
<tr><td width="20%">include/OCG_detect_file.h</td><td>header file of detect_file()</td></tr>
<tr><td width="20%">include/OCG_parse_filename.h</td><td>header file of parse_filename()</td></tr>
<tr><td width="20%">include/OCG_create_dir.h</td><td>header file of create_dir()</td></tr>
<tr><td width="20%">include/OCG_parse_XML.h</td><td>header file of parse_XML(), contains the declaration of parsing position indicators</td></tr>
<tr><td width="20%">include/OCG_save_XML.h</td><td>header file of save_XML()</td></tr>
<tr><td width="20%">include/OCG_call_emu.h</td><td>header file of call_emu()</td></tr>
<tr><td width="20%">include/OCG_generate_report.h</td><td>header file of generate_report()</td></tr>
<tr><td width="20%">demo/eurecom.20110208110244.xml</td><td>contains a demo</td></tr>
</table>  
    
    
\section  _makefile 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 
		
		
\section _howto 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".
				
*/

