NSCL DAQ Software Documentation
PrevNext

mqdc

Name

mqdc -- Support Mesytec MQDC-32 modules

Synopsis

mqdc create name

mqdc config name ?options

mqdc cget name

DESCRIPTION

The mqdc command provides scripted support for the Mesytec 32 channel charge-to-digital converter.

As with all VM-USB module support commands, mqdc is a command ensemble with subcommands that create and configure modules as well as cget, which introspects a module configuration.

create creates an object with the specified name. Additional options are treated like configuration options. config configures an existing module, and cget returns a list of configuration name/value pairs that describe the configuration of the module.

It is important to note that the module configuration does not actually get loaded until the run is initialized. The order in which configuration parameters are supplied is therefore unimportant. Think of the configuration options as being accumulated and then applied as the run starts. Only modules that are registered to a stack are configured.

The configurable options are given names and reasonable defaults for the purpose of reducing the learning curve for using the device. However, in order to address the considerable number of use cases that this driver will be used in, the decision was made to support flexibility at the cost of some complexity. To create a specific behavior, it is sometimes necessary to configure multiple options. For this reason, correlated options to the option be described are listed for cross reference. Furthermore, two examples are provided in the EXAMPLES section to demonstrate common configurations.

OPTIONS

In contrast to some of the other Mesytec digitizer drivers provided by NSCLDAQ, this driver does not initiate a soft reset at the beginning of every run. This is so that timestamps have the option of not clearing between runs, which is a behavior that some experiments have required. If you would like to soft reset the device, see the slow controls module mxdcsoftreset. When used, this module will cause a soft reset at the startup of the VMUSBReadout program and then on-demand via the init command any time thereafter.

-base address

address must be the module base address as configured in its rotary switches. This base address is used to access the module's register and event memory.

Each module must be programmed and hardware configured with a different base address. The address used will be an A32 VME address.

By default, the value is 0.

-id vsn

vsn will be used as the module's identifier or virtual slot number. The vsn will be encoded into the event data that is returned by the module. This, in turn is normally used by event decoders to determine which parameters the channels of the module should be unpacked into.

Each module should be given a unique vsn.

By default, the value is 0.

-timestamp onoff

This option controls whether or not the module tags each event with a trigger number (event count) or with a timestamp (see also the -timingsource, -timingdivisor, -nimtiming, -ecltiming, and -syncmode options).

The onoff is a boolean value. If true, the module tags events with a 46-bit timestamp. Otherwise, a 32-bit trigger number number is used. The upper 16 bits of the 46-bit timestamp are encoded into the extended timestamp packet that is outputted before the end of event word.

By default, this is false.

-usethresholds onoff

The onoff sets whether the thresholds will be used or not. The effect is the same as providing a list of 32 zeroes to the -thresholds option.

By default, the value is true.

-thresholds valueList

Supplies the per channel thresholds for the adc. Channels which convert below their threshold are suppressed from the data stream reducing both data volume and dead-time. The valueList is a 32 element Tcl list of the integer thresholds.

The user can supply an 8-bit threshold for each channel. Note that there zero threshold value disables the threshold for the associated channel. To disable all usage of thresholds, the user can either provide a TCL list containing all zero values or make use of the -usethresholds option.

By default, all values in the list are 0.

-ipl irqlevel

If the module will be used to trigger an interrupt driven stack, the irqlevel parameter must be programmed to a valid non zero interrupt priority level (1 through 7). This must match the interrupt priority level used to trigger the stack.

The default value of 0 disables module interrupts.

-vector statusId

If the module will be used to trigger an interrupt driven stack, the statusId must be programmed to a non zero 8-bit status id, or vector (between 1 and 255).

The value used must match the value of the -vector configuration parameter used to trigger the stack.

The default value is 1.

-irqthreshold integer

Sets the interrupt threshold. If interrupts are enabled, the module will interrupt when the buffer contains at least this number of longwords.

The "max transfer data" (register at 0x601a) described in the MQDC-32 manual is always the same as the value provided to this option.

The default value is 1.

Be aware that the value provided will be overridden if -multievent is set to off.

-multievent off | on | limited

Configures the device for multievent mode. The valid values are off, on, and limited. When the value is off, then the device is a purely single event mode. There is no buffering that occurs within the device and no new gates are accepted until the device is read out (we reset the device when we read). When the value is on, the device will transfer an unlimited amount of data with each read. This driver is written so that each read will attempt to transfer 1024 words. Finally, if the value is limited, then the device will buffer events and then read out an amount determined by the -maxtransfers option. The default value for this parameter is off.

-countevents on | off

If the value passed to this parameter is on, then the -maxtransfers value is taken to be the number of events rather than the number of words. If you inspect the manual, this controls the "count events" bit in the multievent mode register. Note that this only affects the output when the -multievent parameter is set to limited. The default value is no.

-skipberr yes | no

If true, then an "end of buffer" is sent instead of a BERR (0xffffffff) when the reached and -multievent is set to limited. This controls the "Emit EOE" bit in the multievent register (see MQDC-32 manual). The default value is no.

-maxtransfers integer

This is a soft threshold for the number of words that can be transferred in a single read when the -multievent parameter is set to limited. The number of words transferred is the least number of words beyond the value set to complete an event. This is only a meaningful parameter if the -multievent parameter is set to limited. The default value is 1.

-bankoffsets intlist

The intlist must be a two element TCL list whose entries are interpreted as the bank 0 and bank 1 offsets, in that order. The values can be in the range [0,255] independently and effectively shift the spectrum by about 2000 channels.

The default value is 128.

-gatemode mode

The MQDC32 has a pair of gate inputs. The mode can be either separate or common.

If set to separate, two separate gates are to be provided for each bank of inputs. One must go into gate 0 input and the other into the gate 1 input. If on the other hand, the option is set to common, the gate 0 input will be used gate all 32 channels.

The default setting is common.

Note that this value will modify the effect of some other options such as -multlowerlimits and -multupperlimits,

-gatelimits intlist

The intlist must be a two element TCL list that contains integer elements in the range [0,255]. The manual provides a coarse table describing the nonlinear mapping. It maps the values 0 to 254 to an integration width range between 4 and 300 ns. If the value is 255, the gate limit is considered infinite such that the physical gate provided as input is used without any width limit.

The default value is 255.

-exptrigdelays intlist

The intlist must be a two element TCL list that contains integer elements each in the range [0,16383]. The range maps to a range of delay from 0 ns to 16384 ns.

The default value is 0.

-inputcoupling0 type

The type determines whether or not the signal inputs for bank 0 are AC or DC couplied. The accepted values for the option are AC and DC.

The default value is AC.

-inputcoupling1 type

This has the exact same semantics as the -inputcoupling0 option except that it applies to the bank 1 signal inputs.

The default value is AC.

-pulser onoff

The onoff specifies whether the internal test pulser will be turned on or off. It must be a valid boolean value.

If the test pulser is enabled, the amplitude of the pulser is determined by the value of the -pulseramp option. The pulser is not described in detail in the manual. What happens at the time of writing is that when the pulser is enabled, an internally generated gate is used to integrate any input signal. This will be uncorrelated to any pulses so the integrator will in general integrate the baseline noise. The pulser amplitude is added to this integrated value. The result is that if no physical signal inputs are provided, the pulser peak will be quite sharp. On the other hand, if any input signals are connected, the pulser peak will be smeared out by the variations in the baseline integration. HOWEVER! What was just described only applies when no cable is attached to the individual gate inputs. If the individual gates are potentially being provided (determined by the presence of a cable), the pulser is rendered ineffective!

The default value is false.

-pulseramp value

The integer value provided for value is to be used for the pulser amplitude. The value must be in the range [0,255].

The default value 32.

-ecltermination onoff

This parameter when true enables the ECL input termination. If disabled, the termination is off. If you are bussing the ECL inputs, only the final module in the bus should have terminatinon enabled, all other modules, should have termination turned off.

The default value is true.

-ecltiming onoff

When true, this parameter enables the gate1 ECL input to to be used as a clock source for the timestamp. It also enables the fast clear ECL input to be used as an external timestamp reset input. When false, the ECL G1 input is an ECL gate1 and the ECL fast clear is a fast clear.

In the case that it is used as a timestamp reset, the behavior is tightly coupled to the value of the -resetlogic option.

The default value is false.

-nimtiming onoff

If true, enables the NIM Gate1 input to be a clock source for the timestamp and NIM faxt clear input to be used as a timestamp reset. If false, the NIM Gate1 input is a gate for bank 1 and the NIM fast clear input is a fast clear.

The actual behavior of the reset depends on the value of the -resetlogic.

The default value is false.

-nimbusy busyselect

This option selects which signal is presented at the NIM busy output lemo connector. By default, this will be the module busy. The busyselect can be any of the following strings:

busy

The module busy is outputted. This is the default.

rcbus

This allows the device to be used as a proxy for the Mesytec RC-bus protocol. The NIM busy output serves as the communication port. A slow-controls module, mxdcrcbus, should be used to perform the actual communication with devices.

overthreshold

A gate will be outputted when the buffer contains more data words than are specified in the -irqthreshold value. This could in principle be used as a signal indicating data is ready to be read out if not using an interrupt as a trigger.

full

A gate will be outputted when the buffer is full of data.

-timingsource sourceName

The value of sourceName specifies the source of the clock for timestamps. If external, whichever of the NIM or ECL GATE1 inputs are enabled is the clock source. If vme, the VME 16Mhz backplane clock is the clock.

If you use an external time source, it is very important that -ecltiming and -nimtiming values are set in a manner that matches your setup.

The default value is vme.

-timingdivisor val

The val is a 16-bit integer that scales down the counter in use (event count or timestamp).

The default value is 1.

-resetlogic mode

The effect of this option should not be confused with enabling or disabling the ability to reset the internal counters (i.e. timestamp or trigger count). Rather it should be used to set some reset logic in the device. There are three accepted values that are described below. The default value is begin_run.

never

In this mode, the counters will never reset automatically between runs. The only way they will reset is by an external reset input, if the devices inputs are configured to accept one (See -nimtiming and -ecltiming). In which case, there is no limit to the number of times a reset by an external signal can occur.

You could use this mode to establish hardware level timestamp synchronization if you have enabled the device for timestamping and also for using an external timing source. If doing so, it is left to the user to make sure only one reset signal arrives during the run.

begin_run

In this mode, the counters will reset during the intialization phase of every run. If using a trigger count (aka. an event count), this is the preferred reset logic.

extern_oneshot

In this mode, the counter will never reset automatically between runs unless an external signal arrives to a reset input (See -nimtiming and -ecltiming). In this respect the behavior is similar to the never mode. The difference is that this only allows a single reset to occur after the start of a run. What this does is arm the device to reset on the rising edge of the first external reset input. After this first input, the device will not reset until it is armed again during the initialization phase of the next run.

If the user has enabled the device for timestamping and the timing source is external, this is the simplest way to establish hardware level synchronization with other components in the system. In fact, it is recommended over use of the never mode.

-multlowerlimit0 val

The val must be an integer in the range [0,32]. The effect of this option changes according to the value of the -gatemode option. In general, this provides a lower multiplicity limit for accepting data. If the number of channels with data for a single gate is greater than or equal to the lower multiplicity limit, the data is added to the buffer. If that is not the case, all data produced for that single gate is discarded.

If -gatemode is set to common, then the value serves as the lower multiplicity limit for all 32 channels.

If instead -gatemode is set to separate, it serves as the lower multiplicity limit for bank 0 channels (channels 0 to 15).

The default value for this is 0.

-multlowerlimit1 val

The val must be an integer in the range [0,16]. The effect of this option changes according to the value of the -gatemode option. If -gatemode is set to common, then the value is written to the device, but the device makes no use of it. If instead -gatemode is set to separate, it serves as the lower multiplicity limit for bank 1 channels (channels 16 to 31).

The default value for this is 0.

-multupperlimit0 val

The requirements and meaning for this are the same as for the -multlowerlimit0 option. The difference is that the val provided is an upper limit instead of a lower limit. If the number of channels with data for a gate must be less than or equal to the upper limit value provided to be accepted. The valid range of values for val are [0,32].

The default value for this 32.

-multupperlimit1 val

The requirements and meaning for this are the same as for the -multlowerlimit1 option. The difference is that the val provided is an upper limit instead of a lower limit. If the number of channels with data for a gate must be less than or equal to the upper limit value provided to be accepted. The valid range of values for val are [0,16].

The default value for this 16.

EXAMPLES

Example 1. Sample use of mqdc command for timestamping with external oscillator

The following example configures the device for use in a system that has single event readout logic. The user will initiate the data readout by means of some logic external to the device. Furthermore the data must be timestamped for the purpose of event building. The clock is provided on NIM G1 input and an external synchronization pulse is provided into the NIM Reset input. Furthermore, the device must scale down the clock count by 14. 


set madcTimeDivisor 10

mqdc create qdc -base 0x40000000 -id 5 -ipl 0             (1)
mqdc config qdc -gatemode common
mqdc config qdc -nimtiming true
mqdc config qdc -timestamp on -timingsource external -timingdivisor $madcTimeDivisor 
mqdc config qdc -resetlogic extern_oneshot                (2)

set thresholds [list]
for {set i 0} {$i < 32} {incr i} {
  lappend thresholds 0                                    (3)
}
mqdc config qdc -thresholds $thresholds                   (4)
(1)
This command creates an object to manage an MQDC-32 whose base address is 0x40000000. The module will be referred to by the symbolic name: qdc.
(2)
This line and the two above it set up the device to receive an external clock signal through the NIM inputs and then synchronize it via a signal at NIM FC. It also establishes that the sync reset will occur once after the run begins and that the number of clock cycles that arrive will be scaled down by a factor of 10 to produce the timestamp.
(3)
This highlights the fact that the configuration file is really a configuration program. The loop creates a variable named thresholds that contains a list of 32 zeroes. This list will be used to program the qdc thresholds. Normally these values will neither be zero nor uniform from channel to channel. It may be best to read them from some external file.
(4)
This command uses the thresholds variable and programs the channel thresholds of the QDC.

Example 2. Sample configuration of mqdc for event counting and interrupt readout

The following example will show how to use the device for readout triggered by an interrupt. It will also use an event count rather than a timestamp that resets between runs. The readout will be single event mode. 


set thresholds [list]
for {set i 0} {$i < 32} {incr i} {
  lappend thresholds 0                                   
}

mqdc create qdc -base 0x40000000 -ipl 1 -vector 0                   (1)
mqdc config qdc -thresholds $thresholds

stack create evt
stack config evt -modules {qdc} -trigger interrupt -ipl 1 -vector 0 (2)
(1)
This creates a new object to manage a QDC whose base address is 0x40000000 that will generate an interrupt whenever an event occurs. The device's interrupt priority level will be 1 and the vector it will respond to is 0.
(2)
Here we set up a stack that is triggered by an interrupt with priority level 1. It will then trigger readout of the qdc that we have enabled to respond via a vector 0.
PrevHomeNext
mtdcUpmadcchain