FreeCalypso > hg > freecalypso-sw

comparison README @ 1000:36e3f6bf0156

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
top README: just describe what each subtree is for, and refer to other docs
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Sun, 06 Mar 2016 21:38:21 +0000
parents e8bdd3d0c4c2
children 405b5469abc4
comparison
equal deleted inserted replaced
999:0ee75fdf082f 1000:36e3f6bf0156
1 What this project is about 1 This source repository is a top-level container for all of the main software
2 ========================== 2 and firmware components developed in the FreeCalypso project.
3
4 You are looking at the software/firmware subproject of FreeCalypso. The goal
5 of this subproject is to produce a fully functional firmware version for the
6 Calypso GSM baseband chipset from Texas Instruments that is fully controlled
7 by We the People (recompilation with a free compiler from full source code
8 which is freely published and maintained by us, as opposed to a frozen
9 impenetrable binary blob from some long-defunct vendor) and which we can use in
10 two ways:
11
12 a) replace the original proprietary firmware of certain pre-existing phone
13 models based on this chipset, thereby turning these historical devices into
14 libre phones;
15
16 b) use as the official firmware for new phones and modems which we design and
17 build ourselves, using the same Calypso chipset.
18
19 Origin of the source
20 ====================
21
22 We are *not* attempting to reimplement a fully functional and practically
23 usable GSM protocol stack from scratch in this project - such a task would be
24 far beyond the capabilities of our very small and woefully underfunded team,
25 and in the opinion of project leader Space Falcon, such a from-scratch
26 reimplementation would be an egregious and morally impermissible waste of human
27 talent. Instead, we are using the L1 and G23M protocol stack code for TI's
28 LoCosto chipset that was included in the chipset.zip public release made by the
29 CEO of Peek, Inc. (the Peek mobile email device company) as that company went
30 under, and porting it from the LoCosto-based Peek platform to our Calypso target
31 devices of interest.
32
33 Where we came from
34 ==================
35
36 Just because we are reusing most components from TI's original firmware releases
37 does not mean that our project is trivial or devoid of our own original work.
38 When we started the GSM firmware subproject in the fall of 2013 (that was when
39 we obtained the last missing piece of required starting source material), the
40 available TI firmware sources consisted of:
41
42 * A TCS211 semi-src deliverable that could be compiled into a working fw image
43 for the GSM modem in the Neo Freerunner. While this version includes
44 recompilable source for most of the supporting components, the actual GSM
45 protocol stack is 100% linkable binary libraries sans source. These binary
46 object components necessitate the use of TI's proprietary compiler tools to
47 rebuild the fw. The build environment is set up for Windows only.
48
49 * The source from Peek (TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip) for TI's
50 I-Sample board with the LoCosto chipset. Mostly real source (about 95%), but
51 still has a few required components which exist only as linkable binary
52 libraries sans source. The use of TI's proprietary compiler tools is still
53 required for the same reason, and the build environment is set up to use a
54 bunch of other Windows-only tools.
55
56 * The Peek Linux project (svn.peeklinux.com) replaced the Windows-based build
57 system with a Linux-based one, but the binary-only libraries are still there,
58 hence the compiler toolchain is still the same proprietary one from TI.
59
60 The above sorry state of affairs (absolute dependency on binary object code
61 sans source, on proprietary compiler toolchains and on Windows) was very far
62 from what we sought to accomplish (compilation from full source with gcc under
63 GNU/Linux or other free Unix), hence we set out on a firmware reintegration
64 project that took a year and a half.
65
66 What we've done
67 ===============
68
69 By a process of painstaking reintegration piece by piece, we have put together
70 our own firmware suite for the Calypso that builds into a flashable or
71 RAM-loadable image and has the following essential features/qualities/
72 attributes:
73
74 * Targets Calypso rather than LoCosto. This decision is somewhat controversial,
75 i.e., one could make a valid argument that we should have gone with LoCosto
76 instead. But in our defense, we already have several pre-existing devices
77 with the Calypso chipset on which we would like to run libre firmware; as for
78 LoCosto, we don't have a hardware platform to use as a bring-up vehicle, and
79 when we started the project, we were missing a copy of some of TI's Windows
80 tools for LoCosto.
81
82 * The overall architecture of our firmware (what components are included) mimics
83 that of TCS211 (TI's official fw for Calypso platforms for which we only have
84 a semi-src): e.g., we use real RiViera rather than RV emulation atop GPF.
85 In the case of RiViera, FFS and other components for which our copy of TCS211
86 has real source, we have used that TCS211 source.
87
88 * L1 and all of G23M (including ACI, CCD and AIM/SAP definitions) are the
89 version from the LoCosto source - which has an unfortunate quality of being
90 completely untested.
91
92 * Configured for a feature set matching TCS211, i.e., most of the newer features
93 appearing in TCS3.2 are *not* enabled. The GSM protocol stack is also
94 configured for the minimal voice+SMS feature set, i.e., CSD, fax and GPRS
95 haven't been integrated or enabled yet.
96
97 * Everything builds from full source with gcc, i.e., *nothing* is used in the
98 form of a precompiled binary object or library. Some parts of GPF, L1 and
99 system initialization code had to be reconstructed from disassembly of TCS211
100 binary objects, as no original or suitable substitute source could be found.
101
102 * The version of Nucleus we use comes from a non-TI source; all TI GSM fw
103 sources we found have their Nucleus in binary-only libs.
104
105 * To reiterate: our compiler is gcc, *not* TI's proprietary TMS470!
106
107 Current status (2015-06-30)
108 ===========================
109
110 Our current firmware can be built for two targets: Openmoko's Calypso modem
111 built into their GTA01 and GTA02 smartphones (target gtamodem) and the Pirelli
112 DP-L10 feature phone. The functionality is the same on both targets: a modem
113 or pseudo-modem controlled by AT commands (no local UI on the Pirelli), and
114 only the voice+SMS subset, i.e., no CSD, fax or GPRS yet. The firmware is able
115 to register successfully to a live commercial GSM network (using a legitimate
116 SIM of course), and SMS sending and receiving both work; all SIM interface
117 functions also work as far as we've tested them. But voice calls don't work
118 yet; making them work is our next task.
119
120 We have also produced some host tools for loading firmware into Calypso GSM
121 devices, for communicating with running firmwares over the RVTMUX interface,
122 and for manipulating TI's flash file system. See README.hosttools for the
123 details.
124
125 Source tree
126 ===========
127
128 The subtrees of this source tree are as follows: 3 The subtrees of this source tree are as follows:
129 4
130 gsm-fw The main FreeCalypso GSM firmware work, see above. 5 compal-flash-boot-for-fc
6 A patched version of Compal's flash boot code for Mot C11x/12x
7 and C139/140 families, modified to work with main fw images from
8 FreeCalypso subprojects. It is compatible with our own gsm-fw
9 and with tcs211-c139.
10
11 ffstools Here you will find tools for "in vitro" examination of FFS
12 (flash file system) images read out of TI-based GSM devices.
13 See doc/TIFFS-Overview for more information.
14
15 gsm-fw Our Calypso GSM firmware reconstruction and reintegration
16 attempt lives here; see doc/Firmware_Architecture and
17 doc/Firmware_Status for more information.
18
19 loadtools These tools allow you to load your own code into Calypso GSM
20 devices. Using these tools, you can load code into target
21 device IRAM or XRAM and run it there, as well as dump and load
22 flash. The operation of these tools is based on gaining
23 control of the target device either through the Calypso on-chip
24 boot ROM (on freedom-enabled devices), or through the
25 flash-resident boot code on the crippled Compal phones.
26
27 lcdemu fc-lcdemu is built here.
28
29 miscutil fc-rgbconv, fc-serterm and imei-luhn are built here.
30
31 rvinterf In common with TI's original fw, FreeCalypso GSM fw implements
32 the so-called RiViera serial MUX, which is a binary packet
33 protocol for multiplexing many kinds of debug and development
34 traffic over just one available physical serial port. This
35 rvinterf directory contains our suite of tools for connecting
36 to this RV serial interface, supporting both our own gsm-fw as
37 well as some existing proprietary firmwares to the extent to
38 which they are compatible.
131 39
132 target-utils This tree contains code that runs on Calypso targets, but is 40 target-utils This tree contains code that runs on Calypso targets, but is
133 not regular firmware (gsm-fw) or a part thereof. The two key 41 not regular firmware (gsm-fw) or a part thereof. The two key
134 components built in this tree are loadagent (needed for all 42 components built in this tree are loadagent (needed for all
135 targets) and compalstage (for Compal phones only), which need 43 targets) and compalstage (for Compal phones only), which need
136 to be installed on the user's host system in order for 44 to be installed on the user's host system in order for
137 loadtools (see README.hosttools) to do their job. 45 loadtools (see above) to do their job.
138
139 ffstools Tools that run on a Unix or GNU/Linux host; see README.hosttools
140 loadtools for the details.
141 miscutil
142 rvinterf
143 46
144 toolchain Scripts and patches for building the gcc+binutils toolchain 47 toolchain Scripts and patches for building the gcc+binutils toolchain
145 targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband 48 targeting ARM7, the CPU core of the Calypso GSM/GPRS baseband
146 processor. You'll need to build and install this toolchain 49 processor. You'll need to build and install this toolchain
147 first before you can build gsm-fw or target-utils. 50 first before you can build gsm-fw or target-utils.