libubb/README: document GPIO and register access

libubb/README

@@ -0,0 +1,123 @@
+libubb - Helper functions for the Universal Breakout Board
+==========================================================
+
+libubb gives convenient access to the GPIOs accessible via UBB [1].
+It also includes additional components that implement more advanced
+functions, such as a software UART, or giving access to additional
+CPU registers.
+
+[1] http://en.qi-hardware.com/wiki/UBB
+
+
+Installation, compiling, and linking
+------------------------------------
+
+The ubb/ directory under include/ should be placed in the
+cross-compiler's include path and libubb.a goes into the
+cross-linker's library search path.
+
+Alternatively, the paths can be added when compiling or linking,
+with -I<wherever>/libubb/include or -L<wherever>/libubb
+
+When linking, add -lubb to include the library.
+
+
+Skeleton program
+----------------
+
+This program fragment illustrates the key elements of basic UBB
+use:
+
+   1	#include <ubb/ubb.h>
+   2
+   3	...
+   4	#define	MY_FOO	UBB_CMD
+   5	#define	MY_BAR	UBB_DAT2
+   6	...
+   7
+   8		if (ubb_open(0) < 0) {
+   9			perror("ubb_open");
+  10			exit(1);
+  11		}
+  12		...
+  13		ubb_power(1);
+  14		...
+  15		CLR(MY_FOO);
+  16		OUT(MY_FOO);
+  17
+  18		IN(MY_BAR);
+  19
+  20		while (PIN(MY_BAR)) {
+  21			SET(MY_FOO);
+  22			CLR(MY_FOO);
+  23		}
+  24		...
+  25		ubb_close(0);
+
+Including ubb/ubb.h at line 1 provides all the basic definitions.
+
+Lines 4 and 5 define project-specific names for the IO pins.
+libubb provides the macros UBB_CMD, UBB_CLK, UBB_DAT0, UBB_DAT1,
+UBB_DAT2, and UBB_DAT3 for the signals available on the 8:10 card
+connector. It also provides UBB_nPWR for the (inverted) signal
+that controls power to the card.
+
+Lines 8 to 11: To get access to UBB and to set the GPIOs to a known
+state, call ubb_open. The default settings are:
+
+  UBB_nPWR	GPIO, output
+  all others	GPIO, input, pull-up enabled
+
+ubb_open takes as argument a list of signals that should not be
+changed. For example, if MY_FOO and MY_BAR had a configuration
+state worth preserving already before running the program, one
+would use ubb_open(MY_FOO | MY_BAR).
+
+Note that all IO pins except UBB_CLK (and UBB_nPWR) have 10 kOhm
+pull-ups soldered to them inside the Ben. Only UBB_CLK can
+therefore be configured to have no pull-up at all.
+
+If ubb_open fails for some reason, it returns a negative value
+and sets "errno". If it succeeds, it returns zero.
+
+Line 13: to make the Ben provide 3.3 V to UBB, call ubb_power(1).
+ubb_power(0) turns off power. ubb_power(1) also adds a delay of
+10 ms to let the card pre-charge any capacitors through the IO
+pins. This is often necessary to limit the inrush current when
+switching on power. If the inrush current is too large, it may
+compromise the Ben's own voltage supply and cause the Ben to
+freeze.
+
+Lines 15 to 23: the convenience macros IN and OUT set the
+respective pins to be inputs or outputs. The argument is a
+bitmask of the pins to change. SET and CLR set the output to "1"
+or "0" respectively. PIN returns 1 if any of the specified pins
+is "1", 0 if they are all "0".
+
+Line 25: To close UBB and restore the pins to their original
+setting, call ubb_close. Like ubb_open, ubb_close accepts a
+mask of pins that should be left as they are.
+
+
+Low-level GPIO control
+----------------------
+
+include/ubb/regbase.h defines the registers that control the
+GPIOs. Settable items generally have three registers: "FOO" to
+read the current setting, "FOOS" to set bits, and "FOOC" to
+clear bits.
+
+When writing to the FOOS or FOOC registers, a 1 sets or clears
+the respective bit while a 0 leaves it unchanged.
+
+For example, the UBB_CLK pull-up would be turned off with
+
+	PDPULLS = UBB_CLK;
+
+
+Access to timers, interrupts, etc.
+----------------------------------
+
+include/ubb/regs4740.h gives access to even more registers.
+Please consult the JZ4740 Programming Manual for details on
+their use.