\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!