package require sis330x
sis330x name ?options...?
name configure option value ?...?
addtcldriver name
This driver provides a simplified driver for the SIS 3300/3301 FADC family. The driver provides three modes of operation for the device:
In start mode an external start input is required to start digitization. Digitization stops either when the desired number of samples have been acquired or when an external stop input is provided.
The start input is the second from the top (input 3). The stop input is the third from the top (input 2).
In stop mode, the digitizer is continuously digitizing. Digitization then stops when an NIM pulse is presented to input 2 (third from the top).
Note that in stop mode, the actual acquired data my not be at the beginning of the digitizer data. See OUPUT DATA FORMAT below for more information.
In gate mode, a gate signal is presented to the start input (input 3 second from the top). digitization begins on the falling edge of the gate and ends on the rising edge of the gate, or when the maximum number of samples has been acquired (if the gate is wider than the time required to digitize the maximum number of samples).
-base
base-addressSets the VME base address of the module. For the 3300, this is set via jumpers that control the top four bits of VME address. For the 3301, this is set via a pair of rotary switches that allow the top eight bits of the VME address to be set.
-clock
source-specSets the digitizer clock source. This can be one of several internal clock frequencies available or one the external clock modes. The default clock source is 100Mhz The valid clock sources are:
Selects an internal clock source at the specified frequency. The default value is
The clock is provided as an external symmetric pulse train on input 4 (top input). See section 2.5.2 of the SIS330x manual for information about the signal requriements for this clock.
Allows arbitray clock trains or slow clocks. The internal logic runs at 100Mhz. On each falling edge of the external clock, data are digitized by the next falling edge of the internal clock and transferred to the buffer memory 10 interal clocks later.
Runs in HiRa random clock mode. This is suitable for use with the Wash-U multiplexing front end boards. Note that new applications should make use of XLM boards with integrated digitizers rather than the XLM + SIS3301 pair.
-mode
start | stop | gateSelects the mode of the digitizer. Defaults to start mode. See DESCRIPTION above for a summary of the modes. Note that start and stop modes represent special use cases of the digitizers's start/stop trigger mode while gate is the digitizer's gate trigger mode.
The -mode
selected can affect the
way you need to decode the data from each event.
See OUTPUT DATA FORMAT below
for more information.
-startdelay
disabled | valueIf the value of this option is disabled, the start delay is not enabled. Otherwise, the value must be a positive integer in the range [0,65535] and is the number of clock ticks the digitizer start is delayed before actually being applied.
This option defaults to disabled.
-stopdelay
disabled | value
Same as -startdelay
above, however
the delay, if enabled, applies to the stop time.
Defaults to disabled
-samples
valueSelects the maximum number of sample that will be acquired. This defaults to 128K. The following values are allowed: 128K, 16K, 4K, 2K, 1K, 512, 256, 128. Note that the K multiplier in the list above means 1024.
It is possible that fewer than -samples
will be acquired. This can happen in:
In start mode if there is a stop input that fires to the time required to digitize all samples.
In stop mode if the stop comes soon enough after the digitizer is started by the VMUSB that not all the samples have been digitized.
In gate mode if the gate is narrower than the time required to digitize all samples.
The data structure allows you to determine if this is the case. See OUTPUT DATA FORMAT for information about this.
This option defaults to 128K
-thresholdslt
listA list of 8 booleans, one per digitizer channel. If a list element is true, the channel threshold is applied for a crossing from above to below the threshold. If false, the channel threshold is applied to a crossing from below the threshold to above it.
See -thresholds
below for more information.
Defaults to an 8 element list of false
-thresholds
list
A list of 8 integer in the range [0,4096)
for the SIS 3300 and [0,16384) for
the SIS3301. If the input signal crosses this value
in the direction specified by the corresponding
-thresholdslt
value,
a pulse is sent on the trigger output (bottom lemo).
This pulse can be cabled to the start or stop input to directly trigger the digitizer or sent to external trigger logic as a term in a more complex trigger scheme.
The default value is a list of 8 16383 values.
-minletime
list
This parameter is a list of four integers, one per channel
group that
specifies the minimum number of clock ticks the trace
in a group must
be below the threshold to result in a trigger when a channel's
thresholdslt
value is true.
This defaults to a list of 40 which disables the
use of this parameter. The value must be in the range
[0, 16). A value of 0
disables the enforcement of this parameter.
Defaults to a list of four 0 values
-mingttime
list
Same as -minletime
except that
this specifies the number of consecutive clock ticks a
channel must be above the threshold value when
-thresholdslt
for the channels
is false..
As with -minletime
, this defaults to
a list of four 0 values.
-trigwidth
listList of four integers in the range [0,16), one for each group of two channels. If the value for a group is 0 (the default), the settable output gate width feature is disabled. Otherwise, this value represents the desired output width of the trigger in clock ticks.
a list of four 0 values
-groupenables list
List of four booleans (defaults to all true), one for each ADC channel group. If a group's flag is true it is read out, if not it is not read out.
Defaults to a group of four false valsuss.
-header
valueThis 16 bit value is inserted into the data from the module prior to the data from each group. See OUTPUT DATA FORMAT below for more information about where this appears.
This defaults to 0xfadc
-trailer
valueThis 16 bit value is inserted into the data from the module after the data from each group. See OUTPUT DATA FORMAT below for more information. Defaults to 0xffff
The output format for this module does not depend on mode. The interpretation of some of the data is, however mode dependent. The overal format of the data is shown below:
+----------------------------------------+ | Mask of group enables (16 bit) | +----------------------------------------+ | DAQ Control register value (32 bits) | +----------------------------------------+ | Data from the lowest set bit in | | group enables | ... +----------------------------------------+ ...
The DAQ control register value provides two bits of useful information:
If its bottom bit (bit 0) is set you need to delay more prior to reading the module as this bit means the module is still digitizing at the time of readout.
If bit number 10 is set, the module is being used in gate mode. If not it is being used in either start or stop mode (there is no hardware way to determine the difference).
Bits 12-14 define the clock source according to the table in section 4.5. Note that there is no way from this register alone to distinguish between the various external clock modes.
Other bits may be set but they are not relevant to this discussion.
Data from each enabled group is provided from lowest to highest group number. No data is provided for disabled groups.
The data from each group is:
+-----------------------------------------------+ | header (16 bits) | +-----------------------------------------------+ | Group trigger event directory (32 bits) | +-----------------------------------------------+ | Size of data from group | +-----------------------------------------------+ | Data from group | ... +-----------------------------------------------+ | trailer (16 bits) | +-----------------------------------------------+
In the data format shown above;
Is the value of the -header
option. If not
configured by you this defaults to 0xfadc
Is the value of the -trailer
option
See section 4.25 of the SIS3300/3301 manual for the detailed format of these 32 bits.
The bottom 17 bits of this value modula the number of samples you have selected are sample in the data from the group after which the data have ended. In the start and gate mode the trace always begins at the first data item and this value indicates the sample after which data end. In start mode, and gate mode, this may indicate fewer samples have been digitized than were acquired if, for example there is an external stop in start mode or, in gate mode, if the gate is short relative to the selected sample size.
In
stop mode, the digitizer treats the data buffer as a circular
buffer into which it is continously digitizing the input.
The stop signal then indicates when digitization ends (
the actual stop may
be delayed by the -stopdelay
).
Therefore in stop mode the bottom 17 bits modula the
-samples
together with bit 19 (the wrap bit)
indicate at which sample the trace starts.
If the wrap bit is not set, then trace begins at the first sample in the buffer and ends at the sample just prior to the value in the bottom 17 bits. If the wrap bit is set, data begins at the sample number in the data indicated by the bottom 17 bits and wraps circulalry to the beginnning of the data before ending in the sample just prior to the first sample.
If you are using the internal thresholds, bits 24-31 indicate which, if any, channels satisfied their threshold conditions. Bit 31 represents the state of the channel 1 trigger and bit 24 the state of the channel 8 trigger.
This is the actual number of samples that will appear
in the data buffer. At present, (this may change), in start
and in stop mode, this is the number of samples selected
by -samples
. In gate mode, this value
repeats the trigger event directory and the bottom 17 bits
indicate the number of samples acquired.
This is the raw sample data, 32 bits per sample containing a sample from each ADC in the group of two samples as shown in section 4.33 of the SIS3300/3301 manual. Note that to decode the data you will need to know if the digitizer is an SIS3300 (12 bits of data over range flag in bit 12) or an SIS3301 (14 bits of data over range flag in bit 14).
These 16 bits are the value of the -trailer
option. If not configured by you, this defaults to
0xffff. Note that since bit 15 is set,
this is not a legal conversion value from the AD and therefore
is distinguishable from real data. I recommend that if you
choose a different -trailer
from the
default value, that you select one that has the top bit
set.