FreeCalypso > hg > freecalypso-citrine
annotate doc/Compiling @ 40:b56928f8c001
doc/Firmware_Architecture: stale links to docs updated
to new FTP and web locations
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Sun, 07 May 2017 16:20:07 +0000 |
parents | 51e1a3b213a3 |
children |
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. |