UART-Based Integrated Logic Analyzer

This module provides the ILA as a streaming UART device, for use with the UART backhaul interface. It does this by wrapping the StreamILA and providing the output stream of the ILA capture data as a UART port using the Torii AsyncSerialTX

The baud rate for the UART stream is adjustable, but the UART stream itself is fixed to 8n1.

class torii_ila.uart.UARTIntegratedLogicAnalyzer(*, divisor, tx, rx, signals=[], sample_depth=32, sampling_domain='sync', sample_rate=50000000.0, prologue_samples=1)

A simple ILA that dumps sample memory down a UART pipe.

The configuration is 8n1 at the baud dictated by the divisor, which should be int(clk // baud) for the desired baud rate.

The output data from this ILA is an rCOBS encoded byte stream with a 0x00 EOF marker indicating the end of an ILA capture sample buffer.

Due to the way the UART works, each sample is byte-reversed, meaning the LSB is output first, then bytes up to the MSB. The UARTIntegratedLogicAnalyzerBackhaul deals with all of the implementation details, meaning the samples that come out from it are already rCOBS decoded and swizzled back into the correct order.

Parameters:

  • divisor (int) – The clock divisor needed on the output domain to reach the desired baudrate.

  • tx (Signal) – The UART Transmit signal to use.

  • rx (Signal) – The UART Receive signal to use.

  • 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:

  • 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.

  • idle (Signal, out) – Indicates the UART transmitter is sitting idle and is ready to send data.

get_backhaul(port)

Automatically create a UARTIntegratedLogicAnalyzerBackhaul from this ILA instance.

Parameters:

port (serial.Serial) – The serial port to use to ingest data from.

Returns:

The newly constructed backhaul interface or the already constructed instance.

Return type:

UARTIntegratedLogicAnalyzerBackhaul

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