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