--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Compiling	Tue Jul 24 23:55:24 2018 +0000
@@ -0,0 +1,223 @@
+Selecting and preparing the compiler environment
+================================================
+
+FreeCalypso Selenite firmware can be built with two different compiler
+toolchains: either with TI's original TMS470 compiler or with gcc.  Transition
+to compiling with gcc is a very bold move with very heavy fallout, and many
+parts of the fw are still broken or destabilized when built with gcc instead of
+the original compiler they were developed with, thus for the foreseeable future,
+anyone who aspires to be a FreeCalypso developer will need to compile our fw in
+both ways, compare the behaviour of the two versions, and work toward making
+the gcc-built version perform as well as the TMS470-built one.  Thus you need
+to have both compiler toolchains installed and working - see the
+Toolchain-setup-470 and Toolchain-setup-gcc articles for the instructions.
+
+Compiling the local helper utilities
+====================================
+
+(cd helpers; make)
+
+Do the above.  Most of the build helper scripts used in the FC Selenite 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
+Selenite 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-selenite tree.  You
+just need to run make in the helpers directory once before any actual firmware
+builds.
+
+Actually building the firmware
+==============================
+
+To build our FC Selenite firmware for your hw target of interest in the default
+configuration, run a command like this from the top level of the fc-selenite
+tree:
+
+./configure-gcc.sh fcdev3b
+
+or
+
+./configure-tms470.sh fcdev3b
+
+As of this writing, the following hardware targets are supported:
+
+c11x		Motorola C11x/12x
+c139		Motorola C139/140
+fcdev3b		FreeCalypso FCDEV3B
+gtamodem	The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
+pirelli		Pirelli DP-L10
+
+Notice the difference from FC Magnetite: there is no "configuration name"
+argument after the target name.  Because FC Selenite does not include any UI
+code (modem functionality only) and does not offer different versions of
+various fw components the way Magnetite does, it does not have named
+configurations in the same sense as Magnetite.  Instead any configuration
+tweaks are done via var=value optional arguments on the configure command line
+after the required target name argument; the following variables are currently
+available for tweaking:
+
+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.  By
+	default it is enabled on targets that have battery charging hardware
+	(c11x, c139, pirelli) and disabled on those that don't have such hw
+	(fcdev3b, gtamodem).
+
+GPRS
+
+	Self-explanatory: enables or disables GPRS.  By default GPRS is enabled
+	on proper modem hw targets (fcdev3b and gtamodem) and disabled on c11x,
+	c139 and pirelli.
+
+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.
+
+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.
+
+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
+
+	The default is SRVC=1 (fax and data enabled) for proper modem hw targets
+	(fcdev3b and gtamodem) and SRVC=0 (voice and SMS only) on c11x, c139
+	and pirelli.
+
+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:
+
+	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
+	TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500
+
+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.
+
+Each configuration is built in its own directory; the name of this build
+directory always begins with build- and is constructed to reflect the
+configuration.  The auto-generated build directory name includes the name of
+the target, the selection of services to be included based on the GPRS, SRVC
+and FCHG_STATE variables, and a -470 or -gcc suffix indicating the compiler
+toolchain, but if you manually override any of the other config variables
+described above, you should also include a SUFFIX=-xxx argument giving an
+identifying suffix for your own configuration changes.
+
+To actually compile the firmware, cd into the created build directory and run
+make there.  With gcc the build proceeds very fast because the compiler runs
+natively, but building with the original TMS470 compiler requires going through
+Wine, which is much slower.  There is, however, a trick to speed up these
+TMS470 builds: 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 Selenite TMS470 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 address 0x10000 on Mot C11x and
+C139 targets, and at address 0 on the more sensible targets that have the
+Calypso boot ROM enabled.  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.
+
+Running on the hardware
+=======================
+
+In order to run the firmware you have built on your FCDEV3B or other Calypso
+device (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-r8.tar.bz2