ben-blinkenlights/ubb-patgen

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.

ubb-patgen warns if the selected frequency does not match the
requested frequency, e.g.,

# ubb-patgen -f 100kHz
bus clk = 100.962 kHz (+0.96%)

This warning can be suppressed with the option -q.

The frequency can also be specified as the cycle time with the
option -i:

# ubb-patgen -i 10us

The meaning of an appended + or - changes here, e.g., 10us+
selects a slower clock (producing an interval of at least 10 us).


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

The delay can be followed by "m", "u", or "n" for the respective
multiplier. Furthermore, it can end with an optional "s". Note
that the minimum time ubb-patgen actually spends generating a
clock will typically be in the order of several milliseconds.

To stop the MMC bus clock, run

# ubb-patgen -c 0


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"
0 10000100 1	# "!"
0 10110000 1	# CR
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.

The trigger can also be a sequence, e.g., -t 01 would first wait
for CLK to become zero (if it isn't already), then wait for it to
become one.

ubb-patgen usually starts the pattern about 2-10 us after the
trigger, but this can be delayed by other system activity. An
extra delay can be added with the option -w, e.g.,

# ubb-patgen -t 0 -w 1s 010

The trigger signal can be debounced with the option -d, e.g.,

# ubb-patgen -t 0 -d 100us 0f0

This accepts the trigger only after it has been zero for at least
100 microseconds. If the trigger is a sequence, debouncing is
applied at each step.