API

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

Most properties are accessible via two APIs: a legacy API with function calls, and the newer property-based API.

PhyWhisperer-USB Main Interface

class Usb(viewsb=False)

PhyWhisperer-USB Interface

arm(value=True)

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_sequence to program the trigger parameters. Use set_capture_size and set_capture_delay to program the capture parameters.

Parameters:

value (bool) – True/False = arm/disarm

Raises:

ValueError – if trying to arm an already armed PhyWhisperer.

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.

property fifo_errors

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

fifo_over_empty_threshold()

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

get_fifo_errors()

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

get_fpga_buildtime()

Returns date and time when FPGA bitfile was generated.

get_num_pm_triggers_seen()

Number of pattern match triggers generated. Resets upon arming.

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_sequence()

ns_trigger(delay_in_ns)

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

property power_source

status changes via pushbutton are not reflected here.

Type:

Power source for target. NOTE

static print_flags(stat_byte)

Print bitfields of USB status flags byte.

print_packets(packets)

Print packets using USBSimplePrintSink from ViewSB/pyopenvizsla. :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. Defaults 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=16376, 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_sequence(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_sequence(), which uses a 240 MHz clock! Can also be accessed via the capture_delay property.

Parameters:

delay (int) – range in [0, 2^18-1] cycles of 60 MHz clock.

set_capture_enabled(enable)

Set whether USB events are captured or not. Can also be accessed via the capture_enabled property.

Parameters:

enable (bool) –

set_capture_size(size=16376)

Set how many events to capture (events include data, USB status, and timestamps). Can also be accessed via the capture_size property.

Parameters:

size (int, option) – number of events to capture. 0 = unlimited (until overflow). Max = 2^24-1. Since the capture FIFO can hold 16376 events, setting this to > 16376 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. Can also be accessed via the power_source property.

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_sequence(num_triggers=1, delays=[0], widths=[1], enable=True)

Program the output trigger sequence that is issued when a pattern match occurs. For each pattern match event, up to 8 pulse(s) of programmable delay and width are issued. Both delay and width 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! The capture delay is automatically set to match the first 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. Can also be accessed via the trigger.enable, trigger.num_triggers, trigger.delays, and trigger.widths properties.

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_sequence(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_sequence(num_triggers=2, delays=[10,20], widths=[1,2])

set_usb_mode(mode='auto')

Set USB PHY speed. Can also be accessed via the usb_mode property.

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). Can also be accessed via the trigger.clock_phase property.

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_sequence()

wait_disarmed()

Blocks until armed() returns false.

write_reg(address, data)

Write a PhyWhisperer register.

Parameters:

  • address – int

  • data – bytes

phy.pattern

Class to inspect pattern settings.

class pattern(main)

Pattern-related settings (read-only).

property mask

Mask used for pattern matching. Read-only property; set via set_pattern().

property num_bytes

Number of bytes used for pattern matching. Read-only property; set via set_pattern().

property pattern

Pattern used for pattern matching. Read-only property; set via set_pattern().

phy.trigger

Class to access trigger settings.

class trigger(main)

Trigger-related settings.

property clock_phase

Wrapper for trigger_clock_phase_shift().

property delays

Delays between the output trigger pulses that are generated when a pattern match occurs. Can also be set via set_trigger_sequence(). Unlike set_trigger_sequence(), this property does not adjust capture_delay.

property enable

Whether trigger output pins (Trig Out MCX and IO4) are driven when a pattern match occurs. Can also be set via set_trigger_sequence().

property num_pm_triggers

Maximum number of pattern match triggers to generate. Defaults to 1. Each pattern match triggers sets off a sequence of output triggers as specified by set_trigger_sequence(). This property allows triggers to be generated for multiple pattern match events without having to be re-armed. Can also be accessed via the num_pm_triggers property.

Parameters:

num (int) – number of triggers; maximum 2**16-2, or set to -1 to generate an infinite number of triggers (until disarmed).

property num_pm_triggers_seen

Number of pattern match triggers generated. Resets upon arming.

property num_triggers

Number of output trigger pulses to generate when a pattern match occurs (maximum 8). Can also be set via set_trigger_sequence().

property widths

Widths of the output trigger pulses that are generated when a pattern match occurs. Can also be set via set_trigger_sequence().

phy.userio

Class to access USERIO settings.

class userio(main)

USERIO-related settings.

property data

Get the status of the USERIO data pins (D0-D7), or set the value to be driven on USERIO pins when the pin’s direction property is set to ‘O’. Index <x> controls pin D<x>. You can set a single index, a slice of indices, or the full array.

property direction

Set the direction of the USERIO data pins (D0-D7). Index <x> controls pin D<x>. You can set a single index, a slice of indices, or the full array. Use with care!

Parameters:

directions (string) – set to ‘I’ to denote an input to PhyWhisperer, or ‘O’ to denote driven by PhyWhisperer.

Firmware Update

Use auto_program():

>>> import phywhisperer.usb as pw
>>> phy = pw.Usb()
>>> phy.con()
>>> phy.auto_program()
Detected com port /dev/ttyACM0
Opening firmware...
Firmware not specified. Using firmware/phywhisperer.py
Opened!
Connecting...
Connected!
Erasing...
Erased!
Programming file None...
Programmed!
Verifying...
Verify OK!
Bootloader disabled. Please power cycle device.