pptest

pptest is a tool for running a range of test protocols. Using the readback interface, it allows you 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

pptest <nr> [args...]

nr indicates the test number.

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
  • -random_final: append a random final data value instead of the default no-modify final terminator
  • -check: perform verification using the readback method
  • -timeout: controls readback wait bounds during -check and -read; if omitted, the default is a conservative 2 s timeout both for the first readback element and for later idle gaps. Use a positive value for idle-gap timeout, or -timeout 0 to disable idle-timeout protection. For compatibility, a negative value is interpreted as a total timeout from the start of the current readback phase, in seconds.
  • -hard-timeout T: total timeout from the start of the current -check or -read phase. Time units such as ms and s are accepted. This is preferred over negative -timeout values for new commands.
  • -dont_wait: return after queueing the sequence, activating or arming the trigger, and completing any requested readback phase. This skips the normal wait and post-run cleanup, so forced or armed trigger state may remain active until reset, reconfiguration, or explicit deactivation.
  • -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, strict raw N,M,C string, or calculated frequency 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, strict raw N,M,C string, or calculated frequency 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 return codes use the shared PulsePins return-code bits. Finite playback runs also have an internal streamer-completion timeout: if the streamer reports neither clean done nor buffer_error within 10 s, the tools report timed out waiting for streamer completion (10 s internal limit) and skip the usual post-completion checks.

If neither -t nor an explicit final V sequence record is provided, the shared playback path appends a no-modify final terminator. The outputs therefore remain at the last value produced by the sequence. Set -random_final or the environment variable PP_RANDOM_FINAL to request a random final value. -t, -random_final/PP_RANDOM_FINAL, and an authored final V record are mutually exclusive final-output selections.

Integer parameter parsing

The numeric parameters can be expressed in decimal (42), hexadecimal (0x2A), octal (052) or binary (0b101010). 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, SystemVerilog-style integer literals are also parsed correctly (e.g. 8'b1111_1111, 32'hFF_FF_FF_FF, 4'hff and similar). Sized literals are evaluated at their declared width, so 4'hff is truncated to 0xf. Unknown/high-impedance digits such as x, z, and ? are accepted by the low-level literal parser but rejected by ordinary unsigned CLI parameter conversions.

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 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 as a raw N,M,C string, as one of the symbolic presets from c++/pll_rules.hh, or as a frequency string such as 66M. Presets and raw triplets must satisfy the same strict Cyclone V fPFD and fVCO limits used by pllcalc. If a value is neither a preset nor raw parameters, the runtime uses the same Cyclone V PLL calculator, prints a warning with the calculated parameters, and then programs the PLL.

pptest test cases

Test 1

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

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 elements that suppress the qout_valid sample qualifier and qout_strobe sampling pulse (three elements, one with both signals suppressed).

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 element with the same value but without the qout_valid sample qualifier or qout_strobe sampling pulse. This can be used in combination with -timeout and -dont_wait to perform a self-test of the initial value setting; remember that -dont_wait intentionally leaves normal post-run cleanup to a later reset, reconfiguration, or explicit deactivation.

Test 8

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

Test 9

Test qout_override functionality: sends out a sequence, checks 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 (10 ms)

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 alternating retrigger stages
  • -delay: time delay between each trigger signal in microseconds, for testing with -trig; default is 100000 (100 ms)
  • -r: second trigger pattern
  • -n: second trigger mask

Test 19

Pseudorandom generator (xoroshiro128+) 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 test 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
  • -rnd: 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 C++ 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 from the text file supplied with -f. The accepted records and numeric syntax are defined by the PulsePins text sequence format.

Invoke it as pptest 42 -f FILE. Here -f selects the file, while an f record inside the file requests forced triggering. Test 42 uses the shared final-output policy: -t, -random_final/PP_RANDOM_FINAL, and a terminal final V record are mutually exclusive; if none is selected, playback appends a no-modify final terminator.

ppmstest

Tool for testing multistreamer.

Test 1

The combiner mode is set with -mode. The expected result 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, and 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. Finite playback appends a terminator after the final repeated sequence so the streamer exits cleanly.

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; finite playback appends a terminator after the final repeated period so the streamer exits cleanly
  • -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