Menu
▾
▴
[Nscldaq-cvscommits] SF.net SVN: nscldaq:[2613] trunk/nextgen/usb
|
From: <ro...@us...> - 2012-01-05 15:42:33
|
Revision: 2613
http://nscldaq.svn.sourceforge.net/nscldaq/?rev=2613&view=rev
Author: ron-fox
Date: 2012-01-05 15:42:21 +0000 (Thu, 05 Jan 2012)
Log Message:
-----------
Replace this tree with stuff from spectrodaq
Removed Paths:
-------------
trunk/nextgen/usb/Makefile.am
trunk/nextgen/usb/acqcommon/
trunk/nextgen/usb/app/
trunk/nextgen/usb/output/
trunk/nextgen/usb/tclcommon/
trunk/nextgen/usb/tclserver/
trunk/nextgen/usb/threadcom/
trunk/nextgen/usb/usbFramework.xml
trunk/nextgen/usb/vmusb/
Deleted: trunk/nextgen/usb/Makefile.am
===================================================================
--- trunk/nextgen/usb/Makefile.am 2011-12-21 14:54:48 UTC (rev 2612)
+++ trunk/nextgen/usb/Makefile.am 2012-01-05 15:42:21 UTC (rev 2613)
@@ -1,7 +0,0 @@
-#
-# Builds the VM/CC usb software. It's important to build the common
-# code first:
-#
-SUBDIRS = threadcom tclcommon tclserver output acqcommon app vmusb
-
-EXTRA_DIST = usbFramework.xml
\ No newline at end of file
Deleted: trunk/nextgen/usb/usbFramework.xml
===================================================================
--- trunk/nextgen/usb/usbFramework.xml 2011-12-21 14:54:48 UTC (rev 2612)
+++ trunk/nextgen/usb/usbFramework.xml 2012-01-05 15:42:21 UTC (rev 2613)
@@ -1,3149 +0,0 @@
-<!-- chapter frameworks -->
-
-<chapter id="ch.usbframework">
- <title>Framework for xx-USB readout software</title>
- <para>
- This software provides a framework that can be specialized
- to produce readout software for the Wiener/JTEC USB controller modules.
- Specific implementations of readout programs for the
- <link linkend="ch.vmusbReadout">VM-USB (USB VME
- interface)</link>, and the CC-USB (USB CAMAC interface) have been written.
- </para>
- <para id="ch.vmusbReadout"></para>
- <para>
- This chapter consists of the following sections:
- <itemizedlist>
- <listitem>
- <para>
- <link linkend="ch.usbframework.introduction">Introduction</link>,
- an introduction to the framework, the devices it intended to
- support and how it works. Much of this can be skimmed by most
- people as it contains information intended for developers.
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="ch.usbframework.linking">Libraries and Linking</link>,
- Describes the
- set of libraries that make up the framework and how
- to compile and link against them.
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="ch.usbframework.using">Using the Framework</link>,
- Describes how to invoke specialized versions of the framework.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <section id="ch.usbframework.introduction">
- <title>Introduction</title>
- <para>
- Weiner/Jtec provide a pair of USB interfaces with similar capabilities.
- The VM-USB is a USB to VME interface, while the CC-USB is a USB
- to CAMAC interface. Both interfaces provide support for
- autonomous mode data taking.
- </para>
- <para>
- While the VM-USB and CC-USB are quite similar programmatically,
- they are different enough that separate readout programs are required
- for each interface. The commmon code has been extracted into this
- framework. The framework makes it possible to add capability to both
- programs in a central place, while providing better maintainability
- than a pair of completely separate programs would allow.
- </para>
- <para>
- The programs that result from building on this framework can
- be used with the Readout GUI, and provide data to the
- ring buffer based data distribution system of the NSCL DAQ.
- The remainder of this section describes the architecture of the framework.
- If you are not building support for an xx-USB like controller you can
- probably ignore much of the remainder of this section.
- </para>
- <para>
- For information about specific specializations of this software, see
- the chapters that describe that specialization.
- </para>
- <section>
- <title>Active Software Structure</title>
- <para>
- The running framework must solve the following set of problems:
- <itemizedlist>
- <listitem>
- <para>
- When data taking is active, the VM-USB works
- best if there is always a read pending on its event
- data pipe.
- </para>
- </listitem>
- <listitem>
- <para>
- The user interface, must always be live to allow an
- active data taking run to be stopped.
- </para>
- </listitem>
- <listitem>
- <para>
- The format of the data from the xx-USB devices requires
- a bit of device dependent massaging before it can
- be inserted into ring buffers.
- </para>
- </listitem>
- <listitem>
- <para>
- Only one program can interact with the xx-USB device,
- though external programs may wish to interact with
- slow control devices that can only be contacted via
- the USB interface...even while data taking is active.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- All of these concerns have led to a multithreaded programming framework.
- Each thread has a distinct set of functions it fulfills:
- <variablelist>
- <varlistentry>
- <term>Main</term>
- <listitem>
- <para>The main thread is an extended Tcl interpreter.
- It is responsible for starting all of the other
- threads that are persistent (see below), and
- adding commands to the interpreter so that
- runs can be started, paused, resumed and stopped.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Readout</term>
- <listitem>
- <para>
- This thread is started by the main thread when a
- run begins. It sets up the USB device for
- data taking and processes buffers from that
- device.
- </para>
- <para>
- Per buffer processing is quite limited. Buffers
- are simply placed in an output queue for processing
- by the Output thread (see below).
- </para>
- <para>
- Between buffer arrivals and when buffer reads time out,
- the readout program examines a request queue.
- The request queue can have entries from the
- main thread requesting it to pause or end data taking.
- A Server thread (see below), and also request a
- pause in data taking so that slow control devices
- can be accessed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Output</term>
- <listitem>
- <para>
- This thread takes buffer from the Readout thread's
- output queue and turns events in them them into
- the appropriate items in a ring buffer.
- The ring buffer name is the same as the name of the user
- running the program. This allows several users to
- take data on the same system simultaneously (but not one user to take
- data from multiple sources on the same system).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Server</term>
- <listitem>
- <para>
- This thread listens on a TCP/IP port. Connecting
- clients are then allowed to send commands that
- perform slow control. The server interacts,
- if needed with Readout to halt data taking
- while it plays with devices.
- </para>
- <para>
- The
- Server is actually an extended Tcl interpreter,
- with the extensions providing the commands for
- slow control
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </section>
- <section>
- <title>Logical Software Structure</title>
- <para>
- The logical software structure must solve the following set of
- problems:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Each USB device must be controlled slightly differently
- by the Readout thread, and the software should only
- be allowed to connect with the correct type of
- interface.
- </para>
- </listitem>
- <listitem>
- <para>
- The format of data in the output buffers may be
- different from device to device.
- </para>
- </listitem>
- <listitem>
- <para>
- Each interface will have support for a different set
- of acquisition and control modules, and how they
- set up their lists is an interface specific
- thing.
- </para>
- </listitem>
-
- </itemizedlist>
- <para>
- We will next describe the base classes that can be extended to provide
- device specific functionality and, in general terms, the how to
- do these extensions. The reference material will provide
- detailed descriptions of these classes. The source code
- in the <filename>usb/vmusb</filename> and
- <filename>usb/ccusb</filename> directories serves as example
- code that you can look at by downloading the source code distribution
- of the NSCL DAQ software.
- </para>
- <section>
- <title>Configurable Objects and Data taking modules</title>
- <para>
- Objects which take data usually must be configured.
- This is done by interpreting a configuration script
- in a slave, extended interpreter. The USB Readout
- framework provides support to make the creation
- of configurable device support relatively simple.
- </para>
- <para>
- The core of this is the <classname>CConfiguration</classname>
- object. This is created by the framework. Device specific code
- provides commands for the configuration object, and devices
- themselves, provide configuration options they understand.
- Configuration options are name value pairs. By convention names
- start with a <literal>-</literal>. For example
- <literal>-base</literal> is usually the name of the configuration
- option that specifies a VME module's base address in the
- VM-USB specialization of this software.
- </para>
- <para>
- Let's take this a bit at a time starting with the actual device
- support modules.
- </para>
- <para>
- Each device is a class that is derived (usually indirectly)
- from <classname>CConfigurableObject</classname>.
- <classname>CConfigurableObject</classname> objects have
- a protected member data; <varname>m_pConfiguration</varname>.
- That member points to a <classname>CItemConfiguration</classname>
- object that holds the configuration for the module as well as
- definitions of the configurable parameters of the module.
- </para>
- <para>
- Key member functions of the <classname>CItemConfiguration</classname>
- are shown below. See the reference material for more:
- </para>
- <variablelist>
- <varlistentry>
- <term><function>addParameter</function></term>
- <listitem>
- <para>
- Allows you to define a configuration parameter.
- Configuration parameters can have
- <firstterm>validator</firstterm> functions
- attached to them. Validators allow the
- object to determine if an attempt to
- provide a specific value for a configuration
- parameter is legal. For example, the
- <literal>-base</literal> configuration
- parameter should not be able to accept
- <literal>george</literal>, but might be able to accept
- <literal>0xdead0000</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><function>configure</function></term>
- <listitem>
- <para>
- Allows a caller to attempt to provide a value for
- a configuration item.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>cget</function></term>
- <listitem>
- <para>
- Allows you to retrieve the string value of a
- configuration parameter.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><function>getIntegerParameter</function>,
- <function>getUnsignedParameter</function>,
- <function>getBoolParameter</function>,
- <function>getFloatparameter</function>
- <function>getIntegerList</function>
- </term>
- <listitem>
- <para>
- Provide ways to fetch a configuration item
- and interpret it as a type other than a string.
- If you use these, you should supply a validator
- with the configuration item that ensures
- the item will have strings of the correct type.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>validators</term>
- <listitem>
- <para>
- The class provides several static functions that
- perform common validations. For example,
- <function>CItemConfiguration::isInteger</function>
- ensures that a value is an integer, optionally
- checking it against range constraints.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- <classname>CConfigurableObject</classname> objects therefore,
- are what the name implies. Objects that have a configuration.
- <classname>CConfigurableObject</classname> objects use a
- two stage construction. The object is constructed, and then
- a <classname>CItemConfiguration</classname> is attached to the
- object via the <methodname>Attach</methodname> member.
- This allows for objects to have configurations that are
- subclasses of <classname>CItemConfiguration</classname>.
- </para>
- <para>
- <classname>CConfigurableObject</classname> is an abstract
- base class. It uses the <methodname>onAttache</methodname>
- pure virtual member function, supplied by your derived
- classes to define the configuration parameters an object
- supports.
- </para>
- <para>
- Other member functions of interest (see the reference material
- for more information):
- </para>
- <variablelist>
- <varlistentry>
- <term><methodname>Attach</methodname></term>
- <listitem>
- <para>
- Call this to attach a configuration to an object.
- The function will establish this as the new
- configuration and call <methodname>onAttache</methodname>
- which is expected to define accepted configuration
- parameters, their validity checkers and constraints.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>configure</methodname></term>
- <listitem>
- <para>
- Delegates to the configuration's
- <methodname>configure</methodname> method.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>cget</methodname></term>
- <listitem>
- <para>
- Delegates to the configuration's
- <methodname>cget</methodname> method.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- Typically each xx-USB specific program will want to
- add a set of methods that know how to initialize
- a module and how to contribute a module's readout instructions
- to a list.
- </para>
- <para>
- When the Readout thread starts, it runs a configuration Tcl
- script. That script is supposed to have commands that
- create modules and organize them into lists that
- can be associated with legal xx-USB triggers.
- </para>
- <para>
- The object that runs that script is the <classname>CConfiguration</classname>
- object. A pointer to that object is stored in <varname>::Globals::pConfig</varname>
- </para>
- <para>
- The <classname>CConfiguration</classname> maintains modules as a collection of
- named <classname>CConfigurableObject</classname> pointers. In addition, each
- object can have a type associated with it (types are strings).
- </para>
- <para>
- The <classname>CConfiguration</classname>
- also maintains the interpreter used to process the
- configuration script. The interpreter can have
- additional command registered on it.
- These command are typically commands that
- allow the script to create module support objects.
- </para>
- <para>
- When constructing an object, these commands must
- create an appropriate <classname>CConfigurableObject</classname>,
- attach an item configuration to it and make it known to the configuration.
- </para>
- <para>
- <classname>CConfiguration</classname> has the following key member functions:
- For more information see the reference pages.
- </para>
- <variablelist>
- <varlistentry>
- <term><methodname>addObject</methodname></term>
- <listitem>
- <para>
- Adds an object to the configuration. The object
- must have an item configuration attached to it
- as it will probably be configured later on
- during program execution.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>getObjectsOfType</methodname></term>
- <listitem>
- <para>
- Returns a vector of the objects that match
- a specific type. This would typically be called
- by the xx-USB specific setup code. For example,
- the VM-USB defines a <literal>stack</literal>
- type to represent the readout lists.
- It requests a list of all the <literal>stack</literal>
- objects, asks each to initialize its modules,
- create its list and then loads each list into
- the interface.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>findObjectByName</methodname></term>
- <listitem>
- <para>
- Locates an object given a name. This is often used
- by container objects and by command objects to
- ensure the existence of objects or to
- ensure that a new object will not clash in name
- with an existing object.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>addCommand</methodname></term>
- <listitem>
- <para>
- Adds a new command object to the interpreter that
- processes configuration files.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>clearConfiguration</methodname></term>
- <listitem>
- <para>
- Clears the set of modules from the configuration.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </section>
- <section>
- <title>The Device Driver and the Readout Thread</title>
- <para>
- The Readout thread makes use of a pair of software
- design patterns. <classname>CAcquisitionThread</classname>
- is a singleton object, having a <methodname>getInstance</methodname>
- member function that returns a pointer to the object, creating it
- if necessary. The object itself uses a strategy pattern to
- encapsulate the code that is interface dependent. The
- <methodname>setDriver</methodname> provides a pointer to a
- <classname>CUSBDeviceDriver</classname> derived object
- that has methods that handle the device specific requests.
- </para>
- <para>
- Each specific reealization of the code must implement
- code that calls <methodname>setDriver</methodname> passing
- the appropriate device driver object. The driver must
- implement the following interface:
- </para>
- <variablelist>
- <varlistentry>
- <term><methodname>usbToAutonomous</methodname></term>
- <listitem>
- <para>
- Starts the device taking data autonomously.
- Once started, typically these devices cannnot do
- anything other than send you data until stopped.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbReadBuffer</methodname></term>
- <listitem>
- <para>
- Read a block of data from the device. This is intended
- to read a block of data acquired in autonomous mode.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbSetup</methodname></term>
- <listitem>
- <para>
- Prepares the device for data taking.
- This includes figuring out the lists to load
- loading and enabling them. This will be called
- prior to <methodname>usbToAutonomous</methodname>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbGetBufferSize</methodname></term>
- <listitem>
- <para>
- Returns the size of a data taking buffer. This
- size will be used in buffer allocation and
- future calls to <methodname>usbReadBuffer</methodname>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbStopAutonomous</methodname></term>
- <listitem>
- <para>
- Halts autonomous data taking mode in the device.
- Following a call to this, you can expect several
- more calls to <methodname>usbReadBuffer</methodname>
- to flush data in the USB FIFOs.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>isusbLastBuffer</methodname></term>
- <listitem>
- <para>
- Returns <literal>true</literal> when given a
- buffer if the buffer is the last one
- from a data taking run. This is used by the
- data flush methods to determine when the flush
- is complete.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbGroinKick</methodname></term>
- <listitem>
- <para>
- This aptly named method is called by the
- readout code when it thinks the controller has
- hung. It is supposed to take drastic action
- to attempt to unhang the controller.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>usbFlushGarbage</methodname></term>
- <listitem>
- <para>
- Intended to throw away any trash that might be
- lingering in a usb controler FIFO. This
- function should read and discard data
- until it believes the usb FIFO's are empty.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section>
- <title>Configuring supported slow control modules</title>
- <para>
- The framework supports a Tcl server that performs slow
- control operations on the behalf of client software.
- Typically, client software is a GUI that connects to the
- Tcl server in the Readout engine to perform slow control
- operations. This implies that the Readout software must
- be running for these applications to work.
- </para>
- <para>
- The framework is open with respect to control devices.
- Control devices are described in a configuration file.
- The configuration file is a Tcl script like all other
- configuration files in the usb Readout framework.
- It is processed by a slave interpreter at program start-time.
- A control configuration file must exist, even if it is empty.
- </para>
- <para>
- Prior to that time, the set of device driver modules for
- control modules must be described to the Tcl Server framework
- so that it knows how to interact with these devices as well
- as how to interpret the control configuration script.
- </para>
- <para>
- The prototype pattern is used to describe to the Tcl server
- the types of modules that can be created. The prototype
- pattern creates objects by duplicating existing objects.
- For each control module type that is supported, a driver
- module must be registered with the Tcl server and given
- a device module type name.
- </para>
- <para>
- When a module of that type is created, the Tcl server
- duplicates the prototype driver and associates it with
- the module name so that it can be used to control the
- module.
- </para>
- <para>
- The <classname>TclServer</classname> class contains
- a method named <methodname>addPrototype</methodname>
- which is used to add a prototype driver to the
- Tcl server.
- </para>
- <para>
- Device drivers themselves are derived from the
- <classname>CControlModule</classname> abstract base
- class. device drivers for slow control objects are assumed
- to have some set of named parameters that can be set
- or retrieved. Furthermore, device drivers are derived
- from <classname>CConfigurableObject</classname> so they
- include a <classname>CItemConfiguration</classname> and
- can therefore support configuration options.
- Drivers must implement
- the following members (see the reference material for full
- documentation):
- </para>
- <variablelist>
- <varlistentry>
- <term><methodname>Initialize</methodname></term>
- <listitem>
- <para>
- Called when a device is specified in the
- configuration file. This method is intended
- to connect the device to the driver, and optionally
- set it to a known state. This is an optional
- method, as a no-op default is provided.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>onAttach</methodname></term>
- <listitem>
- <para>
- Called when the object is connected to
- its configuration object. The driver
- should define the set of configuration
- options supported by the device.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>Update</methodname></term>
- <listitem>
- <para>
- Some devices are write only. This is called
- to allow drivers to massively update their
- internal copy of the device state back to the
- device.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>Set</methodname></term>
- <listitem>
- <para>
- Sets a named parameter in the module to a specific
- value. The name and value are not interpreted
- or validated by the caller in any way. See the
- reference pages for more information about that,
- and how drivers should report errors.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>Get</methodname></term>
- <listitem>
- <para>
- Return the current value of a named parameter.
- The name is not validated by the caller.
- See the reference pages for more information
- about how to handle and report error
- conditions.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>clone</methodname></term>
- <listitem>
- <para>
- Produces a copy of the object. This is called
- by the Tcl server to turn the prototype instance
- of a device driver into an instance of the device
- driver that is bound to a device.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- Usually, a two-level derivation scheme is used to make
- controller specific device drivers. The first level creates
- a device driver that is still asbstract, but implements the
- methods above that interact with the hardware in such a way
- that they delegate to identical methods that also get passed
- a controller object. The second level implements specific
- device support by using the controller arguments to interact
- with the hardware.
- </para>
- </section>
- <section>
- <title>The Application object, and the entry point.</title>
- <para>
- When the system is being started up, the pieces and parts
- of the system must be created and knit together. Furthermore,
- threads objects must be created and started.
- </para>
- <para>
- While this process is mostly device independent, there are
- points in the process where device dependent configuration
- must be performed. A template method pattern is used to
- implement this.
- </para>
- <para>
- The <classname>CApplication</classname> class contains the
- controller independent implementation sections of code.
- These invoke pure virtual methods that are expected to implement
- the device dependent pieces of the startup process.
- </para>
- <para>
- The following are key methods for the <classname>CApplication</classname>
- class and its subclasses.
- </para>
- <variablelist>
- <varlistentry>
- <term><methodname>main</methodname></term>
- <listitem>
- <para>
- This is the entry point for the initialization.
- Typically, the program main will create
- the specialized application object and then
- invoke its main entry. See the example
- below; which is code taken from the
- <application>VMUSBReadout</application>
- specialization of this framework.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>selectInterface</methodname></term>
- <listitem>
- <para>
- Called to select and access a USB interface
- of the appropriate type. This method should
- create a device driver object appropriate to the
- interface, and bind that device driver object into
- the acquisition thread.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>setupConfiguration</methodname></term>
- <listitem>
- <para>
- Called to set up the daq configuration object so
- that it is extended with the commands needed to
- create the daq device driver objects.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>setupTclServer</methodname></term>
- <listitem>
- <para>
- Called to set up the Tcl server, by stocking it
- with the appropriate set of template device drivers.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>startOutputThread</methodname></term>
- <listitem>
- <para>
- Recall that the outupt thread is derived from
- a common base class and specialized for the
- specific device via a template design pattern.
- This member is called so that the correct
- <classname>COutputThread</classname> subclass
- object can be created and started.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><methodname>createBuffers</methodname></term>
- <listitem>
- <para>
- Buffer sizes depend on the interface. This
- member function is called to create the
- buffers in the buffer pool that will be filled
- by USB reads with event data.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <example>
- <title>Sample main code</title>
- <programlisting>
-<![CDATA[
-int
-main(int argc, char** argv)
-{
- App theApp;
- return theApp.main(argc, argv);
-}
-
-
-]]>
- </programlisting>
- </example>
- <para>
- The sample code aboveis the main program for the
- VMUSBReadout program. The <classname>App</classname>
- class is the specialization of
- <classname>CApplication</classname> for the
- VM-USB. An instance of that class is created and control
- transferred to its <methodname>main</methodname> method which
- initializes and runs the framework.
- </para>
- </section>
- </section>
- </section>
- <section id="ch.usbframework.linking">
- <title>Libraries and Linking</title>
- <para>
- The framework is made up of tons of libraries and headers.
- The headers are all located in the
- <filename>include</filename> subdirectory of your installation.
- The libraries are in the <filename>lib</filename> subdirectory.
- </para>
- <para>
- Therefore, when you are compiling a module in a
- specialization of the framework,
- you will need to have something like the following (<literal>daqroot</literal>
- is assumed to point to the base of the DAQ intallation directory tree):
- </para>
- <example>
- <title>Compiling modules in the USB readout framework</title>
- <programlisting>
-g++ -c -I$daqroot/include yourmodule.cpp
- </programlisting>
- </example>
- <para>
- When linking you will need to specify the location of thelibraries
- as well as a ton of libraries. Suppose you have crammed all of your
- specializations into one file that has been compiled to
- <filename>tailoring.o</filename> (I don't recommend actually doing
- this).
- </para>
- <example>
- <title>Linking specialized frameworks</title>
- <programlisting>
-gcc -o myapp tailoring.o -L$daqroot/lib \
- -lusbacqcommon -lusbtclcommon -lOutputStage \
- -lThreadComm -lusbapplication -lControlServer \
- -ldaqthreads -ltcl -lusb
- </programlisting>
- </example>
- <para>
- Note that on some/many Linux installations
- <literal>-ltcl</literal> may need to be replaced by a versioned
- library e.g. <literal>-ltcl8.4</literal>, or a link may need to be
- made to establish the 'default' version of Tcl.
- </para>
- </section>
- <section id="ch.usbframework.using">
- <title>Using the Framework</title>
- <para>
- An extension of the framework results in a program. The
- program accepts a set of command line switches.
- These switches are parsed by the
- <methodname>main</methodname> member function of the
- <classname>CApplication</classname> object.0
- </para>
- <para>
- The following switches are supported:
- </para>
- <variablelist>
- <varlistentry>
- <term><option>--help</option></term>
- <listitem>
- <para>
- Prints brief help that descripts the options supported
- by the program.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--version</option></term>
- <listitem>
- <para>
- Prints the program version and exits.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--daqconfig</option>=<replaceable>filename</replaceable></term>
- <listitem>
- <para>
- Overrides the default value of the readout configuration script.
- By default, the readout configuration script it
- <filename>~/config/daqconfig.tcl</filename>
- </para>
- <para>
- Note that if the configuration file has errors, they will
- not be detected until a run is started. Note as well,
- the configuration file is processed for each begin run,
- so it can be changed between runs to reflect
- changes in your hardware, without needing to restart
- the program.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--ctlconfig</option>=<replaceable>filename</replaceable></term>
- <listitem>
- <para>
- Overrides the default control configuration file. By default,
- the control configuration script is
- <filename>~/config/ctlconfig.tcl</filename>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--port</option>=<replaceable>portspec</replaceable></term>
- <listitem>
- <para>
- Overrides the default port specification. <replaceable>portspec</replaceable>
- The port specification determines which port the application
- listens on for slow control connections. The
- <replaceable>portspec</replaceable> can either be an integer port
- number that must not be in use by any other server in the system,
- or it can be the string <literal>managed</literal> in which the
- port manager will be requested to allocated a port for a
- service named <literal>SlowControls</literal>. See, however
- <option>--application</option> below.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>--application</option>=<replaceable>name</replaceable></term>
- <listitem>
- <para>
- If the port manager is used to allocate a port to the
- slow controls TclServer, this overrides the default
- application name of <literal>SlowControls</literal> with
- the one specified by <replaceable>name</replaceable>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-</chapter>
-
-
-
-<!-- /chapter -->
-
-<!-- usb not tclplus -->
-<!-- manpage 3usbReadout -->
-
-
- <refentry id="manpage.cconfiguration">
- <refmeta>
- <refentrytitle>CConfiguration</refentrytitle>
- <manvolnum>3usbReadout</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>CConfiguration</refname>
- <refpurpose>Provide a collection of <classname>CConfigurableObject</classname>s.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <programlisting>
-#include <CConfiguration.h>
- </programlisting>
- <classsynopsis>
- <ooclass><classname>Configuration</classname></ooclass>
- <constructorsynopsis>
- <methodname>CConfiguration</methodname>
- <void />
- </constructorsynopsis>
- <destructorsynopsis>
- <modifier>virtual</modifier> <methodname>~CConfiguration</methodname>
- <void />
- </destructorsynopsis>
- <methodsynopsis>
- <type>void</type>
- <methodname>processConfiguration</methodname>
- <methodparam>
- <type>std::string</type> <parameter>configFile</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>void</type> <methodname>addObject</methodname>
- <methodparam>
- <type>std::string</type> <parameter>name</parameter>
- </methodparam>
- <methodparam>
- <type>std::string</type> <parameter>type</parameter>
- </methodparam>
- <methodparam>
- <type>CConfigurableObject*</type> <parameter>pObject</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>void</type> <methodname>setResult</methodname>
- <methodparam>
- <type>std::string</type> <parameter>result</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>std::vector<ConfigItem></type>
- <methodname>getObjectsOfType</methodname>
- <methodparam>
- <type>std::string</type> <parameter>type</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>ConfigurationIterator</type>
- <methodname>findObjectByName</methodname>
- <methodparam>
- <type>std::string</type> <parameter>name</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>ConfigurationIterator</type>
- <methodname>end</methodname> <void />
- </methodsynopsis>
- <methodsynopsis>
- <type>void</type> <methodname>addCommandM</methodname>
- <methodparam>
- <type>CTCLObjectProcessor&</type> <parameter>processor</parameter>
- </methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>void</type> <methodname>clearConfiguration</methodname>
- <void />
- </methodsynopsis>
- <methodsynopsis>
- <type>CTCLInterpreter*</type> <methodname>getInterpreter</methodname>
- <void />
- </methodsynopsis>
- </classsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>Description</title>
- <para>
- This class contains a collection of pointers to <classname>CConfigurableObject</classname>s.
- Since these are pointers, derived classes can live in this collection as well.
- Each object has a name and type associated with it, that are simple text strings.
- </para>
- <para>
- Search functions are provided. An object with a specific name
- can be searched for. All objects of a specified type can also
- be found.
- </para>
- <para>
- A member function also exists to read in the configuration from
- a file, under the assumption that the serialized collection
- can be represented by a Tcl script that has been extended
- appropriately.
- </para>
- </refsect1>
- <refsect1>
- <title>
- Public member functions
- </title>
- <methodsynopsis>
- <methodname>CConfiguration</methodname>
- <void />
- </methodsynopsis>
- <para>
- Constructs a configuration. Note that it is at this point that
- a Tcl interpreter is constructed as well. The same Tcl interpreter
- is re-used over and over again to process configuration files, if
- they the <methodname>processConfiguration</methodname> method is
- called several times.
- </para>
- <methodsynopsis>
- <modifier>virtual</modifier> <methodname>~CConfiguration</methodname>
- <void />
- </methodsynopsis>
- <para>Destructor</para>
- <methodsynopsis>
- <type>void</type>
- <methodname>processConfiguration</methodname>
- <methodparam>
- <type>std::string</type> <parameter>configFile</parameter>
- </methodparam>
- </methodsynopsis>
- <para>
- Processes the file named <parameter>configFile</parameter>
- as a script in the object's interpreter. Normally, this
- interpreter has been extended with commands that support
- the creation of configuration items, which are added via
- <methodname>addObject</methodname> and manipulation of those
- objects. This allows the script to influence the contents of
- the configuration collection.
- </para>
- <para>
- Prior to processing the configuration script, the configuration
- is cleared. The same interpreter is used over and over again,
- however placing the onus on the script writer to ensure that the
- interpreter state is reasonable.
- </para>
- <methodsynopsis>
- <type>void</type> <methodname>addObject</methodname>
- <methodparam>
- <type>std::string</type> <parameter>name</parameter>
- </methodparam>
- <methodparam>
- <type>std::string</type> <parameter>type</parameter>
- </methodparam>
- <methodparam>
- <type>CConfigurableObject*</type> <parameter>pObject</parameter>
- </methodparam>
- </methodsynopsis>
- <para>
- Adds an object pointed to by
- <parameter>pObject</parameter>
- to the configuration. <parameter>name</parameter>
- provides a name that should be unique across all objects.
- Functions that call <methodname>addObject</methodname> should
- ensure that there are no objects that have that name already, or else
- the new object will be masked by the existing object.
- </para>
- <para>
- Objects also have a type. The type is specified by the
- <parameter>type</parameter> parameter. Generally objects
- that have the same final type should have the same textual type.
- </para>
- <methodsynopsis>
- <type>void</type> <methodname>setResult</methodname>
- <methodparam>
- <typ...
[truncated message content] |