ben-blinkenlights/ubb-la/README

UBB pattern capture
===================

ubb-la is the counterpart of ubb-patgen: it captures a pattern on DATx
and prints on standard output what it has received. The output format
is the same as the one used by ubb-patgen, i.e., hex digits with
repetitions indicated by {number}.

ubb-la is currently a proof of concept implementation and therefore
only provides the most basic functions.

Capture frequencies are the same as for ubb-patgen. The sample size is
fixed at 8008 samples.


Sample rate
-----------

The frequency in MHz is selected with the option -f. For example, this
would select 10.5 MHz:

# ubb-la -f 10.5
bus 10.5 MHz controller 168 MHz

Note that - unlike ubb-patgen - there are no SI prefixes or rounding
modes to select. ubb-la simply picks the frequency closest to the one
specified.

The option -F works like -f but also allows frequencies that may
exceed the hardware's capabilities. As a consequence, the MMC
controller may hang.

A list of available frequencies can be obtained with

# ubb-patgen -q

The default sample rate is 1 MHz.


Clock output
------------

The CLK line (CLK/TRIG) is usually configured as an input.  If the
option -C is present, ubb-la outputs the MMC bus clock instead.


Trigger
-------

Capture only starts after detection of a trigger. By default, ubb-la
triggers when the CLK/TRIG line changes.

The trigger pattern can be selected with the option -t pattern/mask,
where ubb-la triggers when  (pins & mask) == pattern

For example,

# ubb-la -t 2/3

would monitor the lines DAT0 and DAT1 and trigger when DAT0 is 0
while DAT1 is 1. In the pattern and mask, DAT0 has the value 1, DAT1
is 2, DAT2 is 4, DAT3 is 8, and CLK/TRIG is 16.

ubb-la turns off interrupts while waiting for a trigger. The only
ways to exit are either detection of a trigger or a button press on
the Ben's keyboard. In the latter case, ubb-la exits immediately and
does not capture any samples.

When the trigger is present, it takes roughly 550 +/- 250 ns plus one
sample time until the first sample is taken.


Graphical output
----------------

A graphical interface is available for exploration of a captured
pattern. This interface is invoked if the option -g is set. Note
that sample rate, trigger, etc., still have to be set up via the
command line. Example:

# ubb-la -f 12 -t 0/8 -g

In the GUI, the following keys are available:

  Left/Right	Pan the waveform left/right. With Shift, jump to the
		next change on any channel in the specified direction.
  Up/Down	Zoom in/out
  Space		Set the user origin (upward-facing green triangle)
		at the current position and display the time to
		the center position (downward-facing blue triangle).
		Pressing space again removes the user origin.
  Enter/Q	Quit


Known bugs
----------

At higher sample rates (observed at 42 and 56 MHz; not observed at
24 MHz), the first sample may have an incorrect value and should be
ignored.

Interrupting ubb-la while a capture is in progress could cause
memory corruption.

The passive ubb-la circuit loads the inputs such that they will only
work if there is a strong driver. In particular, signals held only by
a pull-up or pull-down resistor are likely to be compromised.

The respective resistive loads are:

Signal	To GND	To 3.3 V
	(max)	(max)
------------------------
DAT0	  1.1 k	 11 k
DAT1-3	 10 k	 10 k
TRIG	330 k	330 k