ubb-la/README: brief description of ubb-la

ubb-la/README

@@ -0,0 +1,90 @@
+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.
+
+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.
+
+
+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