--- a/CHANGES	Fri Nov 27 04:39:38 2020 +0000
+++ b/CHANGES	Sat Nov 28 00:32:41 2020 +0000
@@ -54,6 +54,10 @@
   new Tourmaline firmware.  The corresponding back end programs are
   compile-fc-batt and compile-fc-batt2.
 
+* New arfcn2ti and ti2arfcn utilities convert back and forth between standard
+  ARFCNs and TCS211 L1 radio_freq numbers - see the new doc/ARFCN-mapping
+  article.
+
 * Documentation updates that don't involve any changes in actual code:
   doc/Loadtools-usage instructions for FC Tango and for new Compal targets
   (Mot V17x), doc/TIFFS-Overview updates for new tools including the new FFS

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/ARFCN-mapping	Sat Nov 28 00:32:41 2020 +0000
@@ -0,0 +1,137 @@
+Frequency bands and band-pairs
+==============================
+
+TI's TCS211 L1 (meaning Layer1 component of TI's TCS211 reference fw and of all
+FreeCalypso firmwares that are based on TCS211) can operate either in a single
+frequency band or in a pair of bands (one low band and one high band)
+corresponding to a regional standard.  TI's G23M protocol stack (specifically
+its ALR component) commands L1 to operate in a given "standard" (single band or
+pair of bands) by way of MPHC_INIT_L1_REQ primitive, which appears in L1 debug
+trace output (seen via rvtdump or rvinterf) as a BAND_R trace.  The "standard"
+number that appears in this BAND_R trace is one of the following 8
+possibilities:
+
+STD 1 (GSM)
+
+	This STD tells L1 to operate only in the GSM900 band by itself (not
+	paired with DCS1800), and furthermore to use the old definition of this
+	GSM900 band with only 124 channels.  TI's code supports this option in
+	order to support old RF hardware that was made for this old definition
+	of the GSM900 band, but none of the phones, modems or development boards
+	we work with in FreeCalypso are this old - thus this STD 1 should never
+	get activated unless something is misconfigured somewhere.
+
+STD 2 (GSM_E)
+
+	This STD tells L1 to operate in the EGSM band, i.e., the new extended
+	definition of the 900 MHz band with 174 channels total - but it still
+	specifies only the EGSM band by itself, not paired with DCS1800.  We
+	don't have any FC hardware targets that support the 900 MHz band but
+	don't support DCS1800, thus this STD can only get selected if the DCS
+	band is artificially disabled - and we do not currently know of any use
+	case for disabling DCS while keeping EGSM enabled - thus this STD should
+	not be seen in practice either.
+
+STD 3 (PCS1900)
+
+	This STD tells L1 to operate in the PCS band by itself.  This STD
+	selection occurs in regular operation on devices like the Pirelli DP-L10
+	and the tri900 version of our FCDEV3B: on such tri900 platforms the G23M
+	protocol stack switches L1 back and forth between STD 6 (900+1800 MHz
+	band pair, see below) and STD 3 for PCS.  Because tri900 platforms have
+	no support for the GSM850 band, the PCS1900 band gets selected as a
+	singleton (not a band pair) when the device operates on the "US" side
+	of its multi-region frequency band support.
+
+STD 4 (DCS1800)
+
+	This STD tells L1 to operate in the DCS band by itself, not paired with
+	900 MHz GSM or EGSM.  Triband devices built in the tri850 configuration
+	(GTA02-850 and FCDEV3B-850) will select this STD when looking for
+	possible DCS1800 cells - however, our expected user pattern is such that
+	a user living or operating in EU-band lands (EGSM and/or DCS bands)
+	would not be using a tri850 device, much in contrast with the reverse
+	situation where tri900 devices are commonly used in the PCS1900 band.
+
+STD 5 (DUAL)
+
+	This STD selects a band pair consisting of the old 124-channel
+	definition of the GSM900 band plus the DCS1800 band.  Because all hw
+	platforms targeted by FreeCalypso support the 900 MHz band in its new
+	EGSM definition if they support it at all, this STD 5 should never get
+	activated unless something is misconfigured somewhere.
+
+STD 6 (DUALEXT)
+
+	This STD selects the classic "EU" band pair of EGSM + DCS1800.  This STD
+	selection will occur in normal operation on EU dual-band devices like
+	the EU versions of Motorola C1xx and Huawei GTM900-B, as well as tri900
+	and quadband devices operating on the "EU" side of their multi-region
+	frequency band support.
+
+STD 7 (GSM850)
+
+	This STD tells L1 to operate in the GSM850 band by itself.  We don't
+	have any FC hardware targets that support the 850 MHz band but don't
+	support PCS1900, thus this STD can only get selected if the PCS band is
+	artificially disabled.
+
+STD 8 (DUAL_US)
+
+	This STD selects the full "US" band pair of GSM850 + PCS1900.  This STD
+	selection will occur in normal operation on US dual-band devices like
+	the US versions of Motorola C1xx and Huawei GTM900-P, as well as tri850
+	and quadband (but not tri900!) devices operating on the "US" side of
+	their multi-region frequency band support.  Note that tri900 devices
+	will go into STD 3 (PCS1900 band by itself) instead!
+
+ARFCN munging
+=============
+
+When L1 operates in one of single-band standards 1 (GSM), 3 (PCS1900), 4
+(DCS1800) or 7 (GSM850), its internal radio_freq numbers that appear in L1 debug
+traces are exactly equal to standard ARFCNs for that band as defined by ETSI.
+However, when it operates in STD 2 (EGSM by itself) or in any of the dual-band
+standards, it uses its own radio_freq numbers which are different from standard
+ARFCNs.  Non-standard internal radio_freq numbers are used in these cases
+because L1 needs a continuous number range for indexing arrays, and the mappings
+are given below.  STD 6 (DUALEXT) and STD 2 (GSM_E) use the following mapping:
+
+Band	Standard ARFCN	TCS211 L1 radio_freq
+--------------------------------------------
+EGSM	1-124		1-124
+EGSM	975-1023	125-173
+EGSM	0		174
+DCS	512-885		175-548
+
+The internal radio_freq number for the DUALEXT band pair ranges continuously
+from 1 to 548.  STD 2 (EGSM by itself) uses the same mapping without the DCS
+subrange, with radio_freq ranging continously from 1 to 174.  DUAL_US band pair
+(STD 8) uses a continuous radio_freq range from 1 to 423 as follows:
+
+Band	Standard ARFCN	TCS211 L1 radio_freq
+--------------------------------------------
+GSM850	128-251		1-124
+PCS	512-810		125-423
+
+Because these internal radio_freq numbers appear in L1 debug traces, power users
+who like to understand these traces and see what their phone is doing need to
+be able to work with these numbers.  I (Mother Mychaela) currently use a Pirelli
+DP-L10 running its original proprietary fw as my everyday phone, for lack of
+anything better, and because it is a tri900 device, it operates in STD 3 for
+PCS1900 band by itself.  In this configuration all radio_freq numbers that
+appear in the debug trace output are native PCS band ARFCNs without any munging,
+thus no conversion tools are needed.  However, I am now starting to work more
+with quadband Tango modules and development boards (iWOW DSK and FC Caramel2),
+and we also have a few FCDEV3B-850 boards; these platforms support both GSM850
+and PCS1900 bands and thus go into STD 8 for DUAL_US, and this dual-band STD
+involves ARFCN munging as detailed above.  Furthermore, anyone who lives or
+operates in EU-band lands would normally be operating in dual-band STD 6
+(DUALEXT), and that one also involves ARFCN munging.
+
+Because there is a need to translate back and forth between standard ARFCNs and
+L1 radio_freq numbers, a pair of utilities has been written for this purpose:
+arfcn2ti and ti2arfcn.  Their usage and operation is straightforward; each
+utility takes two command line arguments: a keyword of "eu" or "us" selecting
+the band pair being mapped, and the number to be converted.  The output of the
+conversion (the other number) is printed on stdout.

--- a/doc/Host-tools-overview	Fri Nov 27 04:39:38 2020 +0000
+++ b/doc/Host-tools-overview	Sat Nov 28 00:32:41 2020 +0000
@@ -46,6 +46,10 @@
 
 And here is a listing of all other tools in mostly-alphabetical order:
 
+arfcn2ti	These two utilities convert back and forth between standard
+ti2arfcn	ARFCNs and TCS211 L1 radio_freq numbers - see ARFCN-mapping
+		article for the explanation.
+
 c139explore	This is a run-from-RAM (no flashing) program for Mot C139/140
 		phones that exercises their peripheral hardware: LCD, keypad
 		backlight, buzzer and vibrator.