# HG changeset patch # User Mychaela Falconia # Date 1559803126 0 # Node ID 6604403aa2127c9493dbbd307d97cb5bb7749832 # Parent bfddfecc52b2466ee43fb91e50709a5dd17d49fa doc/Target-utils: checking in unfinished document diff -r bfddfecc52b2 -r 6604403aa212 doc/Target-utils --- /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.