freecalypso-docs: TCS211-fw-arch annotate

annotate TCS211-fw-arch @ 106:28c1cb869d91

TCH-tap-modes: updates for TCH/HS

author	Mychaela Falconia <falcon@freecalypso.org>
date	Mon, 22 Jul 2024 22:36:29 +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 @ 106:28c1cb869d91