FreeCalypso > hg > fc-magnetite

annotate cdg3/README @ 94:596d86109e44

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial round of documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 03 Oct 2016 04:26:16 +0000
parents c15047b3d00d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 There exists a set of C header files, needed for TI's GSM firmware to build,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 called cdginc. They are not needed for building everything up to and including
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 GPF and L1, but they are needed in order to build the core G23 protocol stack
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 components.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 However, these cdginc headers are generated files, not human-written sources,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 and the process by which they get created is very messy:
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 1. Contained as part of the ultimate source for the firmware, there is a set of
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 XML files which give definitions for Air Interface Messages (AIMs) and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 Service Access Points (SAPs).
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 2. Each *.aim file is "compiled" into an MDF (message definition file) and each
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 *.sap file gets similarly "compiled" into a PDF (primitive definition file).
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 (Despite sharing the same acronym and filename suffix, these "primitive
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 definition files" have nothing to do with PDF as in Portable Document
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 Format.) This "compilation" is done by way of XSLT: an XSLT processor is
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 invoked, its inputs being the source *.{aim,sap} files and a set of *.xsl
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 files defining the transformation. (The latter can be found under
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 gpf/util/sape/xslt in the "peek" LoCosto source.)
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 3. A special TI/Condat-developed program called ccdgen (which we only have in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 the form of an M$ Windows binary sans source, ccdgen.exe) reads the *.mdf
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 and *.pdf files produced in the previous step, performs some unknown
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 processing (unknown because we have no source for this tool), and writes out
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 most of the C header files which appear in the cdginc directory. (The
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 exception is that a few of these header files seem to be produced directly
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 by the XSLT step.)
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 ==================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 XSLT and Java woes
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 ==================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 When I (Space Falcon) tried to reproduce the above steps for FreeCalypso,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 problems began at the XSLT step. The XSLT processor used in TI's build flow is
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 an old version of Xalan-J from Apache. J stands for Java - yikes. Thus TI's
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 build flow actually runs java with a set of *.jar files which comprise Xalan-J.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 I looked to see if the use of Xalan-J (and thus of Java) was required, or if
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 one could use any XSLT processor, including non-Java implementations. Not so
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 fast: TI's *.xsl files for the needed transformation call some functions
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 (please forgive my probably incorrect terminology: both XSLT and Java are as
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 foreign and unfamiliar to me as Japanese or Arabic or ... - you get the idea)
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 which seem to have been implemented by TI as custom Java classes, falling under
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 com.ti.xslt.extension - the latter live in gpf/tools/lib/java/xalan-ext.jar in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 TI's semi-source trees (both Leonardo and LoCosto), if you would like to see
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 for yourself.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 That xalan-ext.jar file with TI's "XSLT extension" classes contains Java
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 bytecode, not source. Thus one of the required pieces for the *.{aim,sap} ->
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 *.{mdf,pdf} build step effectively exists only in the form of compiled code
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 sans source. It is of course an impairment to freedom, and as I quickly
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 discovered, not only in philosophical terms, but also in practice: as I will
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 show in a moment, there appears to be a bug in there which we lack the ability
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 to fix.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 Of course TI ran their java invokation for XSLT under Winblows. (As a side
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 note, I successfully ran TI's entire Winblows environment, including this step,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 under Wine when I did leo2moko - but I wasn't trying to extract any individual
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 step and get it to run by itself, instead I ran TI's *entire Winblows env*
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 under a single top-level wine invokation.) But Java bytecode is supposed to be
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 platform-independent, right? So I tried running the java command from pdt_*.mak
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 makefiles in the Leonardo version, using their set of XSLT/xalan jars as-is,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 under Slackware Linux without Wine, using the Linux-native version of Java that
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 came with Slackware.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 I started with the AIM->MDF part. The operation succeeded on a few of the
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 files, but then failed on others. The error had something to do with filename
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 and pathname manipulation. Some of the com.ti.xslt.extension functions called
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 by TI's xslt transforms seem to be responsible for turning short filenames into
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 absolute pathnames and then into file:// URLs, and it appears that TI's
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 implementation of these functions assumes that absolute pathnames will have
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 Weendoze drive letters, and breaks on Unix absolute pathnames which lack that
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 nonsense. And the part responsible for the bug is a piece of Java bytecode in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 a jar sans source, remember? I didn't get as far as trying the SAP->PDF part.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 I reason that someone who knows the world of Java could probably reverse-eng
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 that bytecode and fix the bug with a binary patch, or rewrite an alternate
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 implementation. Reversing Java bytecode might not even be necessary: someone
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 who understands XSLT could probably figure out what functionality is expected
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 from these extension functions, and then reimplement that (most likely trivial)
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 functionality anew. But XSLT is just as foreign to me as Java; they both might
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 as well be Japanese or Arabic or some other super-hard foreign language.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 Given that my goal is to produce free GSM firmware, I decided that taking a
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 very long detour to learn XSLT and Java just so we can regenerate TI's *.[mp]df
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 files from *.{aim,sap} is not worth it, and imported prebuilt *.[mp]df files
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 from the LoCosto source along with *.{aim,sap}.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 ============================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 Different versions of cdginc
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 ============================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 Most of the hard work in the FreeCalypso project involves reconciliation between
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 our two reference versions: TCS211 (aka Leonardo) and LoCosto. Our TCS211
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 reference version (in the form of leo2moko) already runs on one of our target
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 platforms and works beautifully, but it has the entire GSM protocol stack in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 binary-only libs. The LoCosto version is full source (aside from Nucleus and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 some parts of GPF which have already been taken care of), but targets the wrong
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 chipset, and has that nasty SBuild crap instead of pdt_*.mak.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 The versions of cdginc used in the TCS211 and LoCosto semi-src trees differ in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 the following ways:
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 1. The starting *.aim and *.sap files are different: the LoCosto versions are
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 newer.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 2. Slightly different versions of ccdgen.exe are used: the version featured in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 the TCS211 version from Sotovik identifies itself as 2.5.5, whereas the one
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 featured in the LoCosto "peek" find identifies itself as 2.5.5A. Aside from
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 some cosmetic differences, one substantive difference was found in the
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 generated output: the so-called mtx tables (don't ask me what they are, as I
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 don't understand it myself) are emitted in a different format. (Ccdgen
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 version 2.5.5A generates the new format by default, and has a command line
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 option to revert to the old format.)
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 These "mtx" generated header files are included by some ccddata modules (see
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 ../ccd/README for more info), and the only C source we have for these modules
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 (for all of CCD, in fact) comes from the LoCosto version. This version of
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 the ccddata C source expects "mtx" cdginc headers in the new format, hence
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 that is the format we need to use.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 3. One additional input to ccdgen besides the *.[mp]df files is a "settings"
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 file called fflags.h. It has the form of a C header file with #define and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 #undef lines (the rest is just comments), but as far as I can tell, it never
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 gets fed to a C preprocessor, only to ccdgen. The starting *.{aim,sap} files
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 contain some "options", and for each of these options, fflags.h must give a
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 yes/no answer in the form of $define or #undef. This "settings" file is
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 mandatory: if it is not given on the ccdgen command line, or if it has
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 neither a #define nor a #undef for some "option" defined in the *.{aim,sap}
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 files, ccdgen aborts with an error.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 It appears that the version of *.{aim,sap} featured in the TCS211 fw has only
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 one option named TI_DUAL_MODE, which needs to be disabled, as the version of
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 fflags.h in that tree has only one non-comment line:
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137 #undef TI_DUAL_MODE
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 But the LoCosto version of fflags.h (which appears here as fflags-locosto.h) is
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 much more extensive, and all of the options listed therein appear in the
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141 *.{aim,sap} files and are in need of explicit enabling or disabling - as I
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 found out when I tried running ccdgen on LoCosto *.[mp]df files with the TCS211
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 version of fflags.h - it immediately failed with a bunch of errors about certain
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 options not being set one way or the other.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 ============
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 New features
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 ============
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150 It appears that all of the options enabled in the LoCosto version of fflags.h
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 correspond to new features of the G23 protocol stack which do not exist at all
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 in our TCS211 reference version (leo2moko). How can we tell what features are
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 present or absent in our TCS211 version if all we have is binary libs sans
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 source? For a long time I thought the problem was unsolvable, but then I found
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155 the answer in an obscure place: the "relic" pdt_*.mak files *other than* the
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 actively used pdt_2091.mak present in the source from Sotovik. The source we
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 have is "sanitized" in that the C source files for all of L1 and G23 have been
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158 removed, and the makefile in pdt_2091.mak has no compilation stanzas for these
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 modules either: this generated makefile is set up to take the corresponding
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 binary-only libs as "sources". However, the other (unused) pdt_*.mak files
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 have been built (back in TI's development environment, presumably) in the "full
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 source present" configuration, and list not only the names and paths for all of
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163 the deleted source files, but also their complete compilation lines with all -I
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 directories and -D options!
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 Looking at the latter compilation lines, one can see that none of the options
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167 related to GSM REL99 or TI's new "multiband" stuff (seen both in fflags.h and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 throughout the L1 and G23 sources we are back-porting from the LoCosto "peek"
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 find) are present at all in our TCS211/leo2moko reference version.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 ===============================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172 Approach chosen for FreeCalypso
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 ===============================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 I have not yet figured out whether the new apparently-high-level GSM PS features
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 found in the LoCosto version we are working with actually depend on some LoCosto
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177 hardware or DSP ROM code feature not present on the Calypso, or if they can be
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 back-ported to the Calypso just fine. I also currently have very little
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 understanding as to their merit, i.e., practical value or usefulness for a GSM
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180 cellphone end user.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 The approach I'm taking for the initial version is to recreate the TCS211
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183 configuration that already works on the Neo Freerunner in the form of leo2moko
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 as closely as possible, and that means setting all of the newer options to the
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 disabled state. Or at least that is the approach I am following until and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
186 unless I run into some problem with it; if and when the latter happens, I'll
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187 re-evaluate my course.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
188
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
189 However, simply using the set of cdginc files from TCS211 (or even regenerating
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
190 them from the TCS211 versions of *.[mp]df with the new ccdgen.exe to get mtx
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
191 tables in the format expected by our version of CCD source) with the G23
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
192 protocol stack C sources from the LoCosto version will likely lead to problems,
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
193 or least more hassle than it's worth, hence I decided to bite the bullet and
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
194 use the *.{aim,sap} and *.[mp]df files from LoCosto.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
195
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
196 Using the LoCosto versions of *.[mp]df, I ran ccdgen.exe (version 2.5.5A, set
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
197 to generate mtx tables in the new format) with two different fflags.h
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
198 configurations: "locosto" (unchanged from the "peek" find) and "conservative".
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
199 The latter is a configuration in which every existing option is set to disabled:
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200 I took fflags-locosto.h and changed every #define to #undef.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
201
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
202 The symlink is currently set to compile the GSM fw using the "conservative"
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
203 version of cdginc headers. As I said above, I'll proceed with this
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
204 configuration until and unless I hit a problem, and then re-evaluate this
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
205 course if need be.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
206
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
207 =====================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
208 ccdgen binary problem
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
209 =====================
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
210
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
211 We only have a ccdgen.exe binary, but no source. The Winblows binary in
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212 question happens to run fine under Wine, at least on my Slackware machine, but
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 needless to say, asking every FreeCalypso user who wishes to compile her own
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 GSM fw from source to run a sans-source Weendoze binary under Wine and pray
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 that it works is not an attractive proposition. Therefore, as a workaround I
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
216 have checked the generated cdginc files into Hg as if they were source files.
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
218 Of course this workaround is not a proper solution either, but it is the best
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
219 we can do for the time being, until and unless someone either finds the missing
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
220 source for ccdgen or figures out its logic and writes a from-scratch functional
c15047b3d00d cdg3: import from freecalypso-citrine/cdg
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
221 replacement.