\documentstyle[11pt,a4wide]{article}
\hyphenation{euro-gam}
\def\EG{EuroGam}
\def\VW{VxWorks}
\def\T#1{\hbox{\tt #1}}
\def\N#1{\hbox{\rm #1}}
\def\nt#1{\hbox{\sf #1}}
\def\lb{\hbox{\it [}}
\def\rb{\hbox{\it ]}}
\def\signed#1#2{{\unskip\nobreak\hfil\penalty50
  \hskip2em\hbox{}\nobreak\hfil#1\quad#2
  \parfillskip=0pt \finalhyphendemerits=0 \par}}       % TeXBook, p106

\title{EuroGam Software Installation Manual}
\author{David Brightly}
\date{Edition 1.0\\November 1991}
\begin{document}
\begin{titlepage}
% a front or cover page for EG docs suitable for inclusion inside
% a titlepage environment in a LaTeX document
% for use with Plain TeX uncomment the \nopagenumbers and the \eject

\hoffset=.5in
\hsize=5.25in
\vsize=10.25in
%---gives left and right margins of 1.5in
\font\small=cmssbx10 scaled \magstep2
\font\medium=cmssbx10 scaled \magstep3
\font\large=cmssbx10 scaled \magstep4
%\nopagenumbers
\hrule height 0pt
\parindent=0pt
%\parskip=0pt
\hskip 3.9in
\large
EDOC095\par
\vskip .5in
\large
EUROGAM PROJECT\par
\vskip 1.5in
\hrule height 2pt
\vskip 20pt
\large
NSF DATA ACQUISITION SYSTEM\par
\vskip .5in
\baselineskip 25pt
Eurogam Software Installation\par
\vskip 20pt
\hrule height 2pt
\vskip 1in
\medium
Edition 1.0\par
\vskip 5pt
November 1991\par
\vfill
\medium
NSF Software Systems Group\par
\vskip 5pt
UK Science and Engineering Research Council\par
\vskip 5pt
Daresbury Laboratory\par
\vskip .5in
%\eject
\end{titlepage}
\maketitle

\section{Introduction}     %----------------------------
This document explains the {\em production\/} file system organisation
supporting the \EG\ data acquisition system at DL.\@
It does not cover the organisation of {\em source\/} files.
The structure outlined here assumes that \VW-based systems and discless
workstations are all supported by a single file server system.


\section{\VW\ systems}

\subsection{Booting \VW}
The organisation of \VW\ boot-time files is constrained by the desire
to keep processor NVRAM boot parameters as constant as possible while
retaining flexible control over the content of the downloaded software.
All the files needed to boot  \VW\ systems are found in a 
directory structure rooted at {\tt /vw/boot} on the server 
{\tt nnsa}.
Each target system takes its kernel image from the file
\begin{quote}
{\tt /vw/boot/{\it target\/}/vxWorks}
\end{quote}
and its startup script from the file
\begin{quote}
{\tt /vw/boot/{\it target\/}/startup.cmd}
\end{quote}
Hence the NVRAM of the target {\tt nnvd} contains the following
boot parameters:
\begin{quote}
\begin{verbatim}
host name           : nnsa
file name           : /vw/boot/nnvd/vxWorks
startup script(s)   : /vw/boot/nnvd/startup.cmd
\end{verbatim}
\end{quote}
We have adopted the practice of using common kernels for each
target architecture type.
Usually each specific target's boot file
is actually a symbolic link to a generic kernel for that target's
architecture.
Thus, in the directory {\tt /vw/boot/{\em target\/}} we have
the link
\begin{quote}
{\tt vxWorks -> ../{\em architecture}/vxWorks}
\end{quote}
For example, {\tt nnvd} being an MVME147 system we have in
{\tt /vw/boot/nnvd}
\begin{quote}
{\tt vxWorks -> ../mv147/vxWorks}
\end{quote}
The \VW\ boot machinery supports booting through a symbolic link so
in practice we can have the link
\begin{quote}
{\tt vw -> /export2/vw}
\end{quote}
in {\tt nnsa}'s root directory.

\subsection{Loading application code}
Once \VW\ is running in a target there is considerably more 
flexibility in determining what further software is downloaded
since each target can NFS-mount whatever remote directory structures
it needs.
Each target's startup script selects what role the target plays
within the \EG\ system by loading a target-specific set of object modules
and starting target-specific tasks.
We have adopted the convention of keeping \VW\ object modules in
the common directory {\tt /vw/eg-obj} and tailoring each target
by either loading target-specific data objects or by spawning tasks
with target-specifc arguments.
Thus the target {\tt nnvd} (the Resource Manager processor of a VXI 
crate) has the following fragment in its {\tt startup.cmd}:
\begin{quote}
\begin{verbatim}
hostAdd ("egmsg", "148.79.208.16");		/* currently nnsa */
nfsMount ("nnsa", "/vw", "/vw");
nfsMount ("nnsa", "/eg", "/eg");
iam "VxWorks"
nfsAuthUnixSet ("nnvd", 14052, 14003, 0);   /* id=VxWorks, grp=eurogam */
cd "/vw/eg-obj"
ld <test_lib.o
ld <message.o
ld <rmSpectrumServer.o
ld <resourceManager.o
ld <registerServer.o
ld <registers.o
ld <frontend.o
sp ers, "vxi1", "/eg/experiments/default/config/vxi1"
\end{verbatim}
\end{quote}
Startup commands common to all \VW\ systems are in the file
{\tt /vw/boot/startup.cmd} which is optionally executed
by each target's startup script.

This structure allows us to keep NVRAM boot parameters fixed
while permitting operational patches and parallel onward development
by modifying the target-specific {\tt startup.cmd} files.
For example, selected targets can be made to load object modules
from a parallel object directory, {\tt /vw/eg-obj-jan92}, say.

In general we expect only system support staff to modify files
within the {\tt /vw/boot} and {\tt /vw/eg-obj} directory structures.


\subsection{Application-specific files}
Most \VW\ applications in \EG\ need access to configuration and other
files which users can modify during the course of an experiment.
Examples include VXI crate register server configurations, apparatus files,
trigger LCA programs,  and object-code files
for event building and sorting. 
These files are found beneath the directory
\begin{quote}
{\tt /eg/experiments/{\em experiment}}
\end{quote}
where {\em experiment\/} is a label chosen by the users for their current
experiment.
\VW\ targets with applications needing to access such files must 
NFS-mount the directory
{\tt /eg/experiments} in their {\tt startup.cmd} script.
For example, a configuration file for a register server
resource called {\tt vxi1} in an experiment named
{\tt dy152} would be placed in the file 
\begin{quote}
{\tt /eg/experiments/dy152/config/vxi1}
\end{quote}
The directory
\begin{quote}
{\tt /eg/experiments/{\em default}}
\end{quote}
contains configuration files, apparatus files, etc., maintained by
the system administrator to reflect what he/she thinks is the 
organisation of crates and cards. 
This directory can thus be thought of as representing a ``default''
experiment.
Users may copy selected files to their own experiment directory and edit the
copies if they wish, but they are not expected to use the default
experiment directly.

\section{Workstation systems}

Workstations must be able to access the shared {\tt /eg/experiments} directory
on the file server system, preferably using this name. 
We do this through the automounter by installing symbolic links in each
workstation's root directory:
\begin{quote}
   {\tt eg --> /nfs/nnsa/export2/eg}
\end{quote}

\section{File server}
This has to provide the {\tt /vw} and {\tt /eg} directories 
mentioned earlier. 
In practice these directories can actually be 
on some disc other then the root file system.
On {\tt nnsa} we have a large partition mounted on {\tt /export2}
containing all the production \EG-related material, but
with symbolic links in the root directory:
\begin{quote}
{\tt vw -> /export2/vw} \\
{\tt eg -> /export2/eg}
\end{quote}
By convention, a \EG\ message logger running in the file server will be
told to log messages into files in the directory
\begin{quote}
{\tt /eg/log}
\end{quote}
The directory must be present before the message logger is started.

Executable programs can be put in directories anywhere convenient.
We recommend putting all \EG-related binaries in the directory
\begin{quote}
   {\tt /usr/local/egbin}
\end{quote}
also NSF-automounted by each discless client.


% \begin{thebibliography}{99}
% \bibitem{EGSS}{\em Eurogam Project: System Specification}, Pucknell et al,
% Edition 1.0, May 1990.
% \bibitem{Spivey}{\em The Z Notation---A Reference Manual}, J.M.Spivey, 
% ISBN~0--13--983768--X
% \bibitem{NP}{\em Network Programming}, Sun Microsystems,
% part number~ 800--1779--10, May 1988.
% \bibitem{CD}{\em Distributed Systems---Concepts and Design}, Coulouris and
% Dollimore, ISBN~0--201--18059--6
% \end{thebibliography}


\end{document}