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: controls readback wait bounds during -check and -read; if omitted, the shared workflow uses a conservative 2s timeout both for the first readback element and for later idle gaps. Use a positive value for idle-gap timeout, a negative value for absolute timeout from start, or -timeout 0 to disable timeout protection.
  • -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
  • -core_pll: configure the core/control-side PLL using a preset name or raw N,M,C string
  • -core_pll_charge_pump: set the core PLL charge pump parameter
  • -core_pll_bandwidth: set the core PLL bandwidth parameter
  • -int_pll: configure the internal candidate streamer-clock PLL using a preset name or raw N,M,C string
  • -int_pll_charge_pump: set the internal PLL charge pump parameter
  • -int_pll_bandwidth: set the internal PLL bandwidth parameter

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
  • bit 6: timeout while waiting for transport queueing, readback, DMA setup, or streamer completion

Finite playback runs also have an internal streamer-completion timeout: if the streamer does not report done within 10 s, the tools report timed out waiting for streamer completion (10 s internal limit) and skip the usual post-completion checks.

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 50 MHz signal generated by a crystal oscillator on the DE10-Nano board. The default frequencies are 100 MHz for both core_clk and int_clk. The two host-side PLL wrappers are configured separately:

  • -core_pll / -core_pll_charge_pump / -core_pll_bandwidth for core_clk
  • -int_pll / -int_pll_charge_pump / -int_pll_bandwidth for int_clk

Each PLL profile may be given either as a raw N,M,C string or as one of the symbolic presets from c++/pll_rules.hh. The current preset set is:

  • 100M
  • 80M
  • 75M
  • 60M
  • 50M
  • 40M
  • 30M
  • 25M
  • 20M
  • 10M
  • 5M
  • 1M
  • 100k
  • 10k
  • lj
  • ilj
  • ih
  • il
  • i2h
  • i2l

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. There 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 overridden 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 an external signal.

Test 13

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

Test 14

Multistage 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 sequence 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 another set by -r and -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 21

PMOD DA3 SPI sweep. This generates DAC codes for a PMOD DA3 module using the host-side SPI sequence generator and streams them through PulsePins.

By default the test sweeps from 0.0 V to 2.5 V in 0.01 V increments, uses a 10 MHz SPI clock, and inserts a 10 ms dwell after each DAC update. This produces a sweep of roughly 2.5 s total duration.

Additional parameters:

  • -vmin: starting voltage, default 0.0
  • -vmax: ending voltage, default 2.5
  • -vstep: voltage increment, default 0.01
  • -dwell: dwell time after each DAC update, default 10ms
  • -spi_clock: requested SPI clock frequency in Hz, default 10e6

Test 42

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

Format:

Regular elements:

  • d C V: strobed data element (BITLOAD)
  • dn C V: non-strobed data element (BITLOAD)
  • s C V: BITSET update
  • c C V: BITCLEAR update
  • x C V: BITFLIP update
  • n C V: BITNOT update
  • a C V: BITAND update
  • o C V: BITOR update
  • xr C V: BITXOR update
  • xn C V: BITXNOR update
  • sl C V: BITSLL update
  • sr C V: BITSRL update

Triggers and execution flags:

  • t P M: final trigger element
  • tn P M: non-final trigger element
  • f: request forced triggering instead of arm-and-wait

Preprocessor and control-flow elements:

  • store I OP ...: parse the following regular-element record and tag it for storage in preprocessor slot I
  • r R L: replay a stored subsequence R times with replay length L
  • rt: pause and wait for a retrigger event
  • pr C: emit pseudo-random values for C cycles
  • final V: explicit final terminator with output value V

If a tool or workflow already controls the final output value through -t, do not also include final V in the sequence text. The shared execution path rejects both sources of final-output policy at the same time.

The store wrapper accepts any regular-element token in place of OP: d, dn, s, c, x, n, a, o, xr, xn, sl, or sr.

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.

Test 22

Repeated playback of the long DMA sequence from test 21. The number of repetitions is controlled by -reps; 0 means repeat indefinitely.

Test 25

PMOD DA3 sine generator using DMA. This builds one sampled sine-wave period as a sequence of SPI DAC updates for the PMOD DA3 and then replays that period using DMA, so repeated playback produces a continuous periodic waveform.

Additional parameters:

  • -samples: number of DAC updates per sine period, default 250
  • -reps: number of DMA repetitions, default 0 for infinite playback
  • -dwell: hold time after each DAC update, default 10us
  • -vmin: minimum sine voltage, default 0.0
  • -vmax: maximum sine voltage, default 2.5
  • -spi_clock: requested SPI clock frequency in Hz, default 10e6