68.4. Tcl device driver support

68.4.1. Conceptual background

If you have not read the section on writing C++ device drivers you should at least skim it. Several of the concepts are important. Specifically:

• A device support module provides a command that generates device instances.

• Device instances have to provide an Initialize method that initializes the device according to some configuration of the instance.

• Device instances have to provide a addReadoutList method that adds elements to the list of CAMAC operations that are executed when the stack they live in is triggered.

All of this is a natural match to the way all of the object oriented extensions to Tcl work. Specifically you write a class like thing. Creating an instance of the class creates a new Tcl command ensemble. The public methods of the instance become sub commands of the new Tcl command.

The CCUSB framework therefore provides a mechanism, the addtcldriver command to add an object instance command to the set of devices that can be added to a stack. The addtcldriver command registers the command name as a name of a device that can be put in a stack. The command ensemble is also wrapped in an actual driver that invokes Initialize, and addReadoutList methods at the appropriate times.

The final piece of the puzzle is providing access to the CCUSB and CCUSBReadout list capabilities to Tcl drivers. This has been done by wrapping Tcl command ensembles around both of those classes using SWIG (see http://www.swig.org).

As we will see when we work our way through sample drivers, the C++ wrappers are not able to actually pass a SWIG wrapped object to the driver methods. The driver must take the swig pointer like parameter and turn it into a SWIG object before it can be used. A Tcl fragment that shows how to turn the CCCUSB pointer into a SWIG CCCUSB object is shown below:

...
method Initialize ccusbPointer {
    cccusb::CCCUSB c -this $ccusbPointer
    ...
}
...
                

The example takes the ccusbPointer parameter which must be a swig like pointer to a CCCUSB object and turns it in to a swig object named c which is a SWIG object representing the underlying CCCUSB passed in to the Initialize method.

68.4.2. A sample snit Tcl CCUSB framework driver

This section will go through a sample snit driver describing how it works. To see this driver incorporated in a DAQ configuration file see Section 68.4.4.

First a word or two about snit. Snit is a pure Tcl object oriented framework for Tcl written by Will Duquette from the Jet Propulsion Laboratory in Pasadena. http://wiki.tcl.tk/3963 provides access to documentation and examples of snit in action.

snit is part of the TclLib which is installed on all systems at the NSCL.

Snit classes are created via the snit::type command. Snit classes feature methods which are analagous to member functions in C++ classes.

snit also provides all types with a configure and cget command and a mechanism for declaring options that can be manipulated by these commands. Using this capability allows you to configure snit device driver instances in a manner analagous to the C++ driver instances supported by the CCUSB framework.

Below is a complete implementation of a snit driver that, at initialization time turns on the yellow LED and adds a marker to the readout list. The marker value can be configured via the instances built in configure subcommand.

lappend auto_path /usr/opt/daq/10.1/lib  

package require snit                    
package require cccusb                  
package require cccusbreadoutlist


snit::type marker-snit {                
    option -value 0                     

    #
    # Called when the run is being started.  
    # 
    # @param driverPtr - 'pointer' to the CCUSB object.
    #
    method Initialize driverPtr {      

 
        cccusb::CCCUSB c -this $driverPtr; 

        # Get the led programming now
        # Yellow is the mask of FF0000
        # Clear out those bits and set that field to be 110000 which is source I3 and
        # inverted.

        set leds [c readLedSelector]      
        set leds [expr {$leds &  0xffff}]
        set leds [expr {$leds | 0x110000}]
        c writeLedSelector $leds         

    }
    # Called to contribute to the readout list
    #   
    # @param list - 'pointer' to the CCCUSBReadoutList which will be wrapped in a
    #                swig wrapper.
    #
    method addReadoutList list {       

        #
        # Wrap the list so we can use it:
        #
        cccusbreadoutlist::CCCUSBReadoutList l -this $list; 

        l addMarker $options(-value)                        (11)

    }
}

                

The numbers in the explanations below refer to the corresponding numbers in the example text.

68.4.3. A sample Incr-Tcl Tcl CCUSB framework driver

Incr Tcl is an object oriented extension for Tcl. It is installed on all NSCL systems. It provides the ability to define classes. As with snit, creating a class instance (object) creates a new command. The public class methods are then subcommands for the object command.

As with snit, objects can have configurations that are manipulated and queried via built in config and cget object subcommands. Unlike snit, all public member variables are considered to be configurable objects to Incr Tcl.

The properties above make Incr Tcl a viable option for implementing driver support.

http://incrtcl.sourceforge.net/itcl/ provides information about Incr Tcl.

The example below shows a marker driver identical in functionality to the snit driver shown in the previous section, but written with Incr Tcl.

lappend auto_path /usr/opt/daq/10.1/lib
puts $auto_path
package require Itcl                       
package require cccusb
package require cccusbreadoutlist

itcl::class marker-itcl {                 
    public variable value 0               

    #
    # Called when the run is being started.  
    # 
    # @param driverPtr - 'pointer' to the CCUSB object.
    #
    public method Initialize driverPtr {  

        #  This turns the driver pointer into a CCUSB object which
        #  can make use of the SWIG wrappers for the CCUSB code:

        cccusb::CCCUSB c -this $driverPtr; # c is a CAMAC controller object.

        # Get the led programming now
        # Yellow is the mask of FF0000
        # Clear out those bits and set that field to be 110000 which is source I3 and
        # inverted.

        set leds [c readLedSelector]
        set leds [expr {$leds &  0xffff}]
        set leds [expr {$leds | 0x110000}]
        c writeLedSelector $leds

    }
    # Called to contribute to the readout list
    #   
    # @param list - 'pointer' to the CCCUSBReadoutList which will be wrapped in a
    #                swig wrapper.
    #
    public method addReadoutList list {               

        #
        # Wrap the list so we can use it:
        #
        cccusbreadoutlist::CCCUSBReadoutList l -this $list; # l is now a swig wrapper over the list.

        l addMarker $value                          

    }

                

The numbers in the explanations below refer to the numbers in the example above.

68.4.4. Using Tcl drivers in the DAQ configuration file.

Using a Tcl driver in the DAQ configuration file requires that you

• Incorporate the driver code into your DAQ configuration script.

• Create device instances for the hardware you want read out by your experiment.

• Register the device instances with the CCUSB frameowork so that they can be referred to in stack or other module containing commands.

• Add the instances to a stack

The source command allows you to include a specific Tcl script file given a relative or absolute path directly to that script. Suppose our device support file named mydriver.tcl is located in the same directory as the configuration script. The code fragment below is an accepted way to source that file that doesn ot assume the current working directory is where the script is:

set here [file dirname [info script]]
source [file join $here mydriver.tcl]
                

The first command determines the directory that holds the script while the second uses that to construct a path to the mydriver.tcl file for the source command.

If you develop a library of device support code, or are using someone else's device support code, it is probably preferable to use the Tcl package command, pkgIndex.tcl and package search paths to load the driver code.

The author of the driver code you are using must have cooperated to the extent of having a package provide command in their scripts, and creating a pkgIndex.tcl (through e.g. Tcl's pkg_mkIndex command) in the directories holding their packagtes.

Once this is done you can append the script package directories to your auto_path variable and use package require to pull in the required files.

Suppose, for example, /projects/mydetector/drivers is a directory that contains several device support scripts given package names like device1 device2, suppose further that you are running in conjunction with another system that has device3 in /projects/otherdetector/drivers. The following script fragment uses the Tcl package facility to load those drivers:

lappend auto_path /projects/mydetector/drivers /projects/otherdetector/drivers
package require device1
package require device2
package require device3
                

Furthermore, by using the TCLLIBPATH rather than the auto_path variable you can make it so that your script does not need to know which directories have package files.

marker-snit create snitmarker
                

creates an instance of the driver named snitmarker. The base name of the resulting command ensemble is also snitmarker. In the case of our Incr Tcl driver:

marker-itcl itclmarker
                

Creates an instance whose name is itclmarker and whose instance command is itclmarker

Once created, how you configure the device depends on the framework used to build the driver. For both the snit and Incr Tcl examples, the configure command can be used to configure the object instance:

instance-command configure -value 0x1234
                

The addtcldriver command associated a Tcl instance command with a module name:

addtcldriver snitmarker
                

Creates a module name snitmarker that is associated with the snitmarker instance of the marker-snit driver.

Given this discussion, here is a fragment of a daq cofiguration script:

...
set here [file dirname [info script]]

source [file join $here testdriver-snit.tcl]
marker-snit create snitmarker
snitmarker configure -value 0x5678
addtcldriver snitmarker

source [file join $here testdriver-itcl.tcl]
marker-itcl itclmarker
itclmarker configure -value 0xfafa
addtcldriver itclmarker


# testing and tdc were defined earlier by 'normal' commands.,

stack create events
stack config events -modules [list itclmarker snitmarker testing tdc] -type event -delay 108