FreeCalypso > hg > freecalypso-tools

comparison doc/Target-utils @ 521:6604403aa212

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Target-utils: checking in unfinished document
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 06 Jun 2019 06:38:46 +0000
parents
children aa4f70e36cbd
comparison
equal deleted inserted replaced
520:bfddfecc52b2 521:6604403aa212
1 FreeCalypso target-utils suite
2 ==============================
3
4 We have a suite of standalone programs and specialized code pieces that run on
5 the Calypso ARM7 processor, but are not regular operational phone or modem
6 firmware; this suite of code bits is called target-utils, maintained and
7 distributed together with FreeCalypso host tools. The primary reason for the
8 coupling between FC host tools and target-utils is that the target-utils suite
9 provides the loadagent target program for fc-loadtool and fc-xram host tools,
10 as well as compalstage code pieces needed for operating on Compal phones.
11
12 Most programs in the target-utils suite are meant to execute out of RAM
13 (specifically, the Calypso chip's internal RAM or IRAM for short), loaded and
14 run via fc-iram or fc-compalram - they are not meant to be flashed. As of this
15 writing, the following run-from-RAM programs are available:
16
17 buzplayer Player for buzzer melodies, used by fc-buzplay
18 c139explore Mot C139 hardware exploration program
19 calversion Calypso version ID tool, primarily for the DSP ROM version
20 helloapp Hello-world program
21 loadagent Flash manipulation and XRAM loading agent
22 pirexplore Pirelli DP-L10 hardware exploration program
23 simtest Low-level exerciser for the SIM interface hardware
24
25 Aside from c139explore which is built as a binary to be loaded via fc-compalram
26 (Compal's bootloader protocol), all of the above programs are built as S-record
27 images to be loaded via fc-iram. Once loaded via the respective serial code
28 download protocol, each of the listed programs runs interactively, listening
29 for and executing commands given over the serial port. The specific set of
30 available commands is different for each program as relevant to its function,
31 but the command framework is common across the target-utils suite. The command
32 interface is text-based, such that each program can be driven manually by a
33 human operator once fc-iram or fc-compalram has dropped into the tty pass-thru
34 mode, but this same text-based command interface can also be driven by other
35 programs: fc-loadtool and fc-xram drive loadagent, and fc-buzplay drives
36 buzplayer.
37
38 Code architecture and execution environment
39 ===========================================
40
41 Our target-utils suite is built with the GNU toolchain (gcc+binutils), not TI's
42 proprietary TMS470 compiler. Because all of target-utils are meant to run out
43 of IRAM rather than flash or XRAM, we compile all code in ARM mode (not Thumb),
44 and we build without interworking support (no -mthumb-interwork): the ARMv4T
45 architecture implemented by the ARM7TDMI core in the Calypso does not support
46 penalty-free ARM/Thumb interworking, thus ARM-only code without interworking
47 support is the most efficient option for execution out of IRAM.
48
49 Selection of UART for communication
50 ===================================
51
52 All target-utils programs are interactive, listening for text commands given
53 over a serial port. But which UART? The Calypso chip has two UARTs, called
54 MODEM and IrDA in the chip docs - which of the two should be used for host
55 communication? The answer is a trick original to FreeCalypso: most of our
56 target-utils programs that are meant to be loaded via fc-iram expect to be
57 loaded specifically via the Calypso boot ROM and not in some other way, and
58 they look at some of the IRAM variables left behind by the boot ROM code. The
59 boot ROM listens on both UARTs for an interrupt-boot sequence, and once it
60 receives that sequence on one of the UARTs, it remembers which UART it was and
61 uses that same UART for the rest of the serial code download protocol. We read
62 that same variable set by the boot ROM, which depends on the boot ROM version.
63 To handle different Calypso boot ROM versions, we read the 16-bit word at 0x1FFE
64 (the last 16 bits of the boot ROM image) where TI put the boot ROM version
65 number, and we support boot ROM versions 0200 (Calypso C05 rev B silicon) and
66 0300 (Calypso C035 silicon). Most target-utils programs won't work (will fail
67 to select the UART for communication) if the boot ROM is some unsupported
68 version or missing altogether, or if the boot ROM is there, but didn't do the
69 loading.
70
71 The exceptions are as follows:
72
73 * c139explore always uses the MODEM UART as appropriate for Mot C139;
74
75 * flash-boot-test (a flashable program described later in this article) always
76 uses the IrDA UART;
77
78 * helloapp is built in 3 versions: helloapp-bootrom.srec, helloapp-irda.srec
79 and helloapp-modem.srec. The first version depends on the boot ROM like
80 other programs, the other two versions are built as fixed-IrDA or fixed-MODEM.
81
82 Other boot ROM and fc-iram dependencies
83 =======================================
84
85 There are two other ways in which target-utils programs that are meant to be
86 loaded via fc-iram depend on the Calypso boot ROM:
87
88 1) The Calypso gets its clock input from the RF section of the GSM device, and
89 the RF block can feed either 13 MHz or 26 MHz to the Calypso - some GSM RF
90 transceiver chips require 13 MHz (TI Clara), others require 26 MHz (TI Rita
91 and Silabs Aero II), yet others can work with either clock (Silabs Aero+),
92 and some use a 26 MHz crystal but have the option of feeding either 13 or
93 26 MHz to the Calypso (Aero II). The Calypso initially boots without knowing
94 what clock frequency it is running at, but then it needs to be told via a
95 register setting what the input clock frequency is, so that all peripherals
96 (both GSM-specific and general-purpose) always run at 13 MHz.
97
98 When the Calypso boot process is interrupted and diverted to serial code
99 download in the boot ROM, the boot ROM code autodetects whether the CLKTCXO
100 input runs at 13 MHz or 26 MHz (it tries both register bits settings until
101 the serial '<' characters sent by the host at 19200 baud are received
102 correctly), and if the CLKTCXO input is 26 MHz, the VCLKOUT_DIV2 bit is set
103 in the FFFF:FD02 register. Most of our target-utils programs have no hard-
104 coded knowledge of the 13 MHz vs. 26 MHz board hardware configuration and
105 rely on the Calypso boot ROM to set the division control bits in the
106 FFFF:FD02 register correctly for the autodetected clock.
107
108 2) The boot ROM allows the serial download host (fc-iram in our case) to
109 configure the Calypso DPLL, allowing the ARM7 core to run at its maximum
110 frequency of 52 MHz on Calypso C035 or 39 MHz on the older Calypso C05
111 silicon. None of our target-utils programs do their own DPLL setup, instead
112 they run with whatever they were booted with - therefore, in order for the
113 IRAM programs to run at their intended fastest speed, the correct -h option
114 needs to be given to fc-iram, selecting a hardware parameter file with the
115 right pll-config setting.
116
117 Delay loop timing
118 =================
119
120 There are a few places in target-utils where a delay of some specific duration
121 needs to be inserted. In most cases the requirement is for a certain minimum
122 delay, with more delay time being harmless except for inefficiency, but there
123 is one case (SPCA552E chip initialization in pirexplore) where the delay
124 requirement is strict: if the delays are too short or too long, the LCD doesn't
125 work. In target-utils all of these delays are implemented with CPU-cycle-count
126 delay loops that are calibrated at software design time; if the code runs out
127 of IRAM and the ARM7 core runs at 52 MHz, the delays will be exactly as
128 designed, otherwise they will be longer. In the case of pirexplore the strict
129 timing requirement is satisfied by loading and running the program via fc-iram
130 -h pirelli, resulting in the correct 52 MHz clock configuration; in all other
131 cases running at a frequency below 52 MHz or running out of flash (the
132 flash-boot-test special case) produces longer-than-needed delays.