--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,61 @@
+FreeCalypso Tourmaline firmware project
+=======================================
+
+In chronological terms, FC Tourmaline is our fourth firmware offering after
+Citrine, Magnetite and Selenite.  FC Tourmaline supports the following two
+fundamental modes of operation:
+
+* AT-command-controlled modem operation (no UI) is currently unchanged from
+  Magnetite hybrid; standard modem operation is supported on Tango/Caramel2,
+  FCDEV3B and Openmoko hardware targets.
+
+* The new work being done in Tourmaline is phone handset functionality - the
+  goal is to produce firmware that can operate a suitable hardware unit as an
+  untethered end user phone.  Only two hardware targets are supported in this
+  FC Tourmaline handset UI development venture: FC Luna development platform
+  and Motorola C139.
+
+See the following articles under doc for further details:
+
+C139-notes		-- running smallbw version of the UI on Mot C139
+Luna-notes		-- running both UI versions on FC Luna
+Modem-operation		-- using the modem configuration
+
+Technical details
+=================
+
+Just like FC Selenite, Tourmaline is derived from the hybrid config of
+Magnetite.  Also in common with Selenite, Tourmaline uses the new source
+version of Nucleus.  However, unlike Selenite, Tourmaline retains sole use of
+the original TMS470 compiler (runs under Wine), retains the original blob
+versions of OSL and OSX glue components of GPF in the default config (see
+doc/Blob-status), and includes both modem and handset functional configs.
+
+Purpose and goal
+================
+
+As of late 2020, FreeCalypso has achieved everything that needs to be done on
+the modem side: our Magnetite hybrid or Tourmaline stdmodem firmware running on
+our Tango modem module embodies complete fulfillment of our long-standing desire
+for a standard GSM+GPRS modem module with fully published circuit schematics and
+firmware source code.  No more significant work beyond maintenance is deemed to
+be needed on the modem side.
+
+OTOH, the other need for a FreeCalypso handset that can replace proprietary
+phones like Mot C1xx or Pirelli DP-L10 running their original proprietary fw
+still remains as unmet as it was when we started back in 2013.  Thus the new
+FreeCalypso work direction is to finally produce this FC handset, initially in
+the form of FC firmware running on Mot C139 (and on FC Luna to keep up the
+bigcolor config) and allowing the possibility of new FreeCalypso handset hw.
+
+Seen from the perspective of handset rather than modem functionality, the
+direction taken in Citrine and Selenite (going for 100% blob-free compilation
+with gcc) is the wrong way to go.  That direction would make sense if one cared
+only about modem functionality rather than handset, but we are currently in the
+opposite situation.  In the case of handset functionality, going for a compiler
+change to gcc in our current state when so many other parts are broken and in
+need of fixing would be pure insanity, and we are not going there.  Let us
+first produce a working FreeCalypso handset (with fw compiled with TMS470 under
+Wine, keeping the tiny remaining blobs) that can replace Mot/Pirelli's original
+proprietary firmwares for daily use, and *then* think about moving to 100%
+blob-free gcc - in this order.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Blob-status	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,32 @@
+State of blobs in FreeCalypso firmware
+======================================
+
+FC Tourmaline is almost completely deblobbed.  Only the following very small
+components exist in the form of blobs (prebuilt binary objects for which we
+have no exact corresponding source) in the standard Tourmaline build:
+
+* OSL and OSX glue components of GPF: 14992 bytes of code
+* TMS470 compiler's RTS library (libc/libgcc equivalent): 13152 bytes of code
+
+For OSL and OSX we do have reconstructed C code written based on disassembly of
+the blobs, but I (Mother Mychaela) do not consider the current state of this C
+reconstruction to be fit for production use - hence standard Tourmaline fw
+builds use blob versions of these components.  However, our configuration and
+build system gives you the freedom to select which version of each component
+you would rather use; the selection is made with Bourne shell config variables
+on the configure.sh invokation line:
+
+OSL=0	use the blob version of OSL
+OSL=1	use the reconstructed C version of OSL
+OSX=0	use the blob version of OSX
+OSX=1	use the reconstructed C version of OSX
+
+The current default is OSL=0 and OSX=0.
+
+RTS library
+===========
+
+We do have source code for some versions of the TMS470 compiler's RTS library,
+but they may not be exactly corresponding to the blob version from TCS211 which
+we are using.  This area is deemed to be such a low priority that no real
+investigation has been done yet.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/C139-notes	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,22 @@
+FC Tourmaline firmware differs from Magnetite in two principal ways when it
+comes to Mot C139 target support:
+
+* C139 LCD support is implemented in a more forward-looking manner: instead of
+  emulating TI's C-Sample at the lowest R2D driver level and therefore being
+  forever limited to 84x48 pixel display size, Tourmaline implements a new
+  96x64 pixel framebuffer, matching the native LCD size of C1xx phones.  The UI
+  configuration is still black&white only though - the Mother of FreeCalypso
+  has no current plans to support color UI on smaller LCD sizes than TI's
+  original 176x220 pix.
+
+* Our aftermarket FFS configuration has been changed from 64x3 at 0x3C0000 to
+  64x7 at 0x300000.  Our earlier 64x3 config was chosen back in 2015, at that
+  time we didn't know how much room we would end up needing for the firmware
+  image vs. how much FFS content we would eventually have, and this 64x3 config
+  is now deemed to be too small, allowing only one 64 KiB sector for FFS
+  content.  Our new FC Tourmaline aftermarket FFS config supports up to 320 KiB
+  of FFS content, matches what we use on other platforms with 4 MiB flash chips,
+  leaves 3 MiB for the firmware image (our current smallbw UI fw is only 2 MiB),
+  and still avoids intersection with Motorola's (or rather Compal's) original
+  FFS, which is important for avoiding problems in converting C139 phones back
+  and forth between Motorola and FreeCalypso firmwares.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compiling	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,204 @@
+Preparing the development and build environment
+===============================================
+
+In order to compile our FreeCalypso Tourmaline firmware, you will need a
+Unix/Linux system.  Even though we are using a compiler which we got in the
+form of Windows .exe binaries and thus have to use Wine (see below), everything
+that we have built on top of it is Unix-based.  The Mother currently uses
+Slackware Linux release 14.2 (32-bit) and previously used Slackware 13.37,
+also 32-bit.
+
+You will need to install the following 3 pieces of software on whatever
+machine you will use to run the FC Tourmaline build process:
+
+1. Wine: self-explanatory.  The Mother uses the following Slackware package:
+
+   https://www.freecalypso.org/members/falcon/slackware/wine-1.5.23-i486-1sg.txz
+
+   I originally used it with Slackware 13.37 and I am still able to use it
+   with 14.2 without any issues.
+
+2. FreeCalypso Wine environment:
+
+   ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/installed-env.tar.xz
+
+   Extract the content of the above tarball into your ~/.wine/drive_c
+   directory - that's all there is to it!
+
+3. nowhine wrapper around Wine:
+
+   ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/nowhine.c
+
+   The purpose of this wrapper is to suppress the following obnoxious whine
+   which wine emits on my system:
+
+   preloader: Warning: failed to reserve range 00010000-00110000
+
+   Wine will also emits a bunch of other whines if you have to run it
+   in an environment without an X11 display (e.g., on a machine that you
+   ssh into), and our nowhine wrapper suppresses those as well.
+
+   If wine does not emit those preloader whines on your system and you
+   never find yourself in a situation of having to run without an X11
+   display and thus you find our nowhine wrapper to be unnecessary,
+   you can skip the wrapper and create a nowhine symlink pointing directly
+   to wine.
+
+Compiling the local helper utilities
+====================================
+
+(cd helpers; make)
+
+Do the above.  Most of the build helper scripts used in the FC Tourmaline build
+system are written in Bourne shell, but a few were easier to implement in C.
+You need to compile these C helper utilities before you can run an actual FC
+Tourmaline firmware build, but these utilities are totally ad hoc and specific
+to the needs of our fw build system, hence they are not meant to be installed
+globally on your system - instead they stay within the fc-tourmaline tree.  You
+just need to run make in the helpers directory once before any actual firmware
+builds.
+
+Actually building the firmware
+==============================
+
+In order to build our FreeCalypso Tourmaline firmware for a particular target
+in a particular configuration, run a command like this from the top level of
+the fc-tourmaline tree:
+
+./configure.sh luna2 bigcolor-gprs
+
+The first required argument to the configure.sh script selects the hardware
+target, the second required argument selects the functional configuration, and
+any further arguments beyond these two (optional) allow changing various
+configurable settings that go beyond basic functional selection and aren't
+strictly fixed by the hardware target.
+
+As of this writing, the following hardware targets are supported:
+
+c11x		Motorola C11x/12x
+c139		Motorola C139/140
+c155		Motorola C155/156
+fcdev3b		FreeCalypso FCDEV3B
+gtamodem	The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
+gtm900mgc	Huawei GTM900, hardware variant MGC1GSMT or MGC2GSMT
+j100		Sony Ericsson J100
+luna1		FreeCalypso Luna, based on iWOW DSK v4.0 or v5.0 motherboard
+luna2		FreeCalypso Luna, based on FC Caramel2 motherboard
+pirelli		Pirelli DP-L10
+tangomdm	FreeCalypso Tango standard modem config
+
+The second required argument selects the basic functional configuration; these
+functional config stanzas appear in the configs directory.  The following
+functional configurations are currently available:
+
+bigcolor-gprs & bigcolor-vo
+
+	These are UI-enabled configurations with the big (176x220 pixel) color
+	version of the UI.  These functional configs can be built only for
+	luna1 and luna2 targets.
+
+smallbw
+
+	Small B&W UI configuration - 96x64 pixel black&white UI version.  This
+	functional config can be built for c139, luna1 and luna2 targets.  When
+	running on Luna, the logical 96x64 pixel B&W LCD is centered in the
+	middle of the 176x220 pixel physical LCD, surrounded by a pale magenta
+	border.
+
+bwtest
+
+	This one is a special intermediate configuration is that the UI layers
+	are built in the smallbw config, but the underlying R2D framebuffer
+	driver is 176x220 pixel B&W, rather than 96x64 pixel B&W.  This config
+	can only be built for Luna targets; it originates from TI's own
+	configuration of running their !LSCREEN (smallbw) UI on D-Sample boards
+	with R2D driver in the BW_D_Sample config.
+
+stdmodem
+
+	Standard modem config, all data services enabled, no UI functionality
+	included.  Supported targets are fcdev3b, gtamodem, gtm900mgc and
+	tangomdm.
+
+vpm
+
+	See the Voice-pseudo-modem article.  This functional config is
+	applicable to c11x, c139, c155, j100 and pirelli targets.
+
+Each configuration is built in its own directory; the name of this build
+directory takes the form of build-$TARGET-$CONFIG$SUFFIX, i.e., for the example
+configure.sh line above, the resulting build directory will be named
+build-luna2-bigcolor-gprs.  The $SUFFIX part is empty by default, but can be set
+on the command line in order to distinguish non-standard builds that had some
+tunable settings changed to values other than the default.  For example, if you
+are building modem firmware for an FCDEV3B V1 board where you need to disable
+sleep, you should run the configure script as follows:
+
+./configure.sh fcdev3b stdmodem DISABLE_SLEEP=1 SUFFIX=-nosleep
+
+The build directory would then become build-fcdev3b-stdmodem-nosleep, and the
+specified suffix will also be included in the firmware version ID string that
+gets compiled into the image.
+
+To actually compile the firmware, cd into the created build directory and run
+make there.  Unfortunately the use of TI's proprietary compiler via Wine makes
+the build quite slow, but there is a trick to speed it up: if you run some
+other Wine program that stays open and does not exit on its own (e.g., wine cmd)
+in another window and leave it open while you run your FC Tourmaline fw build,
+the build will proceed much faster - the presence of another Wine process using
+the wineserver environment will keep Wine from shutting this environment down
+and restarting it for every individual cl470 run, i.e., for each individual C
+source file.
+
+When the build is done, the flashable firmware image will be in fwimage.bin.
+This image is to be flashed with fc-loadtool at a target-dependent base address.
+The build system also produces a short text file named flash-script which is a
+flashing command script for fc-loadtool that erases the correct range of flash
+sectors and then programs fwimage.bin at the right address.
+
+When building firmware for the FCDEV3B or for the Pirelli, one can build either
+a flashable image or a RAM-loadable one - or both.  Because this part of the
+build system is common with other targets for which only flash images can be
+produced, the Makefile always builds the flashable image by default -
+fwimage.bin is always meant for flash and never for RAM.  To build a RAM-
+loadable image when the target allows it, run 'make ram' - the image will be in
+ramimage.srec, which you can then load and run on the target with FreeCalypso
+host tool fc-xram.
+
+Cached libraries
+================
+
+In the build architecture of all TCS211-based firmwares including Tourmaline,
+each fw component is first compiled into a linkable library (*.lib file with
+TI's TMS470 toolchain), and then these libraries are linked together into the
+final code image.  Early in FreeCalypso project history many of these component
+libraries were blobs, meaning that we had to use prebuilt libraries for which
+we had no corresponding source.  Our fw has now been almost fully deblobbed,
+meaning that we have transitioned from blobs to recompilation from source for
+almost all of our fw components.  But this deblobbing has had an unfortunate
+downside: because our Wine-based compiler is very slow, every time we deblobbed
+a component library, build times would get longer and longer.
+
+FC Tourmaline introduces a partial solution to this problem in the form of
+cached libs.  Some component libraries are completely independent of
+configuration particulars, i.e., they remain exactly the same no matter which
+Calypso target you are building firmware for, and are likewise unaffected by
+our various supported functional configs.  Prebuilt versions of these config-
+independent libs have been checked into the cache directory of our source tree,
+and Tourmaline fw builds use these cached libs by default.  These cached libs
+are NOT blobs in that we do have the corresponding source for them, and the
+versions that are checked in have been built by us, not by any evil source-
+withholding third parties.  You can disable the use of cached libs and force
+full recompilation from source by adding a USE_CACHE=0 argument to your
+configure.sh line.
+
+Running on the hardware
+=======================
+
+In order to run the firmware you have built on your Calypso phone or modem
+(flash or run in RAM as appropriate), you will need to use FreeCalypso host
+tools.  The current version at any given moment can be found at this URL:
+
+ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2
+
+Please see target-specific notes for more details.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Config-vars	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,203 @@
+The following Bourne shell variables can be set on the ./configure.sh command
+line to tweak the firmware build configuration:
+
+ALLOW_CSIM_GSM
+
+	Per TI's original design, the AT+CSIM command does not allow GSM APDUs
+	of class 0xA0.  Openmoko found some need for them, and they patched
+	their modem fw to allow these APDUs with AT+CSIM.  With our new hybrid
+	modem fw this policy setting is configurable at build time; the default
+	is ALLOW_CSIM_GSM=1 (GSM APDUs allowed).
+
+DISABLE_SLEEP
+
+	The general default is DISABLE_SLEEP=0, and the firmware automatically
+	enables all of the chipset's available sleep modes on boot.  Setting
+	DISABLE_SLEEP=1 causes all sleep modes to be disabled by default on
+	boot (they can still be enabled with the AT%SLEEP command); this
+	setting is needed for FCDEV3B V1 boards that have a hardware bug that
+	causes breakage when sleep modes are enabled.
+
+FCHG_STATE
+
+	This setting enables or disables the FCHG battery charging driver.
+	This driver can be enabled even on targets where no charging hw exists
+	(it won't do anything without explicit configuration), and our UI
+	firmware will soon require FCHG to be always present - hence our current
+	config mechanism already sets FCHG_STATE=1 for UI-enabled configs.  If
+	the firmware is built in a non-UI modem or VPM configuration, the
+	default FCHG_STATE setting depends on the target: enabled on targets
+	that have battery charging hardware (c11x, c139, c155, j100, pirelli)
+	and disabled otherwise.
+
+L1_DYN_DSP_DWNLD
+
+	This setting enables TI's dynamic DSP patch download mechanism.  When
+	the firmware is built for a Calypso target with DSP ROM version 36 in
+	the silicon (all FreeCalypso-made hw and most of the supported legacy
+	targets), L1_DYN_DSP_DWNLD is enabled by default and needs to be kept
+	enabled for correct operation: the patch code we got from TI for this
+	ROM is the dynamic download version, and the ARM-side L1 code expects
+	all of these patches to be present, both the static part and the
+	dynamic parts.  However, one can build our fw with L1_DYN_DSP_DWNLD=0
+	for experimental testing, to see what breaks when the dynamic patches
+	are omitted.
+
+L1_VOICE_MEMO_AMR
+
+	This setting enables or disables support in L1 and in the RiViera Audio
+	Service for AMR voice memo recording and playback.  This code has not
+	been properly studied yet and no test AT commands are provided for it,
+	but it is enabled by default like in TI's original TCS211 fw.
+
+MELODY_E2
+
+	This setting enables or disables support in L1 and in the RiViera Audio
+	Service for playing E2-format melodies.  The default is MELODY_E2=1
+	like in TI's original TCS211 fw.  Note that Melody E1 support is always
+	enabled; setting MELODY_E2=0 disables only Melody E2, but not E1.
+
+MEMSUPER
+
+	This setting enables the memory supervision feature in TI's GPF and in
+	the G23M protocol stack built on top of it.  This code has not been
+	properly studied yet; play with it at your own risk.
+
+OSL
+
+	This flag selects between original blob and reconstructed C versions of
+	the OSL glue component of GPF - see the Blob-status article.
+
+OSX
+
+	This flag selects between original blob and reconstructed C versions of
+	the OSX glue component of GPF - see the Blob-status article.
+
+RVTMUX_ON_MODEM
+
+	This setting configures the usage of Calypso UARTs.  RVTMUX_ON_MODEM=0
+	puts the AT command interface on the MODEM UART and RVTMUX on the IrDA
+	UART (TI's intended config and the default on sensible hw targets);
+	RVTMUX_ON_MODEM=1 (default on the crippled C1xx targets) puts RVTMUX on
+	the MODEM UART, sacrificing the standard AT command interface.
+
+SERIAL_DYNAMIC_SWITCH
+
+	TI's TCS211 fw includes a provision (only for Bluetooth-enabled fw in
+	TI's original) to switch one UART between the AT command interface and
+	RVTMUX while the other UART is fixed for Bluetooth.  In FreeCalypso we
+	have changed this code to work without Bluetooth, for the purpose of
+	switching the user-facing MODEM UART between AT commands and RVTMUX,
+	but the mechanism does not work properly yet and is disabled by default.
+	Enable it with SERIAL_DYNAMIC_SWITCH=1 if you would like to play with
+	it.
+
+SPEECH_RECO
+
+	This setting enables or disables support in L1 and in the RiViera Audio
+	Service for TI's speech recognition mechanism.  This code and the
+	underlying DSP facility itself have not been properly studied yet and
+	no test AT commands are provided for it, but it is enabled by default
+	like in TI's original TCS211 fw.
+
+SUFFIX
+
+	This setting is solely for configuration management.  If you make a
+	build with any of the settings described in this document changed from
+	the default, you should also pass a SUFFIX=-xxx argument so your special
+	build will be appropriately identified in the build directory name and
+	in the firmware version ID string compiled into the image.  The naming
+	of suffixes is up to you, but here are some examples:
+
+	DISABLE_SLEEP=1 SUFFIX=-nosleep
+	L1_DYN_DSP_DWNLD=0 SUFFIX=-nodyn
+	MELODY_E2=0 SUFFIX=-noe2
+	MEMSUPER=2 SUFFIX=-ps
+	SERIAL_DYNAMIC_SWITCH=1 SUFFIX=-sds
+	SPEECH_RECO=0 SUFFIX=-nosr
+	TI_PROFILER=1 SUFFIX=-prf
+	TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500
+	USE_STR2IND=1 SUFFIX=-s2i
+
+TI_PROFILER
+
+	TI's original firmware architecture had a built-in profiler (program
+	counter sampler) enabled with TI_PROFILER=1; we (FreeCalypso) are just
+	beginning to experiment with this debug feature in late 2020.
+
+TRACEMASK_IN_FFS
+
+	TI's Test Interface (TIF) component in the GPF realm includes an
+	optional feature for saving trace masks in FFS, but TI's production
+	firmwares had it disabled.  We have now switched to recompiling the
+	component in question from source, but we still keep this
+	TRACEMASK_IN_FFS code disabled by default, at least for now.
+	Set TRACEMASK_IN_FFS=1 to enable this code in GPF.
+
+TR_BAUD_CONFIG
+
+	The value of this symbol is an alphanumeric keyword of the form
+	TR_BAUD_xxxxxx; the default is TR_BAUD_115200.  See
+	src/cs/drivers/drv_core/uart/traceswitch.h for the available baud rate
+	choices; the most practical use is setting TR_BAUD_CONFIG=TR_BAUD_812500
+	when you need to run the RVTMUX serial channel at the maximum possible
+	baud rate.
+
+USE_CACHE
+
+	This setting enables or disables the use of cached libs - see the
+	Cached libraries section in the Compiling article for the explanation.
+
+USE_STR2IND
+
+	Unlike TI's original firmwares, we build without str2ind by default.
+	You can enable str2ind with USE_STR2IND=1, but the time to build the fw
+	will be significantly longer as the compiler has to be run twice for
+	each C source file, with str2ind sandwiched in between.
+
+The following Bourne shell variables are used inside the build system, set by
+functional configuration stanzas:
+
+GPRS
+
+	Self-explanatory: enables or disables GPRS.
+
+MMI
+
+	TI's original config variable: MMI=0 for the AT-command-controlled
+	modem configuration or MMI=2 for the UI-enabled configuration with
+	BMI and MFW.
+
+R2D_STATE
+
+	Enables or disables inclusion of the R2D driver in the firmware.
+
+R2D_EMBEDDED_LCD
+
+	This setting selects the framebuffer config to be used by the R2D
+	driver, valid settings are:
+
+	R2D_EMBEDDED_LCD=7: D-Sample color framebuffer
+	R2D_EMBEDDED_LCD=8: D-Sample B&W framebuffer
+	R2D_EMBEDDED_LCD=10: new FreeCalypso 96x64 pixel B&W framebuffer
+
+	See src/cs/drivers/drv_app/r2d/r2d_config.h for the details.
+
+SRVC
+
+	TI's original config variable, selects the presence or absence of data
+	services other than GPRS as follows:
+
+	SRVC=0: voice and SMS only
+	SRVC=1: CSD and fax enabled
+	SRVC=2: CSD enabled, but not fax
+
+UI_CONFIG
+
+	The two allowed settings in FC Tourmaline are UI_CONFIG=bigcolor and
+	UI_CONFIG=smallbw.  This setting controls the passing of -DLSCREEN and
+	-DCOLOURDISPLAY to all C modules in the UI layers.
+
+Finally, CHIPSET, DSP, RF and AMR variables reflect the physical configuration
+of the selected target hw that no amount of software hacking can change.
+(The AMR variable indicates the presence or absence of AMR support in the DSP.)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Luna-notes	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,25 @@
+FreeCalypso Luna phone handset UI development platform consists of these 3
+components:
+
+* A Caramel-type Calypso motherboard, either iWOW DSK or FC Caramel2
+* An LCD carrier board, currently using HaoRan HT020K1QC36S LCD module
+* A 5x5 keyswitch matrix board for the keypad function
+
+This Luna is our primary official platform for FreeCalypso phone handset UI
+development.  The UI code we got from TI comes in two interesting versions:
+
+* Big color version: 176x220 pixels, 16-bit color
+* Small B&W version: originally 84x48 pixels, we are extending it to 96x64 pix
+
+(Originally there was also a third version, large 176x220 pix B&W, but we find
+ it uninteresting and we've removed it from our supported set.  It was really
+ nothing more than a hack to display a minimal-effort derivative of the original
+ small B&W UI on the large D-Sample LCD, so we are not removing anything of any
+ real substance here.)
+
+FC Luna hardware is required for anyone who wishes to work on the phone handset
+UI project in FC Tourmaline: it is the only target platform that can display
+both versions of our work-in-progress UI firmware.  Mot C1xx and other similar
+phones have small LCDs that can only display the small B&W version of our
+TI-based UI, and in the Mother's opinion working solely on the smallbw version
+to the exclusion of the bigcolor version is not acceptable.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Modem-operation	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,16 @@
+FC Tourmaline stdmodem functional configuration is equivalent to Magnetite
+hybrid.  The only intentional diff from Magnetite to Tourmaline in the modem
+configuration is the change of Nucleus: Magnetite uses the blob version of
+Nucleus which came with TCS211-20070608, whereas Tourmaline uses the source
+version of Nucleus by Comrade XVilka.  It is essentially a change from an
+unknown version of Nucleus to a known one, thus it should generally be
+considered an improvement - but as always with such changes, extensive
+verification and testing needs to be done in order to ensure that nothing got
+broken.
+
+Aside from the one intentional change of Nucleus version, FC Tourmaline is an
+entirely new firmware source tree, thus it is always possible that something
+could have got broken unintentionally, particularly in rarely-tested areas of
+the firmware.  Therefore, extensive testing will need to be done before we can
+declare Tourmaline stdmodem as officially replacing Magnetite hybrid for stable
+modem products.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Voice-pseudo-modem	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,92 @@
+Back when TI's TCS211 fw existed in the traditional world of phone handset and
+cellular modem manufacturers, there were only two principal classes of target
+devices for it: handsets and modems.  The former have local UI hardware (LCDs
+and keypads) and run firmware that works with this UI hw, the latter have no
+such hw and run firmware that expects to be controlled by an external host via
+AT commands.
+
+But the peculiar circumstances under which our FreeCalypso family of projects
+operates give rise to a third possibility: what happens if one were to run
+non-UI-capable firmware that expects control via AT commands on a hardware
+target device that was originally designed to be an end user phone handset, in
+our case either Motorola C1xx or Pirelli DP-L10?  The result is what I call a
+voice pseudo-modem (VPM): the phone's LCD stays dark, the buttons do nothing
+and the device expects to be controlled via AT commands as if it were a modem
+like the one in GTA01/02 smartphones, but there is no practically usable way to
+make use of any data services, only voice and SMS, hence my VPM term.
+
+It needs to be noted clearly that the VPM hack described in this article is NOT
+a substitute for proper modem hardware - if your area of interest is Standard
+Modem functionality (the full set of GSM and GPRS services accessed via AT
+commands), then you need a proper hardware platform for it, either FCDEV3B or
+Caramel2.  However, support for VPM operation in FreeCalypso exists for the
+following purposes:
+
+* On some hw targets the VPM configuration can be an intermediate stepping stone
+  toward potential future UI-enabled firmware - this situation holds on the
+  C139.
+
+* Being able to run FreeCalypso fw in the VPM configuration on Mot C1xx hw that
+  many people already have and that may still be readily and cheaply available
+  makes our firmware accessible to those who are not able to buy new FreeCalypso
+  hardware.
+
+* If you have a Pirelli DP-L10 phone (now very rare and hard to get, but were
+  readily available in early 2013 when I started FreeCalypso): while there is
+  unfortunately very little chance of being able to turn it into a practically
+  usable Libre Dumbphone with FreeCalypso (the unwanted extra chips sans docs
+  which we don't know how to power down are a killer), running FreeCalypso fw
+  on the Pirelli in the VPM configuration is so easy and convenient that I do
+  it all the time during development and testing.
+
+Playing with FreeCalypso VPM on C1xx phones
+===========================================
+
+If a Mot C1xx phone is flashed with a FreeCalypso firmware image in the VPM
+configuration, it will behave as follows:
+
+* The LCD will remain dark and the buttons will do nothing no matter what.
+
+* If you plug in Motorola's charging adapter (it's a regulated 5 VDC power
+  source, but with a non-USB connector) and you had properly installed the
+  charging config file when creating the aftermarket FFS for FreeCalypso, the
+  battery will charge.  When you unplug the charging adapter, if there is no
+  host computer running FC host program rvinterf connected to the phone
+  serially, the phone will power off some 15 to 20 s after the charger unplug.
+
+* If you press the power button while the phone is off, even momentarily, the
+  phone will power on and boot (with nothing on the LCD as usual), but if the
+  headset jack serial port is not connected to a computer running rvinterf, the
+  firmware will execute a power-off after at most 20 s.
+
+* In order to make the phone-turned-VPM do anything useful, you will need to
+  connect the headset jack serial port to a host computer running FC host tools,
+  run rvinterf to keep the phone alive (keep it from automatically powering
+  off), and use FC host utility fc-shell to issue AT commands to it over the
+  RVTMUX channel managed by rvinterf.
+
+* The phone will remain on (i.e., the fw won't execute an automatic power-off)
+  for as long as there is either a charging power adapter plugged in or a
+  connected host computer running rvinterf - if there is no charging power,
+  the fw will send periodic keepalive queries to check for the presence of a
+  connected rvinterf process.
+
+Playing with FreeCalypso VPM on a Pirelli DP-L10
+================================================
+
+There are two ways in which one can play with FC VPM firmware on a Pirelli:
+
+* FC VPM fw can be flashed into the phone just like on Mot C1xx.  To make this
+  approach sensible, you will also need to craft and install a charging config
+  file that will cause our FCHG driver to initiate the charging process
+  automatically when the battery voltage falls below some sensible threshold,
+  without requiring manual charging start via AT@CHG=1.  In this case the
+  reflashed phone will behave like C1xx in the previous section, except that
+  the charging power source and the host computer connection are one and the
+  same in the case of Pirelli's USB.
+
+* The other approach is to keep Pirelli's original fw in the flash, let the
+  phone function normally when not in the middle of a FreeCalypso VPM session,
+  and load our FC VPM fw into RAM via fc-xram, making use of this phone's huge
+  RAM that can hold an entire functional fw image without flashing.  This is
+  the Mother's preferred method.