ILA¶

The customizable Integrated Logic Analyzer (ILA) IP core is a logic analyzer that can be used to monitor the internal signals of a design. The ILA core includes many advanced features of modern logic analyzers, including boolean trigger equations and edge transition triggers. Because the ILA core is synchronous to the design being monitored, all design clock constraints that are applied to your design are also applied to the components of the ILA core.

Features Selectable at Design Flow Time:

Number of probe ports and port widths
The number of match unit comparators, per port.
Multiple (logical) Probes may use different bit ranges on the same probe port.
Waveform Data sample storage depth.
Trig-In and Trig-Out signal ports.

Features Selectable at Debug Run-Time:

Probe match values.
Global boolean trigger condition.
Waveform window count, window size and Trigger Position.

The ILA class represents one ILA core

ILA Attributes¶

class chipscopy.api.ila.ila.ILA(tcf_ila, device, ltx)[source]¶

Data read-only attributes are accessible by dot-notation’, e.g. my_ila.static_info.status

Attribute	Type	Description
name	str	Name of ILA core instance.
core_info	`CoreInfo`	Debug core version information.
static_info	`ILAStaticInfo`	Feature set and dimensions of the ILA core.
status	`ILAStatus`	Dynamic status of ILA capture controller.
control	`ILAControl`	Trigger setup.
ports	[`ILAPort`]	List of ILA core ports.
probes	{str, `ILAProbe`}	Probes by probe name.
probe_values	{str, `ILAProbeValues`}	Probe compare values.
waveform	`ILAWaveform`	Last uploaded waveform data, or None.

ILA Probe Functions¶

There is a logical mapping between ports of an ILA core and elements in the user’s design. This port mapping is recorded in the LTX file in the Vivado design flow.

When an LTX file is read, the HDL net/bus name mapping is available. This enables reading and writing probe values in the context of the HDL design.

ILA.get_probe_capture_value¶

ILA.get_probe_capture_value(name)[source]¶

Get basic capture mode compare value for a probe.

Parameters: name (str) – Probe name.
Return type: []
Returns: List with two items [<operator>, <value>]. See ILAProbeValues

ILA.get_probe_trigger_value¶

ILA.get_probe_trigger_value(name)[source]¶

Get basic trigger mode compare value(s) for a probe.

Parameters: name (str) – Probe name.
Return type: []
Returns: List of <operator>/<value> pairs. See ILAProbeValues

ILA.reset_probes¶

ILA.reset_probes(reset_trigger_values=True, reset_capture_values=True)[source]¶

Reset probe compare values, to dont-cares.

Parameters

reset_trigger_values (bool) – Resets trigger compare values, for all core probes.
reset_capture_values (bool) – Resets basic capture control compare value, for all probes.

Return type

None

ILA.set_probe_capture_value¶

ILA.set_probe_capture_value(name, capture_value)[source]¶

For basic capture mode, set probe compare value to filter samples.

Parameters

name (str) – Probe name.
capture_value ([]) – List with two items: [<operator>, <value>]. See ILAProbeValues

Return type

None

ILA.set_probe_trigger_value¶

ILA.set_probe_trigger_value(name, trigger_value)[source]¶

For basic trigger mode, set probe compare value(s).

A compare value consists of a pair: <operator> and <value> <value> may be of type int or binary string of the correct bit_width. An empty list is a don’t-care value.

Example: Test for LSB is ‘0’ on a 4-bit probe.
[‘==’, ‘XXX0’]

Example: Range check, assuming the global Trigger Condition is ILATriggerCondition.AND:
[‘>=’, ‘0011’, ‘<=’, ‘1010’]

Example: Range check, assuming the global Trigger Condition is ILATriggerCondition.AND:
[‘>=’, 3, ‘<=’, 10]

Example: Test equal to any of 3 numbers, assuming the global Trigger Condition is ILATriggerCondition.OR:
[‘==’, ‘0011’, ‘==’, ‘0111’, ‘==’, ‘1111’]

Example: 4-bit dont-care value.
[‘==’, ‘XXXX’]

Example: Dont-care value, written as an empty list.
[]

Parameters

name (str) – Probe name.
trigger_value (list) – [<operator>, <value>, …] See ILAProbeValues

Return type

None

ILA Run Functions¶

The run functions specifies trigger capture options and arms the ILA core.

ILA.refresh_status¶

ILA.refresh_status()[source]¶

Read dynamic status and store in attribute ‘ila.status’.

Return type: None

ILA.monitor_status¶

ILA.monitor_status(max_wait_minutes=None, progress=None, done=None)[source]¶

Function monitors ILA capture status and waits until all data has been captured, or until timeout or the function is cancelled. Call this function after arming the ILA, before uploading the waveform. The command operates in synchronous mode if done argument has default value None .

Synchronous Mode

Calling this function in synchronous mode, is the same as calling function ILA.wait_until_done().
Function waits until all data has been captured in the ILA core, or timeout.
Use default argument value None for arguments progress and done .
Returns an ILAStatus object.

Asynchronous Mode

This mode is useful for reporting the capture status to stdout or a GUI.
Function does not block. The main thread continues with the next statement.
Returns a future object, which represents the monitor.
A blocking function should be called later on the future object, in order to wait on the calling thread until the status monitor has completed.
Asynchronous Mode is selected, by specifying a done function, which is called after the function has completed.
If no user defined callback is needed, set done argument to dummy function chipscopy.null_callback , to enable asynchronous mode.

Future Object

When the monitor_status function is called in asynchronous mode, it will return a future object. The future object has blocking attributes and functions, which will block the current thread until the status monitor has completed.

Blocking Attributes:

future.result (None or ILAStatus) - ILAStatus object if capture completed successfully, without timeout.
future.error - (None or Exception) - None if no error otherwise an exception object, e.g. timeout exception.

Non-blocking Attribute:

future.progress (None or ILAStatus) - Access in progress function, to read the ILA capture status.

Blocking Function:

future.wait(timeout=None) - None means wait until status monitor completed. Argument timeout is in seconds.

Non-blocking Function:

future.cancel() - Cancels the status monitor. An exception will be raised, in the thread which called the function ILA.monitor_status .

Progress Function

User-defined function which takes one argument future .
Useful for reporting ILA capture status.
The progress function is only called when the ILA capture status changes.
The progress function is called in the TCF Event Thread. The progress function must not call any ChipScoPy API function, which interacts with the cs_server or the device.

Example:

def monitor_status_done(future):
   if not future.error:
       # future.result holds an ILAStatus object.
       print_status(future.progress)

Parameters

max_wait_minutes (float) – Max time in minutes for status monitor. If None, status monitor never times out.
progress (progress_fn) – See Asynchronous Mode, above. This function runs in the TCF Event Thread.
done (request.DoneFutureCallback) – Done callback. This function runs in the TCF Event Thread.

Returns (ILAStatus or request.CsFutureRequestSync or None):

Return type: ILAStatus

ILA.run_trigger_immediately¶

ILA.run_trigger_immediately(trigger_position=0, window_count=1, window_size=-1, trig_out=<ILATrigOutMode.DISABLED: 0>)[source]¶

Trigger ILA immediately.

Parameters

trigger_position (int) – Default : 0 Range [0..window_size-1].
window_count (int) – Number of windows to capture. Default value: 1.
window_size (int) – Number of samples per window. Must be a power-of-two value. Default value: ILA_WINDOW_SIZE_MAX
trig_out (ILATrigOutMode) – Specify what drives TRIG-OUT port. Default value: ILATrigOutMode.DISABLED

Return type

None

ILA.run_basic_trigger¶

ILA.run_basic_trigger(trigger_position=-1, window_count=1, window_size=-1, trigger_condition=<ILATriggerCondition.AND: 1>, capture_condition=<ILACaptureCondition.ALWAYS: 4>, trig_in=<ILATrigInMode.DISABLED: 0>, trig_out=<ILATrigOutMode.DISABLED: 0>)[source]¶

Trigger using probe compare values.

Parameters

trigger_position (int) – Default ILA_TRIGGER_POSITION_HALF denotes the middle of the window. Range [0..window_size-1].
window_count (int) – Number of windows to capture. Default value: 1.
window_size (int) – Number of samples per window. Must be a power-of-two value. Default value: ILA_WINDOW_SIZE_MAX
trigger_condition (ILATriggerCondition) – Trigger condition global boolean operator.
capture_condition (ILACaptureCondition) – Capture condition global boolean operator, to filter samples.
trig_in (ILATrigInMode) – Usage of TRIG-IN Port. Default value: ILATrigInMode.DISABLED
trig_out (ILATrigOutMode) – Specify what drives TRIG-OUT port. Default value: ILATrigOutMode.DISABLED

Return type

None

ILA.wait_till_done¶

ILA.wait_till_done(max_wait_minutes=None)[source]¶

Wait until all data has been captured, or until timeout. Call this function after arming the ILA, before uploading the waveform.

Parameters: max_wait_minutes (float) – Max time in minutes for command. If None, status monitor never times out.

Returns (ILAStatus): ILA capture status.

Return type: ILAStatus

ILA Waveform Functions¶

ILA functions to upload waveform from core and export.

ILA.upload¶

ILA.upload()[source]¶

Upload waveform. If the ILA has not triggered yet, it will return with value False. The uploaded waveform is at self.waveform.

Returns (bool):: True, if a waveform was uploaded.

Return type: bool

export_waveform¶

ila.export_waveform(export_format='CSV', fh_or_filepath=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, probe_names=None, start_window_idx=0, window_count=None, start_sample_idx=0, sample_count=None)¶

Export a waveform in VCD or CSV format, to a file. By default all samples for all probes are exported, but it is possible to select which probes and window/sample ranges.

Parameters

waveform (ILAWaveform) – waveform data.
export_format (str) –
Alternatives for output format.
- ’CSV’ - Comma Separated Value Format. Default.
- ’VCD’ - Value Change Dump.
fh_or_filepath (TextIOBase, str) –
File object handle or filepath string. Default is sys.stdout. If a file object, the file object is opened and closed by the caller, if needed.

Alternatively, a file path may be specified as a string. The file will be opened and closed by the function.
probe_names (Optional[List[str]]) – List of probe names. Default ‘None’ means export all probes.
start_window_idx (int) – Starting window index. Default is first window.
window_count (Optional[int]) – Number of windows to export. Default is all windows.
start_sample_idx (int) – Starting sample within window. Default is first sample.
sample_count (Optional[int]) – Number of samples per window. Default is all samples.

Return type

None

get_waveform_data¶

ila.get_waveform_data(probe_names=None, start_window_idx=0, window_count=None, start_sample_idx=0, sample_count=None, include_trigger=False, include_sample_info=False)¶

Get probe waveform data as a list of int values for each probe. By default all samples for all probes are included in return data, but it is possible to select which probes and window/sample ranges.

Parameters

waveform (ILAWaveform) – waveform data.
probe_names (Optional[List[str]]) – List of probe names. Default ‘None’ means export all probes.
start_window_idx (int) – Starting window index. Default is first window.
window_count (Optional[int]) – Number of windows to export. Default is all windows.
start_sample_idx (int) – Starting sample within window. Default is first sample.
sample_count (Optional[int]) – Number of samples per window. Default is all samples.
include_trigger (bool) – Include pseudo probe with name ‘__TRIGGER’ in result. Default is False.
include_sample_info (bool) –
Default is False. Include the following pseudo probes in result:
- ’__SAMPLE_INDEX’ - Sample index
- ’__WINDOW_INDEX’ - Window index.
- ’__WINDOW_SAMPLE_INDEX’ - Sample index within window.

Returns (Dict[str, List[int]]):

Ordered dict, in order:

‘__TRIGGER’, if argument include_trigger is True
‘__SAMPLE_INDEX’, if argument include_sample_info is True
‘__WINDOW_INDEX’, if argument include_sample_info is True
‘__WINDOW_SAMPLE_INDEX’, if argument include_sample_info is True
probe values in order of argument probe_names.

Dict key: probe name. Dict value is list of int values, for a probe.

Return type: Dict[str, List[int]]

get_waveform_probe_data¶

ila.get_waveform_probe_data(probe_name, start_window_idx=0, window_count=None, start_sample_idx=0, sample_count=None)¶

Get waveform data as a list of int values for one probe. By default all samples for the probe are returned, It is possible to select window range and sample range.

Parameters

waveform (ILAWaveform) – waveform data.
probe_name (str) – probe name.
start_window_idx (int) – Starting window index. Default is first window.
window_count (Optional[int]) – Number of windows to export. Default is all windows.
start_sample_idx (int) – Starting sample within window. Default is first sample.
sample_count (Optional[int]) – Number of samples per window. Default is all samples.

Returns (List[int]):: List probe values.

Return type: List[int]

ILA Data Defintions¶

Constant to indicate trigger position in the middle of the waveform window.

ila.ILA_TRIGGER_POSITION_HALF = -1¶

Constant to indicate maximum window size.

ila.ILA_WINDOW_SIZE_MAX = -1¶

CoreInfo¶

class chipscopy.api.CoreInfo(core_type, drv_ver, core_major_ver, core_minor_ver, tool_major_ver, tool_minor_ver, uuid)[source]¶

Debug Fabric Core version information.

core_type: int¶: Core type number.

drv_ver: int¶: SW/IP interface version.

core_major_ver: int¶: Core IP major version.

core_minor_ver: int¶: Core IP minor version.

tool_major_ver: int¶: Major version of the design tool, which created the core.

tool_minor_ver: int¶: Minor version of the design tool, which created the core.

uuid: str¶: Core UUID. UUID is unique among debug cores in the design.

ILABitRange¶

class chipscopy.api.ila.ILABitRange(index: int, length: int)[source]¶

Create new instance of ILABitRange(index, length)

property index¶: Bit index.

property length¶: Bit length.

ILACaptureCondition (enum)¶

class chipscopy.api.ila.ILACaptureCondition(value)[source]¶

For Basic Capture Control, the global boolean operator of participating probe comparators.

Enum Value	Description
ALWAYS	Capture all samples.
AND	AND probe comparators to filter data.
OR	OR probe comparators to filter data.
NAND	NAND probe comparators to filter data.
NOR	NOR probe comparators to filter data.

ILAControl¶

class chipscopy.api.ila.ILAControl(capture_condition, trig_in_mode, trig_out_mode, trigger_condition, trigger_position, trigger_state_machine, window_count, window_size)[source]¶

Trigger setup

capture_condition: chipscopy.api.ila.ila_capture.ILACaptureCondition¶: Basic capture cntrol global boolean operator. See ILACaptureCondition

trig_in_mode: chipscopy.api.ila.ila_capture.ILATrigInMode¶: Usage of TRIG-IN port. See ILATrigInMode

trig_out_mode: chipscopy.api.ila.ila_capture.ILATrigOutMode¶: Usage of TRIG-OUT port. See ILATrigOutMode

trigger_condition: chipscopy.api.ila.ila_capture.ILATriggerCondition¶: Global boolean operator, for trigger probes. See ILATriggerCondition

trigger_position: int¶: Trigger position index, within data window.

trigger_state_machine: str¶: Trigger State Machine, as a string.

window_count: int¶: Number of data windows.

window_size: int¶: Sample count for a window.

ILAPort¶

class chipscopy.api.ila.ILAPort(bit_width, data_bit_index, index, is_trigger, is_data, match_unit_count, match_unit_type)[source]¶

Probe Port on the ILA Core

bit_width: int¶: Number of port bits.

data_bit_index: int¶: Start bit index in waveform data.

index: int¶: Port index

is_trigger: bool¶: Port is used for triggering.

is_data: bool¶: Port is used for capturing data.

match_unit_count: int¶: Number of compare match units, available to the port.

match_unit_type: chipscopy.api.ila.ila_probe.ILAMatchUnitType¶: Type of match unit.

ILAProbe¶

class chipscopy.api.ila.ILAProbe(name, bit_width, is_data, is_trigger, map, mu_count, is_bus=False, bus_left_index=None, bus_right_index=None, display_radix=<ILAProbeRadix.HEX: 2>)[source]¶

Logical probe. Probes may share the same probe port.

name: str¶: Name of probe.

bit_width: int¶: Number of probe bits.

is_data: bool¶: Probe is used to capture waveform data.

is_trigger: bool¶: Probe can be used in trigger settings.

map: str¶: How probe is mapped to ports.

mu_count: int¶: Max number of compare match units, available to the probe.

is_bus: bool = False¶: True for bus probes

bus_left_index: Optional[int] = None¶: Bus left index. E.g. 5 in probe counter[5:0]

bus_right_index: Optional[int] = None¶: Bus right index. E.g. 0 in probe counter[5:0]

display_radix: chipscopy.api.ila.ila_probe.ILAProbeRadix = 2¶: Display radix, when exporting waveform data. Default is ILAProbeRadix.HEX

ILAProbeValues¶

ila.ILA_MATCH_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '||']¶

Operators for probe compare values.

Operator	Description
==	Equal
!=	Not equal
<	Less than
<=	Equal or less than
>	Greater than
>=	Equal or Greater than
\|\|	Reduction OR

ila.ILA_MATCH_BIT_VALUES = '01xXrRfFnNbBtTlLsS_'¶

Binary bit values for probe compare values.

Bit Value	Description
_	Underscore separator for readability.
X	Don’t care bit matches any bit-value.
0	Zero
1	One
F	Falling. Transition 1 -> 0
R	Rising. Transition 0 -> 1
L	Laying. Opposite to R.
S	Staying. Opposite to F.
B	Either Falling or Rising.
N	No change. Opposite to B.

class chipscopy.api.ila.ILAProbeValues(bit_width, trigger_value, capture_value, radix=<ILAProbeRadix.BIN: 0>)[source]¶

A compare value consists of a pair: <operator> and <value> <value> may be of type int or binary/hex string of the correct bit_width. Hex values start with a ‘0x’ prefix.

An empty list is a don’t-care value.

Example: Test for LSB is ‘0’ on a 4-bit probe.
[‘==’, ‘XXX0’]

Example: Range check, assuming the global Trigger Condition is ILATriggerCondition.AND:
[‘>=’, ‘0x3’, ‘<=’, ‘0x10’]

Example: Range check, assuming the global Trigger Condition is ILATriggerCondition.AND:
[‘>=’, 3, ‘<=’, 10]

Example: Test equal to any of 3 numbers, assuming the global Trigger Condition is ILATriggerCondition.OR:
[‘==’, ‘0011’, ‘==’, ‘0111’, ‘==’, ‘1111’]

Example: 4-bit dont-care value.
[‘==’, ‘XXXX’]

Example: Dont-care value, written as an empty list.
[]

bit_width: int¶: Number of probe bits.

trigger_value: ]¶: Trigger compare values, in a list.

capture_value: ]¶: Basic capture compare value. A two item list with [<operator>, <value>]

radix: chipscopy.api.ila.ila_probe.ILAProbeRadix = 0¶: Display radix, when exporting waveform data.

ILAStaticInfo¶

class chipscopy.api.ila.ILAStaticInfo(data_depth, data_width, has_advanced_trigger, has_capture_control, has_trig_in, has_trig_out, match_unit_count, port_count)[source]¶

Feature set and dimensions of the ILA core.

data_depth: int¶: Data depth in samples.

data_width: int¶: Waveform data sample width, in bits.

has_advanced_trigger: bool¶: ILA has advanced trigger mode.

has_capture_control: bool¶: ILA has basic capture control.

has_trig_in: bool¶: ILA has TRIG-IN port.

has_trig_out: bool¶: ILA has TRIG-OUT port.

match_unit_count: int¶: Total number of probe compare match units.

port_count: int¶: Number of probe ports.

ILAStatus¶

class chipscopy.api.ila.ILAStatus(capture_state, is_armed, is_full, samples_captured, windows_captured, samples_requested, windows_requested, trigger_position_requested)[source]¶

Dynamic status of ILA capture controller

capture_state: chipscopy.api.ila.ila_capture.ILAState¶: Capture state. See ILAState

is_armed: bool¶: Trigger is armed.

is_full: bool¶: Data buffer is full.

samples_captured: int¶: Number of samples captured in current data window.

windows_captured: int¶: Number of fully captured data windows.

samples_requested: int¶: Number of samples per window, as requested when was ILA armed.

windows_requested: int¶: Number of windows, as requested when ILA was armed.

trigger_position_requested: int¶: Trigger position, as requested when ILA was armed.

ILAState (enum)¶

class chipscopy.api.ila.ILAState(value)[source]¶

ILA State Transitions:: IDLE -> PRE_TRIGGER -> TRIGGER -> POST_TRIGGER -> IDLE

Enum Value	Description
IDLE	Not armed.
PRE_TRIGGER	Capturing pre-trigger samples.
TRIGGER	Waiting for trigger.
POST_TRIGGER	Capturing post-trigger samples.

ILATriggerCondition (enum)¶

class chipscopy.api.ila.ILATriggerCondition(value)[source]¶

For Trigger Condition, set trigger mode including basic trigger global boolean operator of participating probe comparators

Enum Value	Description
AND	Basic Trigger mode: AND probe comparators.
OR	Basic Trigger mode: OR probe comparators.
NAND	Basic Trigger mode: NAND probe comparators.
NOR	Basic Trigger mode: NOR probe comparators.
IMMEDIATELY	Trigger now.
TRIGGER_STATE_MACHINE	Advanced Trigger mode: TSM file decides when to trigger.

ILATrigInMode (enum)¶

class chipscopy.api.ila.ILATrigInMode(value)[source]¶

Enum Value	Description
DISABLED	No TRIG-IN port use.
TRIG_IN_ONLY	Trigger only on TRIG-IN port.
TRIGGER_OR_TRIG_IN	Trigger on basic/trigger mode or on TRIG-IN port.

ILATrigOutMode (enum)¶

class chipscopy.api.ila.ILATrigOutMode(value)[source]¶

Choices for Trig-Out port.

Enum Value	Description
DISABLED	Disables the TRIG_OUT port.
TRIGGER_ONLY	Result of the basic/advanced trigger condition.
TRIG_IN_ONLY	Propagates the TRIG_IN port to the TRIG_OUT port.
TRIGGER_OR_TRIG_IN	OR-ing of the basic/advanced trigger and TRIG_IN port.

ILAWaveform¶

class chipscopy.api.ila.ILAWaveform(width, sample_count, trigger_position, window_size, probes, data)[source]¶

Waveform data, with data probe information.

width: int¶: Sample bit width.

sample_count: int¶: Number of data samples.

trigger_position: [<class ‘int’>]¶: Trigger position index, for each data window.

window_size: int¶: Number of samples in a window.

probes: {<class ‘str’>, <class ‘chipscopy.api.ila.ila_waveform.ILAWaveformProbe’>}¶: Dict of {probe name, waveform probe} See ILAWaveformProbe

data: bytearray¶

Waveform data.

Samples are aligned on byte boundary.

This formula can be used to read a bit from the data:

bytes_per_sample = len(data) // sample_count

def get_bit_value(data: bytearray, bytes_per_sample: int,
                  sample_index: int, data_bit_index: int) -> bool:
    byte_value = data[sample_index * bytes_per_sample + data_bit_index // 8]
    mask = 1 << (data_bit_index & 0x7)
    return (byte_value & mask) != 0

ILAWaveformProbe¶

class chipscopy.api.ila.ILAWaveformProbe(name, map, map_range, is_bus, bus_left_index=None, bus_right_index=None, display_radix=<ILAProbeRadix.HEX: 2>)[source]¶

Probe location in a data sample.

name: str¶: Name of probe.

map: str¶: Location string

map_range: [<class ‘chipscopy.api.ila.ila_probe.ILABitRange’>]¶: List of bit ranges. See ILABitRange

is_bus: bool¶: True for bus probes

bus_left_index: Optional[int] = None¶: Bus left index. E.g. 5 in probe counter[5:0]

bus_right_index: Optional[int] = None¶: Bus right index. E.g. 0 in probe counter[5:0]

display_radix: chipscopy.api.ila.ila_probe.ILAProbeRadix = 2¶: Display radix, when exporting waveform data. Default is ILAProbeRadix.HEX