freecalypso-docs: TCS211-fw-arch annotate

annotate TCS211-fw-arch @ 23:14391ad53281

FCDEV3B-repackaging article removed for legal reasons The idea expressed in that article, namely the idea that some party other than Mother Mychaela could be permitted to create a derived work based on FCDEV3B board design and have it be accepted into the FreeCalypso family, is no longer allowed by our current stance on the matters of intellectual property, particularly Falconia IP. For technical content, the new FC-modem-family and Quadband-ideas articles should fully supplant this old FCDEV3B-repackaging article.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Wed, 23 Oct 2019 00:43:21 +0000
parents	f5ddeacbe744
children

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.

FreeCalypso > hg > freecalypso-docs

annotate TCS211-fw-arch @ 23:14391ad53281