Date:2012-12-31 13:44:05 (11 years 2 months ago)
Author:Werner Almesberger
Commit:9d298216e7989a48fcab9f353b88884a4904d144
Message:libubb/README: document GPIO and register access

Files: libubb/README (1 diff)

Change Details

libubb/README
1libubb - Helper functions for the Universal Breakout Board
2==========================================================
3
4libubb gives convenient access to the GPIOs accessible via UBB [1].
5It also includes additional components that implement more advanced
6functions, such as a software UART, or giving access to additional
7CPU registers.
8
9[1] http://en.qi-hardware.com/wiki/UBB
10
11
12Installation, compiling, and linking
13------------------------------------
14
15The ubb/ directory under include/ should be placed in the
16cross-compiler's include path and libubb.a goes into the
17cross-linker's library search path.
18
19Alternatively, the paths can be added when compiling or linking,
20with -I<wherever>/libubb/include or -L<wherever>/libubb
21
22When linking, add -lubb to include the library.
23
24
25Skeleton program
26----------------
27
28This program fragment illustrates the key elements of basic UBB
29use:
30
31   1 #include <ubb/ubb.h>
32   2
33   3 ...
34   4 #define MY_FOO UBB_CMD
35   5 #define MY_BAR UBB_DAT2
36   6 ...
37   7
38   8 if (ubb_open(0) < 0) {
39   9 perror("ubb_open");
40  10 exit(1);
41  11 }
42  12 ...
43  13 ubb_power(1);
44  14 ...
45  15 CLR(MY_FOO);
46  16 OUT(MY_FOO);
47  17
48  18 IN(MY_BAR);
49  19
50  20 while (PIN(MY_BAR)) {
51  21 SET(MY_FOO);
52  22 CLR(MY_FOO);
53  23 }
54  24 ...
55  25 ubb_close(0);
56
57Including ubb/ubb.h at line 1 provides all the basic definitions.
58
59Lines 4 and 5 define project-specific names for the IO pins.
60libubb provides the macros UBB_CMD, UBB_CLK, UBB_DAT0, UBB_DAT1,
61UBB_DAT2, and UBB_DAT3 for the signals available on the 8:10 card
62connector. It also provides UBB_nPWR for the (inverted) signal
63that controls power to the card.
64
65Lines 8 to 11: To get access to UBB and to set the GPIOs to a known
66state, call ubb_open. The default settings are:
67
68  UBB_nPWR GPIO, output
69  all others GPIO, input, pull-up enabled
70
71ubb_open takes as argument a list of signals that should not be
72changed. For example, if MY_FOO and MY_BAR had a configuration
73state worth preserving already before running the program, one
74would use ubb_open(MY_FOO | MY_BAR).
75
76Note that all IO pins except UBB_CLK (and UBB_nPWR) have 10 kOhm
77pull-ups soldered to them inside the Ben. Only UBB_CLK can
78therefore be configured to have no pull-up at all.
79
80If ubb_open fails for some reason, it returns a negative value
81and sets "errno". If it succeeds, it returns zero.
82
83Line 13: to make the Ben provide 3.3 V to UBB, call ubb_power(1).
84ubb_power(0) turns off power. ubb_power(1) also adds a delay of
8510 ms to let the card pre-charge any capacitors through the IO
86pins. This is often necessary to limit the inrush current when
87switching on power. If the inrush current is too large, it may
88compromise the Ben's own voltage supply and cause the Ben to
89freeze.
90
91Lines 15 to 23: the convenience macros IN and OUT set the
92respective pins to be inputs or outputs. The argument is a
93bitmask of the pins to change. SET and CLR set the output to "1"
94or "0" respectively. PIN returns 1 if any of the specified pins
95is "1", 0 if they are all "0".
96
97Line 25: To close UBB and restore the pins to their original
98setting, call ubb_close. Like ubb_open, ubb_close accepts a
99mask of pins that should be left as they are.
100
101
102Low-level GPIO control
103----------------------
104
105include/ubb/regbase.h defines the registers that control the
106GPIOs. Settable items generally have three registers: "FOO" to
107read the current setting, "FOOS" to set bits, and "FOOC" to
108clear bits.
109
110When writing to the FOOS or FOOC registers, a 1 sets or clears
111the respective bit while a 0 leaves it unchanged.
112
113For example, the UBB_CLK pull-up would be turned off with
114
115    PDPULLS = UBB_CLK;
116
117
118Access to timers, interrupts, etc.
119----------------------------------
120
121include/ubb/regs4740.h gives access to even more registers.
122Please consult the JZ4740 Programming Manual for details on
123their use.

Archive Download the corresponding diff file

Branches:
master



interactive