sics/doc/programmer/site.tex

\chapter{Site Adaptions}\label{site}
Any new site adapting SICS will have different hardware and thus
require different drivers. Moreover additional commands may need to be
added in order to support special hardware, instrument specific
computations or status displays and local usage patterns. In order to
separate such site specific code from the SICS kernel, the site data
structure was conceived. Any new site is supposed to create a library
which provides site specific code and the site data structure which
allows SICS to locate the code. A site data structure can be retrieved
using:
\begin{verbatim}
pSite getSite(void);
\end{verbatim}
The site data structure is meant to be a singleton. It is a site's
programmers task to provide an implementation of getSite which returns
a nice site structure.

The site data structure  is a structure which holds pointers to
functions. A user has to implement suitable functions along the
signatures given and assign them to this data structure. 
\begin{verbatim}
        typedef struct {
                void (*AddSiteCommands)(SicsInterp *pSics);
                void (*RemoveSiteCommands)(SicsInterp *pSics);
                pMotor (*CreateMotor)(SConnection *pCon,
                                            int argc, char *argv[]);
                pCounterDriver (*CreateCounterDriver)(
                                                SConnection *pCon,
                                                int argc, 
                                                char *argv[]);
                HistDriver *(*CreateHistogramMemoryDriver)(
                                char *name, pStringDict pOption);
                pVelSelDriv (*CreateVelocitySelector)(char *name, 
                                char *array, Tcl_Interp *pTcl);
                pCodri      (*CreateControllerDriver)(SConnection *pCon,
                                                        int argc,
                                                        char *argv[]);
                pEVControl            (*InstallEnvironmentController)(
                                        SicsInterp *pSics,
                                        SConnection *pCon,
                                        int argc,
                                        char *argv[]);
                int                     (*ConfigureScan)(pScanData self,
                                                char *option);
                void (*KillSite)(void *pData);
}Site, *pSite;
\end{verbatim}  

The members of this data structure:
\begin{description}
\item[AddSiteCommand] adds site specific commands coded in C to the
SICS interpreter pSics. 
\item[RemoveSiteCommands] removes object creation commands after SICS
has processed the instrument initialization file. See \ref{factory}
for details on the scheme. 
\item[CreateMotor] creates a motor object. \verb+argv[0]+ contains the
motors name, \verb+argv[1]+ the identifier for the motor driver and
the rest of argv, argc holds further driver initialisation
parameters. Any errors in processing the arguments can be reported to
pCon. If CreateMotor can create a suitable motor object, a pointer to
it is returned, if not NULL must be returned. 
\item[CreateCounterDriver] creates a driver for a counter.  argc, argv
is the full array of arguments given to the MakeCounter factory
function. Of interest are: \verb+argv[1]+ the counter name,
\verb+argv[2]+, the driver identifier and the rest of the
initialization arguments. On success a pointer to
new driver is returned, on failure NULL.
\item[CreateHistogramMemoryDriver] creates a driver for a histogram
memory. The driver is identified through name, the options database is
in pOptions. Histogram memory initialization follows the following
pattern:
\begin{itemize}
\item At first the raw driver is created. This code has to initializie
defaults in the options data base.
\item Then, with calls to {\em hmname configure opt val} the options
database is populated with the histogram memories configuration
options. The options database is pOptions a dictionary of name value
pairs. 
\item In the last step, with {\bf hmname init} the options are parsed
and the driver is supposed to connect to the histogram memory. See
Configure in the histogram memory driver.  
\end{itemize} 
On success a pointer to
new driver is returned, on failure NULL.
\item[CreateVelolcitySelector] creates a driver for a velocity selector. The
driver is identified by nname, array is the name of a Tcl array in
pTcl  holding initialization parameters for name.
\item[CreateControllerDriver] generates a driver for a SICS general controller
object. \verb+argv[0]+ is the driver identifier, the rest of argc,
\verb+argv[]+ are further initialization parameters. Any errors in
parsing argc, argv can be reported to pCon. On success a pointer to
new driver is returned, on failure NULL. 
\item[InstallEnvironmentController] installs a sample environment
controller into pSics. \verb+argv[3]+ is the driver identifier,
\verb+argv[2]+ is the SICS name of the environment device command, the
rest are initialization parameters.  This function must also install
the command into pSics with AddCommand. This is because for many PSI
environment devices special interpreter wrapper functions are
provided. Any errors encountered while processing the arguments has to
be reported to pCon. On success a pointer to the environment
controller is returned, on failure NULL.  
\item[ConfigureScan] configures the SICS general scan object self according
to the value of option. Returns 1 on success and 0 on failure. SICS
general scan object is a data structure holding function pointers for
various steps in the scan. These functions can be overloaded in order
to provide for special scans. See the documentation in scan.tex,
scan.h and scan.c for more details.   
\end{description}


All the simulation drivers for the hardware are part of the SICS
kernel and need not be initialized from these functions. SICS also
handles sample environment devices built in Tcl or on the general
controller object. 


The site data structure suffers a little from inconsistencies
introduced through varying concepts for initializing SICS objects implemented 
in various stage of the development of SICS.  If you need to bypass the schemes
introduced here, consider implementing an own factory command and
install it through AddSiteCommand, RemoveSiteCommand.



Good luck!