FreeCalypso > hg > freecalypso-tools

annotate doc/Target-utils @ 1011:6d9b10633f10 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
etmsync Pirelli IMEI retrieval: fix poor use of printf() Bug reported by Vadim Yanitskiy <fixeria@osmocom.org>: the construct where a static-allocated string was passed to printf() without any format arguments causes newer compilers to report a security problem. Given that formatted output is not needed here, just fixed string output, change printf() to fputs(), and direct the error message to stderr while at it.
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 23 May 2024 17:29:57 +0000
parents ae237e4e8d9b
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
521
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 FreeCalypso target-utils suite
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 ==============================
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 We have a suite of standalone programs and specialized code pieces that run on
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 the Calypso ARM7 processor, but are not regular operational phone or modem
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 firmware; this suite of code bits is called target-utils, maintained and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 distributed together with FreeCalypso host tools. The primary reason for the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 coupling between FC host tools and target-utils is that the target-utils suite
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 provides the loadagent target program for fc-loadtool and fc-xram host tools,
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 as well as compalstage code pieces needed for operating on Compal phones.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 Most programs in the target-utils suite are meant to execute out of RAM
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 (specifically, the Calypso chip's internal RAM or IRAM for short), loaded and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 run via fc-iram or fc-compalram - they are not meant to be flashed. As of this
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 writing, the following run-from-RAM programs are available:
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 buzplayer Player for buzzer melodies, used by fc-buzplay
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 c139explore Mot C139 hardware exploration program
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 calversion Calypso version ID tool, primarily for the DSP ROM version
550
bdaa4e7c9c05 doc/Target-utils: dspdump documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 532
diff changeset
20 dspdump Calypso DSP ROM dump tool
521
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 helloapp Hello-world program
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 loadagent Flash manipulation and XRAM loading agent
741
72feb9763de4 lunadrv documentation updates for upcoming release
Mychaela Falconia <falcon@freecalypso.org>
parents: 703
diff changeset
23 lunadrv Driver for FreeCalypso Luna LCD
521
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 pirexplore Pirelli DP-L10 hardware exploration program
787
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
25 simagent SIM interface agent to be used by fc-simint and fc-simtool
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
26 simtest Previous low-level exerciser for the SIM interface hardware
521
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 Aside from c139explore which is built as a binary to be loaded via fc-compalram
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 (Compal's bootloader protocol), all of the above programs are built as S-record
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 images to be loaded via fc-iram. Once loaded via the respective serial code
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 download protocol, each of the listed programs runs interactively, listening
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 for and executing commands given over the serial port. The specific set of
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 available commands is different for each program as relevant to its function,
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 but the command framework is common across the target-utils suite. The command
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 interface is text-based, such that each program can be driven manually by a
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 human operator once fc-iram or fc-compalram has dropped into the tty pass-thru
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 mode, but this same text-based command interface can also be driven by other
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 programs: fc-loadtool and fc-xram drive loadagent, and fc-buzplay drives
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 buzplayer.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 Code architecture and execution environment
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 ===========================================
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 Our target-utils suite is built with the GNU toolchain (gcc+binutils), not TI's
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 proprietary TMS470 compiler. Because all of target-utils are meant to run out
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 of IRAM rather than flash or XRAM, we compile all code in ARM mode (not Thumb),
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 and we build without interworking support (no -mthumb-interwork): the ARMv4T
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 architecture implemented by the ARM7TDMI core in the Calypso does not support
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 penalty-free ARM/Thumb interworking, thus ARM-only code without interworking
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 support is the most efficient option for execution out of IRAM.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 Selection of UART for communication
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 ===================================
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 All target-utils programs are interactive, listening for text commands given
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 over a serial port. But which UART? The Calypso chip has two UARTs, called
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 MODEM and IrDA in the chip docs - which of the two should be used for host
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58 communication? The answer is a trick original to FreeCalypso: most of our
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 target-utils programs that are meant to be loaded via fc-iram expect to be
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 loaded specifically via the Calypso boot ROM and not in some other way, and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 they look at some of the IRAM variables left behind by the boot ROM code. The
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62 boot ROM listens on both UARTs for an interrupt-boot sequence, and once it
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 receives that sequence on one of the UARTs, it remembers which UART it was and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 uses that same UART for the rest of the serial code download protocol. We read
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 that same variable set by the boot ROM, which depends on the boot ROM version.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 To handle different Calypso boot ROM versions, we read the 16-bit word at 0x1FFE
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 (the last 16 bits of the boot ROM image) where TI put the boot ROM version
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68 number, and we support boot ROM versions 0200 (Calypso C05 rev B silicon) and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 0300 (Calypso C035 silicon). Most target-utils programs won't work (will fail
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 to select the UART for communication) if the boot ROM is some unsupported
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 version or missing altogether, or if the boot ROM is there, but didn't do the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 loading.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 The exceptions are as follows:
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 * c139explore always uses the MODEM UART as appropriate for Mot C139;
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 * flash-boot-test (a flashable program described later in this article) always
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 uses the IrDA UART;
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 * helloapp is built in 3 versions: helloapp-bootrom.srec, helloapp-irda.srec
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 and helloapp-modem.srec. The first version depends on the boot ROM like
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 other programs, the other two versions are built as fixed-IrDA or fixed-MODEM.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 Other boot ROM and fc-iram dependencies
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 =======================================
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 There are two other ways in which target-utils programs that are meant to be
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 loaded via fc-iram depend on the Calypso boot ROM:
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 1) The Calypso gets its clock input from the RF section of the GSM device, and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 the RF block can feed either 13 MHz or 26 MHz to the Calypso - some GSM RF
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 transceiver chips require 13 MHz (TI Clara), others require 26 MHz (TI Rita
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 and Silabs Aero II), yet others can work with either clock (Silabs Aero+),
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 and some use a 26 MHz crystal but have the option of feeding either 13 or
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 26 MHz to the Calypso (Aero II). The Calypso initially boots without knowing
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97 what clock frequency it is running at, but then it needs to be told via a
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 register setting what the input clock frequency is, so that all peripherals
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 (both GSM-specific and general-purpose) always run at 13 MHz.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
100
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 When the Calypso boot process is interrupted and diverted to serial code
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 download in the boot ROM, the boot ROM code autodetects whether the CLKTCXO
527
aa4f70e36cbd doc/Target-utils: typo fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 521
diff changeset
103 input runs at 13 MHz or 26 MHz (it tries both register bit settings until
521
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 the serial '<' characters sent by the host at 19200 baud are received
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105 correctly), and if the CLKTCXO input is 26 MHz, the VCLKOUT_DIV2 bit is set
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 in the FFFF:FD02 register. Most of our target-utils programs have no hard-
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 coded knowledge of the 13 MHz vs. 26 MHz board hardware configuration and
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108 rely on the Calypso boot ROM to set the division control bits in the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 FFFF:FD02 register correctly for the autodetected clock.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 2) The boot ROM allows the serial download host (fc-iram in our case) to
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 configure the Calypso DPLL, allowing the ARM7 core to run at its maximum
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 frequency of 52 MHz on Calypso C035 or 39 MHz on the older Calypso C05
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 silicon. None of our target-utils programs do their own DPLL setup, instead
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115 they run with whatever they were booted with - therefore, in order for the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 IRAM programs to run at their intended fastest speed, the correct -h option
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 needs to be given to fc-iram, selecting a hardware parameter file with the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118 right pll-config setting.
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 Delay loop timing
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
121 =================
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
123 There are a few places in target-utils where a delay of some specific duration
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124 needs to be inserted. In most cases the requirement is for a certain minimum
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 delay, with more delay time being harmless except for inefficiency, but there
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 is one case (SPCA552E chip initialization in pirexplore) where the delay
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 requirement is strict: if the delays are too short or too long, the LCD doesn't
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 work. In target-utils all of these delays are implemented with CPU-cycle-count
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 delay loops that are calibrated at software design time; if the code runs out
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 of IRAM and the ARM7 core runs at 52 MHz, the delays will be exactly as
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 designed, otherwise they will be longer. In the case of pirexplore the strict
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 timing requirement is satisfied by loading and running the program via fc-iram
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133 -h pirelli, resulting in the correct 52 MHz clock configuration; in all other
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 cases running at a frequency below 52 MHz or running out of flash (the
6604403aa212 doc/Target-utils: checking in unfinished document
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135 flash-boot-test special case) produces longer-than-needed delays.
528
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
136
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
137 Common interactive commands
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
138 ===========================
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
139
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
140 The exact set of implemented commands is different for each target-utils
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
141 program, including commands specific to each program's unique function, but the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
142 following basic commands are included in most programs:
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
143
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
144 abbinit Initialize ABB communication
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
145 abbpage2 Unlock access to ABB register page 2
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
146 abbr pg reg Read ABB register <reg> on page <pg>
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
147 abbw pg reg val Write <val> into register <reg> on page <pg>
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
148 dump hex-start hex-len Display a human-oriented memory dump in hex and ASCII
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
149 jump addr Jump to given address with BX
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
150 poweroff Execute Iota ABB soft poweroff (DEVOFF)
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
151 r8 addr Read an 8-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
152 r16 addr Read a 16-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
153 r32 addr Read a 32-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
154 w8 addr data Write an 8-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
155 w16 addr data Write a 16-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
156 w32 addr data Write a 32-bit register or memory location
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
157
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
158 For further details, please refer to the source code - if you are playing with
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
159 such low-level components, you need to put on the hat of a developer rather
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
160 than a mere user.
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
161
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
162 ABB support in target-utils
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
163 ===========================
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
164
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
165 Our target-utils suite includes code for initializing and executing SPI
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
166 communication with the Iota ABB device (TWL3014 or TWL3025), Calypso's analog
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
167 and power management companion chip. Only Iota ABB type is supported, not
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
168 Omega/Nausica or Syren. The primary reason for having this infrastructure is
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
169 to be able to perform a soft poweroff operation, i.e., to return the Calypso
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
170 phone or modem to its switched-off state after flashing or various standalone
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
171 debug operations, but once implemented, this same ABB SPI communication
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
172 infrastructure is also used in model-specific hardware exploration utilities
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
173 for functions like keypad backlight and vibrator control which are implemented
787
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
174 via the ABB on some models, and it is used in simagent and simtest to control
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
175 the part of the SIM interface that resides in the Iota ABB.
528
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
176
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
177 Aside from specialized programs like c139explore that are specific to target
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
178 devices known to use the Iota ABB, most target-utils programs do not execute
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
179 any ABB or SPI communication code (not even initialization) until they receive
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
180 one of the ABB commands: abbinit, abbr, abbw or poweroff. This way if someone
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
181 comes across a Calypso device that has a different ABB type or needs to debug a
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
182 board with broken ABB communication, one can explore other functions without
787
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
183 touching ABB commands. (simagent and simtest constitute another exception:
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
184 even though these programs aren't specific to one particular target device like
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
185 c139explore, their main function of exercising the SIM interface depends on the
ae237e4e8d9b doc/Target-utils: simagent addition documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 741
diff changeset
186 Iota ABB, thus they are restricted to Calypso+Iota targets.)
528
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
187
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
188 The abb_init() function invoked by the abbinit command may be invoked multiple
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
189 times: it maintains an internal flag remembering if the initialization steps
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
190 have already been done or not, and repeated invokations do nothing. User-
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
191 friendly abbr, abbw and poweroff commands invoke abb_init() internally, but the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
192 special abbpage2 command does not - if you are interested in exploring the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
193 undocumented register page 2, you need to execute abbinit manually first, then
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
194 abbpage2, then explore with abbr and abbw.
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
195
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
196 poweroff operation details: VRPCAUX and VRPCDEV
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
197 ===============================================
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
198
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
199 The abb_power_off() function invoked by the poweroff command performs the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
200 following sequence of steps:
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
201
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
202 * Calls abb_init() to establish ABB communication in the case that it hasn't
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
203 already been done;
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
204
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
205 * Executes the magic writes to TAPCTRL and TAPREG registers that unlock access
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
206 to register page 2 - this step is factored out into the abb_unlock_page2()
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
207 function which is also accessible as the abbpage2 command;
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
208
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
209 * Writes 0x007 into the undocumented VRPCAUX register to clear the erratic
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
210 state that will be there if we got booted via nTESTRESET rather than PWON;
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
211
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
212 * Flushes all UART output, i.e., waits for it to finish going out on the wire;
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
213
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
214 * Writes 0x001 into the VRPCDEV register, which is the actual DEVOFF command.
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
215
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
216 The step of writing into VRPCAUX and its prerequisite page 2 unlock steps are a
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
217 recent addition as of fc-host-tools-r11; these steps have been added to fix the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
218 erratic behaviour that was occurring on TI/FC development boards (D-Sample and
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
219 FCDEV3B) when fc-loadtool (or fc-iram with some specialized target-utils
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
220 program) was entered via the RESET button rather than PWON, followed by the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
221 soft poweroff operation and another switch-on via PWON. For more details,
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
222 please refer to the Calypso-test-reset article in the freecalypso-docs
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
223 repository.
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
224
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
225 If you are interested in doing some experiments of your own with this
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
226 undocumented quirk of the Calypso+Iota chipset and the odd behaviour it can
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
227 cause, you can do the following:
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
228
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
229 * To see the content of the undocumented VRPCAUX register resulting from
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
230 different boot modes, execute these commands:
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
231
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
232 abbinit
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
233 abbpage2
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
234 abbr 2 30
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
235
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
236 Our abbr and abbw commands support page 2, but if you don't issue the magic
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
237 register writes encapsulated in the abbpage2 command, the Iota chip itself
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
238 disallows access to page 2.
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
239
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
240 * To perform a DEVOFF operation without cleaning up VRPCAUX first (to see the
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
241 resulting erratic behaviour with your own eyes), do it manually as follows:
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
242
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
243 abbw 0 30 1
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
244
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
245 flash-boot-test
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
246 ===============
81a3fc069301 doc/Target-utils: ABB support documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 527
diff changeset
247
529
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
248 In addition to the repertoire of run-from-IRAM (loadable via fc-iram) programs
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
249 that form the main course of target-utils, we have a flashable program called
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
250 flash-boot-test - it will be called FBT for short in this article. FBT is a
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
251 test case for the "main application" in flash, and it can be flashed in the
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
252 place of a regular firmware image for certain very low-level tests. Because it
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
253 runs via the flash boot path and does not get loaded serially, FBT is quite
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
254 hardware-specific by necessity: it assumes a platform with 26 MHz Calypso clock
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
255 input and always uses the IrDA UART for communication (hard-coded). FBT was
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
256 written with FCDEV3B and Openmoko GTA02 boards in mind; it won't work on a
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
257 D-Sample board because of the 13 MHz vs. 26 MHz clock difference.
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
258
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
259 FBT is built in two versions: fbt-mode0.bin and fbt-mode1.bin, differing in the
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
260 magic words at location 0x2000 which tell the Calypso boot ROM how the main
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
261 application in flash should be booted - please refer to the Flash-boot-modes
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
262 article in the freecalypso-docs repository. Only the magic words differ between
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
263 fbt-mode0.bin and fbt-mode1.bin versions; the main body of the code is exactly
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
264 the same. Once it receives control from the boot ROM in whichever mode it was
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
265 booted in, FBT's own code in main.c does the absolute minimum initialization to
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
266 allow serial communication (sets the VCLKOUT_DIV2 bit in the FFFF:FD02 register
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
267 and initializes the IrDA UART) and falls into the same interactive mode of
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
268 operation (listening for text-based commands) as our various run-from-IRAM
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
269 programs, allowing the operator to explore system state as closely out of boot
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
270 as possible.
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
271
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
272 When a main application in flash is booted in mode 1 (with the boot ROM moved
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
273 out of the way), the Calypso watchdog timer is running, and our FBT program
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
274 does not a perform a watchdog disable step on its own. Therefore, if you flash
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
275 fbt-mode1.bin and boot it, you will see it keep endlessly rebooting about every
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
276 9 s. To stop this endless reboot cycle, issue a wd (watchdog disable) command:
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
277 it is short enough to be easily typed in the available 9 s window. The same
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
278 issue does not occur in flash boot mode 0, as the Calypso boot ROM does disable
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
279 the watchdog and leaves it disabled when booting mode 0 flash images or serially
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
280 downloaded code.
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
281
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
282 FBT also has a few other commands that have been added to facilitate further
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
283 experimentation with the watchdog timer feature of the Calypso chip - please
30bec872824a doc/Target-utils: flash-boot-test documented
Mychaela Falconia <falcon@freecalypso.org>
parents: 528
diff changeset
284 refer to the source code.