- made fixes to hkl
- Introduced a help system - introduced a module for handling automatic updates of files during long measurements - Added a circular buffer and handling facilities to varlog - Upgraded documentation SKIPPED: psi/faverage.h psi/nxamor.tex psi/pimotor.h psi/pimotor.tex
This commit is contained in:
cvs
@@ -1,129 +1,143 @@
|
||||
\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.
|
||||
\subsubsection{Site Abstraction Layer}
|
||||
With ANSTO using SICS as well it became necessary to separate the
|
||||
general parts of SICS from the installation specific components. Each
|
||||
installation will have a separate set of drivers and, to some
|
||||
extent, instrument specific commands. Such code has to be in a
|
||||
separate library. Access to this library is through an interface which
|
||||
consists of a structure containing pointers to functions which allow
|
||||
for the creation of site specific drivers and commands. Moreover, the
|
||||
site specific library has to implement a function, getSite, which
|
||||
returns the appropriate data structure for the site for which SICS is
|
||||
being compiled. This data structure looks like this:
|
||||
|
||||
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{flushleft} \small
|
||||
\begin{minipage}{\linewidth} \label{scrap1}
|
||||
$\langle$sitedata {\footnotesize ?}$\rangle\equiv$
|
||||
\vspace{-1ex}
|
||||
\begin{list}{}{} \item
|
||||
\mbox{}\verb@@\\
|
||||
\mbox{}\verb@ typedef struct {@\\
|
||||
\mbox{}\verb@ void (*AddSiteCommands)(SicsInterp *pSics);@\\
|
||||
\mbox{}\verb@ void (*RemoveSiteCommands)(SicsInterp *pSics);@\\
|
||||
\mbox{}\verb@ pMotor (*CreateMotor)(SConnection *pCon,@\\
|
||||
\mbox{}\verb@ int argc, char *argv[]);@\\
|
||||
\mbox{}\verb@ pCounterDriver (*CreateCounterDriver)(@\\
|
||||
\mbox{}\verb@ SConnection *pCon,@\\
|
||||
\mbox{}\verb@ int argc, @\\
|
||||
\mbox{}\verb@ char *argv[]);@\\
|
||||
\mbox{}\verb@ HistDriver *(*CreateHistogramMemoryDriver)(@\\
|
||||
\mbox{}\verb@ char *name, pStringDict pOption);@\\
|
||||
\mbox{}\verb@ pVelSelDriv (*CreateVelocitySelector)(char *name, @\\
|
||||
\mbox{}\verb@ char *array, Tcl_Interp *pTcl);@\\
|
||||
\mbox{}\verb@ pCodri (*CreateControllerDriver)(SConnection *pCon,@\\
|
||||
\mbox{}\verb@ int argc,@\\
|
||||
\mbox{}\verb@ char *argv[]);@\\
|
||||
\mbox{}\verb@ pEVControl (*InstallEnvironmentController)(@\\
|
||||
\mbox{}\verb@ SicsInterp *pSics,@\\
|
||||
\mbox{}\verb@ SConnection *pCon,@\\
|
||||
\mbox{}\verb@ int argc,@\\
|
||||
\mbox{}\verb@ char *argv[]);@\\
|
||||
\mbox{}\verb@ int (*ConfigureScan)(pScanData self,@\\
|
||||
\mbox{}\verb@ char *option);@\\
|
||||
\mbox{}\verb@ void (*KillSite)(void *pData);@\\
|
||||
\mbox{}\verb@}Site, *pSite;@\\
|
||||
\mbox{}\verb@@$\diamond$
|
||||
\end{list}
|
||||
\vspace{-1ex}
|
||||
\footnotesize\addtolength{\baselineskip}{-1ex}
|
||||
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
|
||||
\item Macro referenced in scrap ?.
|
||||
\end{list}
|
||||
\end{minipage}\\[4ex]
|
||||
\end{flushleft}
|
||||
\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[AddSiteCommands] adds site specific object creation and
|
||||
instrument specific commands to the SICS interpreter, pSics.
|
||||
\item[RemoveSiteCommands] will be called to remove surplus object
|
||||
creation commands after the SICS interpreter has processed the
|
||||
initialization files. Please note, that SICS does not support the
|
||||
removal of objects at runtime in general. This is due to the fact that
|
||||
any possible object may be used by or linked to others and and it
|
||||
would be a bookeeping nightmare to keep track of all those relations.
|
||||
\item[CreateMotor] creates a motor using the arguments in argc and
|
||||
argv. It returns a pointer to the new motor structure on success or
|
||||
NULL in case of a failure. This function has to return a complete
|
||||
motor in order to allow for special configurations of the motor to
|
||||
take place in its initialization.
|
||||
\item[CreateCounterDriver] returns a driver for a new counter box
|
||||
driver if the parameters are valid or NULL if not. Driver arguments
|
||||
are in the argc, argv pair.
|
||||
\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!
|
||||
|
||||
|
||||
memory. The driver type is specified through name.
|
||||
Driver options are in pOptions.
|
||||
\item[CreateVelocitySelector] create a driver for a velocity selector.
|
||||
The parameter name is the name of the driver, array is the name of a
|
||||
Tcl array holding configuration parameters for the driver and pTcl is
|
||||
the Tcl interpreter in which array lives.
|
||||
\item[CreateControllerDriver] creates a driver for the general
|
||||
controller module within SICS. argc and argv hold the parameters,
|
||||
starting with the name of the driver to create.
|
||||
\item[InstallEnvironmentController] installs a a sample
|
||||
environment device such as a temperature controller or magnet
|
||||
controller etc. into the interpreter pSics. pCon is a connection
|
||||
object to which errors can be
|
||||
reported, argc and argv are the controller parameters starting with
|
||||
the driver name. This method does not get away with creating a driver
|
||||
but must install the command into SICS because some environment
|
||||
devices overload the standard Wrapper function with special ones. The
|
||||
newly created object is still returned for further processing. In the
|
||||
case of failure NULL is returned. Errors will have been printed to
|
||||
pCon.
|
||||
\item[ConfigureScan] allows for modules which configure the scan
|
||||
object. option is the option to xxscan configure to process, the scan
|
||||
object to configure is passed in in self. This returns 1 on success
|
||||
and 0 on failures or options which are not recognized.
|
||||
\item[KillSite] is a function to remove the site data structure when
|
||||
SICS is done with it. pData must point to the site data structure.
|
||||
KillSite's purpose is to free all memory associated with
|
||||
the site data structure. This is mostly a cleanup thing, to keep the
|
||||
fortify logs clear off inconsequential and confusing data.
|
||||
\end{description}
|
||||
|
||||
|
||||
\begin{flushleft} \small
|
||||
\begin{minipage}{\linewidth} \label{scrap2}
|
||||
\verb@"site.h"@ {\footnotesize ? }$\equiv$
|
||||
\vspace{-1ex}
|
||||
\begin{list}{}{} \item
|
||||
\mbox{}\verb@@\\
|
||||
\mbox{}\verb@/*-----------------------------------------------------------------------@\\
|
||||
\mbox{}\verb@ S i t e A b s t r a c t i o n L a y e r@\\
|
||||
\mbox{}\verb@@\\
|
||||
\mbox{}\verb@With ANSTO using SICS as well it became necessary to separate the@\\
|
||||
\mbox{}\verb@general parts of SICS from the installation specific components. Each@\\
|
||||
\mbox{}\verb@installation will have a separate set of drivers and, to some@\\
|
||||
\mbox{}\verb@extent, instrument specific commands. Such code has to be in a@\\
|
||||
\mbox{}\verb@separate library. Access to this library is through an interface which@\\
|
||||
\mbox{}\verb@consists of a structure containing pointers to functions which allow@\\
|
||||
\mbox{}\verb@for the creation of site specific drivers and commands. Moreover, the@\\
|
||||
\mbox{}\verb@site specific library has to implement a function, getSite, which@\\
|
||||
\mbox{}\verb@returns the appropriate data structure for the site for which SICS is@\\
|
||||
\mbox{}\verb@being compiled. @\\
|
||||
\mbox{}\verb@------------------------------------------------------------------------*/@\\
|
||||
\mbox{}\verb@#ifndef SICSSITE@\\
|
||||
\mbox{}\verb@#define SICSSITE@\\
|
||||
\mbox{}\verb@#include <sics.h>@\\
|
||||
\mbox{}\verb@#include <motor.h>@\\
|
||||
\mbox{}\verb@#include <countdriv.h>@\\
|
||||
\mbox{}\verb@#include <HistDriv.i>@\\
|
||||
\mbox{}\verb@#include <stringdict.h>@\\
|
||||
\mbox{}\verb@#include <velo.h>@\\
|
||||
\mbox{}\verb@#include <tcl.h>@\\
|
||||
\mbox{}\verb@#include <codri.h>@\\
|
||||
\mbox{}\verb@#include <evcontroller.h>@\\
|
||||
\mbox{}\verb@#include <scan.h>@\\
|
||||
\mbox{}\verb@@$\langle$sitedata {\footnotesize ?}$\rangle$\verb@@\\
|
||||
\mbox{}\verb@/*-------------------------------------------------------------------*/@\\
|
||||
\mbox{}\verb@pSite getSite(void);@\\
|
||||
\mbox{}\verb@#endif@\\
|
||||
\mbox{}\verb@@$\diamond$
|
||||
\end{list}
|
||||
\vspace{-2ex}
|
||||
\end{minipage}\\[4ex]
|
||||
\end{flushleft}
|
||||
|
||||
Reference in New Issue
Block a user