%
%================= VXI data base structures =========================
%
\documentstyle[11pt,a4wide]{article}
 \def\EG{{\sf EUROGAM}}
 \def\EB{{\sf EUROBALL}}
 \def\VR{{\sf VXI-RM} }
 \def\DB{{\sf Data Base}}
 \def\Vc{{\sf VXIconfig}}
 \def\Vs{{\sf VXIslot}}
 \def\Vd{{\sf VXIdevice}}
 \def\Va{{\sf VXIaddressMap}}
 \def\Md{{\sf ModuleDescription}}
 \def\Ch{{\sf DAQchannel}}
 \title{\bf VXI Basic Data Base Structure}
 \author{Christoph Ender}
 \date{1-Sep-1990 Draft 0.2}
 %
 % description  now definition extended to allow specification of an additional
 %              label which is a placeholder to compute the labelsize
 %
 % \begin{description}[label_of_largest_size]
 % \item<<item_label>> <text>
 % <<another_item>>...
 % \end{description}
 %
 %
 \makeatletter
 \def\descriptionlabel#1{\hfil\boldmath\bf#1\hspace\labelsep}%
 %
 \def\@@descr{\list{}{\advance\loclabelwidth\labelsep\labelwidth\loclabelwidth%
  \ifdim\labelwidth<\leftminwidth \labelwidth\leftminwidth%
  \fi\leftmargin\labelwidth\advance\leftmargin\labelsep%
  \let\makelabel\descriptionlabel}}%
 
 \def\@@setlabwidth[#1]{\settowidth\loclabelwidth{\boldmath\bf{#1}}\@@descr}%
 %
 \newdimen\leftminwidth
 \newdimen\loclabelwidth
 \leftminwidth\leftmargini
 %
 \def\description{\@ifnextchar[{\@@setlabwidth}{\loclabelwidth 2.5em\@@descr}}%
 %
 % start record description
 % syntax:
 %  \begin{rdes}{name of record}[size of definition area]
 %  optional explanation
 %  \ritem{Name}{attribute} explanation
 %  \end{rdes}
 %
 \def\rdes#1{\let\@@decsr\@@rdescr\ifx!#1!\def\rdes@lab{!}%
  \else\def\rdes@lab{#1}\fi\@ifnextchar[{%
  \@@setlabwidth}{\loclabelwidth 6cm\@@descr}}%
 \def\@@rdescr{\list{}{\advance\loclabelwidth\labelsep\labelwidth\loclabelwidth%
  \ifdim\labelwidth<\leftminwidth \labelwidth\leftminwidth%
  \fi\leftmargin\labelwidth\advance\leftmargin\labelsep%
  \let\makelabel\rdescriptionlabel}\ifx!\rdes@lab\relax\else%
  \item[\sc\rdes@lab]\fi}%
 \let\endrdes\endlist
 %
 %\def\rdescriptionlabel#1{{#1}\hspace\labelsep}%
 \def\rdescriptionlabel#1{\setbox2=\hbox{{#1}\hspace\labelsep}%
  \ifdim\wd\z@>\loclabelwidth\unhbox2\else%
  \hbox to\loclabelwidth{\unhbox2\hfil}\fi}
 %
 % \ritem{Definition}
 \newdimen\@rspace
 \def\ritem#1#2{\setbox\z@=\hbox{\sf%
  #1\ :}\@rspace6em\ifdim\wd\z@<\@rspace\advance\@rspace-\wd\z@%
  \@rspace\labelsep\else\ifx!#2!\@rspace\labelsep\else\@rspace\z@\fi\fi%
  \item[\sf#1\ :\hskip\@rspace\sl #2] }
 %
 \makeatother
\begin{document}
 \maketitle
 
 This Document tries to explain why a \DB\  is necessary for the VXI Resource
  Manager. Furthermore a first attempt to define a basic \DB\  for the
  VXI Resource Manager is done. The term \DB\ used in this document defines the
  data structures and the relationship between the data structures. It has
  nothing to do with the event storage or event format definition, which some
  people have in mine if they call something a data base.
 
 \section{Introduction}
  Following the VXIbus specification one finds in part C of them a detailed
  description what to do during startup of a VXI system. One has to scan the
  geographical and logic address space to find SC (static configured)
  VXI-devices
  and DC (dynamic  configurable). The information found in the VXI configuration
  registers has to be stored in a data structure owned by the VXI Resource
  Manager
  to allow them to configure the system {\em the DC devices} (refer to part F of
  the VXI specifications) and to initialize the
  modules found in the system.
 
  For the \EG\ project as well as for the other projects in Europe (i.e.\
  \EB , DEMON, ICAR, SUSAN)\footnote{They might use the same general design of
  the
  data acquisition structure.} a flexible solution is required, to allow
  upgrades
  and changes in the VXI based electronics. To reach this requested flexibility
  the most VXI devices will be dynamic configurable. This VXIbus modules has to
  initialized in their device dependent part according the experiment in which
  they are incorporated.
 
  Therefore the VXI \DB\  has to describe:
  \begin{enumerate}
    \item what's inside the VXI crate, which type of VXI devices, where it is
     located
    \item how to initialize it
    \item the result of the initialization \\
     (e.q.\ logical address, VMEbus address, status of the device ...)
    \item Module constants to allow proper experiment initialization
    \item Channel {\em physics channel} initialization to a basic operation
     which allows proper testing, and a save state between different modules
     in the crate.
    \end{enumerate}
  This Informations are necessary on a per crate basis. {\bf Note:} that
   the \DB\  has to store all information which are stored
   by the VXI devices configuration registers. Due the fact that a register can
   have different meanings in read and write case. Some of them carries three or
   or four different meanings, just depending on the current content of them
   {\em an example is the message protocol register}.
 
  However in most applications we have in mind the systems consist out of
   several VXI crates and a few other VME crates. Therefore we need in addition
   to
   the crate based \DB\  a more general \DB\  somewhere in the system.
   This {\sf central} \DB\  contains information about
  \begin{enumerate}
   \item How many VXIbus crates,
   \item where they are located,
   \item how to reach them (Network address, ... ),
   \item what is inside the crate (partial copy of VXIcrate \DB\, ... )
   \item state of the crate
   \item other hardware (CAMAC, VMEbus, TapeServer, ...)
   \item experiment specific \DB\  contains actual settings
   \item read out relevant informations \\
    mapping of experiment channels to the actual hardware and the
    {\em  Event Format Definition}.
   \item logging and calibration \DB\
   \end{enumerate}
 
  Most points of this overview have to deal the the overall design of the
   \EB{}--\DB\ and
   will be not discussed within this document. In the following only the
   VXI \DB\  relevant parts and a mapping structure from a more general
   description to the VXI hardware is discussed.
 
 
 
  As a start point in the design the Entity-Relationship Model is choosen,
   combined with modern SASD techniques (Data Flow Analysis, Performance
   Analysis). The mapping of the results into a
   \DB\  will be done in a model as simple as possible, due to the requests
   from realtime constrains.
  \vspace*{3ex}
 
  \noindent {\bf NOTE: } {\em There will be changes in the mapping of the
  \DB --design into our simple \DB --model (Tabular form together with linked
  lists) during the development of the system and the forthcoming discussion.}
 
 \section{Overview}
  In this part a detailed  overview about the relationship between the different
   parts of the \DB\ is given. In figure \ref{VXIDB.over} the different required
   components are shown.
  \begin{figure}
   \setlength{\unitlength}{1mm}
   \begin{picture}(160,160)(0,-10)
    \put(0,0){\framebox(40,104){ }}
    \multiput(0,8)(0,8){12}{\line(1,0){40}}
    \put(0,104){\makebox(40,6){\Vs\ table}}
    \put(40,3){\thicklines\vector(1,0){10}}
    \put(50,5){\thicklines\vector(-1,0){10}}
    \put(50,0){\framebox(40,50){\Vd\ table}}
    \put(90,5){\thicklines\vector(1,0){10}}
    \put(100,10){\thicklines\vector(-1,0){10}}
    \put(50,85){\framebox(40,30){\shortstack{\sf Module\\ \sf
     Description\\table}}}
    \put(50,60){\framebox(40,20){\shortstack{\Va \\table}}}
    \put(70,60){\thicklines\vector(0,-1){10}}
    \put(100,0){\framebox(40,70){\large\bf\shortstack{\Vc\\table}}}
    \put(110,-5){\thicklines\line(0,1){5}\line(-1,0){80}\vector(0,1){5}}
    \put(100,62){\thicklines\vector(-1,0){10}}
    \put(90,64){\thicklines\vector(1,0){10}}
    \put(100,67){\thicklines\line(-1,0){5}\line(0,1){23}}
    \put(95,90){\thicklines\vector(-1,0){5}}
    \put(110,70){\thicklines\vector(0,1){5}}
    \put(130,75){\thicklines\vector(0,-1){5}}
    \put(100,75){\framebox(40,35){\bf\shortstack{\large\Ch\ \\ table }}}
    \end{picture}
   \caption[]{Overview and relationship between the different components of
     the VXI \DB\ .}\label{VXIDB.over}
   \end{figure}
 
  In total we will have six tables. The \Vs\ and the \Vd\
   tables are required to allow a mapping to the \Vc\ table. One can
   identify these as index tables to speed up the access to the \Vc\ table in
   the
   case of a geographical (via \Vs ) or logical (via \Vd ) addressing of a VXI
   module\footnote{Remark: A VXI module in a single slot can house several
   logical \Vd s}. In addition both index tables will have some cross reference
   information. {\em In principle this is in some way a redundant information,
   specially if we use it in the central \DB . In the case of the use of a full
   Relational Data Base System (RDBS) the redundant information can be omitted
   there. However the importance of these cross links will be
   arise in the case of error handling during the normal operation where a fast
   response to certain conditions is necessary to ensure save operation of the
   Data Acquisition System.}
 
 
  In the \Vc\ table there will be stored the complete information over the
   status of the related \Vd , it's type and the associated link to the \Md\
   table, and a link to the \Ch\ -- table. Furthermore back links to the \Vs\
   and \Vd\ tables will be used. Another required link points to the \Va\ table,
   which is used to construct the VXIbus address schema, as pointed out in the
   VXI specifications.
 
  The \Md -- table which will be discussed in detail in section
   \ref{VXIDB.smod}.
   It contains a full description of the module and the description what to do
   during the different phases of initialization. Furthermore the basic initial
   data, test and diagnostics information is stored. For each Module type used
   only one entry in that table has to be used. The information is stored there
   in a  position or logical/real address independent way, for use by any
   module under inspection/ access/ test/ diagnostic.
 
  The just discussed organisation, which defines the relations between
   different entities, has the benefit that informations -- out of the
   \Md , \Vc , \Vd , \Vs , \Va , and \Ch\ -- has to stored only once.
   This speeds up also the access to the relevant information, due the fact
   that for a certain task only a specific set of information is necessary,
   which    will be stored in one of the tables (e.q.\ Initialisation).
 
  A critical part in the design of this structures is the detailed organisation
   which is very closely related to the VXI RM software design. The
   organisation
   of the structures and will be discussed in the appendix to this document.
 
   %  <<text>>...
 
 %
 
 
 
 
 
 
 
 
 
 \clearpage\section{Module Description \DB\ }\label{VXIDB.smod}
  Module definition, what's in what's required should be in a form of a text
   file
   available, from which other programs can extract informations required for
   them. In addition  Interpreters will be necessary to convert this
   information into a binary form. In the following a prototype of the a
   possible     form is shown:
  \begin{verbatim}
    Module name;
      Description
        Type ..... , ......;
        Manufacturer .....;
        Channels ..... , .....;
        Hardware Description file ..... ;
        Software Description file ..... ;
        Submodules ..... ;
        BusSystem .....;
        { BusSystem dependent part (VXI|Fastbus|CAMAC|VME|.....)}
          Capability ..... , ..... ;
          VXIdevices ..... ;
          ....... ;
        EndDescription;
      Initial Phase n;
        DBcreate name, type , size, substructure , .....
          Record description in SQL or similar syntax;
          EndDBcreate
        Read address , type of access, expected data value [= DBentry.field] ;
        Write address , type of access, data value ;
        Test .... ;
        Sequence ...
          End Sequence ;
        Store data in DBentry.field;
        CheckForSubmodule address, name of expected Submodule, action();
        GenerateAddress ;
        ExecuteProgram filename ;
        EndInitial;
      Test 1
       Read, Write, Test, Sequence, ...
       EndTest 1;
      Test 2
       Read, Write, Test, Sequence, ...
       EndTest 2;
      Diagnostic
        Type ... Phase .... File ... ;
        required Diag ... ;
        EndDiagnostic;
     EndModule name ;
   \end{verbatim}
  Each module requires first a description to define what type it is, what bus
   system it supports\footnote{That's the main bus, the module itself may have
   several private busses (normally CPU's) where additional submodules will be
   connected.}, the capability of the module and the type of submodules if there
   are any. The later has to be defined in a similar form. An example is shown
   below. Note that the syntax will be the same with one exception: the
   submodule keyword is not allowed.
 
  \begin{verbatim}
    SubModule name;
      Description
        Type ..... , ......;
        BusSystem .....;
        Manufacturer .....;
        Channels ..... , .....;
        Capability ..... , ..... ;
        Hardware Description file ..... ;
        Software Description file ..... ;
        { BusSystem dependent part (VXI|Fastbus|CAMAC|VME|Slave,FERA,VSB.....)}
         VXIdevices ..... ;
       EndDescription;
      Initial Phase n;
        Read address , expected Data ;
        Write .... ;
        Test .... ;
        Sequence ... ;
        End Sequence ;
        DBcreate name, type , size, substructure , .....
          Record description in SQL or similar syntax;
          EndDBcreate;
        EndInitial;
      Test 1
        Read, Write, Test, Sequence, ...
        EndTest 1;
      Test 2
        Read, Write, Test, Sequence, ...
        EndTest 2;
      Diagnostic
        Type ... Phase .... File ... ;
        required Diag ... ;
        EndDiagnostic;
      EndSubModule name ;
   \end{verbatim}
 
 
  The further characterization of the module has to specify informations about
   the necessary module initialisation, test, and diagnosis.
   For this purpose this Module definition file contains additional subfields:
 
  \begin{description}[Diagnostics::]
   \item[Initial:] what to do during the Module initialisation
   \item[Test:] declare Test sequences
   \item[Diagnostics:] declare available Diagnostic
   \end{description}
 
 
  To allow a proper operation -- during the several startup (initial) phases:
   {\em primary initial, test, autoconfiguration, diagnostic (extended tests),
   channel initial, channel tests, initial for normal operation (defaults),
   initial for experiment operation} and the during normal operation as well as
   during user requested tests and diagnostics -- for each of the actions a
   phase number has to be specified. In this proposal phases 0 ... 10
   should be assigned for execution during the
   startup of the VXI--System\footnote{This can be generalized to any bus
   system. In the definition it is already foreseen!}. Each phase is finished
   completely before the next is allowed to be started: i.e.\ Initial Phase 0,
   Test Phase 0, Diagnostic Phase 0, Initial Phase 1 ,.... and so on. Phase
   numbers larger than 10 can be called by the user during data acquisition and
   phase number larger 100 specifies initial, tests and diagnostics sequences
   for standalone test, calibration and extended diagnostics, which can be
   requested only in test mode of the crate (locally via Console terminal or a
   connected workstation).
 
 
  In the following subsection the detailed syntax will be defined. Note that
   there will be different representations of the Module Data base in the
   different parts of the System. In the VXI system only a subset of the Module
   description will be loaded, whereas in the central Data base all information
   is available. To extract the informations and to bring it in a useful form
   (binary) a set of programs are required. They should also be able to create
   the required include files, the data definition files, and an insert into the
   general data base after some syntax checks and ordering of the information
   found in the user supplied Module Definition file. There will be also
   comments allowed, specify them in the same syntax like ``C'' (i.e.\
   \verb+/* ... */+ ).
 
  In the following subsections items set in {\sf typeface } are keywords, text
   appear if {\sl typeface} signal user specified input/variables/values.
  \subsection{Module Description}
   The module description is the most important part of the definition. It is
    enclosed in the keywords {\tt Description} and {\tt EndDescription;} .
    Inside this pair of keywords a fixed set of keywords and a bus type
    dependent keyword set is allowed.
   \begin{description}[{\sf HardwareDescription}]
    \item[$<${\sf Type ={\sl name}[,ID={\sl hhhh}][,OPT={\sl further
     informations}]}$>$] Type of module out of a fixed identifier set.
     {\sf ADC, TDC, Memory, Message, VXIDC, VXISC, VXIREG, VXIDAQ, CPU, VXIRM}
     Other will be defined if it will be necessary.
    \item[{\sf $<$ Manufacturer = {\sl name}[,ID={\sl hhhh}];$>$}] specify the
     Manufacturer
     name of the module and as a optional argument the manufacture ID. The ID
     might be not available for all Bus Systems, for the VXI it is a must.
    \item[{\sf $<$ HardwareDescription {\sl filename};$>$}] Define the
     filename/path in
     which the description, including the schematics will be found.
    \item[{\sf $<$ SoftwareDescription {\sl filename};$>$}] the same for the
     software description.
    \item[{\sf $<$ SubModules={\sl list of submodule names};$>$}] Several
     Modules
     will consist out of several submodules. Some of the Modules will have
     one type others will hold
     different submodules. (One example will be the Flash ADC/Logic Analyser)
    \item[{\sf $<$ BusSystem = {\sl keyword }$>$}] Depending on the Bus System
     type there will be a special syntax.
     \begin{description}[XXXXXXX]
      \item[{\sf VXI}] defines the module to be a VXI device which fulfills the
       VXI specification in all points.
      \item[{\sf Slave}] defines a module which have only two access registers
       one to set up the slave internal address and a data access register
       (i.e.\ FALA Submodule for the \VR ). Such a module can be a submodule of
       another module only.
      \item[{\sf VME}] a normal VME device
      \item[{\sf VSB}] a device which is connected to a VMEbus CPU by the VSB
       bus.
      \item[{\sf CAMAC}] not defined up to now
      \item[{\sf FERA}] A Fast Encoded Read device. {\em syntax not specified}
      \item[{\sf FASTBUS}] {\em not defined up to now}
      \item[{\sf SCSI}] {\em not defined up to now}
      \item[{\sf Ethernet}] {\em not defined up to now}
      \item[{\sf User}] {\em not defined up to now}
      \end{description}
    \end{description}
   Depending on the specified bus type there are different keywords allowed.
    Each keyword have as the prefix the bus type to allow an easy
    implementation of the syntax scanner. In the following subsections we
    distinguish between the different bus types, because a keyword may have
    different meanings by the use of different bus types. {\em Only the
    keywords of full specified bus types are described.}
 
   \subsubsection{VXI}
    Define here all keywords allowed for VXI devices. Note all keywords have
     an additional prefix {\sl VXI\_} which is not shown here.
    \begin{description}[{\sf HardwareD}]
     \item[{\sf Capability =}] {\sl A16 A24 A32 A64 ; D08 D16 D32 D64}
      supported access type to the module.
     \item[{\sf ManId = hhh;}] Manufactur Id
     \item[{\sf DevID = hhh;}] Device Id
     \item[{\sf AddressMask = hhhhhhhh;}] <text>
     \item[{\sf AddressSize = hhhhhhhh;}] <text>
     \item[{\sf BaseAddress = \{fixed=aaaaa | dynamic \};}] define the base
      address for the VME bus address map. Normal it should be dynamic. Only
      for test and devices under development fixed addresses are allowed.
     \item[{\sf VXIdevtype = \{Register, Memory, Message, Extended \}, \{DC,
      SC \};}]
      define the type of module and if that is a dynamic configurable or
      static configurable. For the device all required Registers are defined
      automatically, the optional ones has to be defined via the following
      keyword.
     \item[{\sf ConfReg = (add,),{\sl (List of regs)};}] Configuration
      registers which are defined in
      addition to the device type ones. Each Registers definition requires
      first the hexadecimal address, then the mnemonic for symbolic access
      together with the access mode (read only, write only, read write).
     \item[{\sf ReadConfRegMask = ({\sl list});}] list of registers which
      allows
      read access. It is a 32bit wide mask, for each register one bit.
     \item[{\sf WriteConfRegMask = ({\sl list});}] Register mask for write
      access.
     \item[{\sf SlavePort = ({ \sl AddressReg, DataReg})}] Define Register
      pair to access a slave device.
     \item[{\sf Interrupts = ({\sl Mnemonic, Vector, VectorSize, Level}),
      ...}] Specify the possible interrupts.
     \end{description}
   \subsubsection{Slave}
    The Slave device is a device which has a register port. There is a 16bit
     address and a 16 bit data bus.
    \begin{description}[{\sf HardwareD}]
     \item[{\sf BaseAddress = nnnn, nnnn}] first address within the slave or
      a list of possible base addresses.
     \item[{\sf AddressMask}] address mask defined by $2~(16-n)$
     \item[{\sf AddressSize}] logical addressing space highest address minus
      base address.
     \item[{\sf Reg = (address, mnemonic, (R0,WO,RW,RC=cccc)), ... }] list
      of registers (16bit) defined by there address, mnemonic, and the access
      mode.
     \item[{\sf Block = (mnemonics, address, size, access), ... }] list of
      memory blocks.
     \end{description}
   \subsubsection{VME}
    Similarly to the VXI devices the VMEbus devices have to be specified.
    \begin{description}[{\sf HardwareD}]
     \item[{\sf Capability=}] has to be specified
      \begin{description}[xxxxxx]
       \item[{\sf AddressMask}] <text>
       \item[{\sf AddressSize}] <text>
       %\item[{\sf <text>}] <text>
       %<<another_item>>...
       \end{description}
 
     %\item[{\sf <text>}] <text>
     \end{description}
   %\subsubsection{VSB}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{CAMAC}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{FASTBUS}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{SCSI}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{Ethernet}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{FERA}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
   %\subsubsection{User}] not defined up to now
    %\begin{description}[{\sf HardwareD}]
    % \item[{\sf Capability=}] has to be specified
    % \item[{\sf <text>}] <text>
    % \end{description}
 
 
  \subsection{Module Initial}
   \begin{description}[{\sf HardwareDescription}]
   \item[{\sf Read {\sl address} [,{\sl expected data}] = \{ {\sl variable}|
    {DBentry.field} \} ,}]
   \item[{\sf error = {\sl("{}output string{}"{},variables, \{ abort,
    continue \}}}] read a defined register and store content in a local
    variable\footnote{allocated from a local private stack} or in a database
    entry. Furthermore the result of the tread can be checked against an
    expected data value. If that is not equivalent an error is signaled, and
    written to the standard console device. Also exceptions like bus trap
    errors are signaled.
   \item[{\sf Write}] <text>
   \item[{\sf Test}] <text>
   \item[{\sf Store}] <text>
   \item[{\sf CheckForSubmodule}] <text>
   \item[{\sf DBcreate}] <text>
   \item[{\sf GenerateAddress}] <text>
   \item[{\sf load program}] <text>
   \item[{\sf execute program}]
   \end{description}
  \subsection{Module Test}
   \begin{description}[{\sf HardwareDescription}]
    \item[{\sf Read {\rm address};}] <text>
    \item[{\sf Write ;}] <text>
    \item[{\sf Check ;}] <text>
    \item[{\sf Store ;}] <text>
    \item[{\sf LoadFile ;}] <text>
    \item[{\sf Error ;}] <text>
    \item[{\sf Execute {\rm program name};}]
    \end{description}
  \subsection{Module Diagnostics}
   \begin{description}[{\sf HardwareDescription}]
    \item[{\sf Type {\rm name} Phase {\rm nnn} File {\rm filename}}] <text>
    \item[{\sf Required Diagnostic {\rm list of}}] {}
    \end{description}
 
 
 
  \subsection{Required Programs}
   For proper operation and handling of the Module description there is a
    handling program necessary which allows the syntax check, a generation of a
    description table, and an ``C'' include file to generate a memory resistant
    version of the table. Furthermore it will be necessary to generate a \TeX\
    formatted file for documentation.
 
   In the future there will be also the need to have a \DB\ version of the
    module description available, which allows the generation of the \DB\ data
    for the central \DB --Server. From that a slave can then retrieve such
    informations not found in the memory base tables.
 
 \section{VXI Configuration Data Base}\label{VXIDB.svco}
  The configuration of the VXI required data base consists out of the following
   \DB\ tables:
  \begin{description}[VXIAddressMapx]
   \item[\Vs] which contains informations about the type of the
     module, the VXI device number, how many VXI devices are in the module
     located, and a pointer to the VXIConfig table.
   \item[\Vd]
    Define the mapping table between the VXIdevice number, the module and the
    config table. This table has 256 entries with the following structure:
   \item[\Va] Defines the Address mapping data structures
      which are required to construct the A24 and A32 address maps.
   \item[\Vc]
    This is the real configuration data table, containing all informations
    required to characterize a VXI device. This table is generated during the
    initialization of the VXI system.
   \end{description}
 
  \subsection{\Vs\ table} which contains informations about the type of the
     module, the VXI device number, how many VXI devices are in the module
     located, and a pointer to the VXIConfig table.
    \begin{description}[BasVXdevx]
     \item[Mtype] Module Type
     \item[ID] Module ID (manufacturer id and module id)
     \item[NumVXdev] Number of VXI devices which are defined by this module
     \item[BasVXdev] VXI device number of the first VXI device of this module
     \item[pConfig] pointer to the first Configuration entry in the VXIConfig
       table
     \end{description}
 
  \subsection{\Vd\ table}
    Define the mapping table between the VXIdevice number, the module and the
    config table. This table has 256 entries with the following structure:
    \begin{description}[SubModule]
     \item[Module]  Module/slot number
     \item[SubModule]  Sub Module/slot number (number of VXI device in this
       module)
     \item[pConfig]  pointer to configuration entry
     \end{description}
 
  \subsection{\Va\ table} Defines the Address mapping data structures
      which are required to construct the A24 and A32 address maps.
    \begin{description}[Addressss]
     \item[next]  pointer to the next AddrMap entry
     \item[pConfig]  pointer to configuration entry
     \item[Address]  access address
     \item[size]  size in bytes
     \item[type]  type of access a24/a32
     \item[m]  copy of required memory size
     \end{description}
 
  \subsection{\Vc\ table}
    This is the read configuration entry.
 
    It contains all VXI configuration registers in each meaning. In addition a
     bit
     map with registers which are readonly, write - only, and not accessible.
     Furthermore it contains also some status information if this device fails.
 
    The organisation of the is in form of a linked list.
     Indices pointing back to the Module mapping table.
    \begin{description}[VXIdeviceNumber]
     \item[prev]  pointer to next and to previous   entry in the  Configuration
      table
     \item[user]  user extension part
     \item[VXIdeviceNumber]  logical address
     \item[VXIslotNumber]  geographic address
     \item[AddressDesc]  Pointer to associated Address map entry
     \item[ModuleDesc]  pointer to the Module description
     \item[DAQchannel]  pointer to DAQchannel
     \item[ReadAddressMask] Bit mask for all of the 32 Config registers,
       specifies which register can be read out without a bus error fault, and
       is defined as a readable register in the module table. {\em this entry is
       a work around to speed up access to this table.}
     \item[WriteAddressMask] Bits mask for writeable Configuration registers.
     \item[InvalidAddressMask] This registers can be not accessed (Bus Error
       occurs during access.)
     \item[RD] Readable configuration registers\\ After a read of such a
       register it's content is written into this field.
     \item[WRT] Writeable configuration registers \\ After a successful write
       the content has to be written into this field.
     %<<another_item>>...
     \end{description}
 
 
 \section{VXI Data Acquisition Data base}\label{VXIDB.svdaq}
  This part will contain all Information which are related to the data
    acquisition system. The information which has to be in that structure has to
    be:
  \begin{enumerate}
   \item Channel parameters, like channel numbers, ADC identifiers, parameters
    for experiment specific setting of ADC's, reg's, ... .
   \item Status Informations
   \item Spectra Definitions
   \item Rates for monitoring
   \item Which  Module, SubModule, VXIDevice is related to that channel. VMEbus
    address for access
    {\em Or more general expressed: some back link Informations are required
    for the easy mapping and debugging of the whole system. See also figure
    \ref{VXIDB.links}}
   \end{enumerate}
 
   From the point of the VXI related \DB\  it is not necessary to know what's
    really inside these records, but the general structure has to be created
    during the startup. Furthermore the default informations/parameters found in
    the Module data base {\em required for initial and proper operation during
    startup tests} have to be inserted as the current values into the channel
    \DB . {\em More discussion required on that point!}
 
   Up to now only the point of view from the VXI system is enlightened. For
    further discussion also the point of view from the global system or more
    specific spoken from the data acquisition application program (i.e.\ Rate
    Monitor, Calibration programs, ... ) has to be discussed in detail.
 
 
 \clearpage\appendix
 \section{Implementation Proposal}
  To implement this database the structures has to been mapped to a
   sufficient form to store it memory and into data files. The mapping into
   data file is the preferred technique for the central \DB\ which is not in
   the scope of this document. That task has to be solved by David Brightly.
 
  In the following  the mapping of the data structures into a memory based form
   is described, which is one of the very important and critical point of the
   design for the basic software structures for the VXI based software.
   (See also the {\bf VXI Resource-Manager Basic Software} document.)
  \subsection{General}
   A data base can be stored quite easily in tabular form, which is the
    normal representation. All entries represent one and only one entity with
    certain attributes within the data base. This entity is called {\bf
    record} in the further discussion. Each record contains the whole
    information required to describe the entity in a unique way.
 
   There exist two organisation forms to store the records:
    \begin{itemize}
    \item[a)] a fixed record structure with fixed length records
    \item[b)] a variable record structure with variable length records
    \end{itemize}
    Both forms are widely used by data base programs.
 
   In our case both forms will be used. The fixed organisation form is
    adequate to organize the index and mapping tables (\Vs , \Vd , \Va ).
    These tables will contain only pointers, a few data values, and indexes.
 
   However for the other \DB\ tables (\Vc , \Md , \Ch ) a variable structure
    is more useful  due to the fact that the number of the required
    information for each record varies from entry to entry. Specially in the
    case of the \Md , due the fact that each module is different from
    the others and therefor other initialization, test, and diagnostics has
    to be executed. If such a structure is mapped into a fixed format one
    have to foreseen all possibilities which may occur during the live of
    such a data base. This allows no flexibility and absolutely no extension
    during the live. If that is necessary the whole data base has to be
    restructured, data base programs has to be modified or rewritten.
    {\em In the \EG\ project with our time constrains the modifications will
    be a problem if we have to change then all our programs which requires
    access to this data structures.}
 
   To overcome this problem the first point is to organize the records into a
    regular structure which will be used by all tables, including the fixed
    tables. This will be the record header with the following data entries
    \begin{rdes}{}[second item block]
     \ritem{length}{} total length of the record in bytes
     \ritem{ID}{} Identifier which record type. {\em Equivalent to the data
      base table}
     \ritem{next}{} pointer to next record (in the case of a variable heap
      organisation of the data base)
     \ritem{previous}{} backward pointer
     \ritem{status}{} status word for use by record type dependent
      software. The highest bit will be used as a lock bit to be able to
      synchronize the access in a multi task environment.
     \ritem{control}{} Control word for use by record type dependent software
     \ritem{N\_entries}{} Number of variable length items within this record
     \ritem{first item block}{}
     \ritem{second item block}{}
     %\ritem{ }{}
     \end{rdes}
    The item blocks are not part of the record header.
    The two pointers are required for the
    organisation of data base structures which will be generated on the fly
    which is the case for the \Vc\ and the \Ch\ table. These dynamic lists
    may change quite frequently. Furthermore that allows changes in the table
    structure on the fly by application programs, for example if one entry
    has to be removed from the channel table due to a malfunction.
 
   The item blocks consists out of two parts, a fixed header and a variable
    section which is defined by the item block identifier. This identifier is
    defined for each information block as a unique number.
    The following fields defines the item header:
    \begin{rdes}{}[lengthxx]
     \ritem{length}{} length of the item block, that's identical to the link
      to the next item block
     \ritem{ID}{} Item identifier.
     \ritem{variable part}{} the content of this field is defined by the
      identifier. This definition is available in the central data base, in
      include files which are generated out of the data base description,
      and in the application programs.
     \end{rdes}
 
   By using this structure a universal data base handling (the memory based
    part of it) can be used.
 
   For each database an information block is required which describes the
    attributes of the data base, the name of it and contains the pointer to the
    records. Depending on the type of the data base this root block contains
    an index or a header for a linked list structure. In principle it should
    be possible to describe the following types of organisation of the data
    base :
    \begin{enumerate}
     \item fixed length record, indexed \\ organised in form of an array
     \item linked list\\ This is a good organisation for small tables and in
      the case when pointers from an additional index data base will be used
      for access to such a table..
     \item linked list with local index\\ will be not used for VXI based data
      base
     \item hash index linked \\ will be not used by VXI data base
     \end{enumerate}
 
   Beside that further information is necessary to define the minimal and
    maximal length of a record, the number of records in the data base, and a
    control and status word for synchronization of the access to the database
    and to disable concurrent manipulation of the data base structure.
    Another important attribute is the information whether the data base is
    dumped into a disk file or not, or if that is only a memory based data
    base. In the case of a disk file the location and the name has to be
    stored in this database header structure.
    Practical reasons make it necessary to add an entry which tells the
    software where the definition of the data base will be found.
 
   In the following structure all fields in the header are described:
    \begin{rdes}{Data Base header}
     \ritem{length}{} length of the data base definition structure
     \ritem{name}{} name of the data base
     \ritem{type}{} which data base type (organisation, disk/memory based)
     \ritem{index header}{}
     \ritem{linked list header}{}
     \ritem{Disk file}{} path to the disk data file
     \ritem{Structure Definition file}{} filename and path to the structure
      definition of this data base table
     \ritem{N\_entry}{} Number of records in the table
     \ritem{Del\_pointer}{} Pointer to deleted data base records (linked list
      structure)
     \ritem{status}{} Status word: in memory, disk updated, ...
     \ritem{access control}{} Synchronization locks (organized as semaphore)
      used for manipulation of pointers, indexes, dump, read back, clean up,
      and index calculation
     \ritem{created}{} date and time of creation
     \ritem{modified}{} date and time of last modification of a data value
     \ritem{last entry}{} date and time of the last insertion of a record
     \ritem{last access}{} date and time of last access
     \ritem{reads}{} number of record reads in the data base
     \ritem{writes}{} number of record writes in the data base
     \ritem{locks}{} number of record locks in the data base
     \end{rdes}
 
   It is also necessary to have a common data base directory, where pointers
    to all databases used will be found. The organisation is a simple index
    with pointer to the data base description block, where as already shown
    all necessary information will be found.
 
   In the following some organisation details of the most important tables
    will be shown.
  \subsection{\Vc}
   The \Vc\ table contains all relevant information about all devices found
    in the VXI crate. It contains the links to all other tables.
    This information ha to be stored in the first item block.
   \begin{rdes}{}
     \ritem{LogDevAdd}{} logical device address
     \ritem{ControlStatus}{} Control and Status word
     \ritem{SlotNumber}{} Number of VXI slot in which the device will be found
     \ritem{DeviceNumber}{} VXI logical device number
     \ritem{ModuleDesc}{} pointer to the module description
     \ritem{AddressMap}{} pointer to the address map
     \ritem{Channel}{} pointer to the first \Ch\ entry
     \ritem{N\_channel}{} number of channels
     \ritem{VXICread}{} copy of VXI configuration registers as been read
     \ritem{VXICwrite}{} copy of VXI configuration registers as been written
     \ritem{extentions}{} extensions to the \Vc\ which will be added during
      a later step (e.q.\ configuration constants).
     \end{rdes}
   All other information will be found in the next item blocks (see therefore
    section \ref{VXIDB.VCitem}).
  \subsection{\Md}
   The \Md\ table contain the module description, initial, test, and
    diagnostic information. The table entry consists of an basic item block
    and several description blocks. The initial, test, and diagnostics
    descriptions are connected via linked lists to the basic item block as
    shown here. For each entry of the phase model there will be a own
    descriptor block (details will be found in
    \ref{VXIDB.MDini}, \ref{VXIDB.MDtst}, \ref{VXIDB.MDdiag}).
   \begin{rdes}{}
     \ritem{name}{} name of module
     \ritem{Btype}{} bus type identifier
     \ritem{ModuleID}{} Module identification number
     \ritem{N\_desc}{} number of module description entries
     \ritem{initial}{} pointer to initial block linked list
     \ritem{test}{} pointer to test block linked list
     \item{diag}{} pointer to diagnostics linked list
     \end{rdes}
 
   The basic organisation of that table is the form of a linked list. It will
    consist out of a small set of records ($ < 30$).
  \subsection{\Ch}
 
 \section{Structure and Item Code Definitions}
  \subsection{Record header }
   Structure definition:
    \begin{rdes}{DB Record header}[Previousxxxxxxxxxxxxxxx]
     \ritem{length}{unsigned short int} length of the record in bytes
     \ritem{ID}{unsigned short int} Identifier upper 8 bit defines the record
      type the lower 8 bit used for item and sub records
     \ritem{next}{unsigned int} address pointer to next record a relative
      form used.
     \ritem{previous}{unsigned int} address pointer to previous entry if a
      double linked list structure is used, or pointer to data base descriptor
     \ritem{control}{unsigned short int} Control word for use by record type
      dependent software
     \ritem{status}{unsigned char} status word for use by record type dependent
      software.
     \ritem{N\_entries}{unsigned char (0 ... 255)} Number of variable length
      items within this record
     \end{rdes}
   %Item definition:
    %\begin{rdes}{}
     %\ritem{}{}
     %\end{rdes}
  \subsection{Item header }
    \begin{rdes}{Item block header}[lengthxx]
     \ritem{length}{} length of the item block, that's identical to the link
      to the next item block
     \ritem{ID}{} Item identifier.
     \ritem{variable part}{} the content of this field is defined by the
      identifier. This definition is available in the central data base, in
      include files which are generated out of the data base description,
      and in the application programs.
     \end{rdes}
  \subsection{\Vs }
  \subsection{\Vd }
  \subsection{\Va }
  \subsection{\Vc }\label{VXIDB.VCitem}
  \subsection{\Md }
   \subsubsection{Description}
   \subsubsection{Initial}\label{VXIDB.MDini}
   \subsubsection{Test}\label{VXIDB.MDtst}
   \subsubsection{Diagnostics}\label{VXIDB.MDdiag}
  \subsection{\Ch }
 \end{document}