pptest

pptest is a tool for running a range of test protocols. Using the read-back interface, it allows to perform self-tests of the entire pulse generation system, including the advanced triggering. The source code of pptest also serves as an example of the API use, as it covers most of the elementary use cases.

pptest syntax

The basic syntax is

pptool <nr> [args...]

nr indicated the test number. We will strive to make the interface stable and maintain the numbering scheme, semantics and synthax.

Command line switches:

  • -c: number of counts (or the overall scale of counts)
  • -v: output data value (or a range of values, or the maximal value in randomized sequence generation)
  • -trig: perform the triggering sequence (subset of tests)
  • -p: trigger pattern
  • -m: trigger mask
  • -t: final data value
  • -check: perform verification using the read-back method
  • -timeout: specifies a timeout in seconds to interrupt checking process if no data is received for an extended period of time
  • -dump_converted: dump out the sequence of elements after converting elements with non-trivial update modes to simple BITLOAD elements
  • -i: initial value to be presented on the output ports before the sequence begins to stream out
  • -pll: configure the PLL; the argument is a PLL configuration string
  • -pll_charge_pump: set PLL charge pump parameter
  • -pll_bandwidth: set PLL bandwidth

Tests return code 0 if successful. Non-zero error indicates an error. The follow bits can be set:

  • bit 0: mismatch detected in sequence checker
  • bit 1: incorrect final data value detected

Integer parameter parsing

The numeric parameters can be expressed in decimal (42), hexadecimal (0x2A), octal (052) or binary (b101010). The parser is implemented in tidbit/misc.hh. Look for functions parse_uint8_t, parse_uint32_t and parse_uint64_t. Underscores are ignored; this allows large input values to be easier to read, e.g. 1_000_000_000. Finally, Verilog literals are also parsed correctly (e.g. 8`b1111_1111, 32`hFF_FF_FF_FF and similar).

WARNING: be careful not to use a leading 0 in what is intended to be a decimal number, because the string will be parsed as an octal base representation.

PLL settings

The PLL input clock is a 50MHz signal generated by a crystall oscillator on the DE10-Nano board. The default frequencies are 100MHz for both core and streaming clocks. To change them, the PLL can be reconfigured using the -pll command-line argument. The argument is a string, a comma separated sequence of interger values: N,M,C0,C1.

The streaming frequency is f_streaming = M*f/(N*C0), where f is the input frequency, f=50MHz.

The core frequency is f_core = M*f/(N*C1).

There is a number of preconfigured coefficient lists (defined in file c++/ppcommon.hh):

  • orig: default settings, f_streaming=f_core=100MHz
  • 100M: f_streaming=f_core=100MH, but with different PLL coefficients as for "orig"
  • 50M-100M: f_streaming=50MHz and f_core=100MHz
  • 10M-100M: f_streaming=10MHz and f_core=100MHz
  • 1M-100M: f_streaming=1MHz and f_core=100MHz
  • 75M: f_streaming=f_core=75MHz
  • 50M: f_streaming=f_core=50MHz
  • 25M-50M: f_streaming=25MHz and f_core=50MHz
  • 10M-50M: f_streaming=10MHz and f_core=50MHz
  • 5M-50M: f_streaming=5MHz and f_core=50MHz
  • 25M: f_streaming=f_core=25MHz
  • 20M: f_streaming=f_core=20MHz
  • 10M: f_streaming=f_core=10MHz
  • 1M: f_streaming=f_core=1MHz

pptest test cases

Test 1

Empty sequence (i.e., terminator element only). This can be used for testing the final data value setting using the -t switch.

Test 2

Sequence with a single element. Value and count can be specified using -v and -c.

Test 3

Counter: step up from a value specified by -v0 (included) to a value specified by -v (excluded). Fixed number of counts for each value (set by -c).

Test 4

Counter with a random number of counts. If -rnd is specified, the values are randomized, too.

Test 5

Test for no-strobing elements (three elements, one without strobes).

Test 6

Bitwise update mode test on a short sequence.

Test 7

Initial value test. Defaults to 4, use -iv to override. The switch -ns furthermore adds an initial no-strobe element with the same value. This can be used in combination with -timeout and -dont_wait to perform a self-test of the initial value setting.

Test 8

Fully randomized sequence testing (random values, random counts, random update operations).

Test 9

Test qout_override functionality: sends out a sequence, check the final qout value, then overrides it with a different value.

Test 10

Test of the preprocessor (replay generator). Sequence defined using -c and -v. The repetitions are defined using -repetitions. The can be multiple replays, controlled using -nr_replays. Additional single elements can be added using -pre, -mid and -post (lengths defined by -p, -m and -o respectively).

Test 11

Test infinite replay. This generates a periodic signal.

Test 12

Simple trigger (defaults to bit 0 high, pattern and mask can be overriden using -p and -m), one element sequence. If -trig is specified, the tool will generate the trigger signal using the internal PIO interface for trigger testing. Without this switch, the trigger must be provided through by an external signal.

Test 13

Two-step trigger sequence. The first condition defaults to 01 (can be overriden using -p and -m), the second one to 10 (can be overriden using -r and -n). The correct trigger sequence can be emitted using -trig.

Test 14

Mutlistage triggering test: the triggering sequence is a series of two different patterns and masks, specified by -p and -m (the default is pattern=01 and mask=01) and by -r and -n (the default is pattern=10 and mask=10). The data sequance consists of a single symbol.

Additional parameters:

  • -cycles: number of such two-step trigger units
  • -delay: time delay between each trigger signal in microseconds, for testing with -trig; default is 10000 (10ms)

Test15

Test for retriggering. It alternates between two trigger conditions, one set by -p, -m` and anoteher set by-rand-n`` pair.

Additional parameters:

  • -cycles: number of such two-step trigger units
  • -delay: time delay between each trigger signal in microseconds, for testing with -trig; default is 100000 (100ms)
  • -r: second trigger pattern
  • -n: second trigger mask

Test 19

Pseudorandom generator (xoroshift128+) test. If -c value is larger than 0, a given number of random variates is produced and output on all 32 output lines. If -c value is zero, an infinite stream is generated.

Test 20

Continuous test. Starts up two threads, one filling the decoder queue, one reading back from the readback encoder. The two are compared in real time. If -v is zero, the tests runs indefinitely. If -v is finite, the value counts up from zero to this maximum value (excluded).

Additional parameters:

  • -quiet: do not dump each element
  • -end: randomize values
  • -report N: report statistics at most every N seconds; this shows total run time, the total number of elements (size), and the total duration of the sequence so far (length)

Test 42

Stream out a sequence specified in a text file. The filename is provided using -f argument.

Format:

  • d C V: data element (BITLOAD)
  • t P M: trigger element
  • f: force trigger

ppmstest

Tool for testing multistreamer.

Test 1

The combiner mode is set with -mode. The expected results is computed and compared with what is actually read back.

ppdmatest

Tool for testing streaming sequences from a RAM buffer using direct memory access.

Test 4

Same as test 4 in pptest, but using DMA for the data transfer.

Test 21

Test for a large number of elements. Note that the readback test is not performed here, this test only exercises memory transfers, no correctness testing of the generated bit pattern is implemented.