diff README @ 700:2913c4fdd34a

top level README: describe the project at a higher level
author Michael Spacefalcon <msokolov@ivan.Harhan.ORG>
date Thu, 02 Oct 2014 00:06:50 +0000
parents 29dae53ad969
children 615fb8847d3f
line wrap: on
line diff
--- a/README	Tue Sep 30 02:26:35 2014 +0000
+++ b/README	Thu Oct 02 00:06:50 2014 +0000
@@ -1,30 +1,108 @@
-You are looking at the top level of the freecalypso-sw source code tree.  The
-primary aim of this project is to produce our own full-source GSM firmware that
-would fully operate the TI Calypso-based GSM phones and modems of interest to
-us; this primary subproject is being worked on in the gsm-fw subtree.  While
-that project is progressing very slowly, the associated side projects have
-already produced some useful tools for operating on these GSM devices; see
-README.hosttools for the details.
+What this project is about
+==========================
+
+Welcome to FreeCalypso.  The goal is this project is to produce a Free Dumb
+Phone - not yet another smartphone (free or otherwise), but a "dumbphone",
+i.e., a traditional cellular telephone handset just like we all had and enjoyed
+back in the 1990s - a device with just enough hardware resources to make and
+receive traditional phone calls on a standard GSM network, and not one iota
+more.  No power-hungry application processors, just have one baseband processor
+that does everything from running the GSM protocol stack to responding to the
+user pressing buttons on the traditional numeric dialpad.  No big screens with
+power-hungry backlights, just a little LCD to display who is calling and the
+current date and time - I use my cellphone as a pocketwatch too, so my wrists
+stay free.
+
+But we seek to build a "dumbphone" with one VERY SPECIAL twist: namely,
+operational firmware for the phone (which includes everything from the UI down
+to GSM Layer 1, as there is no separate baseband processor) available to every
+end user in the form of full source code.  Hence it will be a Free Dumb Phone.
+We seek to achieve this "special twist" by doing the following:
+
+* We'll use the ancient TI Calypso chipset for our Free Dumb Phone instead of
+  whatever is the current offering from MTK or other cellular chipset company
+  du jour.  TI stopped making these chips ages ago, and got out of the cellular
+  baseband chipset business altogether, but we can still source these chips in
+  5-digit quantities on the Chinese surplus market.
+
+* Because we'll be using a baseband chipset from the surplus market made by a
+  company that long bit the dust, we will not be getting any official firmware
+  releases from any vendor.  Therefore, there is no one to sign any NDAs with,
+  and there is no one to tell us what we can or cannot do with the firmware as
+  we won't be getting any official firmware in the first place.
+
+* Our Free Dumb Phone will run free firmware which we put together ourselves.
+  When TI completely exited the cellular baseband chipset business, closed all
+  their offices involved with that work and laid off all of the responsible
+  employees, they broke their firmware into pieces and threw the pieces in the
+  trash.  We have picked these shattered pieces out of the trash dumpster, and
+  like anything else found in a dumpster, these abandonware pieces are
+  effectively in the public domain, and any person in the world is free to do
+  with them as she pleases.
+
+The "shattered pieces" aspect of the firmware needs to be re-emphasized.  TI's
+complete firmware suite for their Calypso chipset, also known as TCS2.1.1 or
+TCS211, has *not* survived the disbanding of its maker company in an intact
+form.  Shattered bits and pieces are all we've been able to gather through our
+dumpster diving efforts.
+
+Reconstructing fully-functional firmware for the Calypso from the available
+broken pieces is where the bulk of the hard work in our project is.  There is
+another project (bb.osmocom.org) seeking to produce similarly-functional fw by
+rewriting it completely from scratch with a totally different architecture, but
+the lead developer of the present FreeCalypso project has chosen the
+reconstruction approach as more reliable and more likely to produce the desired
+result.
+
+Hardware vs. software
+=====================
+
+Our goal is to produce a complete and usable cellphone product.  Such a product
+requires both hardware and software (firmware).  We need to produce both.  We
+could do the hw and fw subprojects in either order, but we have chosen to work
+on the firmware first.  By doing the fw first, we will get to exercise it on
+some existing phones that use the same Calypso chipset; doing the hw ahead of
+the fw would give us a fancy paperweight.
+
+Current status
+==============
+
+We are currently using the Calypso GSM modem in the Openmoko GTA02 smartphone
+as our bring-up vehicle.  We have our own firmware suite, compiled 100% from
+source with gcc (no blobs or proprietary compiler toolchains!), but we have not
+yet reintegrated the full GSM protocol stack in this project.  (The leo2moko
+side project doesn't count.)  But we are getting close: we've got the
+FreeNucleus RTOS by XVilka as a working replacement for the binary-only version
+of Nucleus used by TI, and we've got the following parts of TI's original
+firmware suite integrated and working:
+
+* RiViera framework and everything that runs under it, including TI's original
+  FFS (flash file system), RVTMUX serial channel and ETM (Enhanced Test Mode).
+  This part has been found in a TCS211 semi-src package.
+
+* GPF (Condat's protocol stack framework) - TI used it mostly as binary libs,
+  even internally, and we had to reconstruct it from pieces.  Some parts of GPF
+  had to be reconstructed from disassembly.  But it works beatifully now.
+
+* GSM Layer 1 code - we took the version from the LoCosto source (no official
+  Calypso L1 source could be found) and backported it from LoCosto to Calypso.
+
+We are now working on reintegrating the rest of the GSM protocol stack code,
+also taking it from the LoCosto source (the only available full source) and
+reintegrating it to build in our FreeCalypso environment, targeting Calypso
+instead of LoCosto.
+
+We have also produced some host tools for loading firmware into Calypso GSM
+devices, for communicating with running firmwares over the RVTMUX interface,
+and for manipulating TI's flash file system.  See README.hosttools for the
+details.
+
+Source tree
+===========
 
 The subtrees of this source tree are as follows:
 
-gsm-fw		This tree contains the early beginnings of my (Michael
-		Spacefalcon's) attempt to recreate TI's GSM firmware suite for
-		modems and basic phones, consisting of Nucleus RTOS, RiViera
-		and GPF frameworks, TI's BSP/driver and L1 code, Condat G23
-		GSM/GPRS protocol stack, AT command interpreter and UI layers.
-
-		Integrated and working so far:
-		* Layer 1 (gtamodem target only): builds and runs, lightly
-		  tested, need the rest of the GSM protocol stack for real
-		  testing.
-		* RTOS foundation (all targets): one can exercise RVT, ETM, FFS
-		  and GPF; all work beautifully.
-
-		Next steps:
-		* Integrate Layers 2&3 (Condat G23);
-		* Rework the tpudrv part of L1 to work on targets other than
-		  gtamodem, i.e., Pirelli DP-L10 and Mot C1xx.
+gsm-fw		The main FreeCalypso GSM firmware work, see above.
 
 target-utils	This tree contains code that runs on Calypso targets, but is
 		not regular firmware (gsm-fw) or a part thereof.  The two key