ubbctl/README: short documentation

ubbctl/README

@@ -0,0 +1,64 @@
+ubbctl - Control UBB signals
+============================
+
+ubbctl queries the state of UBB signals and allows the user to change
+them. It can run in parallel with any other UBB users.
+
+
+Querying
+--------
+
+To query the UBB signals, run
+
+# ubbctl
+
+This will display something like this:
+
+nPWR=1 DAT2=F1 DAT3=F1 CMD=F1 CLK=Z1 DAT0=1 DAT1=0
+
+"0" means that the pin is driven low. "1" means that is it driven
+high. If the pin reads back as something different than what it is
+set to, this is indicated as "0!1" (pin is shorted to VDD) or "0!0"
+(pin is shorted to ground).
+
+"Z0" and "Z1" means that the pin is an input without internal
+pull-up (note however that all pins but nPWR and CLK) have external
+10 kOhm pull-ups) and that it reads back a low or high,
+respectively.
+
+"R0" and "R1" are like "Z0" and "Z1", except that the internal
+pull-up is enabled.
+
+"F0" and "F1" indicate that the pin configured as a function (i.e.,
+for the MMC controller) and does not operate as GPIO.
+
+ubbctl can run in continuous mode, in which it updates the status
+regularly (currently every 200 ms):
+
+# ubbctl -c
+
+To exit continuous mode kill the process, e.g., which Ctrl-C.
+
+
+Setting
+-------
+
+ubbctl can change the configuration of the UBB pins. The syntax is
+the same as the one used for the status display except that there
+are no readback values. E.g., nPWR=1 would disable power, CLK=R
+would configure CLK as input with pull-up, etc.
+
+A pin can be changed several times. For example, if the idle state
+of DAT0 is 0
+
+# ubbctl dat0=0
+
+then
+
+# ubbctl dat0=1 dat0=0
+
+would send a short positive pulse.
+
+ubbctl also recognizes the keywords ON and OFF to control power to
+the 8:10 interface. They're synonymous to nPWR=0 and nPWR=1,
+respectively.