% 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} % The instruments TRICS and AMOR use 2D position sensitive detectors provided by the EMBL at ILL. These detectors have a delay line readout. This means the detector readout for each neutron is two delay values. From these values the actual detector positions can be calculated from the formula: \begin{equation} pos = \frac{(delay - offset)}{factor} \end{equation} Thus the configuration message must carry two additional values for each of the two detector dimensions. AMOR will be operated in time--of--flight mode. For TRICS this is not necessary. However, as the data telegrams coming from the fibre optic link contain the time binning information in any case it was decided to treat both conditions equally as a variation of the time--of--flight case. For a description of the edge and bank data structures involved see \ref{SubSect-TOF}. TRICS detectors will then be treated as a time--of--flight detector with a single huge timebin. Thus the SQHM{\usc}{\usc}HM{\usc}PSD configuration command looks as follows: \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{SQHM{\usc}CONFIG}} \put(0,-21){\Midbox{SQHM{\usc}{\usc}HM{\usc}{\usc}PSD}} \put(0,-28){\Midbox{extra-bytes}} \put(0,-35){\Midwordbox{n-banks}{n-edges}} \put(0,-42){\Midbox{preset-delay}} \put(0,-49){\Midwordbox{x-Factor}{y-Factor}} \put(0,-56){\Midwordbox{X Offset}{Y Offset}} \put(0,-63){\Midwordbox{x Size}{y Size}} \put(0,-70){\Midbox{}} \put(0,-76){\Midbodydashed{edge[0] $\ldots$ edge[n-edges]}} \put(0,-84){\Botbody{}} \put(0,-91){\Midbox{}} \put(0,-98){\Midbodydashed{bank[0] $\ldots$ bank[n-banks]}} \put(0,-105){\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}HM{\usc}{\usc}PSD}{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{x-Factor}{$<$prefix$>$.xFactor}{Division factor for calculating x position.} \Tabrow{y-factor}{$<$prefix$>$.yFactor}{Division factor for calculating y position.} \Tabrow{x Offset}{$<$prefix$>$.xOffset}{Offset value for calculating x position.} \Tabrow{y Offset}{$<$prefix$>$.yOffset}{Offset value for calculating y position.} \Tabrow{xSize}{$<$prefix$>$.xSize}{Number of detector wires in x direction.} \Tabrow{ySize}{$<$prefix$>$.ySize}{Number of detector wires in y direction.} \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} % \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}