FreeCalypso > hg > freecalypso-citrine

annotate doc/Compiling @ 28:cb00b90edaff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation write-ups imported from freecalypso-sw and updated for Citrine
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 12 Jun 2016 18:28:35 +0000
parents 51e1a3b213a3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
26
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 Building and installing the ARM7 toolchain
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ==========================================
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 Before you can compile Citrine, you first need to build and install the
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 necessary toolchain targeting ARM7, the CPU core in the Calypso. The current
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 "official" GNU ARM toolchain for FreeCalypso consists of binutils-2.21.1,
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and build
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 configuration options. All of the necessary bits can be downloaded here:
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/toolchain/
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 Please note: the toolchain that is prescribed for FreeCalypso as above is
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 *believed* to be equivalent to the one used by OsmocomBB, but there are no
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 guarantees. Use any other toolchain at your own risk.
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 Compiling FreeCalypso Citrine firmware
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 ======================================
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 Citrine firmware can be built in many different configurations, hence there is
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 no singular build for it. The configuration choices consist of:
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 * Which target device the firmware should be built for: the target device
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 selection is made at compile time; do not attempt to take a firmware image
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 built for one target device and flash or fc-xram it into another!
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 * What functionality is to be included. As the FreeCalypso firmware subproject
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 moves forward, we gradually add chunks of functionality, slowly approaching
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 what each target device is ultimately capable of. However, each time we add
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 a new piece of functionality, the ability to build a firmware image that works
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 like before, without the newly added functionality, still remains. Each
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 feature to be included needs to be explicitly selected.
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 * Miscellaneous configuration: which Calypso UART should be used for what,
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 should the firmware use a real FFS (flash file system) in flash or a fake one
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 in RAM, etc.
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 The GSM firmware build configuration is set by way of an editable text file
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 named build.conf; the configuration and build procedure is as follows:
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 1. Look at the available repertoire of standard configurations in the configs
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 directory and choose which one you would like to use, either as-is or as a
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 basis for your own;
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 2. Copy the configuration you selected to build.conf in the top level directory
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 of the source tree;
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 3. Optionally edit it to taste - the configuration language is Bourne shell;
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 4. Run 'make' in the top level directory.
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 Depending on the configuration, either a flashable or a RAM-loadable image will
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 be built by default. A flashable image will appear in finlink/flashImage.bin;
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 these images are meant to be programmed with fc-loadtool's flash program-bin
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 command; the starting flash address at which the image needs to be programmed
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 depends on the target device - see target-specific notes. A RAM-loadable image
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 will appear in finlink/ramImage.srec; these images are meant to be loaded and
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 run with the fc-xram utility.
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 It is possible to build either a flashable or a RAM-loadable image, or both,
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 without changing build.conf: run 'make flashImage' or 'make ramImage' as
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 desired. (The compilation of each module from source into a .o and all
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 intermediate linking steps are agnostic to whether a flashImage or a ramImage
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 is being built, only the very final link step differs.) Any otherwise working
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 configuration can be built into a flashImage, even if it makes no logical sense
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 to do so, but the ability to build a ramImage for a given configuration depends
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 on the code image size (which in turn depends on the selected feature set) and
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 the amount of RAM available on the target in question: most Calypso GSM devices
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 have small RAM, enough to satisfy a GSM firmware's data space requirements, but
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 not enough to hold the entire firmware code in RAM as well. Please see target-
51e1a3b213a3 started re-adding documentation
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 specific notes for more details.