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
c155		Motorola C155/156
fcdev3b		FreeCalypso FCDEV3B
gtamodem	The Calypso GSM/GPRS modem in Openmoko GTA01/02 smartphones
j100		Sony Ericsson J100
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, c155, 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, c155 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.

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.

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,
	c155 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

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.  The component in question is now compiled
	from source like the rest of our fw, 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.

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

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-r10.tar.bz2

Please see the Running-on-hw article for further instructions.