DESCRIPTION

The Struck SIS8800 MTCA.4 Scaler is a "MicroTCA For Physics" conforming card supported by spec as a both a 32-channel counter/timer and a multi-channel scaler (MCS), the latter for use mainly with spec fly scan macros. MicroTCA is a standard for modular computer systems. As far as spec is concerned, the MicroTCA card looks like a PCI device. The SIS8800 spec interface is very similar to that of the Struck SIS3820 VME Scaler module (see the sis3820 help file).

spec can be configured to use the same module as both a regular timer/counter and as an MCS, although the module can be only be operated in one of the modes at a time. It is not necessary to change the hardware configuration to switch between modes. If active using tcount() or mcount(), for example, a call of mca_par("run") will result in an error. Likewise if the module is active as an MCS, the counting functions will generate an error. It is not possible to use the MCS in "auto_run" mode if the SIS8800 is also configured as a timer/counter or counter device.

In the sections that follow, items that apply to only one of the modes will be marked as COUNTERS or MCS.

Note, spec refers to the 32 channels as channel 1 through channel 32 to match the hardware labels (most of spec's hardware support is for counters that start with a channel zero).

COUNTERS: When used as timer, any of the counter inputs can be used as a preset. The default counter channel for monitor preset counting can be selected in the config file. The counter_par() "monitor" command can be used to change which counter will be used within a spec session. If channel 1 is configured as the timebase, it will be programmed to use the 50 MHz internal reference pulser as input. The default output mode (value 1) puts that same 50 Mhz signal on output 7 and makes output 6 available to be used to gate other devices. If another channel is used as a timebase, then a frequency source needs to be connected to the associated input and the config file scale factor needs to be set accordingly.

MCS: Although the SIS8800 can be used as a traditional MCS, it is specifically supported in spec with the standard flyscan macros. These macros do continuous scans with the MCS channel advance driven by pulses from a motor. The motor signal can connect to any counter or to any one of the eight backplane M-LVDS (multipoint low voltage-differential signal) transceivers (if so equipped), and the counts will be prescaled to match the fly-scan parameters. With motor pulses generating the channel advance, each multi-channel scaler channel can be associated with an accurate motor position. See the flyscan help file for details.

In MCS mode, any or all of the 32 counters can be used as an MCS input. An MCS data collection run is divided into channels and passes. A normal MCS sums data in each channel over each pass. In the current spec implementation, the SIS8800 stores data from each channel and each pass into a separate memory word. The SIS8800 has 2 gigabytes of memory to store such data. The product of effective_counters * channels * passes * word_size cannot exceed the module memory. The value "effective_counters" may be more than the explicitly configured number of counters due to the way the SIS8800 moves data in 32-byte segments.

The word size for the data can be configured to 1, 2 or 4 bytes in order to decrease the memory needed to accommodate the configured data size. The SIS8800 writes data to memory 32 bytes at a time. That means that with a word size of four, data for 8 counters (1 to 8, 9 to 16, 17 to 24 and/or 25 to 32) is written for each MCS time slot. Similarly, a word size of 2 leads to 16 counters (1 to 16 and/or 17 to 32) being written. A word size of 1 has all 32 counters written for each slot. If only some of the counters are configured to be used with the MCS acquisition, spec will disable copy to memory for the unused counters. However, if even one counter in the group of 8 or 16 is being used, data for the entire group will be saved. For one byte words, data for all channels is always saved.

Currently, spec allocates a memory buffer big enough to hold all the data from all the counters, channels and passes configured at the start of an MCS run. The data is actively read and can be viewed during collection. The raw data from all counters, channels and passes can be read at once or in segments. The MCS sums from multiple passes can be read one counter at a time, as described below.

The SIS8800 requires DMA to transfer data in MCS mode, and DMA requires a kernel driver. The spec SIS8800 support currently works with a generic Linux DMA driver called u-dma-buf for "user space mappable DMA buffer", available from github.com/ikwzm/udmabuf.

CONFIGURATION (COUNTERS)

Use spec's configuration editor (edconf, normally invoked by the config macro) to select the timer and to configure the scaler channels. On the Devices screen choose one of the following configurations depending on whether you are using the SIS8800 as master timer or as just as counters:

 SCALERS DEVICE  ADDR <>MODE NUM                          <>TYPE U#
0  YES            0:0         32 Struck SIS8800 as Timer/Counter  0
1  YES            0:0         32      Struck SIS8800 as Counters  1

The ADDR field can be optionally used to configure the PCI bus:slot numbers if more than of these cards is installed in the same computer. Leaving the default value of 0:0 means the card can be in any slot. Note, the values must be entered as decimal numbers in spec's configuration editor, even though the Linux /sbin/lspci utility will list the values in hexadecimal. For cards with ADDR set to the default 0:0, spec will select the next unassigned card it detects.

On the Scaler screen of the configuration editor, choose SIS8800 for the controller type:

Scaler (Counter) Configuration

Num     Name  Mne <>Device Unit Chan <>Use As Scale Factor
  0  Seconds  sec  SIS8800    0    1 timebase     50000000
  1  Monitor  mon  SIS8800    0    2  monitor            1
  2 Detector  det  SIS8800    0    3  counter            1
  3       c3   c3  SIS8800    0    4  counter            1

If channel 1 is configured as a "timebase" counter, spec will use the internal 50 MHz pulser as the time base, ignoring whatever scale factor is set here.

CONFIGURATION (MCS)

MCS mode is configured on the Acquisition screen in spec's configuration editor:

MCA (1D) and Image (2D) Acquisition Device Configuration

MCA            DEVICE  ADDR  <>MODE                                   <>TYPE
0   YES /dev/udmabuf0   0:0         Struck SIS8800 MCS with u-dma-buf driver

Again, the ADDR field can be set to the module PCI bus:slot, as described above. The DEVICE field is the device node associated with the u-dma-buf kernel driver (see github.com/ikwzm/udmabuf.)

FUNCTIONS

Note that values for the parameters "input_mode" and "output_mode" in counter mode and MCS mode are independent. Values can be set for each of the operation modes and those values will be saved to and restored from the state file.

All parameters are case insensitive.

COUNTERS: The counter_par() function takes an initial argument specifying a counter mnemonic or number. When using counter_par() for commands that apply to the entire module, the module affected will be the one associated with the mne argument.

counter_par(mne, "monitor")

Sets the channel assigned to mnemonic mne to be the monitor preset channel. The monitor channel gets reset when the config file is read on start up or on reconfig.

counter_par("input_mode" [, val])

The input mode bits in the operation-mode register control the behavior of the four input signals available on the controller front panel. Allowed values are from 0 through 7. The default value for counter/timer mode is 2.

counter_par("output_mode" [, val])

The output mode bits in the operation-mode register control the behavior of the four output signals available on the controller front panel. Allowed values are from 0 through 5. The default value for counter/timer mode is 1.

counter_par(mne, "veto_inhibit" [, val])

A value passed here will be written to the "veto external count inhibit register" when started in counter/timer mode.

counter_par(mne, "test_pulse_mask" [, val])

A value passed here will be written to the "test pulse mask register" when the device is started in counter/timer mode. This register allows the 25 MHz internal pulse train to be routed to any channel. If a nonzero value is written to this register, spec will enable counter test mode and the 25 MHz test pulses by writing to the "control/status register" when the device is started in counter/timer mode. In addition, val will be used to mask the channels that are to count external signals by writing to the "test pulse mask register". Note, spec will always mask channel 0 on the master unit, as spec uses that channel to measure elapsed time based on the 50 MHz internal signal.

MCS: The mca_par() function works on the default or currently selected MCA-type device. The mca_sel() command can be used to choose which MCA-type device is the current selection. (See the mca help file.) The mca_spar() function takes an initial argument that specifies the MCA-type device unit number, as set in the hardware config file. The mca_spar() commands that apply to a particular counter channel use a subaddress syntax, where the address argument is given as 0.1, 0.2, ..., 0.32. The first digit is the MCA unit number from the config file, and the digit right of the decimal point is the counter channel, which can be from 1 through 32. The syntax "0:1", "0:1", ..., "0:32" is also recognized, where the arguments are strings.

All parameters are saved to the state file.

mca_par("run")

Programs and starts the SIS8800 for MCS acquisition.

mca_par("halt")

Halts the SIS8800 MCS acquisition.

mca_par("passes" [, value])

Selects or returns the configured number of MCS passes.

mca_par("dwell" [, value])

Selects or returns the channel dwell value. Negative values indicate external dwell. The magnitude of the negative value is used to estimate the data rate.

mca_par("channels"|"npts" [, value])

Selects or returns the number of channels per pass.

mca_par("start_mode" [, value])

Selects or returns the start mode. MCS acquisition can begin when the device is started (mode 1) or with the first channel advance (mode 0).

mca_par("input_mode" [, val])

The input mode bits in the operation-mode register control the behavior of the four input signals available on the controller front panel. Allowed values are from 0 through 7. The default value for MCS mode is 0.

mca_par("output_mode" [, val])

The output mode bits in the operation-mode register control the behavior of the four output signals available on the controller front panel. Allowed values are from 0 through 5. The default value for MCS mode is 1.

mca_par("word_size" [, 1|2|4])

Selects or returns the MCS word size, which can be one, two or four bytes per word. Smaller word sizes can allow faster acquisition and more data to be accumulated.

Note, the MCS transfers 32 bytes at a time with data on 32-byte boundaries. Only 32-byte segments that have an enabled channel will be transferred to memory. With one byte word size, all channels will always be transferred to memory at each count, whether or not they are enabled. With a two byte word size, 16 or 32 channels will be transferred, depending on whether there are enabled channels in the 16-channel groups. For a four-byte word size, either 8, 16, 24 or 32 channels will be transferred.

Note also, spec will use four-byte data arrays to read data with mca_get() no matter what the acquisition word size.

mca_par("first_counter" [, chan])

Selects or returns the number of the first counter to be read during data acquisition. Can be used with "last_counter" to enable consecutive channels. Counters are numbered from 1 to 32.

mca_par("last_counter" [, chan])

Selects or returns the number of the last counter to be read during data acquisition. Can be used with "first_counter" to enable consecutive channels. Counters are numbered from 1 to 32.

mca_par("counters" [, mask|arr])

Enables an arbitrary set of channels to be enabled. The argument can be a single number where each set bit corresponds to an enabled channel. That is, bit 0 corresponds to channel 1, bit 1 to channel 2, etc. Alternatively, the argument can be a one- or two-dimensional associative array, where the index of the element (first element for a 2D array) contains the hardware channel number (from 1 to 32), and the corresponding element value has a nonzero or non-null value to indicate the channel is to be enabled. The "counters" option is an alternative to using "first_counter" and "last_counter".

mca_par("prescale_counter" [, chan])

Selects or returns the counter or M-LVDS transceiver to be used for channel advance. The counts in this channel will be prescaled according to the "prescale" value. If the chan argument is from 1 to 32, it specifies the counter number. This counter can not be enabled for MCS acquisition. A value from 40 to 47 indicates using the falling edge of M-LVDS transceiver 0 to 7, respectively. A value from 50 to 57 indicates using the rising edge of M-LVDS transceiver 0 to 7.

mca_par("prescale" [, value])

Selects the prescale value for the designated prescale counter. Every value input pulses will generate one channel advance.

mca_par("elapsed_passes")

Returns the current number of elapsed passes. The return value can be non integral reflecting the progress in transmitting data from the current pass. The value is estimated from the data so far read from the device. Data is read in chunks, so the calculated value will be granular.

mca_par("elapsed_channels")

Returns the current channel number in the current pass. The value is estimated from the data so far read from the device. Data is read in chunks, so the calculated value will be granular.

mca_par("elapsed_time")

Returns the elapsed time of the current acquisition based on the software clock.

mca_par("report"|"report2")

Displays the current MCS parameters along the following lines:

  Struck SIS8800 (fw 1.0B sn 64) 2048 Mb

      Enabled counters = 1  3  4 15 16 17 18 19 (0x7c00d)
      Chan Adv counter = 4
              Prescale = 6
                 Dwell = External (0.01 sec)
            Start mode = On first channel advance (1)
          MCS channels = 2001
                Passes = 1
             Word size = 2 bytes
            Input mode = 2
           Output mode = 3
         Invert inputs = 0x0
        Invert outputs = 0x0
 LNE Delay/Width logic = Enabled
      LNE output delay = 4 ns
      LNE output width = 0 ns
            Reset time = 10 ns
DAC thresholds (ch:mV) = 17: -100  18: -100  19: -100

      Elapsed channels = 2001
        Elapsed passes = 1.00
          Elapsed time = 20.24 sec
             Data rate = 1200 bytes/sec

The form "report2" includes the mca_par() argument string associated with the parameter displayed. The parenthesized value for enabled counters is the bit-wise representation that can be passed as an argument. The time associated with external dwell is the value passed in the argument used to estimate the data rate.

mca_par("chans"|"max_chans"|"max_channels")

Returns the currently configured number of points for the device. For the SIS8800, the number is the product of the configured number of counters, channels and passes. The value is recalculated when any of those parameters is changed. This value is the size of the array needed when reading back the raw data. If either the number of counters or number of passes is greater than one, one either needs to specify the roi_beg and roi_end arguments with mca_get() and mca_sget() or pass an array dimensioned to this "chans" value.

mca_get(arr [, roi_beg [, roi_end]])

Gets data from the MCS associated with the first counter configured and transfers it to the array arr. The optional region-of-interest arguments limit the data to the range of channels indicated. The data is placed starting at the beginning of the array. For multiple passes, data from each pass is summed for each channel.

mca_sget(addr[.ch]|"addr:ch", arr [, roi_beg [, roi_end]])

Gets data from the MCA unit number addr. If the subaddress ch is specified, data from that counter number will be returned. If the subaddress is not specified, data from the first counter will be returned. The function will return zero if ch is not an enabled channel. If the optional region-of-interest beginning and ending channels are given, the data is returned from those channels and placed starting at the beginning of the array. For multiple passes, data from each pass is summed for each channel. If the subaddress ch is 33, the raw data from all the counters, channels and passes is returned in a single array. Such data is ordered consecutively by counter, channel, pass.

If more than one pass or more than one counter is configured, the number of MCA channels associated with the device is the product of counters, channels and passes, which is the value returned by mca_par("chans"). Either the array passed to the mca_get() and mca_sget() functions has to be that size, or the region of interest arguments need to be specified.

COUNTERS and MCS:

The following counter_par(), mca_par() and mca_spar() commands are available. The shorthand xxx_par() is used to represent all three for the commands available in both counter and MCS modes. The initial counter mnemonic argument for counter_par() or MCA selection argument for mca_spar() will not be shown.

xxx_par("invert_inputs" [, how])

If passed with a nonzero argument, will set the "control inputs inverted" bits in the module's operation-mode register immediately. With no argument, reads and returns the current value of the parameter. The value has four bits, that is, from 0 to 15 (0x0F), for the four front panel inputs.

xxx_par("invert_outputs" [, how])

If passed with a nonzero argument, will set the "control outputs inverted" bit in the module's operation-mode register immediately. With no argument, reads and returns the current value of the parameter. The value has four bits, that is, from 0 to 15 (0x0F), for the four front panel outputs.

xxx_par("LNE_delay_logic" [, 0|1])

Enables or disables the LNE/CIP Delay/Width logic when passed a nonzero or zero argument, respectively. With no arguments, returns the current setting. When enabled, the CIP/LEN output width and output delay registers will be programmed with values set for "LNE_output_delay" and LNE_output_width". The value is set when the device is started.

xxx_par("LNE_output_delay" [, val])

Sets or returns the value of the CIP/LNE output delay register. Units are nanoseconds with a resolution of 4 nanoseconds. Values are programmed at the start of acquisition if the "LNE_delay_logic" parameter is nonzero. The value is set when the device is started.

xxx_par("LNE_output_width" [, val])

Sets or returns the value of the CIP/LNE output width register. Units are nanoseconds with a resolution of 4 nanoseconds. Values are programmed at the start of acquisition if the "LNE_delay_logic" parameter is nonzero. The value is set when the device is started.

xxx_par("snum")

Returns the serial number as reported by the SIS8800.

xxx_par("lvds_csr" [, value])

Sets or returns the value of the M-LVDS control and status register. (LVDS is the low voltage differential signaling.) The value is set immediately.

xxx_par("lvds_enable" [, value])

Sets or returns the value of the LNE M-LVDS source enable register. The value is set immediately.

xxx_par("reset_time" [, value])

Sets or returns the value of the RTM channel reset register. The value is in nanoseconds. The value is set immediately.

xxx_par("threshold")

Reads and returns the current threshold DAC value for the selected channel in units of millivolts. A threshold voltage is only associated with channels 17 through 32. Works with counter_par() or mca_spar() where the first argument to mca_spar() contains both the unit and channel number. The value is set immediately.

xxx_par("threshold", val [,"all"])

Sets a value for the threshold DAC on an SIS8980 Rear Transition Module. Such a module would only be associated with channels 17 through 32. The units of val are millivolts. The valid range is -2500 to 3000, inclusive. Values that are outside that range are set to the closest allowed value, that is, -2500 or 3000). If the optional argument "all" is included, the thresholds for the DACs associated with all of the enabled channels are set simultaneously to the indicated value. Likewise, if mca_par() rather than mca_spar() is used, the threshold is set for all enabled DAC channels. Setting all DACs to the same threshold is faster, as it can be done in one register write. The values are set immediately.

xxx_par("reg" [, value])

Sets or returns the value of an SIS8800 register. Note, spec makes if difficult to write to certain registers, where bad values can have disastrous consequences, such as the DMA source and destinations addresses. Those addresses can be written using the parameter "reg*" instead of "reg", but only if spec wizard mode is enabled. See the wizard help file.

xxx_par("dumpreg")

Prints the values of all the readable SIS8800 registers along these lines:

reg[0x000] = 0x8800010b (2281701643)
reg[0x001] =       0x40 (64)
reg[0x002] =          0 (0)
reg[0x003] =          0 (0)
reg[0x004] =    0x10000 (65536)
reg[0x005] =       0x10 (16)
reg[0x006] =          0 (0)
reg[0x007] =          0 (0)
...
reg[0x400] =  0xee6b280 (250000000)
reg[0x401] =          0 (0)
reg[0x402] =  0x3adf9bd (61733309)
reg[0x403] =          0 (0)
...

The values are the register address, the value in hexadecimal and the value in decimal. Register addresses at 0x400 to 0x41F are the counter shadow registers. Registers 0x420 to 0x43F are the counter registers. See the Struck SIS8800 documentation for details on the register layout.

STATE FILE

The following parameters are saved in the user state file, so will be restored when restarting spec, except when starting fresh. The following MCS parameters are saved:

First MCS channel ("first_counter")

Last MCS channel ("last_counter")

Enabled MCS channels ("counters")

Prescale channel ("prescale_counter")

Prescale value ("prescale")

Output Mode for MCS ("output_mode")

Input Mode for MCS ("input_mode")

Number of passes ("passes")

Number of channels ("channels")

Start mode ("start_mode")

Word size ("word_size")

MCS dwell time ("dwell")

The following are associated with COUNTERS:

Output Mode for counting ("output_mode")

Input Mode for counting ("input_mode")

The following parameters are used for both MCS and COUNTERS:

Invert inputs ("invert_inputs")

Invert outputs ("invert_outputs")

LVDS CSR ("lvds_csr")

LVDS enable ("lvds_enable")

Reset time ("reset_time")

DAC threshold (16 values) ("threshold")

LNE delay/width logic ("LNE_delay_logic")

LNE output delay ("LNE_output_delay")

LNE output width ("LNE_output_width")

When spec starts up (not fresh), if a threshold value from the state file is nonzero and the associated channel is in use, spec programs the DAC for that value. During a reconfig, spec only reprograms the DAC thresholds if there is a change in channel configuration associated with the Rear Transition Module, that is, whether any of channels 17 through 32 have been added or removed from the hardware configuration.