From d49dab42ef33c1f30719128d133999874cdc020b Mon Sep 17 00:00:00 2001 From: cvs Date: Wed, 8 Nov 2000 13:26:00 +0000 Subject: [PATCH] SinqHM Specification --- sinqhm/hist_mem_spec.tex | 2605 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 2605 insertions(+) create mode 100755 sinqhm/hist_mem_spec.tex diff --git a/sinqhm/hist_mem_spec.tex b/sinqhm/hist_mem_spec.tex new file mode 100755 index 00000000..b646fef7 --- /dev/null +++ b/sinqhm/hist_mem_spec.tex @@ -0,0 +1,2605 @@ +% TAS_SRC:[PSI.NOTES]HIST_MEM_SPEC.TEX - Ident 1.4 +% ==================================== +%% +%%==================================================================== +\documentclass[openbib,a4paper,twoside,12pt]{article} +\usepackage{array} +\usepackage{epsfig} +% + \newcommand{\nc}{\newcommand} + \newcommand{\rc}{\renewcommand} +% + \nc{\myident}{Vn 1.5} + \nc{\mydate}{23rd November, 1999} +% +%%==================================================================== +%% +%% +--------------------------------------------------------------+ +%% | 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 . . . . : Specification of SinqHM Histogram Memory +%% Author . . . . . . . . . . . : D.Maden +%% Date of creation . . . . . . : 2-Apr-1997 +%% +%% Updates: +%% 2-Apr-1997 DM. Initial Latex Version. +%% 1.3a 3-Dec-1998 DM. Add details of SQHM__TOF configuration. +%% 1.4a 15-Jun-1999 DM. Add details of SQHM_MERGE command. +%% 1.4b 17-Aug-1999 DM. Rename SQHM_MERGE as SQHM_PROJECT. +%%==================================================================== +%% To process this file on PSICL0: +%% +%% $ import tex +%% $ set default usr_scroot:[maden] +%% $ copy lnsa09::tas_src:[psi.notes]hist_mem_spec.tex [] +%% $ copy lnsa09::tas_src:[psi.notes]hist_mem_spec_fig%.ps [] +%% $ copy lnsa09::tas_src:[psi.notes]psi_logo.ps,sinq_logo [] +%% $ latex hist_mem_spec +%% $ dvips/printer=lps20 hist_mem_spec +%% $ print/noti/noflag/par=(side=two,page_orientation=portrait) - +%% /que=whga_u119_ps1 hist_mem_spec.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}spec.tex} +% + \nc{\Topbox}[1]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(30,7){\line(0,-1){1}} + \put(60,7){\line(0,-1){1}} + \put(90,7){\line(0,-1){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + \put(0,7){\makebox(5,3)[lt]{\textsf{\tiny{31}}}} + \put(115,7){\makebox(5,3)[rt]{\textsf{\tiny{0}}}} + } +% + \nc{\Midbox}[1]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(30,7){\line(0,-1){1}} + \put(60,7){\line(0,-1){1}} + \put(90,7){\line(0,-1){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + } +% + \nc{\Midwordbox}[2]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(30,7){\line(0,-1){1}} + \put(60,7){\line(0,-1){7}} + \put(90,7){\line(0,-1){1}} + \put(30,3.5){\makebox(0,0){\textsf{#1}}} + \put(90,3.5){\makebox(0,0){\textsf{#2}}} + } +% + \nc{\Midbytebox}[4]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(30,7){\line(0,-1){7}} + \put(60,7){\line(0,-1){7}} + \put(90,7){\line(0,-1){7}} + \put(15,3.5){\makebox(0,0){\textsf{#1}}} + \put(45,3.5){\makebox(0,0){\textsf{#2}}} + \put(75,3.5){\makebox(0,0){\textsf{#3}}} + \put(105,3.5){\makebox(0,0){\textsf{#4}}} + } +% + \nc{\Midbody}[1]{ + \put(0,0){\line(0,1){7}} + \put(120,7){\line(0,-1){7}} + \put(0,7){\line(1,0){1}} + \put(120,7){\line(-1,0){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + } +% + \nc{\Midbodydashed}[1]{ + \put(0,0){\multiput(0,1)(0,2){3}{\line(0,1){1}}} + \put(120,0){\multiput(0,1)(0,2){3}{\line(0,1){1}}} + \put(0,7){\line(1,0){1}} + \put(120,7){\line(-1,0){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + } +% + \nc{\Botbox}[1]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(0,0){\line(1,0){120}} + \put(30,7){\line(0,-1){1}} + \put(60,7){\line(0,-1){1}} + \put(90,7){\line(0,-1){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + } +% + \nc{\Botbody}[1]{ + \put(0,0){\line(0,1){7}} + \put(120,7){\line(0,-1){7}} + \put(0,0){\line(1,0){120}} + \put(0,7){\line(1,0){1}} + \put(120,7){\line(-1,0){1}} + \put(30,0){\line(0,1){1}} + \put(60,0){\line(0,1){1}} + \put(90,0){\line(0,1){1}} + \put(60,3.5){\makebox(0,0){\textsf{#1}}} + } +% + \nc{\Botwordbox}[2]{ + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){120}} + \put(120,7){\line(0,-1){7}} + \put(0,0){\line(1,0){120}} + \put(30,7){\line(0,-1){1}} + \put(60,7){\line(0,-1){7}} + \put(90,7){\line(0,-1){1}} + \put(30,3.5){\makebox(0,0){\textsf{#1}}} + \put(90,3.5){\makebox(0,0){\textsf{#2}}} + } +% + \nc{\Topwbox}[2]{ % Same as \Topbox but with width arg. + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}% + \line(0,-1){7}} + \put(#1,6){\line(0,1){1}} + \put(#1,0){\put(#1,6){\line(0,1){1}}} + \put(#1,0){\put(#1,0){\put(#1,6){\line(0,1){1}}}} + \put(#1,0){\put(#1,3.5){\makebox(0,0){\textsf{#2}}}} + \put(0,7){\makebox(5,3)[lt]{\textsf{\tiny{31}}}} + \put(#1,0){\put(#1,0){\put(#1,0){\put(#1,0){\put(-5,7){% + \makebox(5,3)[rt]{\textsf{\tiny{0}}}}}}}} + } +% + \nc{\Midwbox}[2]{ % Same as \Midbox but with width arg. + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}% + \line(0,-1){7}} + \put(#1,6){\line(0,1){1}} + \put(#1,0){\put(#1,6){\line(0,1){1}}} + \put(#1,0){\put(#1,0){\put(#1,6){\line(0,1){1}}}} + \put(#1,0){\put(#1,3.5){\makebox(0,0){\textsf{#2}}}} + } +% + \nc{\Midwwordbox}[3]{ % Same as \Midwordbox but with width arg. + \put(0,0){\line(0,1){7}} + \put(0,7){\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}% + \line(0,-1){7}} + \put(#1,6){\line(0,1){1}} + \put(#1,0){\put(#1,0){\line(0,1){7}}} + \put(#1,0){\put(#1,0){\put(#1,6){\line(0,1){1}}}} + \put(#1,3.5){\makebox(0,0){\textsf{#2}}} + \put(#1,0){\put(#1,0){\put(#1,3.5){\makebox(0,0){\textsf{#3}}}}} + } +% + \nc{\Botwwordbox}[3]{ % Same as \Botwordbox but with width arg. + \put(0,0){\line(0,1){7}} + \put(0,0){\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}% + \line(0,1){7}} + \put(0,7){\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}\line(1,0){#1}} + \put(#1,6){\line(0,1){1}} + \put(#1,0){\put(#1,0){\line(0,1){7}}} + \put(#1,0){\put(#1,0){\put(#1,6){\line(0,1){1}}}} + \put(#1,3.5){\makebox(0,0){\textsf{#2}}} + \put(#1,0){\put(#1,0){\put(#1,3.5){\makebox(0,0){\textsf{#3}}}}} + } +% + \nc{\Tabrow}[3]{% + \textsf{#1} & \textsf{\textbf{#2}} & \textsf{#3} \\% + }% +% + \nc{\sfbf}[1]{\textsf{\textbf{#1}}} +% + \setlength{\unitlength}{1.0mm} +% +% Define insertplot is insert a PostScript plot. +% Usage: +% \insertplot{}{}{} +% Example: +% \insertplot{dvipsdoc.pal}{70mm}{5.0mm} +% + \def\insertplot#1#2#3{\par + \hbox{% + \hskip #3 + \vbox to #2{ + \vfil + \special{ps: plotfile #1} + }% + } + } +% + \title{The SINQ Histogram Memory \\ SinqHM} + \author{D. Maden} + \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-701.-}} + \put( 25,195){\makebox(0,0)[l]{Maden, D}} + \put( 25,175){\makebox(0,0)[l]{The SINQ Histogram Memory, SinqHM}} + \put(170,152){\makebox(0,0){39}} + \put( 25,135){\shortstack[l]{% + This note specifies the interface between the data \\ + acquisition software and the SINQ histogramming memories}} + \put( 25, 86){\shortstack[l]{% + \tiny HISTOGRAM MEMORY \\ + \tiny SINQHM}} + \put( 25, 60){\shortstack[l]{% + \tiny D. Maden, WHGA/247 \\ + \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*{126mm}SinqHM \myident}}% + {\underline{\rm SinqHM \myident \hspace*{44mm} File = \myfile}} +% + \begin{abstract} + \noindent This note specifies the interface + between the data acquisition software and + the SINQ histogramming memories. + \end{abstract} +% + \tableofcontents +% + \cleardoublepage + \rc{\thepage}{\arabic{page}} +% + \pagestyle{myheadings} + \markboth{\hspace*{-8mm} \underline{\rm \hspace*{126mm} SinqHM \myident}}% + {\underline{\rm SinqHM \myident \hspace*{126mm}} \hspace*{-8mm}} +% + \section{Introduction} +% ====================== +% + This note specifies the interface between the SINQ histogram memory, + SinqHM, and the data acquisition software. + + The histogram memory is based on a VME Power-PC single board + computer (MVME-1603). In the first instance, access to the memory + from the data acquisition software will be via its Ethernet interface. + At a later date, it is possible to consider a read-out of the memory + either via the VME bus or via a higher speed network technology. The + client/server nature of the specification should make such extensions + relatively simple. + + The initial version of this specification, therefore, is concerned + exclusively with defining a TCP/IP client/server model which will + allow the control and read-out of the histogram memory via its + Ethernet interface. The histogram memory will act as a TCP/IP + server offering data access to several data acquisition clients + simultaneously. Many of the concepts described here are similar to + those implemented in the histogram memory server package which is + in use on \musr experiments at PSI \cite{CTN94005}. + + This document assumes a certain familiarity with the C programming + language. The header file {\em SinqHM{\usc}def.h} defines all data + structures and symbols referred to in the text. +% + \section{Histogramming Concepts and Definitions} +% ================================================ +% + It appears that there are differences in terminology associated with + histograms and the histogramming process according to one's scientific + background. These differences can naturally lead to some confusion. + The purpose of this section is to try to remove this confusion by + describing the process of histogramming in abstract terms and defining + the various terms as used in this document. Some of the limitations + implicit in the SinqHM implementation will also be discussed. + The description of PAW, the Physics Analysis Workstation software + package from the CERN + Program Library \cite{PAW}, should be consulted for more + information\footnote{Warning: this reference naturally presents the high + energy physicist's histogramming terminology!}. + + A {\em histogram} is a frequency distribution of an {\em + Ntuple}\footnote{An {\em Ntuple} is a list of identical data structures + where each element describes a single event. In the simple + case typical of neutron diffraction experiments, an element of the Ntuple + might be a single integer giving the number of the counter which detected + a neutron. In the more complex situation of a signal from a position + sensitive detector, an element of the Ntuple might be several integers + giving the various ADC values associated with the signal.}. Each element + of the {\em Ntuple} specifies a measured event such as a detected + neutron. The processing of an element may generate one or more + quantities characterising the event. The process of generating a + frequency distribution of these quantities is referred to as {\em + histogram filling} or simply {\em histogramming}. + + The number of quantities which are used to define an event + determines the dimension of the histogram. For SinqHM, the events of + interest are detected neutrons and the various dimensions of a histogram + might be: + \begin{itemize} + \item the x- or y-coordinate of a position sensitive detector; + \item the time-of-flight of a neutron; + \item the wire number of a one-dimensional counter array or + the counter number of an array of counters. + \end{itemize} +% + The histogram is defined by dividing each of its dimensions into + a number of intervals called {\em bins} or {\em cells}. Once the bin + boundaries in each dimension have been specified, the total number of + bins can be calculated and space may be reserved for compiling the + histogram. SinqHM refers to this operation as {\em configuring} the + histogram memory. Other histogram packages such as HBOOK \cite{PAW} refer + to it as {\em booking} the histogram. + + In the general case, the bin boundaries are floating point numbers. It is + also possible that bin boundaries along a particular axis are not equally + spaced. A further consideration when configuring the histogram memory is + the maximum number of events to be recorded in each bin. This determines + the number of bytes of computer memory to be reserved for each + bin\footnote{SinqHM allows the user to specify that each bin be associated + with either 1, 2 or 4 bytes of storage.}. There is + naturally a trade-off between available computer memory, the desired + experimental resolution and the statistical errors. The + action to be taken by the histogramming process on bin overflow should + also be specified\footnote{SinqHM will wrap + overflowed bins to zero by default. Other actions are possible (see + Section~\ref{Sect-sinqhm-config})}. + + Once storage space for the histogram has been reserved, the histogram may + by {\em filled}. The process of filling a histogram consists of + processing each element of the Ntuple to obtain the index of a bin in the + histogram corresponding to the element. This bin is then incremented. + In the general case, it is conceivable that the bin increment be weighted + in some way so that the bin content could be a floating point number + rather than a simple counter. + + The Ntuple to be processed by SinqHM consists of events occuring in + real-time during an experimental run. It is therefore vital that the + event processing should be efficient in order to minimise the + experimental deadtime. For this reason and also because the data to be + processed by SinqHM is mainly of integer type, + the histogramming procedures implemented in SinqHM are restricted to + integer quantities, i.e. the bin boundaries are specified as + integers and the histogram bin content is a simple integer counter. + Updating a histogram involves adding one to the contents of a single bin. + + In many cases, the + dimension of a histogram is somewhat arbitrary since, + in practice, a histogram is stored as a one dimensional array in + computer memory: an $m \times n$ 2-dimensional histogram may equally + well be considered as $m$ 1-dimensional histograms with $n$ bins each. + SinqHM does not have a well-defined policy in this respect. In general, + though, the dimension of a histogram as perceived by SinqHM is a + function of the number of values used to access a bin. For example: + \begin{itemize} + \item On the FOCUS time-of-flight instrument, a histogram bin is defined + by the number of the counter which detected the neutron and the time at + which the neutron was detected after the chopper's start pulse. SinqHM + considers this to be a 2-dimensional histogram. + \item On the SANS small angle scattering instrument, the x/y position + of the neutron in the 128~$\times$~128 2-dimensional detector is + encoded into a single 14 bit integer. SinqHM therefore considers + this to be a 1-dimensional histogram with 16384 bins. Physically, + however, a 2-dimensional interpretation would be more meaningful. If the + instrument is operated in time-of-flight mode, the result is a + 2-dimensional histogram with the x/y position as one dimension + and time as the second dimension. It is also possible to operate the + instrument in {\em stroboscopic} mode in which a cyclic variation + in the conditions of the sample could be considered as yet another + dimension of the histogram. However, in the specification of SinqHM, + it has been decided to consider instead that the stroboscopic phase + be treated as a histogram selector rather than as an extra histogram + dimension. + \item On experiments with polarised neutrons, the up/down polarity + could be used as an extra dimension to the histogram. The histogram + would only have + two bins in this dimension. As with the SANS stroboscopic mode, it + has been decided to treat the up/down bit as a histogram selector + rather than as an extra histogram dimension. + \end{itemize} + + \noindent The problem of selecting the number of bytes of computer memory + associated with each bin has already been mentioned. In some + histogramming package implementations, this + parameter is referred to as the {\em bin-width}, i.e. its width in + computer memory. In this document, however, this parameter will be + referred to as {\em bytes-per-bin}. The term {\em bin-width} will be used + to refer to the physical width of the bin. For example, in a time-of + flight spectrum, the {\em bin-width}\footnote{The terms {\em bin-span} or + {\em span} may sometimes be used instead.} might refer to the time in + nsecs spanned by the bin and, in the case where the parameter being + histogrammed is a counter number, {\em bin-width} will refer to the + number of counters combined into one bin. In this latter case, the term + {\em bin-compression} may be used instead. +% + \section{Hardware Overview} +% =========================== +% + \label{Sect-hardware} +% + The data acquisition hardware of a typical SINQ instrument is as + shown in Figure~\ref{Fig-hard-config}. The various types of multi-detector + which are + planned for SINQ instruments can be interfaced via the + multi-detector interface to a 100 Mbaud fibre optic link to the + histogram memory. The multi-detector interface is set up via + front-panel switches and via its serial RS-232-C interface. + An inhibit signal\footnote{The inhibit + signal can, for + example, be generated by the {\em rate-low} output from an EL737 + Neutron Counter. It is therefore referred to as {\em Neutron Rate Low} + or {\em NRL}.} can be input to the multi-detector interface. The + state of this signal is transmitted along with the detector data + to the histogram memory and will be used to suppress data + acquisition by the histogram memory. + + \begin{figure}[b]% + \begin{center}% + \epsfig{bbllx=82,bblly=35,bburx=552,bbury=470,% + file=hist_mem_spec_fig1.ps,% + height=147mm,clip=}% + \caption{Typical SINQ Instrument Configuration}% + \label{Fig-hard-config}% + \end{center}% + \end{figure} + + The host communicates with the various serial devices, which are used to + control the instrument, via the TCP/IP based terminal server. + + The main interaction between the physicists and the instrument + hardware is via the {\em host} computer. +% + \section{Software Components} +% ============================= +% + The software components of the SinqHM sub-system are shown in + Figure~\ref{Fig-soft-comp}. + The SinqHM-master process is responsible for creating + offspring processes which then run asynchro\-nously under the + PowerPC's operating system. When the SinqHM sub-system is first + started, only SinqHM-master is running. It is waiting to accept a + connection on its TCP/IP listener port from a client whose first + job is to ``configure'' SinqHM. ``Configuring the Histogram Memory'' + involves specifying the mode in which the histogram memory is to + operate, reserving and initialising the histogram memory buffer, + creating the necessary semaphores for synchronising access to this + buffer and activating the {\em histogram filler} background process. + + \begin{figure}[b]% + \begin{center}% + \epsfig{bbllx=102,bblly=40,bburx=535,bbury=590,% + file=hist_mem_spec_fig2.ps,% + height=165mm,clip=}% + \caption{SinqHM Software Components}% + \label{Fig-soft-comp}% + \end{center}% + \end{figure} + + The main activity of the {\em filler} process is to read data from the + fibre-optic link and update the defined histograms accordingly. It + will use the RS-232-C connection to the front-end electronics, as + described in Section~\ref{Sect-mdi-comm}, for forwarding any necessary + configuration information to the electronics. It is also possible + to instruct {\em filler} to suspend and resume data acquisition but it + is expected that this will not be the normal method used to + control data acquisition. Instead, the data acquisition software + (running on the host computer) will usually inhibit data + acquisition by inhibiting the EL737 neutron counter. This will + then cause suspension of data acquisition by {\em filler} via the + inhibit signal to the multi-detector interface (see + Fig.~\ref{Fig-hard-config}). + + Once SinqHM has been configured, SinqHM-master enters its normal + operating mode where it will accept requests from clients. These + requests may either be of a one-off nature or they may involve the + creation of a SinqHM-server process for a long-term connection + between the client and the SinqHM system. One-off requests are + suitable for infrequent operations such as the setting of the contents of + the histogram memory to zero in preparation for a new data acquisition + run. A long-term connection would be suitable for a client which is + generating an updating display of the histogram contents. + + Figure~\ref{Fig-soft-comp} shows the + situation in which SinqHM has been configured + and has set up long-term connections for 3 clients. One of these + clients could, for example, be responsible for making a regular + archive of the histogram contents to disk file while the other two + could be programs which periodically show the current contents of + all or part of the histogram memory buffer. These two display + programs could quite well be running on two different hosts such + as the DECstation in the experimental barrack and a workstation in + a physicist's office. + + The general procedure for configuring SinqHM is described in + Section~\ref{Sect-config-sinqhm} whereas + the general procedure for creating a long-term + connection to a SinqHM-server is described in + Section~\ref{Sect-serv-setup}. The + detailed definition of messages to SinqHM is given in + Section~\ref{Sect-sinqhm-comm}. + + \begin{figure}[b]% + \begin{center}% + \epsfig{bbllx=136,bblly=40,bburx=507,bbury=480,% + file=hist_mem_spec_fig3.ps,% + height=155mm,clip=}% + \caption{Configuring SinqHM}% + \label{Fig-conf-sinqhm}% + \end{center}% + \end{figure} + + \section{Configuring the SinqHM Master} +% ======================================= +% + \label{Sect-config-sinqhm} +% + The general procedure for configuring SinqHM is shown in + Figure~\ref{Fig-conf-sinqhm}. + Note that the creation of the ``Histogram Filler'' is indicated as + being via a Posix {\em fork} operation. Unfortunately, the operating + system which is being used to develop SinqHM on the PowerPC, + VxWorks, does not provide the {\em fork} system call. The {\em taskSpawn} + system call is used instead. + + The details of the configure request which is sent to SinqHM + Master are given in Section~\ref{Sect-sinqhm-config}. + This request will define the type + of detector which is connected to the front-end electronics, the + size and number of histograms required, whether ``stroboscopic'' + (gummi) mode is to be used to switch between histograms as a result + of indicators in the data flow from the detector, etc., etc. + + \section{Setting up a Client/Server TCP/IP Data Acquisition Connection} +% ======================================================================= +% + \label{Sect-serv-setup} +% + Once SinqHM has been configured, SinqHM-master will accept + requests from clients for the establishment of a long-term + client/server connection. The procedure for doing this is shown in + Figure~\ref{Fig-tcpip-setup}. + Note that the connection is a two step process. This is + {\bf not} the normal procedure for establishing TCP/IP client/server + connections. + + \begin{figure}[b]% + \begin{center}% + \epsfig{bbllx=141,bblly=37,bburx=500,bbury=565,% + file=hist_mem_spec_fig4.ps,% + height=170mm,clip=}% + \caption{TCP/IP Client/Server Setup}% + \label{Fig-tcpip-setup}% + \end{center}% + \end{figure} + + The normal procedure would be for a server to invoke the {\em accept} + procedure to await a connection from a client. The return value of + the procedure would be a socket which could be used for communicating with + the client. Since a server usually wishes to support several + clients simultaneously, it would be + usual for the server to {\em fork} at this + point in order to create a child process which would then handle + the communication with the client using this socket. The parent + returns to the {\em accept} call to await connections from further + clients via the original socket. In this way, it is simple to + generate single-threaded code in the server and to let the + operating system handle the multi-processing aspects of the + system. + + However, when the Histogram Memory package was implemented + for the \musr experi\-ments at PSI using the VAXeln real-time + operating system, it was found that the POSIX version of the {\em fork} + procedure created a child process with too much autonomy for it to + be able to use a socket passed to it by its parent. Because of + some of the conditions which the POSIX standard imposes on child + processes created via the {\em fork} procedure\footnote{e.g. a child + should be able to survive the termination of its parent.}, it is + possible that other real-time operating systems may also suffer from + this same problem. + + In order not to abandon POSIX compatibility as a goal + in the implementation of the SinqHM package, it has been decided to use + the same two step procedure for setting up client/server connections for + SinqHM. The procedure is as follows: + \begin{itemize} + \item The server establishes a base port and waits for clients to + connect to it by calling the {\em accept} procedure. + \item The client connects to the base port and sends a + $<$serve-me$>$ request. + \item The server responds by finding a free port (it maintains a pool + of ports to be used by its children), setting a global semaphore + to the {\em claimed} state, {\em forking} to create a child and + informing + the child which port it is to use. From now on, the terms + {\em server-master} and {\em server-child} will be used to + distinguish the + two server processes. + \item The server-master then waits for the server-child to set the + global semaphore to the {\em released} state to indicate that it has + completed its initialisation.The server-child creates a socket + of its own, {\em binds} it to the port specified by the server-master, + sets it to be a {\em listener} and then releases the semaphore on + which the server-master is waiting. It then waits via the {\em accept} + procedure for the client to connect to it. + \item On continuing from the wait for the global semaphore to become + free, the server-master sends the port number of the + server-child to the client. It then closes this connection and + loops to {\em accept} a further connection to its base port from + another client. + \item The client, having received the port number from the + server-master, closes its connection with server-master, creates + a new socket and uses it to connect to the server-child. + \item This completes the setup of the client/server connection to + SinqHM. + \end{itemize} + \newpage +% + \section{Communication with SinqHM} +% =================================== +% + \label{Sect-sinqhm-comm} +% + All communication with SinqHM (master or child) + is initiated from the client side by sending a message of 64 bytes. The + format\footnote{Data structures and symbols are defined in + the {\em SinqHM{\usc}def.h} header file.} of the message is defined by + {\em struct req{\usc}buff{\usc}struct} and + has the form: +% + \begin{center}\begin{picture}(125,42)(0,-42) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{command}} + \put(0,-21){\Midbox{}} + \put(0,-28){\Midbodydashed{command-body (56 bytes)}} + \put(0,-35){\Midbody{}} + \put(0,-42){\Botbody{}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{90mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{Value = 0x12345678\footnotemark. It % + allows SinqHM to decide what byte swapping % + is required, if any.} + \Tabrow{command}{cmnd}{Command verb.} + \Tabrow{command-body}{}{56 bytes of command dependent data.} + \hline + \end{tabular}\end{center} + \footnotetext{For the benefit of readers not familiar with the C + programming language, {\em 0x} indicates a hexadecimal number.} +% + If there are data associated with the command (e.g. the SQHM{\usc}WRITE + command), the command may be followed by extra data. In such cases, + the parameters in the command-body will indicate to SinqHM how many + extra bytes of data it must receive. The client must not send any further + commands until it has sent the indicated number of data bytes. + + When SinqHM has completed the command, it returns a status + response to the client. The response to all commands is a 64 byte + message defined by {\em struct rply{\usc}buff{\usc}struct}. Its format is: +% + \begin{center}\begin{picture}(125,49)(0,-49) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{status}} + \put(0,-21){\Midbox{sub-status}} + \put(0,-28){\Midbox{}} + \put(0,-35){\Midbodydashed{reply-body (52 bytes)}} + \put(0,-42){\Midbody{}} + \put(0,-49){\Botbody{}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{90mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{Value = 0x12345678. It allows the client % + to decide what byte swapping is required, % + if any.} + \Tabrow{status}{status}{Status code} + \Tabrow{sub-status}{sub{\usc}status}{Secondary status code} + \Tabrow{reply-body}{}{52 bytes of command dependent data.} + \hline + \end{tabular}\end{center} +% + The following values for status are possible: +% + {\sffamily\begin{center}\begin{tabular}{|lr|lr|} \hline + KER{\usc}{\usc}SUCCESS & 1 & + KER{\usc}{\usc}BAD{\usc}VALUE & -6 \\ + KER{\usc}{\usc}BAD{\usc}CREATE & -2 & + KER{\usc}{\usc}BAD{\usc}RECV & -14 \\ + KER{\usc}{\usc}BAD{\usc}STATE & -4 & + KER{\usc}{\usc}BAD{\usc}ALLOC & -16 \\ + \hline + \end{tabular}\end{center}} +% + \noindent Depending on the command (e.g. the SQHM{\usc}READ command) and + the values of \sfbf{status} and + \sfbf{sub{\usc}status}, the status response may be + followed by extra data. In such cases, the parameters in the reply-body + will indicate to the client how many extra bytes of data it must + receive. These extra bytes must be read by the client before further + commands are sent to SinqHM. + + \noindent If the value of \sfbf{status} indicates an error, + the reply-body will contain a zero-terminated ASCII string which may help + in locating the problem. +% + \begin{itemize} + \item[{\bf Note:}] In the various diagrams of commands and status + messages which follow, only the defined fields will be + shown. The bytes which must be added as padding to + bring the total message length up to 64 bytes will not + be shown. + \end{itemize} + + The following values of \sfbf{cmnd} are recognised by SinqHM: +% + {\sffamily\begin{center}\begin{tabular}{|p{40mm}cp{75mm}|} \hline + \textbf{Symbolic Name} & \textbf{Value} & \textbf{Description} \\ + \hline + SQHM{\usc}CNCT & 0x01 & Create a SinqHM-server (child) and % + open a connection to it. \\ + SQHM{\usc}CLOSE & 0x02 & Close connection to SinqHM-server. \\ + SQHM{\usc}CONFIG & 0x03 & Configure SinqHM. \\ + SQHM{\usc}DAQ & 0x04 & Functions related to data % + acquisition. \\ + SQHM{\usc}DBG & 0x05 & Set debug level. \\ + SQHM{\usc}DECONFIG & 0x06 & De-configure SinqHM. \\ + SQHM{\usc}EXIT & 0x07 & Instruct SinqHM to close down. \\ + SQHM{\usc}IDENT & 0x0e & Get SinqHM identification. \\ + SQHM{\usc}PROJECT & 0x0d & Read projected histogram data. \\ + SQHM{\usc}READ & 0x08 & Read an area of histogram memory. \\ + SQHM{\usc}SELECT & 0x09 & Select active histogram. \\ + SQHM{\usc}STATUS & 0x0a & Get SinqHM status. \\ + SQHM{\usc}WRITE & 0x0b & Pre-set an area of histogram % + memory. \\ + SQHM{\usc}ZERO & 0x0c & Zero an area of histogram memory. \\ + \hline + \end{tabular}\end{center}} +% + The various commands are detailed in the following subsections. + + The programs SINQHM{\usc}CTRL and SINQHM{\usc}CLIENT, described in + Sections~\ref{Sect-sinqhm-ctrl} and \ref{Sect-sinqhm-client}, are + utility programs which may be used to + issue most of these commands to SinqHM. +% + \newpage +% + \subsection{SQHM{\usc}CNCT} +% =========================== +% + The SQHM{\usc}CNCT command is the first step in establishing a + client/server relationship with SinqHM. It causes SinqHM-master to + create a SinqHM-server process to which one may open a connection + as a client. This command may only be sent after SinqHM has been + configured. The format of the SQHM{\usc}CNCT command is: +% + \begin{center}\begin{picture}(125,28)(0,-28) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}CNCT}} + \put(0,-21){\Midbox{max-packet-size}} + \put(0,-28){\Botbox{startup-mode}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{80mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}CNCT}{cmnd}{Command verb} + \Tabrow{max-packet-size}{u.cnct.max{\usc}pkt}{Maximum packet size + supported by client.} + \Tabrow{startup-mode}{u.cnct.strt{\usc}mode}{Startup mode of + SinqHM-server.} + \hline + \end{tabular}\end{center} + + \sfbf{max{\usc}pkt} should be set to a proposed maximum + packet size in bytes\footnote{A value of 8192 is recommended. This is + the maximum value which is to be used for the {\em len} argument in + calls to the send/recv TCP/IP functions. Although the TCP/IP protocol + hides the underlying packet nature of network communications, it has been + found that the use of much larger values for {\em len} seems to cause + problems.} for communication with the server. The value should be at least + 1024. SinqHM will respond with the actual value to be used. The + actual value will not be greater than \sfbf{max{\usc}pkt}. + + The value of \sfbf{strt{\usc}mode} is passed by SinqHM-master + to the created SinqHM-server process. It should normally be set to zero. + If it is set non-zero, the server process will suspend itself as soon as + it is started. This is intended to allow the server process to be debugged + interactively. + + In response to the SQHM{\usc}CNCT command, SinqHM-master allocates a + TCP/IP port number for a new server process, establishes the packet size + which the server should use and creates the server process. The server is + passed the value of the TCP/IP port number and the value of + \sfbf{strt{\usc}mode}. It then waits for the server to + initialise itself before returning a status response to the client. The + format of the response is shown below. Values of the + \sfbf{status} field may be: +% + {\sffamily\begin{center}\begin{tabular}{|p{40mm}p{100mm}|} \hline + KER{\usc}{\usc}SUCCESS & SinqHM-server started successfully.\\ + KER{\usc}{\usc}BAD{\usc}STATE & SinqHM has not yet been configured.\\ + KER{\usc}{\usc}BAD{\usc}CREATE & Creation of child process failed. The + cause is indicated by \textbf{sub{\usc}status}. + Possible values are: \\ + & \hspace*{5mm} -1 Spawn failed. \\ + & \hspace*{5mm} -2 No more ports available. \\ + & \hspace*{5mm} -3 The child took more than 15 seconds to \\ + & \hspace*{15mm} initialise itself. The child has been + terminated. \\ + & \hspace*{5mm} -4 The child had a start-up problem. \\ + \hline + \end{tabular}\end{center}} +% + \newpage + The format of the status response to a SQHM{\usc}CNCT command is: +% + \begin{center}\begin{picture}(125,112)(0,-112) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0, -14){\Midbox{status}} + \put(0, -21){\Midbox{sub-status}} + \put(0, -28){\Midbox{port-number}} + \put(0, -35){\Midbox{packet-size}} + \put(0, -42){\Midbox{hist-mode}} + \put(0, -49){\Midbox{number-hists}} + \put(0, -56){\Midbox{number-bins}} + \put(0, -63){\Midbox{bytes-per-bin}} + \put(0, -70){\Midbox{current-hist}} + \put(0, -77){\Midbox{max-free-block}} + \put(0, -84){\Midbox{total-bytes}} + \put(0, -91){\Midbox{low-cntr}} + \put(0, -98){\Midbox{low-bin}} + \put(0,-105){\Midbox{compress}} + \put(0,-112){\Botbox{up-time}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{80mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{status}{status}{Status code} + \Tabrow{sub-status}{sub{\usc}status}{Secondary status code} + \Tabrow{port-number}{u.cnct.port}{TCP/IP port number of SinqHM-server} + \Tabrow{packet-size}{u.cnct.pkt{\usc}size}{Client/server packet size} + \Tabrow{hist-mode}{u.cnct.hm{\usc}mode}{Histogram memory mode} + \Tabrow{number-hists}{u.cnct.n{\usc}hists}{Number of defined histograms} + \Tabrow{number-bins}{u.cnct.num{\usc}bins}{Number of bins per histogram} + \Tabrow{bytes-per-bin}{u.cnct.bytes{\usc}per{\usc}bin}{Number of bytes + per bin (1, 2 or 4)} + \Tabrow{current-hist}{u.cnct.curr{\usc}hist}{Currently selected histogram} + \Tabrow{max-free-block}{u.cnct.max{\usc}block}{Largest free memory block % + (in bytes)} + \Tabrow{total-bytes}{u.cnct.total{\usc}bytes}{Size of all defined histograms} + \Tabrow{low-cntr}{u.cnct.lo{\usc}cntr}{First defined counter} + \Tabrow{low-bin}{u.cnct.lo{\usc}bin}{Lower edge of first bin} + \Tabrow{compress}{u.cnct.compress}{Bin compression factor} + \Tabrow{up-time}{u.cnct.up{\usc}time}{SinqHM up-time in seconds} + \hline + \end{tabular}\end{center} +% + If the value of \sfbf{status} indicates success, the value of + \sfbf{port} is the + value to be used by the client in establishing its connection to + the SinqHM-server. \sfbf{pkt{\usc}size} will be the maximum + value of the {\em len} + argument which the server will use in calls to the {\em send/recv} + functions. The value will not be greater than + \sfbf{max{\usc}pkt}. The values + of \sfbf{hm{\usc}mode}, \sfbf{n{\usc}hists}, + \sfbf{num{\usc}bins}, + \sfbf{bytes{\usc}per{\usc}bin}, + \sfbf{total{\usc}bytes}, + \sfbf{lo{\usc}cntr}, \sfbf{lo{\usc}bin} and + \sfbf{compress} indicate the + configuration\footnote{Note: in TOF mode, it is possible to define a more + complex configuration than can be described in the 64 byte status + response. At present, there is no way of obtaining this detailed + information from SinqHM.} of the histogram memory (see + Sect.~\ref{Sect-sinqhm-config}). + \sfbf{curr{\usc}hist} indicates the currently selected + histogram (see Sect.~\ref{Sect-sinqhm-select}). + \sfbf{max{\usc}block} indicates + the maximum free memory block currently + available in the histogram memory. \sfbf{up{\usc}time}, which is set + whether or not \sfbf{status} indicates success, gives the time in seconds + since SinqHM-master was started. +% + \vspace*{20mm} +% + \subsection{SQHM{\usc}CLOSE} +% ============================ +% + The SQHM{\usc}CLOSE command is used to terminate communication with + one's SinqHM-server. There are no command dependent parameters and + there is {\bf no status response}. The SinqHM-server will simply tidy up, + close its TCP/IP socket and exit. + + The SQHM{\usc}CLOSE command will be ignored if issued to SinqHM-master. +% + \newpage +% + \subsection{SQHM{\usc}CONFIG} +% ============================= +% + \label{Sect-sinqhm-config} +% + The SQHM{\usc}CONFIG command is used to configure SinqHM. It informs + SinqHM-master of the required histogram memory space, the type of + detector from which data will be coming and the mode in which + histograms are to be filled. Until SinqHM has been successfully + configured, it will not establish any client/server connections. The + format of the SQHM{\usc}CONFIG command is: +% + \begin{center}\begin{picture}(125,49)(0,-49) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}CONFIG}} + \put(0,-21){\Midbox{hist-mode}} + \put(0,-28){\Midbox{}} + \put(0,-35){\Midbody{mode dependent parameters}} + \put(0,-42){\Midbody{see Sections~\ref{SubSect-transp}, + \ref{SubSect-hm-dig}, \ref{SubSect-TOF}, + \ref{SubSect-HRPT} and \ref{SubSect-PSD}}} + \put(0,-49){\Botbody{}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{75mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}CONFIG}{cmnd}{Command verb} + \Tabrow{hist-mode}{u.cnfg.mode}{Histogram memory mode} + \hline + \end{tabular}\end{center} +% + The \sfbf{mode} parameter specifies the basic operating mode + of the histogram memory. This mode must agree with the set-up of + the multi-detector interface since the format of data packets from this + interface is mode dependent. Values which may be taken by + \sfbf{mode} are: +% + {\sffamily\begin{center}\begin{tabular}{|p{37mm}cp{94mm}|} \hline + \multicolumn{3}{|l|}{Supported values of \textbf{mode}} \\ + \hline + SQHM{\usc}{\usc}TRANS & 0x1000 & Transparent mode. See + Section~\ref{SubSect-transp}. \\ + SQHM{\usc}{\usc}HM{\usc}DIG & 0x2000 & Histogram mode with + digitised read-out. See + Section~\ref{SubSect-hm-dig}. \\ + SQHM{\usc}{\usc}TOF & 0x3000 & Time-of-flight mode. See + Section~\ref{SubSect-TOF}. \\ + SQHM{\usc}{\usc}HM{\usc}PSD & 0x4000 & Histogram mode with + TriCS type position sensitive detector + (charge division read-out). See + Section~\ref{SubSect-PSD}. \\ + SQHM{\usc}{\usc}HRPT & 0x5000 & Histogram mode for HRPT type + interface. See + Section~\ref{SubSect-HRPT}. \\ + \hline + \end{tabular}\end{center}} +% + It is also possible to set modifier bits in the \sfbf{mode} parameter. + These may be used to refine the operation of the histogramming function. + The defined modifier bits are listed in the upper table on the next + page.\\[1.0ex] +% + In response to a SQHM{\usc}CONFIG command, + SinqHM-master will reserve the required buffer space for the + histograms and start the SinqHM-filler process. Once the filler + process has initialised itself, a status response is returned. + Only the \sfbf{status} and \sfbf{sub{\usc}status} + fields of the response are significant. Possible values for \sfbf{status} + in the status response are listed in the lower table on the next + page. +% + {\sffamily\begin{center}\begin{tabular}{|p{37mm}cp{94mm}|} \hline + \multicolumn{3}{|l|}{Modifier bits of \textbf{mode}} \\ + \hline + SQHM{\usc}{\usc}DEBUG & 0x01 & Can be set to facilitate interactive % + debugging of the histogram memory software. If this % + bit is set, the histogram filler process will suspend % + itself after being started to allow the use of an % + interactive debugger. \\ + SQHM{\usc}{\usc}UD & 0x02 & The \textsl{up/down} bit delivered by + the front-end electronics will be used to select + the histogram to be updated. The value of + \textbf{n{\usc}hists} must be a multiple of 2 + in this mode. This bit and the SQHM{\usc}{\usc}STROBO + bit are mutually exclusive. \\ + SQHM{\usc}{\usc}BO{\usc}MSK & 0x18 & Bin-overflow mask - use this + to mask out the \textsl{bin-overflow} bits + of \textbf{mode} as defined in the following + 3 entries. \\ + SQHM{\usc}{\usc}BO{\usc}IGN & 0x00 & Ignore bin overflows. An + overflowing bin will wrap-around to zero. \\ + SQHM{\usc}{\usc}BO{\usc}SMAX & 0x08 & Stop at maximum. If a bin + overflows, stop incrementing the bin when the maximum + count in the bin is reached. Other bins will continue + to count. \\ + SQHM{\usc}{\usc}BO{\usc}CNT & 0x10 & Count bin overflows. If a bin + overflows, the number of the overflowing bin is + added to a table where the number of overflows of + this bin are recorded. This feature is not yet + supported. \\ + SQHM{\usc}{\usc}STROBO & 0x20 & The raw data from the + fibre-optic link is expected to be + single-channel-stroboscopic-mode. The + binning-address-bits delivered + by the front-end electronics will be + used to select the histogram + which will be updated. The value of + \textbf{n{\usc}hists} must be a multiple of + 16. This bit and the SQHM{\usc}{\usc}UD + bit are mutually exclusive. + Note that a finer selection of the + histogram which is to be updated based on + the time-stamp information in the raw data is + not yet defined. \\ + SQHM{\usc}{\usc}REFLECT & 0x40 & The histogram wires will be + reflected (needed by HRPT). \\ + SQHM{\usc}{\usc}NO{\usc}STAT & 0x80 & The status info displayed by + Filler on the COM1 port will be suppressed. \\ + \hline + \end{tabular}\end{center}} +% + {\sffamily\begin{center}\begin{tabular}{|p{40mm}p{104mm}|} \hline + KER{\usc}{\usc}SUCCESS & SinqHM-filler started successfully.\\ + KER{\usc}{\usc}BAD{\usc}STATE & SinqHM has already been configured.\\ + KER{\usc}{\usc}BAD{\usc}VALUE & Invalid parameter found. \\ + KER{\usc}{\usc}BAD{\usc}ALLOC & Not enough space available for + histogram memory buffer. The maximum + available space in bytes is given by + \textbf{sub{\usc}status}. \\ + KER{\usc}{\usc}BAD{\usc}CREATE & Creation of SinqHM-filler failed. The + cause is indicated \\ + & by \textbf{sub{\usc}status}. Possible values are: \\ + & \hspace*{5mm} -1 Spawn failed. \\ + & \hspace*{5mm} -2 SinqHM-filler already active (should + not be possible). \\ + & \hspace*{5mm} -3 SinqHM-filler took more than 15 seconds + to \\ + & \hspace*{15mm} initialise itself. It has been + terminated. \\ + & \hspace*{5mm} -4 SinqHM-filler had a start-up problem. \\ + \hline + \end{tabular}\end{center}} +% + \newpage +% + \subsubsection{SQHM{\usc}{\usc}TRANS: Transparent Mode} +% ======================================================= +% + \label{SubSect-transp} +% + No histogramming is done in Transparent Mode. The raw data as read from + the fibre-optic link is buffered and transferred to the host on request. + The format of the SQHM{\usc}TRANS command is: +% + \begin{center}\begin{picture}(125,35)(0,-35) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}CONFIG}} + \put(0,-21){\Midbox{SQHM{\usc}{\usc}TRANS}} + \put(0,-28){\Midbox{buff-number}} + \put(0,-35){\Botbox{buff-size}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{68mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}CONFIG}{cmnd}{Command verb} + \Tabrow{SQHM{\usc}{\usc}TRANS}{mode}{The selected mode} + \Tabrow{buff-number}{$<$prefix$>$.n{\usc}buffs}{Number of buffers to + use.} + \Tabrow{buff-size}{$<$prefix$>$.n{\usc}bytes}{Size of each buffer in + bytes.} + \hline + \end{tabular}\end{center} +% + \sfbf{$<$prefix$>$} is + \sfbf{u.cnfg.u.trans}.\\[1.0ex] +% + The buffers are used cyclically. Their contents may be read via the + SQHM{\usc}READ command. +% + \newpage +% + \subsubsection{SQHM{\usc}{\usc}HM{\usc}DIG: Digitised Histogram Mode} +% ===================================================================== +% + \label{SubSect-hm-dig} +% + The raw data from the fibre-optic link is expected to be + \textsl{single-channel-histogram-mode}. It will be histogrammed into the + currently selected histogram (see Sect.~\ref{Sect-sinqhm-select}). If the + SQHM{\usc}{\usc}UD or SQHM{\usc}{\usc}STROBO modifier bit of + \sfbf{mode} is + set, the {\em up/down bit} or the {\em binning-address-bits} in the + fibre-optic data packets will be used to select one of a group of adjacent + histograms to be updated.\\[1.0ex] +% + The format of the SQHM{\usc}CONFIG command for Digitised Histogram Mode + is: +% + \begin{center}\begin{picture}(125,56)(0,-56) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}CONFIG}} + \put(0,-21){\Midbox{SQHM{\usc}{\usc}HM{\usc}DIG}} + \put(0,-28){\Midbox{number-hists}} + \put(0,-35){\Midbox{low-bin}} + \put(0,-42){\Midbox{number-bins}} + \put(0,-49){\Midbox{bytes-per-bin}} + \put(0,-56){\Botbox{bin-compress}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{68mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}CONFIG}{cmnd}{Command verb} + \Tabrow{SQHM{\usc}{\usc}HM{\usc}DIG}{mode}{The selected mode} + \Tabrow{number-hists}{$<$prefix$>$.n{\usc}hists}{Number of + defined histograms.} + \Tabrow{low-bin}{$<$prefix$>$.lo{\usc}bin}{Coordinate of lower + edge of first bin.} + \Tabrow{number-bins}{$<$prefix$>$.num{\usc}bins}{Number of bins + per histogram.} + \Tabrow{bytes-per-bin}{$<$prefix$>$.bytes{\usc}per{\usc}bin}{% + Number of bytes per bin (1, 2 or 4).} + \Tabrow{bin-compress}{$<$prefix$>$.compress}{Bin compression factor + (bin width).} + \hline + \end{tabular}\end{center} +% + \sfbf{$<$prefix$>$} is + \sfbf{u.cnfg.u.hm{\usc}dig}.\\[1.0ex] +% + Let $x$ be the 16-bit data field obtained from the fibre-optic event + packet. If\\[1.0ex] +% + \hspace*{\fill} + $ x < \sfbf{lo{\usc}bin} $ + \hspace*{\fill} \\[1.0ex] +% + the lower {\em out-of-range} counter for the histogram will be + incremented. If\\[1.0ex] +% + \hspace*{\fill} + $ x \geq (\sfbf{lo{\usc}bin} + \sfbf{num{\usc}bins} \times + \sfbf{compress}) $ + \hspace*{\fill} \\[1.0ex] +% + the upper {\em out-of-range} counter for the histogram will be + incremented. Otherwise, the index of the bin to be incremented + is:\\[1.0ex] +% + \hspace*{\fill} + $ (x - \sfbf{lo{\usc}bin})/\sfbf{compress} $ + \hspace*{\fill} \\[1.0ex] +% + In most cases, \sfbf{lo{\usc}bin} will be 0 and + \sfbf{compress} will be 1. +% + \newpage +% + \subsubsection{SQHM{\usc}{\usc}TOF: Time-of-Flight Mode} +% ======================================================== +% + \label{SubSect-TOF} +% + Time-of-flight (TOF) histograms are intrinsically 2-dimensional. One + dimension is the time after the start signal at which the neutron was + detected and the other dimension is the position (or number) of the + detector which detected the neutron. There are two special + requirements for TOF spectra which + complicate the definition of the configuration command. These are: + \begin{itemize} + \item the time-span of the bins of the histogram along the time axis may + not be constant. It may, for example, be preferable to define bin + boundaries so that the bin width is constant after the histograms have + been converted to energy space. + \item it may be necessary to define different time-binning for various + sections of the bank of detectors. + \end{itemize} +% + For this reason, two special data structures have been defined for use in + the SQHM{\usc}{\usc}TOF mode configuration command. These are the {\em + edge-array} and {\em counter-bank} data structures.\\[1.5ex] +% + \hspace*{-3mm}\textbf{The {\em edge-array} Structure} + + \noindent The {\em edge-array} data structure is \sfbf{struct + tof{\usc}edge{\usc}arr}. It is used to specify the bin coordinates of a + histogram. Its format is: +% + \begin{center}\begin{picture}(125,35)(0,-35) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{number-bins}} + \put(0,-14){\Midbox{flag}} + \put(0,-21){\Midbox{}} + \put(0,-28){\Midbody{edges}} + \put(0,-35){\Botbody{}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{68mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} \hline + \Tabrow{number-bins}{n{\usc}bins}{Number of bins per counter.} + \Tabrow{flag}{flag}{If set to 1, variable bin width.} + \Tabrow{edges}{edges[]}{Array of lower bin edges.} + \hline + \end{tabular}\end{center} +% + If the least significant bit of \sfbf{flag} is zero, the associated + histogram has a fixed bin width + along the time axis. In this case, \sfbf{edges[]} has 2 elements giving + the lower edge of the first two bins. From this, the lower edges of the + complete time axis of the histogram can be computed. \\[1.0ex] +% + If the least significant bit of \sfbf{flag} is non-zero, the associated + histogram has a variable bin + width. In this case, \sfbf{edges[]} must have (\sfbf{n{\usc}bins} + 1) + elements giving the lower edges of all the bins. The last element should + be 1 greater than the upper edge of the last bin. \\[1.5ex] +% + \hspace*{-3mm}\textbf{The {\em counter-bank} Structure} + + \noindent The {\em counter-bank} data structure is \sfbf{struct + tof{\usc}bank}. It is used to specify a group of TOF counters, all of + which have the same histogram binning along the time axis. Its format is: +% + \begin{center}\begin{picture}(125,28)(0,-28) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{first-cntr}} + \put(0,-14){\Midbox{number-cntrs}} + \put(0,-21){\Midbox{edge-index}} + \put(0,-28){\Botbox{bytes-per-bin}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{68mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} \hline + \Tabrow{first-cntr}{first}{Number of first counter in bank.} + \Tabrow{number-cntrs}{n{\usc}cntrs}{Number of counters in bank.} + \Tabrow{edge-index}{edge{\usc}indx}{Index of corresponding edge-array.} + \Tabrow{bytes-per-bin}{bytes{\usc}per{\usc}bin}{Number of bytes per bin + (1, 2 or 4).} + \hline + \end{tabular}\end{center} +% + Having defined the {\em edge-array} and {\em counter-bank} data + structures, it is now possible to define the SQHM{\usc}{\usc}TOF mode + configuration command as follows: +% + \begin{center}\begin{picture}(125,84)(0,-84) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}CONFIG}} + \put(0,-21){\Midbox{SQHM{\usc}{\usc}TOF}} + \put(0,-28){\Midbox{extra-bytes}} + \put(0,-35){\Midwordbox{n-banks}{n-edges}} + \put(0,-42){\Midbox{preset-delay}} + \put(0,-49){\Midbox{}} + \put(0,-56){\Midbodydashed{edge[0] $\ldots$ edge[n-edges]}} + \put(0,-63){\Botbody{}} + \put(0,-70){\Midbox{}} + \put(0,-77){\Midbodydashed{bank[0] $\ldots$ bank[n-banks]}} + \put(0,-84){\Botbody{}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{68mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}CONFIG}{cmnd}{Command verb} + \Tabrow{SQHM{\usc}{\usc}TOF}{mode}{The selected mode} + \Tabrow{extra-bytes}{$<$prefix$>$.n{\usc}extra{\usc}bytes}{Number of + extra bytes to read.} + \Tabrow{n-edges}{$<$prefix$>$.n{\usc}edges}{Number of edge arrays + following.} + \Tabrow{n-banks}{$<$prefix$>$.n{\usc}banks}{Number of counter banks + following.} + \Tabrow{preset-delay}{$<$prefix$>$.preset{\usc}delay}{Time delay for + sending to multi-detector interface.} + \Tabrow{edge[i]}{$<$prefix$>$.edge{\usc}0}{An edge array.} + \Tabrow{bank[j]}{$<$prefix$>$.bank{\usc}0}{A counter bank.} + \hline + \end{tabular}\end{center} +% + \sfbf{$<$prefix$>$} is + \sfbf{u.cnfg.u.tof}. \\[1.0ex] +% + If the data required for the edge-arrays and counter-banks exceeds the + normal 64-byte limit for a message to SinqHM, the parameter + \sfbf{n{\usc}extra{\usc}bytes} must indicate the number of extra bytes + which must be read by SinqHM to complete the message. For the case of + fixed bin width histograms and a single counter-bank, + \sfbf{n{\usc}extra{\usc}bytes} will be zero. The + \sfbf{preset{\usc}delay} is sent to the multi-detector interface via + the COM2 port of the MVME-1603 PowerPC module. See + Section~\ref{Sect-mdi-comm} for details.\\[1.0ex] +% + Note that, if there is more than one edge-array or if the + edge-array defines bins with a variable width, the location of the + counter-banks in the command must be computed at run time. +% + \vspace*{10mm} +% + \subsubsection{SQHM{\usc}{\usc}HRPT: HRPT Detector Mode} +% ============================================================================ +% + \label{SubSect-HRPT} +% + The raw data from the fibre-optic link is expected to be + \textsl{3-channel-histogram-mode} as defined for the CERCA interface for + the HRPT detector. It will be histogrammed into the + currently selected histogram (see Sect.~\ref{Sect-sinqhm-select}). If the + SQHM{\usc}{\usc}UD or SQHM{\usc}{\usc}STROBO modifier bit of + \sfbf{mode} is + set, the {\em up/down bit} or the {\em binning-address-bits} in the + fibre-optic data packets will be used to select one of a group of adjacent + histograms to be updated.\\[1.0ex] +% + The format of the SQHM{\usc}CONFIG command for HRPT mode is the same + as for Digitised Histogram Mode (see Sect.~\ref{SubSect-hm-dig}) + except for the \sfbf{mode} field, which must naturally be set to + \sfbf{SQHM{\usc}{\usc}HRPT} rather than + \sfbf{SQHM{\usc}{\usc}HM{\usc}DIG}. +% + \vspace*{10mm} +% + \subsubsection{SQHM{\usc}{\usc}HM{\usc}PSD: Position Sensitive Detector Mode} +% ============================================================================ +% + \label{SubSect-PSD} +% + Position Sensitive Detector operation of the histogram memory has still + to be defined. +% + \newpage +% + \subsection{SQHM{\usc}DAQ} +% ========================== +% + The SQHM{\usc}DAQ command is used for operations related to the + enabling and inhibiting of data acquisition by SinqHM. As + mentioned in Section~\ref{Sect-hardware}, + the method of data acquisition control + used in the SinqHM histogram memory is to apply a signal to the + inhibit input of the multi-detector interface to disable data + acquisition by the histogram memory. In this situation, the + SQHM{\usc}DAQ command is not necessary. It has been provided to allow + the possibility of extending SinqHM for use in other types of + experiment, such as \musr, where the data acquisition control + philosophy is somewhat different. + + In order to understand the details of the command, it is first + necessary to describe the way in which the command is implemented. + + SinqHM maintains a mask, {\em Dsbl{\usc}Mask}, in a region of memory + which is + accessible to SinqHM-filler and to the SinqHM-servers. Both + SinqHM-filler and the SinqHM-servers are each associated with a + particular bit in {\em Dsbl{\usc}Mask}. If the mask is non-zero, data + acquisition will be inhibited. + + When SinqHM-filler is first started in response to a SQHM{\usc}CONFIG + command, it flushes the FIFO from the fibre-optic link and clears + {\em Dsbl{\usc}Mask}. Data acquisition is therefore enabled. + However, since + the inhibit input to the multi-detector interface is presumably + set at this point and remains so until the user starts a data + acquisition run via the EL737 neutron counter, any data which + SinqHM-filler reads from the fibre-optic link will be discarded. + + Whenever a SinqHM-server is started in response to a SQHM{\usc}CNCT + command, its associated bit is cleared. Whenever a server exits, + it also ensures that its bit is clear. The SQHM{\usc}DAQ command allows + a user to manipulate the bits in {\em Dsbl{\usc}Mask} and hence to control + whether SinqHM-filler will read data from the fibre-optic link or + not. Because of the high speed of the PowerPC processor and the + way in which SinqHM-filler has been implemented, the test to see + if {\em Dsbl{\usc}Mask} is set or not adds only about 30 nsec + to the read-out loop of the histogram memory. + + The format of the SQHM{\usc}DAQ command, which may only be issued once + SinqHM has been successfully configured, is: +% + \begin{center}\begin{picture}(125,21)(0,-21) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}DAQ}} + \put(0,-21){\Botbox{modifier}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{75mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}DAQ}{cmnd}{Command verb} + \Tabrow{modifier}{u.daq.sub{\usc}cmnd}{Command modifier (see below)} + \hline + \end{tabular}\end{center} +% + The values which may be taken by \sfbf{sub{\usc}cmnd} are + given in the following table. + If the commands DAQ{\usc}{\usc}CLR and DAQ{\usc}{\usc}INH are issued as + one-off commands to SinqHM-master, they behave as though DAQ{\usc}{\usc}GO + and DAQ{\usc}{\usc}STOP commands had been issued. +% + {\sffamily\begin{center}\begin{tabular}{|p{37mm}cp{94mm}|} \hline + \multicolumn{3}{|l|}{Supported values of \textbf{sub{\usc}cmnd}} \\ + \hline + DAQ{\usc}{\usc}CLR & 0x0001 & Clear the client's bit in + \textsl{Dsbl{\usc}Mask}. If, as a result, the + mask becomes zero, data acquisition will be + enabled. \\ + DAQ{\usc}{\usc}GO & 0x0002 & Instruct SinqHM-filler to clear its bit + in \textsl{Dsbl{\usc}Mask}. \\ + DAQ{\usc}{\usc}INH & 0x0003 & Set the client's bit in + \textsl{Dsbl{\usc}Mask}. This is guaranteed + to disable data acquisition. \\ + DAQ{\usc}{\usc}STOP & 0x0004 & Instruct SinqHM-filler to set its bit + in \textsl{Dsbl{\usc}Mask}. \\ + DAQ{\usc}{\usc}TST & 0x0005 & Read the state of + \textsl{Dsbl{\usc}Mask}. \\ + \hline + \end{tabular}\end{center}} + + The format of the status response to a SQHM{\usc}DAQ command is: +% + \begin{center}\begin{picture}(125,35)(0,-35) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{status}} + \put(0,-21){\Midbox{sub-status}} + \put(0,-28){\Midwordbox{daq-state-was}{daq-state-now}} + \put(0,-35){\Botwordbox{server-mask}{filler-mask}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{85mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{status}{status}{Status code} + \Tabrow{sub-status}{sub{\usc}status}{Secondary status code} + \Tabrow{daq-state-now}{u.daq.daq{\usc}now}{New (or current) data + acquisition status (= value of \textsl{Dsbl{\usc}Mask})} + \Tabrow{daq-state-was}{u.daq.daq{\usc}was}{Previous data acquisition + status (= old value of \textsl{Dsbl{\usc}Mask}).} + \Tabrow{filler-mask}{u.daq.filler{\usc}mask}{Mask indicating which bit + in \textbf{daq{\usc}now} corresponds to + SinqHM-filler.} + \Tabrow{server-mask}{u.daq.server{\usc}mask}{Mask indicating which bit + in \textbf{daq{\usc}now} corresponds to the + client which issued the SQHM{\usc}DAQ command.} + \hline + \end{tabular}\end{center} +% + The only values for \sfbf{status} should be + KER{\usc}{\usc}SUCCESS and + KER{\usc}{\usc}BAD{\usc}VALUE, the latter indicating that + \sfbf{sub{\usc}cmnd} is invalid. + Any other value which might occur indicates a software problem, + probably related to accessing the semaphore associated with + {\em Dsbl{\usc}Mask}. + + \noindent If \sfbf{daq{\usc}now} is non-zero, data acquisition by + SinqHM is disabled. + Each non-zero bit in \sfbf{daq{\usc}now} corresponds to a + process in SinqHM + which is inhibiting data acquisition. \sfbf{filler{\usc}mask} + indicates the + bit which is associated with SinqHM-filler. + \sfbf{client{\usc}mask} indicates + the bit which is associated with the client which issued the + SQHM{\usc}DAQ command. + + \noindent \sfbf{daq{\usc}was} is a copy of {\em Dsbl{\usc}Mask} prior + to the execution of the current command. +% + \newpage +% +% + \subsection{SQHM{\usc}DBG} +% ========================== +% + The SQHM{\usc}DBG command is used to enable the display of diagnostic + messages from SinqHM. A mask of 4 bits may be set to select various + diagnostic messages. The diagnostic messages are directed to the COM1 + console port of the PowerPC module. The format of the command is: +% + \begin{center}\begin{picture}(125,21)(0,-21) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}DBG}} + \put(0,-21){\Botbox{debug-mask}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{80mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}DBG}{cmnd}{Command verb} + \Tabrow{debug-mask}{u.dgb.mask}{Mask of bits selecting various debug + print switches. The least significant + 4 bits are relevant.} + \hline + \end{tabular}\end{center} +% + Setting \sfbf{mask} to a value of 15 will enable all diagnostic messages. + + \noindent The response to the SQHM{\usc}DBG command will have + \sfbf{status} set to KER{\usc}{\usc}SUCCESS. +% + \newpage +% + \subsection{SQHM{\usc}DECONFIG} +% =============================== +% + The SQHM{\usc}DECONFIG command is used to de-configure SinqHM (usually + in preparation for a new SQHM{\usc}CONFIG command). The + format of the command is: +% + \begin{center}\begin{picture}(125,21)(0,-21) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}DECONFIG}} + \put(0,-21){\Botbox{harshness}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{70mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}DECONFIG}{cmnd}{Command verb} + \Tabrow{harshness}{u.decnfg.sub{\usc}code}{Command modifier (see below)} + \hline + \end{tabular}\end{center} +% + SinqHM-master will check to see if there are any active + SinqHM-server (child) processes active. If there are no active + children, the SinqHM-filler process will be terminated and SinqHM + returns to the de-configured state. + + \noindent If there are active children, however, the + \sfbf{sub{\usc}code} (harshness) + field is used. If it is zero, then the condition is considered to + be an error. + + \noindent If it is non-zero, then SinqHM-master will be more ruthless. All + its active children (including SinqHM-filler) will be terminated + and it will then return to the de-configured state. + + \noindent Possible values for \sfbf{status} in the status response to the + SQHM{\usc}DECONFIG command are: +% + {\sffamily\begin{center}\begin{tabular}{|p{40mm}p{110mm}|} \hline + KER{\usc}{\usc}SUCCESS & SinqHM has been successfully + de-configured.\\ + KER{\usc}{\usc}BAD{\usc}STATE & Either: \\ + & \hspace*{5mm} - there are active clients and + \textbf{sub{\usc}code} was zero or \\ + & \hspace*{5mm} - there were problems terminating + the children. \\ + \hline + \end{tabular}\end{center}} +% + \vspace*{10mm} +% + \subsection{SQHM{\usc}EXIT} +% =========================== +% + The SQHM{\usc}EXIT command is used to terminate SinqHM-master and all + its children. It is only recognised as a one-off command to + SinqHM-master. It will not be recognised by a SinqHM-server. + + It is normally only of interest in debugging situations since + manual intervention on the histogram memory module is required + afterwards to start up SinqHM-master again. The status response is + the same as for the SQHM{\usc}DECONFIG command. An error status will + only be returned if SinqHM-master has trouble terminating its + children. It will, in any case, proceed to exit. +% + \newpage +% + \subsection{SQHM{\usc}IDENT} +% ============================ +% + The SQHM{\usc}IDENT command is used for obtaining information about + the revision status of the SinqHM software running in the histogram + memory. There are no command dependent parameters. The format of the + status response is: +% + \begin{center}\begin{picture}(125,77)(10,-77) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topwbox{35}{bigend}} + \put(0,-14){\Midwbox{35}{status}} + \put(0,-21){\Midwbox{35}{sub{\usc}status}} + \put(0,-28){\Midwbox{35}{u.ident.n{\usc}extra{\usc}bytes}} + \put(0,-35){\Midwbox{35}{u.ident.up{\usc}time}} + \put(0,-42){\Midwwordbox{35}% + {u.ident.offset{\usc}vxWorks{\usc}date}% + {u.ident.offset{\usc}vxWorks{\usc}ident}} + \put(0,-49){\Midwwordbox{35}% + {u.ident.offset{\usc}def{\usc}ident}% + {u.ident.offset{\usc}instr}} + \put(0,-56){\Midwwordbox{35}% + {u.ident.offset{\usc}sinqhm{\usc}main{\usc}date}% + {u.ident.offset{\usc}sinqhm{\usc}main{\usc}ident}} + \put(0,-63){\Midwwordbox{35}% + {u.ident.offset{\usc}sinqhm{\usc}server{\usc}date}% + {u.ident.offset{\usc}sinqhm{\usc}server{\usc}ident}} + \put(0,-70){\Midwwordbox{35}% + {u.ident.offset{\usc}sinqhm{\usc}filler{\usc}date}% + {u.ident.offset{\usc}sinqhm{\usc}filler{\usc}ident}} + \put(0,-77){\Botwwordbox{35}% + {u.ident.offset{\usc}sinqhm{\usc}routines{\usc}date}% + {u.ident.offset{\usc}sinqhm{\usc}routines{\usc}ident}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|lp{90mm}|} \hline + \sfbf{Symbol Name} & \sfbf{Description} \\ \hline + \sfbf{bigend} & \textsf{% + See Section~\ref{Sect-sinqhm-comm}} \\ + \sfbf{status} & \textsf{% + Status code} \\ + \sfbf{sub{\usc}status} & \textsf{% + Secondary status code} \\ + \sfbf{n{\usc}extra{\usc}bytes} & \textsf{% + Number of extra bytes to receive.} \\ + \sfbf{up{\usc}time} & \textsf{% + SinqHM up-time in seconds} \\ + \sfbf{offset{\usc}vxWorks{\usc}ident} & \textsf{% + Revision level of the vxWorks system.} \\ + \sfbf{offset{\usc}vxWorks{\usc}date} & \textsf{% + Date on which the vxWorks system was created.} \\ + \sfbf{offset{\usc}instr} & \textsf{% + Instrument for which SinqHM was compiled.} \\ + \sfbf{offset{\usc}def{\usc}ident} & \textsf{% + Revision level of SinqHM{\usc}def.h} \\ + \sfbf{offset{\usc}sinqhm{\usc}main{\usc}ident} & \textsf{% + Revision level of SinqHM{\usc}srv{\usc}main.c} \\ + \sfbf{offset{\usc}sinqhm{\usc}main{\usc}date} & \textsf{% + Date on which SinqHM{\usc}srv{\usc}main.c was compiled.} \\ + \sfbf{offset{\usc}sinqhm{\usc}server{\usc}ident} & \textsf{% + Revision level of SinqHM{\usc}srv{\usc}server.c} \\ + \sfbf{offset{\usc}sinqhm{\usc}server{\usc}date} & \textsf{% + Date on which SinqHM{\usc}srv{\usc}server.c was compiled.} \\ + \sfbf{offset{\usc}sinqhm{\usc}filler{\usc}ident} & \textsf{% + Revision level of SinqHM{\usc}srv{\usc}filler.c} \\ + \sfbf{offset{\usc}sinqhm{\usc}filler{\usc}date} & \textsf{% + Date on which SinqHM{\usc}srv{\usc}filler.c was compiled.} \\ + \sfbf{offset{\usc}sinqhm{\usc}routines{\usc}ident} & \textsf{% + Revision level of SinqHM{\usc}srv{\usc}routines.c} \\ + \sfbf{offset{\usc}sinqhm{\usc}routines{\usc}date} & \textsf{% + Date on which SinqHM{\usc}srv{\usc}routines.c was compiled.} \\ + \hline + \end{tabular}\end{center} +% + Possible values for \sfbf{status} in the status response to the + SQHM{\usc}IDENT command are KER{\usc}{\usc}SUCCESS, indicating success, + and KER{\usc}{\usc}BAD{\usc}ALLOC, indicating that Sinq\-HM was unable + to reserve buffer space for composing the revision status response. + If \sfbf{status} indicates success, the status response is followed + by \sfbf{n{\usc}extra{\usc}bytes} of data giving the requested revision + status of SinqHM. This extra block of data must be read by the client + before further commands are sent to SinqHM. The various {\em offset} items + in the status response specify byte offsets from the start of this extra + block to null-terminated strings. +% + \newpage +% + \subsection{SQHM{\usc}PROJECT} +% ============================== +% + The SQHM{\usc}PROJECT command is used for projecting a rectangular + region of two-dimensional histogram data onto the x or y axis + and reading it out. It is intended to be used, for example, for adding + together a number of TOF histograms in order to obtain a fast, rough + status display from the histogram memory of large histogram arrays + which would take too long to read out otherwise. + + \noindent The command may also be used to obtain a projection within a + one-dimensional histogram. This is intended for detectors such as SANS + which are physically two-dimensional but where the electronics presents + the data to the histogram memory in a one-dimensional form. It may be + useful in such cases to be able to generate an x- or y-projection of + the data in the histogram memory rather than having to transfer the + complete histogram data over the network. + + \noindent The format of the command is: +% + \begin{center}\begin{picture}(125,63)(0,-63) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{bigend}} + \put(0,-14){\Midbox{cmnd = SQHM{\usc}PROJECT}} + \put(0,-21){\Midbox{u.project.sub{\usc}code}} + \put(0,-28){\Midbox{u.project.x{\usc}lo}} + \put(0,-35){\Midbox{u.project.nx}} + \put(0,-42){\Midbox{u.project.y{\usc}lo}} + \put(0,-49){\Midbox{u.project.ny}} + \put(0,-56){\Midbox{u.project.xdim}} + \put(0,-63){\Botbox{u.project.nhist}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|lp{95mm}|} \hline + \sfbf{Symbol Name} & \sfbf{Description} \\ \hline + % + \sfbf{bigend} & \textsf{% + See Section~\ref{Sect-sinqhm-comm}} \\ + \sfbf{cmnd} & \textsf{% + Command verb = SQHM{\usc}PROJECT} \\ + \sfbf{sub{\usc}code} & \textsf{% + Sub-code} \\ + \sfbf{x{\usc}lo} & \textsf{% + Number of first bin in x-direction.} \\ + \sfbf{nx} & \textsf{% + Number of bins in x-direction.} \\ + \sfbf{y{\usc}lo} & \textsf{% + Number of first bin in y-direction.} \\ + \sfbf{ny} & \textsf{% + Number of bins in y-direction.} \\ + \sfbf{xdim} & \textsf{% + If PROJECT{\usc}{\usc}1{\usc}DIM is set, the histogram dimension + in x-direction.} \\ + \sfbf{nhist} & \textsf{% + If PROJECT{\usc}{\usc}1{\usc}DIM is set, the number of the histogram + to be projected.} \\ + \hline + \end{tabular}\end{center} +% + The following bits are defined in \sfbf{sub{\usc}code}: +% + {\sffamily\begin{center}\begin{tabular}{|p{37mm}cp{75mm}|} \hline + PROJECT{\usc}{\usc}ON{\usc}Y & 0x0001 & Project onto y-axis. \\ + PROJECT{\usc}{\usc}1{\usc}DIM & 0x0002 & Make projection of a + 1-dim histogram. \\ + \hline + \end{tabular}\end{center}} +% + \noindent The interpretation and default values for the various parameters + depend on the configured mode of the histogram memory and the settings + of bits in \sfbf{sub{\usc}code}. The following description is limited to + the known applications of the SQHM{\usc}PROJECT command. Other + combinations may also work but may not be physically meaningful. + + \subsubsection{SQHM{\usc}{\usc}TOF Mode and PROJECT{\usc}{\usc}1{\usc}DIM + = 0} +% + In TOF mode, it is expected that the SQHM{\usc}PROJECT command will be + used to combine TOF spectra from adjacent counters. + + \noindent In this case, + \sfbf{y{\usc}lo} specifies the number of the first counter and + \sfbf{ny} specifies the number of adjacent counters whose spectra are + to be combined. The parameters \sfbf{x{\usc}lo} and \sfbf{nx} specify + the range of bins in each spectrum which is to be combined. + + \noindent An error + will be reported if all counters in the specified range do not have the + same edge-array (see Section~\ref{SubSect-TOF}). + + \subsubsection{SQHM{\usc}{\usc}HM{\usc}DIG or SQHM{\usc}{\usc}HRPT Mode + and \\ PROJECT{\usc}{\usc}1{\usc}DIM = 0} +% + In SQHM{\usc}{\usc}HM{\usc}DIG and SQHM{\usc}{\usc}HRPT modes, it is + possible for multiple histograms to be defined, e.g. for stroboscopic + type measurements. The SQHM{\usc}PROJECT command may be used for + combining a range of these histograms by setting the + PROJECT{\usc}{\usc}1{\usc}DIM bit to zero. + + \noindent In this case, + \sfbf{y{\usc}lo} specifies the number of the first histogram and + \sfbf{ny} specifies the number of adjacent histograms which are to be + combined. The parameters \sfbf{x{\usc}lo} and \sfbf{nx} specify + the range of bins in each histogram which is to be combined. + + \subsubsection{SQHM{\usc}{\usc}HM{\usc}DIG or SQHM{\usc}{\usc}HRPT Mode + and \\ PROJECT{\usc}{\usc}1{\usc}DIM = 1} +% + In SQHM{\usc}{\usc}HM{\usc}DIG and SQHM{\usc}{\usc}HRPT modes, it is + possible for SinqHM to consider a histogram to be one-dimensional whereas + it would be more natural for it to be considered as a two-dimensional + histogram. + A typical example is the SANS detector at SINQ which is a 128~$\times$~128 + x-y detector. This appears to the histogram memory as a 16k + one-dimensional histogram since the 7-bits of x and 7-bits of y + information from + the detector are combined into a 14-bit word before being presented to it. + In this case, the PROJECT{\usc}{\usc}1{\usc}DIM bit may be set to force + SinqHM to consider the histogram as two-dimensional. + + \noindent The \sfbf{x{\usc}lo}, \sfbf{nx}, \sfbf{y{\usc}lo} and \sfbf{ny} + arguments define the rectangle of interest. \sfbf{xdim} + provides SinqHM with the size of the histogram in the x + dimension\footnote{Histograms are assumed to be stored so that bins in + the x-direction are adjacent.}. \sfbf{xdim} must be an exact divisor + of the number of bins per histogram. \sfbf{nhist} is used to select + which of the defined histograms is to be projected. + + \noindent PROJECT{\usc}{\usc}ON{\usc}Y bit may be set to request that + the histogram be projected onto the y-axis. In this case, \sfbf{ny} + rather than \sfbf{nx} bins of data will be returned. + + \noindent Having checked the validity of the parameters, SinqHM tries to + reserve sufficient buffer space to hold the projected histogram + contents. If this succeeds, which it usually will since it is usually only + necessary to reserve a relatively small amount of memory, + data acquisition is inhibited, the projected histogram data is computed, + data acquisition is re-enabled + and the status response plus data are sent to the client.\\[1.0ex] +% + \noindent If buffer space is not available, an error status is returned + to the client.\\[1.0ex] +% + \noindent The format of the status response is: +% + \begin{center}\begin{picture}(125,49)(0,-49) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{bigend}} + \put(0,-14){\Midbox{status}} + \put(0,-21){\Midbox{sub{\usc}status}} + \put(0,-28){\Midbox{u.project.n{\usc}bins}} + \put(0,-35){\Midbox{u.project.bytes{\usc}per{\usc}bin = 4}} + \put(0,-42){\Midbox{u.project.cnts{\usc}lo}} + \put(0,-49){\Botbox{u.project.cnts{\usc}hi}} + } + \end{picture}\end{center} +% + If the value of \sfbf{status} is KER{\usc}{\usc}SUCCESS, the + status response is + followed by + (\sfbf{n{\usc}bins} $\times$ 4) bytes + of histogram data which must + be received before any other commands are issued. \sfbf{n{\usc}bins} + will be either \sfbf{nx} or \sfbf{ny} depending on the setting of + PROJECT{\usc}{\usc}ON{\usc}Y. The only other + possible values of \sfbf{status} should be + KER{\usc}{\usc}BAD{\usc}VALUE, which indicates + that a command parameter was invalid and KER{\usc}{\usc}BAD{\usc}ALLOC, + which indicates that SinqHM was unable to reserve buffer space for + projecting the histogram data. Any other value of + \sfbf{status} + indicates a software problem in the SinqHM package.\\[1.0ex] +% + \sfbf{cnts{\usc}lo} and \sfbf{cnts{\usc}hi} are the lower and + upper {\em out-of-range} counters for the projected histogram. They count + events which are either below or above the range of the histogram bins. + The values will be the sum of the counters for the projected histograms. +% + \newpage +% + \subsection{SQHM{\usc}READ} +% =========================== +% + The SQHM{\usc}READ command is used for reading data from the histogram + memory. It may only be issued once SinqHM has been successfully + configured. The format of the command is: + + \begin{center}\begin{picture}(125,35)(0,-35) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}READ}} + \put(0,-21){\Midbox{hist-number}} + \put(0,-28){\Midbox{first-bin}} + \put(0,-35){\Botbox{number-bins}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{75mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}READ}{cmnd}{Command verb} + \Tabrow{hist-number}{u.read.hist{\usc}no}{Histogram number (see below).} + \Tabrow{first-bin}{u.read.first{\usc}bin}{Number of first bin to be + read.} + \Tabrow{number-bins}{u.read.n{\usc}bins}{Number of bins to read.} + \hline + \end{tabular}\end{center} +% + In SQHM{\usc}{\usc}HM{\usc}DIG or SQHM{\usc}{\usc}HRPT mode, + \sfbf{hist{\usc}no} specifies the + number of the histogram which is to be read or -1. If \sfbf{hist{\usc}no} + is -1, then \sfbf{first{\usc}bin} and \sfbf{n{\usc}bins} specify a portion + of the total histogram buffer considered as a single histogram of size + (\sfbf{n{\usc}hists} $\times$ \sfbf{num{\usc}bins}) bins. Otherwise, + \sfbf{first{\usc}bin} and \sfbf{n{\usc}bins} specify a portion of the + histogram to be read. If + \sfbf{hist{\usc}no}~=~% + \sfbf{first{\usc}bin}~=~% + \sfbf{n{\usc}bins}~=~-1 + the complete histogram memory buffer will be read. + + \noindent In SQHM{\usc}{\usc}TOF mode, \sfbf{hist{\usc}no} is assumed to + specify a counter number or -1. If \sfbf{hist{\usc}no} is -1, then + \sfbf{first{\usc}bin} and \sfbf{n{\usc}bins} are used as in + SQHM{\usc}{\usc}HM{\usc}DIG mode. Otherwise, \sfbf{first{\usc}bin} and + \sfbf{n{\usc}bins} select a portion of the time histogram of the + specified counter which is to be read. + + \noindent Having checked the validity of the parameters, SinqHM tries to + reserve sufficient buffer space for making a copy of the histogram + contents. If this succeeds, data acquisition is inhibited, a copy + of the histogram contents is made, data acquisition is re-enabled + and the status response plus data are sent to the client. If + buffer space is not available for making a copy of the histogram + contents, data acquisition will not be inhibited during the + transmission of data to the client. This is because the + transmission may be quite long and could therefore cause the loss + of data. The data will therefore be slightly skewed. + + \noindent The format of the status response is given in the diagram below. + If the value of \sfbf{status} is KER{\usc}{\usc}SUCCESS, the + status response is + followed by + (\sfbf{n{\usc}bins} $\times$ + \sfbf{bytes{\usc}per{\usc}bin}) bytes + of histogram data which must + be received before any other commands are issued. The only other + possible value of \sfbf{status} should be + KER{\usc}{\usc}BAD{\usc}VALUE which indicates + that a command parameter was invalid. Any other value of + \sfbf{status} + indicates a software problem in the SinqHM package. +% + \begin{center}\begin{picture}(125,56)(0,-56) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{status}} + \put(0,-21){\Midbox{sub-status}} + \put(0,-28){\Midbox{first-bin (\textbf{u.read.first{\usc}bin})}} + \put(0,-35){\Midbox{number-bins (\textbf{u.read.n{\usc}bins})}} + \put(0,-42){\Midbox{bytes-per-bin + (\textbf{u.read.bytes{\usc}per{\usc}bin})}} + \put(0,-49){\Midbox{low-cnts (\textbf{u.read.cnts{\usc}lo})}} + \put(0,-56){\Botbox{high-cnts (\textbf{u.read.cnts{\usc}hi})}} + } + \end{picture}\end{center} + + \noindent \sfbf{cnts{\usc}lo} and \sfbf{cnts{\usc}hi} are the lower and + upper {\em out-of-range} counters for the selected histogram. They count + events which are either below or above the range of the histogram bins. If + more than one histogram is defined, there are 2 such counters defined for + each histogram. If \sfbf{hist{\usc}no} was specified as -1, the values + will be the sum of the counters for all defined histograms. +% + \vspace*{20mm} +% + \subsection{SQHM{\usc}SELECT} +% ============================= +% + \label{Sect-sinqhm-select} +% + The format of the SQHM{\usc}SELECT command, which may only be issued + once SinqHM has been successfully configured, is: +% + \begin{center}\begin{picture}(125,21)(0,-21) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}SELECT}} + \put(0,-21){\Botbox{hist-number}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{75mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}SELECT}{cmnd}{Command verb} + \Tabrow{hist-number}{u.select.hist{\usc}no}{Histogram number to be + selected} + \hline + \end{tabular}\end{center} +% + When SinqHM is configured, the user may specify that space be + reserved for multiple histograms. If so, the histogram or + group\footnote{If the SQHM{\usc}UD mode modifier was specified, + \sfbf{hist{\usc}no} must be a multiple of 2 and selects a + pair of histograms which will be active. If the SQHM{\usc}STROBO mode + modifier was specified, \sfbf{hist{\usc}no} must be a multiple + of 16.} of histograms which is currently active, i.e. + which will be updated as data are read from the fibre-optic link, can be + selected using the SQHM{\usc}SELECT command. + + There are no command-specific fields in the status response from + a SQHM{\usc}SELECT command. A value of KER{\usc}{\usc}BAD{\usc}VALUE for + \sfbf{status} + indicates that \sfbf{hist{\usc}no} is illegal. +% + \newpage +% + \subsection{SQHM{\usc}STATUS} +% ============================= +% + The SQHM{\usc}STATUS command is used to obtain the status of SinqHM. + There are no command dependent + parameters. The format of the status response is: +% + \begin{center}\begin{picture}(125,105)(0,-105) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{status}} + \put(0,-21){\Midbox{sub-status}} + \put(0,-28){\Midbox{config-state}} + \put(0,-35){\Midwordbox{current-hist}{number-hists}} + \put(0,-42){\Midbox{bins-per-hist}} + \put(0,-49){\Midbox{max-num-hists}} + \put(0,-56){\Midbox{max-num-bins}} + \put(0,-63){\Midbytebox{bin-compress}{bytes-per-bin}% + {active-servers}{max-servers}} + \put(0,-70){\Midwordbox{filler-mask}{daq-state-now}} + \put(0,-77){\Midbox{max-free-block}} + \put(0,-84){\Midwordbox{flags}{tsi-status}} + \put(0,-91){\Midbox{dead-time/delay-to-start}} + \put(0,-98){\Midbox{number-bad-events}} + \put(0,-105){\Botbox{up-time}} + } + \end{picture}\end{center} +% + All of these fields occur in the description of other commands. + The following list therefore only gives the various symbol names: +% + {\sffamily\begin{center}\begin{tabular}{|ll|ll|} \hline + \textbf{Field} & \textbf{Symbol Name} & \textbf{Field} & + \textbf{Symbol Name} \\ \hline + big-end-id & \textbf{bigend} & + bytes-per-bin & \textbf{bytes{\usc}per{\usc}bin} \\ + status & \textbf{status} & + bin-compress & \textbf{compress} \\ + sub-status & \textbf{sub{\usc}status} & + daq-state-now & \textbf{daq{\usc}now} \\ + config-state & \textbf{cfg{\usc}state} & + filler-mask & \textbf{filler{\usc}mask} \\ + number-hists & \textbf{n{\usc}hists} & + max-free-block & \textbf{max{\usc}block} \\ + current-hist & \textbf{curr{\usc}hist} & + tsi-status & \textbf{tsi{\usc}status} \\ + bins-per-hist & \textbf{num{\usc}bins} & + flags & \textbf{flags} \\ + max-num-hists & \textbf{max{\usc}n{\usc}hists} & + dead-time/ & \textbf{dt{\usc}or{\usc}dts.both} \\ + max-num-bins & \textbf{max{\usc}num{\usc}bins} & + \hspace*{3mm}delay-to-start & \\ + max-servers & \textbf{max{\usc}srvrs} & + number-bad-events & \textbf{num{\usc}bad{\usc}events} \\ + active-servers & \textbf{act{\usc}srvrs} & + up-time & \textbf{up{\usc}time} \\ + \hline + \end{tabular}\end{center}} + + \noindent The prefix \sfbf{u.status} is required for each of the above + symbols.\\[1.0ex] +% + \sfbf{tsi{\usc}status} is the status word (i.e. the last two bytes) + contained in the last {\em Timing Status Info} packet received from the + multi-detector interface. The \sfbf{flags} item gives various flag bits + from the last {\em Timing Status Info} packet. The various bits in + \sfbf{flags} are: + + {\sffamily\begin{center}\begin{tabular}{|p{48mm}cp{75mm}|} \hline +STATUS{\usc}FLAGS{\usc}{\usc}PF & 0x8000 & Power Fail \\ +STATUS{\usc}FLAGS{\usc}{\usc}SWC & 0x4000 & Status Word Changed \\ +STATUS{\usc}FLAGS{\usc}{\usc}NRL & 0x2000 & Neutron Rate Low \\ +STATUS{\usc}FLAGS{\usc}{\usc}DAQ & 0x1000 & DAQ on -- set if Hdr Mask Bits + are correct so that data acq is active \\ +STATUS{\usc}FLAGS{\usc}{\usc}SYNC3 & 0x0800 & Ext Synch Bit 3 \\ +STATUS{\usc}FLAGS{\usc}{\usc}SYNC2 & 0x0400 & Ext Synch Bit 2 \\ +STATUS{\usc}FLAGS{\usc}{\usc}SYNC1 & 0x0200 & Ext Synch Bit 1 \\ +STATUS{\usc}FLAGS{\usc}{\usc}SYNC0 & 0x0100 & Ext Synch Bit 0 \\ +STATUS{\usc}FLAGS{\usc}{\usc}UD & 0x0080 & UD - Up/Down \\ +STATUS{\usc}FLAGS{\usc}{\usc}GU & 0x0040 & GU - Gummi (i.e. Strobo) \\ + \hline + \end{tabular}\end{center}} + +\noindent Note that \sfbf{STATUS{\usc}FLAGS{\usc}{\usc}DAQ} is a derived +quantity. The derivation is intrument dependent. The following table lists +the requirements which must be satisfied in order for this bit to be set. + + {\sffamily\begin{center}\begin{tabular}{|c|l|l|} \hline + \textbf{Instrument} & \textbf{Conditions for DAQ = 1} & + \textbf{Significance} \\ \hline +FOCUS & NRL = 0 & Neutron rate not low \\ + & SYNC2 = 0 & Neutron counter is counting \\ \hline +HRPT & SYNC2 = 1 & ?? \\ + & SYNC0 = 0 & ?? \\ \hline +Other & NRL = 0 & Neutron rate not low \\\hline + \end{tabular}\end{center}} + + \newpage +% +% + \subsection{SQHM{\usc}WRITE} +% =========================== +% + The SQHM{\usc}WRITE command is the opposite of the SQHM{\usc}READ command. + It allows a user to preset a region of the histogram memory. It + may only be issued once SinqHM has been successfully configured. + The command format is: +% + \begin{center}\begin{picture}(125,42)(0,-42) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}WRITE}} + \put(0,-21){\Midbox{hist-number}} + \put(0,-28){\Midbox{first-bin}} + \put(0,-35){\Midbox{number-bins}} + \put(0,-42){\Botbox{bytes-per-bin}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{70mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}WRITE}{cmnd}{Command verb.} + \Tabrow{hist-number}{u.write.hist{\usc}no}{Histogram number.} + \Tabrow{first-bin}{u.write.first{\usc}bin}{Number of first bin to be + written.} + \Tabrow{number-bins}{u.write.n{\usc}bins}{Number of bins to write.} + \Tabrow{bytes-per-bin}{u.write.bytes{\usc}per{\usc}bin}{Number of bytes + per bin (1, 2 or 4).} + \hline + \end{tabular}\end{center} +% + \sfbf{hist{\usc}no} has the same meaning as for the + SQHM{\usc}READ command. Since SQHM{\usc}WRITE is intended mainly for + debugging and demonstration purposes, data acquisition is not inhibited + whilst data is read over the network and written to the histogram memory + buffer. + + The SQHM{\usc}WRITE command must be followed by + $(\sfbf{n{\usc}bins} \times + \sfbf{bytes{\usc}per{\usc}bin})$ + bytes of histogram data. + + There are no command-specific fields in the status response to an + SQHM{\usc}WRITE command. Possible error values for + \sfbf{status} are: +% + {\sffamily\begin{center}\begin{tabular}{|p{40mm}p{110mm}|} \hline + KER{\usc}{\usc}BAD{\usc}STATE & SinqHM has not yet been configured. \\ + KER{\usc}{\usc}BAD{\usc}VALUE & A command parameter is invalid. \\ + KER{\usc}{\usc}BAD{\usc}RECV & SinqHM had problems reading the + histogram data over the network. \\ + \hline + \end{tabular}\end{center}} +% + \newpage +% + \subsection{SQHM{\usc}ZERO} +% =========================== +% + The SQHM{\usc}ZERO command is used for setting a region of the + histogram memory buffer to zero. It may only be issued once SinqHM + has been successfully configured. The command format is: +% + \begin{center}\begin{picture}(125,35)(0,-35) + \linethickness{0.15mm} \put(0,0){ + \put(0, -7){\Topbox{big-end-id}} + \put(0,-14){\Midbox{SQHM{\usc}ZERO}} + \put(0,-21){\Midbox{hist-number}} + \put(0,-28){\Midbox{first-bin}} + \put(0,-35){\Botbox{number-bins}} + } + \end{picture}\end{center} +% + \begin{center}\begin{tabular}{|llp{70mm}|} \hline + \Tabrow{\textbf{Field}}{Symbol Name}{\textbf{Description}} + \hline + \Tabrow{big-end-id}{bigend}{See Section~\ref{Sect-sinqhm-comm}} + \Tabrow{SQHM{\usc}ZERO}{cmnd}{Command verb} + \Tabrow{hist-number}{u.zero.hist{\usc}no}{Histogram number.} + \Tabrow{first-bin}{u.zero.first{\usc}bin}{Number of first bin to zero.} + \Tabrow{number-bins}{u.zero.n{\usc}bins}{Number of bins to zero.} + \hline + \end{tabular}\end{center} +% + The parameters are the same as for the SQHM{\usc}WRITE command except + that there is no histogram data accompanying the command. In + addition, if\\[1.0ex] +% + \hspace*{\fill}\sfbf{hist{\usc}no} = + \sfbf{first{\usc}bin} = + \sfbf{n{\usc}bins} = -1\hspace*{\fill}\\[1.0ex] +% + the complete histogram memory buffer will be set to zero. + Data acquisition is disabled whilst the histogram memory buffer is + set to zero. The status response is the same as for the SQHM{\usc}WRITE + command. +% + \newpage +% + \section{The SinqHM Control Program, SINQHM{\usc}CTRL} +% ====================================================== +% + \label{Sect-sinqhm-ctrl} +% + The SINQHM{\usc}CTRL program can be used for transmitting commands to + SinqHM-master. It has been implemented for both the OpenVMS and + Unix operating systems. +% + \subsection{Using SINQHM{\usc}CTRL under OpenVMS} +% ================================================= +% + \label{Sect-sinqhm-ctrl-vms} +% + In order to use SINQHM{\usc}CTRL under OpenVMS, it is necessary to + define a so-called DCL Foreign Command. This is best achieved by + including a command of the form:\\[1.0ex] +% + \hspace*{20mm}\texttt{\$ ctrl :== \$mad{\usc}exe:sinqhm{\usc}ctrl} + \\[1.0ex] +% + in one's login command file. One may also specify the TCP/IP host + parameters of the histogram memory via the logical name + SINQHM{\usc}FRONTEND\footnote{It is also possible to specify the + histogram memory by means of the {\em -host} option on the command + line.}, e.g.\\[1.0ex] +% + \hspace*{20mm}\texttt{\$ define/job sinqhm{\usc}frontend + ",,"} \\[1.0ex] +% + where \verb## is the name of the histogram memory (no + default), \verb## + is the TCP/IP port of SinqHM (default = 2400) and \verb## is the + packet size for messages to and from SinqHM (default = 8192). + Once this has been done, it is then possible to execute the + following commands: + {\ttfamily\begin{tabbing}% +% + \hspace*{20mm}\=\$ ctrl config \verb#<#modifier\verb#>#mmmm\=! .. \kill + \>\$ ctrl config \verb#<#modifier\verb#># \>! Send SQHM{\usc}CONFIG % + command \\ + \>\$ ctrl debug \verb#<#level\verb#># \>! Send SQHM{\usc}DBG % + command \\ + \>\$ ctrl deconfig \verb#<#severity\verb#># \>! Send % + SQHM{\usc}DECONFIG command \\ + \>\$ ctrl go \>! Send SQHM{\usc}DAQ/GO % + command \\ + \>\$ ctrl help \verb#<#subject\verb#># \>! Display some help text\\ + \>\$ ctrl rundown \>! Send SQHM{\usc}EXIT % + command \\ + \>\$ ctrl show \>! Send SQHM{\usc}STATUS % + command \\ + \>\$ ctrl stop \>! Send SQHM{\usc}DAQ/STOP % + command \\ + \>\$ ctrl zero \>! Send SQHM{\usc}ZERO % + command + \end{tabbing}} +% + \noindent% + The parameters for the SQHM{\usc}CONFIG command are taken from + logical name definitions. The primary logical name is: +% + {\sffamily\begin{center}\begin{tabular}{|llp{71mm}|} \hline + \textbf{Logical Name} & \textbf{Default Value} & \textbf{Description} \\ + \hline + SINQHM{\usc}MODE & \verb#"HM_DIG"# & The histogramming mode. \\ + \hline + \end{tabular}\end{center}} +% + \noindent% + Further logical names are used depending on the value of + SINQHM{\usc}MODE as follows:\\[1.0ex] +% + {\bf SINQHM{\usc}MODE = \verb#"HM_DIG"# or \verb#"HRPT"#:} +% + {\sffamily\begin{center}\begin{tabular}{|lcp{69mm}|} \hline + \textbf{Logical Name} & \textbf{Default Value} & \textbf{Description} \\ + \hline + SINQHM{\usc}NBINS & \verb#None# & Number of bins per histogram. \\ + SINQHM{\usc}LOW{\usc}BIN & \verb#0# & First bin of histogram. \\ + SINQHM{\usc}COMPRESS & \verb#0# & Bin compression factor \\ + SINQHM{\usc}BYTES{\usc}PER{\usc}BIN & \verb##4 & Number of bytes per + bin (1, 2 or 4).\\ + SINQHM{\usc}NHISTS & \verb#1# & Number of histograms.\\ + \hline + \end{tabular}\end{center}} +% + \noindent% + {\bf SINQHM{\usc}MODE = \verb#"TOF"#:} +% + {\sffamily\begin{center}\begin{tabular}{|lcp{69mm}|} \hline + \textbf{Logical Name} & \textbf{Default Value} & \textbf{Description} \\ + \hline + SINQHM{\usc}NCNTRS & \verb#None# & Number of counters.\\ + SINQHM{\usc}LOW{\usc}CNTR & \verb#0# & Number of first counter.\\ + SINQHM{\usc}NBINS & \verb#None# & Number of bins per histogram. \\ + SINQHM{\usc}LOW{\usc}BIN & \verb#0# & First bin of histogram. \\ + SINQHM{\usc}BIN{\usc}SPAN & \verb#None# & Time span per bin.\\ + SINQHM{\usc}BYTES{\usc}PER{\usc}BIN & \verb##4 & Number of bytes per + bin (1, 2 or 4).\\ + \hline + \end{tabular}\end{center}} +% + \noindent The values of the sub-mode bits in the SQHM{\usc}CONFIG + request to + SinqHM may be set by appending the tokens \verb#"BO_IGN"#, + \verb#"BO_SMAX"#, \verb#"BO_CNT"#, \verb#"UD"#, \verb#"STROBO"#, + \verb#"REFLECT"# or \verb#"NO_STAT"# to the value + of SINQHM{\usc}MODE. + + \noindent \verb## may be specified as \verb#"suspend"#. If so, + the SQHM{\usc}{\usc}DEBUG + modifier bit in \sfbf{mode} will be set so that SinqHM-filler + will suspend itself as soon as it starts. This is intended to allow + interactive debugging of SinqHM-filler. + + \noindent \verb## + may be ``on'', ``off'' or an integer in the range 0 to 15. + The default is ``on'' which corresponds to level 1. + + \noindent The SQHM{\usc}DECONFIG command will be sent with + \sfbf{sub{\usc}code} (harshness) set to zero unless + \verb## is specified as ``harsh''. In this + case, \sfbf{sub{\usc}code} will be set to 1. + + \noindent The \sfbf{zero} command will set the entire + histogram buffer to zero. +% + \subsection{Using SINQHM{\usc}CTRL under Unix} +% ============================================== +% + The exact use of SINQHM{\usc}CTRL under Unix depends on the shell which + is being used. In the following, this is assumed to be {\em csh}. + It is also assumed that the {\em sinqhm{\usc}ctrl} executable is + located in directory \textsf{/data/lnslib/bin}. + + The invocation of SINQHM{\usc}CTRL can be facilitated by defining + an alias such as:\\[1.0ex] +% + \hspace*{20mm} \verb#alias ctrl /data/lnslib/bin/sinqhm_ctrl# \\[1.0ex] +% + in one's \textsf{\$HOME/.cshrc} shell initialisation script. Once + this has been done, the program can be used in the same way as + is described above for OpenVMS except that one uses environment variables + instead of logical names, e.g.\\[1.0ex] +% + \hspace*{20mm} \verb#setenv SINQHM_MODE "TOF"# +% +% + \section{The SinqHM Client Program, SINQHM{\usc}CLIENT} +% ======================================================= +% + \label{Sect-sinqhm-client} +% + The SINQHM{\usc}CLIENT, as opposed to the SINQHM{\usc}CTRL, program can + be used for communicating with SinqHM for functions which usually + require a long-lived link such as the display of the histogram data. + As with SINQHM{\usc}CTRL, it + has been implemented for both the OpenVMS and Unix operating systems. + The following description refers to the Unix implementation. By referring + to Section~\ref{Sect-sinqhm-ctrl-vms}, it should be clear how to run the + program under OpenVMS. + + \noindent Assuming that the program is located in the + directory \textsf{/data/lnslib/bin}, define an alias as follows:\\[1.0ex] +% + \hspace*{20mm} \verb#alias client /data/lnslib/bin/sinqhm_client# \\[1.0ex] +% + The program can then be started via a command of the form:\\[1.0ex] +% + \hspace*{20mm} \verb#client -host #\\[1.0ex] +% + where \verb## specifies the name of the histogram memory. One + should then obtain a prompt of the form:\\[1.0ex] +% + \hspace*{20mm}\verb#The following commands are available:# \\ + \hspace*{20mm}\verb# Help Open Status Read 2D Project Dump# \\ + \hspace*{20mm}\verb# LOAD WRITE W2D GO STOP ZERO Quit# \\[1.0ex] +% + More information can then be obtained via the help command. +% + \section{Communication with Multi-detector Interface} +% ===================================================== +% + \label{Sect-mdi-comm} +% + SinqHM can communicate with the front-end electronics via the + full-duplex RS-232-C COM2 port of the MVME-1603 PowerPC module. + The details of this communication have still to be worked out. + Here is a very, very, very preliminary proposal. + + SinqHM can send the following messages to the front-end + electronics: +% + \begin{center}\begin{tabular}{|cp{90mm}|} \hline + \rule{0em}{2.5ex}\verb#RMT 1# & Set the front-ent electronics to + remote mode. \\ + \rule{0em}{2.5ex}\verb#DT # & Set TOF start time delay to + \verb##. \\ \hline + \end{tabular}\end{center} +% + \section{Update History} +% ======================== +% + \label{Updates} +% + This document has had the following changes: +% + \begin{center}\begin{tabular}{llp{90mm}} + \sfbf{Version} & \sfbf{Date} & \sfbf{Description} \\[1.0ex] + Vn 1.5 & 23-Nov-1999 & a) Add SQHM{\usc}IDENT command. \\ + & & b) Add SQHM{\usc}PROJECT command. \\ + & & c) Add HRPT support. \\ + Draft 1.4 & 9-Dec-1998 & Add TOF support. \\ + Draft 1.3 & 10-Jul-1997 & Mainly expanded documentation. \\ + Draft 1.2 & 19-Mar-1997 & Initial release. + \end{tabular}\end{center} +% + \begin{thebibliography}{9} + + \bibitem{CTN94005} D. Maden, PSI, Oct 1994 \\ + {\em The \musr Histogram Memory Server for the KAV-30 rtVAX} \\ + CTN-94-005 + + \bibitem{PAW} CERN Program Library, Long Write-up, Feb 1995 \\ + {\em PAW Physics Analysis Workstation} \\ + Entry Q121 + + \end{thebibliography} +\end{document}