Test specification
General Standards Digitizer Integration
Revision: 1.4
Status: Released
Project: C-SLAC-GenStds_digitizer
Document ID: CSL-TPL-16-135833
Last modification: July 31, 2017
Created: January 31, 2017
© 2017 Cosylab
–i–
Confidential
Released
CSL-TPL-16-135833 v1.4
Document History
Revision Date
Changed/ Section(s)
reviewed
1.0
2016-10-28 abizjak
1.1
2016-11-09 abizjak
1.2
2016-11-10 Jpdef
1.3
2017-01-31 abizjak
1.4
2017-02-02 abizjak
Modification
Initial version.
Initialize Action
Tests
Correcting Initialize test.
Updating driver version.
Added space for initials and
dates
Tests
Changes to accommodate
refactored
software,
editorial changes
Tests
Corrected IOC paths, GUI
screenshot and example
IOC startup output.
Confidentiality
This document is classified as a confidential document. As such, it or parts thereof must not be
made accessible to anyone not listed in the Audience section, neither in electronic nor in any
other form.
Scope
This document defines the Test Plan for the EPICS integration of General Standards digitizers.
Audience
The audience of this document is the test engineers who will execute the Test Plan and produce
the Test Report.
© 2017 Cosylab
– ii –
Confidential
Table of Contents
1. Introduction
5
2. Test Environment Setup
6
2.1. Hardware ............................................................................................................... 6
2.2. Software ................................................................................................................ 7
2.2.1. Preparing the Environment ............................................................................ 7
2.2.2. Running the EDM Screens ............................................................................ 9
3. Tests
12
3.1. Miscellaneous tests.............................................................................................. 12
3.1.1. Initialize Action ............................................................................................ 12
3.1.2. Device Information....................................................................................... 13
3.2. Device configuration ............................................................................................ 14
3.2.1. Voltage range, input mode and channel selection........................................ 14
3.2.2. Re-arming an armed device ........................................................................ 16
3.2.3. AUX-IO settings ........................................................................................... 16
3.2.4. Clock calculation.......................................................................................... 17
3.3. Data acquisition ................................................................................................... 19
3.3.1. Channel mapping ........................................................................................ 19
3.3.2. Burst processing .......................................................................................... 20
3.3.3. Single-burst mode ....................................................................................... 20
3.3.4. Voltage calculation ...................................................................................... 21
3.3.5. Sample clock and burst size ........................................................................ 22
3.3.6. Buffer overflow recovery .............................................................................. 23
3.3.7. External sample clock .................................................................................. 24
3.3.8. Demand-Mode DMA .................................................................................... 25
3.4. Additional burst information .................................................................................. 26
3.4.1. Time array ................................................................................................... 26
3.4.2. Data timestamps.......................................................................................... 26
3.4.3. Relative times .............................................................................................. 27
3.4.4. Data snapshot ............................................................................................. 28
3.4.5. Sample rate tags ......................................................................................... 28
3.5. Reliability tests ..................................................................................................... 29
3.5.1. Long-running acquisition.............................................................................. 29
Tables
Table 1: List of hardware tested .................................................................................................... 6
Table 2: List of software components (correct manually as necessary) ....................................... 7
© 2017 Cosylab
– iii –
Confidential
Released
CSL-TPL-16-135833 v1.4
References
[1]
Requirements Specification, General Standards Digitizer Integration, CSL-SPE-16-132878
rev 1.2
[2]
http://www.generalstandards.com/downloads/16ai64ssa.linux.3.6.68.18.0.tar.gz
© 2017 Cosylab
– iv –
Confidential
CSL-TPL-16-135833 v1.4
1. Introduction
Released
1. Introduction
This test specification defines tests for the EPICS integration of General Standards digitizer
devices 16AI64SSC and 16AI64SSA, covering the requirements of the project as defined in the
requirements specification [1].
© 2017 Cosylab
– 5 / 31 –
Confidential
Released
2. Test Environment Setup
CSL-TPL-16-135833 v1.4
2. Test Environment Setup
All tests in this document are performed on the SLAC premises with the test setup described in
the following chapters.
2.1. Hardware
Table 1: List of hardware tested
ID
Hardware item
Location and manager device
For the majority of tests, the card under test will have to be connected to a function generator
with two output channels:
1. A trigger channel, which is a TTL-level digital output (e.g. 3V) providing trigger events
(e.g. a square wave). It must be connected to the “SYNC I/O” line on the card’s I/O
connector, and the associated ground must be connected to the “SYNC I/O RTN” line.
2. A signal channel, which is an analog output capable of voltages between -10V and +10V.
In most tests this channel will be connected to one of the input lines such as “INP 00”
and the associated ground to some “INPUT RTN”.
In the test for testing with an external sample clock (3.3.7), a digital TTL-level output will have
to be connected to one of the four input/output pins on the AUX header of the board (and the
signal ground to one of the two AUX ground lines). This could be the same output of the function
generator that is otherwise used for the trigger.
In the test for voltage levels (3.3.4), testing pseudo-differential and full-differential modes
requires special configuration, where two separate analog signals will need to be provided. One
signal (base signal) will be connected to one of the INP lines; for pseudo-differential this can be
any except “INP 00”, for full-differential this can be any even-numbered line. The other signal
(reference signal) will be connected to the associated reference input; for pseudo-differential
this is “INP 00”, for full-differential this is the odd INP line following the base signal line.
In other tests (i.e. except test 3.3.4) which involve observing data acquired in pseudo- or fulldifferential mode, the reference input associated with the channel being observed should be
© 2017 Cosylab
– 6 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
2. Test Environment Setup
Released
bridged to one of the “INPUT RTN” lines, so that the reference input is stabilized to zero instead
of being left floating.
2.2. Software
Table 2: List of software components (correct manually as necessary)
Software component
Version
Linux RT operating system
Red Hat 6 RT, 3.18 kernel, Buildroot 2015.02
General Standards 16ai64ssa Linux driver
3.6.68.18.0 [2]
EPICS Base
3.14.12.4_1-1
asynDriver
R4-29 (included in the source package)
AreaDetector
Unreleased version, included in the source
package
Note that the version of EPICS Base included in the source package is different from the one
mentioned above. To test the intended version, an option will have to be provided to a configure
script (explained below).
2.2.1. Preparing the Environment
To perform the tests, the following steps must be performed:

Compile and start the driver. Verify that the driver is running.

Connect the function generator to the card.

Run the IOC on the test machine.

Run the EDM screens.
2.2.1.1. Building the driver
Download and extract the driver (source code). After extraction, a new directory 16ai64ssa will
be created.
Build the example programs and the driver:
$
$
$
$
cd 16ai64ssa
bash make_all
cd driver
make
© 2017 Cosylab
– 7 / 31 –
Confidential
Released
2. Test Environment Setup
CSL-TPL-16-135833 v1.4
Load the driver by running this command as root from the driver directory:
# bash start
To verify that the driver is loaded, run the following command:
$ cat /proc/16aissa
The output of the command should look as follows (some information will vary based on the
boards installed):
version: 3.5.67.17
32-bit support: yes
boards: 1
models: 16AI64SSA
The driver installation procedure may need to be adapted based on the target platform. The
driver is not part of the delivered software and therefore these instructions are to be understood
as informational only. The vendor may need to be contacted regarding issues with the driver.
2.2.1.2. Building the IOC application
Ensure that the dependencies of EPICS and AreaDetector are satisfied. On RedHat-based
systems, the following command can be used to install AreaDetector dependencies.
# yum install libjpeg-devel libtiff-devel hdf5-devel libxml2-devel
Extract the genstds-epics source tree. A directory named genstds-epics will be created. Then use
the following commands to build the IOC application.
$ cd genstds-epics
$ python2.7 -B prepare.py -d <path-to-driver> -b <path-to-base>
$ make
It is necessary to pass the following paths to the prepare script:

Path to the driver source code (subdirectory driver of the 16ai64ssa directory).

Path to a pre-built EPICS Base. This should be the Base version used in SLAC. Note that
if the path is not specified via the “-b” option, a bundled version of Base will be used.
Python version 2.7 is required to run the prepare script.
Check for and resolve any build errors before proceeding.
2.2.1.3. Starting the IOC application
Ensure that the IOC application process will have the required real-time privileges. This can be
achieved by adding the following to the file /etc/security/limits.conf (with the correct
username):
© 2017 Cosylab
– 8 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
2. Test Environment Setup
Released
username - memlock 2000000
username - rtprio 80
After this change it is necessary to do a new log-in as this user, as the setting is not applied to
existing shells.
Before starting the IOC, it may be necessary to adjust some configuration in the IOC startup
script, TRGeneralStandards/iocBoot/iocgenStdsTestIoc/st.cmd. The following options may be of
interest:
# device node
epicsEnvSet("GENSTDS_DEVICE", "/dev/16ai64ssa.0")
# prefix of all records
epicsEnvSet("PREFIX", "GENSTDS")
# Size (NELM) of waveform records.
epicsEnvSet("WAVEFORM_SIZE", "2048")
Use the following command from within the source tree to start the IOC.
$ bash TRGeneralStandards/iocBoot/iocgenStdsTestIoc/run.sh
The output should be similar to:
Successfully locked memory using mlockAll
#!../../bin/linux-x86_64/genStdsTestIoc
< envPaths
--- many lines not shown --iocInit
Starting iocInit
###################################################################
#########
## EPICS R3.14.12.5 $Date: Tue 2015-03-24 09:57:35 -0500$
## EPICS Base built Feb 1 2017
###################################################################
#########
iocRun: All initialization complete
epics>
If the output of the command differs greatly and especially if it contains any error, the IOC did
not start correctly. In this case it is advised to verify that the driver is loaded and that the correct
device node is configured in the IOC startup configuration.
Verify that the line “Successfully locked memory using mlockAll” is present. If it is not, real-time
privileges are probably not configured correctly. Or the selected version of EPICS Base does not
include the memory locking feature. Do not proceed until the line can be seen.
2.2.2. Running the EDM Screens
To run the EDM screens move into edmGUI folder and use next command from the source tree
root:
$ cd TRGeneralStandards/edmGUI
$ edm -m "PORT=GENSTDS" -x genStdsDisplay.edl
© 2017 Cosylab
– 9 / 31 –
Confidential
Released
2. Test Environment Setup
CSL-TPL-16-135833 v1.4
Verify that the PVs are connected. If they are not, it may be necessary to adjust the environment
variables EPICS_CA_ADDR_LIST and EPICS_CA_AUTO_ADDR_LIST before starting edm.
Figure 1: The EDM GUI
2.2.2.1. Introduction to the GUI
In the top left container, we can find the main operating button controls i.e. disarm and
postTrigger. When postTrigger is clicked, the settings from this and from top central container
(where system input and channel active setting can be found) will be applied to the device. At
this point the device is armed i.e. ready to accept triggers, read input data and provide it to the
waveform records. Note that clicking the postTrigger button again will re-arm the device,
however for testing purposes it is recommended to always disarm. The device can be disarmed
by clicking on the disarm button, which reconfigures the device to a default state, where it is
unable accept triggers and process data.
The settings in the top right container are applied immediately and can be modified at runtime
regardless of device arm state. The voltage offset is applied to future bursts.
Other containers display read back information. The bursting information section contains
timing data about burst processing, the buffering states section shows info vital to digitizers
internal FIFO buffer, the armed settings section displays the current armed settings, and the
device information section shows static device properties.
© 2017 Cosylab
– 10 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
2. Test Environment Setup
Released
Channel data can be viewed in the graph on the main display. One of 16 preset channels can be
chosen using the button above the chart. The update speed (fast or slow) can be chosen by using
the button to the right. Note that the set of selectable channels is limited due to the capabilities
of EDM, but it can be changed in edit mode. Additionally, it is possible to view channel data in a
separate window, using the buttons in the bottom-right section of the main window.
© 2017 Cosylab
– 11 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
3. Tests
The following two test configurations are commonly used in the tests. Most of the settings are
done using the EDM GUI.
Test configuration 1 (these should be the default settings also shown in Figure 1):
- clock 10kHz,
- burst size 900
- auto restart on
- burst timestamp on,
- DM-DMA off,
- single-ended input mode,
- channel range “Channels 0-31”,
- single channel 0,
- first channel in range 0,
- last channel in range 1,
- voltage range +-10 V,
- settings of auxiliary-IO lines left at default values
Test configuration 2: all settings as above except:
- clock 33kHz (via Custom Frequency),
- burst size 1980
For all tests the IOC and GUI must be running, if not noted otherwise.
Except as noted in specific tests, a function generator should be configured to produce a 10Hz
square wave on the trigger channel, and a 200Hz sine wave with amplitude +- 10 V on the signal
channel.
Note that certain settings can be different if they are not relevant for the functionality being
tested, or if they are not relevant due to values of other settings (e.g. the “single channel” value
is irrelevant if the channel-range is not “single”).
Several tests involve monitoring values of PVs that represent configuration readbacks from the
hardware. The IOC is designed to refresh these automatically whenever the device is armed or
disarmed or when the Initialize action completed (but they are not refreshed periodically). For
the tests that use these readbacks, this is sufficient so there is no need to force refreshing.
3.1. Miscellaneous tests
3.1.1. Initialize Action
Description
Test the Initialize action.
Pre-requisites
Test configuration 1. Function generator not needed for this test. EDM GUI running.
Test procedure
© 2017 Cosylab
– 12 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
Part 1:
Set the voltage range to any value other than +-10V. Arm and disarm.
Verify that the hardware readback of the voltage reflects the value which was selected:
$ caget GENSTDS:VOLTAGE_RANGE_RBV
Click on the Initialize button.
Verify that the result field to the right of the button shows “success” and clears after
approximately 5 seconds (5-6).
Verify that the hardware readback of the voltage range is again +-10V (with the same command
as before). The change of the voltage range in the hardware proves that initialization was
actually performed. Note, the voltage range selection is not expected to change, just the
hardware readback.
Part 2:
Arm for acquisition. Click Initialize.
Verify that the result shows “fail” immediately and clears after approximately 5 seconds.
Part 3:
Disarm.
Click Initialize. After “success” appears, click the same action again before it clears (e.g. 4
seconds later). Verify that the status remains “success” and clears after approximately 5
seconds.
Click Initialize. Wait for the result to clear then click the same action again, within 1s. Verify that
“success” is shown again and clears after approximately 5 seconds.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.1.2. Device Information
Description
Verify that information about the device is reported correctly.
Pre-requisites
EDM GUI and IOC not running initially. Function generator not needed.
Test procedure
Ensure the IOC is not running. In a terminal, change to the source tree of the driver. Run the “id”
program:
$ ./id/id
It should return result similar as this.
USAGE: id <index>
index The zero based index of the device to access.
…
© 2017 Cosylab
– 13 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
RESULTS: PASS (duration 0:0:00)
SUMMARY: tests 1, pass 1, fail 0 (duration 0:0:00)
If there are multiple boards installed, pass the device number to this program, of the board being
tested.
Now start the IOC and EDM GUI and check that all information in the device-information section
of the GUI (except the device name) matches that produced by the “id” program:
- Firmware revision
- Master clock frequency
- Maximum sample rate
- Device type
- Maximum number of channels
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.2. Device configuration
3.2.1. Voltage range, input mode and channel selection
Description
Test that the desired voltage range, input mode, and channel selection are applied when arming.
This test relies on readbacks only but is relatively exhaustive. In other tests, some of these
settings will be verified indirectly in the context of acquisition.
Pre-requisites
Test configuration 1. Function generator not needed for this test. EDM GUI running.
Test procedure
First configure: trigger=softTrigger, system-input-mode=single-ended, channel-range=
channels-0-31, first-channel-in-range=0, last-channel-in-range=31, single-channel=2.
In this test different settings will be tested. Each time, some settings will be set, the device will
be armed by pressing postTrigger, and then the result will be checked, typically by observing a
readback PV.
In cases where arming succeeds, one must verify the associated values in the Armed Settings
section of the GUI in addition to the readback PVs specified. Also, when postTrigger is pressed,
the arm state must change to postTrigger, except in specific cases where arming must fail with
an error indication.
At the end of each test step, disarm must be pressed before testing the next configuration, at
which point the arm state must change to disarm.
Part 1: Test all different voltage ranges. In each case after arming, verify that the readback PV
matches:
© 2017 Cosylab
– 14 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
$ camonitor GENSTDS:VOLTAGE_RANGE_RBV
Part 2: Test all values of system-input-mode. In each case after arming, verify that the readback
PV matches:
$ camonitor GENSTDS:INPUT_MODE_RBV
Part 3: Using system-input-mode=single-ended, test all values of channel-range. In each case
after arming, verify that the readback PV matches:
$ camonitor GENSTDS:CHANNEL_ACTIVE_RANGE_RBV
Repeat the above also with system-input-mode=zero-test-voltage and =reference-voltage.
Part 4: Using system-input-mode=single-ended and channel-range=single, test different values
of single-channel. Test at least -1, 0, 1, 62, 63, 64. For values outside of 0-63, arming must fail.
For values within 0-63, arming must succeed and the readback PV must match.
$ camonitor GENSTDS:CHANNEL_SINGLE_RBV
Repeat the above also with system-input-mode=zero-test-voltage and =reference-voltage.
Part 5: Using system-input-mode=single-ended and channel-range=channel-range, test
different values of first-channel-in-range and last-channel-in-range. Test at least (0,63), (-1, 63),
(0, 64), (1, 62), (1, 2), (1, 1). For combinations where either the first or last channel are outside
of 0-63 or the last channel is not greater than the first, arming must fail. Otherwise, arming must
succeed and the readback PVs must match.
$ camonitor GENSTDS:CHANNEL_RANGE_FIRST_RBV
$ camonitor GENSTDS:CHANNEL_RANGE_LAST_RBV
Part 6: Using system-input-mode=pseudo-differential, test that:
- Arming succeeds when channel-range is any of channels-0-N (all except single and
channel-range).
- Arming succeeds when channel-range=single and single-channel is a valid channel other
than 0 (test at least 1 and 63).
- Arming fails when channel-range=single and single-channel is 0.
- Arming succeeds when channel-range=channel-range, the first/last-channel is a valid
range of at least two channels and does not include 0 (test at least (1,2) and (62,63)).
- Arming fails when channel-range=channel-range, first-channel is zero and last-channel
is in the range 1-63 (test at least 1 and 63).
Part 7: Using system-input-mode=full-differential, test that:
- Arming succeeds when channel-range is any of channels-0-N (all except single and
channel-range.
- Arming succeeds when channel-range=single and single-channel is a valid evennumbered channel (test at least 0 and 62).
- Arming fails when channel-range=single and single-channel is an odd-numbered channel
(test at least 1 and 63).
- Arming succeeds when channel-range=channel-range and first/last-channel is a valid
range starting with an even-numbered channel and ending with an odd-numbered
channel (test at least (0,1), (0,3) and (62,63)).
- Arming fails when channel-range=channel-range and first/last-channel is a valid channel
range starting with an odd-numbered channel or ending with an even-numbered
channel (test at least (1,2), (1,3), (2, 4), (3, 4)).
Test result:
© 2017 Cosylab
Not tested
Passed
– 15 / 31 –
Failed
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
Comment:
Initials:
Date:
3.2.2. Re-arming an armed device
Description
Test that the desired voltage range, input mode and channel selection are applied when device
is already armed. Note that re-arming is not tested exhaustively as that would mean duplicating
the work in most tests.
Pre-requisites
Test configuration 1. Function generator not needed for this test. EDM GUI running.
Test procedure
First set trigger=softTrigger and arm the device.
Set voltage-range=0-5V, system-input-mode=zero-test-voltage, channel-range=channels-0-63.
Set the clock to a custom frequency, custom sample rate to 10 Hz and set trigger to external.
Re-arm the device by pressing postTrigger, without pressing disarm first.
The desired settings should now match the hardware readbacks. Use “caget” to check the
setting values. Note, the expected value for CLOCK_SOURCE_RBV is “Rate-B”.
$
$
$
$
caget
caget
caget
caget
GENSTDS:VOLTAGE_RANGE_RBV
GENSTDS:INPUT_MODE_RBV
GENSTDS:CHANNEL_ACTIVE_RANGE_RBV
GENSTDS:CLOCK_SOURCE_RBV
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.2.3. AUX-IO settings
Description
Test that the desired auxiliary line settings are applied immediately when changed. This test
relies on readbacks only.
Pre-requisites
Test configuration 1. Function generator not needed for this test. EDM GUI running.
Test procedure
The settings covered by this test are applied immediately not when arming. Therefore, each step
will involve changing the setting and verifying the readback PV. The button state in the GUI must
change to the selected value as well.
Since each setting will have an initial value, it is suggested to first only verify it, and later after
having tested at least one other value test the initial value fully.
© 2017 Cosylab
– 16 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
Part 1: Test all values of each aux-line-<N> (<N>=0,1,2,3). Verify with:
$ camonitor GENSTDS:GET_AUX_LINE_<N>_MODE
Part 2: Test both values of aux-invert-in. Verify with:
$ camonitor GENSTDS:GET_AUX_INVERT_IN
Part 3: Test both values of aux-invert-out. Verify with:
$ camonitor GENSTDS:GET_AUX_INVERT_OUT
Part 4: Test both values of aux-noise-suppression. Verify with:
$ camonitor GENSTDS:GET_AUX_NOISE_SUPPRESSION
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.2.4. Clock calculation
Description
Test that clock configuration is calculated according to the desired sample rate.
Pre-requisites
Test configuration 1. Function generator not needed for this test. EDM GUI running.
Test procedure
Note that the master clock frequency, which needs to be known for this test, is displayed in the
GUI in the “device information” section.
In this test, different sample rates will be selected (both presets and custom-frequency) and the
resulting achievable-sample-rate should be checked. Note that in order to see the achievablesample-rate at a sufficient precision, it may be necessary to use a “camonitor” command as
shown, instead of relying on the GUI.
$ camonitor -f 15 GENSTDS:ACHIEVABLE_SAMPLE_RATE
Part 1:
Choose different preset frequencies (available in the clock button). Verify that for each case, a
frequency very close to the selected one appears in the achievable-sample-rate field.
Choose custom-frequency and enter different frequencies into the custom-frequency field.
Verify that for each case, a frequency very close to it appears in the achievable-sample-rate field
(except for frequencies out of range of the device – see next part).
Part 2:
Test desired frequencies outside of the achievable range (minimum frequency = master-clockfrequency/655352, maximum frequency is shown under Device Information in the GUI). Verify
that frequencies outside of these bounds are clamped into the achievable range.
Part 3:
© 2017 Cosylab
– 17 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
Test some frequencies which can be exactly achieved. These are master-clock-frequency/(N*M)
for N and M both between 250 and 65535. In these cases, the achievable-sample-rate must be
exactly equal to the desired rate. Make sure to test some frequencies which can be achieved
with one divider only (those not below master-clock-frequency/65535) as well as some (low)
frequencies which require chained dividers.
In each case, check that calculated divisors in fact produce the requested sample rate. Get the
divisors with the following command:
$ camonitor GENSTDS:CALC_DIVISOR_{A,B}
The desired sample rate must be equal to master-clock-frequency/A (if B is 0) or master-clockfrequency/(A*B) (if B is not zero).
Part 4:
Test frequencies which cannot be exactly achieved:
o For sample rates which can be achieved using only one frequency divider (not below
master-clock-frequency/65535), a simple test is that the error does not or only slightly
exceeds requested-frequency2/(2*master-clock-frequency). This is an approximation of
the error based on a derivative.
Another approach is to find the solution manually. This can be done by calculating
D=(master-clock-frequency/desired-sample-rate), calculating A=floor(D) and B=ceil(D),
picking A or B based on which minimizes the error of the sample rate, and returning the
resulting sample rate (master-clock-frequency/(A or B)).
o For the lower sample rates that require chaining the two frequency dividers, there is
unfortunately no simple accurate test of the error. One may verify the result by finding
the solution. The procedure for solving this is similar to the one described above, except
that A and B are determined as follows:
 A is the greatest integer <=D which can be factored into a product of two
integers between 250 and 65535.
 B is the smallest integer >=D which can be factored into a product of two
integers between 250 and 65535.
An example calculation is given below.
Example calculation for solving frequencies that require two dividers:
Suppose we desire a sample rate of 12.3 Hz.
Calculate D = 50MHz/12.3Hz = 4065040.6…
4065040 can already be factored as 3920*1037, therefore A=4065040.
The prime factorization of 4065041 is 59*68899, which is not acceptable because one of the
factors is too large. So we check the next integer 4065042, which can be factored as 222*18311.
This factorization is acceptable, therefore B=4065042.
The frequency error using A is abs(12.3Hz-(50MHz/A))= 1.96…e-06..
The frequency error using B is 4.08…e-06.
Since A gives a smaller error, the result is to use frequency divider values 3920 and 1037, which
achieve the sample rate 12.300001968… Hz.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
© 2017 Cosylab
Date:
– 18 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
3.3. Data acquisition
3.3.1. Channel mapping
Description
Test that the selected set of channels is correctly mapped to physical channels and their data
waveforms.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Note that in the tests below, channels within and outside of the selected range are checked. It
is recommended to test at least the first and last selected channel, the channel before the first,
and the channel after the last selected channel (as applicable).
In tests other than for zero-test-voltage and reference-voltage, rewiring the signal line is needed
to verify the waveforms observed. But note that the purpose of these tests is not to verify exact
correctness of data, only that the mapping is correct.
Part 1:
Make sure the function generator’s signal ground is connected to some “INPUT RTN” line.
Using system-input-mode=single-ended, test all channel-range=channels-0-N, and =single with
different single-channel, and =channel-range with different ranges (first/last). Verify that in each
case, the selected channels receive updates with the expected waveform but others do not.
Part 2:
Using system-input-mode=zero-test-voltage and then =reference-test-voltage, test all channelrange=channels-0-N, and =single with different single-channel, and =channel-range with
different ranges. Expect updates on the selected channels (near zero or near maximum values)
and no updates on other channels.
Part 3:
Make sure that the “INP 00” line is bridged to some “INPUT RTN” and the function generator’s
signal is connected to some other input line e.g. “INP 01”.
Using system-input-mode=pseudo-differential, test all channel-range=channels-0-N, and=single
with different single-channel except 0, and =channel-range with different ranges except those
starting with 0. Verify that in each case, the selected channels except channel 0 receive updates
with the expected waveform but others (including channel 0) do not.
Part 4:
For this part it is necessary to connect the signal to an even-numbered INP line being tested and
bridge the following odd-numbered INP line connected to some “INPUT RTN”.
Using system-input-mode=full-differential, test all channel-range=channels-0-N, and =single
with different even-numbered single-channel, and =channel-range with different ranges valid
for full-differential mode (even first-channel and odd last-channel). Check that in each case,
even-numbered selected channels receive updates with the expected waveform but others do
not.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
© 2017 Cosylab
Date:
– 19 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
3.3.2. Burst processing
Description
This test verifies that software is able to process bursts and accordingly update the channel data
and burst metadata.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Part 1:
Set channel-range=single and set single-channel to the channel where the signal is connected.
Arm for acquisition.
Verify the following:
 The data of the selected channel updates regularly (as per external trigger) and the
waveform is as expected.
 Bursts-per-second shows approximately the trigger frequency.
 Last-burst-ID is incremented after completion of each burst.
 Time-of-last-burst changes after completion of each burst to the time when the burst
started. Note, correctness of the timestamp will be checked in another test case.
 The three relative burst timestamps are updated with each burst.
Disarm acquisition. Verify that bursts-per-second becomes 0 after no more than 1 second, and
that none of the other aforementioned information including the channel data updates any
more.
Part 2:
Do as in Part 1, but select trigger=soft before arming. Then click softTrigger (i.e. Send Software
Trigger button) a few times.
Verify that the software processes a burst only each time softTrigger is pressed (except when
softTrigger is pressed before the current burst is completed). Particularly, verify that the burstID increments by exactly 1 each time.
Try pressing softTrigger at different rates and verify the displayed bursts-per-second (likewise,
note that if it is pressed too soon after, triggers will be missed).
Disarm. Verify that pressing softTrigger now has no effect.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.3. Single-burst mode
Description
Test that in single-burst mode (autoRestart if off), the device is disarmed after the first burst is
read.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
© 2017 Cosylab
– 20 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
Test procedure
Set trigger=external and auto-restart=on. Arm. Verify that bursts are being processed.
Disarm and arm using auto-restart=off. Verify that the only the first burst is processes and the
arm state changes to disarm automatically after that.
Test again but now with trigger=soft. Verify that the device disarms only after softTrigger is
pressed.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.4. Voltage calculation
Description
Test that the conversion of raw data to voltage is correct, and that the user-configurable voltage
offset is applied. Note that testing voltage ranges with differential input modes requires
different function generator configuration as described in 2.1.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Note: all of the tests here must be done with channel-range=single.
Part 1 (single-ended mode):
Make sure the function generator’s signal is connected to any of the INP lines and the signal
ground is connected to an “INPUT RTN” line.
Set system-input-mode=single-ended and set single-channel to the channel which is connected
to the signal from the function generator. Select voltage-range=+-10V. Configure the function
generator for a +-10V sine wave. Arm for acquisition.
Verify that the channel data for the selected channel shows a sine waveform with the expected
voltage range (visually).
Perform a similar test for all other available bipolar voltage ranges (+-5V, +-2.5V) – configure the
same voltage range on the function generator and in the device. Verify the voltages in the
waveform, it must be oscillating between the minimum (negative) and maximum (positive) of
the selected voltage range and that the height of the data peaks corresponds to the generated
function, if in scope of the voltage range.
Perform a similar test for all available unipolar voltage ranges (0-10V, 0-5V) – configure the same
unipolar voltage range on the function generator and in the device. Verify the voltages in the
waveform shown, it must be oscillating between 0 and maximum of the selected voltage range
and that the height of the data peaks corresponds to the generated function, if in scope of the
voltage range.
Part 2 (pseudo-differential mode):
Connect one analog output from the function generator to any of the INP lines other than “INP
00” and another analog output to “INP 00” (differential reference channel).
© 2017 Cosylab
– 21 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
Set system-input-mode=pseudo-differential, trigger-type=softTrigger, select voltage-range=+10V and set single-channel to the channel which is connected to the first analog output from the
function generator.
Configure the function generator to produce sine signals for both channels with same frequency,
same phase and oscillating within the input voltage range. Arm for acquisition, send software
trigger and check voltage data shows sine signal oscillating with an amplitude equal to the
difference of the two signals. Disarm, change voltage range and arm for acquisition. Verify the
voltage in the channel data are consistent for all bilateral voltage ranges and for unilateral
voltage accordingly.
For example:
If the first signal has amplitude of 2V and the second has 1.5V: the resulting channel waveform
oscillates from between 0.5V to -0.5V.
Repeat the above for all input voltage ranges. Make sure that the outputs of the function
generator do not saturate the inputs according to the input voltage range. This also means that
when testing unipolar voltage ranges, the function generator should produce a non-negative
output.
Part 3 (full-differential mode):
Connect one analog output from the function generator to any even-numbered INP line and
another analog output to the following odd-numbered INP line.
Set system-input-mode=full-differential, trigger-type=softTrigger, voltage-range=+-10V and set
single-channel to the selected even-number channel.
Test all the available voltage ranges as in Part 2, verifying the voltages in the channel data for
the selected channel.
Part 4:
With any of the configurations above, set the voltage offset to a nonzero value. Verify that the
voltage shown in the waveform is offset by that amount (that the voltage offset is added to the
data), for bursts processed after the change is made.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.5. Sample clock and burst size
Description
Test configuration of the sample rate and burst size, and correctness of the time axis.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Part 1:
Arm with different sample rates, and make sure to try at least with one preset and one custom
frequency. For each case only verify that the achievable-sample-rate is copied to the armedsettings.
Part 2:
© 2017 Cosylab
– 22 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
Arm with different combinations of sample-rate (try at least one frequency using one divider
and one frequency using two dividers) and burst-size. Verify (visually) that signal length equals
burst-size/sample-rate, and that the number of wavelengths in the data is equal to burstsize*signal-frequency/sample-rate.
Note: if a burst size greater than the value of the WAVEFORM_SIZE setting is configured, the
extra samples will not be shown. This test should only be executed with burst sizes that do not
exceed WAVEFORM_SIZE.
For example, the following configurations can be tested, all using a 200Hz signal:
- sample-rate 100kHz, burst-size 1000: signal length is 0.01s – 0.01s of data and exactly
two wavelengths should be displayed
- sample-rate 40kHz, burst-size 600: signal length is 0.015s – 0.015s of data and exactly
three wavelengths should be displayed
Part 3:
Determine the buffer size of the device. Valid buffer sizes are powers of two, such as 262144.
Note that the buffer size depends on the device and is part of its model number (here K means
1024, e.g. 256K = 256 * 1024). The buffer size can also be retrieved using software:
$ caget GENSTDS:GET_BUFFER_SIZE
A mismatch between this PV and the model number indicates a defect in the vendor’s driver,
which should be reported to the vendor. Note that if the software reports a larger than actual
buffer size, than the buffer overflow handling of the software will not work.
Select a single channel. Try to arm with burst size at and beyond the bounds of the valid range
1 to (buffer-size - 1). Verify that arming succeeds with the former succeeds but fails with the
latter (try at least the boundary values (buffer-size - 1) and buffer-size).
Select Channels 0-31. Calculate the associated maximum burst size which may fit in the buffer:
floor((buffer-size - 1) / 32). Verify that arming succeeds with this maximum buffer size and fails
with one greater buffer size. Other numbers of channels may be tested too (divide by the
number of channels).
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.6. Buffer overflow recovery
Description
Test that the software detects and recovers from buffer overflow.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Set the delay after burst processing to 0.11 seconds as shown. This software feature is
implemented specifically for this kind of test.
caput GENSTDS:SET_TEST_READ_SLEEP_TIME 0.11
© 2017 Cosylab
– 23 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
Don’t forget to reset this to 0 before performing other tests (or restart the IOC).
Arm for acquisition. Observe buffering states in the GUI as well as the IOC output.
Expected result:
 The buffer-samples number is increasing.
 When the number reaches the buffer-size, buffer-overflow status turns to overflow,
burst state to idle and IOC outputs messages similar to the following.
sevr=minor TRBaseDriver Warning: Buffer overflow, reading up to 8
remaining bursts
sevr=minor TRBaseDriver Warning: Restarting after overflow.


After the second message (restarting after overflow), the number of samples falls to 0
or close to 0, overflow status switches to no overflow, burst status to active and
sampling continues (growing again).
More overflows occur and associated recovery attempts also succeed (check that at
least one more overflow works).
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.7. External sample clock
Description
Test acquisition using an external sample clock, provided to one of the inputs in the AUX header.
The NDArrays should be tagged with the user-provided sample rate.
Pre-requisites
Test configuration 1. Function generator connected to provide a clock signal to one of the four
AUX I/O lines (described in chapter 2.1). EDM GUI running.
Test procedure
Part 1:
Set the mode of the AUX-IO line to which the generator is connected to be active-input (instead
of inactive).
Configure a known clock frequency on the function generator (at most 200kHz, which is the
maximum supported by the hardware).
Select clock “External Trigger”, set custom-sample-rate to the frequency of the external clock,
set trigger=softTrigger.
Verify that the achievable-sample-rate field is nan.
At this point you may also adjust the burst size. Note that the combination of burst size and
external clock frequency affects the duration of a burst, and it is recommended to select a
configuration where at least one wavelength fits into a burst, otherwise the result is harder to
verify visually.
Arm the device.
In the Armed Settings section, verify that sample-rate is nan and the display-sample-rate is what
was entered into custom-sample-rate.
© 2017 Cosylab
– 24 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
Part 2:
Send a software trigger using the button.
Verify that a burst was generated and that:
1. The X axis shows correct time, i.e. the sample data spans from zero to (burst-size 1)/display-sample-rate.
2. Check that the number of wavelengths is equal to burst-size*signal-frequency/externalsample-rate. For example, with signal frequency 20Hz, burst-size 100, external-samplerate 1kHz: exactly two wavelengths should be displayed.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.3.8. Demand-Mode DMA
Description
Test that usage of Demand-Mode DMA (DM-DMA) works. In this mode, the software starts a
DMA transfer without waiting for a complete burst to be present in the device’s FIFO buffer, and
the hardware transfers sample data to main memory as it becomes available.
Note that when using DM-DMA, the last two samples of a burst will always be copied using PIO
(which may involve polling, especially for slower sample data rates). This cannot be avoided due
to the design of the hardware (in fact doing it this way is a recommendation from the vendor,
to make DM-DMA work with bursting in the first place).
Also note that DM-DMA mode is not applicable in configuration where the number of data
samples in a burst (burst-size * number of channels) is <=34. In such configurations the software
will revert to normal DMA mode, and a warning will be printed to the IOC console during arming.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Arm the device but with DM-DMA enabled.
Verify that bursts are being processed and the data appears correct.
Then try arming with different combinations of burst-size and number of channels, and in each
case verify the same.
Try a configuration where (burst-size * number of channels) is equal to 35, such as burst-size=1
and using channel range 0 to 34. Verify operation and check that a warning about “Not using
DM-DMA” was not printed to the IOC console when the device was armed.
Try a configuration where (burst-size * number of channels) is equal to 34, such as burst-size=1
and using channel range 0 to 33. Verify operation and check that a warning about “Not using
DM-DMA” was printed to the IOC console when the device was armed.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
© 2017 Cosylab
Date:
– 25 / 31 –
Confidential
Released
3. Tests
CSL-TPL-16-135833 v1.4
3.4. Additional burst information
3.4.1. Time array
Description
Test that that software computes the time array according to the selected sample clock and
burst size when the device is armed.
Pre-requisites
Test configuration 1. Function generator not used. EDM GUI running.
Test procedure
Part 1:
Arm the device (with an internal sample clock). Verify that the time array contains exactly burstsize elements and that the elements are equal to i/expected-sample-rate, where i is the zerobased element index.
$ caget GENSTDS:TIME_DATA{,.NORD}
The NORD field of the record should be used to check the number of elements (which should be
equal to the burst size).
Possibly try with different burst sizes and sample rates. In case of using burst-size greater than
the configured WAVEFORM_SIZE, the time array should be cut short.
Part 2:
Arm the device using external clock, custom-sample-rate=1234Hz and software trigger. Note,
there is no need to connect an external clock.
Verify that the time array contains times based on the entered custom-sample-rate, i.e. i/
custom-sample-rate.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.4.2. Data timestamps
Description
Test that all the timestamps connected to the acquisition of data match.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Arm acquisition. Open and observe channel data on channel 0. Disarm and after at least one
second (to give time for the slow snapshot to update), check the data, data snapshot and last
burst time:
© 2017 Cosylab
– 26 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
$ caget -a GENSTDS:CH0:DATA GENSTDS:CH0:DATA_SNAPSHOT
GENSTDS:GET_LAST_BURST_TIME
Sanity check these values, verifying that:
- The timestamps of DATA, DATA_SNAPSHOT and GET_LAST_BURST_TIME and the value
of GET_LAST_BURST_TIME all match.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.4.3. Relative times
Description
Test that the diagnostic relative times between significant points in burst processing are
provided (burst-started-to-completed, burst-reading, burst-processing time).
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
In this test, the device will be armed with different combinations of burst-timestamp and DMDMA enabled settings, and the relative times will be verified. In each case, a specific subset of
the relative times are expected to update with each burst.
Part 1:
Arm the device with burst-timestamp=on and DM-DMA=off. Verify that with each burst, the
three relative times are updated and appear sane. Notably, burst-started-to-completed time
should be approximately equal to burst-size/sample-rate, however be aware that with shorter
bursts, the software latency may be too large for a meaningful comparison.
Part 2:
Arm the device with burst-timestamp=off and DM-DMA=off. Verify that the burst-started-tocompleted time is not available (=nan) but the other two times are available.
Part 3:
Arm the device with burst-timestamp=on and DM-DMA=on. Verify that the burst-started-tocompleted and burst-processing times are available but the burst-reading time is not (=nan).
Part 4:
Arm the device with burst-timestamp=off and DM-DMA=on. Verify that the burst-processing
time is available but the other two times are not.
Test result:
Not tested
Passed
Failed
Comment:
© 2017 Cosylab
– 27 / 31 –
Confidential
Released
Initials:
3. Tests
CSL-TPL-16-135833 v1.4
Date:
3.4.4. Data snapshot
Description
Test that the show data waveforms provide periodic snapshots of the latest channel data.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running.
Test procedure
Set to read data from all channels. Arm acquisition. Change the signal channel’s frequency on
the function generator so that it is not a multiple of the trigger frequency. Open channel 0 data
in a separate window. The name of the channel data PV can be observed in the title of the graph.
Observe channel data on channel 0 and verify that that data is updating at the trigger rate.
Click Slower and check that the data is now updating at 1 Hz, and that the PV name in the title
has changed accordingly. Use “camonitor” commands to confirm the refresh rate if necessary:
$ camonitor GENSTDS:CH0:DATA
$ camonitor GENSTDS:CH0:DATA_SNAPSHOT
Disarm the device and verify that the snapshot data is not updating. Then click Faster to return
to previous view.
Check the same for a few other channels.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.4.5. Sample rate tags
Description
Test that the NDArrays are tagged with the sample rate.
Pre-requisites
Test configuration 1. Function generator connected and configured. EDM GUI running. IOC not
running.
Test procedure
Modify the IOC startup script st.cmd file to load NDAttribute plugin, which extracts attributes
from NDArrays of other plugins (in this case channel port 0). The file can be found in the folder
TRGeneralStandards/iocBoot/iocgenStdsTestIoc. In the st.cmd file uncomment the next two
lines (contents are hidden for clarity):
# Uncomment to initialize NDAttrPlugin to test sample rate.
NDAttrConfigure(…)
…
# Uncomment to load records for NDAttrPlugin waveforms.
© 2017 Cosylab
– 28 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
3. Tests
Released
dbLoadRecords(…)
Start the IOC as described before.
Run the following command, to configure the NDAttrPlugin to extract the sample-rate attribute:
$ caput -S GENSTDS:SET_NAME_ATTR READ_SAMPLE_RATE
Arm the device, with an internal clock. Disarm after at least one burst is processed.
Obtain the value of the sample-rate attribute of the last array with the following command, and
verify that it matches the achieved-sample-rate.
$ caget GENSTDS:GET_VALUE_ATTR
Now arm with an external sample clock, custom-sample-rate=1234Hz and software trigger. It
should not be necessary to actually provide the external clock, because the device appears to
make a sample each trigger. Therefore one can choose a small burst size like 10, and press
softTrigger 10 times, for a burst to be completed. If this does not work, provide an external
sample clock as in test 3.3.7.
After a burst has been successfully generated, verify that the value of the last sample-rate
attribute is equal to the custom-sample-rate value which was used.
Test result:
Not tested
Passed
Failed
Comment:
Initials:
Date:
3.5. Reliability tests
3.5.1. Long-running acquisition
Description
Test longevity and reliability of software.
Pre-requisites
Execute separately with test configurations 1 and 2. Function generator connected and
configured. EDM GUI running.
Test procedure
Arm and leave to process data for a longer period of time (e.g. 4 hours or overnight, if possible).
Verify that the IOC still runs, there has been no buffer overflow (check the IOC console for
overflow recovery messages), and that bursts are still being processed.
Temporarily disconnect the trigger line and verify that the buffer-samples status quickly
becomes 0 (if it was not already). This proves that data processing did not lose synchronization
with burst boundaries.
Possibly test with different combinations of burst-timestamp-enabled and DMDMA-enabled.
Test result:
Not tested
Passed
Failed
Comment:
© 2017 Cosylab
– 29 / 31 –
Confidential
Released
Initials:
© 2017 Cosylab
3. Tests
CSL-TPL-16-135833 v1.4
Date:
– 30 / 31 –
Confidential
CSL-TPL-16-135833 v1.4
© 2017 Cosylab
0.
– 31 / 31 –
Released
Confidential