--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Config-vars	Sun Oct 18 18:08:15 2020 +0000
@@ -0,0 +1,203 @@
+The following Bourne shell variables can be set on the ./configure.sh command
+line to tweak the firmware build configuration:
+
+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.
+	This driver can be enabled even on targets where no charging hw exists
+	(it won't do anything without explicit configuration), and our UI
+	firmware will soon require FCHG to be always present - hence our current
+	config mechanism already sets FCHG_STATE=1 for UI-enabled configs.  If
+	the firmware is built in a non-UI modem or VPM configuration, the
+	default FCHG_STATE setting depends on the target: enabled on targets
+	that have battery charging hardware (c11x, c139, c155, j100, pirelli)
+	and disabled otherwise.
+
+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.
+
+OSL
+
+	This flag selects between original blob and reconstructed C versions of
+	the OSL glue component of GPF - see the Blob-status article.
+
+OSX
+
+	This flag selects between original blob and reconstructed C versions of
+	the OSX glue component of GPF - see the Blob-status article.
+
+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.
+
+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:
+
+	DISABLE_SLEEP=1 SUFFIX=-nosleep
+	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
+	TI_PROFILER=1 SUFFIX=-prf
+	TR_BAUD_CONFIG=TR_BAUD_812500 SUFFIX=-812500
+	USE_STR2IND=1 SUFFIX=-s2i
+
+TI_PROFILER
+
+	TI's original firmware architecture had a built-in profiler (program
+	counter sampler) enabled with TI_PROFILER=1; we (FreeCalypso) are just
+	beginning to experiment with this debug feature in late 2020.
+
+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.  We have now switched to recompiling the
+	component in question from source, 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.
+
+USE_CACHE
+
+	This setting enables or disables the use of cached libs - see the
+	Cached libraries section in the Compiling article for the explanation.
+
+USE_STR2IND
+
+	Unlike TI's original firmwares, we build without str2ind by default.
+	You can enable str2ind with USE_STR2IND=1, but the time to build the fw
+	will be significantly longer as the compiler has to be run twice for
+	each C source file, with str2ind sandwiched in between.
+
+The following Bourne shell variables are used inside the build system, set by
+functional configuration stanzas:
+
+GPRS
+
+	Self-explanatory: enables or disables GPRS.
+
+MMI
+
+	TI's original config variable: MMI=0 for the AT-command-controlled
+	modem configuration or MMI=2 for the UI-enabled configuration with
+	BMI and MFW.
+
+R2D_STATE
+
+	Enables or disables inclusion of the R2D driver in the firmware.
+
+R2D_EMBEDDED_LCD
+
+	This setting selects the framebuffer config to be used by the R2D
+	driver, valid settings are:
+
+	R2D_EMBEDDED_LCD=7: D-Sample color framebuffer
+	R2D_EMBEDDED_LCD=8: D-Sample B&W framebuffer
+	R2D_EMBEDDED_LCD=10: new FreeCalypso 96x64 pixel B&W framebuffer
+
+	See src/cs/drivers/drv_app/r2d/r2d_config.h for the details.
+
+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
+
+UI_CONFIG
+
+	The two allowed settings in FC Tourmaline are UI_CONFIG=bigcolor and
+	UI_CONFIG=smallbw.  This setting controls the passing of -DLSCREEN and
+	-DCOLOURDISPLAY to all C modules in the UI layers.
+
+Finally, CHIPSET, DSP, RF and AMR variables reflect the physical configuration
+of the selected target hw that no amount of software hacking can change.
+(The AMR variable indicates the presence or absence of AMR support in the DSP.)