cvmusb

Name

cvmusb -- SWIG Tcl wrapping of CVMUSB

Synopsis

package require cvmusb

Device enumeration and identification.

::cvmusb::CVMUSB_enumerate

::cvmusb::CVMUSB_usb_device_vector_get enumeration i

::cvmusb::CVMUSB_usb_device_vector_size enumeration

::cvmusb::CVMUSB_serialNo usbdevice

Construction.

::cvmusb::CVMUSB name usbdevice

::cvmusb::CVMUSB name -this usb-object-ptr

VM-USB register operations.

object readBulkXferSetup

object readDAQSettings

object readDGG_A

object readDGG_B

object readDGG_Extended

object readDeviceSource

object readFirmwareID

object readGlobalMode

object readIrqMask

object readLEDSource

object readScalerA

object readScalerB

object readVector

object createReadoutList

object writeActionRegister value

object writeBulkXferSetup value

object writeDAQSettings value

object writeDGG_A value

object writeDGG_B value

object writeDGG_Extended value

object writeDeviceSource value

object writeGlobalMode value

object writeIrqMask value

object writeLEDSource value

object writeVector which value

VME operations.

object vmeBlockRead base amod xfers

object vmeFifoRead base amod xfers

object vmeRead16 address amod

object vmeRead32 address amod

object vmeRead8 address amod

object vmeReadBlockCount16 address mask amod

object vmeReadBlockCount32 address mask amod

object vmeReadBlockCount8 address mask amod

object vmeVariableBlockRead address mask amod

object vmeVariableFifoRead address mask amod

object vmeWrite16 address amod data

object vmeWrite32 address amod data

object vmeWrite8 address amod data

List operations.

object executeList list maxbytes

object loadList number list offset

Miscellaneous operations.

object setDefaultTimeout ms

::cvmusb::CVMUSB_getuint16 uint16

::cvmusb::CVMUSB_string_to_char std_string

::cvmusb::CVMUSB_uint32_vector_get std_uint32_vector i

::cvmusb::CVMUSB_uint32_vector_size std_uint32_vector

::cvmusb::CVMUSB_uint8_vector_get std_uint8_vector i

::cvmusb::CVMUSB_uint8_vector_size std_uint8_vector

DESCRIPTION

This package provides a tcl interface to the CVMUSB class described in CVMUSB(3). See COMMANDS below for more information.

COMMANDS

Device enumeration and identification. The commands in this section are used to determine the set of VM-USB controllers attached to the host and identify them by serial number.

::cvmusb::CVMUSB_enumerate

Enumerates the set of VM-USB devices that are attached to and powered up on the host. The result of this command is usb_device_vector. You can think of this as a sort of an array with integer indices whose elements represent a single VM-USB device. See below for commands that can manipulate this vector.

::cvmusb::CVMUSB_usb_device_vector_get enumeration i

Given the result of the ::cvmusb::CVMUSB_enumerate command enumeration and an integer index i, returns a single element of the enumerated device set. The return value is of type usb_device and can be passed to the constructor, to create a controller object that talks to this device or to cvmusb::CVMUSB_serialNo to get the device's serial number string.

::cvmusb::CVMUSB_usb_device_vector_size enumeration

Given a enumeration gotten from ::cvmusb::CVMUSB_enumerate, returns the number of elements in that array. The array is indexed from 0.

::cvmusb::CVMUSB_serialNo usbdevice

Given a usbdevice returned from ::cvmusb::CVMUSB_usb_device_vector_get Returns the serial number string. Note that this is not immediately usable but must be converted to a Tcl string via a call to ::cvmsusb::CVMUSB_string_to_char described below.

Construction. This set of commands is used to construct CVMUSB objects. The return value of these constructors is a command. The command can be either explicitly named by the name parameter in each of these constructors or you can use the name %AUTO to allow constructors to generate a unique object command name.

::cvmusb::CVMUSB name usbdevice

Creates a new CVMUSB object given a usbdevice gotten from ::cvmusb::CVMUSB_usb_device_vector_get. This results in a new command name unless name is the special value %AUTO, in which case a unique name will be assigned the object.

Naturally if you use %AUTO as the name you must capture the actual name in a Tcl variable e.g.:


set controller [::cvmusb::CVMUSB %AUTO $device]
$controller some method
                

::cvmusb::CVMUSB name -this usb-object-ptr

Constructs a VMUSB object given a usb-object-ptr object pointer. This is normally used to wrap a pointer to a C++ underlying object passsed into a method from compiled code (e.g in the Tcl driver Initialize method).

VM-USB register operations. These methods all require a constructed VM-USB object object and write internal registers of the VM-USB. It is beyond the scope of this document to fully describe these registers. For each method, therefore, a high level description will be given along with the VM-USB reference manual section that does fully describe the register.

object readBulkXferSetup

Returns the current value of the USB Bulk transfer register. This register is described in section 3.4.10. It can be used to tune performance of the USB interface by setting the number of buffers that can be streamed without a packet end signal.

object readDAQSettings

Returns the current value of the Data acquisition settings register. This register is described in section 3.4.3 of the VM-USB manual. It contains bit fields that control the way in which the scaler stack is trigggered and the delay between a trigger and stack start. Note that within the VM-USB readout framework, this register is programmed by the framework at the start of each run. You will only need to program this register if you are building pure Tcl applications with the VM-USB.

object readDGG_A

Reads the contents of the VM-USB A gate and delay generator. The VM-USB has two internal Gate and delay generators named A and B. Section 3.4.6 describes the registers that control these resources. The bit fields in this register control the gate width and delay of the A gate and delay generator.

object readDGG_B

Same as readDGGG_A but the register for the B gate and delay register is read.

object readDGG_Extended

Returns the value of the extended gate and delay generator register. This supplies high order bits for the delay values for both the A and B DGG's.

object readDeviceSource

Reads the device source register. This register, described in section 3.4.5 defines the sources for the the NIM outputs, the internal scalers and the starts for the gate generators.

object readFirmwareID

Returns the current firmware revision level of the controller. The bit fields of this register are defined in section 3.4.1 of the VM-USB manual.

object readGlobalMode

Reads the module's global mode register (see VM-USB manual secgtion 3.4.2). This register sets the VME bus request level, as well as several data acquisition options.

object readIrqMask

This reads a shadow regiseter that remembers the last value written to the VM-USB's interrupt request mask register (see section 3.5 of the VM-USB manual). This is a write only register. Therefore, when you create a CVMUSB object, the value of the register is set to all ones which disables all interrupts. Remember to set interrupt enable bits if you use interrupt triggered stacks.

object readLEDSource

Reads the LED source selectors register. This is described in section 3.4.4 of the VM-USB manual. The registser allows you to determine the cirumstances which light each of the four LED's on the VM-USB front panel.

object readScalerA

The VM-USB has a pair of 32 bit scalers, Scaler A and B. These are descsribed in section 3.4.7 of the VM-USB manual. This method returns the value of scaler A's counter.

object readScalerB

The VM-USB has a pair of 32 bit scalers, Scaler A and B. These are descsribed in section 3.4.7 of the VM-USB manual. This method returns the value of scaler B's counter.

object readVector which

Reads the value of the interrupt vector register designated by which The vector registers are described in section 3.4.8 of the VM-USB Manual. The VM-USB supports triggering stacks as a result of an interrupt on the VME bus. To do this, an interrupt service vector register must be programmed with the IPL, the vector and stack id. The interrupt sevice vectors are in pairs numbered 1-4. This function returns one of those pairs.

object writeActionRegister value

Writes the value to the action register. This register is responsible for starting data acquisition mode and can be used to trigger lists. It is a write only register that is described in section 3.1 of the VM-USB manual.

object writeBulkXferSetup value

Writes value to the bulk transfer setup register described in section 3.4.10 of the VM-USB manual. This register allows sophisiticated users to optimize the bandwidth of the USB during event data transfer.

object writeDAQSettings value

Writes value to the data acquisition settings register described in sectino 3.4.3 of the VM-USB manual. TYhat register allows you to determine how the scaler stack is triggered as well as the delay betrweena stack trigger and the start of stack execution.

object writeDGG_A value

Writes value to the A delay and gate generator. The gate and delay generator registers are described in section 3.4.6 of the VM-USB manual.

object writeDGG_B value

Same as above but writes to the B delay and gate generator register.

object writeDGG_Extended value

Writes the gate and delay extended delay register. This is provides the ability to run very long delays.

object writeDeviceSource value

Writes value to the users device sources selection register described in section 3.4.5 of the VM-USB manual. This determines what is gated to the NIM 0/1 outputs, the Scaler inputs and the gate and delay generator inputs.

object writeGlobalMode value

Writes value to the global mode register described in section 3.4.2 of the VM-USB manual. This sets a variety of data acquisition parameters as well as the VM-USB bus request level.

object writeIrqMask value

Writes the interrupt request mask register. This register is desacribed in section 3.5 and describes the set of interrupt priority levels the VM-USB responds to. See also writeVector.

object writeLEDSource value

Writes value the LED source register described in section 3.4.4 of the VM-USB manual. This register determines the conditions under which the four programmable LEDS on the front panel of the VM-USB light.

object writeVector which value

Writes one of the four vector registers (numbered [1-4]) described in section 3.4.8. These allow stacks to be triggered by specific VME interrupts. Note that at present there is no support to write the interrupt extension bits registers as virtually all VME interrupters use 8-bit vectors.

VME operations. This section describes the methods that perform VME actions. Single shot read operations return the value read, howver block reads return an std::vector which requires further calls to obtain the actual number of items read and to fish out individual items.

VME operations target an address within an address space. The address space is seleted by what in VME parlance is called an address modifier. A table of address modifiers is available on the Wikipedia article describing the VME bus: http://en.wikipedia.org/wiki/VMEbus.

The documentation that describes each module describes the set of address modifiers it supports. Modules occupy an address space whose base is generally configured by switches, jumpers or rotary switches. The module documentation will describe both the size and contents of its address space as well as how the base address is determined.

object vmeBlockRead base amod xfers

Performs a block read from the the VME bus. The source is determined by the base address and the address modifier (amod). At most xfers transfers will be performed. The block transfer may terminate prematurely if a bus error occurs during the transfer.

The result of the block read is returned as an item that is encapsulates a std::vector<uint32_t>. See ::cvmusb::CVMUSB_uint32_vector_size which will return the actual number of transfers performed. ::cvmusb::CVMUSB_uint32_vector_get allows you to extract individual values from the data returned.

Suitable address modifiers force the VME bus to run in block transfer mode. In that mode, Addresses cycles are only performed infrequently with the source device keeping track of the offset from the last address cycle. If the module providing the data supports block transfer address modifiers, substantial peformance gains can be had by using it.

object vmeFifoRead base amod xfers

This method is the same as vmeBlockRead however all address cycles assert the base address. This makes the operation suitable for address blocks that actually implement FIFO memories.

Consider, for example the data buffer address block of a large group of CAEN 32 bit digitizers run in multi-event mode read out via a chained block transfer. If a block read is used to read this module, it is possible for the address to increment off the end of the window that is recognized as the data buffer. Using a FIFO read ensures this cannot happen.

object vmeRead16 address amod

Performs a single 16 bit transfer from address in the address space selected by amod The result of the command is word that was read.

object vmeRead32 address amod

Same as vmeRead16 however a 32 bit read is performed.

object vmeRead8 address amod

Same as vmeRead16 however a 16 bit read is performed.

object vmeReadBlockCount16 address mask amod

The VM-USB provides the ability to do a variable sized block read. When using this facility you first perform a VME read operation to obtain the number of transfers in the block read. You then perform the block read itself

The block read count is a field in the data transferred from the VME address/amod specified by a mask. This method performs an 16 bit read from the VME bus and uses the mask provided to determine which bits constitute the transfer size. The resulting block transfer size is saved for the variable block transfer operation which should immediately follow.

object vmeReadBlockCount32 address mask amod

Same as vmeReadBlockCount16 however the read is 32 bits wide.

object vmeReadBlockCount8 address mask amod

Same as vmeReadBlockCount16 however the data transfer is 8 bits wide.

object vmeVariableBlockRead address mask maxcount

Performs a variable block read whose transfer count was determined by one of the previous three methods. The transfer base address is specified by address/amod. maxcount is used to allocate aninternal buffer fro the transfer and can further limit the number of transfers. The return value from this method is the same as a return value from vmeBlockRead

object vmeVariableFifoRead address mask amod

Same as vmeVariableBlockRead however all address cycles provide address as the address making this suitable as a block read froma FIFO. The return value is the same as from vmeBlockRead.

object vmeWrite16 address amod data

Performs a single shot 16 bit write of data to the VME target specified by address/amod. The least significant bits of data are written.

object vmeWrite32 address amod data

Same as vmeWrite16 however 32bits of data are written.

object vmeWrite8 address amod data

Same as vmeWrite16, however only the least significant 8 bits of data are written.

List operations. The VM-USB allows you to build and execute lists of VME operations. These are built up using cvmusbreadoutlist. Lists can also be downloaded for execution in data acquisition mode when triggered.

object executeList list maxbytes

Executes a list of instructions. list is a cvmusbreadoutlist object or pointer. mabytes is the maximum number of bytes of data that miight be returned from this list as a result of the reado operations it contains. This is used to size an internal buffer into which that data are accepted.

The return value from this command is a std::vector<uint8_t>. See cvmusb::CVMUSB_uint8_vector_size and cvmusb::CVMUSB_uint8_vector_get for information about how to get data ouf of this object.

object loadList number list offset

Loads a list into the VM-USB for execution in response to a trigger in data taking mode. list is a cvmusbreadoutlist object. number is the stack number and must be in the range [0..7]. offset is the memory offset at which the list should be loaded. See CVMUSB::loadList for information about how to compute this.

Miscellaneous operations. This section describes methods that don't fit into a convenient category. Many of these are static methods that provide impedance matching between the data types in use in the CVMUSB underlying class ansd Tcl data types.

object setDefaultTimeout ms

Sets the default timeout of VM-USB operations as ms milliseconds. This timeout is used to define how long most of the methods in this section will wait for a response from the VM-USB before giving up.

::cvmusb::CVMUSB_getuint16 uint16

Given a uint16_t Returns an integer that has the same value This is needed because SWIG thinks that uint16_t is some fancy object type and will not allow it to be shimmered to an int.

::cvmusb::CVMUSB_string_to_char std_string

Given an std::string, returns a string that Tcl can deal with.

::cvmusb::CVMUSB_uint32_vector_get std_uint32_vector i

Given a std::vector<uint32_t> (std_uint32_vector) returns element i.

::cvmusb::CVMUSB_uint32_vector_size std_uint32_vector

Given std_uint32_vector a std::vector<uint32_t> returns the number of elements it contains. Elements are indexed from zero.

::cvmusb::CVMUSB_uint8_vector_get std_uint8_vector i

Same as ::cvmusb::CVMUSB_uint32_vector_get but std_uint8_vector is a std::vector<uint8_t>.

::cvmusb::CVMUSB_uint8_vector_size std_uint8_vector

Same as ::cvmusb::CVMUSB_uint32_vector_size but std_uint8_vector is a std::vector<uint8_t>