From 9d298216e7989a48fcab9f353b88884a4904d144 Mon Sep 17 00:00:00 2001 From: Werner Almesberger Date: Mon, 31 Dec 2012 09:44:05 -0300 Subject: [PATCH] libubb/README: document GPIO and register access --- libubb/README | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 libubb/README diff --git a/libubb/README b/libubb/README new file mode 100644 index 0000000..1ef7c83 --- /dev/null +++ b/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/libubb/include or -L/libubb + +When linking, add -lubb to include the library. + + +Skeleton program +---------------- + +This program fragment illustrates the key elements of basic UBB +use: + + 1 #include + 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.