ben-blinkenlights/ubb-patgen/README

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.