API

This is where the documentation for the public API functions, and classes lives.

PhyWhisperer-USB Main Interface

class Usb(viewsb=False)

PhyWhisperer-USB Interface

arm()

Arm PhyWhisperer for capture and optionally generating a trigger. Use set_pattern to program the pattern and bitmask which will initiate the capture and/or trigger operation. Use set_trigger to program the trigger parameters. Use set_capture_size and set_capture_delay to program the capture parameters.

armed()

Returns True if the PhyWhisperer is armed.

auto_program()

Erases the firmware of the onboard SAM3U, and reprograms it with default firmware

Attempts to autodetect the COM PORT that the SAM3U shows up as. If this fails, it will be necessary to flash new firmware via program_sam3u

check_fifo_errors(underflow=0, overflow=0)

Check whether an underflow or overflow occured on the capture FIFO.

Parameters:
  • underflow (int, optional) – expected status, 0 or 1
  • overflow (int, optional) – expected status, 0 or 1
close()

Terminates our connection to the PhyWhisperer device.

con(PID=50704, sn=None, program_fpga=True, bitstream_file=None)

Connect to PhyWhisperer-USB. Raises error if multiple detected

Parameters:
  • PID (int, optional) – USB PID of PhyWhisperer, defaults to 0xC610 (NewAE standard).
  • sn (int, option) – Serial Number of PhyWhisperer, required when multiple PhyWhisperers are connected.
  • program_fpga (bool, option) – Specifies whether or not to program the FPGA with the default firmware when we connect. Set to False if using custom bitstream.
erase_sam3u()

Erase the SAM3U Firmware, which forces it into bootloader mode.

fifo_empty()

Returns True if the capture FIFO is empty, False otherwise.

fifo_over_empty_threshold()

Returns True if the capture FIFO has more entries than the empty threshold (128).

get_fpga_buildtime()

Returns date and time when FPGA bitfile was generated.

get_usb_mode()

Returns USB PHY speed. Return values:

  • ‘auto’: the speed has not been determined yet (was the mode set
    to ‘auto’ _before_ the target was connected or powered up?).
  • ‘LS’: low speed
  • ‘FS’: full speed
  • ‘HS: high speed
load_bitstream(bitfile)

Load bitstream onto FPGA

ms_trigger(delay_in_ms)

Convert a mS number to delay or width cycles for set_trigger()

ns_trigger(delay_in_ns)

Convert a nS number to delay or width cycles for set_trigger()

static print_flags(stat_byte)

Print bitfields of USB status flags byte.

print_packets(packets)

Print packets using USBSimplePrintSink from ViewSB. :param packets: list of dictionaries, e.g. obtained from split_packets()

program_sam3u(port, fw_path=None)

Program the SAM3U Firmware assuming device is in bootloader mode.

Parameters:
  • port (str) – Serial port name, such as ‘COM36’ or ‘/dev/ttyACM0’.
  • fw_path (str) – Path to firmware binary to program the sam3u with. If None, use default firmware. Defautls to None.
read_capture_data(entries=0, verbose=False, blocking=False, burst_size=8192, timeout=5)

Read from USB capture memory.

Parameters:
  • blocking (bool, optional) –
    • True: wait for data to be available before reading (slower).
    • False: read immediately, with underflow protection, all of the captured data, until PW tells us we’ve read everything that it captured (‘entries’ is ignored).
  • entries (int, optional) – When blocking=True, number of capture entries to read. If not specified, read all the captured data. Cannot be greater than capture size, as set by set_capture_size().
  • burst_size (int, optional) – When blocking=False, size of burst FIFO reads, defaults to 8192.
  • timeout (int, optional) – timeout in seconds (ignored if 0, defaults to 5)
  • verbose (bool, optional) – Print extra debug info.

Returns: List of captured entries. Each list element is itself a 3-element list, containing the 3 bytes that make up a capture entry. Can be parsed by split_packets() or split_data(). See software/phywhisperer/firmware/defines.v for definition of the FIFO data fields.

read_reg(address, size=1)

Reads a PhyWhisperer register.

Parameters:
  • address – int
  • size – int, number of bytes to read

Returns:

register_sink(event_sink)

ViewSB: Registers a USBEventSink to receive any USB events.

Parameters:event_sink (sniffer.USBEventSink) – The sniffer.USBEventSink object to receive any USB events that occur.
reset_fpga()

Reset FPGA registers to defaults, use liberally to clear incorrect states.

run_capture(size=8188, burst=True, pattern=[0], mask=[0], timeout=5, statistics_callback=None, statistics_period=0.1, halt_callback=<function Usb.<lambda>>)

Runs a capture for ViewSB, including power cycling the device to catch the descriptors.

Runs following internally:

self.reset_fpga()
self.set_power_source("host")
self.set_power_source("off")
time.sleep(0.5)
self.set_usb_mode("auto")
self.set_capture_size(size)
self.arm()
self.set_trigger(enable=False)
self.set_pattern(pattern=pattern, mask=mask)
self.set_power_source("host")
time.sleep(0.25)
set_capture_delay(delay)

Program the capture delay, measured in clock cycles of USB-derived 60 MHz clock. Note that this is a different time base than set_trigger(), which uses a 240 MHz clock!

Parameters:delay (int) – range in [0, 2^18-1] cycles of 60 MHz clock.
set_capture_size(size=8188)

Set how many events to capture (events include data, USB status, and timestamps).

Parameters:size (int, option) – number of events to capture. 0 = unlimited (until overflow). Max = 2^24-1. Since the capture FIFO can hold 8188 events, setting this to > 8188 may result in overflow.
set_pattern(pattern, mask=None)

Set the pattern and its bitmask used for capture and trigger output.

Parameters:
  • pattern (list of ints) – list of between 1 and 64 bytes
  • mask (list, optional) – list of bytes, must have same size as ‘pattern’ if set. Defaults to [0xff]*len(pattern) if not set.
set_power_source(src)

Set power source for target.

Parameters:src (str) –
  • “5V” for power from this computer (via ‘Control’ USB port).
  • ”host” for power from the host of the connection we’re sniffing.
  • ”off” for no power.
set_stat_pattern(pattern, mask=31)

Set a 5-bit pattern and mask for the USB status lines.

Parameters:
  • pattern (int) – 5-bit number
  • mask (int) – non-zero 5-bit number (default: 0x1f)
set_trigger(num_triggers=1, delays=[0], widths=[1], enable=True)
Program the output trigger pulse(s) delay and width. Both are measured in clock cycles of USB-derived
240 MHz clock. Note that this is a different time base than set_capture_delay(), which uses a 60 MHz clock! Up to 8 pulses may be issued. The capture delay is automatically set to match the trigger delay; use set_capture_delay to set it to a different value. Use ns_trigger(), us_trigger(), and ms_trigger() to convert values as needed.
Parameters:
  • num_triggers (int) – number of trigger pulses, from 1 to 8.
  • delay (list of ints) – delay for each trigger pulse; each element in range [0, 2^20-1] cycles (only first element can be zero).
  • width (list of ints) – width for each trigger pulse; each element in range [1, 2^17-1] cycles.
  • enable (bool, optional) – set to ‘False’ to disable trigger generation on hardware pins.

Examples

  1. To set obtain three 2-cycle-wide pulses, each 3 cycles apart, starting immediately after a pattern match: set_trigger(num_triggers=3, delays=[0,3,3], widths=[2,2,2])
  2. To set obtain a 1-cycle wide pulse 10 cycles after a pattern match, followed by a 2-cycle wide pulse 20 cycles later: set_trigger(num_triggers=2, delays=[10,20], widths=[1,2])
set_usb_mode(mode='auto')

Set USB PHY speed.

Parameters:mode (str) –
  • “LS”: manually set the PHY to low speed.
  • ”FS”: manually set the PHY to full speed.
  • ”HS”: manually set the PHY to high speed.
  • ”auto”: Default. PW will attempt to automatically determine the
    speed when the target is connected. Mode must be set to ‘auto’ prior to connecting or powering up the target, otherwise speed cannot be determined correctly. Setting the mode to ‘auto’ actively causes PW to try to determine the speed.
slurp_defines()

Parse Verilog defines file so we can access register and bit definitions by name and avoid ‘magic numbers’.

split_data(rawdata, verbose=False)

Split raw USB capture data into data events and times, stat events and times.

Parameters:rawdata – list of lists, e.g. obtained from read_capture_data()
Returns:
  1. data event times
  2. data bytes corresponding to data event times
  3. USB status update times
  4. USB status bytes corresponding to status update times
Return type:4-tuple of lists
split_packets(rawdata)

Split raw USB capture data into packets.

Parameters:rawdata – list of lists, e.g. obtained from read_capture_data()
Returns:
list
Each list element is one packet and is presented in a dictionary with the following keys:
  • ’timestamp’
  • ’size’ in bytes
  • ’contents’ list of bytes
stat_pattern_matched()

Returns 1 if a stat pattern match occurred (automatically resets to 0 when armed, and when a new match pattern is written). Actual match value is stored in self.stat_pattern_match_value.

trigger_clock_phase_shift(steps=1)

Shifts the trigger clock phase (and by extension the output trigger) in steps of 18.6ps (18.6 ps = 1/960 MHz / 56)

Parameters:steps (int) – Number of steps to shift the phase (positive or negative integer).
us_trigger(delay_in_us)

Convert a uS number to delay or width cycles for set_trigger()

wait_disarmed()

Blocks until armed() returns false.

write_reg(address, data)

Write a PhyWhisperer register.

Parameters:
  • address – int
  • data – bytes