--- /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.