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.


Competing users of the 8:10 card interface
------------------------------------------

Other programs and kernel drivers may compete for access to the
8:10 card interface. The most common conflicts are with the
kernel drivers for MMC (uSD card) and AT86RF230 (atben).

OpenWRT and JLime start with the MMC driver loaded and active.

To detach the MMC driver, run

# echo jz4740-mmc.0 >/sys/bus/platform/drivers/jz4740-mmc/unbind

To re-attach the MMC driver, run

# echo jz4740-mmc.0 >/sys/bus/platform/drivers/jz4740-mmc/bind

To detach the AT86RF230 driver, run

# cd /sys/bus/spi/drivers/at86rf230
# echo spi*.0 >unbind

libubb allows multiple programs to open UBB at the same time,
leaving it up to these programs to coordinate their access.