pynq.lib.logictools Package

pynq.lib.logictools.boolean_generator Module

class pynq.lib.logictools.boolean_generator.BooleanGenerator(mb_info, intf_spec_name='PYNQZ1_LOGICTOOLS_SPECIFICATION')[source]

Bases: object

Class for the Boolean generator.

This class can implement any combinational function on user IO pins. Since each LUT5 takes 5 inputs, the basic function that users can implement is 5-input, 1-output boolean function. However, by concatenating multiple LUT5 together, users can implement complex boolean functions.

There are 20 5-LUTs, so users can implement at most 20 basic boolean functions at a specific time.

logictools_controller

The generator controller for this class.

Type:LogicToolsController
intf_spec

The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

Type:dict
expressions

The boolean expressions, each expression being a string.

Type:list/dict
waveforms

A dictionary storing the waveform objects for display purpose.

Type:dict
input_pins

A list of input pins used by the generator.

Type:list
output_pins

A list of output pins used by the generator.

Type:list
analyzer

Analyzer to analyze the raw capture from the pins.

Type:TraceAnalyzer
num_analyzer_samples

Number of analyzer samples to capture.

Type:int
frequency_mhz

The frequency of the captured samples, in MHz.

Type:float
analyze()[source]

Update the captured samples.

This method updates the captured samples from the trace analyzer. It is required after each step() / run()

clear_wave()[source]

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()[source]

Method to configure the IO switch.

Usually this method should only be used internally. Users only need to use run() method.

disconnect()[source]

Method to disconnect the IO switch.

Usually this method should only be used internally. Users only need to use stop() method.

reset()[source]

Reset the boolean generator.

This method will bring the generator from any state to ‘RESET’ state.

run()[source]

Run the boolean generator.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to run the boolean generator.

setup(expressions, frequency_mhz=10)[source]

Configure the generator with new boolean expression.

This method will bring the generator from ‘RESET’ to ‘READY’ state.

Parameters:
  • expressions (list/dict) – The boolean expression to be configured.
  • frequency_mhz (float) – The frequency of the captured samples, in MHz.
show_waveform()[source]

Display the boolean logic generator in a Jupyter notebook.

A wavedrom waveform is shown with all inputs and outputs displayed.

status

Return the generator’s status.

Returns:Indicating the current status of the generator; can be ‘RESET’, ‘READY’, or ‘RUNNING’.
Return type:str
step()[source]

Step the boolean generator.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to step the boolean generator.

stop()[source]

Stop the boolean generator.

This method will stop the currently running boolean generator.

trace(use_analyzer=True, num_analyzer_samples=128)[source]

Configure the trace analyzer.

By default, the trace analyzer is always on, unless users explicitly disable it.

Parameters:
  • use_analyzer (bool) – Whether to use the analyzer to capture the trace.
  • num_analyzer_samples (int) – The number of analyzer samples to capture.

pynq.lib.logictools.fsm_generator Module

class pynq.lib.logictools.fsm_generator.FSMGenerator(mb_info, intf_spec_name='PYNQZ1_LOGICTOOLS_SPECIFICATION')[source]

Bases: object

Class for Finite State Machine generator.

This class enables users to specify a Finite State Machine (FSM). Users have to provide a FSM in the following format.

fsm_spec = {‘inputs’: [(‘reset’,’D0’), (‘direction’,’D1’)],

‘outputs’: [(‘alpha’,’D3’), (‘beta’,’D4’), (‘gamma’,’D5’)],

‘states’: (‘S0’, ‘S1’, ‘S2’, ‘S3’, ‘S4’, ‘S5’),

‘transitions’: [[‘00’, ‘S0’, ‘S1’, ‘000’],

[‘01’, ‘S0’, ‘S5’, ‘000’],

[‘00’, ‘S1’, ‘S2’, ‘001’],

[‘01’, ‘S1’, ‘S0’, ‘001’],

[‘00’, ‘S2’, ‘S3’, ‘010’],

[‘01’, ‘S2’, ‘S1’, ‘010’],

[‘00’, ‘S3’, ‘S4’, ‘011’],

[‘01’, ‘S3’, ‘S2’, ‘011’],

[‘00’, ‘S4’, ‘S5’, ‘100’],

[‘01’, ‘S4’, ‘S3’, ‘100’],

[‘00’, ‘S5’, ‘S0’, ‘101’],

[‘01’, ‘S5’, ‘S4’, ‘101’],

[‘1-‘, ‘*’, ‘S0’, ‘’]]}

The current implementation assumes Moore machine, so the output is decided by the current state. Hence, if a wildcard * is specified for the current state, users can just set the output to be empty.

logictools_controller

The generator controller for this class.

Type:LogicToolsController
intf_spec

The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

Type:dict
fsm_spec

The FSM specification, with inputs (list), outputs (list), states (list), and transitions (list).

Type:dict
num_input_bits

The number of input bits / pins.

Type:int
num_outputs

The number of possible FSM outputs specified by users.

Type:int
num_output_bits

The number of bits used for the FSM outputs.

Type:int
num_states

The number of FSM states specified by users.

Type:int
num_state_bits

The number of bits used for the FSM states.

Type:int
state_names

List of state names specified by the users.

Type:list
transitions

Transition list with all the wildcards replaced properly.

Type:int
input_pins

List of input pins on Arduino header.

Type:list
output_pins

List of output pins on Arduino header.

Type:list
use_state_bits

Flag indicating whether the state bits are shown on output pins.

Type:bool
analyzer

Analyzer to analyze the raw capture from the pins.

Type:TraceAnalyzer
num_analyzer_samples

The number of analyzer samples to capture.

Type:int
frequency_mhz

The frequency of the running FSM / captured samples, in MHz.

Type:float
waveform

The Waveform object used for Wavedrom display.

Type:Waveform
analyze()[source]

Update the captured samples.

This method updates the captured samples from the trace analyzer. It is required after each step() / run().

clear_wave()[source]

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()[source]

Method to configure the IO switch.

Usually this method should only be used internally. Users only need to use run() method.

disconnect()[source]

Method to disconnect the IO switch.

Usually this method should only be used internally. Users only need to use stop() method.

reset()[source]

Reset the FSM generator.

This method will bring the generator from any state to ‘RESET’ state.

run()[source]

Run the FSM generator.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to run the FSM generator.

setup(fsm_spec, use_state_bits=False, frequency_mhz=10)[source]

Configure the programmable FSM generator.

This method will configure the FSM based on supplied configuration specification. Users can send the samples to PatternAnalyzer for additional analysis.

Parameters:
  • fsm_spec (dict) – The FSM specification, with inputs (list), outputs (list), states (list), and transitions (list).
  • use_state_bits (bool) – Whether to check the state bits in the final output pins.
  • frequency_mhz (float) – The frequency of the FSM and captured samples, in MHz.
show_state_diagram(file_name='fsm_spec.png', save_png=False)[source]

Display the state machine in Jupyter notebook.

This method uses the installed package pygraphviz. References: http://pygraphviz.github.io/documentation/latest/pygraphviz.pdf

A PNG file of the state machine will also be saved into the current working directory.

Parameters:
  • file_name (str) – The name / path of the picture for the FSM diagram.
  • save_png (bool) – Whether to save the PNG showing the state diagram.
show_waveform()[source]

Display the waveform.

This method requires the waveform class to be present. Also, javascripts will be copied into the current directory.

status

Return the generator’s status.

Returns:Indicating the current status of the generator; can be ‘RESET’, ‘READY’, or ‘RUNNING’.
Return type:str
step()[source]

Step the FSM generator.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to step the FSM generator.

stop()[source]

Stop the FSM generator.

This command will stop the pattern generated from FSM.

trace(use_analyzer=True, num_analyzer_samples=128)[source]

Configure the trace analyzer.

By default, the trace analyzer is always on, unless users explicitly disable it.

Parameters:
  • use_analyzer (bool) – Whether to use the analyzer to capture the trace.
  • num_analyzer_samples (int) – The number of analyzer samples to capture.
pynq.lib.logictools.fsm_generator.check_duplicate(fsm_spec, key)[source]

Function to check duplicate entries in a nested dictionary.

This method will check the entry indexed by key in a dictionary. An exception will be raised if there are duplicated entries.

Parameters:
  • fsm_spec (dict) – The dictionary where the check to be made.
  • key (object) – The key to index the dictionary.
pynq.lib.logictools.fsm_generator.check_moore(num_states, num_outputs)[source]

Check whether the specified state machine is a moore machine.

This method will raise an exception if there are more state outputs than the number of states.

Parameters:
  • num_states (int) – The number of bits used for states.
  • num_outputs (int) – The number of state outputs.
pynq.lib.logictools.fsm_generator.check_num_bits(num_bits, label, minimum=0, maximum=32)[source]

Check whether the number of bits are still in a valid range.

This method will raise an exception if num_bits is out of range.

Parameters:
  • num_bits (int) – The number of bits of a specific field.
  • label (str) – The label of the field.
  • minimum (int) – The minimum number of bits allowed in that field.
  • maximum (int) – The maximum number of bits allowed in that field.
pynq.lib.logictools.fsm_generator.check_pin_conflict(pins1, pins2)[source]

Function to check whether there is conflict between input / output pins.

This method will raise an exception if there are pins specified in both inputs and outputs.

Parameters:
  • pins1 (list) – The list of the first set of pins.
  • pins2 (list) – The list of the second set of pins.
pynq.lib.logictools.fsm_generator.check_pins(fsm_spec, key, intf_spec)[source]

Check whether the pins specified are in a valid range.

This method will raise an exception if pin is out of range.

Parameters:
  • fsm_spec (dict) – The dictionary where the check to be made.
  • key (object) – The key to index the dictionary.
  • intf_spec (dict) – An interface spec containing the pin map.
pynq.lib.logictools.fsm_generator.expand_transition(transition, input_list)[source]

Add new (partially) expanded state transition.

Parameters:
  • transition (list) – Specifies a state transition.
  • input_list (list) – List of inputs, where each input is a string.
Returns:

New (partially) expanded state transition.

Return type:

list

pynq.lib.logictools.fsm_generator.get_bram_addr_offsets(num_states, num_input_bits)[source]

Get address offsets from given number of states and inputs.

This method returns the index offset for input bits. For example, if less than 32 states are used, then the index offset will be 5. If the number of states used is greater than 32 but less than 64, then the index offset will be 6.

This method also returns the address offsets for BRAM data. The returned list contains 2**`num_input_bits` offsets. The distance between 2 address offsets is 2**`index_offset`.

Parameters:
  • num_states (int) – The number of states in the state machine.
  • num_input_bits (int) – The number of inputs in the state machine.
Returns:

A list of 2**`num_input_bits` offsets.

Return type:

int, list

pynq.lib.logictools.fsm_generator.merge_to_length(a, b, length)[source]

Merge 2 lists into a specific length.

This method will merge 2 lists into a short list, replacing the last few items of the first list if necessary.

For example, a = [1,2,3], b = [4,5,6,7], and length = 6. The result will be [1,2,4,5,6,7]. If length = 5, the result will be [1,4,5,6,7]. If length is greater or equal to 7, the result will be [1,2,3,4,5,6,7].

Parameters:
  • a (list) – A list of elements.
  • b (list) – Another list of elements.
  • length (int) – The length of the result list.
Returns:

A merged list of the specified length.

Return type:

list

pynq.lib.logictools.fsm_generator.replace_wildcard(input_list)[source]

Method to replace a wildcard - in the input values.

This method will replace the wildcard - in the input list; the returned two lists have different values on the position of -.

Example: [‘0’, ‘-‘, ‘1’] => ([‘0’, ‘0’, ‘1’], [‘0’, ‘1’, ‘1’])

Parameters:input_list (list) – A list of multiple values, possibly with - inside.
Returns:Two lists differ by the location of -.
Return type:list,list

pynq.lib.logictools.pattern_generator Module

class pynq.lib.logictools.pattern_generator.PatternGenerator(mb_info, intf_spec_name='PYNQZ1_LOGICTOOLS_SPECIFICATION')[source]

Bases: object

Class for the Pattern generator.

This class can generate digital IO patterns / stimulus on output pins. Users can specify whether to use a pin as input or output.

logictools_controller

The generator controller for this class.

Type:LogicToolsController
intf_spec

The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

Type:dict
stimulus_group

A group of stimulus wavelanes.

Type:dict
stimulus_group_name

The name of the stimulus wavelanes.

Type:str
stimulus_names

The list of all the stimulus wavelane names, each name being a string.

Type:list
stimulus_pins

The list of all the stimulus wavelane pin labels, each pin label being a string.

Type:list
stimulus_waves

The list of all the stimulus wavelane waves, each wave being a string consisting of wavelane tokens.

Type:list
analysis_group

A group of analysis wavelanes.

Type:dict
analysis_group_name

The name of the analysis wavelanes.

Type:str
analysis_names

The list of all the analysis wavelane names, each name being a string.

Type:list
analysis_pins

The list of all the analysis wavelane pin labels, each pin label being a string.

Type:list
src_samples

The numpy array storing the stimuli, each sample being 32 bits.

Type:numpy.ndarray
dst_samples

The numpy array storing the response, each sample being 64 bits.

Type:numpy.ndarray
waveform_dict

A dictionary storing the patterns in WaveJason format.

Type:dict
waveform

The Waveform object used for Wavedrom display.

Type:Waveform
analyzer

Analyzer to analyze the raw capture from the pins.

Type:TraceAnalyzer
num_analyzer_samples

The number of analyzer samples to capture.

Type:int
frequency_mhz

The frequency of the running generator / captured samples, in MHz.

Type:float
analyze()[source]

Update the captured samples.

This method updates the captured samples from the trace analyzer. It is required after each step() / run()

clear_wave()[source]

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()[source]

Method to configure the IO switch.

Usually this method should only be used internally. Users only need to use run() method.

disconnect()[source]

Method to disconnect the IO switch.

Usually this method should only be used internally. Users only need to use stop() method.

longest_wave

Return the name of the longest wave.

Will only be changed by internal method.

max_wave_length

Return the maximum wave length

Will only be changed by internal method.

reset()[source]

Reset the pattern generator.

This method will bring the generator from any state to ‘RESET’ state.

run()[source]

Run the pattern generation.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to run the pattern generator.

setup(waveform_dict, stimulus_group_name=None, analysis_group_name=None, mode='single', frequency_mhz=10)[source]

Configure the pattern generator with a single bit pattern.

Generates a bit pattern for a single shot operation at specified IO pins with the specified number of samples.

Each bit of the 20-bit patterns, from LSB to MSB, corresponds to: D0, D1, …, D13, A0, A1, …, A5, respectively.

Note the all the lanes should have the same number of samples. And the token inside wave are already converted into bit string.

Users can ignore the returned data in case only the pattern generator is required.

Mode single means the pattern will be generated only once, while mode multiple means the pattern will be generated repeatedly.

Parameters:
  • waveform_dict (dict) – Waveform dictionary in WaveJSON format.
  • stimulus_group_name (str) – Name of the WaveLane group for the stimulus if used.
  • analysis_group_name (str) – Name of the WaveLane group for the analysis if used.
  • mode (str) – Mode of the pattern generator, can be single or multiple.
  • frequency_mhz (float) – The frequency of the captured samples, in MHz.
show_waveform()[source]

Display the waveform in Jupyter notebook.

This method requires the waveform class to be present. At the same time, javascripts will be copied into the current directory.

status

Return the generator’s status.

Returns:Indicating the current status of the generator; can be ‘RESET’, ‘READY’, or ‘RUNNING’.
Return type:str
step()[source]

Step the pattern generator.

The method will first collects the pins used and sends the list to Microblaze for handling. Then it will start to step the pattern generator.

stop()[source]

Stop the pattern generation.

This method will stop the currently running pattern generator.

trace(use_analyzer=True, num_analyzer_samples=128)[source]

Configure the trace analyzer.

By default, the trace analyzer is always on, unless users explicitly disable it.

Parameters:
  • use_analyzer (bool) – Whether to use the analyzer to capture the trace.
  • num_analyzer_samples (int) – The number of analyzer samples to capture.

pynq.lib.logictools.trace_analyzer Module

class pynq.lib.logictools.trace_analyzer.TraceAnalyzer(ip_info, intf_spec_name='PYNQZ1_LOGICTOOLS_SPECIFICATION')[source]

Bases: object

Class for trace analyzer.

This class can capture digital IO patterns / stimulus on monitored pins.

This class can wrap one out of the two classes: (1) the Microblaze controlled trace analyzer, or (2) the PS controlled trace analyzer.

To use the PS controlled trace analyzer, users can set the ip_info to a dictionary containing the corresponding IP name; for example:

>>> ip_info = {'trace_cntrl':'trace_analyzer_pmoda/trace_cntrl_0',
    'trace_dma': 'trace_analyzer_pmoda/axi_dma_0'}

Otherwise the Microblaze controlled trace analyzer will be used. By default, the Microblaze controlled version will be used, and the interface specification name will be set to PYNQZ1_LOGICTOOLS_SPECIFICATION.

Most of the methods implemented inside this class assume the protocol is known, so the pattern can be decoded and added to the annotation of the waveforms.

In case the protocol is unknown, users should refrain from using these methods.

Two files are maintained by this class: the csv file, which is human readable; and the sr file, which is sigrok readable.

analyze(steps=0)[source]

Analyze the captured pattern.

This function will process the captured pattern and put the pattern into a Wavedrom compatible format.

The data output is of format:

[{‘name’: ‘’, ‘pin’: ‘D1’, ‘wave’: ‘1…0…..’},
{‘name’: ‘’, ‘pin’: ‘D2’, ‘wave’: ‘0.1..01.01’}]

Note the all the lanes should have the same number of samples. All the pins are assumed to be tri-stated and traceable.

Currently only no step() method is supported for PS controlled trace analyzer.

Parameters:steps (int) – Number of samples to analyze. A value 0 means to analyze all the valid samples.
Returns:A list of dictionaries, each dictionary consisting the pin number, and the waveform pattern in string format.
Return type:list
decode(trace_csv, start_pos, stop_pos, decoded_file, options='')[source]

Parse CSV file, add metadata, and use sigrok to decode transactions.

Internally, this method is calling save_csv(), set_metadata(), and sigrok_decode() methods.

Parameters:
  • trace_csv (str) – Name of the output file (*.csv) which can be opened in text editor.
  • start_pos (int) – Starting sample number, no less than 1.
  • stop_pos (int) – Stopping sample number, no more than the maximum number of samples.
  • decoded_file (str) – Name of the output file, which can be opened in text editor.
  • options (str) – Additional options to be passed to sigrok-cli.
Returns:

Return type:

None

get_transactions()[source]

List all the transactions captured.

The transaction list will only be non-empty after users have run decode() method. An exception will be raised if the transaction is empty, or the text file cannot be found.

Returns:A list of dictionaries. Each bus event is a dictionary: [{‘command’: str, ‘begin’: int, ‘end’: int}]
Return type:list
reset()[source]

Reset the trace analyzer.

This method will bring the trace analyzer from any state to ‘RESET’ state.

At the same time, all the trace files stored previously will be removed.

run()[source]

Start the trace capture.

Returns:
Return type:None
set_protocol(protocol, probes)[source]

Set the protocol and probes for the decoder.

This method is usually called at beginning of the analyzer. To learn from that specific protocol, users can call show_protocol to learn useful information about that protocol.

Currently only i2c and spi are supported.

This method also sets the probe names for the decoder.

The dictionary probes depends on the protocol. For instance, the I2C protocol requires the keys ‘SCL’ and ‘SDA’. An example can be:

>>>probes = {‘SCL’: ‘D2’, ‘SDA’: ‘D3’}

To avoid memory error for decoding, users can add NC as non-used pins to the probes.

Parameters:
  • protocol (str) – The name of the protocol.
  • probes (dict) – A dictionary keeping the probe names and pin number.
setup(num_analyzer_samples=128, frequency_mhz=10, fclk_index=None)[source]

Configure the trace analyzer.

The wrapper method for configuring the PS or Microblaze controlled trace analyzer.

Users need to provide the fclk_index explicitly, otherwise the driver will just use the default clock. For MB-controlled trace analyzer, the default fclk_index is 1; for PS-controlled trace analyzer, the default fclk_index is 3.

Parameters:
  • num_analyzer_samples (int) – The number of samples to be analyzed.
  • frequency_mhz (float) – The frequency of the captured samples, in MHz.
  • fclk_index (int) – The index of the fclk controlled by clock management object.
show_protocol()[source]

Show information about the specified protocol.

This method will print out useful information about the protocol.

Returns:
Return type:None
status

Return the analyzer’s status.

Returns:Indicating the current status of the analyzer; can be ‘RESET’, ‘READY’, or ‘RUNNING’.
Return type:str
step()[source]

Step the trace analyzer.

This method is only supported in the Microblaze controlled trace analyzer. An exception will be raised if users want to call this method in PS controlled trace analyzer.

stop()[source]

Stop the DMA after capture is done.

Returns:
Return type:None
pynq.lib.logictools.trace_analyzer.get_tri_state_pins(io_pin_dict, tri_dict)[source]

Function to check tri-state pin specifications.

Any tri-state pin requires the input/output pin, and the tri-state selection pin to be specified. If any one is missing, this method will raise an exception.

Parameters:
  • io_pin_dict (dict) – A dictionary storing the input/output pin mapping.
  • tri_dict (dict) – A dictionary storing the tri-state pin mapping.
Returns:

A list storing unique tri-state and non tri-state pin names.

Return type:

list

pynq.lib.logictools.waveform Module

class pynq.lib.logictools.waveform.Waveform(waveform_dict, intf_spec_name='PYNQZ1_LOGICTOOLS_SPECIFICATION', stimulus_group_name=None, analysis_group_name=None)[source]

Bases: object

A wrapper class for Wavedrom package and interfacing functions.

This class wraps the key functions of the Wavedrom package, including waveform display, bit pattern converting, csv converting, etc.

A typical example of the waveform dictionary is:

>>> loopback_test = {'signal': [

[‘stimulus’,

{‘name’: ‘clk0’, ‘pin’: ‘D0’, ‘wave’: ‘lh’ * 64},

{‘name’: ‘clk1’, ‘pin’: ‘D1’, ‘wave’: ‘l.h.’ * 32},

{‘name’: ‘clk2’, ‘pin’: ‘D2’, ‘wave’: ‘l…h…’ * 16},

{‘name’: ‘clk3’, ‘pin’: ‘D3’, ‘wave’: ‘l…….h…….’ * 8}],

[‘analysis’,

{‘name’: ‘clk15’, ‘pin’: ‘D15’},

{‘name’: ‘clk16’, ‘pin’: ‘D16’},

{‘name’: ‘clk17’, ‘pin’: ‘D17’},

{‘name’: ‘clk18’, ‘pin’: ‘D18’},

{‘name’: ‘clk19’, ‘pin’: ‘D19’}]

],

‘foot’: {‘tock’: 1},

‘head’: {‘text’: ‘Loopback Test’}}

waveform_dict

The json data stored in the dictionary.

Type:dict
intf_spec

The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

Type:dict
stimulus_group_name

Name of the WaveLane group for the stimulus, defaulted to stimulus.

Type:str
analysis_group_name

Name of the WaveLane group for the analysis, defaulted to analysis.

Type:str
stimulus_group

A group of lanes, each lane being a dict of name, pin label,and wave.

Type:list
analysis_group

A group of lanes, each lane being a dict of name, pin label,and wave.

Type:list
analysis_group

Return the analysis WaveLane group.

An analysis group looks like: [{‘name’: ‘dat’, ‘pin’: ‘D1’, ‘wave’: ‘l…h…lhlh’}, {‘name’: ‘req’, ‘pin’: ‘D2’, ‘wave’: ‘lhlhlhlh….’}]

Returns:A list of lanes, each lane being a dictionary of name, pin label, and wave.
Return type:list
analysis_names

Returns all the names of the analysis WaveLanes.

The returned names are in the same order as in the waveform dictionary.

Returns:A list of names for all the analysis WaveLanes.
Return type:list
analysis_pins

Returns all the pin labels of the analysis WaveLanes.

The returned pin labels are in the same order as in the waveform dictionary.

Returns:A list of pin labels for all the analysis WaveLanes.
Return type:list
analysis_waves

Returns all the waves of the analysis WaveLanes.

The returned waves are in the same order as in the waveform dictionary.

Returns:A list of waves for all the analysis WaveLanes.
Return type:list
annotate(group_name, wavelane_group)[source]

Add annotation to the existing waveform dictionary.

This method will add annotation wavelane into the specified group. Usually this is used in combination with the trace analyzer.

The annotation usually has the following format:

[{name: ‘’,
wave: ‘x.444x4.x’, data: [‘read’, ‘write’, ‘read’, ‘data’]}]
Parameters:
  • group_name (str) – The name of the WaveLane group to be updated.
  • wavelane_group (list) – The WaveLane group specified for updating.
append(group_name, wavelane_group)[source]

Append new data to the existing waveform dictionary.

A typical use case of this method is that it gets the output returned by the analyzer and append new data to the dictionary.

Since the analyzer only knows the pin labels, the data returned from the pattern analyzer is usually of format:

[{‘name’: ‘’, ‘pin’: ‘D1’, ‘wave’: ‘l…h…lhlh’}, {‘name’: ‘’, ‘pin’: ‘D2’, ‘wave’: ‘lhlhlhlh….’}]

Note the all the lanes should have the same number of samples. Note each lane in the analysis group has its pin number. Based on this information, this function only updates the lanes specified.

Parameters:
  • group_name (str) – The name of the WaveLane group to be updated.
  • wavelane_group (list) – The WaveLane group specified for updating.
clear_wave(group_name)[source]

Clear the wave in the existing waveform dictionary.

This method will clear the wave stored in each wavelane, so that a brand-new waveform dict can be constructed.

Annotation is assumed to have an empty name, so the entire annotation lane will get deleted in this method.

Parameters:group_name (str) – The name of the WaveLane group to be updated.
display()[source]

Display the waveform using the Wavedrom package.

This package requires 2 javascript files to be copied locally.

stimulus_group

Return the stimulus WaveLane group.

A stimulus group looks like: [{‘name’: ‘dat’, ‘pin’: ‘D1’, ‘wave’: ‘l…h…lhlh’}, {‘name’: ‘req’, ‘pin’: ‘D2’, ‘wave’: ‘lhlhlhlh….’}]

Returns:A list of lanes, each lane being a dictionary of name, pin label, and wave.
Return type:list
stimulus_names

Returns all the names of the stimulus WaveLanes.

The returned names are in the same order as in the waveform dictionary.

Returns:A list of names for all the stimulus WaveLanes.
Return type:list
stimulus_pins

Returns all the pin labels of the stimulus WaveLanes.

The returned pin labels are in the same order as in the waveform dictionary.

Returns:A list of pin labels for all the stimulus WaveLanes.
Return type:list
stimulus_waves

Returns all the waves of the stimulus WaveLanes.

The returned waves are in the same order as in the waveform dictionary.

Returns:A list of waves for all the stimulus WaveLanes.
Return type:list
update(group_name, wavelane_group)[source]

Update waveform dictionary based on the specified WaveLane group.

A typical use case of this method is that it gets the output returned by the analyzer and refreshes the data stored in the dictionary.

Since the analyzer only knows the pin labels, the data returned from the pattern analyzer is usually of format:

[{‘name’: ‘’, ‘pin’: ‘D1’, ‘wave’: ‘l…h…lhlh’}, {‘name’: ‘’, ‘pin’: ‘D2’, ‘wave’: ‘lhlhlhlh….’}]

Note the all the lanes should have the same number of samples. Note each lane in the analysis group has its pin number. Based on this information, this function only updates the lanes specified.

Parameters:
  • group_name (str) – The name of the WaveLane group to be updated.
  • wavelane_group (list) – The WaveLane group specified for updating.
pynq.lib.logictools.waveform.bitstring_to_int(bitstring)[source]

Function to convert a bit string to integer list.

For example, if the bit string is ‘0110’, then the integer list will be [0,1,1,0].

Parameters:bitstring (str) – The input string to convert.
Returns:A list of elements, each element being 0 or 1.
Return type:list
pynq.lib.logictools.waveform.bitstring_to_wave(bitstring)[source]

Function to convert a pattern consisting of 0, 1 into a sequence of l, h, and dots.

For example, if the bit string is “010011000111”, then the result will be “lhl.h.l..h..”.

Returns:New wave tokens with valid tokens and dots.
Return type:str
pynq.lib.logictools.waveform.draw_wavedrom(data)[source]

Display the waveform using the Wavedrom package.

Users can call this method directly to draw any wavedrom data.

Example usage:

>>> a = {
    'signal': [
        {'name': 'clk', 'wave': 'p.....|...'},
        {'name': 'dat', 'wave': 'x.345x|=.x',
                        'data': ['head', 'body', 'tail', 'data']},
        {'name': 'req', 'wave': '0.1..0|1.0'},
        {},
        {'name': 'ack', 'wave': '1.....|01.'}
    ]}
>>> draw_wavedrom(a)

More information can be found at: https://github.com/witchard/nbwavedrom

Parameters:data (dict) – A dictionary of data as shown in the example.
pynq.lib.logictools.waveform.int_to_sample(bits)[source]

Function to convert a bit list into a multi-bit sample.

Example: [1, 1, 1, 0] will be converted to 7, since the LSB of the sample appears first in the sequence.

Parameters:bits (list) – A list of bits, each element being 0 or 1.
Returns:A numpy uint32 converted from the bit samples.
Return type:int
pynq.lib.logictools.waveform.wave_to_bitstring(wave)[source]

Function to convert a pattern consisting of l, h, and dot to a sequence of 0 and 1.

Parameters:wave (str) – The input string to convert.
Returns:A bit sequence of 0’s and 1’s.
Return type:str