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