\documentstyle[11pt,a4]{article} \begin{document} \begin{titlepage} { \hoffset=1truein \hsize=5.25truein \vsize=10.25truein \font\small=cmssbx10 at 14.4truept \font\medium=cmssbx10 at 17.28truept \font\large=cmssbx10 at 20.74truept \hrule height 0pt \parindent=0pt %\parskip=0pt \hskip 3.9truein \large EDOC099\par \vskip .5truein \large EUROGAM PROJECT\par \vskip 1.5truein \hrule height 2pt \vskip 20pt \large NSF DATA ACQUISITION SYSTEM\par \vskip .5truein Autofill software technical manual\par \vskip 20pt \hrule height 2pt \vskip 1truein \medium Edition 2.4\par \vskip 5pt December 1994\par \vfill \medium Nuclear Structure Software Support Group\par \vskip 5pt Liverpool University\par \vskip .5truein } \end{titlepage} \setlength{\parskip}{1ex} \setlength{\parindent}{0em} \section{Introduction} This is the full documentation for the Eurogam Autofill System software, how to install it, an overview of design and coding, and a brief guide to code maintenance.. It is assumed that the reader is familiar with VxWorks, SUN and UNIX and also has an idea on how the Autofill functions as a whole. The code is written in C under SUN.OS (UNIX) using GNU and VxWorks development tools. It was initially developed under OS/9, so some of the design choices reflect this. This document reflects version 2.4 of the software. \section{Installation} This part of the document describes how to install the Eurogam Autofill software on a new site. The code is portable on object level so recompilation is not neccessary when porting it to another SUN/MVME147/VxWorks setup. The full system will be delivered as a tar-file. Although certain values (eg path names) may vary between the sites it is recommended that all sites use the same hierarchy of files, directories and stick to the same configuration of the actual Autofill hardware. \subsection {IO configuration} The Autofill software assumes that the jumper-selectable parameters of the IO are set as follows: \subsubsection{XVME560} \begin{itemize} \item SHORT IO operation: J2B inserted, SWITCH BANK 2 - sw8 closed \item SUPERVISOR AND USER MODE ACCESS: SWITCH BANK 2 - sw7 closed \item BASE ADDRESS: 0x0400, 0x0800, ..... , 0xf800, 0xfc00 \item DIFFERENTIAL INPUT: J10A, J11, J14B inserted \item VOLTAGE RANGE: +- 10 V: J6,J9 inserted, J5,J7,J8 removed \item DIGITAL DATA FORMAT: Two's complement: J3B and J4B inserted \end{itemize} Base address setting (SWITCH bank 2): switches 1 to 6 selects the base address. Examples: \begin{verbatim} 0x1000: closed, closed, open, closed, closed, closed 0x2000: closed, closed, closed, open, closed, closed 0x4000: closed, closed, closed, closed, open, closed 0x4400: open, closed, closed, closed, open, closed \end{verbatim} \subsubsection{XVME260} \begin{itemize} \item SHORT IO operation: J2B inserted, SWITCH BANK 2 - sw8 closed \item SUPERVISOR AND USER MODE ACCESS: SWITCH BANK 2 - sw7 closed \item BASE ADDRESS: 0x0400, 0x0800, ..... , 0xf800, 0xfc00 \end{itemize} \subsubsection{XVME240} \begin{itemize} \item SHORT IO operation: J2B inserted, SWITCH BANK 2 - sw8 closed \item SUPERVISOR AND USER MODE ACCESS: SWITCH BANK 2 - sw7 closed \item BASE ADDRESS: 0x0400, 0x0800, ..... , 0xf800, 0xfc00 \end{itemize} \subsubsection{MVME712M} The jumpers on the MVME712 must be set to enable those of the serial ports you want to use. The software assumes that all of them are in use and provides login daemons for all four of them. \subsubsection{IO requirement EUROGAM phase 2} {\bf Three XVM560 cards} at addresses {\bf 0x4000}, {\bf 0x4400}, {\bf 0x4800}. {\bf Three XVM260 cards} at addresses {\bf 0x0400}, {\bf 0x0800}, {\bf 0x1000}. {\bf Two XVM240 cards} at addresses {\bf 0x2000}, {\bf 0x2400}. Note that these addresses are {\em recommended} as standard and correspond to the configuration which is delivered in the file {\bf egam2.src}. Chosing different addresses means you will have to change the configuration source file. \subsection{FILE ORGANISATION} The Autofill systems depends on several support files residing in four directories. This section will give a brief overview of the files which are required for the system to operate. \subsubsection{BOOT DIRECTORY} This is where the VxWorks related files reside, including VxWorks itself. It also contains the startup script. The name of the directory obviously depends on the chosen boot parameters (fields {\bf filename} and {\bf startup script}). In the setup for Eurogam we have chosen the boot directory to be $/eg/boot/$. This directory contains the following files (a benchmark startup.cmd is supplied on the delivery tar file): \begin{verbatim} -rw-rw-r-- 1 startup.cmd lrwxrwxrwx 1 vxWorks -> ../mv147/vxWorks lrwxrwxrwx 1 vxWorks.sym -> ../mv147/vxWorks.sym \end{verbatim} The VxWorks files are links to files appropriate for the CPU. These links must be installed by yourself onto wherever your mv147 VxWorks code resides. Note that the cpu name for the Autofill for phase 2 is {\bf egaf}, so this directory will have the name $/eg/boot/egaf$ when it is loaded from the tar file. You will also have to edit parts of {\bf startup.cmd} (server name, inet addresses etc.) but the lines concerning the Autofill path names need not be edited unless you intend to use a non-standard setup. Remember to change the {\bf setRloginHost} and {\bf setRshellHost} entries to something appropriate for your site. These site dependent parameters {\bf must} be set. See STARTUP in the code maintenance section of this document. \newpage \subsubsection{WORK DIRECTORY} This directory is {\em /eg/autoFill/work} by default. The files {\bf egam2.src} and {\bf passwd} are supplied on the delivery tar-file and reflect the default configuration name of {\em egam2}. These files MUST be present for the Autofill to work. In addition some tools to view the state of the Autofill from a remote machine are included. The files are: \begin{itemize} \item $$.src \item passwd \item lcheck \item afview \item afmon \item afdate \item netcontrol \end{itemize} The last five files are not essential to the operation of the Autofill. The following files will be created as the Autofill is running and are only mentioned here for future reference. \begin{itemize} \item $$O.bin \item $$C.bin \item $$P.bin \item $pos01.log$ \item $posxx.log$ \item $pos54.log$ \end{itemize} The {\em configuration name} is selected by setting the {\bf other} field in the {\bf boot parameters}. This will in turn determine the names of the files in the work directory. Ensure that there is a configuration file which correspond to the chosen configuration name. It must be ensured that the user who "owns" the VxWorks system, has read and write access to this directory and its files. The work directory path name may be changed through startup.cmd. The UNIX and VxWorks work paths must be physically the same. In the Eurogam phase 2 setup the path names are also identical. The UNIX work path tells {\bf cpp} where to find the Autofill work directory when it is invoked as a remote shell during configuration generation. Here is an example of a work directory: \begin{verbatim} total 496 -rwxrwxrwx 1 jh eurogam 107 May 12 1994 afdate -rwxrwxr-x 1 jh eurogam 1489 Dec 9 12:42 afmon -rwxrwxr-x 1 jh eurogam 2341 Nov 28 13:58 afview -rw-rw-r-- 1 jh eurogam 10762 Dec 14 18:39 egam2.src -rw-rw-rw- 1 VxWorks eurogam 11886 Jan 5 18:24 egam2C.bin -rw-rw-rw- 1 VxWorks eurogam 11886 Nov 29 13:35 egam2O.bin -rw-rw-rw- 1 VxWorks eurogam 11886 Jan 5 17:44 egam2P.bin -rwxrwxr-x 1 jh eurogam 1006 Dec 21 10:59 lcheck -rwxr-xr-x 1 jh eurogam 511 Nov 30 16:07 netcontrol -rw-r--r-- 1 VxWorks eurogam 125 Nov 28 13:13 passwd -rw-rw-rw- 1 VxWorks eurogam 2082 Dec 19 18:03 pos01.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:04 pos02.log -rw-rw-rw- 1 VxWorks eurogam 2075 Jan 5 18:06 pos03.log -rw-rw-rw- 1 VxWorks eurogam 2090 Nov 26 18:05 pos04.log -rw-rw-rw- 1 VxWorks eurogam 2078 Jan 5 18:09 pos05.log -rw-rw-rw- 1 VxWorks eurogam 2079 Jan 5 18:04 pos06.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:07 pos07.log -rw-rw-rw- 1 VxWorks eurogam 2073 Jan 5 18:08 pos08.log -rw-rw-rw- 1 VxWorks eurogam 2057 Jan 5 18:13 pos09.log -rw-rw-rw- 1 VxWorks eurogam 2083 Jan 5 18:07 pos10.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:05 pos11.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:07 pos12.log -rw-rw-rw- 1 VxWorks eurogam 2058 Jan 5 18:04 pos13.log -rw-rw-rw- 1 VxWorks eurogam 2086 Jan 5 18:04 pos14.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:04 pos15.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:06 pos16.log -rw-rw-rw- 1 VxWorks eurogam 2082 Dec 22 18:18 pos17.log -rw-rw-rw- 1 VxWorks eurogam 2084 Dec 19 07:38 pos18.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:07 pos19.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:05 pos20.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:06 pos21.log -rw-rw-rw- 1 VxWorks eurogam 2092 Jan 5 18:06 pos22.log -rw-rw-rw- 1 VxWorks eurogam 2072 Jan 5 18:07 pos23.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:07 pos24.log -rw-rw-rw- 1 VxWorks eurogam 2018 Jan 5 18:09 pos25.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:04 pos26.log -rw-rw-rw- 1 VxWorks eurogam 2084 Nov 26 18:05 pos27.log -rw-rw-rw- 1 VxWorks eurogam 2098 Jan 5 18:04 pos28.log -rw-rw-rw- 1 VxWorks eurogam 2079 Jan 5 18:05 pos29.log -rw-rw-rw- 1 VxWorks eurogam 2090 Jan 5 18:05 pos30.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:20 pos31.log -rw-rw-rw- 1 VxWorks eurogam 2098 Dec 16 07:45 pos32.log -rw-rw-rw- 1 VxWorks eurogam 2101 Jan 5 18:22 pos33.log -rw-rw-rw- 1 VxWorks eurogam 2134 Dec 14 08:23 pos34.log -rw-rw-rw- 1 VxWorks eurogam 2055 Jan 5 18:22 pos35.log -rw-rw-rw- 1 VxWorks eurogam 2082 Dec 21 07:11 pos36.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:20 pos37.log -rw-rw-rw- 1 VxWorks eurogam 2032 Jan 5 07:28 pos38.log -rw-rw-rw- 1 VxWorks eurogam 2073 Jan 5 18:21 pos39.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:25 pos40.log -rw-rw-rw- 1 VxWorks eurogam 2079 Jan 5 18:18 pos41.log -rw-rw-rw- 1 VxWorks eurogam 2055 Jan 5 18:21 pos42.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:21 pos43.log -rw-rw-rw- 1 VxWorks eurogam 2091 Jan 5 18:20 pos44.log -rw-rw-rw- 1 VxWorks eurogam 2076 Jan 5 18:21 pos45.log -rw-rw-rw- 1 VxWorks eurogam 2084 Jan 5 18:20 pos46.log -rw-rw-rw- 1 VxWorks eurogam 2082 Jan 5 18:19 pos47.log -rw-rw-rw- 1 VxWorks eurogam 2083 Jan 5 18:23 pos48.log -rw-rw-rw- 1 VxWorks eurogam 2111 Jan 5 07:20 pos49.log -rw-rw-rw- 1 VxWorks eurogam 2077 Jan 5 18:21 pos50.log -rw-rw-rw- 1 VxWorks eurogam 2086 Jan 5 18:20 pos51.log -rw-rw-rw- 1 VxWorks eurogam 2064 Jan 5 18:23 pos52.log -rw-rw-rw- 1 VxWorks eurogam 2066 Jan 5 18:19 pos53.log -rw-rw-rw- 1 VxWorks eurogam 2079 Jan 5 18:23 pos54.log \end{verbatim} As one can see from the filenames, the name of this configuration is {\bf egam2}. The pos??.log files hold information about the latest fill times, they support the FT command in the Autofill user program. \newpage \subsubsection{HELP DIRECTORY} This directory contains one text file for each of the user commands. The other help topics also have their corresponding text files. The default name of this directory is $/eg/autoFill/help$, but it might be set to another path through {\bf afSetHelpPath} in startup.cmd. This option will be useful if you want a choice of languages. There could e.g be a directory called $/eg/autoFill/help/french$ and another called $/eg/autoFill/help/english$. The following files must be present: \begin{verbatim} admin delay help preset threshold avoid dgen insert quit to cancel display iousg remove unavoid clear fill normal show working conn ftimes positions syntax \end{verbatim} \subsubsection{OBJECT FILE DIRECTORY} This is where all the object code for the Autofill resides. Presumably all Eurogam object code will be stored here. The default is {\em /eg/obj} but may be changed if you for instance want to run an alternative software version without having to move the files to the standard directory. This is achieved by changing {\bf objpath} in startup.cmd. The following object files must be present in the chosen directory: \begin{verbatim} afExec.o afRegs.o afUser.o afXvme560.o afLogin.o afShare.o afXvme240.o vxShare.o afMain.o afXvme260.o \end{verbatim} \newpage \subsection{CONFIGURING THE AUTOFILL} The configuration and work files for the EUROGAM AUTOFILL are stored in the directory $/eg/autoFill/work$ The {\bf name} of the configuration is selected by setting the field {\bf other} in the VxWorks boot parameters. EXAMPLE: The chosen name is {\bf egam2}. This will select the names of the system files as follows: \begin{itemize} \begin{description} \item [egam2.src] text file containing a description of the configuration \item [egam2O.bin] binary file containing a configuration and state database as described in egam2.src when Dgen is run. \item [egam2C.bin] continuous backup of the database \item [egam2P.bin] periodic backup of the database \end{description} \end{itemize} By changing the {\bf other} field you can easily switch between configurations. This will not be done normally, but might be useful if you want to run a test setup. The program {\bf afDgen} "compiles" the *.src file and leaves the resulting output in *O.bin. It can be invoked from the USER program (command DGEN) or from the VxWorks shell. When the Autofill System starts after a reboot it will look for the database in the {\em egam2C.bin} first, if that fails in {\em egam2P.bin} and finally in {\em egam2O.bin}. If none of these exist the last resort will be to generate a database from {\em egam2.src} (calling afDgen). If that fails the system will go down, and after a short wait display the login window, indicate "DOWN" and start bleeping. When you run the Autofill first time after installing it, no *.bin files will be present so the {\bf afDgen} will be run automatically. \subsubsection{Editing the configuration} The source file of the configuration is a text file which MAY contain C-language preprocessor definitions. These do not have to be included but using them will make maintenance a lot easier as you can make use of the facilities of the C-language pre-processor. The format of the configuration source is as follows: \begin{verbatim} System name (up to 32 characters) Generation date (up to 24 characters) Generation time (up to 12 characters) Refill delay Number of dewars For each dewar: name sensor address and channel number Number of detectors For each detector: information string physical position presence flag sensor reference voltage (millivolts) maximum fill time (seconds) valve closure delay (seconds) preset fill times ( format HH MM ... 99 99 ) this may be none (ie. 99 99 alone on the line) if 88 88 is given the fill times in the current configuration are preserved! address and channel number of liquid sensor input address and channel number of valve control output address and channel number of bias shutdown input manifold connection number (0-11) exhaust valve number (0-3) Number of manifolds For each manifold: address and channel number of inlet valve control address and channel number of outlet valve control address and channel number of liquid sensor input sensor reference voltage (millivolts) maximum purge time (seconds) valve closure delay (seconds) exhaust valve number (0-3) Number of exhaust valves: For each exhaust valve address and channel number of valve control \end{verbatim} \newpage \subsection{Installation checklist} \begin{itemize} \begin{enumerate} \item Configure the VME cards as prescribed in chapter 2. \item Log on to the UNIX file server as {\em root, eg OR VxWorks}. \item Load the system from the delivery tar-file. The target directories listed below need not reside at the top of your directory structure. At Liverpool, for instance {\em /eg} and {\em /eg} are just links onto {\em /usr/local}. \item Check that the following directories and files are present with correct permissions: \begin{verbatim} drwxrwsr-x /eg/boot drwxrwsr-x /eg/boot/egaf -rw-rw-r-- /eg/boot/egaf/startup.cmd drwxrwsr-x /eg/autoFill drwxr-sr-x /eg/autoFill/help -rw-r--r-- /eg/autoFill/help/admin -rw-r--r-- /eg/autoFill/help/avoid -rw-r--r-- /eg/autoFill/help/cancel -rw-r--r-- /eg/autoFill/help/clear -rw-r--r-- /eg/autoFill/help/conn -rw-r--r-- /eg/autoFill/help/delay -rw-r--r-- /eg/autoFill/help/dgen -rw-r--r-- /eg/autoFill/help/display -rw-r--r-- /eg/autoFill/help/fill -rw-r--r-- /eg/autoFill/help/ftimes -rw-r--r-- /eg/autoFill/help/help -rw-r--r-- /eg/autoFill/help/insert -rw-r--r-- /eg/autoFill/help/iousg -rw-r--r-- /eg/autoFill/help/normal -rw-r--r-- /eg/autoFill/help/positions -rw-r--r-- /eg/autoFill/help/preset -rw-r--r-- /eg/autoFill/help/quit -rw-r--r-- /eg/autoFill/help/remove -rw-r--r-- /eg/autoFill/help/show -rw-r--r-- /eg/autoFill/help/syntax -rw-r--r-- /eg/autoFill/help/threshold -rw-r--r-- /eg/autoFill/help/to -rw-r--r-- /eg/autoFill/help/unavoid -rw-r--r-- /eg/autoFill/help/working drwxrwsr-x /eg/autoFill/work -rwxr--r-x /eg/autoFill/work/egam2.src -rwxrwxr-- /eg/autoFill/work/lcheck -rwxrwxr-- /eg/autoFill/work/afmon -rwxrwxr-- /eg/autoFill/work/afview -rwxrwxr-- /eg/autoFill/work/netcontrol -rw-rw-r-- /eg/autoFill/work/passwd drwxrwsr-x /eg/obj -rwxr-xr-x /eg/obj/afExec.o -rwxr-xr-x /eg/obj/afLogin.o -rwxr-xr-x /eg/obj/afMain.o -rwxr-xr-x /eg/obj/afRegs.o -rwxr-xr-x /eg/obj/afShare.o -rwxr-xr-x /eg/obj/afUser.o -rwxr-xr-x /eg/obj/afXvme240.o -rwxr-xr-x /eg/obj/afXvme260.o -rwxr-xr-x /eg/obj/afXvme560.o -rwxr-xr-x /eg/obj/vxShare.o \end{verbatim} \item Change the ownership of the above files to the user which will "own" your VxWorks system in the Autofill crate (default {\em VxWorks}. \item Change the path name {\bf /eg/boot/egaf} to correspond to the name of your crate (only if you use a non-standard setup). \item Insert the links to vxWorks in this directory. \item Edit the {\em passwd} file to suit your own requirement. \item Edit the {\em egam2.src} file to reflect your own hardware and your connection between the array and the Autofill crate. \item Edit startup.cmd in the work directory. You will need to change the {\em server} and {\em hostAdd entries}. You MUST set the following {\bf site dependent parameters}: Objpath, rloginhost, rshell host(set to server), unixworkpath, helppath, cpppath. If you adhere to the standard file organisation you should not need to edit any of these except "rloginhost". You MUST use the function calls provided like it is done in the {\bf startup.cmd} delivered on the tar-file. \item Edit the boot parameters. \begin{verbatim} Example of a boot-line (Strasbourg): boot device : ln processor number : 0 host name : egc5 * file name : /eg/boot/egaf/vxWorks ? inet on ethernet (e) : 193.48.87.7 * host inet (h) : 193.48.87.25 * user (u) : VxWorks ? flags (f) : 0x6 target name (tn) : egaf ? startup script (s) : /eg/boot/egaf/startup.cmd ? other (o) : egam2 * \end{verbatim} The fields marked '*' will have to be changed, the {\bf egaf} entries all refer to the cpu name. The entries marked '?' will need to change if you use a non-standard setup. The name of the configuration is {\bf egam2}, the server "egc5" and the CPU name "egaf". \item Make sure the user (u) field in the boot parameters and the ownership of the Autofill related files correspond. \item Continue with the booting \end{enumerate} \end{itemize} \subsection{Booting first time} If your startup.cmd executes its calls correctly, you will get the message {\em EUROGAM AUTOFILL STARTING} on the screen, and as the configuration is generated messages describing its progress are displayed. This might take a few seconds. Then the messages from the Autofill startup sequence will appear on the screen: \begin{verbatim} LOADING tasks .. OK STARTING tasks .. OK STARTING selftest .. OK \end{verbatim} This message will stay put for a few seconds, then login will be initiated. The system is now ready for normal operation, and you can log on. For further information, refer to the Autofill users manual. \newpage \section{SYSTEM MAINTENANCE} This section deals with the day to day running of the Autofill system, like maintaining the work directory. The maintenance can be don either from the VxWorks shell or from a SUN workstation. The latter is easier, and a few hints are given below. All the examples assume that the configuration name is "egam2". \subsection{WORK DIRECTORY} This is where you find the files that are used by the Autofill in its operational phase. It contains backup, log files, configuration source and a few supplement programs to facilitate remote viewing of the system state. The database backup files are \begin{itemize} \item egam2O.bin - the original database as generated when Dgen was last run \item egam2P.bin - the periodic backup \item egam2C.bin - the "on demand" continuous backup \end{itemize} The supplement programs are: \begin{itemize} \item lcheck - views statistics of previous fills, by default the last fill. \item afview - view system, either by detector, manifold or parameter \item afmon - continuously display the main systems status \item afdate - set date/time of Autofill identical to server \item netcontrol - switch Autofill to/from standalone mode, this programs may be used by the server to disconnect/reconnect the Autofill safely when it (the server) is taken down/rebooted. \end{itemize} \subsubsection{MODIFYING THE CONFIGURATION} You might sometimes want the change the configuration of the Autofill by editing the file .src. To do this you have to perform the following: \begin{itemize} \item Edit the source file in the work directory. \item Log on to the Autofill console as a privileged user \item Do the ADMIN command, followed by DGEN \item Confirm, when asked if you want to reboot \item If this reboot fails, boot manually \item After reboot, log on and UNAVOID the detectors you want to use \end{itemize} The old database gets stored in old.bin and can be retrieved if you made a mistake. You can also do this remotely from a work station as follows: \begin{verbatim} edit the source file ersclaim egaf erswrite control -a afHalt mv egam2C.bin old.bin rm egam2?.bin erswrite control -a reboot \end{verbatim} {\bf RESTORING AN OLD DATABASE:} If you have saved an old database in say "old.bin" and want to restore it do the following (on the SUN): \begin{verbatim} ersclaim egaf erswrite control -a afHalt cp old.bin egam2C.bin erswrite control -a reboot ersfree OR from the VxWorks shell: afHalt copy "old.bin","egam2C.bin" reboot 6 \end{verbatim} \subsection{REGISTERS} Some Eurogam registers have been implemented, mostly for the purpose of allowing remote viewing of the system. These registers are currently used by the {\em afview} and {\em afmon} commands. The register "control" was added for executing single-argument commands in the crate. Example: erswrite control -a reboot (careful!!) A useful debug commands is: {\bf erswrite control -a vxinfo} This will execute the VxWorks commands {\bf i}, {\bf checkStack} and {\bf memShow} and dump the output in the file "vxinfo.d" in the work directory. To obtain information about the current state of the database, type: \begin{verbatim} erswrite control -a dbSave \end{verbatim} This stores a description of the database in the file "afdb.d" in the work directory. \newpage \subsection {SETTING THE CLOCK} The clock can be set from the VxWorks shell through the command {\bf setDate}. This command allows you to type in the data and the time. A simpler method is to use {\bf rdate}. This will pick up the time of the SUN server and set the Autofill time accordingly. {\bf rdate} is always executed when the system is booted. The VxWorks shell command {\bf printDate} displays current time and date.. NB! Remember the summertime. All you have to do is to execute an {\em rdate} when you are positive that the servers time has changed over. From a SUN: {\em afdate} From the VxWorks shell: {\em rdate} Or: {\em Reboot the crate} ! \subsection {DEBUG VARIABLES} Four debug variables have been included to enable and disable some functions of the system. They are defined as follows in the file "debug.c" in the /eg/autoFill/src/share directory. \begin{verbatim} PUBLIC int afDebug= 0; /* bit 0 - force load user program for each login */ /* bit 1 - show hex value of detector/manifold status in show command */ PUBLIC int enableBs= 1; /* Enable bias shutdown detection */ PUBLIC int enableKey= 1; /* Enable manual fill key */ PUBLIC int enableLog= 1; /* Enable message logging */ \end{verbatim} You can change those as you go by logging in to the VxWorks shell, or set them to different values in "startup.cmd". Note that disabling message logging will improve the response time for user commands. The default values are as shown in the example above. You can enable and disable the message logging from the SUN as follows: \begin{verbatim} erswrite control -a msgOn erswrite control -a msgOff \end{verbatim} \newpage \section{CODE STRUCTURE} The Autofill software takes advantage of the VxWorks multi-tasking facility by dividing the software into a number of tasks according to which function of the system they perform. This provides for modular software and hence easier maintenance. The core of the Autofill system consists of four tasks which communicate via a shared data module hereafter referred to as the {\em database}. The database contains configuration and state information for each detector and each manifold. Three of these tasks are drivers for the three types of IO-cards used by the system, while the EXEC task controls the fill cycle. The four {\bf core tasks} are: \begin{itemize} \item XVME240: driver for bias shutdown input, it reads the TTL-inputs on the XVME240 card, and writes the values into the database. One input is set aside to sense the state of the {\em Manual Fill} key on the manifold control units. One channel is configured as output and is used to inhibit the filling of the main 300 liter liquid nitrogen dewar during and after a fill. \item XVME260: driver for the relay card which controls the valves. It reads the required valve state from the database (these are provided by EXEC), and ensures that the valves are operated accordingly. \item XVME560: driver for liquid sensor input, it reads the ADC values from the XVME560 card, and stores the values in the database for subsequent use by EXEC. \item EXEC: takes care of fill operations etc. This is the "heart" of the Autofill system. It communicates with the drivers via the database. This task constantly checks the timing information in the database to determine whether detectors need filling. When a fill is due EXEC initiates it by telling the XVME260 task to open the relevant valves. Then it will continuously check ADC-values from the XVME560-task to determine whether the detector is full or not. The EXEC task always checks for {\em fill timeouts} (UNDERFULL), and {\em liquid exhaust} when valves should be closed (OVERFULL). EXEC also controls the input and output valves of the manifolds. The database is backed up to disk to enable reconstruction of the system after power failure. \end{itemize} Operator access to the Autofill is provided by \begin{itemize} \item USER: this is a program to provide the operator with means to intervene in the fill cycle, set new fill times and get a detailed view of the state of the Autofill system. This program also uses the database, some of the parameters can be changed by a privileged user. For details see the Autofill Users Manual. \item LOGIN: login daemons serving the four serial ports. These will call the USER program after a correct login identifier and password have been given. Access to the VxWorks shell and a remote SUN workstation is also provided for. \end{itemize} {\bf MAIN} starts the system and also supervises the other tasks, constantly checking for fatal error conditions. Intertask communication is done through the following mechanisms: \begin{itemize} \item SEMAPHORES: used for synchronisation. The scheduling of the {\em core tasks} is controlled by a synchronisation semaphore with a timeout in order to avoid deadlock. \item DATABASE: large buffer containing the setup and the state of the Autofill, read and written by the four {\em core} tasks and USER. Protected by the synchronisation semaphores. \item SHARED VARIABLES: In the code these are hidden by the use of macro definitions. They are defined in header files by the keyword SEXTERN. One of the shared variables {\bf Afstate} contains the overall system state. It is always displayed on all four terminals, regardless of whether the user is logged on or not. See Autofill Users Manual. \end{itemize} \subsection{STARTUP} After VxWorks is booted it runs a script {\em startup.cmd} which is in fact the application specific part of the boot sequence. Except for the choice of Autofill configuration name, all parameters relevant to the Autofill are set in this script (see section 1). \begin {itemize} \item load common Eurogam startup code \item load shared code (still application independent) \item initialises crate specific parameters. \item setSever sets the name of the current server \item setRloginHost determines which remote SUN you will connect to if you rlogin directly from the login prompt. \item setRshellHost determines which SUN should execute the remote commands like RDATE and DGEN. This should be set to server. \item setObjPath decides where the the object code should be loaded from \item rdate syncs the crate clock with the server \item afInitCrate sets a map of the XVME cards and initialises them \item afSetUnixWorkPath determines where the files created by afDgen should be stored. This as seen from the work station used by afDgen for it's cpp call. This path must physically correspond to the workpath, even though the path {\bf names} may vary depending on how the file systems are mounted. \item afSetHelpPath tells the USER program where to look for help files \item afSetCppPath determines which {\bf cpp} to use (as seen from workstation) \item change to working directory and start Autofill \end{itemize} \subsection {TIMING} The Autofill uses the on-board clock of the MVME147 to generate time references. For historical reasons (the system was migrated from OS/9) it uses a (quasi) Julian time, i.e counting seconds from an absolute reference. \newpage \subsection{DATABASE} The database consists of three sections: \begin{itemize} \item general information (name, creation date, etc.) \item state information (for each detector and manifold) \item configuration information (for each detector and manifold) \end{itemize} The {\bf state} of a detector is described by \begin{itemize} \item Status word, current (described below) \item Status word, at completion of last fill \item Most recent ADC-value \item delay time, if a fill has been delayed the total value of the delay is recorded (maximum 1 hour). \item timing information on latest fill \item time of next fill \end{itemize} In the {\bf state} of a {\bf manifold} is described by \begin{itemize} \item Status word (described below) \item Most recent ADC-value \item Number of open output valves on the manifold \item Number of overfull detectors on the manifold \item timing information on latest purge \end{itemize} The {\bf configuration} of a {\bf detector} is described by \begin{itemize} \item information string \item physical position \item sensor input connection (XVME560 card address, channel number) \item bias shutdown input connection (XVME240 card address, channel number) \item valve output connection (XVME260 card address, channel number) \item reference voltage \item maximum allowable fill time \item valve closure delay time \item table of pre-programmed fill times \item manifold number (0-11) \item exhaust valve number (0-3) \end{itemize} The {\bf configuration} of a {\bf manifold} is described by \begin{itemize} \item inlet valve connection (XVME260 card address, channel number) \item outlet valve connection (XVME260 card address, channel number) \item sensor input connection (XVME560 card address, channel number) \item reference voltage \item maximum allowable purge time \item valve closure delay time \item exhaust valve number (0-3) \end{itemize} The status word of a detector$/$manifold has these bits: \begin{itemize} \item OVERFULL, set if liquid has been detected when not expected to. This can i.e result from a valve being stuck in open position. \item UNDERFULL, set if no liquid has been detected within a set period after a fill has started. Most likely to be caused by ice blockage. \item FILL\_ABTD, set if any detector on the manifold or the manifold itself is overfull. This leads to the manifold inlet being closed, so any ongoing fills on the affected manifold will be aborted. This flag is also set when a fill has been aborted by a power failure. \item FILLING, set when a detector is filling. \item DELAYED, set in the period between initially scheduled fill time and a new fill time resulting from a DELAY command from the user. \item PURGING, set when a manifold is being purged of air \item AVOIDED, indicates detector AVOIDED, i.e no fill actions or alarms take place. \item SHUTDOWN, indicates bias shutdown from the GE detector. This is caused by the detector warming up. The AVOIDED flag is set automatically. \item LIQUID, set when liquid nitrogen has been sensed by XVME560 card \item GAS, set when gas has been sensed by XVME560 card \item MISSED\_FILL, set when a fill has been missed due to power failure \item TOG\_AVOID, set by USER program to tell EXEC to toggle the AVOIDED flag. \item MANF\_ERR, set if an error has occurred during purging of the manifold. \item REQ\_CANCEL, set by USER program to request cancelling of a fill. \item ALARM, inclusive or of MISSED\_FILL, OVERFULL, UNDERFULL and MANF\_ERR flags. \item VALVE\_IN, input valve state \item VALVE\_OUT, output valve state (manifold only) \item DIRTY, flag telling that the state has changed and backup is required. \end{itemize} \subsection{EMERGENCY BACKUP} The backup of the database to disk is done using two independent methods: \begin{itemize} \item backup on demand: whenever the state of the database changes, the relevant part is written to a file. It is therefore ensured that there at any moment exists an updated image of the database on disk. There is a delay of between the change and the actual update. This is to allow time to accumulate changes and thus cut down on the number of disk accesses. \item periodic backup: the database is written in full to a disk file at regular intervals. The current release uses the same disk for both backups. \end{itemize} \subsection{MAIN TASK} As explained under STARTUP this task is spawned from the startup script. It initialises the shared variables(defined as SEXTERN in the code). The VxWorks shell is deleted to avoid it interfering with the console. The next step is to load the code of the other tasks and start them with the desired setting of priority, options and stacksize. This includes the core tasks and the login daemons. The task names of the Autofill application all start in "af" with corresponding entry points "\_afxxxxx" in order that they be distinguishable from other tasks running on the CPU. For instance, the EXEC task will be known to VxWorks as "afExec", the XVME560 as "afXvme560" etc. After spawning the other Autofill tasks {\bf main} blocks until has received signals from the {\em core tasks} telling it that the initialisation phase has succeeded. {\bf Main} then signals the login daemons that everything is ready and the system now enters its operational phase. From this point onwards {\em main} only checks that the other tasks are "alive", it does not interfere with them. If a task is found to be suspended the {\em core tasks} are terminated, all VME-boards are reset. This calamity could either be caused by an exception like a bus error, or a bug in the software. Any open valves will be shut and the red LEDs on the XVME-cards will come on. The system state will be DOWN. \subsection{EXEC TASK} \subsubsection{INITIALISATION} This is the "control centre" the filling operations. The first operation is to load the database from disk. This will normally be a retrieval of the latest state before the system was rebooted. For first time boot, see section 1. If loading the database succeeds, the three driver tasks are signalled that the database is valid. The state of the database is checked after loading to see whether there are missed fills or any fills interrupted by a system reset. In both cases error flags will be set and the alarm turned on. Further an initial backup is made on {\em both} the backup files. The initial phase is now completed and a signal is sent to {\bf main} (to indicate "system operative"). \subsubsection{OPERATIONAL PHASE} The task must first wait for its execution timeslot. Then each detector is repeatedly checked as follows: \begin{itemize} \item check for {\bf avoid} or change in avoid setting \item if not avoided: \begin{itemize} \item if time for fill: open valve(s) \item check for cancellation request \item check for exhaust liquid; if seen then close valve(s) {\bf or} set OVERFULL flag depending on whether detector is filling or not. If no liquid is seen within a timeout, the detector state is set UNDERFULL \item check the corresponding manifold; operate valves and set error flags if necessary \end{itemize} Check if detector needs backup. \end{itemize} During an execution slots all the detectors are looped through to check for fills and error conditions. At the end of the slot, any necessary backup will be done. \subsubsection{FILL CYCLE} The fill cycle for a detector starts when EXEC determines that current time has reached the programmed fill time. Initially all alarm conditions for that detector are cleared and the fill is initiated by setting the status flag PURGING. If there are no other detectors filling on the manifold, the PURGING flag of the manifold is also set together with the flags instructing the XVME260 task to open the manifold input and output valves. If the manifold is already purging, no action is taken on it. If another detector on the same manifold is filling, and the manifold is already purged the fill will start straight away. When liquid is seen at the manifold output, the output valve closes and simultaneously all the detectors which have requested a fill, ie have their PURGING flag set, get their inlet valves opened and enter the FILLING state. The fill may be stopped by the commands "CANCEL" or "AVOID" in the user program, but would normally go on until liquid is seen at the LN2 exhaust point. The manifold inlet valve is kept open as long as there are any detectors still filling. A fill could also be terminated if liquid is not seen within a set period. In this case the UNDEFULL alarm condition is set. Another alarm condition is OVERFULL. This happens if the sensor continues to see liquid after the inlet valves ought to have closed (save a delay to account for LN2 still in the pipes etc.). This will also cause the manifold inlet valve to be closed, thus aborting the fill of detectors on the affected manifold. The manifolds "detector overfull" count will be increased. The FILL\_ABTD flag is then set for the detectors whose fills have been aborted. This is an error condition, and the detectors concerned must be filled again. The UNDERFULL and OVERFULL errors also apply to the manifold purge. If purging of a manifold times out, all the detectors concerned get their MF\_ERR flag set. This also happens if the manifold is OVERFULL. The manifold overfull error causes a fill abortion on the whole manifold. All ongoing fills (one that manifold) are stopped and the FILL\_ABTD flag set. When a mainfold undefull occurs, any filling detectors will get their UNDERFULL flag set. \newpage \subsection{XVME560 TASK} The purpose of this task is to read the liquid sensor voltages through an ADC, and store the value(s) in the database. Thus it is available for the EXEC task for it to determine whether or not liquid is seen. During initialisation the task first waits for a signal from EXEC that the database is loaded from disk. Then it makes a list of all the {\bf card addresses} found in the configuration, and associates a list of detectors with each of these cards. After this the cards are tested (for presence in crate) and initialised. There is also a simple test of the validity of the configuration(e.g. checking that no two detectors are configured to use the same ADC-channel). The result of the initial tests are logged. If any of the tests fails the task will terminate and the Autofill system will go down. In the operational phase each card is handled successively, the ADC-value for each detector on the card are read and stored in the database. All cards are scanned before the task releases its execution slot. \subsection{XVME240 TASK} This structure of this task is exactly as for XVME560, but in the main loop this task polls the digital input for bias shutdown and writes the value to the database. This task also reads the key-switches on the front of the manifold control units so the computer can take action to inhibit interference from the console terminal. One of the channels on the XVME240s is configured as an output, and drives the "dewar fill inhibit" signal. In the current setup fill of the main dewar is inhibited {\em during fills} and 1 hour after. \subsection{XVME260 TASK} This task is structured as the two other drivers. It {\em reads} values from the database and and sets the outputs on the XVME260 cards accordingly. The state of the relay driver outputs on this card reflects the state of the VALVE\_IN and VALVE\_OUT flags in the database. \subsection{LOGIN DAEMONS} \subsubsection{INITIALISATION} Unlike the other tasks, the four login daemons are not spawned directly by {\bf main}. Main starts a single {\bf login} task which opens and initialises those tty-devices which are not used by VxWorks. This task now loads the password file and spawns the four {\em login daemons} before it terminates. The login daemons are identical, re-entrant tasks. \subsubsection{OPERATION} Each daemon is initialised by setting its standard io, terminal options, port name, number etc. Then the display is initialised and execution pends reception of a signal from {\bf main} when the initialisation of the four {\em core tasks} has completed. The login prompt is then displayed and normal login operations can take place. Privileged access to the Autofill, VxWorks shell login, remote server login are only allowed on the console. The login daemons constantly checks the state of the system and maintains a display of this. If a filling error or a system crash occurs, the login daemons will send continuous bleeps to the connected screens. The main purpose of the login daemon is to provide controlled access to the {\bf user} program (see the next paragraph). {\bf User} is loaded from disk during daemon startup and an entry pointer is kept for subsequent sessions. Each daemon keeps its own copy of {\bf user} as it (user) is not re-entrant. \subsection{USER PROGRAM} The {\bf user} program is the human interface to the Autofill system. Through this an operator can manipulate valves, change fill times, avoid detectors, and observe the state of the system in various degrees of detail. {\bf User} is not an independent task, it is called as a subroutine from the login daemons. The {\em privilege level} and user name are passed as parameters. The first is significant as operations which change the database can only be done by privileged users (and only when logged on to the console). A comprehensive {\bf online help} facility is provided. Details of the commands are described in the Autofill Users Manual (EDOC098). \newpage \section{CODE MAINTENANCE} The source code is kept on the {\bf nsa} server at Liverpool under the directory {\em /eg/autoFill/src}. The documentation is kept in {\em /eg/autoFill/doc}. A copy of the source code is kept at the Daresbury machine {\bf nnsa} and at the Strasbourg machine {\bf orchidee}. The code is organised in a hierarchy of directories, where the code of each task is kept separate. There are also separate directories for the USER program, library code, include files and shared code. Each directory has its own {\em makefile} which generate the object code. For example typing {\em make} in the "exec" directory, will generate the object module "afExec.o". References to shared variables and VxWorks are resolved as the code is loaded by VxWorks. NB! BEFORE RUNNING MAKE, YOU HAVE TO SOURCE THE FILE {\bf make\_env} which can be found in {\bf /eg/autoFill/src}. This sets the necessary environment variables. Make also has targets for print, clean, tags and "proto.h" (prototyping). The library and shared module prototype files are copied over to "include". The complete system is generated by running {\em make} from {\bf /eg/autoFill/src}. \vskip 8pt {\bf Directory organisation:} \begin{itemize} \item VXSHARE, shared code, not tied to the Autofill application \item SHARE, shared code, Autofill specific \item USER, code for USER program \item MAIN, code for MAIN task \item LOGIN, code for LOGIN tasks \item EXEC, code for EXEC task \item XVME240, code for XVME240 driver task (bias shutdown sense) \item XVME260, code for XVME260 driver task (valve operation) \item XVME560, code for XVME560 driver task (liquid sensor) \item INCLUDE, common include files + makerules \item VXLIB, general purpose library for VxWorks \item AFLIB, library for Autofill application \end{itemize} The rules for the make command are kept in {\em rules.mk} and {\em generate.mk} in the {\bf include/make} directory. These contain common definitions for all the makefiles. The makefiles themselves are thus kept simple, they contain little more than a list of the files which are to be {\em compiled} and {\em linked} together. The rest is accomplished by including the "rule" files. The {\bf exec, xvme560, xvme260, xvme240, main and login} tasks each have separate directories. \vskip 8pt {\bf ADDITIONAL DIRECTORIES ARE:} \subsection {vxshare} Does not contain any Autofill specific code, but som of the routines found here are used. The code is tied to the MVME147 / VxWorks / SUN environment and includes bus error testing, drivers for the clock chip on the MVME147, the rdate and other commands to set the time, code to set site parameters like "object path"(see startup.cmd), code for use of serial ports on MVME147, a timer pool (which uses th VxWorks system clock), and some utility routines. There is also a SUN remote shell facility (a primitive rsh), which is used by {\bf rdate} and the Autofill configuration compiler {\bf afDgen}. Some Eurogam registers are included here. A copy of the proto.h file is kept in "include" as {\bf vxShare.h}. The {\bf vxshare} code is also used by the Rate Monitor and HighVoltage. \subsection {vxlib} Contains library routines for to support {\em afDgen}, vt100 display, string manipulations, user identification, the "vxinfo" command (see Registers), and keyboard input support, VxWorks shell login and some utility functions. A copy of the proto.h file is kept in "include" as {\bf vxLlib.h}. The {\bf vxlib} code is also used by the Rate Monitor and HighVoltage. \subsection {share} This is shared code available to all tasks like in "vxshare" but here tied to the Autofill. It contains the function to search the crate for XVME cards, the {\bf afDgen} configuration tool, and the code for restarting with a blank configuration. The register configuring is also found here as well as the functions to set some additional site dependent parameters. In startup.cmd these will begin with "af". The code for interfacing to the Eurogam message logger is also included here. A copy of the proto.h file is kept in "include" as {\bf afShare.h}. \subsection {aflib} Library of routines tied to the Autofill application. Contains a special {\bf fopen} which sets the SYS\_ALONE flag in {\bf Afstate} if a {\em fopen} does not return within a set period. A copy of the proto.h file is kept in "include" as {\bf afLib.h}. \subsection {user} The largest of all the modules, it contains the code for all the commands and various supporting routines like input line parsing. During debugging this module can be force-loaded on each login (set afDebug=1). \subsection {include} \begin{verbatim} gdefs.h - general purpose definitions and macros * gtime.h - timing related definitions * vxLlib.h - prototypes from the library vxlib * vxShare.h - prototypes from the shared module vxshare * afLib.h - prototypes from the library aflib afShare.h - prototypes from the shared module share afVxBind.h - definitions for VxWorks - Autofill interface afdefs.h - autofill database specific definitions afmsg.h - definition of log messages afvme.h - definitions for the XVME cards and the driver tasks afdrv.h - data structures fro XVME drivers afdbase.h - database structure for core tasks and USER afsys.h - system state definition and site dependent parameters \end{verbatim} *) These files are taken from /eg/include. This is a common Eurogam include directory. \newpage \section {APPENDICES} \subsection {Example of startup.cmd} \begin{verbatim} # ====================================================== # Startup for Eurogam Autofill # ====================================================== < /eg/boot/startup.cmd objpath="/eg/obj"; workpath="/eg/autoFill/work"; cd (objpath); ld (0,0,"message.o"); ld (0,0,"register-server.o"); ld (0,0,"vxShare.o"); # setServer(server); setRshellHost(server); setRloginHost("egc5"); setObjPath(objpath); rdate(); # ld (0,0,"afShare.o"); afInitCrate(setleds,2); afSetUnixWorkPath(workpath); afSetHelpPath("/eg/autoFill/help"); afSetCppPath("/usr/local/vw/bin/solaris/cpp"); # ld (0,0,"afMain.o"); ld (0,0,"afRegs.o"); ersInstall(0,0); # cd (workpath); afStart(); \end{verbatim} \subsection {passwd format } \begin{verbatim} username password group Group: 0 - nonprivileged Autofill access 1 - privileged Autofill access 3 - VxWorks shell access 4 - login to a remote work-station (determined by setRloginHost in startup.cmd) \end{verbatim} \newpage \subsection {DETECTOR STATUS WORD} Extract from {\bf afdefs.h} \begin{verbatim} /* D - refers to use in detector status word , M to manifold */ enum { N_OVERFULL=0, N_UNDERFULL, N_FILL_ABTD, N_MANF_ERR, N_MISSED_FILL, N_FILLING, N_DELAYED, N_PURGING, N_CLOSING, N_LIQUID, N_GAS, N_WARNING, N_AVOIDED, N_SHUTDOWN, N_OVERRIDE, N_WARN_RANGE, N_WARN_FILLT, N_WARN_CANCEL, N_WARN_NOGAS, N_VALVE_IN, N_TOG_AVOID, N_REQ_CANCEL, N_PRESENT, N_DIRTY, N_DT_OVERF , N_SCHEDFILL}; #define OVERFULL (1<