ubb-patgen/README: brief description how ubb-patgen works

ubb-patgen/README

@@ -0,0 +1,144 @@
+UBB pattern generator
+=====================
+
+ubb-patgen uses the MMC controller in the Ben Nanonote to send a
+digital pattern on the DATx lines of UBB. All four DATx lines can
+be used. The maximum output rate is 56 MHz, the maximum pattern
+size is 8128 nibbles.
+
+ubb-patgen can also output a clock of arbitrary duration on the
+CLK signal.
+
+The frequencies available for the pattern and the clock signal
+range from 41 kHz to 56 MHz. A map can be found here:
+http://downloads.qi-hardware.com/people/werner/ubb/ben-mmc-clk.png
+
+
+Frequency list
+--------------
+
+# ubb-patgen
+
+shows the available frequencies in ascending order and the
+corresponding MMC clock divider and bus clock tap settings.
+
+# ubb-patgen -q
+
+does the same but shows only the frequencies (in Hz) as
+floating-point numbers.
+
+
+Frequency selection
+-------------------
+
+# ubb-patgen -f 17000000
+# ubb-patgen -f 17M
+# ubb-patgen -f 17MHz
+
+all look for the available frequency closest to 17 MHz and print
+its value in Hz.
+
+Appending a + limits the search to frequencies greater than or
+equal to the specified value. Similarly, - searches for
+frequencies that don't exceed the specified value. Examples:
+
+# ubb-patgen -f 10MHz
+9882352.941176
+# ubb-patgen -f 10MHz+
+10500000.000000
+
+# ubb-patgen -f 15M
+15272727.272727
+# ubb-patgen -f 15M-
+14000000.000000
+
+Note that this form of invocation only searches the frequency
+table but does not produce any output on UBB.
+
+
+Clock output
+------------
+
+# ubb-patgen -c
+
+outputs a clock on CLK. The default is 1 MHz and can be changed
+with the option -f.
+
+ubb-patgen exits and leaves the clock running. To wait for a
+while and clean up on exit, add the delay in seconds, e.g.:
+
+# ubb-patgen -f 500kHz -c 10
+
+To stop the MMC bus clock, run
+
+# ubb-patgen -c 0
+
+ubb-patgen warns if the selected frequency does not match the
+requested frequency, e.g.,
+
+# ubb-patgen -f 100kHz -c
+bus clk = 100.962 kHz (+0.96%)
+
+This warning can be suppressed with the option -q.
+
+
+Pattern output
+--------------
+
+# ubb-patgen 0110
+
+first sets the DATx lines to 0, then outputs a 1 bit on DAT0 for
+two clock cycles, and returns DAT0 to zero.
+
+Each digit is a nibble representing the four DATx lines, with DAT0
+having the value 1, DAT1 2, DAT2 4, and DAT3 8.
+
+The repetition of a nibble can also be expressed by following it
+with the number of repetitions in curly braces, e.g.,
+
+# ubb-patgen 01{2}0
+
+The options -f and -q work as usual.
+
+The clock is normally not output but can be activated with the
+option -C. Note that the clock output is not continuous in this
+case.
+
+The pattern can be read from a file. All whitespace is ignored
+and so are comments beginning with #:
+
+# cat <<EOF >pattern-file
+1		# idle state is high
+# send two characters in RS232 format
+0 00010010 1	# "H"
+0 10010110 1	# "i"
+1		# return to idle (high)
+EOF
+# ubb-patgen -f 115.2k pattern-file
+
+If a file with the same name as a pattern exists, ubb-patgen will
+try to load that file. This can be prevented with the option -p.
+
+If only some of the DATx lines should be used for pattern output,
+the option -m MASK can be used to leave the unused lines in their
+previous state. MASK is a value in C syntax. Only lines whose bit
+is set are used for pattern output.
+
+
+External trigger
+----------------
+
+ubb-patgen normally sends the pattern immediately. This can be
+delayed by waiting for an external trigger with the option -t.
+
+# ubb-patgen -t 0 0f0
+
+configures CLK as an input, waits for it to become zero, and then
+outputs the 010 pattern. If CLK is already zero, ubb-patgen will
+send the pattern immediately.
+
+Likewise, -t 1 waits for CLK to become 1. -t cannot be used with
+the -C option.
+
+ubb-patgen usually starts the pattern about 2 us after the
+trigger, but this can be delayed by other system activity.