%	TAS_SRC:[PSI.NOTES]HIST_MEM_NOTES.TEX	- Ident 1A05
%	====================================
%%
%%====================================================================
\documentclass[openbib,a4paper,twoside,12pt]{article}
\usepackage{array}
\usepackage{epsfig}
%
 \newcommand{\nc}{\newcommand}
 \newcommand{\rc}{\renewcommand}
%
 \nc{\myident}{1A05}
 \nc{\mydate}{26th October 2000}
%
%%====================================================================
%%
%%  +--------------------------------------------------------------+
%%  |			Paul Scherrer Institute			   |
%%  |                       SINQ Division			   |
%%  |                                                              |
%%  | This software may be used freely by non-profit organizations.|
%%  | It may be copied provided that the name of P.S.I. and of the |
%%  | author is included. Neither P.S.I. nor the author assume any |
%%  | responsibility for the use of this software outside of P.S.I.|
%%  +--------------------------------------------------------------+
%%
%%  Project  . . . . . . . . . . : SINQ
%%  Brief Document Title . . . . : Notes for the SinqHM Histogram Memory
%%  Author . . . . . . . . . . . : D.Maden
%%  Date of creation . . . . . . : 4-Nov-1997
%%
%%  Updates:
%%	    4-Nov-1997 DM.	Initial Latex Version.
%%	   15-Dec-1998 DM.	Expand.
%%	   18-Jun-1999 DM.	Bring up to date.
%%	   18-Nov-1999 DM.	Bring up to date.
%%====================================================================
%%  To process this file under Digital Unix
%%
%%	rcp maden@lnsa04:sinqhm/hist_mem_notes.tex .
%%	rcp maden@lnsa04:sinqhm/psi_logo.ps .
%%	rcp maden@lnsa04:sinqhm/sinq_logo.ps .
%%	latex hist_mem_notes
%%	dvips -o hist_mem_notes.ps hist_mem_notes
%%	vpp -device=ps800 -form=duplex hist_mem_notes.ps
%%====================================================================
%%
 \addtolength{\textheight}{40mm}
 \setlength{\textwidth}{160mm}
 \setlength{\oddsidemargin}{8mm}
 \setlength{\evensidemargin}{-10mm}
 \setlength{\topmargin}{-20mm}
%
 \setcounter{tocdepth}{2}
%
 \parskip 1.0ex plus 5pt minus 5pt      % Space between paragraphs.
%%\setlength{\parindent}{0em}
%
%%%\rc{\thepage}{\arabic{page}%
%%%			\setcounter{footnote}{0}}
 \rc{\topfraction}{0.9}
 \rc{\bottomfraction}{0.9}
 \nc{\botfigrule}{\vspace*{-3pt}%
	\hspace*{\fill}\rule{0.75\columnwidth}{0.4pt}\hspace*{\fill}%
	\vspace*{-2.6pt}}
 \nc{\topfigrule}{\vspace*{-3pt}%
	\hspace*{\fill}\rule{0.75\columnwidth}{0.4pt}\hspace*{\fill}%
	\vspace*{-2.6pt}}
%
 \nc{\PreserveBackslash}[1]{\let\temp=\\#1\let\\=\temp}
 \let\PBS=\PreserveBackslash	% shorthand
%
%		Define "\usc" to get a proper underscore!!
 \nc{\usc}{\protect\makebox[0.6em]{\protect\rule{0.5em}{0.1ex}}}
%
 \nc{\camac}{\protect\makebox[4.1em][l]{CAMAC}}
 \nc{\musr}{\protect\makebox[2.1em][l]{$\mu$SR}}
%
 \nc{\myfile}{tas{\usc}src:[psi.notes]hist{\usc}mem{\usc}notes.tex}
%
 \rc{\sf}[1]{\textsf{#1}}
 \rc{\bf}[1]{\textbf{#1}}
 \nc{\sfbf}[1]{\textsf{\textbf{#1}}}
%
 \setlength{\unitlength}{1.0mm}
%
 \title{SinqHM Histogram Memory \\ Software Support Notes}
 \author{U. Greuter, D. Maden and P. Rasmussen}
 \date{\mydate}
%
 \pagestyle{empty}
 \begin{document}
      \begin{center}\begin{picture}(160,242)(16,5)
       \put(0,0){
         \linethickness{0.80mm}
         \put(0, 0){\framebox(180,255){~}}
			% Horizontal lines - bottom to top
         \linethickness{0.40mm}
         \put(0,  12){\line(1,0){180}}
         \linethickness{0.30mm}
         \multiput(124, 17)(0,5){8}{\line(1,0){56}}
         \linethickness{0.60mm}
         \put(124, 63){\line(1,0){56}}
         \put(124, 57){\line(1,0){56}}
         \linethickness{0.40mm}
         \put(0,  76){\line(1,0){180}}
         \put(0,  98){\line(1,0){180}}
         \put(0, 154){\line(1,0){180}}
         \put(0, 184){\line(1,0){180}}
         \put(0, 206){\line(1,0){180}}
         \put(0, 218){\line(1,0){180}}
         \linethickness{0.80mm}
         \put(0, 230){\line(1,0){180}}
			% Vertical lines - left to right
         \linethickness{0.40mm}
         \put( 40, 230){\line(0,1){25}}
         \put( 60, 206){\line(0,1){12}}
	 \put( 90,   0){\line(0,1){12}}
         \put(120, 184){\line(0,1){46}}
	 \put(140, 218){\line(0,1){37}}
			%
	 \linethickness{0.40mm}
         \put(124,  12){\line(0,1){64}}
         \put(138,  12){\line(0,1){51}}
         \linethickness{0.60mm}
         \put(152,  12){\line(0,1){51}}
         \linethickness{0.40mm}
         \put(166,  12){\line(0,1){51}}
	 %
         \put(50, 232){\shortstack{%
		{\huge Paul Scherrer Institut} \\
		{W\"{u}renlingen und Villigen} \\
		{\large CH-5232 Villigen PSI} \\[1.0ex]
		{\tiny{\em (N\"{u}r f\"{u}r internen Gebrauch)}}}}
         \put(160, 250){\makebox(0,0){\Large Projekt}}
         \put(  2, 228){\makebox(0,0)[l]{\tiny Klassifizierung:}}
         \put(122, 228){\makebox(0,0)[l]{\tiny Kurzzeichen:}}
         \put(142, 228){\makebox(0,0)[l]{\tiny PSP-Nr:}}
         \put(  2, 216){\makebox(0,0)[l]{\tiny Ersatz f\"{u}r:}}
         \put( 62, 216){\makebox(0,0)[l]{\tiny Erstellungs/\"{A}nderungsdatum:}}
         \put(122, 216){\makebox(0,0)[l]{\tiny Doku-Nr:}}
	 \put(  2, 204){\makebox(0,0)[l]{\tiny Federf. Autor:}}
	 \put(  2, 201){\makebox(0,0)[l]{\tiny Co-autoren:}}
         \put(122, 204){\makebox(0,0)[l]{\tiny Unterschrift Federf. Autor:}}
         \put(  2, 182){\makebox(0,0)[l]{\tiny Titel:}}
         \put(  2, 152){\makebox(0,0)[l]{\tiny Kurztext bzw. Inhalt:}}
         \put(110, 152){\makebox(0,0)[l]{\tiny Doppelseitig:}}
		\put(128, 152){\makebox(0,0)[l]{\tiny Ja}}
		\put(135, 152){\makebox(0,0)[l]{$\bullet$}}
		\put(128, 149){\makebox(0,0)[l]{\tiny Nein}}
		\put(135, 149){\makebox(0,0)[l]{$\circ$}}
         \put(145, 152){\makebox(0,0)[l]{\tiny Seitenzahl total:}}
         \put(  2,  96){\makebox(0,0)[l]{\tiny Schlagw\"{o}rter/Suchkriterien:}}
         \put(  2,  74){\makebox(0,0)[l]{\tiny Verteiler:}}
         \put(126,  74){\makebox(0,0)[l]{\tiny Erstellereigene Doku-Nr:}}
         \put(131,  60){\makebox(0,0){PSP}} \put(145, 60){\makebox(0,0){Visum}}
         \put(159,  60){\makebox(0,0){PSP}} \put(173, 60){\makebox(0,0){Visum}}
		%
	 \put(131,54.5){\makebox(0,0){\tiny 8}}
	 \put(131,49.5){\makebox(0,0){\tiny 82}}
	 \put(131,44.5){\makebox(0,0){\tiny 83}}
	 \put(131,39.5){\makebox(0,0){\tiny 84}}
	 \put(131,34.5){\makebox(0,0){\tiny 85}}
	 \put(131,29.5){\makebox(0,0){\tiny 86}}
	 \put(131,24.5){\makebox(0,0){\tiny 89}}
		%
	 \put(159,54.5){\makebox(0,0){\tiny 811}}
	 \put(159,49.5){\makebox(0,0){\tiny 812}}
	 \put(159,44.5){\makebox(0,0){\tiny 813}}
	 \put(159,39.5){\makebox(0,0){\tiny 814}}
	 \put(159,34.5){\makebox(0,0){\tiny 815}}
	 \put(159,29.5){\makebox(0,0){\tiny 816}}
	 \put(159,24.5){\makebox(0,0){\tiny 817}}
		%
         \put(  2,  10){\makebox(0,0)[l]{\tiny Datum:}}
         \put( 47,  10){\makebox(0,0)[l]{\tiny Visum FBV:}}
         \put( 92,  10){\makebox(0,0)[l]{\tiny Datum:}}
         \put(137,  10){\makebox(0,0)[l]{\tiny Visum PL:}}
%
	 \put(2,230){\epsfig{bbllx=93,bblly=697,bburx=207,bbury=754,%
		file=psi_logo.ps,%
		height=20mm,clip=}}
%
	 \put(150,232){\epsfig{bbllx=122,bblly=700,bburx=201,bbury=740,%
		file=sinq_logo.ps,%
		height=14mm,clip=}}
%
	 \put( 25,223){\makebox(0,0)[l]{Basisunterlage}}
	 \put(130,223){\makebox(0,0){FI}}
	 \put(160,223){\makebox(0,0){89}}
	 \put( 90,210){\makebox(0,0){\mydate}}
	 \put(150,210){\makebox(0,0){891/MD36-???-}}
	 \put( 25,195){\makebox(0,0)[l]{\shortstack[l]{%
		U. Greuter	\\
		D. Maden	\\
		P. Rasmussen}}}
	 \put( 25,175){\makebox(0,0)[l]{Software Support Notes for the
					SINQ Histogram Memory, SinqHM}}
	 \put(170,152){\makebox(0,0){25}}
	 \put( 25,135){\shortstack[l]{%
		This note provides software support information \\
		for the SINQ histogramming memories}}
	 \put( 25, 86){\shortstack[l]{%
		\tiny HISTOGRAM MEMORY \\
		\tiny SOFTWARE NOTES \\
		\tiny SINQHM}}
	 \put( 25, 60){\shortstack[l]{%
		\tiny U. Greuter, WMHA/C15 \\
		\tiny D. Maden, WHGA/247 \\
		\tiny P. Rasmussen, WMHA/C28 \\
		\tiny SINQ-Sekretariat, WHGA/249}}
	 \put(150, 69){\makebox(0,0){\myident}}
       }
      \end{picture}\end{center}
 \cleardoublepage
%
 \setcounter{page}{1}
%
 \maketitle
%
 \thispagestyle{myheadings}
 \rc{\thepage}{}
 \markboth%
   {\rm \roman{page}\hspace*{-8mm}\underline{\hspace*{120mm}SinqHM
				Notes Vn \myident}}%
   {\underline{\rm SinqHM Notes Vn \myident \hspace*{21mm} File = \myfile}}
%
 \begin{abstract}
	\noindent Software support notes for the SINQ histogramming memories.
 \end{abstract}
%
 \tableofcontents
%
 \cleardoublepage
 \rc{\thepage}{\arabic{page}}
%
 \pagestyle{myheadings}
 \markboth{\hspace*{-8mm} \underline{\rm \hspace*{117mm} SinqHM
				Notes Vn \myident}}%
	 {\underline{\rm SinqHM Notes Vn \myident
				\hspace*{118mm}} \hspace*{-8mm}}
%
    \section{Introduction}
%   ======================
%
      This document provides the support programmer
      with information on setting up and using
      the \mbox{SinqHM} histogramming memories which have been developed by
      Bereichs B8 and ASQ for SINQ experiments. Details of the TCP/IP interface
      with the SinqHM software are given elsewhere \cite{Hist-Mem-Spec}.

      The histogram memory is based on a VME Power-PC single board computer
      (MVME-1603). The processor is interfaced to an instrument's detector via a
      {\em PMC\/}\footnote{PMC = PCI local bus Mezzanine Card.} piggy-back card.
      Control and read-out of the SinqHM histogramming software are via the
      processor's Ethernet interface.

      Most of the examples in these notes refer to the DMC instrument. For
      the other instruments using a histogram memory, e.g. SANS, FOCUS and
      HRPT), simply substitute the capitalised name of the instrument for
      {\em DMC\/} wherever it occurs and replace the histogram memory name,
      {\em lnse01}, accordingly.
%
    \section{Power-PC Hardware Setup}
%   =================================
%
    \label{PPC-HW-Setup}
%
      The MVME-1603\footnote{The MVME-1603 consists of an MVME1600-001 base
      board which has a plug-on processor/memory module. This is why the front
      of the VME module is labelled MVME1600-001 rather than MVME-1603!}
      Power-PC module is delivered with two factory installed EPROMs designed
      for OS9 operation. These must be removed and a single VxWorks boot EPROM
      must be installed in the upper EPROM socket (XU1). It is also
      necessary\footnote{Some of these settings may not be actually {\em
      necessary}. They are, however, known to be sufficient for the operation of
      SinqHM.} to set the on-board jumpers as follows:
       \begin{itemize}
	\item[J7:] In to enable on-board SCSI termination.
	\item[J8:] All 8 jumpers in to set the software readable header to 0x00.
	\item[J9:] Jumper between pins 1 and 2 to select ``Auto System
		Controller''.
	\item[J10:] Jumper between pins 2 and 3 to select ``Drive TXC'' on
		Serial Port 3.
	\item[J13:] Jumper between pins 2 and 3 to select ``Drive TXC'' on
		Serial Port 4.
       \end{itemize}
%
      The location of these jumpers is given in Reference~\cite{MVME-1603}. The
      PMC fibre-optic interface card must be plugged into the appropriate
      sockets of the MVME1600-001 base board.
%
    \section{Power-PC Installation}
%   ===============================
%
    \label{PPC-Install}
%
      In normal operation of SinqHM, the MVME-1603 only requires power from the
      VME crate since it acquires data via the PMC and builds the histograms in
      its internal memory. The MVME-1603 can, in this case, simply be plugged
      into any slot of a double-height VME crate.

      If, however, SinqHM will require VME access, e.g. to implement a VME bus
      shared memory network\footnote{FOCUS uses a VME bus network between its 3
      MVME-1603 
      modules.}, to generate simulated
      data via a histogram memory test generator or to generate timing signals
      via a VMIO10 I/O module, then the setup of the VME crate is important. In
      this case, it is important that the VME bus-grant (BG) and
      interrupt-acknowledge (IACK) links are correctly configured.

      The simplest way to do this is to place all modules which require to act
      as VME bus masters in adjacent slots to the left of the crate, starting
      in Slot~1. If any slots are empty, the 5 jumpers (BG1, BG2, BG3, BG4 and
      IACK) of the empty slot must be bridged. So far at SINQ, this is only
      necessary on the FOCUS instrument.

      For all instruments except FOCUS, the MVME-1603 is located in an
      arbitrary slot and no other VME master is present in the crate.

      On FOCUS, there are 3 MVME-1603 modules in the VME
      crate. Since a MVME-1603 with its PMC piggy-back requires 2 VME slots,
      these modules are located in slots 1, 3 and 5. The BG and IACK signals
      are bridged with 10 jumpers in slots 2 and 4. On the WES type VME crates
      in use at SINQ, these jumpers are located to the right of the so-called
      J1 connector on the front of the crate's backplane. The J1 connector is
      the upper of the 2 connectors present at each slot. Note that there are 2
      columns of jumpers between slots 2 and 3. The right-hand column contains
      the jumpers which are to be bridged.

      Having installed the MVME-1603 module(s) in the front of the crate, it is
      then necessary to install a corresponding {\em MVME-760-001 Transition
      Module\/} in the rear of the crate for each MVME-1603. The connection is
      to the so-called J2 (lower) connector via a ribbon cable. The transition
      module provides connectors for the COM1, COM2 and Ethernet ports of the
      MVME-1603.

      The COM1 and COM2 ports are 9-pin male D-type connectors, common on PCs.
      The Ethernet port has both an AUI (15-pin) and a 10BaseT Ethernet
      connector, either of which may be used without changing any jumpers.

      There are 2 jumpers on the transition module but their settings are
      not relevant for COM1, COM2 or Ethernet operation. The important point
      to remember is that, if the MVME-1603 is moved to a different slot,
      then the ribbon cable connection to the rear J2 connector must be moved
      as well.

      For normal operation of the SinqHM software, there is no need to connect a
      `dumb' terminal to the COM1 port. However, for set-up and debugging
      operations,
      such a connection can be extremely valuable. If possible, it is even
      better if the COM1 port can be connected to the port of a terminal server.
      One can then use a {\em telnet\/} session from a remote computer to
      emulate the `dumb' terminal. In this case, it is usually necessary to
      issue the following two {\em telnet\/} commands after the {\em telnet\/}
      connection has been established: \\[1.0ex]
%
	\hspace*{15mm}\verb#telnet> mode character# \\
	\hspace*{15mm}\verb#telnet> set binary# \\[1.0ex]
%
      In order to obtain the \verb#telnet># prompt, it is usually necessary
      to hit \verb#<Ctrl-]>#. Alternatively, this setup can be automated by
      means of entries in the {\em .telnetrc} file. See the {\em telnetrc}
      manual page for more information.

      Given such a connection, the
      VxWorks operating system may be rebooted by simply hitting
      \verb#<Ctrl-X># on the terminal keyboard. Alternatively, the
      recessed {\em reset\/} button (RST) on the MVME-1603 or the white {\em
      Manual System Reset} button on the front of the VME crate may be pressed.
%
    \section{Power-PC Software Setup}
%   =================================
%
    \label{PPC-Soft-Setup}
%
      On powering up an MVME-1603 which has been correctly configured for
      SinqHM, the following is typical of the messages which should appear on a
      dumb terminal connected to COM1:
      \vspace*{-3ex}
      \begin{verbatim}
                             VxWorks System Boot

   Copyright 1984-1996  Wind River Systems, Inc.

   CPU: Motorola MVME1600 - PowerPC 603e
   Version: 5.3
   BSP version: 1.1/3
   Creation date: Aug 23 1996, 14:30:10

   Press any key to stop auto-boot...
    0                                             <== See Note 1
   auto-booting...

   boot device     : dc
   processor num   : 0
   host name       : pss123
   file name       : /home/pss123/aco/sinqhm/wind/SinqHM/DMC/vxWorks_auto
   inet on e'net   : 129.129.62.101:ffff0000
   host inet (h)   : 129.129.40.123
   user (u)        : sinqhm
   flags (f)       : 0x8
   target name     : lnse01
   other (o)       : sp=bootUtil/sp=SinqHM/cfg=HM_DIG,400  <== See Note 2

   Attaching network interface dc0... done.
   Attaching network interface lo0... done.

   Loading... 598800
   Starting at 0x100000...

   Attaching network interface dc0... done.
   Attaching network interface lo0... done.

                    VxWorks

   Copyright 1984-1996  Wind River Systems, Inc.

               CPU: Motorola MVME1600 - PowerPC 603e
           VxWorks: 5.3
       BSP version: 1.1/3
     Creation date: Nov 11 1999 14:55:43
               WDB: Ready. \end{verbatim}
 \newpage
      \begin{verbatim}
   Spawning SinqHM_bootParamsConfig ...                  <== See Note 3

   Parsing the "other" field defined in the boot line    <== See Note 4
         Other = "sp=bootUtil/sp=SinqHM/cfg=HM_DIG,400"

   Spawning bootUtil ..                                  <== See Note 5
       TCP/IP port = 2300.
   bootUtil: Started -- program ident = "1A01".
   bootUtil: waiting for connections on Port 2300

   Spawning SinqHM_srv ..
       TCP/IP port = 2400.
       No timing signal generation requested.
   Timing signal generation via VMIO10 module disabled.
   hmRoot2400: Program  Ident = "1D01". Started on lnse01 ...
   hmRoot2400: Protocol Ident = "V03A"
   hmRoot2400: Instrument = "DMC"
   hmRoot2400: Lwl_hdr_daq_mask = 0x20000000 NRL         <== See Note 6
   hmRoot2400: Lwl_hdr_daq_soll = 0x00000000

   Configuring SinqHM_srv ...
       Histogramming mode           = SQHM__HM_DIG
       Number of bins per histogram = 400
\end{verbatim}

	\vspace*{-3.5ex}\hspace*{15mm} \vdots \vspace*{-3.5ex}
	\begin{verbatim}
   Connecting to SinqHM_srv via TCP/IP port 2400 ...
   hmRoot2400: Connected to Node 129.129.62.101, Port 1024.
   hmRoot2400: Configure ..                              <== See Note 7
       Histogramming mode is "SQHM__HM_DIG"
       Number of histograms   =     1
       First bin              =     0
       Number of bins         =   400
       Bytes per bin          =     4
       Bin compression factor =     1
       Bin-overflow action is "Ignore"
       Histogram base address = 0x007fc710
       SQHM__HM_DIG mode configured.
       .. configuration complete, hmFill2400 has been started.

   SinqHM_srv has been configured.

   Taking data in Digitised Histogramming Mode
     #-Events     #-Skip      #-TSI  Dead-Time Sync-Status
            0          0          0          0
\end{verbatim}%
      \hspace*{-5mm}\textbf{Notes:}
      \begin{enumerate}
	\item By hitting any key at this point, the boot procedure can be
		interrupted and the boot program enters interactive mode which
		allows one to inspect and modify the boot parameters as
		described below.
	\item This {\em other\/} information specifies the default configuration
		information for SinqHM. See Note 4 and Appendix~\ref{other}.
	\item The VxWorks system image, selected by the {\em file name} boot
		parameter,
		includes the SinqHM software and code for automatically starting
		up SinqHM once the boot procedure has completed. This is the
		first message indicating the start-up of the SinqHM software.
		More information on available VxWorks system images is given in
		Section~\ref{VxWorks-os}.
	\item This is where the {\em other\/} boot parameter gets parsed in
		order to configure SinqHM automatically.
	\item {\em bootUtil\/} is a TCP/IP server program which allows a remote
		client to display and modify the MVME-1603 boot configuration
		over the network rather than via 
		a `dumb' terminal connection to COM1. {\em bootUtil\/}
		is not needed for normal SinqHM operation.
	\item This {\em Lwl\/} information is instrument dependent. It indicates
		the signals which must be present at the multi-detector
		interface for an event to be accepted and histogrammed.
	\item This and the following messages are generated by SinqHM{\usc}srv
		in response to a configure request.
      \end{enumerate}
      If one interrupts the VxWorks boot procedure as described in Note 1, one
      obtains the VxWorks boot prompt. Issuing a \sfbf{p} command lists the
      settings of the boot parameters, e.g.
      \begin{verbatim}
    [VxWorks Boot]: p

   boot device   : dc
   processor num : 0
   host name     : pss123
   file name     : /home/pss123/aco/sinqhm/wind/SinqHM/DMC/vxWorks_auto
   inet on e'net : 129.129.62.101:ffff0000
   host inet (h) : 129.129.40.123
   user (u)      : sinqhm
   flags (f)     : 0x8
   target name   : lnse01
   other (o)     : sp=SinqHM/cfg=HM_DIG,400\end{verbatim}%
%
      The boot parameters may be changed by issuing a \sfbf{c} command and
      following the dialogue, e.g.
      \begin{verbatim}
    [VxWorks Boot]: c

    '.' = clear field;  '-' = go to previous field;  ^D = quit

   boot device   : dc
   processor num : 0
   host name     : pss123
   file name     : /home/pss123/aco/sinqhm/wind/SinqHM/DMC/vxWorks_auto
   inet on e'net : 129.129.62.101:ffff0000
   inet on b'pl  :
   host inet (h) : 129.129.40.123
   gateway inet  :
   user (u)      : sinqhm
   ftp password  (blank = use rsh):
   flags (f)     : 0x8
   target name   : lnse01
   startup scr   :
   other (o)     : sp=boo..400 sp=SinqHM/cfg=HM_DIG,512\end{verbatim}%
%
      In the above dialogue, all prompts were answered with a
      \verb#<Return># except for the {\em other\/} prompt. Here, the
      default histogram size was changed to 512 bins and the
      spawning of the {\em bootUtil\/} utility was removed.

      Having changed the boot parameters, the VxWorks system can be booted by
      hitting \verb#<Ctrl-X>#.
%
    \section{VxWorks Host Computer Setup}
%   =====================================
%
    \label{VxWorks-Host-Setup}
%
      The VxWorks operating system is booted from a file belonging to user {\em
      sinqhm\/} on computer {\em pss123.psi.ch}. There are 2 files on this
      computer which must be set up before the target can be booted.

%
    \subsection{The {\em /etc/hosts\/} File}
%   ========================================
%
    \label{etc-hosts}
%
      All target hosts must be entered into the file: \\[1.0ex]
%
	\hspace*{15mm} \sfbf{/etc/hosts} \\[1.0ex]
%
      on computer {\em pss123.psi.ch}. The following are some examples of
      entries in this file:\\[1.0ex]
      \texttt{%
       \hspace*{15mm}129.129.62.101~~lnse01\\
       \hspace*{15mm}129.129.62.102~~lnse02\\
       \hspace*{15mm}129.129.62.103~~lnse03\\
       \hspace*{15mm}129.129.62.104~~lnse04\\
       \hspace*{15mm}\\
       \hspace*{15mm}192.168.11.4~~~~lnse04.vme~~~~}\verb#\#\texttt{\\
       \hspace*{15mm}192.168.11.5~~~~lnse05.vme~~~~~>} ~~ See
						Section~\ref{FOCUS-setup}\\
      \texttt{%
       \hspace*{15mm}192.168.11.6~~~~lnse06.vme~~~~/}\\[1.0ex]
%
      \hspace*{-5mm}\textbf{Note:} One needs {\em root\/} privilege to edit this
      file.
%
    \subsection{The {\em .rhosts\/} File}
%   =====================================
%
      All target hosts must also be entered into the proxy definition file:
      \\[1.0ex]
%
	\hspace*{15mm} \sfbf{/home/pss123/aco/sinqhm/.rhosts} \\[1.0ex]
%
      on computer {\em pss123.psi.ch}. This is in the home directory of user
      {\em sinqhm}. The following are some examples of entries in this
      file:\\[1.0ex]
      \texttt{%
       \hspace*{15mm}lnse01~~sinqhm\\
       \hspace*{15mm}lnse02~~sinqhm\\
       \hspace*{15mm}lnse03~~sinqhm\\
       \hspace*{15mm}\\
       \hspace*{15mm}lnse04~~~~~~sinqhm~~}\verb#\#\texttt{\\
       \hspace*{15mm}lnse04.vme~~sinqhm~~~}\verb#\#\texttt{\\
       \hspace*{15mm}lnse05~~~~~~sinqhm~~~~}\verb#\# ~~ See
						Section~\ref{FOCUS-setup}\\
      \texttt{%
       \hspace*{15mm}lnse05.vme~~sinqhm~~~~/\\
       \hspace*{15mm}lnse06~~~~~~sinqhm~~~/\\
       \hspace*{15mm}lnse06.vme~~sinqhm~~/}
%
  \subsection{Special Considerations for FOCUS}
% =============================================
%
    \label{FOCUS-setup}
      The FOCUS detector consists of 383 detectors connected to 3 histogram
      memories in a single VME crate. Only one of the histogram memories is
      connected to the PSI-wide Ethernet. Communication with the other 2
      modules is via the VME bus and a so-called VME bus shared memory network.
      The module
      with the Ethernet connection acts as an Internet router from the PSI
      Internet domain, 129.129.xxx.xxx, to the Class C network, 192.168.11.xxx,
      which operates over the backplane.
      This configuration requires special setup as described in this
      section.

      The network connections for FOCUS are as shown in the figure:
      \begin{verbatim}
  +----------------+                             +----------------+
  |    pss123      |                             |    lnsa12      |
  | 129.129.40.123 |                             | 129.129.56.231 |
  +-------+--------+                             +-------+--------+
          |                                              |
          |                   Ethernet                   |
 ---------+--+-------------------------------------------+---------
             |
             |
     +-------+--------+     +----------------+     +----------------+
     | 129.129.62.104 |     |                |     |                |
     |    lnse04      |     |  lnse05.vme    |     |  lnse06.vme    |
     | 192.168.11.4   |     | 192.168.11.5   |     | 192.168.11.6   |
     +-------+--------+     +-------+--------+     +-------+--------+
             |                      |                      |
             |                      |                      |
        -----+----------------------+----------------------+---
                                         VME
      \end{verbatim}
      It is necessary to declare that {\em lnse04} is the router for {\em
      lnse05.vme} and {\em lnse06.vme} on both the VxWorks boot server, {\em
      pss123}, and on the FOCUS host computer, {\em lnsa12}. This requires {\em
      root} privilege. The details are described in the following two
      sub-sections.

  \subsubsection{Setup for FOCUS on {\em pss123}}
% ===============================================
%
      One should first check that the Internet addresses for the 3 histogram 
      memory modules are defined in the {\em /etc/hosts} file,
      as shown in Sect.~\ref{etc-hosts}. The command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{route~~add~~net~~192.168.11.0~~129.129.62.104~~1}
		\\[1.0ex]
%
      will then set up the necessary routing. In order to set the
      routing automatically whenever the computer is rebooted, it is
      necessary to add a startup file to the Unix boot
      procedure. According to the documentation, this is supposed to
      be possible via the {\em /etc/gateways} file. Unfortunately, the 
      author was unable to get this to work and therefore the
      following, somewhat more complicated, method was necessary.

      During the boot procedure, Unix proceeds through several phases
      and, in each phase, a series of scripts is executed. The routing 
      information must be added in Phase~2, after the {\em inet}
      subsystem has been started. The scripts which are executed in
      Phase~2 have names of the form:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/etc/rc2.d/Snn*}\\[1.0ex]
%
      where {\em nn} is a number in the range 01 to 99. The scripts
      are executed in numerical order. On the current {\em pss123}
      system, the {\em inet} subsystem is started up in script {\em
      S69inet}. The file:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/etc/rc2.d/S69z-inet-D.Maden}\\[1.0ex]
%
      has therefore been created containing the command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/usr/sbin/route add net 192.168.11.0
			129.129.62.104 1}\\[1.0ex]
%
      Because the file name is alphabetically after {\em S69inet},
      this script is executed after the {\em inet} subsystem has been
      started, as required.

      In order to check that the route has been defined correctly, one 
      may issue the command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{netstat -r}\\[1.0ex]
%
      One should obtain output of the form:
\begin{verbatim}
   Routing Table:
     Destination           Gateway           Flags  Ref   Use   Interface
   -------------------- -------------------- ----- ----- ------ ---------
   ...
   192.168.11.0         lnse04                UG       0     84
   ...
\end{verbatim}
%
  \subsubsection{Setup for FOCUS on {\em lnsa12}}
% ===============================================
%
      One should first check that the Internet addresses for the 3 histogram 
      memory modules are defined in the {\em /etc/hosts} file,
      as shown in Sect.~\ref{etc-hosts}. The command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{route~~add~~-net~~192.168.11.0~~129.129.62.104}
		\\[1.0ex]
%
      will then set up the necessary routing. In order to set the
      routing automatically whenever the computer is rebooted, it is
      necessary to add a startup file to the Unix boot
      procedure. According to the documentation, this is supposed to
      be possible via the {\em /etc/gateways} file. Unfortunately, the 
      author was unable to get this to work and therefore the
      following, somewhat more complicated, method was necessary.

      During the boot procedure, Unix proceeds through several phases
      and, in each phase, a series of scripts is executed. The routing 
      information must be added in Phase~3, after the {\em inet}
      subsystem has been started. The scripts which are executed in
      Phase~3 have names of the form:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/sbin/rc3.d/Snn*}\\[1.0ex]
%
      where {\em nn} is a number in the range 01 to 99. The scripts
      are executed in numerical order. On the current {\em lnsa12}
      system, the {\em inet} subsystem is started up in script {\em
      S55inetd}. The file:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/sbin/rc3.d/S55z-inetd-D.Maden}\\[1.0ex]
%
      has therefore been added to this directory containing the
      command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{/sbin/route add -net 192.168.11.0 129.129.62.104
					 }\\[1.0ex]
%
      Because the file name is alphabetically after {\em S55inetd},
      this script is executed after the {\em inet} subsystem has been
      started, as required.

      In order to check that the route has been defined correctly, one 
      may issue the command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{netstat -r}\\[1.0ex]
%
      One should obtain output of the form:
\begin{verbatim}
   Routing tables
   Destination      Gateway            Flags     Refs     Use  Interface
   Netmasks:
   ...
   192.168.11       lnse04             UGS         0      347  tu0
   ...
\end{verbatim}
%
    \section{SinqHM Software}
%   =========================
%
    \label{SinqHM-Soft}
%
      The master copy of the SinqHM software resides on the computer
      {\em lnsa15.psi.ch\/} as module {\em sinqhm} of a CVS\footnote{{\em
      CVS\/} is a code management
      system.} repository. A working copy of the current SinqHM software can
      be obtained by logging in to the LNS CVS repository
      (See~\cite{LNS-CVS}) and issuing the command:\\[1.0ex]
%
       \hspace*{15mm}\texttt{cvs export -D today sinqhm}\\[1.0ex]
%
      In order to compile and link SinqHM, it is necessary to use a computer
      on which the VxWorks cross-development software has been installed.
      This is {\em pss123.psi.ch\/} and the user account is {\em sinqhm},
      whose home directory, \sf{\$HOME}, is: \\[1.0ex]
%
	\hspace*{15mm} /home/pss123/aco/sinqhm \\[1.0ex]
%
      The build procedure involves the copying of the
      SinqHM source files from working copy to {\em pss123}, compiling and
      linking them and then merging the resultant object files into a VxWorks
      system image.

      \noindent The main components of the software are:
      \begin{itemize}
	\item the VxWorks operating system image;
	\item the SinqHM histogram memory server, {\em SinqHM{\usc}srv\/};
	\item the SinqHM auto-configure utility, {\em
		SinqHM{\usc}bootParamsConfig\/};
	\item a fibre-optic test generator server, {\em lwl{\usc}server\/};
	\item a boot-line configuration server, {\em
	SinqHM{\usc}bootUtil} and
	\item the SinqHM server-server for FOCUS, {\em FOCUS{\usc}srv}.
      \end{itemize}
      These are described in the following sub-sections.
%
    \subsection{The VxWorks Operating System}
%   =========================================
%
    \label{VxWorks-os}
%
      There is a VxWorks system image file for each instruments called:
      \\[1.0ex]
%
	\hspace*{15mm} \texttt{\$HOME/wind/SinqHM/$<$instr$>$/vxWorks{\usc}auto}
	\\[1.0ex]
%
      where \texttt{$<$instr$>$} is either \texttt{"DMC"}, \texttt{"SANS"},
      \texttt{"FOCUS"}, \texttt{"HRPT"}, \texttt{"TRICS"},
      \texttt{"POLDI"}, \texttt{"AMOR"} or
      \texttt{"Devel"}\footnote{\texttt{"Devel"}
      is a directory where test versions of SinqHM may be built.}. These
      are VxWorks system images into which the four or five 
      SinqHM utility programs
      have been loaded and code has been added to the VxWorks startup so that
      {\em SinqHM{\usc}bootParamsConfig\/} is started automatically once
      the system has been booted. Copies of the source code used to build
      the instrument specific system images are also kept in the same directory
      as the image, viz. \texttt{\$HOME/wind/SinqHM/$<$instr$>$}.

      In addition, there is a VxWorks system image file common to all
      instruments called:
      \\[1.0ex]
%
	\hspace*{15mm} \texttt{\$HOME/wind/SinqHM/vxWorks{\usc}basic}
	\\[1.0ex]
%
      This is a basic VxWorks system with no user application
      software installed. After it has been booted, one must use the VxWorks
      Tornado {\em shell\/}
      to load and start the SinqHM software as described in
      Section~\ref{manual-start}. It is intended for debugging the
      SinqHM software.

      The system images were originally created interactively
      using the WindCFG Tornado
      utility (see Chapter 8 of Ref.~\cite{Tornado-Users} on {\em Target
      Configuration\/}). The current procedure, however, is to use the
      {\em bld\/} script described in Appendix~\ref{bld-script}. The remainder
      of this section describes these two procedures. Beware that there
      are some possible problems with the {\em bld\/} script as noted
      in the warnings in the text.

      The WindCFG configuration names for the system images are
      \texttt{SinqHM} for the basic system and
      \texttt{SinqHM{\usc}spawn{\usc}$<$instr$>$} for each of the
      instruments. All
      have the same \mbox{VxWorks} options included, viz:
      \begin{center}\begin{tabular}%
		{@{}l@{\hspace{1mm}}l@{\hspace{1mm}}l@{\hspace{1mm}}l@{}}
      BOOTP			& NETWORK		& SIGNALS		& WDB{\usc}CTXT	\\
      CONSTANT{\usc}RDY{\usc}Q	& NET{\usc}INIT		& SM{\usc}NET		& WDB{\usc}DIRECT{\usc}CALL \\
      ENV{\usc}VARS		& NET{\usc}SHOW		& STDIO			& WDB{\usc}EVENTS \\
      EXC{\usc}HANDLING		& PIPES			& TASK{\usc}HOOKS	& WDB{\usc}EXC{\usc}NOTIFY \\
      EXC{\usc}TASK		& POSIX{\usc}SIGNALS	& TASK{\usc}VARS	& WDB{\usc}EXIT{\usc}NOTIFY \\
      FLOATING{\usc}POINT	& POSIX{\usc}TIMERS	& TFTP{\usc}CLIENT	& WDB{\usc}FUNC{\usc}CALL \\
      FORMATTED{\usc}IO		& PROXY{\usc}CLIENT	& TIMEX			& WDB{\usc}GOPHER \\
      FTP{\usc}SERVER		& RAMDRV		& TTY{\usc}DEV		& WDB{\usc}MEM \\
      IO{\usc}SYSTEM		& SELECT		& WATCHDOGS		& WDB{\usc}REG \\
      LOGGING			& SEM{\usc}BINARY	& WDB			& WDB{\usc}TTY{\usc}TEST \\
      MEM{\usc}MGR{\usc}FULL	& SEM{\usc}COUNTING	& WDB{\usc}BANNER	& WDB{\usc}VIO \\
      MSG{\usc}Q		& SEM{\usc}MUTEX	& WDB{\usc}BP \\
      \end{tabular}\end{center}
%
      In addition, the \texttt{SinqHM{\usc}spawn{\usc}$<$instr$>$}
      configurations have the first four\footnote{The {\em
      FOCUS{\usc}srv} module has not been included in the VxWorks
      systems by means of WindCFG.} SinqHM
      modules included and the {\em edit\/} button is used to define symbol
      \texttt{SINQHM{\usc}SPAWN} in the {\em config.h\/} file. This causes the
      auto-configure module, {\em SinqHM{\usc}bootParamsConfig}, to get
      spawned automatically at the end of the boot
      procedure and this, in its turn, uses the {\em other\/}
      field from the boot
      parameters to spawn and configure the other modules. The full build
      procedure is described in the comments in the file: \\[1.0ex]
%
	\hspace*{15mm}\$HOME/wind/ppc/target/config/all/usrConfig.c
		\\[1.0ex]
%
      For completeness, these comments are reproduced here:

      \begin{verbatim}
    /*
    **  This file should be copied to the VxWorks directory tree, e.g:
    **    pss123> set src = "lnslib@lnsa15:sinqhm/"
    **    pss123> rcp -p "${src}usrConfig.c" \
    **                $HOME/wind/ppc/target/config/all/usrConfig.c
    **    pss123> rcp -p "${src}bld" $HOME/wind/SinqHM/bld
    **
    **  The system images are:
    **
    **       $HOME/wind/SinqHM/vxWorks_basic
    **       $HOME/wind/SinqHM/<instr>/vxWorks_auto
    **
    ** Using the Tornado tools:
    ** =======================
    **  To build the system image WITHOUT the SinqHM modules:
    **      a) Start WindCFG with no target selected.      <== see Note 1
    **      b) Select the "mv1603" BSP.
    **      c) Select configuration "SinqHM"
    **      d) Start up the editor and ensure that "SINQHM_SPAWN"
    **          is either not defined or is defined to be 0.
    **      e) Select the Build option.
    **      f) Copy file vxWorks to $HOME/wind/SinqHM/vxWorks_basic.
    **
    **  To build the system image WITH the SinqHM modules:
    **      a) Start WindCFG with no target selected.      <== see Note 1
    **      b) Select the "mv1603" BSP.
    **      c) Select configuration "SinqHM_spawn_<instr>".
    **      d) Start up the editor and ensure that "SINQHM_SPAWN"
    **          is defined to be non-zero, e.g:
    **              #define  SINQHM_SPAWN  1
    **      e) Select the Build option.
    **      f) Copy file $HOME/wind/ppc/target/config/mv1603/vxWorks 
    **                to $HOME/wind/SinqHM/<instr>/vxWorks_auto.
    **
    ** Using the bld script:
    ** ====================
    **  To build system images using the bld script:
    **
    **    a) without the SinqHM modules:
    **                     pss123> $HOME/wind/SinqHM/bld basic
    **    b) with    the SinqHM modules:
    **                     pss123> bld <instr> all
    **
    **  Warnings:
    **    The bld script will only work if SINQHM_SPAWN is NOT
    **    defined in $HOME/wind/ppc/target/config/mv1603/config.h
    **
    **    When using the bld script, be sure that the file
    **    $HOME/wind/ppc/target/config/mv1603/configdb.h
    **    is set to select the correct VxWorks options. It is
    **    easiest to use the Tornado WindCFG tool to do this.
    */ \end{verbatim}%
      \hspace*{-5mm}\textbf{Note:}
      \begin{enumerate}
	\item This step is important because the SinqHM boot files do not
		reside in the usual VxWorks directory tree. If the VxWorks
		Tornado Launcher has a target processor selected when
		WindCFG is started, WindCFG assumes that the directory
		tree in which the target's boot file is located is the one
		which it should use. As a result, it is
		unable to find the BSPs\footnote{{\em BSP\/} = Board
		Support Package.} which it needs for building system images.
		If, on the other hand, the Launcher has {\em no\/} target
		processor selected when WindCFG is started, WindCFG will use
		the \texttt{WIND{\usc}BASE} environment variable to locate
		the directory tree and it will be able to find the BSPs.
		Unfortunately, there is no {\em Target-deselect\/} option
		in the Launcher. It may therefore be necessary to quit the
		Launcher and to restart it in order to be able to use WindCFG.
      \end{enumerate}
%
    \subsection{The SinqHM Histogram Memory Server}
%   ===============================================
%
      The SinqHM histogram memory server, {\em SinqHM{\usc}srv}, is the
      central item
      of the histogramming memory system in the MVME-1603. It normally runs
      under the name {\em hmRoot2400}. Once configured (see
      Sect.~\ref{auto-config}), it spawns a background task, {\em hmFill2400},
      which reads data from the multi-detector interface via the PMC card and
      fills
      histograms appropriately. It then listens for TCP/IP connections from
      clients and responds to any requests received. \\[1.0ex]
%
      {\em SinqHM{\usc}srv\/} is built from the following source files: \\[1.0ex]
%
      \hspace*{\fill} \begin{tabular}{ll}
      SinqHM{\usc}srv{\usc}main.c	& - the main program of
						{\em SinqHM{\usc}srv}.\\
      SinqHM{\usc}srv{\usc}filler.c	& - the histogram filler.\\
      SinqHM{\usc}srv{\usc}server.c	& - the server program.\\
      SinqHM{\usc}srv{\usc}routines.c	& - miscellaneous routines.\\
      SinqHM{\usc}def.h			& - header file defining symbols and
						structures.\\
      SinqHM{\usc}gbl.h			& - header file defining global
						variables.\\
      vmio10{\usc}def.h			& - header file defining symbols for
						the VMIO10 module.
      \end{tabular} \hspace*{\fill} \\[1.0ex]
%
      These files are compiled and linked using the script {\em bld} via
      the command: \\[1.0ex]
%
	\hspace*{15mm}\texttt{\$HOME/wind/SinqHM/bld $<$instr$>$
		SinqHM{\usc}srv} \\[1.0ex]
%
      which generates the object module\footnote{Note that there are 2 
      directories in each instrument's base directory called
      \texttt{OLD} and \texttt{NEW}. It is assumed that the released 
      version of SinqHM for an instrument resides in its base
      directory. The {\em bld} script uses the \texttt{NEW} directory
      as its working directory. When the new version is to be
      released, the files in the base directory should be moved to
      the \texttt{OLD} directory and then the files from \texttt{NEW}
      can then be copied to the base directory.}\\[1.0ex]
%
	\hspace*{15mm}\texttt{\$HOME/wind/SinqHM/$<$instr$>$%
		/NEW/SinqHM{\usc}srv.o} \\[1.0ex]
%
      This can be loaded into VxWorks and started.
      \noindent When the {\em SinqHM{\usc}srv\/} process is created via the
      VxWorks {\em taskSpawn\/} function, up to 10 arguments, \verb#<arg1>#
      \ldots \verb#<arg10>#, may be specified. The following are used by {\em
      SinqHM{\usc}srv\/}: \\[1.0ex]
      \hspace*{\fill}\begin{tabular}{llp{91mm}}
	\texttt{$<$arg1$>$}  & \texttt{$<$port$>$} & The TCP/IP port number to
					be used for listening for connections
					from clients. Default = 2400. \\
	\texttt{$<$arg2$>$}  & \texttt{$<$use-level-gen$>$} & If non-zero, the
					SinqHM {\em Filler\/} process will
					use a VMIO10 module for
					generating signals so that its speed
					may be measured on an
					oscilloscope. Default = 0. \\
	\texttt{$<$arg3$>$}  & \texttt{$<$base-addr$>$} & The VME base address
					of the VMIO10 module. Default = 0x1900.
					\\
	\texttt{$<$arg10$>$} & \texttt{$<$suspend$>$} & If non-zero, {\em
					SinqHM{\usc}srv\/} will immediately
					suspend itself
					as soon as it starts. This is intended
					for debug purposes.
      \end{tabular}\hspace*{\fill}
%
    \subsection{The SinqHM Auto-configure Utility}
%   ==============================================
%
      \label{auto-config}
%
      The SinqHM auto-configure utility, {\em SinqHM{\usc}bootParamsConfig}, is
      a program which will analyse the {\em other\/} field of the boot setup of
      the processor and configure {\em SinqHM{\usc}srv\/} accordingly. It is an
      optional module whose use is intended to simplify the start-up of {\em
      SinqHM{\usc}srv\/} in cases where SinqHM is being used without a data
      acquisition
      computer\footnote{Normally, SinqHM is configured prior to data acquisition
      via software such as SICS, the SINQ Instrument Control System,
      which is running on the data acquisition computer.}. The
      syntax of the {\em other\/} field is described in
      Appendix~\ref{other}. The way in which the {\em other\/} field is specified
      is described in Section~\ref{PPC-Soft-Setup}.

      \noindent {\em SinqHM{\usc}bootParamsConfig\/} is built from the following
      source files: \\[1.0ex]
%
      \hspace*{\fill} \begin{tabular}{ll}
      SinqHM{\usc}bootParamsConfig.c	& - the main program. \\
      SinqHM{\usc}def.h			& - header file defining symbols and
						structures.
      \end{tabular} \hspace*{\fill} \\[1.0ex]
%
      The program is compiled via the command: \\[1.0ex]
%
      \verb#   ccvx -I${WIND_BASE}/target/config/all SinqHM_bootParamsConfig.c#

      \noindent which generates the object module {\em
      SinqHM{\usc}bootParamsConfig.o}. This can be loaded into VxWorks and
      started. {\em ccvx\/} is an alias defined in the {\em sinqhm\/}
      login script as:\begin{verbatim}
    alias ccvx 'ccppc -O0 -mcpu=603 -I${WIND_BASE}/target/h ' \
               '-fno-builtin -fno-for-scope -nostdinc ' \
               '-DCPU=PPC603 -D_GNU_TOOL -gdwarf -c -Wimplicit'\end{verbatim}

      \noindent When the {\em SinqHM{\usc}bootParamsConfig\/} process is created
      via the VxWorks {\em taskSpawn\/} function\footnote{This normally happens
      via code which has been added to the {\em usrConfig.c\/} file, but the
      program may also be
      started manually via the Tornado WindSh utility for debugging 
      purposes.}, up to
      10 arguments, \verb#<arg1># \ldots
      \verb#<arg10>#, may be specified. Only \verb#<arg1># is used by
      {\em SinqHM{\usc}bootParamsConfig\/} as follows: \\[1.0ex]
      \hspace*{\fill}\begin{tabular}{llp{90mm}}
	\texttt{$<$arg1$>$}  & \texttt{$<$port$>$} & The TCP/IP port number to
					be used for connecting to SinqHM when
					issuing the SQHM{\usc}CONFIG command.
					No default is allowed. The value of
					2400 should usually be specified.
      \end{tabular}\hspace*{\fill}
%
    \subsection{The Test Generator Server}
%   ======================================
%
      The Test Generator Server, {\em lwl{\usc}server}, is a program which can
      run in the Power-PC processor and which can be used to generate a data
      stream into the fibre-optic input channel of SinqHM via a Histogram
      Test-generator Module. The data to be
      written to the module is created by an interactive client program running
      elsewhere and connecting to {\em lwl{\usc}server\/} via TCP/IP sockets.
      It is an optional module whose use is intended to facilitate the
      debugging of {\em SinqHM{\usc}srv}.

      \noindent {\em lwl{\usc}server\/} is built from the following
      source files: \\[1.0ex]
%
      \hspace*{\fill} \begin{tabular}{ll}
      lwl{\usc}server.c		& - the main program. \\
      vmio10{\usc}def.h		& - header file defining symbols for
						VMIO10 VME modules.
      \end{tabular} \hspace*{\fill} \\[1.0ex]
%
      The program is compiled via the command: \\[1.0ex]
%
      \verb#      ccvx lwl_server.c#

      \noindent which generates the object module {\em
      lwl{\usc}server.o}. This can be loaded into VxWorks and
      started. {\em ccvx\/} is an alias defined as shown in
      Section~\ref{auto-config}.

      \noindent When the {\em lwl{\usc}server\/} process is created via the
      VxWorks {\em taskSpawn\/} function, up to 10 arguments, \verb#<arg1>#
      \ldots \verb#<arg10>#, may be specified. The following are used by {\em
      lwl{\usc}server\/}: \\[1.0ex]
      \hspace*{\fill}\begin{tabular}{llp{90mm}}
	\texttt{$<$arg1$>$}  & \texttt{$<$port$>$} & The TCP/IP port number to
					be used for listening for connections
					from clients. Default = 3501. \\
	\texttt{$<$arg2$>$}  & \texttt{$<$base-addr$>$} & The VME base address
					of the Histogram Test-generator Module.
      					Default = 0x1800. \\
	\texttt{$<$arg3$>$}  & \texttt{$<$verbose$>$} & If non-zero, {\em
					lwl{\usc}server\/} generates extra
					messages via the COM1 console port of
					the MVME-1603. \\
	\texttt{$<$arg10$>$} & \texttt{$<$suspend$>$} & If non-zero, {\em
					lwl{\usc}server\/} will immediately
					suspend itself
					as soon as it starts. This is intended
					for debug purposes.
      \end{tabular}\hspace*{\fill}
%
    \subsection{The {\em SinqHM{\usc}bootUtil\/} Server}
%   ====================================================
%
      The {\em SinqHM{\usc}bootUtil\/} server is a program which can
      run in the Power-PC processor and which can be used to display and
      modify the boot parameters of the Power-PC via a client program running
      remotely. The Power-PC can also be rebooted via the
      {\em SinqHM{\usc}bootUtil\/}
      server. It is an optional module whose use is intended to allow
      the configuration of a Power-PC's boot parameters in cases where
      the more usual method via a `dumb' terminal connected to its COM1 port,
      as described in Section~\ref{PPC-Soft-Setup}, is not convenient.

      \noindent {\em SinqHM{\usc}bootUtil\/} is built from the following
      source files: \\[1.0ex]
%
      \hspace*{\fill} \begin{tabular}{ll}
      SinqHM{\usc}bootUtil.c		& - the main program. \\
      SinqHM{\usc}def.h			& - header file defining symbols and
						structures.
      \end{tabular} \hspace*{\fill} \\[1.0ex]
%
      The program is compiled via the command: \\[1.0ex]
%
      \verb#   ccvx -I${WIND_BASE}/target/config/all SinqHM_bootUtil.c#

      \noindent which generates the object module {\em
      SinqHM{\usc}bootUtil.o}. This can be loaded into VxWorks and
      started. {\em ccvx\/} is an alias defined as shown in
      Section~\ref{auto-config}.

      \noindent When the {\em SinqHM{\usc}bootUtil\/} process is created via the
      VxWorks {\em taskSpawn\/} function, up to 10 arguments, \verb#<arg1>#
      \ldots \verb#<arg10>#, may be specified. The following are used by {\em
      SinqHM{\usc}bootUtil\/}: \\[1.0ex]
      \hspace*{\fill}\begin{tabular}{llp{90mm}}
	\texttt{$<$arg1$>$}  & \texttt{$<$port$>$} & The TCP/IP port number to
					be used for listening for connections
					from clients. Default = 2300. \\
	\texttt{$<$arg10$>$} & \texttt{$<$suspend$>$} & If non-zero, {\em
					SinqHM{\usc}bootUtil\/} will immediately
					suspend itself
					as soon as it starts. This is intended
					for debug purposes.
      \end{tabular}\hspace*{\fill}
%
    \section{Starting SinqHM Manually}
%   ==================================
%
      \label{manual-start}
%
      This section describes the manual loading and startup of the SinqHM
      software. It is presented in check-list form, assuming some familiarity
      with the VxWorks Tornado cross-development system. The reader is referred
      to the Tornado User's Guide \cite{Tornado-Users} for more information.
      \begin{enumerate}
%
      \item It is assumed in the following that the Power-PC boot parameters
	have been configured so that the boot file is
	the basic VxWorks system image, \texttt{vxWorks{\usc}basic},
	described in Section~\ref{VxWorks-os} and
	that the Power-PC has been freshly booted. When debugging, it is
	recommended to reboot the Power-PC rather than to try simply to reload
	the software. This is because the TCP/IP ports are not automatically
        released when a module is reloaded. Reloaded software modules will
	therefore generally fail at the call to the {\em bind\/} function.
%
      \item From a terminal with X-windows support, login to {\em pss123\/} as
	user {\em sinqhm\/} and change the default directory: \\[1.0ex]
%
	\verb#      cd $HOME/wind/SinqHM/DMC/NEW#
%
      \item Start the Tornado launcher\footnote{If one is logged-in to
	{\em pss123\/} from a Unix workstation, it may be necessary to issue
	the command \texttt{"xhost pss123"} on the workstation before the
	Tornado launcher can be started.} via a command of the form: \\[1.0ex]
%
	\verb#      launch -fg black &#
%
      \item If necessary, select the launcher's menu item
	``\texttt{Target/Create ...}'' and create a {\em Target Server\/} for the
	target processor. The only item in the {\em Create Target Server\/} form
	which needs to be specified is ``\texttt{Target name or IP address}''.
	As a result of typing the target's name into this item, the entry in
	``\texttt{Target server launch command}'' should read
	``\verb#tgtsvr <target-name>#''. None of the other check marks need to
	be selected. The {\em Target Server\/} can then be started by clicking the
	{\em Launch\/} button. The name of the target should then appear in the
	list of targets in the Tornado Launcher window.
%
      \item Select the target in the list of targets in the Tornado Launcher
	window by clicking on it.
%
      \item Start a WindSh tool for the target processor by clicking
	the {\em WindSh\/} button. A WindSh window should
	appear and the VxWorks shell prompt, ``\verb#->#'' should be displayed.
%
      \item Load the SinqHM modules into the VxWorks system via the commands:
	\\[1.0ex]
%
	\verb#      -> ld < SinqHM_srv.o# \\
	\verb#      -> ld < lwl_server.o# \\
	\verb#      -> ld < SinqHM_bootParamsConfig.o# \\
	\verb#      -> ld < SinqHM_bootUtil.o# \\[1.0ex]
%
	Note that these commands assume that the default directory has been set
	correctly in Step~2 above. Otherwise, the object files must be prefixed
	with the appropriate directory path.
%
      \item If it is desired to debug one of the SinqHM modules, it is now
	possible to start the module in the suspended state via the WindSh
	spawn-and-suspend command, {\em sps}, e.g. \\[1.0ex]
%
	\verb#      -> sps lwl_server, 3501, 0x1800, 0# \\[1.0ex]
%
	The meanings of the arguments for the various modules are given in
	Section~\ref{SinqHM-Soft}. One can now start the Tornado debugger, {\em
	CrossWind}, attach to the suspended task and debug it interactively.
	Note that the program counter of the task will initially be in the
	{\em suspend\/} routine of the operating system. The easiest way to get to
	the start of the program's code is by issuing the \sfbf{s} command to
	the debugger.
%
      \item Alternatively, the programs may be started normally via the normal
	VxWorks spawn function, {\em taskSpawn}, e.g. \\[1.0ex]
%
	\verb#      -> taskSpawn "hmRoot2400", 100, 8, 20000, \# \\
        \verb#               SinqHM_srv, 2400, 0, 0x1900# \\[1.0ex]
%
	The arguments preceding {\em SinqHM{\usc}srv\/} are standard VxWorks
	defaults for priority, stack size, etc. The other arguments are as
	defined in Section~\ref{SinqHM-Soft}.
%
      \end{enumerate}
 \newpage
%
    \appendix
    \section{The {\em bld\/} Script}
%   ==============================
%
      \label{bld-script}
%
      The various components of SinqHM, including the bootable system images,
      can be created using the {\em bld\/} script. For help on using the script,
      simply enter the command \\[1.0ex]
%
	\hspace*{15mm}\texttt{\$HOME/wind/SinqHM/bld h} \\[1.0ex]
%
      A simplified version of the script is reproduced
      below. The script is actually more complicated than illustrated on
      account of checking for the correctness of the arguments.
      \begin{verbatim}
    #!   /bin/csh
    #-------------------------------------------------
    #           pss123:~sinqhm/wind/SinqHM/bld   V01G
    #
    #       Script to compile and link the SinqHM programs for vxWorks
    #
       set proc = "$0"
       if (`expr match "$proc" "\/"` != 1) set proc = "./$0"
       cd $proc:h                     # Move to bld's directory!
       if ("$1" == "dmc") then
         cd DMC/NEW                           <== See Note 1
         set defn = '-DINST="DMC" -DDMC'      <== See Note 2
       else if ("$1" == "sans") then
\end{verbatim}

	\vspace*{-3.5ex}\hspace*{15mm} \vdots \vspace*{-3.5ex}
	\begin{verbatim}
       endif
    #
       set src = "maden@lnsa04:sinqhm/"
    #
       printf "\nWorking directory is %s\n" "$cwd"
       printf 'Source is "%s"\n\n' "$src"
    #
       alias  ccvx   'ccppc -O0 -mcpu=603 -I${WIND_BASE}/target/h ' \
            '-fno-builtin -fno-for-scope ' \
            '-nostdinc -DCPU=PPC603 -D_GNU_TOOL -gdwarf -c -Wimplicit'
\end{verbatim}

      \vspace*{-2.5ex}\hspace*{15mm} \vdots \vspace*{-2.5ex}
      \begin{verbatim}
    #-------------------------------------------------
       echo "Building SinqHM_srv ..."
       echo "   Copying header files ..."
          rcp -p  "${src}SinqHM_gbl.h" ./SinqHM_gbl.h
          rcp -p  "${src}SinqHM_def.h" ./SinqHM_def.h
          rcp -p  "${src}vmio10_def.h" ./vmio10_def.h
       echo "   Copying source files ..."
          rcp -p  "${src}SinqHM_srv_main.c"     ./SinqHM_srv_main.c
          rcp -p  "${src}SinqHM_srv_routines.c" ./SinqHM_srv_routines.c
          rcp -p  "${src}SinqHM_srv_filler.c"   ./SinqHM_srv_filler.c
          rcp -p  "${src}SinqHM_srv_server.c"   ./SinqHM_srv_server.c
    #---------------------------------- (continued on next page) \end{verbatim}
 \newpage \begin{verbatim}
    #---------------------------------- (continuation of "bld")
       echo "   Compiling SinqHM ..."
          ccvx $defn SinqHM_srv_main.c        <== See Note 2
          ccvx $defn SinqHM_srv_routines.c
          ccvx $defn SinqHM_srv_filler.c
          ccvx $defn SinqHM_srv_server.c
       echo "   Linking ..."
          ldppc -o SinqHM_srv.o -r   \
                    SinqHM_srv_main.o SinqHM_srv_routines.o \
                    SinqHM_srv_filler.o SinqHM_srv_server.o
       echo "   Done. Result is $cwd/SinqHM_srv.o"
    #-------------------------------------------------
       echo "Building lwl_server ..."
       echo "   Copying files ..."
          rcp -p "${src}vmio10_def.h" ./vmio10_def.h
          rcp -p "${src}lwl_server.c" ./lwl_server.c
       echo "   Compiling lwl_server.c ..."
          ccvx lwl_server.c
       echo "   Done."
    #-------------------------------------------------
       echo "Building SinqHM_bootParamsConfig ..."
       echo "   Copying files ..."
          rcp -p "${src}SinqHM_def.h" ./SinqHM_def.h
          rcp -p "${src}SinqHM_bootParamsConfig.c" \
                        ./SinqHM_bootParamsConfig.c
       echo "   Compiling SinqHM_bootParamsConfig.c ..."
          ccvx -I${WIND_BASE}/target/config/all \
                        SinqHM_bootParamsConfig.c
       echo "   Done."
    #-------------------------------------------------
       echo "Building SinqHM_bootUtil ..."
       echo "   Copying files ..."
          rcp -p "${src}SinqHM_def.h" ./SinqHM_def.h
          rcp -p "${src}SinqHM_bootUtil.c" \
                        ./SinqHM_bootUtil.c
       echo "   Compiling SinqHM_bootUtil.c ..."
          ccvx -I${WIND_BASE}/target/config/all \
                        SinqHM_bootUtil.c
       echo "   Done."
    #-------------------------------------------------
       printf "\n\nBuilding vxWorks_auto system image ...\n\n"
       set dflt = "$PWD"
       cd $WIND_BASE/target/config/mv1603
       echo " Default directory changed to: $PWD"
    #
       touch config.h        # Force a complete re-compilation
     #---------------------------------- (continued on next page) \end{verbatim}
 \newpage \begin{verbatim}
    #---------------------------------- (continuation of "bld")
       set mods = ( \
             ../../../../SinqHM/SinqHM_srv.o \
             ../../../../SinqHM/lwl_server.o \
             ../../../../SinqHM/SinqHM_bootParamsConfig.o \
             ../../../../SinqHM/SinqHM_bootUtil.o )
       make  ADDED_CFLAGS=" -DSINQHM_SPAWN=1" \
             ADDED_MODULES="$mods"
       cp -p vxWorks     $dflt/vxWorks_auto
       cp -p vxWorks.sym $dflt/vxWorks.sym
       echo "   Done. Result is $dflt/vxWorks_auto"
    #-------------------------------------------------
       printf "Building vxWorks_basic system image ...\n\n"
       cd $proc:h                     # Move to bld's directory!
       set dflt = "$PWD"
       cd $WIND_BASE/target/config/mv1603
       echo " Default directory changed to: $PWD"
       touch config.h        # Force a complete re-compilation
    
       make  ADDED_CFLAGS=" -DSINQHM_SPAWN=0"  \
             ADDED_MODULES=""
       cp -p vxWorks     $dflt/vxWorks_basic
       cp -p vxWorks.sym $dflt/vxWorks.sym
       echo "   Done. Result is $dflt/vxWorks_basic"\end{verbatim}%
      \hspace*{-5mm}\textbf{Notes:}
      \begin{enumerate}
	\item {\em bld\/} changes to the instrument's \texttt{NEW} directory
		for building instrument dependent modules.
	\item {\em defn\/} supplies compile time definitions
		to enable the selection of instrument specific code by
		means of conditional compilation macros.
      \end{enumerate}
 \newpage
%
    \section{The {\em other\/} Field}
%   =================================
%
      \label{other}
%
      \vspace*{-2ex}
      The {\em other\/} field of the boot setup of the Power-PC processor can be
      used for specifying the default configuration of SinqHM. It can, for
      example, be used to set a default histogramming mode and number of bins
      per histogram. The procedure for setting up the {\em other\/} field is
      described in Section~\ref{PPC-Soft-Setup}. The syntax of the field is
      described in the comments in file {\em SinqHM{\usc}bootParamsConfig.c}.
      These comments are reproduced here:
      \vspace*{-2ex}
      \begin{verbatim}
    /*
    **  The "other" string may be specified as follows:
    **
    **         <action>=<arg0>,..,<argn>/...
    **
    **  There may be no white space characters in the string. Tokens
    **  in the string may be specified in upper or lower case.
    **
    **  <action> may be "sp"   for "Spawn a task"
    **                  "sps"  for "Spawn and suspend a task"
    **                  "cfg"  for "Configure SinqHM_srv"
    **                  "wt"   for "Wait"
    **----------------------------------------------------
    **  If <action> = "sp" or "sps", then
    **
    **     <arg0> = name of task to spawn. This may be:
    **                "SinqHM"   for SinqHM_srv or
    **                "lwl"      for lwl_server or
    **                "bootUtil" for SinqHM_bootUtil or
    **                "focus"    for FOCUS_srv
    **     <arg1>,..<arg9> = integer args for the spawn, as follows:
    **
    **    If <arg0> = "SinqHM"
    **     <arg1> = TCP/IP port number for server (dflt=2400).
    **     <arg2> = <use-level-gen> flag. If non-zero, then use level
    **                  generator to generate timing signals (dflt=0).
    **     <arg3> = base address of VMIO10 level generator
    **                     module (dflt=0x1900).
    **
    **    If <arg0> = "lwl"
    **     <arg1> = TCP/IP port number for lwl_server (dflt=3501).
    **     <arg2> = base address of Histogram Test-generator
    **                     module (dflt=0x1800).
    **     <arg3> = verbosity. If non-zero, be verbose (dflt=0).
    **
    **    If <arg0> = "bootUtil"
    **     <arg1> = TCP/IP port number for SinqHM_bootUtil (dflt=2300).
    **
    **    If <arg0> = "focus"
    **     <arg1> = name of hostM (Mittel-bank) (dflt=localhost).
    **     <arg2> = #-counters in Mittel-bank (dflt=151).\end{verbatim}
 \newpage%
      \begin{verbatim}
    **     <arg3> = name of hostO (Ober-bank) (dflt=lnse05.vme).
    **     <arg4> = #-counters in Ober-bank (dflt=117).
    **     <arg5> = name of hostU (Unter-bank) (dflt=lnse06.vme).
    **     <arg6> = #-counters in Unter-bank (dflt=116).
    **     <arg7> = Client-side TCP/IP port number (dflt=2500).
    **     <arg8> = Server-side TCP/IP port number (dflt=2400).
    **
    **    In addition, <arg10> will be set to 0 for "sp" and 1 for
    **    "sps". SinqHM_srv, lwl_server and SinqHM_bootUtil will suspend
    **    themselves immediately if they find <arg10> is non-zero. This
    **    cooperation on the part of the spawned task is intended as a
    **    debugging aid.
    **
    **    "SinqHM" and "SinqHM_bootUtil" will be spawned with priority
    **    100, "lwl" with priority 250.
    **
    **  Notes:
    **    a) Lower numbers imply higher priority.
    **    b) "SinqHM_Filler" also gets spawned with priority 250. It is
    **          important that "lwl" and "SinqHM_Filler" have the same
    **          priority.
    **----------------------------------------------------
    **  If <action> = "cfg":
    **     <arg0> = HM_DIG, HM_PSD, TOF, HRPT or TRANS to specify the
    **                      hist memory mode.
    **     <arg8> = sub-mode bits to "or" with <arg0> (dflt=0)
    **     <arg9> = TCP/IP port # of server (dflt=2400)
    **    And for <arg0> = HM_DIG or HRPT,
    **     <arg1> = # bins (no dflt)
    **     <arg2> = # histograms (dflt=1)
    **     <arg3> = bytes per bin (dflt=4)
    **     <arg4> = bin compression (dflt=0)
    **     <arg5> = first bin (dflt=0)
    **
    **    And for <arg0> = TOF,
    **     <arg1> = # counters (no dflt)
    **     <arg2> = # bins per counter (no dflt)
    **     <arg3> = time_span_per_bin (no dflt)
    **     <arg4> = Start delay (dflt=0)
    **     <arg5> = # of first counter (dflt=0)
    **     <arg6> = bytes per bin (dflt=4)
    **
    **     Note: The built-in "cfg" program can only define bins of equal
    **          width. For non-equal width bins, one must send the
    **          SQHM_CONFIG message to SinqHM_srv from a host computer.\end{verbatim}
 \newpage%
      \begin{verbatim}
    **
    **    And for <arg0> = TRANS,
    **     <arg1> = #-buffers (dflt = 8)
    **     <arg2> = buff-size (dflt = 4096)
    **
    **    And for <arg0> = HM_PSD, the arguments still need defining.
    **----------------------------------------------------
    **  If <action> = "wt", then
    **
    **     <arg0> = number of seconds to wait (may be useful for
    **                FOCUS startup).
    **----------------------------------------------------
    **  For example:
    **
    **     other = "sp=bootUtil/sp=SinqHM/cfg=HM_DIG,400"
    **
    **  will cause bootUtil and SinqHM_srv to be automatically started
    **  after the system has been booted and will configure it in HM_DIG
    **  mode with a single histogram of 400 bins (as used for DMC).
    **----------------------------------------------------
    */
      \end{verbatim}
%
 \newpage
%
 \begin{thebibliography}{9}
      \addcontentsline{toc}{section}{References}

 \bibitem{Hist-Mem-Spec} D. Maden, PSI, May 1997 \\
	{\em The SINQ Histogram Memory, SinqHM} \\
	Project SINQ 891/MD36-701
      
 \bibitem{MVME-1603} Motorola Inc, February 1995 \\
	{\em MVME1603/MVME1604 Single Board Computer} \\
	{\em Installation and Use\/} V1600-1A/IH1

 \bibitem{Tornado-Users} Wind River Systems, December 1995 \\
	{\em Tornade User's Guide (Unix Version)} \\
      	DOC-11033-ND-01

 \bibitem{LNS-CVS} Mark K\"{o}nnecke, February 2000 \\
	{\em The LNS CVS Repository} \\
      	Internal Note

 \end{thebibliography}
\end{document}
