--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Target-utils	Thu Jun 06 06:38:46 2019 +0000
@@ -0,0 +1,132 @@
+FreeCalypso target-utils suite
+==============================
+
+We have a suite of standalone programs and specialized code pieces that run on
+the Calypso ARM7 processor, but are not regular operational phone or modem
+firmware; this suite of code bits is called target-utils, maintained and
+distributed together with FreeCalypso host tools.  The primary reason for the
+coupling between FC host tools and target-utils is that the target-utils suite
+provides the loadagent target program for fc-loadtool and fc-xram host tools,
+as well as compalstage code pieces needed for operating on Compal phones.
+
+Most programs in the target-utils suite are meant to execute out of RAM
+(specifically, the Calypso chip's internal RAM or IRAM for short), loaded and
+run via fc-iram or fc-compalram - they are not meant to be flashed.  As of this
+writing, the following run-from-RAM programs are available:
+
+buzplayer	Player for buzzer melodies, used by fc-buzplay
+c139explore	Mot C139 hardware exploration program
+calversion	Calypso version ID tool, primarily for the DSP ROM version
+helloapp	Hello-world program
+loadagent	Flash manipulation and XRAM loading agent
+pirexplore	Pirelli DP-L10 hardware exploration program
+simtest		Low-level exerciser for the SIM interface hardware
+
+Aside from c139explore which is built as a binary to be loaded via fc-compalram
+(Compal's bootloader protocol), all of the above programs are built as S-record
+images to be loaded via fc-iram.  Once loaded via the respective serial code
+download protocol, each of the listed programs runs interactively, listening
+for and executing commands given over the serial port.  The specific set of
+available commands is different for each program as relevant to its function,
+but the command framework is common across the target-utils suite.  The command
+interface is text-based, such that each program can be driven manually by a
+human operator once fc-iram or fc-compalram has dropped into the tty pass-thru
+mode, but this same text-based command interface can also be driven by other
+programs: fc-loadtool and fc-xram drive loadagent, and fc-buzplay drives
+buzplayer.
+
+Code architecture and execution environment
+===========================================
+
+Our target-utils suite is built with the GNU toolchain (gcc+binutils), not TI's
+proprietary TMS470 compiler.  Because all of target-utils are meant to run out
+of IRAM rather than flash or XRAM, we compile all code in ARM mode (not Thumb),
+and we build without interworking support (no -mthumb-interwork): the ARMv4T
+architecture implemented by the ARM7TDMI core in the Calypso does not support
+penalty-free ARM/Thumb interworking, thus ARM-only code without interworking
+support is the most efficient option for execution out of IRAM.
+
+Selection of UART for communication
+===================================
+
+All target-utils programs are interactive, listening for text commands given
+over a serial port.  But which UART?  The Calypso chip has two UARTs, called
+MODEM and IrDA in the chip docs - which of the two should be used for host
+communication?  The answer is a trick original to FreeCalypso: most of our
+target-utils programs that are meant to be loaded via fc-iram expect to be
+loaded specifically via the Calypso boot ROM and not in some other way, and
+they look at some of the IRAM variables left behind by the boot ROM code.  The
+boot ROM listens on both UARTs for an interrupt-boot sequence, and once it
+receives that sequence on one of the UARTs, it remembers which UART it was and
+uses that same UART for the rest of the serial code download protocol.  We read
+that same variable set by the boot ROM, which depends on the boot ROM version.
+To handle different Calypso boot ROM versions, we read the 16-bit word at 0x1FFE
+(the last 16 bits of the boot ROM image) where TI put the boot ROM version
+number, and we support boot ROM versions 0200 (Calypso C05 rev B silicon) and
+0300 (Calypso C035 silicon).  Most target-utils programs won't work (will fail
+to select the UART for communication) if the boot ROM is some unsupported
+version or missing altogether, or if the boot ROM is there, but didn't do the
+loading.
+
+The exceptions are as follows:
+
+* c139explore always uses the MODEM UART as appropriate for Mot C139;
+
+* flash-boot-test (a flashable program described later in this article) always
+  uses the IrDA UART;
+
+* helloapp is built in 3 versions: helloapp-bootrom.srec, helloapp-irda.srec
+  and helloapp-modem.srec.  The first version depends on the boot ROM like
+  other programs, the other two versions are built as fixed-IrDA or fixed-MODEM.
+
+Other boot ROM and fc-iram dependencies
+=======================================
+
+There are two other ways in which target-utils programs that are meant to be
+loaded via fc-iram depend on the Calypso boot ROM:
+
+1) The Calypso gets its clock input from the RF section of the GSM device, and
+   the RF block can feed either 13 MHz or 26 MHz to the Calypso - some GSM RF
+   transceiver chips require 13 MHz (TI Clara), others require 26 MHz (TI Rita
+   and Silabs Aero II), yet others can work with either clock (Silabs Aero+),
+   and some use a 26 MHz crystal but have the option of feeding either 13 or
+   26 MHz to the Calypso (Aero II).  The Calypso initially boots without knowing
+   what clock frequency it is running at, but then it needs to be told via a
+   register setting what the input clock frequency is, so that all peripherals
+   (both GSM-specific and general-purpose) always run at 13 MHz.
+
+   When the Calypso boot process is interrupted and diverted to serial code
+   download in the boot ROM, the boot ROM code autodetects whether the CLKTCXO
+   input runs at 13 MHz or 26 MHz (it tries both register bits settings until
+   the serial '<' characters sent by the host at 19200 baud are received
+   correctly), and if the CLKTCXO input is 26 MHz, the VCLKOUT_DIV2 bit is set
+   in the FFFF:FD02 register.  Most of our target-utils programs have no hard-
+   coded knowledge of the 13 MHz vs. 26 MHz board hardware configuration and
+   rely on the Calypso boot ROM to set the division control bits in the
+   FFFF:FD02 register correctly for the autodetected clock.
+
+2) The boot ROM allows the serial download host (fc-iram in our case) to
+   configure the Calypso DPLL, allowing the ARM7 core to run at its maximum
+   frequency of 52 MHz on Calypso C035 or 39 MHz on the older Calypso C05
+   silicon.  None of our target-utils programs do their own DPLL setup, instead
+   they run with whatever they were booted with - therefore, in order for the
+   IRAM programs to run at their intended fastest speed, the correct -h option
+   needs to be given to fc-iram, selecting a hardware parameter file with the
+   right pll-config setting.
+
+Delay loop timing
+=================
+
+There are a few places in target-utils where a delay of some specific duration
+needs to be inserted.  In most cases the requirement is for a certain minimum
+delay, with more delay time being harmless except for inefficiency, but there
+is one case (SPCA552E chip initialization in pirexplore) where the delay
+requirement is strict: if the delays are too short or too long, the LCD doesn't
+work.  In target-utils all of these delays are implemented with CPU-cycle-count
+delay loops that are calibrated at software design time; if the code runs out
+of IRAM and the ARM7 core runs at 52 MHz, the delays will be exactly as
+designed, otherwise they will be longer.  In the case of pirexplore the strict
+timing requirement is satisfied by loading and running the program via fc-iram
+-h pirelli, resulting in the correct 52 MHz clock configuration; in all other
+cases running at a frequency below 52 MHz or running out of flash (the
+flash-boot-test special case) produces longer-than-needed delays.