--- a/doc/Compiling	Sun May 10 05:28:05 2015 +0000
+++ b/doc/Compiling	Sun May 10 19:35:29 2015 +0000
@@ -65,3 +65,58 @@
 
 Run 'make all' in target-utils to build some other components that aren't
 really needed.
+
+Compiling FreeCalypso GSM firmware
+==================================
+
+The firmware in our gsm-fw tree can be built in many different configurations,
+hence there is no singular build for it.  The configuration choices consist of:
+
+* Which target device the firmware should be built for: the target device
+  selection is made at compile time; do not attempt to take a firmware image
+  built for one target device and flash or fc-xram it into another!
+
+* What functionality is to be included.  As the FreeCalypso firmware subproject
+  moves forward, we gradually add chunks of functionality, slowly approaching
+  what each target device is ultimately capable of.  However, each time we add
+  a new piece of functionality, the ability to build a firmware image that works
+  like before, without the newly added functionality, still remains.  Each
+  feature to be included needs to be explicitly selected.
+
+* Miscellaneous configuration: which Calypso UART should be used for what,
+  should the firmware use a real FFS (flash file system) in flash or a fake one
+  in RAM, etc.
+
+The GSM firmware build configuration is set by way of an editable text file
+named build.conf; the configuration and build procedure is as follows:
+
+1. Look at the available repertoire of standard configurations under
+   gsm-fw/configs and choose which one you would like to use, either as-is or
+   as a basis for your own;
+
+2. Copy the configuration you selected to build.conf in the gsm-fw directory;
+
+3. Optionally edit it to taste - the configuration language is Bourne shell;
+
+4. Run 'make' in the gsm-fw directory.
+
+Depending on the configuration, either a flashable or a RAM-loadable image will
+be built by default.  A flashable image will appear in finlink/flashImage.bin;
+these images are meant to be programmed with fc-loadtool's flash program-bin
+command; the starting flash address at which the image needs to be programmed
+depends on the target device - see target-specific notes.  A RAM-loadable image
+will appear in finlink/ramImage.srec; these images are meant to be loaded and
+run with the fc-xram utility.
+
+It is possible to build either a flashable or a RAM-loadable image, or both,
+without changing build.conf: run 'make flashImage' or 'make ramImage' as
+desired.  (The compilation of each module from source into a .o and all
+intermediate linking steps are agnostic to whether a flashImage or a ramImage
+is being built, only the very final link step differs.)  Any otherwise working
+configuration can be built into a flashImage, even if it makes no logical sense
+to do so, but the ability to build a ramImage for a given configuration depends
+on the code image size (which in turn depends on the selected feature set) and
+the amount of RAM available on the target in question: most Calypso GSM devices
+have small RAM, enough to satisfy a GSM firmware's data space requirements, but
+not enough to hold the entire firmware code in RAM as well.  Please see target-
+specific notes for more details.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Freerunner-Howto	Sun May 10 19:35:29 2015 +0000
@@ -0,0 +1,57 @@
+How to play with FreeCalypso GSM firmware on a Neo Freerunner
+=============================================================
+
+Aside from the half-source leo2moko fw we produced back in 2013-10 (you can
+read all about that one at www.freecalypso.org/leo2moko/), we don't have a
+working free GSM firmware version for the Freerunner yet.  What we do have
+currently is experimental code that can be built into an image that can be
+flashed into a GTA02 modem - but it doesn't really work yet.
+
+If you would like to play with our experimental code on your Neo FR and maybe
+help us make it work, here are the instructions:
+
+1. Build the firmware in the gtamodem-gsm configuration - see the Compiling
+   document for more details;
+
+2. You should get a flashImage.bin image built; now you need to flash it into
+   your FR's modem.  The serial cable method is highly recommended: the only
+   thing you'll be able to do with our current non-working firmware is help us
+   debug it, and the serial cable will be needed for the latter part anyway.
+
+3. Run fc-loadtool the same way you would if you were flashing leo2moko;
+
+4. The actual flash programming commands are a little different because the
+   image is smaller and in a different format:
+
+flash erase 0 0x160000
+flash program-bin 0 finlink/flashImage.bin
+
+The second number in the flash erase command needs to be the size of
+flashImage.bin rounded up to a multiple of 64 KiB (the flash sector size in the
+GTA02 modem); 0x160000 is correct for the fw image size as of this writing, but
+please double-check it yourself before flashing.  The 0 argument in the
+flash program-bin command is the flash offset at which the image should be
+programmed: it will always be 0 for FreeCalypso flashable fw images for gtamodem
+and other targets that have the Calypso boot ROM enabled in the hardware.
+
+Once you have flashed our experimental fw into your modem, you can power-cycle
+the modem and see the new fw boot.  You should have the serial cable connected,
+the serial channel enabled from the Freerunner's AP side and either rvtdump or
+rvinterf running on your PC or other development machine when you first power
+your modem up with the experimental fw in it: this way you will see whether the
+fw boots successfully or crashes.  If it does boot without crashing (whether or
+not it does seems to depend on some factors which we have yet to understand),
+you will get an AT command interface on the other UART going to the Freerunner's
+AP - now go ahead and play from there. :)
+
+To reflash your modem back to stable and working leo2moko aka moko12, execute
+the following fc-loadtool commands:
+
+flash erase 0 0x230000
+flash program-m0 leo2moko.m0
+
+(Whichever firmware image you are flashing, the flash erase command needs to
+ cover the range of flash sectors this image will occupy.  You can erase more
+ sectors up to 0x300000, the "natural" boundary of the flash area where fw
+ images live, but I prefer to erase only the needed number of sectors: it is
+ both faster and imposes less wear on the flash.)