PDQ2 Documentation

Contents

PDQ2 Overview

Zenodo DOI URL Continuous integration build and test Documentation Status

A pretty darn quick interpolating arbitrary waveform generator.

Build

Requirements:

Installation of Migen differs depending on what packaging system is used (or if one is used at all). Migen can be installed using pip:

$ pip install -e git://github.com/m-labs/migen.git@legacy#egg=migen

Then to build the gateware:

$ python make.py

The HTML documentation can be built with:

$ pip install -r doc/requirements.txt
$ make -C doc html

Programming

Once the device has been programmed with the gateware and powered up, it can be used to generate waveforms.

See the host.pdq2.Pdq2 class for how to access a stack of PDQ2 board programmatically, how to submit commands, and how prepare, serialize, and program segments, frames, and channels.

An example how host.pdq2.Pdq2 can be used is the command line test interface to the PDQ2 in host.cli.main().

Individual commands are described in the manual in USB Protocol.

The wavesynth format is described with examples in Wavesynth Format.

To communicate with the device, run the testbenches and generate the data, the following additional packages are required:

  • pyserial
  • scipy

Testbenches

$ python3 -m testbench.escape
$ python3 -m testbench.cli

References

Arbitrary waveform generator for quantum information processing with trapped ions; R. Bowler, U. Warring, J. W. Britton, B. C. Sawyer and J. Amini; Rev. Sci. Instrum. 84, 033108 (2013); http://dx.doi.org/10.1063/1.4795552 http://tf.boulder.nist.gov/general/pdf/2668.pdf

Coherent Diabatic Ion Transport and Separation in a Multizone Trap Array; R. Bowler, J. Gaebler, Y. Lin, T. R. Tan, D. Hanneke, J. D. Jost, J. P. Home, D. Leibfried, and D. J. Wineland; Phys. Rev. Lett. 109, 080502; http://dx.doi.org/10.1103/PhysRevLett.109.080502 http://tf.boulder.nist.gov/general/pdf/2624.pdf

Architecture

The PDQ2 is an interpolating, scalable, high speed arbitrary waveform generator.

  • Outputs: 16 bit DACs, +- 10V
  • Sample rate and interpolation speed: 50 MHz or 100 MHz online selectable.
  • Scalability: Three DACs per board. Up to 16 boards stackable to provide 48 channels per USB device. Number of PDQ2 stacks limited by maximum number of USB devices per computer.
  • Memory: 16 KiB or 8 KiB per channel. Compact partitionable data format.
  • Interpolation: DC bias B-spline: constant, linear, quadratic, or cubic. Selectable for each spline knot, each channel.
  • DDS output per channel: 32 bit frequency, 16 bit phase offset, 48 bit frequency chirp. Cubic spline amplitude modulation, aligned with frequency/phase modulator. DDS output added to DC bias spline.
  • Digital outputs: One AUX channel per board, synchronous to spline knots.
  • External control, synchronization: One TTL trigger control input to trigger the execution of marked spline knots.
  • Frame selection: Eight separate frames each describing a waveform. Selectable in hard real-time using three TTL frame select signals.

Spline Interpolation

Many use cases of analog voltages in physics experiments do not continuously need large bandwidth analog signals yet the signals need to be clean and with very small content of spurious frequencies. Either a large bandwidth at very small duty cycle or a very small bandwidth at longer duty cycles is sufficient. It is therefore prudent to generate, represent, transfer, and store the output waveform data in a compressed format.

The method of compression chosen here is a polynomial basis spline (B-spline). The data consists of a sequence of knots. Each knot is described by a duration \(\Delta t\) and spline coefficients \(u_n\) up to order \(k\). If the knot is evaluated starting at time \(t_0\), the output \(u(t)\) for \(t \in [t_0, t_0 + \Delta t]\) is:

\[u(t) = \sum_{n=0}^k \frac{u_n}{n!} (t - t_0)^n = u_0 + u_1 (t - t_0) + \frac{u_2}{2} (t - t_0)^2 + \dots\]

A sequence of such knots describes a spline waveform. Such a polynomial segment can be evaluated and evolved very efficiently using only iterative accumulation (recursive addition) without the need for any multiplications and powers that would require scarce resources on programmable logic. From one discrete time \(i\) to the next \(i + 1\) each accumulators \(v_{n, i}\) is incremented by the value of the next higher order accumulator:

\[v_{n, i + 1} = v_{n, i} + v_{n + 1, i}\]

For a cubic spline the mapping between the accumulators’ initial values \(v_{n, 0}\) and the polynomial derivatives or spline coefficients \(u_n\) can be done off-line and ahead of time. The mapping includes corrections due to the finite time step size \(\tau\).

\[\begin{split}t_i &= t_0 + i\tau\\ v_{n, i} &= u_n(t_i)\\ v_{0, 0} &= u_0\\ v_{1, 0} &= u_1\tau + \frac{u_2 \tau^2}{2} + \frac{u_3 \tau^3}{6}\\ v_{2, 0} &= u_2\tau^2 + u_3\tau^3\\ v_{3, 0} &= u_3\tau^3\end{split}\]

The data for each knot is then described by the integer duration \(T = \Delta t/\tau\) and the initial values \(v_{n, 0}\).

This representation allows both very fast transient high bandwidth waveforms and slow but smooth large duty cycle waveforms to be described efficiently.

CORDIC

Trigonometric functions can also be represented efficiently on programmable logic using only additions, comparisons and bit shifts. See gateware.cordic for a full documentation of the features, capabilities, and constraints.

Features

Each PDQ2 card contains one FPGA that feeds three DAC channels. Multiple PDQ2 cards can be combined into a stack. There is one data connection and one set of digital control lines connected to a stack, common to all cards, all FPGAs, and all channels in that stack.

Each channel of the PDQ2 can generate a waveform \(w(t)\) that is the sum of a cubic spline \(a(t)\) and a sinusoid modulated in amplitude by a cubic spline \(b(t)\) and in phase/frequency by a quadratic spline \(c(t)\):

\[w(t) = a(t) + b(t) \cos(c(t))\]

The data is sampled at 50 MHz or 100 MHz and 16 bit resolution. The higher order spline coefficients (including the frequency offset \(c_1\)) receive successively wider data words due to their higher dynamic range.

The duration of a spline knot is of the form:

\[\Delta t = 2^E T \tau_0 = T \tau\]

Here, \(T\) is a 16 bit unsigned integer and \(E\) is a 4 bit unsigned integer. The spline time step is accordingly scaled to \(\tau = 2^E \tau_0\) where \(\tau_0\) = 20 ns or 10 ns to accommodate the corresponding change in dynamic range of the coefficients. The only exception to the scaling is the frequency offset \(c_1\) which is always unscaled. At 100 MHz sampling rate, this allows for knot durations anywhere between up to 655 µs at 10 ns resolution and up to 43 s at 655 µs resolution. The encoding of the spline coefficients and associated metadata is described in Line Format.

The execution of a knot can be delayed until a trigger signal is received. The trigger signal is common to all channels of all cards in a stack.

Each channel can play waveforms from any of eight frames, selected by the three frame signals that are common to all channels and all boards of a stack. All frames of a channel share the same memory. The memory layout is described in Memory Layout. Transitions between frames happen at the end of frames. Frames can be aborted at the end of a spline knot by disarming the stack.

Each channel also has one digital output aux that can be set or cleared at each knot. The logical OR of each set of three channels is mapped to the F5 output of each PDQ2 card.

The waveform data is written into the channel memories over a full speed USB link. Each channel memory can be accessed individually. Data or status messages can not be read back.

The USB channel also carries in-band control commands to switch the clock speed between 50 MHz and 100 MHz, reset the device, arm or disarm the device, enable or disable soft triggering, and enable or disable the starting of new frames. The USB protocol is described in USB Protocol.

The host side software receives waveform data in an easy-to generate, portable, and human readable format that is then encoded and written to the channels attached to a device. This wavesynth format is described in Wavesynth Format.

Reference Manual

USB Protocol

The data connection to a PDQ2 stack is a single, full speed USB, parallel FIFO with byte granularity. On the host this appears as a “character device” or “serial port”. Windows users may need to install the FTDI device drivers available at the FTDI web site and enable “Virtual COM port (VCP) emulation” so the device becomes available as a COM port. Under Linux the drivers are usually already shipped with the distribution and immediately available. Device permissions have to be handled as usual through group membership and udev rules. The USB bus topology or the device serial number can be used to uniquely identify and access a given PDQ2 stack. The serial number is stored in the FTDI FT245R USB FIFO chip and can be set as described in the old PDQ documentation. The byte order is little-endian (least significant byte first).

Control Messages

The communication to the device is one-way, write-only. Synchronization has to be achieved by properly sequencing the setting of digital lines with control commands, control commands, and memory writes on the USB bus.

Control commands apply to all channels on all boards in a stack.

Control commands on the USB bus are single bytes prefixed by the 0xa5 escape sequence (0xa5 0xYY). If the byte 0xa5 is to be part of the (non-control) data stream it has to be escaped by 0xa5 itself.

Name Command Description
RESET 0x00 Reset the FPGA registers. Does not reset memories. Does not reload the bitstream. Does not reset the USB interface.
TRIGGER 0x02 Soft trigger. Logical OR with the external trigger control line to form the trigger signal to the spline.
ARM 0x04 Enable triggering. Disarming also aborts parsing of a frame and forces the parser to the frame jump table. A currently active line will finish execution.
DCM 0x06 Set the clock speed. Enabling chooses the Digital Clock Manager which doubles the clock and thus operates all FPGA logic and the DACs at 100 MHz. Disabling chooses a 50 MHz sampling and logic clock. The PDQ2 logic is inherently agnostic to the value of the sample clock. Scaling of coefficients and duration values must be performed on the host.
START 0x08 Enable starting new frames (enables leaving the frame jump table).

The LSB of the command byte then determines whether the command is a “disable” or an “enable” command.

Examples:

  • 0xa5 0x02 is TRIGGER enable,
  • 0xa5 0x03 is TRIGGER disable,
  • 0xa5 0xa5 is a single 0xa5 in the non-control data stream.
Memory writes

The non-control data stream is interpreted as 16 bit values (two bytes little-endian). The stream consists purely of writes of data to memory locations on individual channels. One channel/one memory can be written to at any given time. A memory write has the format (each row is one word of 16 bits):

channel
start_addr
end_addr
data[0]
data[1]
...
data[length-1]

The channel number is a function of the board number (selected on the dial switch on each PDQ2 board) and the DAC number (0, 1, 2): channel = (board_addr << 4) | dac_number. The length of the data written is length = end_addr - start_addr + 1.

Warning

  • No length check or address verification is performed.
  • Overflowing writes wrap.
  • Non-existent or invalid combinations of board address and/or channel number are silently ignored or wrapped.
  • If the write format is not adhered to, synchronization is lost and behavior is undefined.
  • A valid RESET sequence will restore synchronization. To reliably reset under all circumstances, ensure that the reset sequence 0xa5 0x00 is not preceded by an (un-escaped) escape character.

Control commands can be inserted at any point in the non-control data stream.

Examples:

  • 0x0072 0x0001 0x0003 0x0005 0x0007 0x0008 writes the three words 0x0005 0x0007 0x0008 to the memory address 0x0001 of DAC channel 2 (the last of three) on board 7 (counting from 0).
  • 0xa5 0x06 0x0000 0x00a5a5 0x00a5a5 0xa5a5a5a5 0xa5 0x02 0xa5 0x04 0xa5 0x08 enables the clock doubler (100 MHz) on all channels, then writes the single word 0xa5a5 to address 0x00a5 (note the escaping and the endianess) of channel 0 of board 0, enables soft trigger on all channels, arms all channels, and finally starts all channels.

Memory Layout

The three DAC channels on each board have 8192, 8192, 4096 words (16 bit each) capacity (16 KiB, 16 KiB, 8 KiB). Overflowing writes wrap around. The memory is interpreted as consisting of a table of frame start addresses with 8 entries, followed by data. The layout allows partitioning the waveform memory arbitrarily among the frames of a channel. The data for frame i is expected to start at memory[memory[i]].

The memory is interpreted as follows (each row is one word of 16 bits):

Address Data
0 frame[0].addr
1 frame[1].addr
... ...
frame[0].addr frame[0].data[0]
frame[0].addr + 1 frame[0].data[1]
... ...
frame[0].addr + N frame[0].data[N]
... ...
frame[1].addr frame[1].data[0]
frame[1].addr + 1 frame[1].data[1]
... ...
frame[1].addr + L frame[1].data[L]
... ...

Warning

  • The memory layout is not enforced or verified.
  • If violated, the behavior is undefined.
  • Jumping to undefined addresses leads to undefined behavior.
  • Jumping to frame numbers that have invalid addresses written into their address location leads to undefined behavior.

Note

This layout can be exploited to rapidly swap frame data between multiple different waveforms (without having to re-upload any data) by only updating the corresponding frame address(es).

Line Format

The frame data consists of a concatenation of lines. Each line has the following format (a row being a word of 16 bits):

header
duration
data[0]
...
data[length - 2]

Warning

  • If reading and parsing the next line (including potentially jumping into and out of the frame address table) takes longer than the duration of the current line, the pipeline is stalled and the evolution of the splines is paused until the next line becomes available.
  • duration must be positive.
Spline Data

The interpretation of the sequence of up to 14 data words contained in each line depends on the typ of spline interpolator targeted by header.typ.

The data is always zero-padded to 14 words.

The assignment of the spline coefficients to the data words is as follows:

typ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14
0 a0 a1 a2 a3  
1 b0 b1 b2 b3 c0 c1 c2

If the length of a line is shorter than 14 words, the remaining coefficients (or parts of coefficients) are set to zero.

The coefficients can be interpreted as two’s complement signed integers or as unsigned integers depending depending on preference and convenience. The word order is the same as the byte order of the USB protocol: little-endian (least significant word first).

The scaling of the coefficients is as follows:

  • a0 is in units of full_scale/(1 << 16).
  • a1 is in units of full_scale/(1 << (32 + shift))/clock_period.
  • a2 is in units of full_scale/(1 << (48 + 2*shift))/clock_period**2.
  • a3 is in units of full_scale/(1 << (48 + 3*shift))/clock_period**3.
  • b0 is in units of full_scale*cordic_gain/(1 << 16).
  • b1 is in units of full_scale*cordic_gain/(1 << (32 + shift))/clock_period.
  • b2 is in units of full_scale*cordic_gain/(1 << (48 + 2*shift))/clock_period**2.
  • b3 is in units of full_scale*cordic_gain/(1 << (48 + 3*shift))/clock_period**3.
  • c0 is in units of 2*pi/(1 << 16).
  • c1 is in units of 2*pi/(1 << 32)/clock_period.
  • c2 is in units of 2*pi/(1 << (48 + shift))/clock_period**2.
  • full_scale is 20 V.
  • The step size full_scale/(1 << 16) is 305 µV.
  • clock_period is 10 ns or 20 ns depending on the DCM setting.
  • shift is header.shift.
  • 2*pi is one full phase turn.
  • cordic_gain is 1.64676 (see gateware.cordic).

Note

With the default analog frontend, this means: a0 == 0 corresponds to close to 0 V output, a0 == 0x7fff corresponds to close to 10V output, and a0 == 0x8000 corresponds to close to -10 V output.

Note

There is no correction for DAC or amplifier offsets, reference errors, or DAC scale errors.

Note

Latencies of the CORDIC path, the DC spline path, and the AUX path are not matched. The CORDIC path (both the amplitude and the phase spline) has about 19 clock cycles more latency than the DC spline path. This can be exploited to align the DC spline knot start and the CORDIC output change. DC spline path and AUX path differe by the DAC latency.

Warning

  • There is no clipping or saturation.
  • When accumulators overflow, they wrap.
  • That’s desired for the phase accumulator but will lead to jumps in the DC spline and CORDIC amplitude.
  • When the CORDIC amplitude b0 reaches an absolute value of (1 << 15)/cordic_gain, the CORDIC output becomes undefined.
  • When the sum of the CORDIC output amplitude and the DC spline overflows, the output wraps.

Note

All splines (except the DDS phase) continue evolving even when a line of a different typ is being executed. All splines (except the DDS phase) stop evolving when the current line has reached its duration and no next line has been read yet or the machinery is waiting for TRIGGER, ARM, or START.

Note

The phase input to the CORDIC the sum of the phase offset c0 and the accumulated phase due to c1 and c2. The phase accumulator always accumulates at full clock speed, not at the clock speed reduced by shift != 0. It also never stops or pauses. This is in intentional contrast to the amplitude, DC spline, and frequency evolution that takes place at the reduced clock speed if shift != 0 and may be paused.

Wavesynth Format

To describe a complete PDQ2 stack program, the Wavesynth format has been defined.

  • program is a sequence of frames.

  • frame is a concatentation of segments. Its index in the program determines its frame number.

  • segment is a sequence is lines. The first line should be triggered to establish synchronization with external hardware.

  • line is a dictionary containing the following fields:

    • duration: Integer duration in spline evolution steps, in units of dac_divider*clock_period.
    • dac_divider == 2**header.shift
    • trigger: Whether to wait for trigger assertion to execute this line.
    • channel_data: Sequence of spline, one for each channel.

  • spline is a dictionary containing as key a single spline to be set: either bias or dds and as its value a dictionary of spline_data. spline has exactly one key.

  • spline_data is a dictionary that may contain the following keys:

    • amplitude: The uncompensated polynomial spline amplitude coefficients. Units are Volts and increasing powers of 1/(dac_divider*clock_period) respectively.
    • phase: Phase/Frequency spline coefficients. Only valid if the key for spline_data was dds. Units are [turns, turns/clock_period, turns/clock_period**2/dac_divider].
    • clear: header.clear.
    • silence: header.silence.

Note

  • amplitude and phase spline coefficients can be truncated. Lower order splines are then executed.
Example Wavesynth Program

The following example wavesynth program configures a PDQ2 stack with a single board, three DAC channels.

It configures a single frame (the first and only) consisting of a single triggered segment with three lines. The total frame duration is 80 cycles. The following waveforms are emitted on the three channels:

  • A quadratic smooth pulse in bias amplitude from 0 to 0.8 V and back to zero.
  • A cubic smooth step from 1 V to 0.5 V, followed by 40 cycles of constant 0.5 V and then another cubic step down to 0 V.
  • A sequence of amplitude shaped pulses with varying phase, frequency, and chirp.
wavesynth_program = [
    [
        {
            "trigger": True,
            "duration": 20,
            "channel_data": [
                {"bias": {"amplitude": [0, 0, 2e-3]}},
                {"bias": {"amplitude": [1, 0, -7.5e-3, 7.5e-4]}},
                {"dds": {
                    "amplitude": [0, 0, 4e-3, 0],
                    "phase": [.25, .025],
                }},
            ],
        },
        {
            "duration": 40,
            "channel_data": [
                {"bias": {"amplitude": [.4, .04, -2e-3]}},
                {"bias": {
                    "amplitude": [.5],
                    "silence": True,
                }},
                {"dds": {
                    "amplitude": [.8, .08, -4e-3, 0],
                    "phase": [.25, .025, .02/40],
                    "clear": True,
                }},
            ],
        },
        {
            "duration": 20,
            "channel_data": [
                {"bias": {"amplitude": [.4, -.04, 2e-3]}},
                {"bias": {"amplitude": [.5, 0, -7.5e-3, 7.5e-4]}},
                {"dds": {
                    "amplitude": [.8, -.08, 4e-3, 0],
                    "phase": [-.25],
                }},
            ],
        },
    ]
]

The following figure compares the output of the three channels as simulated by the artiq.wavesynth.compute_samples.Synthesizer test tool with the output from a full simulation of the PDQ2 gateware including the host side code, control commands, memory writing, memory parsing, triggering and spline evaluation.

_images/pdq2_wavesynth_test.png

PDQ2 and Synthesizer outputs for wavesynth test program.

The abcissa is the time in clock cycles, the ordinate is the output voltage of the channel.

The plot consists of six curves, three colored ones from the gateware simulation of the board and three black ones from the Synthesizer verification tool. The colored curves should be masked by the black curves up to integer rounding errors.

The source of this unittest is part of ARTIQ at artiq.test.test_pdq2.TestPdq2.test_run_plot.

Code Documentation

host.cli module

PDQ2 frontend.
Evaluates times and voltages, interpolates and uploads them.

usage: pdq2 [-h] [-s SERIAL] [-c CHANNEL] [-f FRAME] [-t TIMES] [-v VOLTAGES]
            [-o ORDER] [-u DUMP] [-r] [-m] [-n] [-e] [-d]
Named Arguments
-s, –serial

device url [“hwgrep://”]

Default: “hwgrep://”

-c, –channel

channel: 3*board_num+dac_num [0]

Default: 0

-f, –frame

frame [0]

Default: 0

-t, –times

sample times (s) [“np.arange(5)*1e-6”]

Default: “np.arange(5)*1e-6”

-v, –voltages

sample voltages (V) [“(1-np.cos(t/t[-1]*2*np.pi))/2”]

Default: “(1-np.cos(t/t[-1]*2*np.pi))/2”

-o, –order

interpolation (0: const, 1: lin, 2: quad, 3: cubic) [3]

Default: 3

-u, –dump dump to file [None]
-r, –reset

do reset before

Default: False

-m, –multiplier
 

100MHz clock [False]

Default: False

-n, –disarm

disarm group [False]

Default: False

-e, –free

software trigger [False]

Default: False

-d, –debug

debug communications

Default: False
host.cli.main(dev=None)[source]

Test a PDQ2 stack.

Parse command line arguments, configures PDQ2 stack, interpolate the time/voltage data using a spline, generate a wavesynth program from the data and upload it to the specified channel. Then perform the desired arming/triggering/starting functions on the stack.

host.pdq2 module

class host.pdq2.Channel[source]

PDQ2 Channel.

num_frames

int – Number of frames supported.

max_data

int – Number of 16 bit data words per channel.

segments

list[Segment] – Segments added to this channel.

clear()[source]

Remove all segments.

new_segment()[source]

Create and attach a new Segment to this channel.

Returns:Segment
place()[source]

Place segments contiguously.

Assign segment start addresses and determine length of data.

Returns:Amount of memory in use on this channel.
Return type:addr (int)
serialize(entry=None)[source]

Serialize the memory for this channel.

Places the segments contiguously in memory after the frame table. Allocates and assigns segment and frame table addresses. Serializes segment data and prepends frame address table.

Parameters:entry (list[Segment]) – See table().
Returns:Channel memory data.
Return type:data (bytes)
table(entry=None)[source]

Generate the frame address table.

Unused frame indices are assigned the zero address in the frame address table. This will cause the memory parser to remain in the frame address table until another frame is selected.

The frame entry segments can be any segments in the channel.

Parameters:entry (list[Segment]) – List of initial segments for each frame. If not specified, the first num_frames segments are used as frame entry points.
Returns:Frame address table.
Return type:table (bytes)
class host.pdq2.Pdq2(url=None, dev=None, num_boards=3)[source]

PDQ stack.

Parameters:
  • url (str) – Pyserial device URL. Can be hwgrep:// style (search for serial number, bus topology, USB VID:PID combination), COM15 for a Windows COM port number, /dev/ttyUSB0 for a Linux serial port.
  • dev (file-like) – File handle to use as device. If passed, url is ignored.
  • num_boards (int) – Number of boards in this stack.
num_dacs

int – Number of DAC outputs per board.

num_channels

int – Number of channels in this stack.

num_boards

int – Number of boards in this stack.

channels

list[Channel] – List of Channel in this stack.

close()[source]

Close the USB device handle.

cmd(cmd, enable)[source]

Execute a command.

Parameters:
  • cmd (str) – Command to execute. One of (RESET, TRIGGER, ARM, DCM, START).
  • enable (bool) – Enable (True) or disable (False) the feature.
program(program, channels=None)[source]

Serialize a wavesynth program and write it to the channels in the stack.

The Channel targeted are cleared and each frame in the wavesynth program is appended to a fresh set of Segment of the channels. All segments are allocated, the frame address tale is generated, the channels are serialized and their memories are written.

Short single-cycle lines are prepended and appended to each frame to allow proper write interlocking and to assure that the memory reader can be reliably parked in the frame address table. The first line of each frame is mandatorily triggered.

Parameters:
  • program (list) – Wavesynth program to serialize.
  • channels (list[int]) – Channel indices to use. If unspecified, all channels are used.
program_segments(segments, data)[source]

Append the wavesynth lines to the given segments.

Parameters:
  • segments (list[Segment]) – List of Segment to append the lines to.
  • data (list) – List of wavesynth lines.
write(data)[source]

Write data to the PDQ2 board.

Parameters:data (bytes) – Data to write.
write_mem(channel, data, start_addr=0)[source]

Write to channel memory.

Parameters:
  • channel (int) – Channel index to write to. Assumes every board in the stack has num_dacs DAC outputs.
  • data (bytes) – Data to write to memory.
  • start_addr (int) – Start address to write data to.
class host.pdq2.Segment[source]

Serialize the lines for a single Segment.

max_time

int – Maximum duration of a line.

max_val

int – Maximum absolute value (scale) of the DAC output.

max_out

float – Output voltage at max_val. In Volt.

out_scale

float – Steps per Volt.

cordic_gain

float – CORDIC amplitude gain.

addr

int – Address assigned to this segment.

data

bytes – Serialized segment data.

bias(amplitude=[], **kwargs)[source]

Append a bias line to this segment.

Parameters:
  • amplitude (list[float]) – Amplitude coefficients in in Volts and increasing powers of 1/(2**shift*clock_period). Discrete time compensation will be applied.
  • **kwargs – Passed to line().
dds(amplitude=[], phase=[], **kwargs)[source]

Append a DDS line to this segment.

Parameters:
  • amplitude (list[float]) – Amplitude coefficients in in Volts and increasing powers of 1/(2**shift*clock_period). Discrete time compensation and CORDIC gain compensation will be applied by this method.
  • phase (list[float]) – Phase/frequency/chirp coefficients. phase[0] in turns, phase[1] in turns/clock_period, phase[2] in turns/(clock_period**2*2**shift).
  • **kwargs – Passed to line().
line(typ, duration, data, trigger=False, silence=False, aux=False, shift=0, jump=False, clear=False, wait=False)[source]

Append a line to this segment.

Parameters:
  • typ (int) – Output module to target with this line.
  • duration (int) – Duration of the line in units of clock_period*2**shift.
  • data (bytes) – Opaque data for the output module.
  • trigger (bool) – Wait for trigger assertion before executing this line.
  • silence (bool) – Disable DAC clocks for the duration of this line.
  • aux (bool) – Assert the AUX (F5 TTL) output during this line.
  • shift (int) – Duration and spline evolution exponent.
  • jump (bool) – Return to the frame address table after this line.
  • clear (bool) – Clear the DDS phase accumulator when starting to exectute this line.
  • wait (bool) – Wait for trigger assertion before executing the next line.
static pack(widths, values)[source]

Pack spline data.

Parameters:
  • widths (list[int]) – Widths of values in multiples of 16 bits.
  • values (list[int]) – Values to pack.
Returns:

Packed data.
Return type:

data (bytes)
host.pdq2.discrete_compensate(c)[source]

Compensate spline coefficients for discrete accumulators.

Given continuous-time b-spline coefficients, this function compensates for the effect of discrete time steps in the target devices.

The compensation is performed in-place.

gateware.pdq2 module

class gateware.pdq2.CRG(platform)[source]

PDQ2 Clock and Reset generator.

Parameters:platform (Platform) – PDQ2 Platform.
rst

Signal – Reset input.

clk_p

Signal – Positive clock output.

clk_n

Signal – Negative clock output.

dcm_sel

Signal – Select doubled clock. Input.

dcm_locked

Signal – DCM locked. Output.

cd_sys

ClockDomain – System clock domain driven.

class gateware.pdq2.Pdq2(platform)[source]

PDQ2 Top module.

Wires up USB FIFO reader gateware.ft245r.Ft345r_rx, clock and reset generator CRG, and the DAC output signals. Delegates the wiring of the remaining modules to Pdq2Base.

pads.go2_out is assigned the DCM locked signal.

Parameters:platform (Platform) – PDQ2 platform.
class gateware.pdq2.Pdq2Base(ctrl_pads, mem_depths=(8192, 8192, 4096))[source]

PDQ2 Base configuration.

Used both in functional simulation and final gateware.

Holds the three gateware.dac.Dac and the communication handler gateware.comm.Comm.

Parameters:
  • ctrl_pads (Record) – Control pads for gateware.comm.Comm.
  • mem_depth (list[int]) – Memory depths for the DAC channels.
dacs

list – List of gateware.dac.Dac.

comm

Module – gateware.comm.Comm.

gateware.comm module

class gateware.comm.Comm(ctrl_pads, dacs)[source]

USB Protocol handler.

Parameters:
  • ctrl_pads (Record) – Control signal pads.
  • dacs (list) – List of gateware.dac.Dac.
sink

Sink[bus_layout] – 8 bit data sink containing both the control sequencences and the data stream.

class gateware.comm.Ctrl(pads, dacs)[source]

Control command handler.

Controls the input and output TTL signals, handled the excaped control commands.

Parameters:
  • pads (Record) – Pads containing the TTL input and output control signals
  • dacs (list) – List of gateware.dac.Dac.
reset

Signal – Reset output from ResetGen. Active high.

dcm_sel

Signal – DCM slock select. Enable clock doubler. Output.

sink

Sink[bus_layout] – 8 bit control data sink. Input.

class gateware.comm.MemWriter(board, dacs)[source]

Handles the memory write protocol and writes data to the channel memories.

Parameters:
  • board (Value) – Address of this board.
  • dacs (list) – List of gateware.dac.Dac.
sink

Sink[mem_layout] – 16 bit data sink.

class gateware.comm.ResetGen(n=128)[source]

Reset generator.

Asserts reset for a given number of cycles when triggered.

Parameters:n (int) – number of cycles.
trigger

Signal – Trigger input.

reset

Signal – Reset output. Active high.

gateware.dac module

class gateware.dac.Dac(fifo=0, **kwargs)[source]

Output module.

Holds the Memory, the Parser, the Sequencer, and its two output line executors.

Parameters:
parser

The memory Parser.

out

The Sequencer and output executor. Connect its data to the DAC.

class gateware.dac.Dds(line, stb, inc)[source]

DDS spline interpolator.

The line data is interpreted as:

  • 16 bit amplitude offset
  • 32 bit amplitude first order derivative
  • 48 bit amplitude second order derivative
  • 48 bit amplitude third order derivative
  • 16 bit phase offset
  • 32 bit frequency word
  • 48 bit chirp
Parameters:
  • line (Record[line_layout]) – Next line to be executed. Input.
  • stb (Signal) – Load data from next line. Input.
  • inc (Signal) – Evolve clock enable. Input.
data

Signal[16] – Output data from this spline.

class gateware.dac.Parser(mem_depth=4096)[source]

Memory parser.

Reads memory controlled by TTL signals, builds lines, and submits them to its output.

Parameters:mem_depth (int) – Memory depth in 16 bit entries.
mem

Memory – Memory to read from.

source

Source[line_layout] – Source of lines read from memory. Output.

arm

Signal – Allow triggers. If disarmed, the next line will not be read. Instead, the Parser will return to the frame address table. Input.

start

Signal – Allow leaving the frame address table. Input.

frame

Signal[3] – Values of the frame selection lines. Input.

class gateware.dac.Sequencer[source]

Line sequencer.

Controls execution of a line. Owns the executors that evolve the line data and sums them together to generate the output. Also manages the line duration counter, the 2**shift counter and the acknowledgment of new line data when the previous is finished.

sink

Sink[line_layout] – Line data sink.

trigger

Signal – Trigger input.

arm

Signal – Arm input.

aux

Signal – TTL AUX (F5) output.

silence

Signal – Silence DAC clocks output.

data

Signal[16] – Output value to be send to the DAC.

class gateware.dac.Volt(line, stb, inc)[source]

DC bias spline interpolator.

The line data is interpreted as a concatenation of:

  • 16 bit amplitude offset
  • 32 bit amplitude first order derivative
  • 48 bit amplitude second order derivative
  • 48 bit amplitude third order derivative
Parameters:
  • line (Record[line_layout]) – Next line to be executed. Input.
  • stb (Signal) – Load data from next line. Input.
  • inc (Signal) – Evolve clock enable. Input.
data

Signal[16] – Output data from this spline.

gateware.platform module

class gateware.platform.Platform[source]

PDQ2 Platform.

  • Xilinx Spartan 3A 500E in a PQ208 package.
  • 50 MHz single ended input clock.
  • Single FT245R USB parallel FIFO.
  • Three 16 bit LVDS DACs.
  • Several TTL control lines.

gateware.cordic module

class gateware.cordic.Cordic(**kwargs)[source]

Four-quadrant CORDIC

Same as TwoQuadrantCordic but with support and convergence for abs(zi) > pi/2 in circular rotate mode or `xi < 0 in circular vector mode.

class gateware.cordic.TwoQuadrantCordic(width=16, widthz=None, stages=None, guard=0, eval_mode='iterative', cordic_mode='rotate', func_mode='circular')[source]

Coordinate rotation digital computer

Trigonometric, and arithmetic functions implemented using additions/subtractions and shifts.

http://eprints.soton.ac.uk/267873/1/tcas1_cordic_review.pdf

http://www.andraka.com/files/crdcsrvy.pdf

http://zatto.free.fr/manual/Volder_CORDIC.pdf

The way the CORDIC is executed is controlled by eval_mode. If “iterative” the stages are iteratively evaluated, one per clock cycle. This mode uses the least amount of registers, but has the lowest throughput and highest latency. If “pipelined” all stages are executed in every clock cycle but separated by registers. This mode has full throughput but uses many registers and has large latency. If “combinatorial”, there are no registers, throughput is maximal and latency is zero. “pipelined” and “combinatorial” use the same number of shifters and adders.

The type of trigonometric/arithmetic function is determined by cordic_mode and func_mode. \(g\) is the gain of the CORDIC.

  • rotate-circular: rotate the vector (xi, yi) by an angle zi. Used to calculate trigonometric functions, sin(), cos(), tan() = sin()/cos(), or to perform polar-to-cartesian coordinate transformation:

    \[ \begin{align}\begin{aligned}x_o = g \cos(z_i) x_i - g \sin(z_i) y_i\\y_o = g \sin(z_i) x_i + g \cos(z_i) y_i\end{aligned}\end{align} \]

  • vector-circular: determine length and angle of the vector (xi, yi). Used to calculate arctan(), sqrt() or to perform cartesian-to-polar transformation:

    \[ \begin{align}\begin{aligned}x_o = g\sqrt{x_i^2 + y_i^2}\\z_o = z_i + \tan^{-1}(y_i/x_i)\end{aligned}\end{align} \]

  • rotate-hyperbolic: hyperbolic functions of zi. Used to calculate hyperbolic functions, sinh, cosh, tanh = cosh/sinh, exp = cosh + sinh:

    \[ \begin{align}\begin{aligned}x_o = g \cosh(z_i) x_i + g \sinh(z_i) y_i\\y_o = g \sinh(z_i) x_i + g \cosh(z_i) z_i\end{aligned}\end{align} \]

  • vector-hyperbolic: natural logarithm ln(), arctanh(), and sqrt(). Use x_i = a + b and y_i = a - b to obtain 2* sqrt(a*b) and ln(a/b)/2:

    \[ \begin{align}\begin{aligned}x_o = g\sqrt{x_i^2 - y_i^2}\\z_o = z_i + \tanh^{-1}(y_i/x_i)\end{aligned}\end{align} \]

  • rotate-linear: multiply and accumulate (not a very good multiplier implementation):

    \[y_o = g(y_i + x_i z_i)\]

  • vector-linear: divide and accumulate:

    \[z_o = g(z_i + y_i/x_i)\]
Parameters:
  • width (int) – Bit width of the input and output signals. Defaults to 16. Input and output signals are signed.
  • widthz (int) – Bit with of zi and zo. Defaults to the width.
  • stages (int or None) – Number of CORDIC incremental rotation stages. Defaults to width + min(1, guard).
  • guard (int or None) – Add guard bits to the intermediate signals. If None, defaults to guard = log2(width) which guarantees accuracy to width bits.
  • eval_mode (str, {"iterative", "pipelined", "combinatorial"}) –
  • cordic_mode (str, {"rotate", "vector"}) –
  • func_mode (str, {"circular", "linear", "hyperbolic"}) – Evaluation and arithmetic mode. See above.
xi, yi, zi

Signal(width), in – Input values, signed.

xo, yo, zo

Signal(width), out – Output values, signed.

new_out

Signal(1), out – Asserted if output values are freshly updated in the current cycle.

new_in

Signal(1), out – Asserted if new input values are being read in the next cycle.

zmax

float – zi and zo normalization factor. Floating point zmax corresponds to 1<<(widthz - 1). x and y are scaled such that floating point 1 corresponds to 1<<(width - 1).

gain

float – Cumulative, intrinsic gain and scaling factor. In circular mode sqrt(xi**2 + yi**2) should be no larger than 2**(width - 1)/gain to prevent overflow. Additionally, in hyperbolic and linear mode, the operation itself can cause overflow.

interval

int – Output interval in clock cycles. Inverse throughput.

latency

int – Input-to-output latency. The result corresponding to the inputs appears at the outputs latency cycles later.

Notes

Each stage i in the CORDIC performs the following operation:

\[ \begin{align}\begin{aligned}x_{i+1} = x_i - m d_i y_i r^{-s_{m,i}},\\y_{i+1} = y_i + d_i x_i r^{-s_{m,i}},\\z_{i+1} = z_i - d_i a_{m,i},\end{aligned}\end{align} \]

where:

  • \(d_i\): clockwise or counterclockwise, determined by sign(z_i) in rotate mode or sign(-y_i) in vector mode.
  • \(r\): radix of the number system (2)
  • \(m\): 1: circular, 0: linear, -1: hyperbolic
  • \(s_{m,i}\): non decreasing integer shift sequence
  • \(a_{m,i}\): elemetary rotation angle: \(a_{m,i} = \tan^{-1}(\sqrt{m} s_{m,i})/\sqrt{m}\).

gateware.escape module

class gateware.escape.Unescaper(layout, escape=165)[source]

Split a data stream into an escaped low bandwidth command stream and an unescaped high bandwidth data stream.

Items in the input stream that are escaped by being prefixed with the escape character, will be directed to the source_b output Source.

Items that are not escaped, and the escaped escape character itself are directed at the source_a output Source.

Parameters:
  • layout (layout) – Stream layout to split.
  • escape (int) – Escape character.
sink

Sink[layout] – Input stream.

source_a

Source[layout] – High bandwidth unescaped data Source.

source_b

Source[layout] – Low bandwidth command Source.

gateware.ft245r module

class gateware.ft245r.Ft245r_rx(pads, clk=10.0)[source]

FTDI FT345R synchronous reader.

Parameters:
  • pads (Record[ft345r_layout]) – Pads to the FT245R.
  • clk (float) – Clock period in ns.
source

Source[bus_layout] – 8 bit data source. Output.

busy

Signal – Data available but not acknowledged by sink. Output.

Indices and tables