This page describes SIS3302 digitzer driver based on the Transient Recorder Framework.

Platforms

The driver has been developed to work on RTEMS and on MVME3100 and MVME6100 boards.

Dependencies

TRCore and its dependencies (Asyn, ADCore).
SLAC's drvRTEMSDmaSup.

See the configure/RELEASE.example file. You need to create the configure/RELEASE file on your own.

Note that you may have to create a proper EPICS build environment for drvRTEMSDmaSup which installs headers and libraries.

Initialization

Use the command SISInitDevice to initialize the device support. The arguments to this command are, in order:

Port name.
VME address of the digitizer.
VME interrupt vector.
VME interrupt level (1-7).
Read thread priority (EPICS units).
Read thread stack size.
maxBuffers (forwarded to asynNDArrayDriver). At least 16 is recommended, use more if AreaDetector plugins (e.g. StdArrays) which receive arrays have blocking callbacks disabled.
maxMemory (forwarded to asynNDArrayDriver). You can use 0 since maxBuffers already limits memory use.

Database Templates

TRSIS.db

The template TRSIS.db defines all driver-specific records except channel-specific ones.

Template parameters are:

PREFIX: Prefix of records (a colon after the prefix is implied). Must match the value passed to TRBase.db.
PORT: Port name of the driver.
STATES_SCAN: SCAN rate for refreshing device states.
ACTUAL_SCAN: SCAN rate for refreshing actual channel values.
TIME_EGU: EGU field for lastRelTime record (default: "s").

For proper operation, TRBase.db must be loaded with LNK_NEW_BURST equal to "PREFIX:_on_new_burst" (with correct PREFIX). This creates a database link which link which ensures that the lastHwTime and lastRelTime records are updated.

The following optional macros can be used to set the default values of configuration parameters: DEFAULT_TRIGGER, DEFAULT_PREAVERAGE, DEFAULT_CLOCK, DEFAULT_EXTRATE, DEFAULT_NUM_PTE, DEFAULT_EVENTS_BUF_SIZE, DEFAULT_TEST_DATA_MODE. Be careful to use the correct option indices for "mbbo" records, especially for pre-average.

TRSIS_Channel.db

The template TRSIS_Channel.db defines the channel-specific records.

This DB file must be loaded for all 8 channels because TRSIS.db has links to records of all channels. This should not be a problem since TRSIS_Channel.db has few records and you can still avoid loading everything else channel-specific for unused channels.

Mandatory template parameters are:

PREFIX: Prefix of records (a colon is implied), this should include identification of the channel.
MPREFIX: Prefix of main records (the PREFIX passed to TRSIS.db).
PORT: Port name of the driver.
CHANNEL: Channel number (0-7).
VOLT_EOFF: Initial EOFF for voltage offset to DAC conversion.
VOLT_ESLO: Initial ESLO for voltage offset to DAC conversion.

Optional template parameters are:

DEFAULT_DAC_VOLTAGE_OFFSET: Default DAC offset can be set with the optional macro.
ENBLD: Whether the channel is initially enabled (1) or disabled (0), default is enabled.

Public PVs

The public framework PVs are automatically supported unless stated otherwise on this page. This page may also have notes about driver-specific semantics of certain framework PVs.

Be aware that the test IOC provided with this driver renames many PVs using the PV customization feature of the framework. If you are using the test IOC, look into TRSIS/TRSISApp/Db/Makefile to find the correct PV names to use (or remove the renamings).

PVs which appear with the prefix CHn in the listings below are channel-specific. The actual prefix may not be CHn but is determined by the PREFIX passed to TRSIS_Channel.db.

Device Information

These PVs contain static information about the device.

PV name, record type	Description
`name` (stringin)	The digitizer name, it is always SIS3302 (this PV is defined by the framework).
`firmwareMajorRev` (longin)	The firmware major revision.
`firmwareMinorRev` (longin)	The firmware minor revision.

Device States

These PVs represent the dynamic states.

All except actualRawValue are updated at the scan rate defined by the STATES_SCAN parameter to TRSIS.db and can also be refreshed manually using the PV updateStates. The actualRawValue PVs are updated at the scan rate ACTUAL_SCAN and can be refreshed manually using updateActualValues.

PV name, record type	Description
`actualEvents` (longin)	The value of the Actual Event Counter register. The hardware will increment this upon start of each event. The hardware clears this when armed for the next event group, so when configured with numberPTE=1 it is normal to see this equal to 0 or 1 most of the time (if pre-trigger samples are not used or used respectively).
`clockRb` (mbbi)	Clock source readback (from Acquisition Control Register).
`samplingBusy` (bi)	Sampling busy state (from Acquisition Control Register). This means whether sampling was started via "start" condition and not yet stopped via "stop" condition or by disarming.
`samplingLogicArmed` (bi)	Sampling logic armed readback (from Acquisition Control Register). This does not generally reflect the framework's meaning of "armed" because in a single course of arming as defined by the framework the digitizer may disam itself and be re-armed many times.
`stopDelayRb` (longin)	Stop delay register readback.
`nextSampleAddressCh0` (longin)	Next sample address for channel 0 (should be the same for all channels so only one is provided).
`CHn:actualRawValue` (ai)	The actual value of the analog input as a raw ADC value. The values are obtained from the "Actual Sample Value" registers.

Desired Settings for Arming

These PVs should be set to the desired settings before an arm request is issued. Their values are captured at the start of arming.

The hardware supports pre-trigger samples so the PV numberPPS (provided by the framework) is available.

PV name, record type	Description
`trigger` (mbbo)	The trigger mode ("soft", "autstart/FPstop", "FPstart/FPstop", "FPstart/autstop"). Note that this driver does not support all possible trigger configurations, especially there is no support for internal triggers. "soft": Software start or stop trigger, supports either pre- or post-trigger samples but not both. In pre-trigger operation, up to 2 samples at the end may be lost due to lack of stop delay function for the KEY_STOP command. "autstart/FPstop": Front panel stop trigger, supports both pre- and post-trigger samples. "FPstart/FPstop": Front panel start and stop triggers; samples between the start and stop are understood as pre-trigger samples, and optional samples after the stop are understood as post-trigger samples. "FPstart/autstop": Front panel start trigger, supports post-trigger samples only.
`preAverage` (mbbo)	Number of ADC samples averaged (powers of 2 from "1" to "128"). Note that the sample counts are strings, numeric values for this PV are binary logarithms of the counts and go from 0 to 7 respectively. Also be aware that averaging does not apply to actual value readbacks (`actualRawValue`).
`clock` (mbbo)	Clock source ("100 MHz", "50 MHz", "25 MHz", "10 MHz", "1 MHz", "Ext Random", "Ext Symm", "2nd 100 MHz"). If you use either of the external clocks you should set `extRate` in order to see correct times in various places.
`extRate` (ao)	The frequency of the external clock relevant when clock is "Ext Random" or "Ext Symm". This is used for example for the time array and calculating relative times.
`numberPTE` (longout)	Number of events per event group. Usually this will be one meaning that each event will be processed independently by software. If it is greater than 1, then the digitizer will acquire this many events (without SW interaction) and the resulting data will be processed together (concatenated). Note: if numberPTE is greater than 1, then the time array will always start at zero (even if pre-trigger samples are used) and will contain numberPTE*numberPPS entries (in steps of 1/sample_rate).
`eventsBufferSize` (longout)	Size of the ring buffer used to store event metadata from the interrupt handler until the event is processed by the read thread.
`testDataMode` (mbbo)	Test data mode ("Disabled", "16 bit", "32 bit"). If test data is enabled the digitizer will generate an increment pattern instead of obtaining data from the ADCs.
`testDataStart` (longout)	The start value for the test data, relevent when test data is enabled. It must be between 0 and 65535 and the low byte must be different from 0xFE and 0xFF.

Current Armed Settings

With regard to the possible values and meaning of these PVs, the text in the section of the same name in framework PVs applies.

PV name, record type	Description
`get_trigger` (mbbi)	Current armed trigger mode.
`get_preAverage` (mbbi)	Current armed number of ADC samples averaged.
`get_clock` (mbbi)	Current armed clock source.
`get_extRate` (ai)	Current armed external clock frequency.
`get_numberPTE` (ai)	Current armed number of events per event group.
`get_eventsBufferSize` (ai)	Current armed size of events ring buffer.
`get_testDataMode` (mbbi)	Current armed test data mode.
`get_testDataStart` (ai)	Current armed test data start value.

Device Requests

To issue a request, write the value 1 (or the associated string value) to the PV. Behavior when writing other values is unspecified.

PV name, record type	Description
`softTrigger` (bo)	Write 1 or "softTrigger" to send a software trigger to the device. This only has an effect when the device is armed with software trigger. Note that the effect is different depending on the settings. If armed with pre-trigger samples it sends the KEY_STOP command but if armed with post-trigger samples it sends the KEY_START command to the digitizer.
`updateActualValues` (bo)	Write 1 or "Update" to update the actual channel value PVs from hardware (`actualRawValue`). The update is done synchronously so it is safe to process this from a DB link then immediately read the associated values.
`updateStates` (bo)	Write 1 or "Update" to update the PVs listed in "Device States" section from hardware (except `actualRawValue`). The update is done synchronously so it is safe to process this from a DB link then immediately read the associated values.
`reset` (bo)	Write 1 or "Reset" to reset the digitizer. This is only allowed while disarmed.
`clearTimestamp` (bo)	Write 1 or "Clear" to clear the hardware timestamp counter. This will make the hardware timestamps (`lastHwTime`) of subsequently acquired events effective relative to when the counter was reset. However, it will also cause one incorrectly computed relative time (`lastRelTime`, see description there for details).

Acquisition Control

These PVs affect acquisition and data processing. Changes are effective immediately.

PV name, record type Description

CHn:dacVoltageOffset (ao)

Configures the voltage offset for the channel by programming its DAC.

The conversion from the requested voltage to the DAC setting is performed using the ao record's EOFF, ESLO and ASLO fields. The ASLO is hardcoded to -1/65536 while EOFF and ESLO are meant to be user-configurable. Effectively the DAC value is calculated according to the following formula (Voff is the voltage written to this record):

DAC = (EOFF - Voff) / ESLO * 65536

The test IOC provides default EOFF and ESLO which were calibrated to the device used for testing. This was done with the assumption that the input span is 10V and the center of the ADC range corresponds to Voff; in other words that the ADC values are interpreted as:

V = Voff + (ADC - 32768) / 65536 * 10V

CHn:enabled (bo) Selects whether data for the channel is read and processed ("Disabled", "Enabled").

Acquisition Information

The driver generates burst IDs as suggested in the description of the BURST_ID PV provided by the framework.

The driver also provides two diagnostic relative times:

From when the interrupt indicated the end of the event group to when the read thread started reading/processing data for the event group. This is exposed in the framework-provided PV GET_BURST_END_TO_READ_END_TIME.
From when the read thread started reading/processing data for the event group to when reading/processing was completed. This is exposed in the framework-provided PV GET_READ_END_TO_DATA_PROCESSED_TIME.

Neither of the default PV names for these times are really suitable, but they are still used since they are readily available. The database customization feature of the framework can be used to rename them, and the included test IOC renames them to InterruptProcessingTime and MainProcessingTime respectively.

PV name, record type	Description
`hwTimePeriod` (ai)	The period of the hardware timestamp counter, in seconds. This can be used to convert raw hardware timestamps to natural units. Raw timestamps are available in the PV `lastHwTime` and are also attached as an attribute to NDArrays. This PV is defined only when armed, otherwise it is NAN.
`lastHwTime` (ai)	The 48-bit hardware stop timestamp of the last event group. If numberPTE is greater than one, this is the timestamp from the first event in the group. The frequency of the hardware timestamp counter depends on the settings (see `hwTimePeriod` above).
`lastRelTime` (ai)	The relative time from the previous event group to the last event group in natural units based on hardware timestamps. It is computed by subtracting the hardware stop timestamps of the first event in each event group (modulo 2^48), converting to seconds by multiplying with `hwTimePeriod` and then converting from seconds to the unit determined by `TIME_UNIT_INV`. Note that EGU will be the parameter `TIME_EGU` passed to `TRSIS.db`. For the first event group after arming this is relative to when the digitizer was armed. When `clearTimestamp` is used to reset the timestamp counter, it is expected that the lastRelTime of the first event acquired after clearing will be incorrect (likely very large). This is because the sofware does not try to track which events were acquired before/after clearing and simply subtracts timestamps of adjacent events.
`delayedArmsCount` (longin)	Counts how many times rearming of the digitizer was delayed due lack of buffer space for the current acquisition. This can be used to detect overload of the IOC. The count is initialized to zero when acquisition is started and is incremented whenever the interrupt handler was not able to rearm the digitizer because there was not enough space in the sample buffer or the events ring buffer (see `eventsBufferSize`). The PV is updated with every processed burst not immediately when this occurs.

Note about Clock PVs

Because the hardware only supports several discrete clock sources, some clock-related PVs provided by the framework do not have any real function with this driver. The unsupported PVs are:

_requestedSampleRate, GET_ARMED_REQUESTED_SAMPLE_RATE,
ACHIEVABLE_SAMPLE_RATE, ACHIEVABLE_SAMPLE_RATE.

These PVs can be excluded from an IOC by passing NOCLK=# to TRBase.db. This is done in the test IOC.

However, GET_DISPLAY_SAMPLE_RATE is available and reflects the selected clock source while armed (and extRate in case of external clock).