diff README @ 218:75ea63a3fce5

README updated for the current status of the project
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 15 Oct 2016 19:30:58 +0000
parents 9fb9f896bd77
children b05dba024f95
line wrap: on
line diff
--- a/README	Sat Oct 15 06:27:58 2016 +0000
+++ b/README	Sat Oct 15 19:30:58 2016 +0000
@@ -24,8 +24,7 @@
 the known working TCS211 code base, without any major restructuring, and making
 small incremental evolutionary changes, testing at every step to ensure that
 nothing breaks.  It is the direct opposite of the "rebuild from the ground up"
-approach taken with our previous Citrine firmware (aka "gsm-fw"), the approach
-that produced very disappointing results.
+approach taken with our previous Citrine firmware aka "gsm-fw".
 
 Functionality
 =============
@@ -33,37 +32,50 @@
 TI's GSM mobile station firmware architecture supports two ways in which the
 GSM device may be controlled: via AT commands from an external host and/or via
 a local UI on devices with LCD & keypad hardware.  (I said "and/or" because the
-two mechanisms can coexist.)  At the present time, however, only the AT command
-mode of operation is supported in FreeCalypso Magnetite.  The effect of this
-limitation is that if you run this fw on a Motorola C139 or a Pirelli DP-L10,
-the phone's LCD will stay dark, the buttons won't do anything, and the
-phone-turned-modem can only be operated via AT commands sent via FreeCalypso
-host utility fc-shell.
+two mechanisms can coexist.)  The code we got from TI (TCS211) is very solid
+and mature in the modem configuration (control via AT commands only, no UI, no
+battery management, no traditional handset on/off control), but the additional
+code layers that are needed for handset products but not for modems are in a
+very rough "proof of concept" condition, nowhere close to a usable product.
+
+The same situation currently exists in FreeCalypso Magnetite.  As explained
+below in the Build system section, a key feature of FC Magnetite is that many
+different firmware configurations can be built from the same source tree.  One
+of the configuration choices is that you can build the fw either with or without
+the phone UI layers.  The work we have done earlier in the tcs211-c139 side
+project (late 2015) has been integrated into Magnetite, properly conditionalized
+so that TI's original configuration is fully preserved when the target != c139.
+However, if you build the UI-enabled configuration for any target other than
+Mot C139, it will compile, but it won't do anything useful: it will try to
+display TI's 176x220 pixel color UI on the D-Sample LCD on Calypso chip select
+nCS3, but this hardware doesn't exist on any of our supported targets.  (The
+Pirelli in particular has flash on that chip select instead, so it may interfere
+with FFS operation.)
 
-The demo/prototype phone UI code in TI's reference fw delivery is written for
-a 176x220 pixel 16-bit color LCD (such an LCD was used on TI's official
-development platform called D-Sample), whereas our available Mot C139 and
-Pirelli targets have significantly smaller LCDs: 96x64 and 128x128 pixels,
-respectively.  Prior to the D-Sample, TI had used 84x48 pixel black&white
-(1 bit per pixel) LCDs, and this old C-Sample LCD code is still there, albeit
-bitrotten.  In late 2015 this author made a very dirty hack to resurrect TI's
-old C-Sample UI code and get it to display on the C139 phone LCD (84x48 is a
-proper subset of 96x64) - you can find this hack in the tcs211-c139 Hg tree.
+Further work on the handset firmware configuration (UI, battery management and
+other currently missing functionality required for a usable phone) will have to
+wait until we build our own Handset Motherboard Prototype (HSMBP) with a 176x220
+pixel 16-bit color LCD, replicating TI's D-Sample - I personally am not too
+interested in doing this handset fw work on the very crippled Mot C139 or on
+the Pirelli with its own host of issues, although others in the community are
+more than welcome to take a shot at it if someone is interested.
 
-The upshot of this LCD situation is that porting TI's phone UI code to run on
-Mot C139 or Pirelli DP-L10 will require major rework of the affected parts of
-the firmware.  While I would like to do it eventually, I am not willing to do
-it right now - I would like to get this code running in its pristine state on
-its native 176x220 pix LCD *before* I hack the holy **** out of it for the
-C139/Pirelli port.  I do have a real TI-made D-Sample kit with the right LCD,
-but unfortunately the main board has an older version of the core chipset for
-which we lack the necessary fw support, hence it doesn't help.  Therefore, we
-will need to build our own Calypso board with a 176x220 pix 16-bit color LCD,
-get the UI-enabled GSM firmware running on that board, and only then proceed
-with C139 and/or Pirelli ports if such are still desired.
-
-For now, modem or pseudo-modem operation with control via AT commands is all
-we have.
+Until then, the primary current focus of the FC Magnetite project is the
+AT-command-controlled modem configuration.  Both TI's original modem fw (TCS211)
+and our recreation thereof in this Magnetite project support not only voice
+calls and SMS, but also CSD, fax and GPRS.  However, before we can really
+exercise this functionality, we need to first build our long-overdue FCDEV3B
+hardware.  TI's standard fw architecture (kept unchanged in FC Magnetite)
+assumes the availability of two UARTs: the modem UART presents a classic AT
+command interface which includes the CSD, fax and GPRS functionality, whereas
+the 2nd IrDA UART carries the debug trace channel (RVTMUX) essential for
+developers.  However, only one UART is practically accessible on Mot C139 and
+Pirelli DP-L10 targets; because we could not give up RVTMUX, we gave up the
+classic AT command UART channel instead.  We have implemented a mechanism for
+passing AT commands over RVTMUX, but this mechanism works only for the voice
+and SMS AT commands, not CSD, fax or GPRS.  Therefore, the latter functionality
+remains inaccessible until we build our own proper Calypso board with both
+UARTs brought out.
 
 Build system
 ============
@@ -121,8 +133,10 @@
 actually making this replacement without breaking functionality is a very
 non-trivial endeavor.  Our previous attempt to rebuild the firmware from the
 ground up, using source pieces lifted from different available leaks and
-building with gcc so that no TMS470 COFF blobs could be used, produced very
-disappointing results.
+building with gcc so that no TMS470 COFF blobs could be used - see FreeCalypso
+Citrine - has produced only a very limited subset of the original functionality,
+and until very recently even the most basic function of voice calls did not work
+reliably.
 
 Instead the new FreeCalypso firmware approach implemented in FC Magnetite is to
 approach the blob-free goal incrementally.  The new Magnetite build system is
@@ -136,12 +150,8 @@
 still works (doesn't break), we make this deblobbing transition permanent and
 move on to the next component.
 
-As of this writing, most of Layer 1 and a few housekeeping parts of the fw have
-already been deblobbed, i.e., are now recompiled from source.  The G23M protocol
-stack is our next deblobbing target - we have a newer version of it in full
-source form, and we are hoping to be able to retrofit this newer G23M version
-into the TCS211 environment in order to replace the binary blob version we are
-using currently.
+See doc/Deblobbing for the current status of the deblobbing effort and for the
+description of the currently available configurations.
 
 Further reading
 ===============