FreeCalypso > hg > freecalypso-tools

comparison doc/Compiling @ 3:6a029ad28212

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Compiling: updated for the split between freecalypso-tools and Citrine
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 11 Jun 2016 01:52:51 +0000
parents e7502631a0f9
children aa20bdae9e53
comparison
equal deleted inserted replaced
2:803e4f4a3db6 3:6a029ad28212
1 There are 3 parts to the complete FreeCalypso software suite which are built
2 independently of each other:
3
4 * The tools that run on a GNU/Linux PC or other host system are the most
5 straightforward: there is a top level Makefile (named Makefile.hosttools if
6 you looking at a development source snapshot, will be renamed to just
7 Makefile in packaged releases of the host tools) that coordinates building
8 and installing all of them.
9
10 * The gsm-fw tree, which will eventually become our main GSM firmware, needs to
11 be built with a GNU cross-compiler toolchain for ARM7. This firmware can be
12 built for several different target devices and with different feature
13 configurations, hence there is no singular build for it - it's more like the
14 Linux kernel in terms of its build configuration management.
15
16 * We also have a few utilities which need to be compiled to run on Calypso
17 targets, but which are not part of gsm-fw; they are gathered in the
18 target-utils tree. They are built with the same GNU toolchain for ARM7 as
19 gsm-fw, but don't have any fancy configuration system.
20
21 Building and installing FreeCalypso host tools 1 Building and installing FreeCalypso host tools
22 ============================================== 2 ==============================================
23 3
24 If you are working with a packaged FC host tools release, just run 'make', then 4 In order to compile and install our host tools, just run 'make', then
25 'make install' as root. If you are working with a development source snapshot, 5 'make install' as root.
26 do 'make -f Makefile.hosttools' instead.
27 6
28 The "standard" install directories are /usr/local/bin for binaries and 7 The "standard" install directories are /usr/local/bin for binaries and
29 /usr/local/share/freecalypso for helper files. If you need to change these 8 /usr/local/share/freecalypso for helper files. If you need to change these
30 paths to something else, you'll need to edit a bunch of individual component 9 paths to something else, you'll need to edit a bunch of individual component
31 Makefiles, and possibly also some source files like loadtools/defpath.c - 10 Makefiles, and possibly also some source files like loadtools/defpath.c -
52 Building and installing the ARM7 toolchain 31 Building and installing the ARM7 toolchain
53 ========================================== 32 ==========================================
54 33
55 The current "official" GNU ARM toolchain for FreeCalypso consists of 34 The current "official" GNU ARM toolchain for FreeCalypso consists of
56 binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and 35 binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and
57 build configuration options. Build it as follows: 36 build configuration options. This toolchain is used to compile target-utils in
37 this package as well as our separately-maintained Citrine firmware. Build it
38 as follows:
58 39
59 1. Download these 3 source tarballs for the standard GNU+newlib components: 40 1. Download these 3 source tarballs for the standard GNU+newlib components:
60 41
61 binutils-2.21.1a.tar.bz2 42 binutils-2.21.1a.tar.bz2
62 gcc-core-4.5.4.tar.bz2 43 gcc-core-4.5.4.tar.bz2
64 45
65 2. Run the build+install.sh script in the toolchain directory. Read the 46 2. Run the build+install.sh script in the toolchain directory. Read the
66 comments in the script first for the usage instructions. 47 comments in the script first for the usage instructions.
67 48
68 The toolchain thus built will need to be in your PATH before you can compile 49 The toolchain thus built will need to be in your PATH before you can compile
69 gsm-fw or target-utils. 50 target-utils or Citrine.
70 51
71 Please note: the toolchain that is prescribed for FreeCalypso as above is 52 Please note: the toolchain that is prescribed for FreeCalypso as above is
72 *believed* to be equivalent to the one used by OsmocomBB, but there are no 53 *believed* to be equivalent to the one used by OsmocomBB, but there are no
73 guarantees. Use any other toolchain at your own risk. 54 guarantees. Use any other toolchain at your own risk.
74 55
81 install these target binaries in /usr/local/share/freecalypso, which is where 62 install these target binaries in /usr/local/share/freecalypso, which is where
82 loadtools will look for them. 63 loadtools will look for them.
83 64
84 Run 'make all' in target-utils to build some other components that aren't 65 Run 'make all' in target-utils to build some other components that aren't
85 really needed. 66 really needed.
86
87 Compiling FreeCalypso GSM firmware
88 ==================================
89
90 The firmware in our gsm-fw tree can be built in many different configurations,
91 hence there is no singular build for it. The configuration choices consist of:
92
93 * Which target device the firmware should be built for: the target device
94 selection is made at compile time; do not attempt to take a firmware image
95 built for one target device and flash or fc-xram it into another!
96
97 * What functionality is to be included. As the FreeCalypso firmware subproject
98 moves forward, we gradually add chunks of functionality, slowly approaching
99 what each target device is ultimately capable of. However, each time we add
100 a new piece of functionality, the ability to build a firmware image that works
101 like before, without the newly added functionality, still remains. Each
102 feature to be included needs to be explicitly selected.
103
104 * Miscellaneous configuration: which Calypso UART should be used for what,
105 should the firmware use a real FFS (flash file system) in flash or a fake one
106 in RAM, etc.
107
108 The GSM firmware build configuration is set by way of an editable text file
109 named build.conf; the configuration and build procedure is as follows:
110
111 1. Look at the available repertoire of standard configurations under
112 gsm-fw/configs and choose which one you would like to use, either as-is or
113 as a basis for your own;
114
115 2. Copy the configuration you selected to build.conf in the gsm-fw directory;
116
117 3. Optionally edit it to taste - the configuration language is Bourne shell;
118
119 4. Run 'make' in the gsm-fw directory.
120
121 Depending on the configuration, either a flashable or a RAM-loadable image will
122 be built by default. A flashable image will appear in finlink/flashImage.bin;
123 these images are meant to be programmed with fc-loadtool's flash program-bin
124 command; the starting flash address at which the image needs to be programmed
125 depends on the target device - see target-specific notes. A RAM-loadable image
126 will appear in finlink/ramImage.srec; these images are meant to be loaded and
127 run with the fc-xram utility.
128
129 It is possible to build either a flashable or a RAM-loadable image, or both,
130 without changing build.conf: run 'make flashImage' or 'make ramImage' as
131 desired. (The compilation of each module from source into a .o and all
132 intermediate linking steps are agnostic to whether a flashImage or a ramImage
133 is being built, only the very final link step differs.) Any otherwise working
134 configuration can be built into a flashImage, even if it makes no logical sense
135 to do so, but the ability to build a ramImage for a given configuration depends
136 on the code image size (which in turn depends on the selected feature set) and
137 the amount of RAM available on the target in question: most Calypso GSM devices
138 have small RAM, enough to satisfy a GSM firmware's data space requirements, but
139 not enough to hold the entire firmware code in RAM as well. Please see target-
140 specific notes for more details.