FreeCalypso > hg > freecalypso-citrine

annotate doc/Current_Status @ 28:cb00b90edaff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation write-ups imported from freecalypso-sw and updated for Citrine
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 12 Jun 2016 18:28:35 +0000
parents
children 23dbd942aa56
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
28
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 The goal of the Citrine firmware project is to replace the Windows-built
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 firmwares which have been produced in other subprojects under the FreeCalypso
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 umbrella - see leo2moko and tcs211-c139. Our leo2moko project has produced a
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 production quality modem fw image for the Openmoko GTA02, while a C139 reflashed
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 with tcs211-c139 is the first dumbphone in history that can still function as an
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 untethered phone after having had its fw replaced with an indie one that bears
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 no relation to the manufacturer's original - but those TCS211-based
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 Windows-built projects have severe limitations. Much of the firmware code base
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 in those versions is in the form of unmodifiable binary object libraries, and
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 the Windows-based configuration and build system is incompatible with the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 long-term needs of FreeCalypso development.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 The present fw project (FreeCalypso Citrine) seeks to rectify the situation by
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 replacing the blob-laden, Windows-built firmware with a version that is built
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 from full source (no binary blobs) with gcc, with an entirely different
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 configuration mechanism that actually suits our needs. Because one of the key
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 goals of this project is to build the firmware from *full source*, the binary
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 object versions of L1 (GSM Layer 1) and G23M (layers 2&3 of the protocol stack)
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 featured in our reference TCS211 fw could not be reused. Instead this project
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 uses versions of L1 and G23M (and some other pieces) that have been lifted from
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 the firmware for TI's other chipset (LoCosto) and backported to Calypso.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 The current state of the project is that we have made remarkable progress, but
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 what we have right now is still not a satisfactory replacement for TCS211.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 Specifically:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 * Only the bare minimal modem functionality for the voice+SMS subset has been
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 integrated so far. "Modem" means our fw can only be controlled via AT
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 commands; no UI code (as in LCD+keypad) has been integrated at all. But it
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 is not a true modem either as none of the data functions have been integrated
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 yet: no CSD, no fax, no GPRS. Thus it is an AT-command-controlled voice+SMS
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 pseudo-modem.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 * The firmware can be built for the following targets:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 Mot C11x/12x
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 Mot C139/140
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 Mot C155/156
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 Openmoko GTA01/02
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 Pirelli DP-L10
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 All configurations are built from the same source tree. The firmware
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 functions identically on all supported targets. Because there is no UI code
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 integrated yet, the LCD stays dark and the buttons do nothing on those target
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 devices that have such hardware.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 * Most of our supported target devices have only one practically accessible
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 serial port (UART). Our firmware presents TI's RVTMUX interface on this
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 UART; the operator is expected to interface to it by running our rvinterf
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 tools on the host PC/laptop. One of the utilities in the rvinterf suite is
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 fc-shell; this tool is used to send AT commands to the running firmware,
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 which is the only way to control its operation.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 * With a valid SIM card inserted and a valid IMEISV configured, a GSM device
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 running our firmware can successfully connect to live commercial GSM networks,
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 make and receive voice calls, and send and receive SMS.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 * In the case of voice calls, the call downlink audio is routed to the phone's
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 earpiece speaker and the phone's microphone serves as the source for the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 uplink audio, i.e., even though the LCD and keypad are dead with our fw, the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 earpiece and mic continue to function as in a conventional phone. FR and EFR
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 codecs work correctly (EFR was broken until recently), but AMR does not work
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 with this fw for some not-yet-understood reason, hence by default our fw
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 currently advertises to the GSM network that the MS only supports FR, HR and
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 EFR codecs.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 There is also a highly experimental and minimally tested alternative mode
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 of operation in which the traffic channel carrying FR codec bits (260 bits
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 every 20 ms; it is not known whether or not this feature will also work with
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 EFR) is rerouted away from the internal vocoder to the external host,
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 such that you can receive the downlink voice bits digitally instead of
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 listening to them in the earpiece speaker, and you can substitute your own
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 uplink bits instead of the microphone-fed internal vocoder output. See the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 TCH-special-feature write-up for more information.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 There are also two known bugs which manifest only intermittently, but the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 misbehaviour does occur often enough that you will likely encounter it:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 * Sometimes something gets messed up in the voice uplink path such that the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80 downlink audio sounds just fine in the earpiece speaker of the phone running
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 FC Citrine, but the far end of the call hears only silence. Other times the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 voice audio passes just fine in both directions. It is not currently
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 understood what factors determine whether it will work or not.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 * Sometimes the L1A task in the firmware (see the Firmware_Architecture
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 write-up) appears to stop running; the externally visible behaviour is that
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 the debug trace output from L1 suddenly stops while the rest of the firmware
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 keeps running. GSM firmware without working L1 is unusable, hence when the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 fw gets into this state, the only remedy is a power cycle reboot. It is not
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 currently understood exactly what happens and under what conditions.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 Going forward, the current plan is to wait until our FCDEV3B hardware gets built
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 before any attempts will be made to go after the above-listed bugs. I, the
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 principal developer, am sick and tired of limping along with Compal, Pirelli
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 and Openmoko hardware when we have a design for our own FreeCalypso development
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 board which, when built, will be a much more convenient platform for firmware
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 development.
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 Target-specific usage instructions
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100 ==================================
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 If you would like to play with our work-in-progress firmware and check it out
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 for yourself, see the following target-specific instructions:
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 Mot C1xx (Compal) Compal-Howto
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 Openmoko GTA01/02 Freerunner-Howto
cb00b90edaff documentation write-ups imported from freecalypso-sw and updated for Citrine
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 Pirelli DP-L10 Pirelli-Howto