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')

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

LogicToolsController – The generator controller for this class.

intf_spec

dict – The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

expressions

list/dict – The boolean expressions, each expression being a string.

waveforms

dict – A dictionary storing the waveform objects for display purpose.

input_pins

list – A list of input pins used by the generator.

output_pins

list – A list of output pins used by the generator.

analyzer

TraceAnalyzer – Analyzer to analyze the raw capture from the pins.

num_analyzer_samples

int – Number of analyzer samples to capture.

frequency_mhz

float – The frequency of the captured samples, in MHz.

analyze()

Update the captured samples.

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

clear_wave()

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()

Method to configure the IO switch.

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

disconnect()

Method to disconnect the IO switch.

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

reset()

Reset the boolean generator.

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

run()

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)

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

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

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

Stop the boolean generator.

This method will stop the currently running boolean generator.

trace(use_analyzer=True, num_analyzer_samples=128)

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')

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

LogicToolsController – The generator controller for this class.

intf_spec

dict – The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

fsm_spec

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

num_input_bits

int – The number of input bits / pins.

num_outputs

int – The number of possible FSM outputs specified by users.

num_output_bits

int – The number of bits used for the FSM outputs.

num_states

int – The number of FSM states specified by users.

num_state_bits

int – The number of bits used for the FSM states.

state_names

list – List of state names specified by the users.

transitions

int – Transition list with all the wildcards replaced properly.

input_pins

list – List of input pins on Arduino header.

output_pins

list – List of output pins on Arduino header.

use_state_bits

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

analyzer

TraceAnalyzer – Analyzer to analyze the raw capture from the pins.

num_analyzer_samples

int – The number of analyzer samples to capture.

frequency_mhz

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

waveform

Waveform – The Waveform object used for Wavedrom display.

analyze()

Update the captured samples.

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

clear_wave()

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()

Method to configure the IO switch.

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

disconnect()

Method to disconnect the IO switch.

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

reset()

Reset the FSM generator.

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

run()

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)

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)

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

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

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

Stop the FSM generator.

This command will stop the pattern generated from FSM.

trace(use_analyzer=True, num_analyzer_samples=128)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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')

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

LogicToolsController – The generator controller for this class.

intf_spec

dict – The interface specification, e.g., PYNQZ1_LOGICTOOLS_SPECIFICATION.

stimulus_group

dict – A group of stimulus wavelanes.

stimulus_group_name

str – The name of the stimulus wavelanes.

stimulus_names

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

stimulus_pins

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

stimulus_waves

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

analysis_group

dict – A group of analysis wavelanes.

analysis_group_name

str – The name of the analysis wavelanes.

analysis_names

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

analysis_pins

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

src_samples

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

dst_samples

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

waveform_dict

dict – A dictionary storing the patterns in WaveJason format.

waveform

Waveform – The Waveform object used for Wavedrom display.

analyzer

TraceAnalyzer – Analyzer to analyze the raw capture from the pins.

num_analyzer_samples

int – The number of analyzer samples to capture.

frequency_mhz

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

analyze()

Update the captured samples.

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

clear_wave()

Clear the waveform object so new patterns can be accepted.

This function is required after each stop().

connect()

Method to configure the IO switch.

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

disconnect()

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

Reset the pattern generator.

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

run()

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)

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

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

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

Stop the pattern generation.

This method will stop the currently running pattern generator.

trace(use_analyzer=True, num_analyzer_samples=128)

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')

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)

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='')

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

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

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

Start the trace capture.

Returns: Return type:None

set_protocol(protocol, probes)

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)

Configure the trace analyzer.

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

Parameters:

• num_analyzer_samples (int) – The number of samples to be analyzed.
• frequency_mhz (float) – The frequency of the captured samples, in MHz.

show_protocol()

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

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

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)

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