/*!
@file README
@author Lars Wetzel <larswetzel@users.sourceforge.net>
@version 0.1
@date 23.04.2010

@mainpage Dynamic Simulator plugin

@section intro Introduction
With the simulation plugins it is possible to run the openhpi daemon
locally without having hardware for it in the background.\n
Since the new simulation plugin gets its simulation data from a file instead
of having it inside the code, the data can be changed without compiling the 
plugin afterwards. This is also the reason, why it is named "dynamic simulator".
Due to the late change of the name, it could be that at some places the old name
"new simulator" is used. I try to replace it step by step and any comment is 
welcome. But it was decided not to change the name of classes or files. So please
don't wonder or be confused if the classes and files have still the old naming
scheme.\n
In combination with the \c hpigensimdata client you can generate your own
simulation data based on a running system e.g. for demonstration purposes 
- see also @ref data.\n
The plugin is written in C++ and adapts the ipmidirect plugin for simulation 
purposes. Therefore you will find many conformities between both plugins.\n
Since it was tried not to introduce new libraries, the gnu lexical scanner was
used for parsing the simulation data as it is used for the \e openhpid.conf 
file. A documentation of this scanner can be found at:
http://library.gnome.org/devel/glib/stable/glib-Lexical-Scanner.html\n
Don't hit me, but the documention was not done by the \c openhpi recommended
tool. Instead of this \c doxygen is used for this purpose. The doxygen
configuration file \c Doxyfile can be found in the main directory of the 
plugin. The documentation itself is in the file \c doc.html.tgz. A good 
description of this tool can be found at:
http://www.stack.nl/~dimitri/doxygen/index.html\n
 
@section architecture Plugin architecture
As already mentioned the new simulator plugin is adapted from the ipmidirect
plugin. Therefore many conformities can be found.\n
To make it easier to enhance the plugin in the following some call hierarchies
are given.\n
@subsection start Build up of the simulation data
The call hierarchy isn't as deep as for the ipmi plugin due to the missing 
micro controller classes (mc). But if you replace the communication layer of
the ipmidirect plugin by the following simulation file handling, the call 
hierarchie is nearly the same:\n 
 - NewSimulatorOpen       Initialize handler and call 
 - NewSimulator::IfOpen()   
                       -# open files (in NewSimulatorFile::Constructor)
                       -# call of NewSimulatorFile::Open() and
                       -# call of NewSimulatorDomain::Init()
 - NewSimulatorFile::Open()     Initialize all tokens and parse 
                                \c CONFIG_TOKEN_HANDLER
 - NewSimulatorDomain::Init()   call of NewSimulatorFile::Discover
 - NewSimulatorFile::Discover() Parsing the simulation file, beginning with 
                                \c RPT_TOKEN_HANDLER

@subsection parse Parsing the simulation file
As already mentioned the glib lexical scanner is used. All classes relevant
for parsing the simulation data file start with NewSimulatorFilexxx (xxx is the
component which should be parsed.). The rdr objects are generated by a fabric 
pattern. (To be correct for a real fabric pattern a interface class is 
missing including the switch - block for the RDR Types.)\n
The start point is 
 - NewSimulatorFile::Discover()        call of process_rpt_token()
 - NewSimulatorFile::process_rpt_token() 
                       -# parsing the \c RPT section
                       -# with the start of a \c RDR section a resource is 
                          added to the domain by calling 
                          NewSimulatorDomain::AddResource()
 - NewSimulatorFile::process_rdr_token() 
                       -# parse the \c RDR section. For each RDR entry the 
                          common rdr information is parsed by calling 
                          process_rdr_token().
                       -# In dependency of \c RDR type a NewSimulatorFilexxx 
                          object is initialized and process_token() of this 
                          object is called.
 - NewSimulatorFileRdr::process_rdr_token() 
                          parsing the common \c RDR information
 - NewSimulatorFileRdr::process_token()  
                          Method to be implemented by the child rdr classes. 
                          Return value is a pointer on a NewSimulatorRdr 
                          object. The object is insert in the Rdr cache by 
                          calling
 - NewSimulatorResource::AddRdr()

@subsection hpifunction Calling a HPI function
For each openhpi function alias \c oh_... a NewSimulator... function is defined
inside the new plugin loader block of new_sim.cpp. Inside these functions
the relevant rdr object is taken (function VerifyAndEnterXXX) and the relevant
method is called of the object.\n
In some cases some sub structures are needed (e.g. inventory areas and fields) 
In these cases first the relevant method of the \c RDR object is called 
(e.g. NewSimulatorInventory). Inside this object the correct sub object is 
identified, which is common an array entry. The implementation of such 
"sub ojects" can be found in the ..._data files 
(e.g. new_sim_inventory_data.cpp). 

@section data Simulation data
The NewSimulator plugin reads at start a simulation file which includes the 
data to be simulated. The filename can be defined inside the plugin section 
of \e openhpid.conf. The default filename is \e simulation.data. The file can be
found in the directory of the \e openhpid.conf file.\n 
The file itself is read only one time during the discovery phase. This means that
the daemon has to be restarted if changes were made and should take effect.\n
Small changes can be done easily in the file but if a whole system hardware
should be simulated it is recommended to use the \c hpigensimdata client which
is described in @ref datagen.

@subsection datagen Generating own simulation data
To generate a simulation file including the data of an own system, it is 
recommended to use the client \c hpigensimdata \c -f \c \<filename\>.\n
The content of \c \<filename\> is in ascii and can be modified using a text
editor of chose. But at changing the file you should be aware to set the 
parenthesis correctly and take the correct names of variables.\n
With the exception of config section and the token marks, all variable
names are equivalent to the variables defined inside \c SafHpi.h. The 
values of the unions and defines are put as integer or hex values inside the 
file to spare the decoding at startup of the daemon (and development efforts 
;-)).\n 
You can use this client also for dump a running system. But keep in mind that 
for reading e.g. the capability fields it is much easier to transfer also
the values properly to text, which is not done by this client.\n

@subsection restrictions
As at the ipmidirect plugin, at the moment no UTF-8 text fields are supported.\n
For announcements the timestamp is overwritten by the plugin when importing the
data.\n
**/