FreeCalypso > hg > freecalypso-docs

annotate TCS211-fw-arch @ 65:153b517ccc7a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
FC-handset-spec section 1.7.2: make contrast with MIDI ringtone chips
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 15 Jun 2021 19:57:05 +0000
parents f5ddeacbe744
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 This document describes the architecture of TI's TCS211 firmware and that of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 our FreeCalypso Magnetite and Selenite firmwares which are based on it.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 What is TCS211, and why we use it as our reference
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 ==================================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 TI were in the business of making GSM baseband chipsets for about a decade
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 from the late 1990s up until 2009, and over that time span both their silicon
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 and their firmware architecture had evolved in many different ways. All of our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 work in the FreeCalypso family of projects is based on one fairly arbitrary
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 snapshot, a rather arbitrarily picked single point in that long evolutionary
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 line: we use the Calypso chipset as opposed to both the ones before and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 ones after, and we use TI's TCS211 firmware from 2007 as our golden reference,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 as opposed to other equally valid ways of architecturing the fw that came
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 before and after our arbitrarily picked snapshot.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 Q: Why do we use the Calypso chipset as opposed to LoCosto or E-Costo or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 whatever was TI's very last offering before they got out of that business?
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 A: Because that's what Openmoko used: their Neo FreeRunner aka GTA02 smartphones
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 were our primary hardware target for many years before we gathered the money
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 and the courage to build our own board-level hardware starting from just chips
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 bought on the Chinese surplus market.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 Q: Why do we use TI's TCS211 firmware from 2007 and its architecture as our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 golden reference, as opposed to any of the other infinitely many equally valid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 ways of architecturing a working firmware implementation for the same Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 chipset?
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 A: Because it works flawlessly, and is extremely stable as a commercial product.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 The firmware which Openmoko got from TI had only a tiny difference from TI's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 internal TCS211 mainline (TSPACT signal definitions in tpudrv12.h which are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 different between the quadband RFFE on TI's internal reference hw and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 triband one in FIC's commercial implementation), and with only a few additional
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 changes related to our use of a newer flash chip that wasn't supported back in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 TI's and Openmoko's days, this golden reference fw can run equally well on our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 own FCDEV3B.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 Relation between TCS211 and FreeCalypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 =======================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 The only "pure" TCS211 firmware we got is the one that has been salvaged from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 the ruins of Openmoko. To the best of our knowledge, it is the world's only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 surviving copy of any version of TCS211 - it is entirely possible that even TI
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 may not have it any more in any of their archives, given the length of time that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 has passed and the total lack of interest in this "ancient junk". In its pure
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 form, this world's sole surviving copy of TI's TCS211 fw is laden with blobs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 (many components exist only as binary object libraries with no corresponding
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 source), and it features a build system that is very thoroughly Windows-based.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 And to top it off, that configuration and build system has many critical
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 components which also exist only as compiled binaries (Windows executables or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 Java bytecode) with no corresponding source.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 We started by replacing the original configuration and build system of TCS211
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 with our own one that is Unix-based rather than Windows-based, and implemented
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 in Bourne shell with a few C helpers instead of XML, Java and Perl. The result
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 was named FreeCalypso Magnetite. At first we changed only the configuration
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 and build system, but kept all of the original TCS211 code, including all of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 the binary-only components. Then we deblobbed it gradually, replacing binary-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 only components with source, one component at a time. Where did we get the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 source for the pieces that came as binary objects with no corresponding source?
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 The answer is different for different components:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 * For GSM Layer 1 (a very critical and highly chipset-dependent component), we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 did a painstaking reconstruction which you can see in the tcs211-l1-reconst
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 repository. That world's last surviving copy of TCS211 which we got only had
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 *.c files censored out, while all of the original *.h files were preserved -
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 and thanks to the preserved configuration and build system, we also got all
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 of the original compilation lines including compiler options, -D definitions
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 and -I include paths. For most of the missing *.c files we got a "wrong"
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 version from the TCS3/LoCosto source. The reconstruction proceeded by taking
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 these "wrong version" *.c files, putting them one module (one *.c file) at a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 time into the TCS211 build environment, and massaging each individual *.c
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 file until it compiled into a perfect match to the original binary object.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 Thus we have reconstructed a full C source for the L1 component which for all
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 practical purposes can be treated as if it were the lost original source.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 * For some small pieces like the tpudrv12 RF driver and the OSL and OSX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 components of GPF it was more of a translation from disassembly to C: the C
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 code we use is of our own writing, but it faithfully matches the logic
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 implemented by the original blobs as recovered through disassembly.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 * The G23M protocol stack is a very large and complex component, and our copy
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 of TCS211 (the world's only surviving copy to the best of our knowledge) has
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 it in binary-only form. Trying to source-reconstruct it precisely like we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 did with L1 would have been infeasible, hence we took a different approach:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 we put together a TCS2/TCS3 hybrid in which we made a wholesale replacement
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 of all G23M components: we adopted the new version of G23M wholesale without
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 trying to recreate the old version.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 * Both TCS211 and TI's newer TCS3.2 fw for the LoCosto chipset are based on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 Nucleus PLUS RTOS (different versions), and both firmwares have their Nucleus
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 only as binary object libraries, no source. However, we got another version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 of Nucleus from about the same time frame (slightly newer than the one TI used
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 in TCS211, but slightly older than the one in TCS3.2) from a non-TI source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 (it was posted on a Russian web forum by Comrade XVilka), and in FreeCalypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 Selenite we use this new Nucleus as a replacement for TCS211 original version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 in the same manner as how we had earlier made a wholesale replacement of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 G23M protocol stack.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 With two major components (Nucleus and the G23M PS) replaced with non-TCS211
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 versions, our Magnetite hybrid and Selenite firmwares are no longer TCS211, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 they still faithfully follow the _architecture_ of TCS211: in each case when we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 replaced the code, we made the new code version fit perfectly into the original
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 architecture without any disruptive changes. Thus anyone who desires to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 understand our current FreeCalypso firmwares (Magnetite and Selenite) needs to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 first understand the original TCS211 architecture, as it is essentially
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 unchanged.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 Why not use the LoCosto chipset and its TCS3.2 firmware?
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 ========================================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 We went the Calypso route and not the LoCosto route because of the circumstances
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 that surrounded the beginning of our family of projects. We did not get all of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 the tools needed for working with LoCosto chips and TI's TCS3.2 fw (CSST and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 SBuild) until the spring of 2015, and by that time we had invested too much into
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 the Calypso to throw it all away and restart anew in the uncharted waters of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 LoCosto. Another factor is that the software for talking to LoCosto's ROM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 bootloader (CSST) exists only as Windows binaries sans source, and it would
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 require some effort to reverse-engineer the protocol and implement a free and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 Unix-based alternative - whereas for the Calypso this work was already done by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122 OsmocomBB folks before we entered the scene. Finally, in the case of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 Calypso we have read out the actual content of the ROMs (both the ARM boot ROM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 and the DSP ROM) and the ARM boot ROM code has been disassembled and thoroughly
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 understood - whereas in the case of LoCosto it is not certain if we can even
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 read out the ROM content, as it is said to be protected against reading.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 If someone else desires to play with LoCosto, either by hacking a Peek device
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 or by building an I-Sample board from the available PADS PCB file, go for it!
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 But the FreeCalypso core team is sticking with the Calypso chipset for now, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 our actively maintained Magnetite and Selenite firmwares follow the architecture
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 of TCS211, not that of TCS3.2.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 Relation between the ARM and DSP cores in the Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 =====================================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 The Calypso digital baseband processor chip has two processor cores in it: an
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 ARM7TDMI core that runs the main firmware and a C54x DSP core that performs the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 more burdensome signal processing tasks. The DSP is subservient to the ARM:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 only the ARM comes out of reset and starts executing code upon power-up, while
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 the DSP is held in reset (does not run) until and unless the ARM firmware starts
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 it running.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 The ARM core executes code from outside of the Calypso chip itself: in normal
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145 operation (outside of development) there is a flash memory chip connected to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 Calypso's external memory bus, and the Calypso's ARM core executes firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 stored in this flash. There is an optional (enabled or disabled by a hardware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 pin) ARM boot ROM inside the Calypso chip; when this boot ROM is enabled by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 nIBOOT pin strapping on the board (like it is on Openmoko and FreeCalypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 hardware), the ARM core executes code from this boot ROM first upon power-up or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 reset before jumping to external flash. The tiny piece of code that is hard-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 cast in this mask ROM acts as an unbricking aid: it gives a certain time window
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 during which the boot process can be interrupted and diverted if certain magic
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 characters are sent into either of Calypso's two UARTs by an external
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 development host, and if nothing is received on either UART during that time
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 window (as would be the case in normal usage of a Calypso phone or modem), the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 boot ROM transfers control to the firmware image in the external flash. The
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 end result is that the ARM core always runs code from outside of the Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 chip itself, either the firmware image in the flash or whatever code is fed by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 an external development host to the boot ROM serially over a UART.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 There is also an internal RAM inside the Calypso from which the ARM can execute
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 code (512 KiB on the full Calypso version or 256 KiB on Calypso Lite silicon
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 used in some historical low-end phones); the primary purpose of this internal
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 RAM is to allow chosen sections of code to execute faster without the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 performance penalty of the external memory bus, but it is volatile RAM, not ROM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 or flash, hence it doesn't have any code in it until and unless loaded by the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 firmware copying code from flash or via the serial boot protocol.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 In contrast, the DSP is very different. The DSP core can never execute any
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 code from outside the chip, and has no access to the Calypso chip's external
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 memory bus at all. Instead the only two memories accessible to the DSP are a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 mask ROM and a fast internal RAM. The DSP's dedicated mask ROM is 128 Kwords;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 the DSP's RAM is 28 Kwords, out of which 8 Kwords constitute the so-called API
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 RAM which is accessible to both ARM and DSP cores. (The C54x DSP addresses
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 memory by words instead of bytes, hence the memory sizes are given in Kwords
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 instead of KiB.)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 The main bulk of the DSP's operating program is already hard-cast in the silicon
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 in the 128 Kword mask ROM. The DSP ROM code is structured in such a way that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 any part of it can be overridden by downloadable patch codes which get loaded
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 somewhere in the DSP's 28 Kword RAM, but because the RAM is significantly
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 smaller than the ROM, downloadable DSP code cannot replace the entirety of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 ROM code - instead the code needs to be patched very selectively only where
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 necessary to fix a bug that was discovered after the silicon was made or to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 extend the DSP functionality with a new feature.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188 The DSP ROM code in the Calypso silicon we are using has been successfully read
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 out, but it is only the executable binary code and data - we never found a copy
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 of the source for this DSP ROM code. And even if we had this source, we would
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 not be able to casually modify and recompile it without spending millions of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 dollars to fab a new chip revision with a modified mask ROM. Having this source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 would allow us to develop our own DSP patch codes and to understand and maintain
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 the existing ones, hence we need to make an effort to convince TI to release
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195 the source for the DSP ROM if they have it in their archives, but if no
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 surviving copy of this source exists anywhere in the world, the fallback plan
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 would be to reverse-engineer the DSP ROM code by disassembly. The latter plan
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 has not been pursued yet because of the very high labor cost it would involve.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 It is possible to run the Calypso DSP without any patches, i.e., have it run
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201 only the code that is already in the mask ROM. Our competitor OsmocomBB
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 operates in this manner, and we have also built and run modified versions of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 our TCS211-based FreeCalypso firmware with DSP patch loading disabled as an
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 experiment. However, all ARM-side firmwares that have been officially released
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 by TI for production use including our TCS211-20070608 golden reference do apply
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206 downloadable patches to the DSP, and are designed to run with this patched DSP;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207 running them with DSP patching disabled results in unstable operation.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 DSP patch codes that are included in ARM-side Calypso firmwares take the form
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210 of const char arrays initialized with hex bytes; these C source files with hex
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 char arrays inside were apparently produced from C54x COFF files with a tool
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 called coff2c, but we never got any of those COFF files or whatever source (C
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 or assembly) they were built from. At the present time in the FreeCalypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 family of projects we use the DSP patch codes (hex char arrays) which we got
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 with our copy of TCS211 from 20070608, and we treat the entire DSP block (the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 combination of mask ROM plus patches) as a functional black box.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218 Having to treat the DSP as a black box is certainly a major shortcoming of our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 FreeCalypso solution. However, I (Mother Mychaela) would much rather have a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 phone or modem in which only the DSP is a black box while I get to maintain all
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221 of the upper layers with full freedom, as opposed to the status quo alternative
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
222 of a very high-level black box with FOTA backdoors. Unlike the ubiquitous
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
223 high-level black boxes from the likes of Qualcomm, the DSP in the Calypso cannot
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
224 be backdoored: it has no access to the ARM address space, thus no access to the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
225 flash (cannot surreptitiously modify the firmware) and no access to any of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
226 higher-level radio protocol state maintained by the ARM, all it can do is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
227 modulate and demodulate bursts and run voice codecs _as commanded by the ARM_.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
228 Furthermore, the DSP has no access to the Calypso chip's TPU (Time Processing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
229 Unit, the block that controls board-level RF hardware) and thus has no direct
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
230 control over any of the RF hardware: it cannot initiate radio transmission or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
231 even reception on its own, instead the ARM firmware has to configure the RF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
232 hardware via the TPU for each and every Rx or Tx time window.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
233
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
234 Finally, if anyone is truly paranoid about the possibility of backdoors in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
235 DSP, the DSP ROM code has been read out - you are welcome to hire a professional
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
236 reverser of your choice to disassemble and audit it as thoroughly as you like.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
237 This code is unchangeable by virtue of being hard-cast in a mask ROM in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
238 silicon.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
239
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
240 The rest of this document covers the firmware that runs on the ARM core; it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
241 controls the DSP via its API RAM, a form of shared memory interface.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
242
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
243 High-level structure of TCS211 firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
244 =======================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
245
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
246 The code base that makes up TI's TCS211 firmware consists of 3 main divisions:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
247 chipset software, Condat G23M (GSM and GPRS L23 protocol stacks, ACI and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
248 optional handset UI layers) and GPF. Let us look at them in turn:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
249
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
250 chipsetsw division
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
251 ------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
252
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
253 In the original TCS211 delivery there was a top-level directory named chipsetsw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
254 (chipset software), containing code that is specific to TI's chipsets in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
255 particular and was never intended to run on any other hardware. This code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
256 division has been retained intact in our FreeCalypso Magnetite and Selenite
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
257 firmwares, taken in its entirety from our TCS211 golden reference, although we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
258 have shortened the name: this code division now resides under src/cs in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
259 Magnetite and Selenite. Aside from a few bits of system glue, this chipsetsw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
260 breaks down into two further subdivisions: the L1+drivers core and the SSA
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
261 division.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
262
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
263 L1+drivers core
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
264 ---------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
265
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
266 This division resides under chipsetsw/layer1 and chipsetsw/drivers/drv_core, or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
267 under src/cs/layer1 and src/cs/drivers/drv_core in our version. The most
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
268 important piece here is L1 (GSM Layer 1): this code drives the DSP and the RF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
269 hardware, and thereby makes the Calypso function as a GSM MS (mobile station)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
270 and not merely as a general purpose microprocessor platform. This code can be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
271 considered to be the most important part of the entire firmware.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
272
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
273 At one time TI had a so-called standalone L1 configuration, selected by the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
274 OP_L1_STANDALONE C preprocessor symbol. We don't have the bits that are needed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
275 to build this configuration (they were probably never released outside of TI at
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
276 all), but it appears that this fw build configuration consisted of just Nucleus,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
277 L1, the drivers under drv_core, the OSL and OSX parts of GPF without the rest,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
278 and some stubs for the few higher-level functions that are intertied with L1.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
279
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
280 The drivers under chipsetsw/drivers are divided into drv_core and drv_app: the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
281 former are the most essential or fundamental ones, used by L1 and/or needed for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
282 the OP_L1_STANDALONE config; the latter belong to the higher-level SSA division
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
283 described below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
284
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
285 SSA division
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
286 ------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
287
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
288 TI had a group called System Software and Applications (SSA), and they supplied
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
289 those parts of the firmware that are neither L1+drv_core nor Condat G23M. The
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
290 more interesting pieces here include the flash file system (FFS), the debug
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
291 trace facility (RVT), the Enhanced Test Mode (ETM) facility that allows
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
292 external development and production tools to poke at the firmware, RiViera Audio
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
293 Service (playing various beeps and ringtones through the DSP, a front-end to L1
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
294 audio functions), LCD and keypad drivers for Calypso-based handsets, and various
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
295 supportive functions implemented via the Iota ABB: switch-on and switch-off
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
296 logic, battery monitoring and charging, backlight LED control.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
297
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
298 All firmware components in the SSA division are built on top of a framework
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
299 called RiViera - more will be said about it later. Everything under
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
300 chipsetsw/drivers/drv_app, chipsetsw/riviera and chipsetsw/services (or under
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
301 src/cs/drivers/drv_app, src/cs/riviera and src/cs/services in our version)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
302 belongs to the SSA realm.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
303
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
304 Condat G23M division
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
305 --------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
306
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
307 At the beginning of TI's involvement in the GSM baseband chipset business, they
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
308 only developed and maintained their own L1 code, which eventually grew into the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
309 larger chipsetsw division described above, while the rest of the protocol stack
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
310 (which is hardware-independent) was licensed from another company called Condat.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
311 Later Condat as a company was fully acquired by TI, and the once-customer of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
312 this code became its owner. The name of TI/Condat's implementation of GSM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
313 layers 2&3 for the MS side is G23M, and it forms its own major division of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
314 overall fw architecture.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
315
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
316 The overall Condat code realm can be further subdivided into GSM and GPRS L23
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
317 protocol stacks, the Application Control Interface (ACI) which includes the AT
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
318 command interpreter (ATI), and additional phone UI layers which are only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
319 included in handset but not modem firmwares.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
320
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
321 We don't know exactly how TI maintained this software internally: given that it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
322 is mostly hardware-independent aside from integration details and some minor
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
323 features which may be present on one hw platform but not on another, it would
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
324 have made the most sense for TI to maintain a single internal mainline common
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
325 to both Calypso and LoCosto, and then integrate the code from this mainline into
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
326 chipset-specific customer releases. We have no way of knowing if TI indeed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
327 followed this approach or not, but when we took the version of G23M from the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
328 TCS3.2 source for the LoCosto chipset and grafted it onto the chipsetsw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
329 foundation from TCS211 for the Calypso to produce our TCS2/TCS3 hybrid, the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
330 integration went surprisingly smoothly. The full-source version of G23M which
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
331 we took from TCS3/LoCosto is newer than the binary-only version featured in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
332 world's last surviving copy of TCS211 from Openmoko.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
333
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
334 GPF island of stability
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
335 -----------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
336
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
337 Underlying the G23M protocol stack is a special layer called GPF, which was
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
338 originally Condat's Generic Protocol stack Framework. Apparently Condat were
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
339 in the business of developing and maintaining a whole bunch of protocol stacks:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
340 GSM MS side, GSM network side, TETRA and who knows what else. GPF was their
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
341 common underpinning for all of their protocol stack projects, which ran on top
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
342 of many different OS environments: Nucleus, pSOS, VxWorks, Unix/Linux, Win32
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
343 and who knows what else.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
344
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
345 In the case of TI/FreeCalypso GSM fw, both the protocol stack and the underlying
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
346 OS environment are fixed: GSM and Nucleus, respectively. But GPF is still a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
347 critically important layer in the firmware architecture: in addition to serving
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
348 as the glue between the G23M stack and Nucleus, it provides some important
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
349 support infrastructure for the protocol stack.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
350
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
351 However, what makes GPF very special is the way in which it relates to the rest
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
352 of the firmware architecture. GPF remained common and unchanged across TI's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
353 many different projects, and it is so independent from the rest of the firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
354 and its build configuration that TI were able to make company-wide GPF library
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
355 builds and then plop them into multiple fw projects which used them as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
356 configuration-independent prebuilt libraries. All TI firmware (semi-)sources
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
357 we've got use GPF in prebuilt library form and are not set up to recompile any
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
358 part of it from source.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
359
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
360 Our FC Magnetite firmware uses the original binary libs from TCS211-Openmoko
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
361 for its GPF component, but for FC Selenite the project requirement is to be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
362 completely blob-free, hence we had to reconstruct the source for GPF. The
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
363 original source for most parts of GPF was found between TCS3.2 from Peek/FGW
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
364 and TCS211 from OM (the former had the source for the core "frame" modules and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
365 the latter had the source for misc and tst), but we never got the source for the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
366 OSL and OSX components, hence we had to reconstruct them from disassembly. OSL
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
367 is the glue layer between GPF and Nucleus, OSX is the glue layer between GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
368 and L1.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
369
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
370 Firmware boot process
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
371 =====================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
372
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
373 As already mentioned earlier, the Calypso chip itself includes an ARM boot ROM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
374 in the silicon that serves as an unbricking aid: it provides a certain time
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
375 window during which the boot process can be interrupted and diverted if certain
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
376 magic characters are sent into either of Calypso's two UARTs by an external
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
377 host, and if nothing is received on either UART during that time window, the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
378 boot ROM transfers control to the firmware image in the external flash. As we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
379 understand it, Calypso was TI's first DBB (digital baseband processor) chip to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
380 include this boot ROM, and their previous DBB chips did not have such: they
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
381 would always execute code directly from external flash immediately out of reset.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
382
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
383 TI's TCS211 and earlier firmwares are structured in such a way that they boot
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
384 and run exactly the same way whether the Calypso boot ROM is present and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
385 enabled, present but disabled, or not present at all. They put magic constant
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
386 0x00000001 in the 32-bit word at flash address 0x2000, which tells the Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
387 boot ROM (if it is present and enabled) to boot the flash fw image in legacy
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
388 mode: after providing the unbricking time window, the boot ROM moves itself out
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
389 of the way (sets two bits in the FFFF:FB10 register which tell the chip to unmap
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
390 the boot ROM and to map external memory at address 0) and induces a watchdog
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
391 reset, causing the chip to re-execute the reset vector, this time directly out
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
392 of external flash - thus the firmware boots as if the boot ROM weren't there,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
393 but the ROM's unbricking function is retained.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
394
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
395 In order to make it easier to load new firmware images during development on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
396 pre-Calypso platforms which didn't have a boot ROM, TI had developed a flash-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
397 resident bootloader stage and included it in their fw architecture. This
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
398 bootloader stage is placed at the beginning of the flash at the reset vector,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
399 and the rest of the firmware begins at an erase unit boundary. The bootloader
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
400 stage executes first, and before it jumps to the main firmware entry point
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
401 (_INT_Initialize) for normal boot, it offers an opportunity for the boot process
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
402 to be interrupted and diverted if an external host sends certain magic command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
403 packets into either of the two UARTs during the allotted time window. If the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
404 external host does interrupt and divert the boot process in this manner, it can
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
405 feed a code image to the bootloader to be written somewhere in target RAM, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
406 then command the bootloader to jump to it. It is exactly the same functionality
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
407 (though with different serial protocol specifics) as implemented in the Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
408 boot ROM. The ROM version is obviously superior because it is unbrickable, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
409 the flash-resident, built-with-firmware version is what TI used before they
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
410 came up with the idea of the boot ROM for the Calypso.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
411
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
412 When the boot-ROM-equipped Calypso came along, TI kept the flash-resident
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
413 bootloader in the firmware: it does no harm aside from adding a little bit of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
414 delay to the boot process, it does not conflict with the ROM bootloader as the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
415 two speak different serial protocols and respond to different interrupt-boot
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
416 sequences, and it allowed TI to keep the same firmware architecture for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
417 platforms with and without a boot ROM. However, in our FreeCalypso firmwares
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
418 starting with Magnetite we have removed this extra bootloader stage for the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
419 following reasons:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
420
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
421 * It is not useful to us on any of our hardware targets: on those devices that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
422 have the Calypso boot ROM enabled, we use that boot ROM and get full
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
423 unbrickability, whereas on Mot C1xx phones we have to work with Mot/Compal's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
424 own different bootloader and serial protocol at least initially, hence it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
425 makes the most sense to stick with the same after the conversion to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
426 FreeCalypso as well.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
427
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
428 * As delivered by TI with their full production TCS211 fw releases, their
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
429 firmware-resident bootloader works as intended only on hw platforms with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
430 13 MHz VCXOs like the original D-Sample (Clara RF), and is broken on platforms
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
431 like Rita RF (the only RF chip for which we have driver code!) with 26 MHz
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
432 VCXOs: there is no conditionally-compiled code anywhere in the bootloader
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
433 code path to set the VCLKOUT_DIV2 bit in the CNTL_CLK register on 26 MHz
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
434 platforms, thus the UARTs are fed with 26 MHz instead of the standard 13 MHz
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
435 clock expected in normal operation, and the intended baud rate of 115200 bps
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
436 turns into 230400. Because 230400 bps is a baud rate which Calypso UARTs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
437 *cannot* produce in normal GSM operation (when the peripheral clock network
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
438 runs at the expected 13 MHz), tools that are designed to talk to Calypso GSM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
439 devices are typically not designed to support this baud rate. In particular
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
440 for CP2102 USB-serial adapters, the precedent established by the factory
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
441 CP2102 EEPROM programming in the Pirelli DP-L10 phone is that the baud rate
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
442 entry for 230400 bps is replaced with 203125 bps, which is a valid baud rate
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
443 for Calypso UARTs running at 13 MHz.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
444
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
445 * We have no source for TI's firmware-resident bootloader, only linkable binary
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
446 objects that came with our world's last surviving copy of TCS211, which are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
447 incompatible with our goal of blob-free firmware.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
448
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
449 Because this extra bootloader stage is ultimately unnecessary in our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
450 environment, the deblobbing goal was easier accomplished by removing it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
451 altogether instead of expending effort on a blob-free replacement. Because I
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
452 wasn't comfortable with modifying TMS470 assembly code and linker script magic,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
453 the removal of the bootloader was accomplished by stubbing out its C body with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
454 an empty function. In the gcc-built FC Selenite version it is removed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
455 completely, without any leftover stubs.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
456
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
457 Finally, it needs to be noted for the sake of completeness that Compal's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
458 bootloader used on Mot C1xx phones is a modified version based on TI's original
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
459 bootloader. However, this factoid matters only for historians and genealogists;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
460 for all practical purposes it is an unrelated animal, as Mot/Compal's serial
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
461 protocol for interrupting and diverting the boot process is their own and bears
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
462 no resemblance to TI's version. And yes, Mot/Compal's version does set the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
463 VCLKOUT_DIV2 bit in the CNTL_CLK register to adjust for the 26 MHz clock input
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
464 as its first order of business; it was probably the very first issue they had
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
465 to fix.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
466
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
467 When we build FC Magnetite or FC Selenite TMS470 firmware for Mot C1xx targets,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
468 we use dd to strip off the first 64 KiB of the image produced by TI's linker
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
469 (the part where TI's bootloader resides, be it intact or stubbed out) and flash
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
470 the remaining image (the main body of the fw) starting at flash address 0x10000.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
471 In the gcc-built Selenite version we natively link images that are designed to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
472 be flashed at 0x10000 without any dirty hacks. Common to all FC firmwares for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
473 C1xx targets, the bootloader image we put at 0 (in the brickable flash sector)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
474 is a modified version based on one of Mot/Compal's originals: we have binary-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
475 patched it to redirect the exception vectors from Mot/Compal's 0x20A0 to 0x10000
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
476 and to move the main fw entry point from Mot/Compal's 0x20F8 to TI's 0x10058.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
477
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
478 None of this muckery applies to our own FreeCalypso hardware or to our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
479 predecessor Openmoko's hw: on these good hw targets the complete fw image as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
480 built is flashed at 0, and there is no possibility of bricking because we use
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
481 the boot ROM to gain access irrespective of what's in the flash.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
482
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
483 Main firmware entry point
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
484 -------------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
485
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
486 With the bootloader distraction out of the way, the main fw entry point is at
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
487 the _INT_Initialize symbol in the int.s assembly module, located in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
488 src/cs/system/main/int.s in Magnetite and Selenite. The functional equivalent
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
489 for the gcc environment in Selenite is in src/cs/system/main/gcc/bootentry.S.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
490 This assembly code performs some basic hardware initialization, sets up
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
491 sensible memory timings for the boot path phase before DPLL setup, copies the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
492 IRAM code (the code that is intended to execute out of the fast internal RAM)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
493 from flash to where it needs to be, zeros both IRAM and XRAM .bss regions, does
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
494 TI's cinit/auto_init business for initialized data in the TMS470 environment
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
495 (Selenite gcc version copies .data from flash to RAM instead), sets up the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
496 system, IRQ, FIQ and exception stacks, does some assembly initialization for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
497 Nucleus and finally jumps to Nucleus' C entry point INC_Initialize().
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
498
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
499 Further initialization takes place in the Init_Target() and Init_Drivers()
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
500 functions called from Application_Initialize(), which is the last function
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
501 called by INC_Initialize() before starting the Nucleus task scheduler.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
502
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
503 Nucleus environment
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
504 ===================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
505
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
506 Like all classic TI firmwares, ours is based on the Nucleus PLUS RTOS. Just
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
507 like TI's original code on which we are based, we use only a small subset of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
508 the functionality provided by Nucleus - but because the latter is a library,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
509 the pieces we don't use simply don't get pulled into the link. The main
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
510 function we get out of Nucleus is the scheduling of threads, or tasks as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
511 Nucleus calls them.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
512
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
513 Aside from pre-stack-setup assembly init code and ARM exception handlers, every
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
514 piece of code in the firmware executes in one of the following contexts:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
515
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
516 * Application_Initialize(): this function and everything called from it execute
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
517 just before Nucleus' thread scheduler starts; at this point interrupts are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
518 disabled at the ARM7 core level (in the CPSR) and must not be enabled; the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
519 stack is Nucleus' "system stack" which is also used by the scheduler and LISRs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
520 as explained below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
521
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
522 * Regular threads or tasks: once Application_Initialize() finishes, all code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
523 with the exception of interrupt handlers (LISRs and HISRs as explained below)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
524 runs in the context of some Nucleus task. Whenever you are trying to debug
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
525 or simply understand some piece of code in the firmware, the first question
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
526 you should ask is "which task does this code execute in?". Most functional
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
527 components run in their own tasks, i.e., a given piece of code is only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
528 intended to run within the Nucleus task that belongs to the component in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
529 question. On the other hand, some components are implemented as APIs,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
530 functions to be called from other components: these don't have their own task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
531 associated with them, and instead they run in the context of whatever task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
532 they were called from. Some only get called from one task: for example, the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
533 "uartfax" driver API calls only get called from the protocol stack's UART
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
534 entity, which is its own task. Other component API functions like FFS and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
535 trace can get called from just about any task in the system. Many components
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
536 have both their own task and some API functions to be called from other tasks,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
537 and the API functions oftentimes post messages to the task to be worked on by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
538 the latter; the just-mentioned FFS and trace functions work in this manner.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
539
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
540 In our TCS211-mimicking Magnetite and Selenite firmwares every Nucleus task is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
541 created either through RiViera or through GPF, and not in any other way - see
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
542 the description of RiViera and GPF below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
543
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
544 * LISRs (Low level Interrupt Service Routines): these are the interrupt handlers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
545 that run immediately when an ARM IRQ or FIQ comes in. The code at the IRQ and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
546 FIQ vector entry points calls Nucleus' magic stack switching function
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
547 (switches the CPU from IRQ/FIQ into SVC mode, saves the interrupted thread's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
548 registers on that thread's stack, and switches to the "system" stack) and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
549 then calls TI's IRQ dispatcher implemented in C. The latter figures out
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
550 which Calypso interrupt needs to be handled and calls the handler configured
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
551 in the compiled-in table. Nucleus' LISR registration framework is not used
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
552 by the GSM fw, but these interrupt handlers should be viewed as LISRs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
553 nonetheless.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
554
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
555 There is one additional difference between canonical Nucleus and TI's version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
556 (we've replicated the latter): canonical Nucleus was designed to support
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
557 nested LISRs, i.e., IRQs re-enabled in the magic stack switching function,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
558 but in TI's version which we follow this IRQ re-enabling is removed: each LISR
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
559 runs with interrupts disabled and cannot be interrupted. (The corner case of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
560 an FIQ interruping an IRQ remains to be looked at more closely as bugs may be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
561 hiding there, but Calypso doesn't really use FIQ interrupts.) There is really
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
562 no need for LISR nesting in our GSM fw, as each LISR is very short: most LISRs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
563 do nothing more than trigger the corresponding HISR.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
564
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
565 * HISRs (High level Interrupt Service Routines): these hold an intermediate
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
566 place between LISRs and tasks, similar to softirqs in the Linux kernel. A
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
567 HISR can be activated by a LISR calling NU_Activate_HISR(), and when the LISR
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
568 returns, the HISR will run before the interrupted task (or some higher
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
569 priority task, see below) can resume. HISRs run with CPU interrupts enabled,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
570 thus more interrupts can occur, with their LISRs executing and possibly
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
571 triggering other HISRs. All triggered HISRs must complete and thereby go
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
572 "quiescent" before task scheduling resumes, i.e., all HISRs as a group have a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
573 higher scheduling priority than tasks.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
574
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
575 Nucleus implements priority scheduling for tasks. Tasks have their priority set
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
576 when they are created (through RiViera or GPF, see below), and a higher priority
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
577 task will run until it gets blocked waiting for something, at which time lower
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
578 priority tasks will run. If a lower priority task sends a message to a higher
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
579 priority task, unblocking the latter which was waiting for incoming messages,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
580 the lower priority task will effectively suspend itself immediately while the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
581 higher priority task runs to process the message it was sent.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
582
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
583 HISRs oftentimes post messages to their associated tasks as well; if one of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
584 these messages unblocks a higher priority task, that unblocked task will run
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
585 upon the completion of the HISR instead of the original lower priority task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
586 that was interrupted by the LISR that triggered the HISR. Nucleus' scheduler
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
587 is fun!
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
588
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
589 RiViera and GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
590 ===============
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
591
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
592 RiViera and GPF are two parallel/independent/competing wrappers around or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
593 layers above Nucleus. GPF comes from Condat and is used by the G23M protocol
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
594 stack and indirectly by L1 (the peculiar way in which L1 ties in with the rest
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
595 of the firmware will be covered later), whereas RiViera is used by the fw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
596 components from TI's SSA group: flash file system, debug trace, RiViera Audio
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
597 Service and so forth.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
598
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
599 At some point in their post-Calypso TCS3.x program TI decided to eliminate
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
600 RiViera as an independent framework and to reimplement RiViera APIs (used by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
601 peripheral but necessary code such as FFS, ETM, various drivers etc) over GPF.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
602 This arrangement is used in the TCS3.2 LoCosto firmware from which we have
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
603 lifted our source replacements for much of the code that came as binary objects
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
604 in our reference TCS211 version. However, our current Magnetite and Selenite
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
605 firmwares follow the architecture of TCS211, not that of TCS3.2, and because
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
606 the entire SSA division of the fw including the RiViera core came in full source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
607 form in our copy of TCS211, it was only natural to keep this code and its
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
608 architecture.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
609
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
610 Start-up process continued
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
611 ==========================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
612
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
613 As mentioned earlier, Nucleus calls the application's software init function
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
614 called Application_Initialize() after it initializes itself but before starting
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
615 the task scheduler. This function in TCS211 is just the following:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
616
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
617 Application_Initialize()
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
618 {
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
619 Init_Target();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
620 Init_Drivers();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
621 Cust_Init_Layer1();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
622 Init_Serial_Flows();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
623 StartFrame();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
624 Init_Unmask_IT();
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
625 }
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
626
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
627 Cust_Init_Layer1() is in L1, StartFrame() is in GPF, and the remaining 4 init
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
628 functions live in the init.c module under src/cs/system/main.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
629
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
630 The Init_Target() function finishes the hardware initialization that was
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
631 started by the assembly code at the firmware boot entry point (int.s): among
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
632 other things, it sets up the final memory timings that will be used by the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
633 running fw and configures the Calypso DPLL which provides multiplied internal
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
634 clocks to both ARM and DSP cores. On Calypso C035 silicon which is used on our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
635 own FreeCalypso boards and on most of our pre-existing hw targets the DPLL and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
636 the DSP run at 104 MHz and the ARM gets half of that, running at 52 MHz.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
637 Init_Target() also calls AI_InitIOConfig(), the function that initializes
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
638 Calypso GPIO directions and initial outputs; both of these functions typically
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
639 need to be tweaked when adding support for a new Calypso board target.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
640
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
641 The Init_Drivers() function is primarily responsible for initializing RiViera
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
642 and FFS, although it also does a bit of init related to ABB and SIM drivers.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
643
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
644 I mentioned earlier that every Nucleus task in our firmware gets created and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
645 started either through RiViera or through GPF. All GPF tasks are created and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
646 placed into the runable state in the Application_Initialize() context: the work
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
647 is done by GPF init code in gpf/frame/frame.c, and the top level GPF init
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
648 function called from Application_Initialize() is StartFrame(). Thus when
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
649 Application_Initialize() finishes and the Nucleus thread scheduler starts
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
650 running for the first time, all GPF tasks are there to be scheduled.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
651
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
652 There is a compiled-in table of all protocol stack entities and the tasks in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
653 which they need to run; in TCS211 these GPF config bits live under
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
654 g23m/condat/frame/config for the GSM+GPRS configuration and under
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
655 g23m/condat/com/src/config for the GSM-only config without GPRS. Canonically
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
656 each protocol stack entity runs in its own task, but sometimes two or more are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
657 combined to run in the same task: for example, in the minimal GSM "voice only"
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
658 configuration (no CSD, fax or GPRS) CC, SMS and SS entities share the same task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
659 named CM. Unlike RiViera, GPF does not support dynamic starting and stopping
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
660 of tasks.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
661
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
662 As each GPF task starts running (immediately upon entry into Nucleus' scheduling
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
663 loop as Application_Initialize() finishes), pf_TaskEntry() function in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
664 gpf/frame/frame.c is the first code it runs. This function creates the queue
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
665 for messages to be sent to all entities running within the task in question,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
666 calls each entity's pei_init() function (repeatedly until it succeeds: it will
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
667 fail until the other entities to which this entity needs to send messages have
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
668 created their message queues), and then falls into the main body of the task:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
669 for all "regular" entities/tasks except L1, this main body consists of waiting
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
670 for messages (or signals or timeouts) to arrive on the queue and dispatching
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
671 each received message to the appropriate handler in the right entity.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
672
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
673 RiViera tasks get started in a different way. The responsible code lives in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
674 src/cs/system/main/create_RVtasks.c, and the create_tasks() function found in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
675 that module is called by Init_Drivers() in the Application_Initialize() context.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
676 But this function does not directly create and start every configured RiViera
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
677 task like StartFrame() does for GPF. Instead it creates a special helper task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
678 which will do this work once scheduled. Thus at the completion of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
679 Application_Initialize() and the beginning of scheduling the set of runable
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
680 Nucleus tasks consists of all GPF ones plus the special RV starter task. Once
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
681 the RV starter task gets scheduled, it will call rvm_start_swe() to launch
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
682 every configured RiViera SWE (SoftWare Entity), which in turns entails creating
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
683 the tasks in which these SWEs are to run.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
684
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
685 Dynamic memory allocation
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
686 =========================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
687
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
688 All dynamic memory allocation (i.e., all RAM usage beyond statically allocated
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
689 variables and buffers) is once again done either through RiViera or through GPF,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
690 and in no other way. Ultimately all areas of the physical RAM that will ever
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
691 be used by the fw in any way are allocated when the fw is compiled and linked:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
692 the areas from which RiViera and GPF serve their dynamic memory allocations are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
693 statically allocated as char arrays in the respective C modules and placed in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
694 the appropriate IRAM or XRAM .bss section by the linker script; RiViera and GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
695 then provide API functions that allocate memory dynamically from these
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
696 statically allocated large pools.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
697
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
698 RiViera and GPF have entirely separate memory pools from which they serve their
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
699 respective clients, hence there is no possibility of one affecting the other.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
700 Riviera's memory allocation scheme is very much like the classic malloc&free:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
701 there is one large unstructured pool from which all allocations are made, one
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
702 can allocate a chunk of any size, free chunks are merged when physically
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
703 adjacent, and fragmentation is an issue: a memory allocation request may fail
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
704 even when there is enough memory available in total if it is too fragmented.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
705
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
706 GPF's dynamic memory allocation facility is considerably more robust: while it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
707 does maintain one or two (depending on configuration) memory pools of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
708 traditional "dynamic" kind (like malloc&free, susceptible to fragmentation),
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
709 most GPF memory allocation works on "partition" memory instead. Here GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
710 maintains 3 separate groups of pools: PRIM, TEST and DMEM; each allocation
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
711 request must specify the appropriate pool group and cannot affect the others.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
712 Within each pool there is a fixed number of partitions of a fixed size: for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
713 example, in TI's TCS211 GSM+GPRS configuration the PRIM pool group consists of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
714 190 partitions of 60 bytes, 110 partitions of 128 bytes, 50 partitions of 632
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
715 bytes and 7 partitions of 1600 bytes. An allocation request from a given pool
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
716 group (e.g., PRIM) can request any arbitrary size in bytes, but it gets rounded
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
717 up to the nearest partition size and allocated out of the respective pool. If
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
718 no free partition is available, the requesting task is suspended until another
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
719 task frees one. Because these partitions are used primarily for intertask
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
720 communication, if none are free, it can only mean (assuming that the firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
721 functions correctly) that all partitions have been allocated and sent to some
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
722 queue for some task to work on, hence eventually they will get freed.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
723
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
724 This scheme implemented in GPF is extremely robust in the opinion of this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
725 author, and the other purely "dynamic" scheme is used (in the case of GPF) only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
726 for init-time allocations which are never freed, such as task stacks - hence
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
727 the GPF-based part of the firmware is not suspectible at all to the problem of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
728 memory fragmentation. But Riviera does suffer from this problem, and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
729 concern is more than just theoretical: one major user of Riviera-based dynamic
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
730 memory allocation is the trace facility (described in its own section below),
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
731 and my observation of the trace output from Pirelli's proprietary fw (which
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
732 appears to use the same architecture with separate Riviera and GPF) suggests
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
733 that after the fw has been running for a while, Riviera memory gets fragmented
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
734 to a point where many traces are being dropped. Replacing Riviera's poor
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
735 dynamic memory allocation scheme with a GPF-like partition-based one is a to-do
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
736 item for our project.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
737
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
738 Message-based intertask communication
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
739 =====================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
740
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
741 Even though all entities of the G23M protocol stack are linked together into
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
742 one monolithic fw image and there is nothing to stop them from calling each
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
743 other's functions and accessing each other's variables, they don't work that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
744 way. Instead all communication between entities is done through messages, just
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
745 as if they ran in separate address spaces or even on separate processors.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
746 Buffers for this message exchange are allocated from a GPF partition pool: an
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
747 entity that needs to send a message to another entity allocates a buffer of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
748 needed size, fills it with the message to be sent, and posts it on the recipient
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
749 entity's message queue, all through GPF services. The other entity simply
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
750 processes the stream of messages that arrives on its message queue, freeing each
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
751 message (returning the buffer to the partition pool it came from) as it is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
752 processed.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
753
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
754 Riviera-based tasks use a similar mechanism: unlike G23M protocol stack
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
755 entities, most Riviera-based functional modules provide APIs that are called as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
756 functions from other tasks, but these API functions typically allocate a memory
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
757 buffer (through Riviera), fill it with the call parameters, and post it to the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
758 associated task's message queue (also in the Riviera land) to be worked on.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
759 Once the worker task gets the job done, it will either call a callback function
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
760 or post a response message back to the requestor - the latter option is only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
761 possible if the requesting entity is also Riviera-based.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
762
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
763 A closer look at GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
764 ====================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
765
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
766 There are certain sublayers within GPF which need to be pointed out. The 3
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
767 major subdivisions within GPF are:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
768
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
769 * The meaty core of GPF: this part is the code under src/gpf/frame in our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
770 Selenite GPF reconstruction, originating from gpf/FRAME in the TCS3.2 source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
771 from Peek/FGW. It appears that this part was originally intended to be both
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
772 project-independent (same for GSM, TETRA etc) and OS-independent (same for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
773 Nucleus, pSOS, VxWorks etc). This is the part of GPF that matters for the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
774 G23M stack: all APIs called by PS entities are implemented here, and so are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
775 all other PS-facing functions such as startup. (PS = protocol stack)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
776
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
777 * OS adaptation layer (OSL): this is the part of GPF that adapts it to a given
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
778 underlying OS, in our case Nucleus.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
779
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
780 * Test interface: see the code under gpf/tst in TCS211 from Openmoko or in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
781 FC Selenite. This part handles the trace output from all entities that run
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
782 under GPF and the mechanism for sending external debug commands to the GPF+PS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
783 subsystem.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
784
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
785 GPF was a difficult step in our GSM firmware deblobbing process because no
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
786 complete source for it could be found anywhere: apparently GPF was so stable
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
787 and so independent of firmware particulars (Calypso or LoCosto, GSM only or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
788 GSM+GPRS, modem or complete phone with UI etc) that it appears to have been
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
789 used and distributed as prebuilt binary libraries even inside TI. All TI fw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
790 (semi-)sources we've got use GPF in prebuilt library form and are not set up to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
791 recompile any part of it from source. (They had to include all GPF header
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
792 files though, as most of them are included by G23M C modules, and it would be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
793 too much hassle to figure out which ones are or aren't needed, hence all were
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
794 included.)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
795
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
796 Fortunately though, we were able to find the sources for most parts of GPF:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
797
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
798 * The LoCosto source in TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src.zip features the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
799 source for the "core" part of GPF under gpf/FRAME - these sources aren't
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
800 actually used by that fw's build system (it only uses the prebuilt binary
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
801 libs for GPF), but they are there.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
802
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
803 * Our TCS211 semi-src doesn't have any sources for the core part of GPF, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
804 instead it features the source for the test interface and some "misc" parts:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
805 under gpf/MISC and gpf/tst in that source tree - these sources are not present
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
806 in the LoCosto version from Peek.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
807
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
808 The GPF frame, misc and tst sources we have found have been verified to match
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
809 the binary objects that came with TCS211 from OM: they can be compiled into a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
810 bit-for-bit match. However, one critical piece was still missing: the OS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
811 adaptation layer. It appears that the GPF core (vsi_??? modules) and OSL
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
812 (os_??? modules) were maintained and built together, ending up together in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
813 frame_<blah>.lib files in the binary form used to build firmwares, but the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
814 source for the "frame" part in the Peek find contained only vsi_*.c and others,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
815 but not any of os_*.c.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
816
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
817 Our FC Magnetite firmware uses the original binary libs from TCS211-Openmoko
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
818 for its GPF component, but for FC Selenite the project requirement is to be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
819 completely blob-free, hence we had to reconstruct the source for the OSL part
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
820 of GPF from disassembly. This work was originally done in 2014 in the context
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
821 of our first attempt at gcc-built blob-free GSM fw (FC Citrine, now deemed to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
822 be a dead end and fully retired); this reconstruction was then dug up and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
823 adapted for Selenite in 2018. As of this writing, this reconstruction is still
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
824 not 100% complete (one complex error handling function is stubbed out) and not
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
825 yet trusted to be fully correct, thus our fully deblobbed Selenite firmware is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
826 currently considered experimental; our current production fw is still Magnetite
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
827 with blobs for GPF.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
828
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
829 A closer look at L1
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
830 ===================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
831
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
832 The L1 code is remarkable in how little intertie it has with the rest of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
833 firmware it is linked into. It is almost entirely self-contained, expecting
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
834 only 4 functions to be provided by the underlying OS environment:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
835
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
836 os_alloc_sig -- allocate message buffer
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
837 os_free_sig -- free message buffer
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
838 os_send_sig -- send message to upper layers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
839 os_receive_sig -- receive message from upper layers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
840
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
841 It helps to remember that at the beginning of TI's involvement in the GSM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
842 baseband chipset business, L1 was the only thing they "owned", while Condat,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
843 the maintainers of the higher level protocol stack, was a separate company.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
844 TI's "turnkey" solution must have consisted of their own L1 code plus G23M code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
845 (including GPF etc) licensed from Condat, but I'm guessing that TI probably
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
846 wanted to retain the ability to sell their chips with their L1 without being
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
847 entangled by Condat: let the customer use their own GSM L23 stack, or perhaps
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
848 work out their own independent licensing arrangements with Condat. I'm
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
849 guessing that L1 was maintained as its own highly independent and at least
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
850 conceptually portable entity for these reasons.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
851
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
852 The way in which L1 is intertied into the rest of the fw is the same in all TI
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
853 production firmwares we have seen, including both our TCS211 reference and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
854 TCS3.2 LoCosto version. There is a module called OSX, which is an extremely
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
855 thin adaptation layer that implements the APIs expected by L1 in terms of GPF.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
856 Furthermore, this OSX layer provides header file isolation: the only "outside"
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
857 (non-L1) header included by L1 is cust_os.h, and it defines the necessary
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
858 interface to OSX *without* including any other headers (no GPF headers in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
859 particular), using only the C language's native types. Apart from this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
860 cust_os.h header, the entire OSX layer is implemented in one C module (osx.c,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
861 which we had to reconstruct from osx.obj as the source was missing - but it's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
862 very simple) which does include some GPF headers and implements the OSX API in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
863 terms of GPF services. Thus in both TI's production firmwares and our own ones,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
864 L1 does sit on top of GPF, but very indirectly.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
865
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
866 More specifically, the "production" version of OSX implements its API in terms
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
867 of *high-level* GPF functions, i.e., VSI. However, they also had an interesting
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
868 OP_L1_STANDALONE configuration which omitted not only all of G23M, but also the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
869 core of GPF and possibly the Riviera environment as well. We don't have a way
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
870 to recreate this configuration exactly as it existed inside TI because we don't
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
871 have the source bits specific to this configuration, but we do have a little
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
872 bit of insight into how it worked.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
873
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
874 It appears that TI's OP_L1_STANDALONE build used a special "gutted" version of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
875 GPF in which the "meaty core" (VSI etc) was removed. The OS layer (os_???
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
876 modules implementing os_*() functions) that interfaces to Nucleus was kept, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
877 so was OSX used by L1 - but this time the OSX API functions were implemented in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
878 terms of os_*() ones (low-level wrappers around Nucleus) instead of the higher-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
879 level VSI APIs provided by the "meaty core" of GPF. It is purely a guess on my
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
880 part, but perhaps this hack was also done in the days before TI's acquisition
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
881 of Condat, and by omitting the "meaty core" of GPF, TI could claim that their
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
882 OP_L1_STANDALONE configuration did not contain any of Condat's "intellectual
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
883 property".
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
884
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
885 Run-time structure of L1
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
886 ========================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
887
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
888 L1 consists of two major parts: L1S and L1A. L1S is the synchronous part where
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
889 the most time-critical functions are performed; it runs as a Nucleus HISR. The
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
890 hardware in the Calypso generates an interrupt on every TDMA frame (4.615 ms,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
891 or more precisely 60/13 ms), and the LISR handler for this interrupt triggers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
892 the L1S HISR. L1S communicates with L1A through a shared memory data structure,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
893 and also sometimes allocates message buffers and posts them to L1A's incoming
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
894 message queue (both via OSX API functions, i.e., via GPF in disguise).
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
895
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
896 L1A runs as a regular task under Nucleus, and includes a blocking call (to GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
897 via OSX) to wait for incoming messages on its queue. It is one big loop that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
898 waits for incoming messages, then processes each received message and commands
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
899 L1S to do most of the work. The entry point to L1A in the L1 code proper is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
900 l1a_task(), although the responsibility for running it as a task falls on some
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
901 "glue" code outside of L1 proper. TI's production firmwares with G23M included
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
902 have an L1 protocol stack entity within G23M whose only job (aside from some
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
903 initialization) is to run l1a_task() in the Nucleus task created by GPF for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
904 that protocol stack entity; we do the same in our firmwares.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
905
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
906 Communication between L1 and G23M
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
907 =================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
908
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
909 It is remarkable that L1 and G23M don't have any header files in common: L1
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
910 uses its own (almost fully self-contained), whereas the G23M+GPF realm is its
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
911 own world with its own header files. One has to ask then: how do they
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
912 communicate? OK, we know they communicate through primitives (messages in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
913 buffers allocated from GPF's PRIM partition memory pool) passed via message
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
914 queues, but what about the data structures in these messages? Where are those
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
915 defined if there are no header files in common between L1 and G23M?
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
916
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
917 The answer is that there are separate definitions of the L1<->G23M interface on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
918 each side, and TI must have kept them in sync manually. Not exactly a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
919 recommended programming or software maintenance practice for sure, but TI took
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
920 care of it, and the existing proprietary products based on TI's firmware are
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
921 rock solid, so it is not really our place to complain.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
922
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
923 TI's firmwares from the era we are working with (both our TCS211 golden
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
924 reference and the TCS3.2/LoCosto source from which we took the newer full-source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
925 version of G23M for our TCS2/TCS3 hybrid) also include a component called ALR.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
926 It resides in the G23M code realm: G23M coding style, uses Condat header files,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
927 runs as its own protocol stack entity under GPF. This component appears to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
928 serve as a glue layer between the rest of the G23M stack (which is supposed to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
929 be truly hardware-independent) and TI's L1.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
930
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
931 Speaking of ALR, it is worth mentioning that there is a little naming
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
932 inconsistency here. ALR is known to the connect-by-name logic in GPF as "PL"
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
933 (physical layer, apparently), while the ACI entity (Application Control
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
934 Interface, the top level entity) is known to the same logic as "MMI". No big
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
935 deal really, but hopefully knowing this quirk will save someone some confusion.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
936
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
937 A closer look at our FreeCalypso TCS2/TCS3 hybrid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
938 =================================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
939
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
940 Because we don't have an official TI firmware release for the Calypso in full
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
941 source form and because I am not willing to throw away all of our Calypso work
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
942 and restart anew with LoCosto with its own host of unknowns, the only currently
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
943 available way for us to have blob-free production-quality GSM mobile station fw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
944 is the TCS2/TCS3 hybrid implemented in FC Magnetite and Selenite. This hybrid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
945 is made by taking the G23M version from TCS3/LoCosto and grafting it onto the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
946 chipsetsw foundation from TCS211, including the original TCS211/Calypso version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
947 of L1 which we have meticulously source-reconstructed. The version of GPF used
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
948 for this hybrid is also the TCS211 version in Magnetite or our source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
949 reconstruction thereof in Selenite.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
950
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
951 The Condat G23M pieces have been hybridized as follows:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
952
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
953 * cdginc generated header files are a special hybrid version described below;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
954
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
955 * The include files under condat/com/inc and condat/com/include are the TCS3
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
956 version, except for pwr.h and rtc.h for which we use the TCS2 version;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
957
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
958 * comlib is the TCS2 version, except for cl_rlcmac.c which is from TCS3;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
959
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
960 * config modules (condat/com/src/config and condat/frame/config) are the TCS2
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
961 version, with some fixes for the needs of the TCS3 version of G23M PS and our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
962 own FreeCalypso fixes;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
963
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
964 * Condat drivers (condat/com/src/driver) are the TCS2 version;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
965
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
966 * All G23M PS components are the TCS3 version by necessity, as this is the part
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
967 for which the source is missing in our TCS211 version, with the exception of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
968 ALR - the original source for the TCS211 version of ALR has miraculously
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
969 survived, the ALR source in TCS211 from OM can be compiled into a perfect
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
970 match for the binary lib version;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
971
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
972 * We use the TCS2 version of ALR (the interface to our TCS211 L1) and not the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
973 TCS3 version (a change from Citrine), but it is compiled with the same hybrid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
974 cdginc headers as the rest of hybrid G23M, not the old TCS211 ones;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
975
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
976 * ACI is the TCS3 version - we have the source for both versions, but trying to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
977 use the old TCS2 version of ACI on top of the new TCS3 version of the PS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
978 would cause untold breakage;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
979
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
980 * The UI layers (MFW and BMI) for handset fw builds are handled like ACI: we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
981 have the source for both versions, but we use the TCS3 version which works
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
982 with the TCS3 versions of ACI and cdginc;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
983
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
984 * The CST (Customer Specific Task) component is the TCS2 version - while it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
985 logically belongs in the Condat realm, the code lives in the chipsetsw realm
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
986 under chipsetsw/services/cst (yes, it's under services with SSA stuff even
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
987 though it doesn't use RiViera) and thus our copy of TCS211 from OM has this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
988 source preserved.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
989
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
990 With this hybrid arrangement the main splice point lies above ALR, and there
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
991 are many little splice points throughout the code where some upper-level code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
992 from TCS3 needs to talk to lower-level code from TCS2. There are no inversions,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
993 i.e., no places where TCS2 code sits on top of code from TCS3, although there
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
994 are a few instances where TCS2 C code uses some TCS3 header files.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
995
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
996 TCS3 feature flags
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
997 ------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
998
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
999 Our TCS3.2/LoCosto code from Peek/FGW from 20090327 supports several new GSM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1000 features (apparently related to GSM release 99) which are not supported by our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1001 TCS211-20070608 golden reference from OM. All of these new features can be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1002 enabled or disabled with conditional compilation flags. Our TCS2/TCS3 hybrid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1003 currently has all of these new features disabled: it was too difficult for me
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1004 to figure out if these new features require some support from the hardware or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1005 the DSP which is present on LoCosto but not Calypso, and even if our hw and DSP
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1006 have all of the necessary capabilities, at least some of the new features
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1007 require adding some code to L1, which is incompatible with my approach of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1008 reconstructing TCS211 L1 pristinely.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1009
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1010 In any case, the GSM functionality we get by using the new version of G23M with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1011 new feature flags disabled on top of pristine TCS211 L1 cannot be any worse
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1012 than what we would have had if we had the full corresponding source for our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1013 TCS211-20070608 golden reference, and it is probably a little better because we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1014 are using a newer version of G23M code.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1015
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1016 cdginc headers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1017 --------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1018
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1019 Much of the code in the Condat G23M realm makes heavy use of a set of machine-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1020 generated C header files called cdginc. These header files contain various
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1021 definitions related both to the GSM air protocols being implemented and to G23M
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1022 protocol stack internals (interfaces and message structures between components),
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1023 and they are generated from a set of message definition files (*.mdf) and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1024 primitive definition files (*.pdf) by a tool called ccdgen. The *.{mdf,pdf}
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1025 inputs to ccdgen are human-readable ASCII, and of course the generated C header
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1026 files are human-readable too, but we have no source for the ccdgen tool itself,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1027 only a Windows binary which we can run under Wine.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1028
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1029 The ccdgen binary problem is yet another instance of so far incomplete
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1030 liberation of the GSM firmware. It is currently a very low-priority problem:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1031 we do not casually edit any of the *.{mdf,pdf} inputs to ccdgen, and we don't
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1032 run ccdgen on every fw build - instead we have run ccdgen once and checked its
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1033 output files (generated C headers) into our Magnetite and Selenite trees as if
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1034 they were sources. If we are not able to convince TI to dig up and release the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1035 source for ccdgen, there is a viable albeit costly alternative: hire a Windows
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1036 reverser to RE the ccdgen.exe binary (262144 bytes) and produce a C
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1037 reimplementation that replicates all of its logic. It is a Win32 console app,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1038 no GUI, and it is a pure data processing application without any hardware access
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1039 or OS functions or any other muckery: it is probably pure ANSI C code that reads
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1040 and parses a bunch of ASCII input files, performs some business logic on the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1041 data, and writes another bunch of ASCII text files as outputs. It is currently
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1042 a very low-priority task though; reversing the Calypso DSP ROM code should
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1043 probably be a higher priority.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1044
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1045 The set of cdginc headers for our TCS2/TCS3 hybrid has been generated as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1046 follows:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1047
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1048 * All of the *.mdf files are the TCS3 version;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1049
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1050 * All of the *.pdf files except mphc.pdf and mphp.pdf are also the TCS3 version;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1051
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1052 * mphc.pdf and mphp.pdf are the TCS211 version - this is the interface to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1053 TCS211 L1;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1054
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1055 * All new feature flags (see discussion above) are set to disabled.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1056
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1057 Condat Coder and Decoder (CCD)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1058 ------------------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1059
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1060 CCD is a firmware component in the Condat G23M realm which I haven't really
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1061 studied yet. It consists of two parts:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1062
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1063 * A fixed portion which TI used to distribute in binary form and which various
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1064 firmware projects used as a prebuilt library like GPF - technically TI
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1065 considered it to be a part of GPF, although we prefer to treat it as its own
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1066 more independent entity;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1067
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1068 * The ccddata portion which needs to be compiled with cdginc headers for each
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1069 given project.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1070
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1071 We got the source for both parts of CCD only in the TCS3.2/LoCosto version, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1072 not in the TCS211 version, hence the decision was easy: we use the TCS3 version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1073 of CCD (both parts) with the TCS3 version of cdginc with the TCS3 version of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1074 the G23M PS.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1075
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1076 TCS3.2 GPF discrepancy
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1077 ----------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1078
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1079 A careful examination of the prebuilt GPF libraries under gpf/LIB in the TCS3.2
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1080 LoCosto source tree has revealed that a few of the binary objects exhibit some
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1081 differences from the TCS211 version which we've been treating as our golden
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1082 reference:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1083
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1084 * The os_mis module (OSL miscellany) in the IRAM library implements a new
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1085 function called os_CheckQueueEvent() and defines a new global data object
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1086 named my_os_mis_Protect;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1087
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1088 * The os_tim module (OSL timer code) in the flash (XIP) library has some code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1089 differences;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1090
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1091 * The vsi_tim module (VSI timer code) in the flash (XIP) library has some code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1092 differences;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1093
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1094 * The vsi_tim module (VSI timer code) in the IRAM library has some code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1095 differences and makes use of the new os_CheckQueueEvent() function.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1096
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1097 In the case of os_??? modules we have no corresponding source for either
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1098 version, but the vsi_tim difference is more bizarre: we got our vsi_tim.c source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1099 (and the rest of vsi_*.c) from the TCS3.2/LoCosto source, but this source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1100 matches the TCS211 binary version and not the newer and different binary version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1101 used by the TCS3.2 build system! (Remember that none of TI's firmware build
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1102 systems that we have seen are set up to recompile any part of GPF from source,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1103 they used it only as prebuilt libraries.)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1104
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1105 Because we have the corresponding source for the "old" version of GPF frame core
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1106 but not for the "new" version, we are continuing to treat the "old" TCS211
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1107 version as our golden reference: we use the source pieces which we got, and we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1108 use the "old" os_???.obj blobs as our basis for reconstruction via disassembly.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1109
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1110 Because the changes in the TCS3.2 binary version of GPF involve only the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1111 implementation of a part of VSI but not its API (there are no changes to any
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1112 part of the GPF API presented to the G23M PS that I can see anywhere), I have
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1113 every good reason to believe that there is no problem with using the new TCS3.2
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1114 version of G23M with the old version of GPF from TCS211: it should work no worse
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1115 than pure TCS211.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1116
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1117 It should also be noted that if we ever succeed in getting some more complete
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1118 GPF source out of TI (including the source for the OS adaptation layer which is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1119 difficult to reconstruct), thanks to the great stability and independence of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1120 GPF, we will be happy with *any* version, does not need to match either TCS211
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1121 or TCS3.2.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1122
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1123 GPRS implementation differences
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1124 -------------------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1125
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1126 There is a visible difference between the way GPRS is implemented in the old
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1127 TCS211-20070608 blob version of G23M and the way it is implemented in the newer
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1128 TCS3.2/LoCosto version we are using for our hybrid. The new implementation adds
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1129 a new protocol stack entity named UPM (User Plane Manager), and the pre-existing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1130 SM and SNDCP entities have been significantly changed to work with this UPM.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1131 Because we are using the GPRS config modules (condat/frame/config) from TCS211,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1132 we had to add a -DFF_UPM compilation flag to include UPM in the GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1133 configuration for the GSM+GPRS protocol stack.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1134
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1135 A closer look at ACI
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1136 ====================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1137
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1138 The Application Control Interface (ACI) is the crown that sits on top of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1139 G23M protocol stack. It includes the AT command interpreter (ATI) component,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1140 and this AT command interface is brought to the outside world via the UART
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1141 protocol stack entity. The UART entity implements the GSM 07.10 MUX, can
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1142 operate the physical UART in either multiplexed or non-multiplexed mode (the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1143 latter is the default on boot for a plain ASCII AT command interface) as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1144 commanded by ACI, and establishes 1 to 4 logical channels carrying AT commands
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1145 to ACI. When a CSD or fax call or a GPRS PPP session is in progress, the data
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1146 path is switched to run between the UART entity and the appropriate GSM or GPRS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1147 protocol stack destination. In the case of modem products that are designed to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1148 be controlled by an external host via AT commands, this combination of ACI and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1149 UART entities provides the ultimate end function of the device.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1150
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1151 The set of implemented AT commands is defined in ati_cmd.c: this is the C file
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1152 where new AT commands get added; there is also an enum of command IDs in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1153 aci_cmh.h which needs to be extended. For every AT command listed in the table
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1154 in ati_cmd.c there is a handler function: for example, for the AT+CFUN command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1155 there is a setatPlusCFUN() function that handles setting and a queatPlusCFUN()
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1156 function that handles querying. For some simple AT commands like AT+CGxx
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1157 queries the function listed in ati_cmd.c does the entirety of the work, but for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1158 most of the interesting GSM commands (including the AT+CFUN example just used)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1159 the set and query functions implemented in the ATI layer only handle the parsing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1160 of ASCII arguments and generation of ASCII output (if any), whereas the actual
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1161 command implementation happens in the CMH layer below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1162
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1163 Below ATI but still within ACI lies the sublayer of command handlers (CMH).
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1164 For each AT command that does something to the GSM mobile station there is a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1165 functional equivalent, a C function that performs the same operation as the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1166 spec-defined AT command, but is designed to be used natively from C code,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1167 without AT command string parsing or output formatting. For the AT+CFUN example
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1168 used above, the setatPlusCFUN() ATI function parses the arguments from ASCII
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1169 and then calls sAT_PlusCFUN() to perform the actual operation, whereas the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1170 queatPlusCFUN() ATI function calls qAT_PlusCFUN() to retrieve the current state
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1171 and then prints it out in ASCII. This functional interface is used by TI's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1172 demo/prototype phone UI implementation described in the Handset-UI-fw companion
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1173 document.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1174
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1175 Finally, at the bottom of ACI lies the sublayer of Protocol Stack Adapters
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1176 (PSA): these are pieces of code that execute within the ACI task and exchange
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1177 primitives with various G23M protocol stack entities below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1178
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1179 We have the source for both TCS2 and TCS3 versions of ACI. The TCS2 version is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1180 from Openmoko, containing OM's modifications, and we had to go through these
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1181 changes and additions by OM, reject the bogus ones and reimplement the sensible
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1182 ones in the new TCS3 version of ACI for our TCS2/TCS3 hybrid going forward.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1183
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1184 Flash file system
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1185 =================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1186
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1187 Every GSM device that is based on TI's firmware architecture contains not only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1188 the firmware image proper, but also a flash file system that is separate from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1189 the fw image and is maintained in a different part of the flash chip. The FFS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1190 implementation code is a mandatory part of the firmware; in TCS211 it resides
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1191 in chipsetsw/drivers/drv_app/ffs and logically belongs to the SSA realm. This
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1192 code initializes early in the fw boot process in the Application_Initialize()
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1193 context before the start of Nucleus task scheduling; the responsible function
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1194 is ffs_main_init() called from Init_Drivers().
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1195
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1196 Flash driver support and FFS location
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1197 -------------------------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1198
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1199 Determining the location of the flash area allocated for FFS and the flash
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1200 driver to be used to write to it is a combination of autodetection and hard-
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1201 coding. The approach implemented in the original TCS211 code is as follows:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1202 there is a piece of autodetection code that reads the flash chip ID, and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1203 autodetected ID is then looked up in a hard-coded table that gives the driver
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1204 and geometry details and the location of the FFS sectors for each supported
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1205 flash chip type. However, this approach has its limitations:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1206
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1207 * The sequence of write operations which TI's original autodetection code
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1208 issues in order to put the flash chip into its Read ID mode worked for older
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1209 flash chips that were used by TI and Openmoko, but does not work for the newer
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1210 Spansion S71PL129NC0HFW4B flash chip which we (FreeCalypso) have copied from
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1211 the Pirelli DP-L10 phone. We have now fixed it, but until recently we had to
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1212 disable flash autodetection and hard-code the flash chip type on Pirelli and
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1213 FCDEV3B targets.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1214
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1215 * While the physical flash chip used on a given phone or modem board is a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1216 physical property that can be autodetected, the choice of which flash sectors
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1217 should be used for FFS is a matter of policy. Before we built our own
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1218 FreeCalypso hardware, we had to run our fw on some pre-existing "alien" hw
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1219 targets, and we still support such usage to a limited extent. When we run
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1220 our FreeCalypso fw on an alien hw target as an aftermarket deal, our
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1221 aftermarket FFS location needs to be chosen quite carefully.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1222
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1223 * Some flash chips have two chip select banks, and with such chips it is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1224 generally desirable to put the FFS in the second bank. However, it is a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1225 matter of board wiring whether that second flash chip select is connected to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1226 Calypso chip select nCS2, nCS3 or nCS4 - thus FFS addresses in the second bank
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1227 have to be hard-coded with conditional compilation per board type and cannot
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1228 be autodetected.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1229
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1230 To support our new repertoire of possible hardware targets, we have made the
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1231 following changes in our Magnetite and Selenite firmwares:
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1232
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1233 * We have a new version of the ffsdrv_device_id_read() autodetection function
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1234 that issues AMD's Read ID command sequence in a way that works with all flash
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1235 chips which we've encountered so far in real life, including Openmoko's
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1236 Samsung K5A3281 and our new (originally Pirelli's) Spansion flash chip. We
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1237 have also incorporated the logic from Pirelli's firmware that distinguishes
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1238 between S71PL-J and S71PL-N chips: they have different sector sizes which FFS
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1239 needs to know about, but they have the same ID codes and can only be
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1240 distinguished through CFI.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1241
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1242 * The autodetected flash ID code is looked up in a compiled-in table like
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1243 before, but we now have 4 different versions of this table selected by
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1244 conditional compilation based on the target for which the firmware is being
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1245 built:
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1246
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1247 - For our own FC hardware family (CONFIG_TARGET_FCFAM) we have our brand-new
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1248 table of possible flash configurations which we keep free of any legacy
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1249 gunk;
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1250
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1251 - For Mot C1xx targets (CONFIG_TARGET_COMPAL) we have a dedicated table
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1252 giving our aftermarket FFS configurations for Intel flash chip types found
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1253 in these phones;
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1254
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1255 - For the Pirelli DP-L10 target (CONFIG_TARGET_PIRELLI) we likewise have
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1256 another dedicated table giving our aftermarket FFS config for Pirelli's
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1257 S71PL-J or S71PL-N flash;
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1258
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1259 - The #else clause is the original table from TI/Openmoko, used on
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1260 dsample and gtamodem targets.
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1261
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1262 The advantages of this new approach over our previous approach of disabling
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1263 flash autodetection and using a strictly fixed hard-coded FFS config for
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1264 FreeCalypso and Pirelli targets are:
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1265
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1266 * The high-capacity flash chip we are currently using (S71PL129NC0HFW4B) is
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1267 great for development boards or perhaps for a high-end Pirelli-like feature
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1268 phone, but it would be way overkill for an embedded modem product - for the
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1269 latter device class a smaller flash chip like Openmoko's K5A32xx would be
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1270 more appropriate. The new autodetection approach makes it possible to build
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1271 a single fw image that can run on both large-flash and small-flash boards.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1272
9
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1273 * I've only seen Pirelli phones with S71PL-N flash so far, but their original
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1274 fw supports both S71PL-J and S71PL-N with autodetection. We can now do
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1275 likewise in our FreeCalypso fw.
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1276
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1277 Finally, independent of flash chip type autodetection vs. hard-coding issues,
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1278 we have had to change the AMD multibank flash driver to issue write commands in
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1279 a way that is compatible with our new S71PL129NC0HFW4B chip. It still works
5de1f72ce941 TCS211-fw-arch: flash chip type autodetection reinstated
Mychaela Falconia <falcon@freecalypso.org>
parents: 0
diff changeset
1280 just as well with Openmoko's K5A32xx.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1281
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1282 FFS life cycle
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1283 --------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1284
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1285 In products that have been built according to TI's original way, including
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1286 Openmoko GTA01/02 and our own FreeCalypso devices, the FFS is formatted and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1287 initialized with some essential content at the time of device manufacture, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1288 this factory-created and factory-initialized FFS then persists for the lifetime
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1289 of the device. In our factory environment at FreeCalypso hardware manufacturing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1290 we initialize the flash on our freshly assembled boards like this:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1291
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1292 flash erase 0 0x800000
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1293 flash program-bin 0 fwimage.bin
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1294 flash2 erase 0 0x800000
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1295
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1296 This factory procedure (which should ONLY be executed at the factory and never
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1297 by any end users or even sw/fw developers and tinkerers) ensures that the flash
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1298 is completely blank everywhere except the fw image loaded at the time of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1299 production, and when this fw image boots for the first time, it will see blank
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1300 flash in the FFS sectors. When TI's FFS code in ffs_main_init() sees this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1301 condition, it performs what TI called a preformat: it writes a basic FFS block
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1302 header into each FFS sector, but does not automatically perform a full format -
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1303 instead the latter needs to be commanded explicitly by the production station
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1304 via one of TMFFS command packet protocols as described later in this article.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1305 In FreeCalypso we have adopted TMFFS2 as our choice of Test Mode FFS access
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1306 protocol, our host side implementation of this protocol is fc-fsio, and we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1307 format and initialize the FFS on our devices with an fc-fsio command script as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1308 part of our factory procedure.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1309
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1310 FFS content and usage
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1311 ---------------------
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1312
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1313 TI's firmware architecture uses the FFS for many purposes:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1314
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1315 * The IMEI is stored in the FFS - GSMA can proclaim all they want that it
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1316 "MUST" be stored in some kind of super-secure one-time programmable fuses,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1317 but in TI's architecture and in FreeCalypso it is just a regular file in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1318 FFS.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1319
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1320 * A number of RF calibration tables are stored in FFS and read by the RF code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1321 in L1. If you have a Rohde&Schwarz CMU200 instrument which is itself in good
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1322 repair and calibration standing and a metrology-grade RF cabling setup whose
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1323 insertion loss at the relevant GSM frequencies is precisely known, creating
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1324 or recreating these RF calibration values is as simple as executing one shell
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1325 script that takes a few minutes to run - this is how we do it at FreeCalypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1326 hw manufacturing - but if you are an ordinary user or sw/fw developer or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1327 tinkerer without a professional calibration station setup, you need to use
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1328 the RF calibration values that have been written into the FFS by the device
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1329 manufacturer. These RF calibration tables live under /gsm/rf.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1330
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1331 * /gsm/com/rfcap tells the RR component in the G23M protocol stack (not L1!)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1332 which frequency bands are supported on a given device - on our devices it is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1333 a factory-programmed file distinguishing between tri900 and tri850 units and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1334 telling the firmware which bands it should scan for possible GSM cells.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1335
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1336 * Manufacturer, model and revision ID strings may be written into /pcm/CGMI,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1337 /pcm/CGMM and /pcm/CGMR, respectively, to be returned by the corresponding
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1338 AT+CGxx query commands.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1339
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1340 * The G23M protocol stack writes a number of dynamically updated files under
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1341 the /gsm hierarchy and under /pcm.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1342
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1343 * TI's demo/prototype UI code (see Handset-UI-fw companion document) writes its
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1344 persistent state in files under /mmi.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1345
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1346 * Audio mode configuration files are kept under /aud - see the Audio-mode-config
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1347 article in freecalypso-tools.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1348
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1349 * If a given product uses the Melody E1 mechanism, melody files to be played
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1350 through the RiViera Audio Service are kept in FFS - see the Melody_E1 article
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1351 in freecalypso-tools.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1352
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1353 Building firmware for different targets
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1354 =======================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1355
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1356 TI's TCS3.2 firmware for their LoCosto chipset which was rejected by the Mother
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1357 for reasons described near the beginning of this article makes a complete break
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1358 from the past and has no possibility of supporting any pre-LoCosto chips such
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1359 as our beloved Calypso, but TI's previous evolutionary developments weren't so
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1360 drastic: the evolution to Calypso from previous chips such as Hercules and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1361 Ulysse was smoother, and our reference TCS211 fw is littered with C preprocessor
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1362 conditionals supporting TI's earlier development boards prior to D-Sample and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1363 DBB chips prior to Calypso.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1364
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1365 TI's configuration management architecture supported only TI's own development
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1366 boards and not any of the end product boards: unfortunately they did not follow
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1367 a development model like the Linux kernel where everyone is encouraged to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1368 contribute their custom board support bits upstream and the mainline kernel
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1369 strives to support every hw target that was ever supported with a single source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1370 tree, instead it was the divergent model where every end device manufacturer
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1371 would take TI's reference firmware source and hack it for their specific needs
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1372 with no concern for upstreamability or support for targets or applications
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1373 other than their own. TI's firmware build configuration model defined the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1374 following C preprocessor symbols relating to support for different hw targets,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1375 all numeric, i.e., each symbol is always defined to a number:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1376
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1377 BOARD identifies which board is to be targeted, with numbers assigned for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1378 different development boards made by various TI groups, but generally not for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1379 customer boards. The only Calypso-based BOARD number is 41, originally
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1380 assigned for the D-Sample but then also reused for the Leonardo; all other
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1381 BOARD numbers are for some other chipsets that aren't Calypso. The previous
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1382 board before D-Sample was C-Sample, which is BOARD 9, but I am not sure exactly
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1383 what chipset it had - perhaps it was Ulysse/Nausica/Clara. There is still
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1384 plenty of support for BOARD 9 and even earlier boards in the firmware source we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1385 got.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1386
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1387 CHIPSET identifies the main DBB chip. The interesting numbers are 7 for the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1388 very original Calypso C05 rev A, 8 for Calypso C05 rev B (found on the D-Sample
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1389 board which the Mother scored in 2015), 10 for Calypso C035 (the Calypso silicon
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1390 version we work with in FreeCalypso), 11 for Calypso Lite (same as the regular
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1391 Calypso except for smaller IRAM), 12 for Calypso+ (a short-lived intermediate
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1392 step between Calypso and LoCosto) and 15 for LoCosto.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1393
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1394 ANLG_FAM (previously ANALOG) identifies the ABB chip. The numbers are 1 for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1395 Nausica, 2 for Iota (what we use) and 3 for Syren (typically used with Calypso+
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1396 like on the E-Sample board).
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1397
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1398 RF_FAM (previously just RF) identifies the RF hardware hooked up to the baseband
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1399 chipset. The interesting numbers are 10 for Clara (D-Sample) and 12 for Rita,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1400 the latter being the only RF chip for which we have driver support.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1401
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1402 Naturally any code that cares about DBB register differences would use the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1403 CHIPSET definition, ABB support code would use ANLG_FAM, RF support code would
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1404 use RF_FAM, and finally code that needs to know about board-level peripherals
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1405 like LCDs and keypads would use the BOARD symbol. This model worked fine up to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1406 D-Sample: for example, the code for C-Sample vs. D-Sample LCDs and keypads is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1407 cleanly conditionalized on BOARD 9 vs. BOARD 41. However, the waters got badly
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1408 muddied when TI introduced their Leonardo board and instead of giving it its
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1409 own BOARD number, reused BOARD number 41 from D-Sample.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1410
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1411 D-Sample was TI's primary internal development platform for the Calypso,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1412 featuring Iota for the ABB and Clara for the RF part. It was a great solid
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1413 platform in every way except the RF part: the old Clara RF is inconvenient
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1414 (needs more external parts) and TI were marketing their newer Rita RF to real
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1415 end device manufacturers, but the D-Sample still worked great for development:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1416 if you aren't working specifically on the RF part, it doesn't matter as long as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1417 you have a working driver for it, which we lack. Then TI made another Calypso
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1418 development board called Leonardo, featuring the same Calypso+Iota baseband
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1419 plus the newer Rita RF. But this Leonardo never fully replaced the D-Sample
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1420 for any of the high-level development in the SSA and UI groups.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1421
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1422 Openmoko's modem is a direct derivative of the Leonardo, the only change being
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1423 the RFFE (for some reason FIC didn't like TI's quadband RFFE as implemented on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1424 Leonardo and E-Sample boards and used their own slightly hobbled triband RFFE
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1425 instead), and the firmware build given to OM was TI's Leonardo fw with just a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1426 few tweaks in tpudrv12.h to account for the RFFE control signal differences.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1427 However, because Leonardo never got its own BOARD number and the BOARD symbol
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1428 is still set to 41, all of the SSA/UI code (LCD, keypad, battery charging etc)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1429 is still built as if for D-Sample - but none of that code is used on a pure AT
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1430 command modem without UI functions or UI hardware, hence OM probably never
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1431 noticed anything odd.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1432
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1433 And it wasn't just Openmoko - it appears that TI used their Leonardo boards
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1434 mostly or perhaps even solely in the ACI configuration without UI layers
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1435 (MMI=0 build configuration), while all or most UI development was done on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1436 D-Sample kits. Their TCS211 reference fw product officially supported both
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1437 D-Sample and Leonardo targets in both ACI and BMI+MFW configurations, but if
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1438 one were to build a high-end UI-enabled config for the Leonardo like pdt_2272,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1439 it would target a 176x220 pixel color LCD, the LCD output driver would be the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1440 one for the D-Sample (expecting memory-mapped LCD registers on nCS3), and the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1441 keypad driver would expect D-Sample keypad wiring. Looking at the available
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1442 Leonardo schematics I see a serial (uWire) LCD interface instead and a more
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1443 basic keypad with different wiring, so I don't see how those Leonardo+UI
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1444 firmware builds could possibly work. Perhaps some other group at TI did some
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1445 UI work on Leonardo boards, but never made it into the internal mainline
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1446 from which TCS211 releases were cut - who knows...
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1447
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1448 Finally, aside from the basic failure to distinguish properly between D-Sample
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1449 and Leonardo boards, this whole BOARD number system provides absolutely no
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1450 mechanism to distinguish between TI's development boards and end product boards
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1451 derived from them, or between end product boards of vendor A vs. vendor B, or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1452 between end product model A and model B from the same vendor - it's always
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1453 BOARD 41 as far as TI's code is concerned. When TI had to modify their code
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1454 for OM to support FIC's different TSPACT signal wiring, they just edited the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1455 definitions in tpudrv12.h without any conditionals, so one couldn't build
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1456 binaries for the original Leonardo vs. OM's hardware from the same source tree
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1457 in different configs.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1458
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1459 The build system of TCS211 produces a set of generated C header files named
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1460 *.cfg (instead of the more natural *.h); these generated config headers define
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1461 all of the C preprocessor symbols listed above and many more. They are included
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1462 sometimes as #include "board.cfg" and othertimes as #include "config/board.cfg"
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1463 (ditto for other *.cfg), thus the list of -I directories passed by the build
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1464 system on compiler invocation lines needs to include both the config directory
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1465 and its parent. In our Magnetite and Selenite build systems we likewise
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1466 generate these *.cfg headers; some of the symbols defined therein are variable
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1467 and originate from Bourne shell variables in our own configuration system, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1468 many others are fixed. See scripts/cfg-template in our Magnetite and Selenite
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1469 trees for the magic.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1470
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1471 The BOARD symbol is always fixed at 41 in all FreeCalypso firmwares,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1472 corresponding to TI's D-Sample and Leonardo, and we use our own different
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1473 mechanism to distinguish among our supported targets. The solution adopted in
14
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1474 Magnetite and Selenite is as follows: we are supplementing TI's *.cfg and
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1475 rv_swe.h files with our own fc-target.h (included as #include "fc-target.h" or
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1476 as #include "config/fc-target.h" matching whatever existing TI code we are
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1477 gently extending), and this fc-target.h header is populated by the build system
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1478 by copying the appropriate targets/*.h header file. These targets/*.h
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1479 header snippets define C preprocessor symbols of our own invention like
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1480 CONFIG_TARGET_xxx, and whenever we need to know our target in C code, we
14
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1481 #include "fc-target.h" and use #ifdef logic based on these preprocessor symbols
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1482 of our own addition.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1483
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1484 RVTMUX debug and development interface
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1485 ======================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1486
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1487 The Calypso chip has two UARTs, and TI's TCS211 firmware and its predecessors
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1488 are designed with the assumption that both of these UARTs are available. Per
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1489 TI's fw architecture, Calypso's MODEM UART presents the standard AT command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1490 interface with GSM 07.10 MUX, CSD, fax and GPRS capabilities as described
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1491 earlier when we looked at ACI and ATI, whereas the other UART (called the IrDA
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1492 UART in hardware docs but not used for that purpose) presents a vitally
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1493 important debug, development and production interface called RVTMUX. This
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1494 RVTMUX interface can also be moved to the MODEM UART, in which case the standard
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1495 AT command interface is lost.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1496
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1497 RVTMUX is a binary packet interface, and it got its name because it is a MUX of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1498 multiple logical channels managed by the RiViera Trace (RVT) firmware component.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1499 RVTMUX is often thought of as being primarily a debug trace interface, as that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1500 is the primary use to which it is put: in normal operation the firmware emits
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1501 quite voluminous debug trace output on the IrDA UART, encapsulated in 3
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1502 different RVTMUX channels as explained below. However, it is also possible to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1503 send a number of different debug and development commands to the firmware via
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1504 this interface, and this functionality is used as a critical component in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1505 Calypso GSM device factory production line processes: this RVTMUX interface is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1506 the only way by which the FFS can be initialized, RF calibration and tests can
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1507 be performed and the IMEI can be set at the factory.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1508
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1509 Communication with a running firmware over this RVTMUX interface in a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1510 development or production setting (whether passively reading debug traces or
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1511 actively sending development or test commands to the running fw) requires
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1512 specialized host tools. TI originally had a suite of Windows-based tools for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1513 this purpose, but we are not using them in FreeCalypso: we only got Windows
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1514 binaries without any sources, and even in the case of those binaries we only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1515 got an incomplete set with some important tools missing. Instead we are using
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1516 our own Unix-based tools called FreeCalypso host tools; these tools have been
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1517 developed from scratch by Mother Mychaela after studying the firmware components
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1518 with which they need to communicate.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1519
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1520 Debug trace output
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1521 ==================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1522
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1523 The firmware component that "owns" the physical UART channel assigned to RVTMUX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1524 is RVT, contained in chipsetsw/riviera/rvt in TCS211 or in src/cs/riviera/rvt
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1525 in our Magnetite and Selenite firmwares. It is a Riviera-based component,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1526 and it has a Nucleus task that is created and started through Riviera. All
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1527 calls to the actual driver for the UART are made from RVT. In the case of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1528 output from the Calypso GSM device to an external host, all such output is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1529 performed in the context of RVT's Nucleus task; this task drains RVT's message
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1530 queue and emits the content of allocated buffers posted to it, freeing them
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1531 afterward. (The dynamic memory allocation system in this case is Riviera's,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1532 which is susceptible to fragmentation - see discussion earlier in this article.)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1533 Therefore, every trace or other output packet emitted from a GSM device running
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1534 our fw (or any of the proprietary firmwares based on the same architecture)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1535 appears as a result of a message in a dynamically allocated buffer having been
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1536 posted to RVT's queue.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1537
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1538 RVT exports several API functions that are intended to be called from other
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1539 tasks, it is by way of these functions that most output is submitted to RVT.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1540 One can call rvt_send_trace_cpy() with a fully prepared output message, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1541 that function will allocate a buffer from Riviera's dynamic memory allocator
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1542 properly accounted to RVT, fill it and post it to the RVT task's queue.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1543 Alternatively, one can call rvt_mem_alloc() to allocate the buffer, fill it in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1544 and then pass it to rvt_send_trace_no_cpy().
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1545
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1546 At higher levels, there are a total of 3 kinds of debug traces that can be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1547 emitted:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1548
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1549 * Riviera traces: these are generated by various components implemented in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1550 Riviera land, although in reality any component can generate a trace of this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1551 form by calling rvf_send_trace() - this function can be called from any task.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1552
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1553 * L1 traces: L1 has its own trace facility implemented in
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1554 src/cs/layer1/cfile/l1_trace.c; it generates its traces as ASCII messages and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1555 sends them out via rvt_send_trace_cpy().
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1556
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1557 * GPF traces: code that runs in GPF/G23M land and uses those header files and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1558 coding conventions etc can emit traces through GPF. GPF's trace functions
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1559 (implemented in gpf/frame/vsi_trc.c) allocate a memory partition from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1560 GPF's TEST pool, format the trace into it, and send the trace primitive to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1561 GPF's special test interface task. That task receives trace and other GPF
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1562 test interface primitives on its queue, performs some manipulations on them,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1563 and ultimately generates RVT trace output, i.e., a new dynamic memory buffer
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1564 is allocated in the Riviera land, the trace is copied there, and the Riviera
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1565 buffer goes to the RVT task for the actual output.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1566
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1567 Trace masking
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1568 =============
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1569
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1570 The RV trace facility invoked via rvf_send_trace() has a crude masking ability,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1571 but by default all traces are enabled. In TI's standard firmwares most of the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1572 trace output comes from L1: L1's trace output is very voluminous, and most of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1573 it is fully enabled by default.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1574
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1575 On the other hand, GPF and therefore G23M traces are mostly disabled by default.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1576 One can turn the trace verbosity level from any GPF-based entity up or down by
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1577 sending a "system primitive" command to the running fw, and another such command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1578 can be used to save these masks in FFS, so that they will be restored on the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1579 next boot cycle and be effective at the earliest possible time. Enabling *all*
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1580 GPF trace output for all entities is generally not useful though, as it is so
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1581 verbose that a developer trying to make sense of it will likely drown in it -
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1582 and it will also overwhelm the debug trace facility itself, causing most of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1583 these far too voluminous traces to be lost. Therefore, a developer seeking to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1584 debug an issue in the G23M protocol stack needs to enable traces very
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1585 judiciously.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1586
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1587 GPF compressed trace hack
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1588 =========================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1589
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1590 TI's Windows-based GSM firmware build systems include a hack called str2ind.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1591 Seeking to reduce the fw image size by eliminating trace ASCII strings from it,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1592 and seeking to reduce the load on the RVTMUX serial interface by eliminating
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1593 the transmission time of these strings, they passed their sources through an
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1594 ad hoc preprocessor that replaces these ASCII strings with numeric indices.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1595 The compilation process with this str2ind hack becomes very messy: each source
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1596 file is first passed through the C preprocessor, then the intermediate form is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1597 passed through str2ind, and finally the de-string-ified form is compiled, with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1598 the compiler being told not to run the C preprocessor again.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1599
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1600 TI's str2ind tool maintains a table of correspondence between the original trace
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1601 ASCII strings and the indices they've been turned into, and a copy of this table
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1602 becomes essential for making sense of GPF trace output: the firmware now emits
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1603 only numeric indices which are useless without this str2ind.tab mapping table.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1604
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1605 Our FC Magnetite build system retains the option of using str2ind, but it is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1606 disabled by default: str2ind significantly increases firmware compilation times,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1607 the resulting fw image sizes without str2ind are fine (the slight increase does
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1608 not push us over any limits), and we haven't had any issues with ASCII strings
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1609 overloading the trace interface. However, there is an additional complication
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1610 stemming from the choice of two possible G23M PS versions, one of which is a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1611 set of blob libraries:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1612
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1613 * If Magnetite is compiled in a pure TCS211 configuration using the original
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1614 blob version of G23M PS, these blobs already have str2ind indices baked into
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1615 them instead of trace ASCII strings, hence the frozen str2ind.tab file from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1616 Openmoko that maps these indices back to strings needs to be used.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1617
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1618 * If Magnetite is compiled in a TCS2/TCS3 hybrid config without G23M blobs,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1619 then unless you enable it explicitly with USE_STR2IND=1, no str2ind will be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1620 used at all.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1621
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1622 Our blob-free FC Selenite firmware does not support str2ind at all - we shall
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1623 stick with full ASCII string traces until and unless we run into an actual (as
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1624 opposed to hypothetical) problem with either fw image size or serial interface
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1625 load.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1626
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1627 RVTMUX command input
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1628 ====================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1629
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1630 RVTMUX is not just debug trace output: it is also possible for an external host
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1631 to send commands to the running fw via RVTMUX.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1632
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1633 Inside the fw RVTMUX input is handled by the RVT entity by way of a Nucleus
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1634 HISR. This HISR gets triggered when Rx bytes arrive at the designated UART,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1635 and it calls the UART driver to collect the input. RVT code running in this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1636 HISR parses the message structure and figures out which fw component the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1637 incoming message is addressed to. Any fw component can register to receive
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1638 RVTMUX packets, and provides a callback function with this registration; this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1639 callback function is called in the context of the HISR.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1640
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1641 In the original TCS211 fw there are only two components that register to receive
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1642 external host commands via RVTMUX: ETM and GPF, hence these are the only command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1643 packet types that can be sent to this original fw. In FreeCalypso we have kept
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1644 these, and we've also added some new RVTMUX channels of our own invention.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1645
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1646 Test Mode (TM) and Enhanced Test Mode (ETM)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1647 ===========================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1648
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1649 A major use of the RVTMUX interface is sending so-called Test Mode commands
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1650 from an external host to a running GSM device. Depending on the firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1651 version, a GSM device can be commanded to do any of the following things
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1652 through this mechanism:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1653
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1654 * Exercise RF test modes, e.g., transmit continuously at a set frequency and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1655 power level;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1656 * Read and write arbitrary memory locations in the Calypso ARM7 address space;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1657 * Read and write ABB chip registers;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1658 * Reboot or power off;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1659 * Access and manipulate the device's flash file system (FFS).
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1660
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1661 In the segment of history of interest to us TI has produced two different
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1662 target firmware components that can receive, interpret and act upon Test Mode
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1663 command packets:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1664
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1665 * The original Test Mode component of Layer 1, called L1TM or TML1: this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1666 component handles all RF test modes (needed for RF calibration on device
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1667 production lines), and originally it also implemented memory and ABB register
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1668 read and write commands, and provided access to TMFFS1 (see below). In the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1669 original implementation this component registered itself as the handler for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1670 the "TM" RVTMUX channel (RVT packet type 0x14), so it would receive all TM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1671 packets sent to the device.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1672
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1673 * Enhanced Test Mode (ETM) is a later invention. It registers itself (instead
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1674 of the old TM in L1) with RVT as the handler for the "TM" RVTMUX channel, and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1675 then provides a registration service of its own, such that various components
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1676 in the fw suite can register to receive external command packets passing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1677 first through RVT, then through ETM, and can send responses passing through
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1678 ETM, then through RVT back to the external host. If a given fw version
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1679 contains both ETM and L1TM like TCS211 does, then L1TM registers itself with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1680 ETM; an external host would send exactly the same binary command packets to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1681 exercise RF test modes, but inside the firmware they now pass through ETM on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1682 their way to L1TM.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1683
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1684 The ETM_CORE module contained within ETM itself provides some low-level debug
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1685 commands: by sending the right binary command packets to the GSM device via the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1686 RVTMUX serial channel, an external host can examine or modify any memory
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1687 location and any hardware register, cause the device to reset, etc. Prior to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1688 ETM some of these functions (but not all) could be exercised through older TM3
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1689 commands, but in FreeCalypso we became familiar with the ETM versions of these
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1690 commands long before the older ones because we got the ETM component in full
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1691 source form, whereas the sole surviving copy of TCS211 that serves as our golden
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1692 reference came with L1TM in binary object form like the rest of L1, and we got
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1693 to source-reconstructing it only much later.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1694
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1695 ETM is implemented as a Riviera SWE and has its own Nucleus task; the callback
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1696 function that gets called from the RVT HISR posts received messages onto ETM's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1697 own queue drained by its task. The ETM task gets scheduled, picks up the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1698 command posted to its queue, executes it, and sends a response message back to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1699 the external host through RVT.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1700
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1701 Because all ETM commands funnel through ETM's queue and task, and that task
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1702 won't start looking at a new command until it finished handling the previous
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1703 one, all ETM commands and responses are in strict lock-step: it is not possible
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1704 to send two commands and have their responses come in out of order, and it makes
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1705 no sense to send another ETM command prior to receiving the response to the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1706 previous one. (But there can still be debug traces or other traffic intermixed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1707 on RVTMUX in between an ETM command and the corresponding response!)
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1708
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1709 L1TM commands get posted to the message queue of the L1A task and then executed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1710 in that task's context.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1711
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1712 FFS access via TM/ETM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1713 =====================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1714
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1715 One of the essential facilities provided in one form or another in all known
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1716 incarnations of the Test Mode mechanism (at least in TI's original architecture,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1717 as opposed to Motorola's bastardized version) is the ability to access and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1718 manipulate the GSM device's flash file system (FFS) that was described earlier
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1719 in this article. TI's TMFFS1 and TMFFS2 protocols provide a command and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1720 response packet interface to the FFS API functions inside the fw, and enable an
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1721 external host connected to the GSM device via the RVTMUX channel to perform
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1722 arbitrary read and write operations on the device file system.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1723
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1724 In the segment of history of interest to us TI has produced two different
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1725 and entirely incompatible versions of the TMFFS protocol: TMFFS1 and TMFFS2.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1726 Or rather, what is now called TMFFS1 was originally just TMFFS, and then came
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1727 TMFFS2. TMFFS2 works only through ETM, whereas TMFFS1 predates ETM: in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1728 original implementation the tm_ffs() function in the FFS code was called from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1729 L1TM code.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1730
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1731 Our copy of TCS211 reference fw includes the source for both TMFFS1 and TMFFS2;
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1732 it is theoretically possible to build a firmware image that includes both TMFFS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1733 versions (they won't conflict because they respond to different command
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1734 packets), but it is pretty clear that TI never intended to have both enabled
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1735 at the same time. Our copy of TCS211 came with TMFFS1 enabled and we didn't
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1736 change it when we made the moko12 (leo2moko-r1) fw release for the Openmoko
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1737 community (the previous proprietary mokoN firmwares also implement TMFFS1),
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1738 but we have subsequently switched to TMFFS2 for our current Magnetite and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1739 Selenite firmwares.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1740
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1741 Our choice of TMFFS2 over TMFFS1 was driven by the need to develop our own host
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1742 tools to replace TI's original ones which we never got. We needed to develop
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1743 our own host tools for operating on GSM device FFS via one of the two TMFFS
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1744 protocols, and after studying the fw source implementing both, I (Mother
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1745 Mychaela) came to the conclusion that TMFFS2 is both more capable and more
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1746 reliable; my guess is that TMFFS1 was likely kept around only because some of
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1747 TI's crappy Weendoze host software depended on it. (See the implementation
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1748 code in chipsetsw/drivers/drv_app/ffs/board/tmffs.c in TCS211 if you would like
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1749 to judge for yourself.) Our host tool that speaks the TMFFS2 protocol is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1750 fc-fsio.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1751
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1752 GPF external command input
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1753 ==========================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1754
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1755 The other component that can receive external commands is GPF. GPF's test
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1756 interface can receive so-called "system primitives", which are ASCII string
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1757 commands parsed and acted upon by GPF, and also binary protocol stack
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1758 primitives. Remember how all entities in the G23M stack communicate by sending
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1759 messages to each other? Well, GPF's test interface allows such messages to be
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1760 injected externally as well, directed to any entity in the running fw. System
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1761 primitive commands can also be used to cause entities to send their outgoing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1762 primitives to the test interface, either instead of or in addition to the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1763 originally intended recipient.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1764
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1765 AT commands over RVTMUX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1766 =======================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1767
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1768 There is one more use to which we put the RVTMUX debug serial interface that is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1769 an original FreeCalypso invention: communicating with the AT command interpreter
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1770 (ATI). TI's original architecture assumes that if a product is to offer a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1771 standard AT command interface (the product is either a GSM/GPRS modem for which
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1772 this AT command interface is the sole mode of usage or a feature phone that
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1773 offers a data port as one of its features), then it will be presented on a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1774 dedicated UART separate from RVTMUX.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1775
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1776 However, in the case of our FreeCalypso family of projects about 2 years had
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1777 passed between our first functional GSM fw attempts in 2015 and us successfully
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1778 building our own development board in 2017; during this time we had to work on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1779 various crippled pre-existing Calypso devices, and many of them had only one
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1780 UART practically accessible. In response to this situation we developed a way
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1781 to pass AT commands over RVTMUX. We created a new RVTMUX channel for this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1782 interface and assigned it RVT packet type 0x1A. Packets sent from an external
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1783 host to the GSM device carry AT commands and SMS string input, whereas packets
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1784 flowing the other way carry ATI's responses to commands and asynchronous
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1785 notifications such as incoming calls. The host utility for talking AT commands
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1786 to a FreeCalypso GSM device via RVTMUX is fc-shell, described below.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1787
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1788 Now that we have built a proper FreeCalypso development board with two UARTs,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1789 the use of this AT-over-RVTMUX hack is deprecated for general usage: this hack
14
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1790 does not support any data services (CSD or GPRS), and even for SMS it was
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1791 crippled for a long time because maximum-length messages could not be sent in
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1792 the more capable PDU mode until our recent extension that works around this
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1793 limitation. However, it still comes in handy during certain casual testing
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1794 sessions, and it is required if one needs to run our FreeCalypso firmware on
f5ddeacbe744 TCS211-fw-arch: change from fc-target.cfg to fc-target.h
Mychaela Falconia <falcon@freecalypso.org>
parents: 9
diff changeset
1795 Mot C1xx or Pirelli DP-L10 hardware.
0
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1796
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1797 FC host tools for talking to firmwares via RVTMUX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1798 =================================================
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1799
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1800 The fundamental tool for talking to running firmwares via RVTMUX is a program
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1801 called rvinterf. It runs on a Unix/Linux host machine, opens a serial port
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1802 that is expected to be connected to the RVTMUX UART on the target, and then
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1803 speaks TI's binary packet protocol on that serial port. It then performs two
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1804 functions:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1805
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1806 * If rvinterf is run in the foreground in a terminal window (or more precisely,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1807 if its default terminal output is not disabled), every packet received from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1808 the target is decoded and printed on stdout in human-readable ASCII. For
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1809 some packets like TM/ETM responses this "human-readable" form is just a hex
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1810 dump, but the trace messages which the firmware emits on its own are printed
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1811 in truly human-readable form. This output can also be saved to a log file.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1812
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1813 * Rvinterf creates a local UNIX domain socket on the machine it is running on,
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1814 and other host tools can then connect to this socket to exchange packets with
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1815 the firmware. Client programs connected to rvinterf via this local socket
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1816 interface can register to receive copies of packets sent by the target on
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1817 specific RVTMUX channels, and they can also send arbitrary packets to the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1818 target.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1819
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1820 Our main "client" programs for actively interacting with running firmwares via
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1821 rvinterf are:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1822
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1823 fc-tmsh This utility speaks the TM/ETM protocol. It supports almost
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1824 all ETM and L1TM commands that are supported by our reference
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1825 TCS211 fw with the important exception of TMFFS; support means
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1826 that fc-tmsh can issue these commands and decode the firmware's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1827 responses to them. fc-tmsh operates asynchronously in that the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1828 issuance of commands to the target and the display of firmware
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1829 responses are completely decoupled; this asynchronous model is
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1830 a good match for L1/RF test mode commands and simple ETM
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1831 operations, but is a poor fit for FFS manipulation. fc-tmsh's
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1832 companion fc-fsio implements FFS access via TMFFS2, and we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1833 don't have a host side implementation for TI's older TMFFS1
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1834 protocol.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1835
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1836 fc-fsio This utility speaks the TMFFS2 protocol over the TM/ETM RVTMUX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1837 channel (same channel as used by fc-tmsh, so don't try to run
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1838 both at the same time) and implements fairly high-level FFS read
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1839 and write operations. fc-fsio is used to format and initialize
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1840 the FFS on newly made devices in our hardware manufacturing
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1841 environment, it can upload files or entire subtrees into target
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1842 device FFS, it has higher-level commands for writing some files
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1843 like the IMEI, rfcap and AT+CGxx ID strings, and it can list and
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1844 read out FFS content. Unlike fc-tmsh, fc-fsio is synchronous:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1845 it is built on command-response (send a command and expect a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1846 response) primitives, and a single user command can turn into a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1847 large number of command-response exchanges on the RVTMUX
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1848 interface. fc-fsio also implements a few non-FFS commands
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1849 because they naturally fit into this ETM synchronous model.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1850
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1851 fc-shell This tool is asynchronous like fc-tmsh, but instead of talking
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1852 and listening on the TM/ETM RVTMUX channel, it talks and listens
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1853 on GPF's channel and on the new AT-over-RVTMUX channel which we
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1854 added in FreeCalypso. fc-shell can be used to issue system
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1855 primitive commands to GPF (and to see firmware responses to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1856 them), and to talk AT commands via RVTMUX.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1857
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1858 Finally, if you only need to passively observe the firmware's debug trace output
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1859 and don't need to make any active pokes at the target, our rvtdump utility is a
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1860 stripped-down version of rvinterf (or historically its predecessor) that only
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1861 decodes and prints/logs the output from the target without sending anything to
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1862 it.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1863
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1864 Further reading
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1865 ===============
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1866
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1867 Believe it or not, some of the documentation that was written by the original
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1868 vendors of the software in question and which we've been able to locate turns
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1869 out to be fairly relevant and helpful, such that I recommend reading it.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1870
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1871 Documentation for Nucleus PLUS RTOS:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1872
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1873 ftp://ftp.freecalypso.org/pub/embedded/Nucleus/nucleus_manuals.tar.bz2
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1874
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1875 Quite informative, and fits our version of Nucleus just fine.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1876
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1877 Riviera environment:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1878
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1879 ftp://ftp.freecalypso.org/pub/GSM/Calypso/riviera_preso.pdf
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1880
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1881 It's in slide presentation form, not a detailed technical document, but
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1882 it covers a lot of points, and all that Riviera stuff described in the
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1883 preso *is* present in our fw for real, hence it should be considered
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1884 relevant.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1885
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1886 GPF documentation:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1887
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1888 https://www.freecalypso.org/LoCosto-docs/SW%20doc/frame_users_guide.pdf
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1889 https://www.freecalypso.org/LoCosto-docs/SW%20doc/vsipei_api.pdf
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1890
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1891 Very good reading, helped me understand GPF when I first reached this
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1892 part of firmware reintegration.
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1893
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1894 TCS3.x/LoCosto fw architecture:
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1895
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1896 https://www.freecalypso.org/LoCosto-docs/SW%20doc/TCS2_1_to_3_2_Migration_v0_8.pdf
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1897 ftp://ftp.freecalypso.org/pub/GSM/LoCosto/LoCosto_Software_Architecture_Specification_Document.pdf
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1898
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1899 These TI docs focus mostly on how they changed the fw architecture from
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1900 their TCS2.x program (Calypso) to their newer TCS3.x (LoCosto), but one
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1901 can still get a little insight into the "old" TCS211 architecture they
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1902 were moving away from, which is the architecture we've adopted for
fcd1cf531017 TCS211-fw-arch masterpiece written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1903 FreeCalypso.