Root/ubb-patgen/README

1UBB pattern generator
2=====================
3
4ubb-patgen uses the MMC controller in the Ben Nanonote to send a
5digital pattern on the DATx lines of UBB. All four DATx lines can
6be used. The maximum output rate is 56 MHz, the maximum pattern
7size is 8128 nibbles.
8
9ubb-patgen can also output a clock of arbitrary duration on the
10CLK signal.
11
12The frequencies available for the pattern and the clock signal
13range from 41 kHz to 56 MHz. A map can be found here:
14http://downloads.qi-hardware.com/people/werner/ubb/ben-mmc-clk.png
15
16
17Frequency list
18--------------
19
20# ubb-patgen
21
22shows the available frequencies in ascending order and the
23corresponding MMC clock divider and bus clock tap settings.
24
25# ubb-patgen -q
26
27does the same but shows only the frequencies (in Hz) as
28floating-point numbers.
29
30
31Frequency selection
32-------------------
33
34# ubb-patgen -f 17000000
35# ubb-patgen -f 17M
36# ubb-patgen -f 17MHz
37
38all look for the available frequency closest to 17 MHz and print
39its value in Hz.
40
41Appending a + limits the search to frequencies greater than or
42equal to the specified value. Similarly, - searches for
43frequencies that don't exceed the specified value. Examples:
44
45# ubb-patgen -f 10MHz
469882352.941176
47# ubb-patgen -f 10MHz+
4810500000.000000
49
50# ubb-patgen -f 15M
5115272727.272727
52# ubb-patgen -f 15M-
5314000000.000000
54
55Note that this form of invocation only searches the frequency
56table but does not produce any output on UBB.
57
58ubb-patgen warns if the selected frequency does not match the
59requested frequency, e.g.,
60
61# ubb-patgen -f 100kHz
62bus clk = 100.962 kHz (+0.96%)
63
64This warning can be suppressed with the option -q.
65
66The frequency can also be specified as the cycle time with the
67option -i:
68
69# ubb-patgen -i 10us
70
71The meaning of an appended + or - changes here, e.g., 10us+
72selects a slower clock (producing an interval of at least 10 us).
73
74The options -F and -I work like -f and -i but also allows
75frequencies that may exceed the hardware's capabilities. As a
76consequence, the MMC controller may hang.
77
78
79Clock output
80------------
81
82# ubb-patgen -c
83
84outputs a clock on CLK. The default is 1 MHz and can be changed
85with the option -f.
86
87ubb-patgen exits and leaves the clock running. To wait for a
88while and clean up on exit, add the delay in seconds, e.g.:
89
90# ubb-patgen -f 500kHz -c 10
91
92The delay can be followed by "m", "u", or "n" for the respective
93multiplier. Furthermore, it can end with an optional "s". Note
94that the minimum time ubb-patgen actually spends generating a
95clock will typically be in the order of several milliseconds.
96
97To stop the MMC bus clock, run
98
99# ubb-patgen -c 0
100
101
102Pattern output
103--------------
104
105# ubb-patgen 0110
106
107first sets the DATx lines to 0, then outputs a 1 bit on DAT0 for
108two clock cycles, and returns DAT0 to zero.
109
110Each digit is a nibble representing the four DATx lines, with DAT0
111having the value 1, DAT1 2, DAT2 4, and DAT3 8.
112
113The repetition of a nibble can also be expressed by following it
114with the number of repetitions in curly braces, e.g.,
115
116# ubb-patgen 01{2}0
117
118The options -f and -q work as usual.
119
120The clock is normally not output but can be activated with the
121option -C. Note that the clock output is not continuous in this
122case.
123
124The pattern can be read from a file. All whitespace is ignored
125and so are comments beginning with #:
126
127# cat <<EOF >pattern-file
1281 # idle state is high
129# send two characters in RS232 format
1300 00010010 1 # "H"
1310 10010110 1 # "i"
1320 10000100 1 # "!"
1330 10110000 1 # CR
1341 # return to idle (high)
135EOF
136# ubb-patgen -f 115.2k pattern-file
137
138If a file with the same name as a pattern exists, ubb-patgen will
139try to load that file. This can be prevented with the option -p.
140
141If only some of the DATx lines should be used for pattern output,
142the option -m MASK can be used to leave the unused lines in their
143previous state. MASK is a value in C syntax. Only lines whose bit
144is set are used for pattern output.
145
146
147External trigger
148----------------
149
150ubb-patgen normally sends the pattern immediately. This can be
151delayed by waiting for an external trigger with the option -t.
152
153# ubb-patgen -t 0 0f0
154
155configures CLK as an input, waits for it to become zero, and then
156outputs the 010 pattern. If CLK is already zero, ubb-patgen will
157send the pattern immediately.
158
159Likewise, -t 1 waits for CLK to become 1. -t cannot be used with
160the -C option.
161
162The trigger can also be a sequence, e.g., -t 01 would first wait
163for CLK to become zero (if it isn't already), then wait for it to
164become one.
165
166ubb-patgen usually starts the pattern about 2-10 us after the
167trigger, but this can be delayed by other system activity. An
168extra delay can be added with the option -w, e.g.,
169
170# ubb-patgen -t 0 -w 1s 010
171
172The trigger signal can be debounced with the option -d, e.g.,
173
174# ubb-patgen -t 0 -d 100us 0f0
175
176This accepts the trigger only after it has been zero for at least
177100 microseconds. If the trigger is a sequence, debouncing is
178applied at each step.
179
180
181Timeline details
182----------------
183
184timing.fig illustrates the various steps of pattern generation.
185A PDF of the diagram can be found here:
186
187http://downloads.qi-hardware.com/people/werner/ubb/patgen/timeline.pdf
188
189CLK is the clock output if selected with -C. DATx are the data
190lines, with the value of DAT0 shown. TRIG is the trigger input.
191Note that in real life, the TRIG/CLK line can only act either as
192trigger input or as clock output but not as both at the same time.
193
194The pattern we send is 0110110. We trigger on TRIG being low, with
195a debounce time of nominally about one pattern clock interval, and
196some post-trigger delay.
197
198After ubb-patgen starts, it first processes the command-line
199options and arguments, then initializes the pins. DATx are set to
200the value of the first pattern. Next, ubb-patgen sets up the MMC
201controller, makes it send a command, receives a pseudo-response,
202and begins sending copies of the first pattern on DATx. These
203copies are necessary to get past the start bit and to make the MMC
204controller drive DATx to known levels. Once this pattern has been
205sent, we switch DATx to GPIO.
206
207When this is done, ubb-patgen waits for the trigger. In this
208example, we first ignore a glitch and then detect a correct
209trigger value. Note that the effective debounce period is usually
210longer than specified, since other system activity can delay the
211sampling.
212
213Once ubb-patgen has triggered, it starts the DMA controller and
214thus begins sending the pattern. The first cycle (marked with a
215question mark) is an uncommanded repetition of the first pattern
216(apparently there is a buffer stage in the MMC controller)
217followed by the entire sequence, first to last pattern.
218
219At the end, several copies of the last pattern may be sent in
220order to reach the transfer size of the DMA controller (32 bytes).
221ubb-patgen then ensures that all data has left the MMC controller,
222switches DATx back to GPIO, and exits.
223

Archive Download this file

Branches:
master



interactive