Integrated Logic Analyzers

Torii ILA has two primary ILA modules, the IntegratedLogicAnalyzer and the StreamILA.

IntegratedLogicAnalyzer is a very simple ILA capable of capturing samples from a Torii design and exposes a simple interface for accessing the sample memory.

StreamILA wraps the IntegratedLogicAnalyzer in a stream API that allows for the USB an UART ILA modules to ingest the data in a streaming way.

class torii_ila.ila.IntegratedLogicAnalyzer(*, signals=[], sample_depth=32, sampling_domain='sync', sample_rate=50000000.0, prologue_samples=1)

A simple Integrated Logic Analyzer for Torii.

It exposes a very straight forward interface that can be used to build more capable ILAs, for example the StreamILA is built on this.

Parameters:

  • signals (Iterable[torii.Signal]) – The signals to capture with the ILA. (default: list())

  • sample_depth (int) – Number of samples we wish to capture. (default: 32)

  • sampling_domain (str) – The clock domain the ILA sampling will take place on. (default: sync)

  • sample_rate (float) – The outwards facing sample rate used for formatting output. This should be tied to the sampling_domain’s frequency if possible. (default: 50e6 i.e 50MHz)

  • prologue_samples (int) – The number of samples to capture before the trigger. (default: 1)

Attributes:

  • sample_width (int) – The width of the sample vector in bits.

  • sample_depth (int) – The depth of the ILA sample buffer in samples.

  • sample_rate (float) – The outwards facing sample rate used for formatting output

  • sample_period (float) – The period of time between samples in nanoseconds, equivalent to 1 / sample_rate.

  • prologue_samples (int) – The number of samples to retain prior to the ILA trigger signal going high.

  • bits_per_sample (int) – The nearest power of 2 number of bits per sample.

  • bytes_per_sample (int) – The number of whole bytes per sample.

  • trigger (Signal, in) – ILA Sample start trigger strobe.

  • sampling (Signal, out) – Indicates when the ILA is actively sampling.

  • complete (Signal, out) – Indicates when sampling is completed and the buffer is full.

  • sample_index (Signal, in) – The sample the ILA will output.

  • sample_capture (Signal, out) – The sample corresponding to the sample index.

add_signal(sig)

Add a signal to the ILA capture list.

This can be used to internal module signals to the ILA, or add signals after construction.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

sig (torii.Signal) – The signal to add to the ILA capture list.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

append_signals(signals)

Like add_signal() but allows for adding an array of signals to the ILA capture list.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

signals (Iterable[torii.Signal]) – The list of additional signals to capture with the ILA.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

add_fsm(fsm)

Add a Torii FSM state to the ILA.

with m.FSM(name = 'Thing') as fsm:
        ila.add_fsm(fsm)

This is effectively equivalent to:

with m.FSM(name = 'Thing') as fsm:
        ila.add_signal(fsm.state)

Note

The FSM you add to the ILA should be named, as to prevent name collisions.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

fsm (torii.hdl.dsl.FSM) – The FSM to add to the ILA.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

class torii_ila.ila.StreamILA(*, signals=[], sample_depth=32, sampling_domain='sync', sample_rate=50000000.0, prologue_samples=1, output_domain=None)

A simple implementation of a stream-based ILA for use in the the UART and USB ILA’s based on the Torii torii.lib.stream.simple.StreamInterface

Parameters:

  • signals (Iterable[torii.Signal]) – The signals to capture with the ILA. (default: list())

  • sample_depth (int) – Number of samples we wish to capture. (default: 32)

  • sampling_domain (str) – The clock domain the ILA sampling will take place on. (default: ‘sync’)

  • output_domain (str | None) – The clock domain the ILA stream will output on. If None it will be the same as sampling_domain (default: None)

  • sample_rate (float) – The outwards facing sample rate used for formatting output. This should be tied to the sampling_domain’s frequency if possible. (default: 50e6 i.e 50MHz)

  • prologue_samples (int) – The number of samples to capture before the trigger. (default: 1)

Attributes:

  • domain (str) – The domain the ILA is sampling on.

  • ila (IntegratedLogicAnalyzer) – The inner ILA module used for actually ingesting the sample data.

  • sample_width (int) – The width of the sample vector in bits.

  • sample_depth (int) – The depth of the ILA sample buffer in samples.

  • sample_rate (float) – The outwards facing sample rate used for formatting output

  • sample_period (float) – The period of time between samples in nanoseconds, equivalent to 1 / sample_rate.

  • bits_per_sample (int) – The nearest power of 2 number of bits per sample.

  • bytes_per_sample (int) – The number of whole bytes per sample.

  • trigger (Signal, in) – ILA Sample start trigger strobe.

  • sampling (Signal, out) – Indicates when the ILA is actively sampling.

  • complete (Signal, out) – Indicates when sampling is completed and the buffer is full.

  • stream (StreamInterface) – The output stream of ILA samples.

add_signal(sig)

Add a signal to the ILA capture list.

This can be used to internal module signals to the ILA, or add signals after construction.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

sig (torii.Signal) – The signal to add to the ILA capture list.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

append_signals(signals)

Like add_signal() but allows for adding an array of signals to the ILA capture list.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

signals (Iterable[torii.Signal]) – The list of additional signals to capture with the ILA.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

add_fsm(fsm)

Add a Torii FSM state to the ILA.

with m.FSM(name = 'Thing') as fsm:
        ila.add_fsm(fsm)

This is effectively equivalent to:

with m.FSM(name = 'Thing') as fsm:
        ila.add_signal(fsm.state)

Note

The FSM you add to the ILA should be named, as to prevent name collisions.

Note

This method must not be called post elaboration, as we are unable to adjust the sample memory size after is it made concrete.

Parameters:

fsm (torii.hdl.dsl.FSM) – The FSM to add to the ILA.

Raises:

RuntimeError – If called during the elaboration of the ILA module

Return type:

None

These are used in conjunction with a backhaul interface to extract data off the device and on to the host system.