--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compiling	Mon Oct 03 04:26:16 2016 +0000
@@ -0,0 +1,108 @@
+Preparing the development and build environment
+===============================================
+
+In order to compile our FreeCalypso Magnetite 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.  This author uses Slackware Linux
+version 13.37, 32-bit.
+
+You will need to install the following four pieces of software on whatever
+machine you will use to run the FC Magnetite build process:
+
+1. Wine: self-explanatory.
+
+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
+
+   Note that Wine may produce different whines on your system than it
+   does on mine, in which case if you wish to be relieved of those
+   whines, you'll need to edit my nowhine.c hack for your situation.
+
+4. mokosrec2bin flash image file format conversion utility:
+
+   ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c
+
+Note that the four host software pieces above are exactly the same as what has
+been needed to build our previous TCS211-based fw works such as leo2moko-debug
+and tcs211-c139 - thus if you have built those previously, you should already
+have all of the necessary host tools.
+
+Compiling the local helper utilities
+====================================
+
+(cd helpers; make)
+
+Do the above.  Most of the build helper scripts used in the FC Magnetite 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
+Magnetite 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-magnetite 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 Magnetite firmware for a particular target in
+a particular configuration, run a command like this from the top level of the
+fc-magnetite tree:
+
+./configure.sh gtamodem l1reconst
+
+The first argument to the configure.sh script selects the target, and the second
+argument selects the configuration.  As of this writing, the following targets
+are supported:
+
+c139		Motorola C139
+fcdev3b		FreeCalypso FCDEV3B (hardware designed but not built yet)
+gtamodem	The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
+pirelli		Pirelli DP-L10
+
+For the available configurations (the second required argument to the configure
+script), look in the configs directory.  As of this writing, the most
+interesting configuration is l1reconst - it was named so because it rebuilds L1
+from the reconstructed source.
+
+Each configuration is built in its own directory; by default the build directory
+is named build-$TARGET-$CONFIG, i.e., for the example configure.sh line above,
+the resulting build directory will be build-gtamodem-l1reconst.  You can change
+the name of this directory by appending a BUILD_DIR=dir argument to the
+./configure.sh line after the two required arguments.
+
+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 very slow - it takes about 42 minutes on my machine.  When it's all
+done, the flashable firmware image will be in fwimage.bin.  This image is to be
+flashed with fc-loadtool at address 0x10000 on the C139 and at address 0 on all
+other targets.
+
+When building firmware for the Pirelli or for future FreeCalypso hardware that
+will use the same high capacity flash+pSRAM chip, 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.
+
+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.  As of this writing, the latest packaged release is this one:
+
+ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-r4.tar.bz2
+
+Please see target-specific notes for more details.