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
dspdump		Calypso DSP ROM dump tool
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.

Common interactive commands
===========================

The exact set of implemented commands is different for each target-utils
program, including commands specific to each program's unique function, but the
following basic commands are included in most programs:

abbinit			Initialize ABB communication
abbpage2		Unlock access to ABB register page 2
abbr pg reg		Read ABB register <reg> on page <pg>
abbw pg reg val		Write <val> into register <reg> on page <pg>
dump hex-start hex-len	Display a human-oriented memory dump in hex and ASCII
jump addr		Jump to given address with BX
poweroff		Execute Iota ABB soft poweroff (DEVOFF)
r8 addr			Read an 8-bit register or memory location
r16 addr		Read a 16-bit register or memory location
r32 addr		Read a 32-bit register or memory location
w8 addr data		Write an 8-bit register or memory location
w16 addr data		Write a 16-bit register or memory location
w32 addr data		Write a 32-bit register or memory location

For further details, please refer to the source code - if you are playing with
such low-level components, you need to put on the hat of a developer rather
than a mere user.

ABB support in target-utils
===========================

Our target-utils suite includes code for initializing and executing SPI
communication with the Iota ABB device (TWL3014 or TWL3025), Calypso's analog
and power management companion chip.  Only Iota ABB type is supported, not
Omega/Nausica or Syren.  The primary reason for having this infrastructure is
to be able to perform a soft poweroff operation, i.e., to return the Calypso
phone or modem to its switched-off state after flashing or various standalone
debug operations, but once implemented, this same ABB SPI communication
infrastructure is also used in model-specific hardware exploration utilities
for functions like keypad backlight and vibrator control which are implemented
via the ABB on some models, and it is used in simtest to control the part of
the SIM interface that resides in the Iota ABB.

Aside from specialized programs like c139explore that are specific to target
devices known to use the Iota ABB, most target-utils programs do not execute
any ABB or SPI communication code (not even initialization) until they receive
one of the ABB commands: abbinit, abbr, abbw or poweroff.  This way if someone
comes across a Calypso device that has a different ABB type or needs to debug a
board with broken ABB communication, one can explore other functions without
touching ABB commands.  (simtest is another exception: even though it is not
specific to one particular target device like c139explore, its main function of
exercising the SIM interface depends on the Iota ABB, thus it is restricted to
Calypso+Iota targets.)

The abb_init() function invoked by the abbinit command may be invoked multiple
times: it maintains an internal flag remembering if the initialization steps
have already been done or not, and repeated invokations do nothing.  User-
friendly abbr, abbw and poweroff commands invoke abb_init() internally, but the
special abbpage2 command does not - if you are interested in exploring the
undocumented register page 2, you need to execute abbinit manually first, then
abbpage2, then explore with abbr and abbw.

poweroff operation details: VRPCAUX and VRPCDEV
===============================================

The abb_power_off() function invoked by the poweroff command performs the
following sequence of steps:

* Calls abb_init() to establish ABB communication in the case that it hasn't
  already been done;

* Executes the magic writes to TAPCTRL and TAPREG registers that unlock access
  to register page 2 - this step is factored out into the abb_unlock_page2()
  function which is also accessible as the abbpage2 command;

* Writes 0x007 into the undocumented VRPCAUX register to clear the erratic
  state that will be there if we got booted via nTESTRESET rather than PWON;

* Flushes all UART output, i.e., waits for it to finish going out on the wire;

* Writes 0x001 into the VRPCDEV register, which is the actual DEVOFF command.

The step of writing into VRPCAUX and its prerequisite page 2 unlock steps are a
recent addition as of fc-host-tools-r11; these steps have been added to fix the
erratic behaviour that was occurring on TI/FC development boards (D-Sample and
FCDEV3B) when fc-loadtool (or fc-iram with some specialized target-utils
program) was entered via the RESET button rather than PWON, followed by the
soft poweroff operation and another switch-on via PWON.  For more details,
please refer to the Calypso-test-reset article in the freecalypso-docs
repository.

If you are interested in doing some experiments of your own with this
undocumented quirk of the Calypso+Iota chipset and the odd behaviour it can
cause, you can do the following:

* To see the content of the undocumented VRPCAUX register resulting from
  different boot modes, execute these commands:

  abbinit
  abbpage2
  abbr 2 30

  Our abbr and abbw commands support page 2, but if you don't issue the magic
  register writes encapsulated in the abbpage2 command, the Iota chip itself
  disallows access to page 2.

* To perform a DEVOFF operation without cleaning up VRPCAUX first (to see the
  resulting erratic behaviour with your own eyes), do it manually as follows:

  abbw 0 30 1

flash-boot-test
===============

In addition to the repertoire of run-from-IRAM (loadable via fc-iram) programs
that form the main course of target-utils, we have a flashable program called
flash-boot-test - it will be called FBT for short in this article.  FBT is a
test case for the "main application" in flash, and it can be flashed in the
place of a regular firmware image for certain very low-level tests.  Because it
runs via the flash boot path and does not get loaded serially, FBT is quite
hardware-specific by necessity: it assumes a platform with 26 MHz Calypso clock
input and always uses the IrDA UART for communication (hard-coded).  FBT was
written with FCDEV3B and Openmoko GTA02 boards in mind; it won't work on a
D-Sample board because of the 13 MHz vs. 26 MHz clock difference.

FBT is built in two versions: fbt-mode0.bin and fbt-mode1.bin, differing in the
magic words at location 0x2000 which tell the Calypso boot ROM how the main
application in flash should be booted - please refer to the Flash-boot-modes
article in the freecalypso-docs repository.  Only the magic words differ between
fbt-mode0.bin and fbt-mode1.bin versions; the main body of the code is exactly
the same.  Once it receives control from the boot ROM in whichever mode it was
booted in, FBT's own code in main.c does the absolute minimum initialization to
allow serial communication (sets the VCLKOUT_DIV2 bit in the FFFF:FD02 register
and initializes the IrDA UART) and falls into the same interactive mode of
operation (listening for text-based commands) as our various run-from-IRAM
programs, allowing the operator to explore system state as closely out of boot
as possible.

When a main application in flash is booted in mode 1 (with the boot ROM moved
out of the way), the Calypso watchdog timer is running, and our FBT program
does not a perform a watchdog disable step on its own.  Therefore, if you flash
fbt-mode1.bin and boot it, you will see it keep endlessly rebooting about every
9 s.  To stop this endless reboot cycle, issue a wd (watchdog disable) command:
it is short enough to be easily typed in the available 9 s window.  The same
issue does not occur in flash boot mode 0, as the Calypso boot ROM does disable
the watchdog and leaves it disabled when booting mode 0 flash images or serially
downloaded code.

FBT also has a few other commands that have been added to facilitate further
experimentation with the watchdog timer feature of the Calypso chip - please
refer to the source code.