From: <ro...@us...> - 2009-04-17 21:02:05
|
Revision: 2130 http://nscldaq.svn.sourceforge.net/nscldaq/?rev=2130&view=rev Author: ron-fox Date: 2009-04-17 21:01:55 +0000 (Fri, 17 Apr 2009) Log Message: ----------- Document the SBS Readout software framework. Modified Paths: -------------- trunk/nextgen/docconfig/config trunk/nextgen/sbs/readout/CCAENV262Busy.h trunk/nextgen/sbs/readout/CReadoutMain.cpp trunk/nextgen/sbs/readout/CReadoutMain.h trunk/nextgen/sbs/readout/SBSReadout.xml trunk/nextgen/sbs/readout/Skeleton.cpp trunk/nextgen/sbs/readout/Skeleton.h Modified: trunk/nextgen/docconfig/config =================================================================== --- trunk/nextgen/docconfig/config 2009-04-14 22:31:00 UTC (rev 2129) +++ trunk/nextgen/docconfig/config 2009-04-17 21:01:55 UTC (rev 2130) @@ -1,2 +1,2 @@ commands utilities libraries servers frameworks -1daq 1epics 1tcl 1usbReadout 3daq 3tcl 3sbsReadout 3usbReadout +1daq 1epics 1tcl 1sbsReadout 1usbReadout 3daq 3tcl 3sbsReadout 3usbReadout Modified: trunk/nextgen/sbs/readout/CCAENV262Busy.h =================================================================== --- trunk/nextgen/sbs/readout/CCAENV262Busy.h 2009-04-14 22:31:00 UTC (rev 2129) +++ trunk/nextgen/sbs/readout/CCAENV262Busy.h 2009-04-17 21:01:55 UTC (rev 2130) @@ -43,7 +43,7 @@ private: CCaenIO& m_busy; public: - CCAENV262Busy(uint32_t base, unsigned crate); + CCAENV262Busy(uint32_t base, unsigned crate = 0); CCAENV262Busy(CCaenIO& module); CCAENV262Busy(const CCAENV262Busy& rhs); Modified: trunk/nextgen/sbs/readout/CReadoutMain.cpp =================================================================== --- trunk/nextgen/sbs/readout/CReadoutMain.cpp 2009-04-14 22:31:00 UTC (rev 2129) +++ trunk/nextgen/sbs/readout/CReadoutMain.cpp 2009-04-17 21:01:55 UTC (rev 2130) @@ -116,14 +116,14 @@ m_pExperiment = CreateExperiment(&parsedArgs); + // Add the application specific commands: + // Now initialize via the virtual functions. + addCommands(); - // State and run variables require the state/runvar manager - - CVariableBuffers* pVarbufs = new CVariableBuffers(*(getInterpreter())); SetupRunVariables(getInterpreter()); SetupStateVariables(getInterpreter()); @@ -141,10 +141,7 @@ } - // Add the application specific commands: - addCommands(); - // Setup our eventloop. @@ -241,10 +238,17 @@ CReadoutMain::addCommands() { CTCLInterpreter& interp(*getInterpreter()); - CRunControlPackage::getInstance(interp); + addCommands(&interp); // Trampoline to user's commands. } +void +CReadoutMain::addCommands(CTCLInterpreter* pInterp) { + CRunControlPackage::getInstance(*pInterp); + CVariableBuffers* pVarbufs = new CVariableBuffers(*pInterp); + +} + ////////////////////////////////////////////////////////////////////////////////////////////// /*! Modified: trunk/nextgen/sbs/readout/CReadoutMain.h =================================================================== --- trunk/nextgen/sbs/readout/CReadoutMain.h 2009-04-14 22:31:00 UTC (rev 2129) +++ trunk/nextgen/sbs/readout/CReadoutMain.h 2009-04-17 21:01:55 UTC (rev 2130) @@ -70,6 +70,7 @@ virtual void SetupReadout(CExperiment* pExperiment); virtual void SetupScalers(CExperiment* pExperiment); virtual void addCommands(); + virtual void addCommands(CTCLInterpreter* pInterp); protected: void startTclServer(std::string port); Modified: trunk/nextgen/sbs/readout/SBSReadout.xml =================================================================== --- trunk/nextgen/sbs/readout/SBSReadout.xml 2009-04-14 22:31:00 UTC (rev 2129) +++ trunk/nextgen/sbs/readout/SBSReadout.xml 2009-04-17 21:01:55 UTC (rev 2130) @@ -214,13 +214,13 @@ <varlistentry> <term><type>CCompoundEventSegment::EventSegmentIterator</type> <methodname>begin</methodname>()</term> - <listitemm> + <listitem> <para> Returns an iterator which 'points' to the beginning of the collection. Refer to the description below for information about iterators. </para> - </listitemm> + </listitem> </varlistentry> <varlistentry> <term><type>CCompoundEventSegment::EventSegmentIterator</type> @@ -546,21 +546,307 @@ <formalpara> <title>Busys</title> <para> - + During the time in which Readout is responding to a trigger it + is unable to accept a new trigger. During this time it is often + important to veto external electronics until the system is able to + accept the next trigger. This is the function of <firstterm>Busy</firstterm> + objects. </para> </formalpara> - + <para> + Busy objects are members of classes that are derived from + <classname>CBusy</classname> which has the following pure virtual + members: + </para> + <variablelist> + <varlistentry> + <term><type>void</type> <methodname>GoBusy</methodname></term> + <listitem> + <para> + This is called when due to software reasons the computer will + be unable to accept a trigger. For example, as the run ends. + It is important to note that the actual event by event busy should + be generated by hardware and then only cleared by software. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><type>void</type> <methodname>GoClear</methodname></term> + <listitem> + <para> + Called when the software is able to accept the next + trigger. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The readout framework provides + <link linkend='manpage.ccaenv262busy'><classname>CCAENV262Busy</classname></link>, + and + <link linkend='manpage.cv977busy'><classname>CV977Busy</classname></link> as + prebuilt busy classes. This, and any busy class you create must be + registered to be used. The example below shows the creation and + registration of a <classname>CV977Busy</classname> object to + manage the busy. The physicsal module is in VME crate 0 and has a base + address of 0x00444400. + </para> + <informalexample> + <programlisting> +#include <CV977Busy.h> +... +void +Skeleton::SetupReadout(CExperiment* pExperiment) +{ + ... + pExperiment->EstablishBusy(new CV977Busy(0x444400)); + ... +} + </programlisting> + </informalexample> </section> <section> <title>Obtaining and building the skeleton application</title> <para> + The readout framework provides a skeleton application that you + can extend to a create a real readout application. + This section provides best practice methods to obtain the skeleton + and build it. </para> + <para> + Framework skeletons are all installed in the <filename>skeletons</filename> + directory of the NSCLDAQ installation tree. The following example shows + how we recommend obtaining this skeleton and how to perform a test build + of the skeleton. + </para> + <example> + <title>Obtaining the SBS readout skeleton</title> + <programlisting> +cd ~ +mkdir -p experiment/readout +cd experiment/readout +cp $DAQROOT/skeletons/sbs/* . + +make + + </programlisting> + </example> + <para> + The example creates the directory + <filename>~/experiment/readout</filename>. + Next the skeleton files are copied to that directory. + <command>make</command> is used to do a test build of the skeleton. + </para> + <note> + <title>NOTE!</title> + <para> + By itself the skeleton cannot take any useful data. You must + modify it to meet you readout needs, and build the modified + version. See + <link linkend='sbsrdo.sec.skeleton'>"Modify8ing the skeleton application to meet your needs</link>, + the next section for information about how to do this. + </para> + </note> </section> <section id='sbsrdo.sec.skeleton'> <title>Modifying the skeleton application to meet your needs</title> <para> + The skeleton provides several member functions that are called + in a specific order. You should fill some or all of these member + function in with actual code to set up the framwork to do what + you want it to do. </para> + <para> + If you add additional source files, you should modify the + <filename>Makefile</filename> as well so that they are incorporated + into the build. The simplest way to do this is to add them to the + definition of the <literal>OBJECTS</literal>macro in the + <filename>Makefile</filename>. + </para> + <para> + Let's look at the member functions in <filename>Skeleton.cpp</filename> + that you may have to fill in. These are listed in order of likelyhood + you'll need or want to add code to them. Note that all of these members + invoke the base class member functions they override. This ensures that + important functionality provided by those members is provided. + </para> + <variablelist> + <varlistentry> + <term><type>void</type> <methodname>SetupReadout</methodname>( + <type>CExperiment*</type> <parameter>pExperiment</parameter> + )</term> + <listitem> + <para> + Fill in code here to setup the event by event reaout + part of the framework. Specific work you must do is: + <itemizedlist> + <listitem> + <para> + Create and register an event trigger. + </para> + </listitem> + <listitem> + <para> + Create event segments and glue them together + into a coherent event segment hierarchy. + </para> + </listitem> + <listitem> + <para> + Register the top end event segment hierarchy + elements in the experiment's top level event + segment so that they will be invoked + at appropriate times. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><type>void</type> <methodname>SetupScalers</methodname> ( + <type>CExperiment*</type> <parameter>pExperiment</parameter> + )</term> + <listitem> + <para> + Fill in code here to set up the scaler readout. + This involves: + </para> + <itemizedlist> + <listitem> + <para> + Create and register a scaler trigger. The + Skeleton provides sample code for registering + a timed trigger. + </para> + </listitem> + <listitem> + <para> + Create your scalers and glue them together + into a coherent scaler readout hierarchy via + scaler banks. + </para> + </listitem> + <listitem> + <para> + Register the top elements of the scaler readout + hierarchy with <parameter>pExperiment</parameter>'s + top level scaler bank so that your elements will + be invoked at the proper times. + </para> + </listitem> + + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term><type>void</type> <methodname>addCommands</methodname> ( + <type>CTCLInterpreter*</type> <parameter>pInterp</parameter> + )</term> + <listitem> + <para> + If you want to add application specific commands to the + framework, add them here. This is usually done by + writing subclasses derived from <classname>CObjectProcessor</classname>, + and creating an instance for each of these classes. + The comments prior to this method describe what you need + to do if you have existing procedural commands you want + to register. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><type>void</type> <methodname>SetupRunVariables</methodname> ( + <type>CTCLInterpreter*</type> <parameter>pInterp</parameter> + )</term> + <listitem> + <para> + If you want to setup some pre-existing run variables, but + don't want to use a script to do this, you can define + them here. The simplest way to define a runvar is to + create the appropriate <command>runvar</command> command + string and pass it to <parameter>pInterp</parameter>-><methodname>Eval</methodname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><type>void</type> <methodname>SetupStateVariables</methodname> ( + <type>CTCLInterpreter*</type> <parameter>pInterp</parameter> + )</term> + <listitem> + <para> + If you want to set up some pre-existing state variables, but + don't want to use a script to do this, you can define + them here. The simplest way to define a statevar is to + create the appropriate <command>statevar</command> command + string and passi to <parameter>pInterp</parameter>-><methodname>Eval</methodname>. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + <section id="sbsrdo.sec.commands"> + <title>Readout commands</title> + <para> + The SBS Readout framework automatically adds several commands. + These are described fully in the 1sbsReadout reference pages. + A brief summary of these commands is given here. + </para> + <para> + A cluster of commands allows you to perform run control operations. + These are the <command>begin</command>, <command>end</command>, + <command>pause</command> and <command>resume</command> commands. + </para> + <para> + The <command>begin</command> command also uses two Tcl global + variables to set the run state. These are: + <varname>title</varname> and <varname>run</varname>. + </para> + <para> + In addition the <command>statevar</command> and <command>runvar</command> + commands are defined. These allow the creation, listing and deleting + of Tcl variables that will be logged to the event stream periodically. + State variables are write-protected from Tcl scripts while the run is + active. Run variables can be modified during the active part of the + run. + </para> + <para> + Thus State variables are intended to log fixed unchanging parameters + of a run, such as documentation of the target, or beam ion or beam + species. Run variables are intended to log things that may change + over time, such as the temperature of the chamber, beamline magnet + readings and so on. + </para> + </section> + <section id='sbsrdo.sec.server'> + <title>Embedded Tcl server</title> + <para> + If requested, the readout program will run a Tcl server. This is + requested via the <option>--port</option> option when Readout is started. + If the value of the <option>--port</option> is an integer, that is + taken to be the port on which the server will listen for connections. + If the value of <option>--port</option> is <literal>managed</literal>, + the port manager will be contacted to dynamically allocate a port + for the <literal>Readout</literal> application. The server will + listen on that port. + </para> + <para> + One use of the tcl server is to modify run variables. For example, + an external program such as <application>controlpush</application> + can be run to data on specified EPICS process variables.l + </para> + </section> + <section id='sbsrdo.sec.running'> + <title>Running a readout application</title> + <para> + The readout application recognizes a few command options. + The full Readout command reference is described in + <link linkend='manpage.1sbsreadout'>Readout(1sbsReadout)</link>. + You can get a summary of the options by invoking Readout with + the <option>--help</option> option. + </para> + </section> </chapter> @@ -568,4 +854,3184 @@ <!-- manpage 3sbsReadout --> + <refentry id="manpage.cbusy"> + <refmeta> + <refentrytitle>CBusy</refentrytitle> + <manvolnum>3sbsReadout</manvolnum> + </refmeta> + <refnamediv> + <refname>CBusy</refname> + <refpurpose>Abstract base class for Busy module management.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <CBusy.h> + </programlisting> + <classsynopsis> + <ooclass><classname>CBusy</classname></ooclass> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>GoBusy</methodname> + <void /><modifier>=0</modifier> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>GoClear</methodname> + <void /><modifier>=0</modifier> + </methodsynopsis> + </classsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + <classname>CBusy</classname> is an abstract base class + for managing busy modules. When the Readout program accepts a + trigger, there is a <firstterm>deadtime</firstterm> during which it + is not able to accept subsequent trigger. External electronics often + needs to know when this deadtime is. + </para> + <para> + The normal way to provide a signal showing when the computer is busy + is to have some electronics module that acts like a latch. The + latch is set true by the trigger itself. Software clears the latch + when it is able to respond to the next trigger. + </para> + <para> + Concrete busy classes are created by deriving them from + <classname>CBusy</classname>. An instance of one of these concrete + classes should be created and registered with the + <link linkend='manpage.cexperiment'>CExperiment</link> + in <classname>Skeleton</classname>::<methodname>SetupReadout</methodname> + </para> + </refsect1> + <refsect1> + <title> + Public member functions + </title> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>GoBusy</methodname> + <void /><modifier>=0</modifier> + </methodsynopsis> + <para> + Pure virtual function the framework calls when, for software + reasons, it is about to be unable to respond to triggers for + some extended period of time. This will be called when data taking + is about to stop due to a <command>end</command> or + <command>pause</command> command. + </para> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>GoClear</methodname> + <void /><modifier>=0</modifier> + </methodsynopsis> + <para> + Pure virtual function the framework calls when it's about to be + able to respond to triggers. In addition to calling this + member after processing each trigger, the framework will invoke + this at some point just prior to starting data taking as a result + of a <command>begin</command> or <command>resume</command> + command. + </para> + </refsect1> + </refentry> + + + <refentry id="manpage.ccaenv262busy"> + <refmeta> + <refentrytitle>CCAENV262Busy</refentrytitle> + <manvolnum>3sbsReadout</manvolnum> + </refmeta> + <refnamediv> + <refname>CCAENV262Busy</refname> + <refpurpose>Concrete busy class for the CAEN V262 input module.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <CCAENV262Busy> + </programlisting> + <classsynopsis> + <ooclass><classname>CCAENV262Busy : public CBusy</classname></ooclass> + <constructorsynopsis> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <type>uint32_t</type> <parameter>base</parameter> + </methodparam> + <methodparam> + <type>unsigned</type> <parameter>crate</parameter> + </methodparam> + </constructorsynopsis> + <constructorsynopsis> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <type>CCaenIO&</type> <parameter>module</parameter> + </methodparam> + </constructorsynopsis> + <constructorsynopsis> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <modifier>const</modifier> <type>CCAENV262Busy&</type> + <parameter>rhs</parameter> + </methodparam> + </constructorsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>GoBusy</methodname> <void /> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>GoReady</methodname> <void /> + </methodsynopsis> + </classsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + This class uses the CAEN V262 I/O register to provide signals + needed to implement a computer busy. When you use this module, + module outputs have the following meanings: + <informaltable frame='all'> + <tgroup cols='2'> + <thead> + <row> + <entry>Output</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>SHP0</entry> + <entry><para>Computer is about to go busy for a long time</para></entry> + </row> + <row> + <entry>SHP1</entry> + <entry><para> + Computer is about to go ready.</para></entry> + </row> + <row> + <entry>SHP3</entry> + <entry><para> + Module clears are output just prior to releasing the + busy.</para></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + Note that <literal>SHP0</literal> is not a hardware signal. It means + that the computer is about to be busy due to data taking stopping or + pausing. To use this module you must have an external latch or + gate generator in latch mode. The latch should start on the OR + of the master trigger and <literal>SHP0</literal> it should clear + on <literal>SHP1</literal>. + </para> + <para> + The module clears are a convenience output and need not be used, however + if you can use them, this is quicker than clearing modules in software. + </para> + </refsect1> + <refsect1> + <title> + Public member functions + </title> + <methodsynopsis><type></type> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <type>uint32_t</type> <parameter>base</parameter> + </methodparam> + <methodparam> + <type>unsigned</type> <parameter>crate</parameter> + </methodparam> + </methodsynopsis> + <para> + Construct a busy object. <parameter>base</parameter> is the + base address of the V262 module and <parameter>crate</parameter> the + VME crate in which the module lives. <parameter>crate</parameter> + is an optional parameter that defaults to <literal>0</literal>. + </para> + <methodsynopsis><type></type> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <type>CCaenIO&</type> <parameter>module</parameter> + </methodparam> + </methodsynopsis> + <para> + Constructs a busy object. <parameter>module</parameter> is a + refererence to a <classname>CCaenIO</classname> module that + has already been constructed and will be the busy hardware + controlled by this object. + </para> + <methodsynopsis><type></type> + <methodname>CCAENV262Busy</methodname> + <methodparam> + <modifier>const</modifier> <type>CCAENV262Busy&</type> + <parameter>rhs</parameter> + </methodparam> + </methodsynopsis> + <para> + Copy constructs a new busy module that is a functional + equivalent to <parameter>rhs</parameter>. + </para> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>GoBusy</methodname> <void /> + </methodsynopsis> + <para> + Called by the framework to indicate the busy should + be asserted. This is not called in response to a gate. + Busy in response to a gate must happen at hardware speeds, + not software. + </para> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>GoReady</methodname> <void /> + </methodsynopsis> + <para> + Called by the framework to indicate it is able to react to + the next trigger. + </para> + </refsect1> + <refsect1> + <title>EXAMPLES</title> + <example> + <title>Creating and registering a V262 as a busy:</title> + <programlisting> +#include <CCAENV262Busy.h> +... +void +Skeleton::SetupReadout(CExperiment* pExperiment) +{ + ... + pExperiment->EstablishBusy(new CCAENV262(0x444400)); + ... +} + </programlisting> + </example> + </refsect1> + <refsect1> + <title> + SEE ALSO + </title> + <para> + <link linkend="manpage.cbusy">CBusy(3sbsReadout)</link> + <link linkend="CaenIO">CaenIO(3daq)</link> + <link linkend='manpage.ccaenv262trigger'>CCAENV262Trigger(3sbsReadout)</link> + </para> + </refsect1> + </refentry> + + <refentry id="manpage.ccaenv262trigger"> + <refmeta> + <refentrytitle>CCAENV262Triger</refentrytitle> + <manvolnum>3sbsReadout</manvolnum> + </refmeta> + <refnamediv> + <refname>CCAENV262Triger</refname> + <refpurpose>Trigger module with CAEN V262</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <CCAEANV262Trigger.h> + </programlisting> + <classsynopsis> + <ooclass><classname>CCAENV262Trigger : public CEventTrigger</classname></ooclass> + <constructorsynopsis> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <type>uint32_t</type> <parameter>base</parameter> + </methodparam> + <methodparam> + <type>unsigned</type> <parameter>crate</parameter> + <initializer>0</initializer> + </methodparam> + </constructorsynopsis> + <constructorsynopsis> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <type>CCaenIO&</type> <parameter>module</parameter> + </methodparam> + </constructorsynopsis> + <constructorsynopsis> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <modifier>const</modifier> + <type>CCAENV262Trigger&</type> <parameter>rhs</parameter> + </methodparam> + </constructorsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> <type>bool</type> + <methodname>operator()</methodname><void /> + </methodsynopsis> + </classsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + Implements a trigger class based on the hardware of the + CAEN V262 I/O register. When used as a triggerm odule, the + Following signals in the V262 have meaning: + <informaltable> + <tgroup cols='2'> + <thead> + <row> + <entry>Signal</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>IN0</entry> + <entry>Computer Master Gate (live)</entry> + </row> + <row> + <entry>SHP2</entry> + <entry><para> + Trigger acknowledge. The V262 does not latch signals + IN0 must be held true until SHP2 is signalled. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + <refsect1> + <title> + Public member functions + </title> + <methodsynopsis><type></type> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <type>uint32_t</type> <parameter>base</parameter> + </methodparam> + <methodparam> + <type>unsigned</type> <parameter>crate</parameter> + <initializer>0</initializer> + </methodparam> + </methodsynopsis> + <para> + Constructs a <classname>CCAENV262Trigger</classname> object. + The <parameter>base</parameter> parameter is the base address + of the CAEN V262 module to be used as a trigger. + The optional <parameter>crate</parameter> parameter specifies + which VME crate the module is in. If not supplied, + <parameter>crate</parameter> defaults to <literal>0</literal>. + </para> + <methodsynopsis> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <type>CCaenIO&</type> <parameter>module</parameter> + </methodparam> + </methodsynopsis> + <para> + Constructs a trigger object from an existing + <classname>CaenIO</classname> object. + <parameter>module</parameter> is the object that represents the + physical module that will be used as the trigger module. + </para> + <methodsynopsis> + <methodname>CCAENV262Trigger</methodname> + <methodparam> + <modifier>const</modifier> + <type>CCAENV262Trigger&</type> <parameter>rhs</parameter> + </methodparam> + </methodsynopsis> + <para> + Copy constructor. Contructs a trigger object from + <parameter>rhs</parameter>. + </para> + <methodsynopsis> + <modifier>virtual</modifier> <type>bool</type> + <methodname>operator()</methodname><void /> + </methodsynopsis> + <para> + The trigger poll function. When the framework is able to accept + triggers, it will poll this method. A <literal>true</literal> + return indicates the presence of the trigger. Note that + this function will also strobe the SHP2 output when it sees a trigger, + making this a possibly destructive read of the trigger. + </para> + </refsect1> + <refsect1> + <title>EXAMPLES</title> + <para> + </para> + </refsect1> + <refsect1> + <title> + SEE ALSO + </title> + <para> + <link linkend='CaenIO'>CaenIO(3daq)</link> + <link linkend='manpage.ccaenv262busy'>CCAENV262Busy(3sbsReadout)</link> + <link linkend='manpage.ceventtrigger'>CEventTrigger(3sbsReadout)</link> + </para> + </refsect1> + </refentry> + + + <refentry id="manpage.ccompoundeventsegment"> + <refmeta> + <refentrytitle>CCompoundEventSegment</refentrytitle> + <manvolnum>3sbsReadout</manvolnum> + </refmeta> + <refnamediv> + <refname>CCompoundEventSegment</refname> + <refpurpose>Container for other event segments</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <CCompoundEventSegment.h> + </programlisting> + <classsynopsis> + <ooclass><classname>CCompoundEventSegement : public CEventSegment</classname></ooclass> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>initialize</methodname> + <void /> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>clear</methodname> + <void /> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>disable</methodname> + <void /> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> <type>size_t</type> + <methodname>read</methodname> + <methodparam> + <type>void*</type> <parameter>pBuffer</parameter> + </methodparam> + <methodparam> + <type>size_t</type> <parameter>maxwords</parameter> + </methodparam> + </methodsynopsis> + <methodsynopsis> + <type>void</type> <methodname>AddEventSegment</methodname> + <methodparam> + <type>CEventSegment*</type> <parameter>pSegment</parameter> + </methodparam> + </methodsynopsis> + <methodsynopsis> + <type>void</type> <methodname>DeleteEventSegment</methodname> + <methodparam> + <type>CEventSegment*</type> <parameter>pSegment</parameter> + </methodparam> + </methodsynopsis> + <methodsynopsis> + <modifier>virtual</modifier> <type>bool</type> + <methodname>isComposite</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>EventSegmentIterator</type> + <methodname>begin</methodname> <void /> + </methodsynopsis> + <methodsynopsis> + <type>EventSegmentIterator</type> + <methodname>end</methodname><void /> + </methodsynopsis> + <methodsynopsis> + <type>size_t</type> + <methodname>size</methodname><void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>size_t</type> <methodname>leafCount</methodname> <void /> + </methodsynopsis> + <methodsynopsis> + <type>size_t</type> <methodname>fullCount</methodname><void /> + </methodsynopsis> + <methodsynopsis> + <type>void</type> <methodname>visit</methodname> + <methodparam> + <type>CVisitor&</type> <parameter>visitor</parameter> + </methodparam> + </methodsynopsis> + </classsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + <classname>CCompoundEventSegemnt</classname> provides an ordered + container for event segment objects (or rather pointers to event + segment objects). Since a <classname>CCompoundEventSegment</classname> + itself is an event segment you can build an arbitrarily deep hierarchy + of event segments using this class. + </para> + <para> + A rich set of facilities for navigating the event segment hierarchy + is provided though normally this hierarchy gets built at program initialization + time and is fixed throughout the lifetime of the program. Navigation models + include iteration and visitation. See Types and Public Data for + information about the class scoped data types that support these + models. + </para> + <para> + Event segments also provide a mechanism to determine if they are + containers via the <methodname>isComposite</methodname> member function. + </para> + </refsect1> + <refsect1> + <title> + Public member functions + </title> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>initialize</methodname> + <void /> + </methodsynopsis> + <para> + Part of the event segment interface. Does a deep initialization + of all events segments in the compound event segment. This is + done by calling the <methodname>initialize</methodname> + member on each element in the container. This implies that + if an element of the container is itself a compound event + segment, it's children will be recursively initialized. + </para> + <methodsynopsis> + <modifier>virtual</modifier> + <type>void</type> <methodname>clear</methodname> + <void /> + </methodsynopsis> + <para> + Part of the event segment interface. Does a deep clear of all + event segments. This is + done by calling the <methodname>clear</methodname> + member on each element in the container. This implies that + if an element of the container is itself a compound event + segment, it's children will be recursively cleared. + </para> + <methodsynopsis> + <modifier>virtual</modifier> <type>void</type> + <methodname>disable</methodname> + <void /> + </methodsynopsis> + <para> + Part of the event segment interface. Does a deep disable of all + event segments. This is + done by calling the <methodname>disable</methodname> + member on each element in the container. This implies that + if an element of the container is itself a compound event + segment, it's children will be recursively disabled. + </para> + <methodsynopsis> + <modifier>virtual</modifier> <type>size_t</type> + <methodname>read</methodname> + <methodparam> + <type>void*</type> <parameter>pBuffer</parameter> + </methodparam> + <methodparam> + <type>size_t</type> <parameter>maxwords</parameter> + </methodparam> + </methodsynopsis> + <para> + Part of the event segment interface. Does a deep read of all + event segments. This is + done by calling the <methodname>read</methodname> + member on each element in the container. This implies that + if an element of the container is itself a compound event + segment, it's children will be recursively read. + </para> + <para> + <parameter>pBuffer</parameter> points to the buffer into which + data should be read. <parameter>maxwords</parameter> is the + maximum number of words that can still fit in that buffer. + The method returns the number of words that were read by this + segment. + </para> + <methodsynopsis> + <type>void</type> <methodname>AddEventSegment</methodname> + <methodparam> + <type>CEventSegment*</type> <parameter>pSegment</parameter> + </methodparam> + </methodsynopsis> + <para> + Adds an event segment <parameter>pSegment</parameter> + to the end of the ordered container of + event segments in the compound. Very bad things will happen if + <parameter>pSegment</parameter>'s lifetime is not at least that of + the event segment. + </para> + <methodsynopsis> + <type>void</type> <methodname>DeleteEventSegment</methodname> + <methodparam> + <type>CEventSegment*</type> <parameter>pSegment</parameter> + </methodparam> + </methodsynopsis> + <para> + If <parameter>pSegment</parameter> is one of the immediate + children of the object, it is removed from the container. + If not, this is a no-op. Please note that this is not a deep + delete. If <parameter>pSegment</parameter> is actually a child + of some compound event segment in the container, it will not + be found and therefore not removed. + </para> + <para> + <parameter>pSegment</parameter> is removed from the container. + It is up to the calling software, if appropriate, to destroy + the actual object. + </para> + <methodsynopsis> + <modifier>virtual</modifier> <type>bool</type> + <methodname>isComposite</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <para> + This returns true. The member function <methodname>isComposite</methodname> + is provided in all event segments. It is true if the object + implements the interface of the compound event segment. + </para> + <methodsynopsis> + <type>EventSegmentIterator</type> + <methodname>begin</methodname> <void /> + </methodsynopsis> + <para> + Returns a begin of iteration iterator. See "Types and Public Data" + below for more about iterators. See as well <methodname>end</methodname> + below for typical usage. This iterator is a shallow iterator. + </para> + <methodsynopsis> + <type>EventSegmentIterator</type> + <methodname>end</methodname><void /> + </methodsynopsis> + <para> + Returns an iterator that points off the end of the container. + This can be used to determine when the iterator has visited + all members of the container. The function below shows a + typical usage. + </para> + <informalexample> + <programlisting> +CCompoundEventSegment es; +... +CCompoundEventSegment::EventSegmentIterator p = es.begin(); +while (p != es.end()) { + CEventSegment *pSegment = *p; + // + // Do something with pSegment: + ... + p++; +} + </programlisting> + </informalexample> + + <methodsynopsis> + <type>size_t</type> + <methodname>size</methodname><void /><modifier>const</modifier> + </methodsynopsis> + <para> + Returns the number of elements in the event segment container. + This is a shallow count. + </para> + <methodsynopsis> + <type>size_t</type> <methodname>leafCount</methodname> <void /> + </methodsynopsis> + <para> + Returns the number of 'terminal' nodes in the hierarchy. A + terminal node is one for which <methodname>isComposite</methodname> + returns <literal>false</literal>. This is a deep count. + </para> + <methodsynopsis> + <type>size_t</type> <methodname>fullCount</methodname><void /> + </methodsynopsis> + <para> + Returns the total number of nodes in the hiearchy. This is a deep + count. + </para> + <methodsynopsis> + <type>void</type> <methodname>visit</methodname> + <methodparam> + <type>CVisitor&</type> <parameter>visitor</parameter> + </methodparam> + </methodsynopsis> + <para> + Visits each node in the hieararchy and invokes the visitor + at each node at this level of the hierarchy. If deep visitation + is required, then whenever the visitor is handed a node for which + <methodname>isComposite</methodname> is true, it should invoke + this method on that node with itself as a parameter. + </para> + <para> + For more on the visitor class, see "Types and public data". + For a recipe for doing recursive visitation, see "EXAMPLES" + </para> + </refsect1> + <refsect1> + <title>Types and public data</title> + <para> + This class provides an iterator for its container; + <classname>CCompoundEventSegment::EventSegmentIterator</classname>. + This is a pointer like object. When dereferenced the iterator + returns a <type>CEventSegment*</type> for a segment that is in the + container. Increment moves the 'pointer' to the next item + in the container (shallow iteration). + </para> + <para> + The class provides an abstract base class on which Visitors can be + built: <classname>CCompoundEventSegment::CVisitor</classname>. + The definition of this class is shown below: + <informalexample> + <programlisting> + class CVisitor { + public: + virtual void operator()(CEventSegment* pSegment) = 0; + }; + </programlisting> + </informalexample> + </para> + <para> + The idea is that you would derive a class from that and + invoke the <methodname>visit</methodname> method with an object + of that class to do something to all nodes in the container. + </para> + </refsect1> + <refsect1> + <title>EXAMPLES</title> + <para> + This section shows how to do deep iteration both with visitors and + with iterators. The key is that whenever a compound is found + iteration or visitation is done recursively on that compond. + </para> + <example> + <title>Deep iteration of <classname>CCompondEventSegment</classname> elements</title> + <programlisting> +/* + Do something to all leaf nodes of the event segment + hierarchy +*/ +void doSomething(CCompoundEventSegment* pSegment) +{ + CCompoundEventSegment::EventSegmentIterator p = pSegment->begin(); + while (p != pSegment->end()) { + CEventSegment* pSeg = *p; + if (pSeg->isComposite()) { + doSomething(pSeg); // Recurse to go deep. + } + else { + // Do whatever needs doing here.... + } + p++; + } +} + </programlisting> + </example> + <example> + <title>Deep visitation of <classname>CCompoundEventSegment</classname> elements</title> + <programlisting> +class MyVisitor : public CCompoundEventSegment::CVisitor +{ + virtual void operator()(CEventSegment* pSeg) + { + if (pSeg->isCompound()) { + pSeg->visit(*this); + } + else { + // Do what needs doing to terminal nodes.... + } + } +}; +... +CCompoundEventSegment segment; +MyVisitor visitor; +segment.visit(visitor); // Visitor ensures deep visitation. + + </programlisting> + </example> + + </refsect1> + <refsect1> + <title> + SEE ALSO + </title> + <para> + <link linkend='manpage.ceventsegment'>CEventSegment(3sbsReadout)</link> + </para> + </refsect1> + </refentry> + + + <refentry id="manpage.cdocumentedpacket"> + <refmeta> + <refentrytitle>CDocumentedPacket</refentrytitle> + <manvolnum>3sbsReadout</manvolnum> + </refmeta> + <refnamediv> + <refname>CDocumentedPacket</refname> + <refpurpose>Encapsulate event data in a packet that is documented.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <CDocumentedPacket> + </programlisting> + <classsynopsis> + <ooclass><classname>CDocumentedPacket</classname></ooclass> + <constructorsynopsis> + <methodname>CDocumentedPacket</methodname> + <methodparam> + <type>unsigned short</type> <parameter>nTag</parameter> + </methodparam> + <methodparam> + <modifier>const</modifier> <type>std::string&</type> + <parameter>rName</parameter> + </methodparam> + <methodparam> + <modifier>const</modifier> <type>std::string&</type> + <parameter>Description</parameter> + </methodparam> + <methodparam> + <modifier>const</modifier> <type>std::string&</type> + <parameter>rVersion</parameter> + </methodparam> + </constructorsynopsis> + <methodsynopsis> + <type>int</type> <methodname>operator==</methodname> + <methodparam> + <modifier>const</modifier> <type>CDocumentedPacket&</type> + <parameter>rhs</parameter> + </methodparam> + <modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>int</type> <methodname>operator==</methodname> + <methodparam> + <modifier>const</modifier> <type>std::string&</type> + <parameter>rhs</parameter> + </methodparam> + <modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>int</type> <methodname>operator!=</methodname> + <methodparam> + <modifier>const</modifier> <type>CDocumentedPacket&</type> + <parameter>rhs</parameter> + </methodparam> + <modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>int</type> <methodname>operator!=</methodname> + <methodparam> + <modifier>const</modifier> <type>std::string&</type> + <parameter>rhs</parameter> + </methodparam> + <modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>unsigned short</type> <methodname>getTag</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>std::string</type> <methodname>getName</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>std::string</type> <methodname>getDescription</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>std::string</type> <methodname>getVersion</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>std::string</type> <methodname>getInstantiationDate</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>unsigned short*</type> <methodname>getHeaderPtr</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>bool</type> <methodname>getPacketInProgress</methodname> + <void /><modifier>const</modifier> + </methodsynopsis> + <methodsynopsis> + <type>std::string</type> <methodname>Format</methodname> + <void /> + </methodsynopsis> + <methodsynopsis> + <type>unsigned short*</type> <methodname>Begin</methodname> + <methodparam> + <type>unsigned short*</type> <parameter>rPointer</parameter> + </methodparam> + </methodsynopsis> + <methodsynopsis> + <type>unsigned short*</type> <methodname>End</methodname> + <methodparam> + <type>unsigned short*</type> <parameter>rBuffer</parameter> + </methodparam> + </methodsynopsis> + </classsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + NSCL data taking programs should try to emit self describing event + data. This is facilitated by providing code to support the generation + of <firstterm>packets</firstterm>. A packet is a chunk of event data + with a three word header. The first longword (32 bits), is the + number of words in the packet, including the header. The last word + of the header is an identifying code. The remainder of the packet + are the data read out for that identifying code. + </para> + <para> + <ulink url="http://groups.nscl.msu.edu/userinfo/daq/nscltags.html"> + http://groups.nscl.msu.edu/userinfo/daq/nscltags.html</ulink> + defines the set of identifiers (tags) that are defined. The tag assigner + for permanent devices is + <ulink url="mailto:ba...@ns...">bazin at nscl dot msu dot edu</ulink>. + Contact him if you need a new tag assigned. + </para> + ... [truncated message content] |