FreeCalypso > hg > freecalypso-docs

comparison Calypso-JTAG-notes @ 18:7ba5c951803c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Calypso-JTAG-notes article written
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 24 Jun 2019 20:01:53 +0000
parents
children
comparison
equal deleted inserted replaced
17:3d65bdaf00da 18:7ba5c951803c
1 This document describes the quirks of Calypso JTAG in an abstract, tool-
2 independent sense, and also covers the little bit of experience we've had with
3 TI's original official tools, but does not delve into OpenOCD specifics.
4 For OpenOCD-on-Calypso custom config and instructions, please refer to the
5 freecalyps-hwlab repository - but the present document should still be read
6 first.
7
8 Unconventional reset structure
9 ==============================
10
11 The first major way in which the JTAG interface on Calypso development boards
12 (or more generally, what is available in the Calypso+Iota chipset) differs from
13 "canonical" JTAG is that this chipset does NOT have reset signals that are
14 anything like classic TRST or SRST. Instead there is only one bundled-with-JTAG
15 reset signal (we call it XDS_RESET) which is turned into Iota nTESTRESET through
16 a transistor circuit - please refer to the Calypso-test-reset article. Aside
17 from its effects on the VRPC state machine described in that article, this test
18 reset can be thought of as a simultaneous combination of an equivalent of TRST
19 (all JTAG logic is hard-reset), an equivalent of SRST (the Calypso is fully
20 reset and proceeds with a cold boot) and more (all hardware is reset at a very
21 deep level), but comparisons to classic TRST and SRST aren't really appropriate
22 as the latter signals simply don't exist in our chipset.
23
24 However, despite its highly unconventional nature, this XDS_RESET signal
25 provided along with JTAG on TI's development boards performs a very important
26 function: this combination of JTAG and test reset allows a "reset and hold
27 still" maneuvre where all hardware is put into its pristine state with a very
28 deep reset, but the ARM7 CPU is halted before it gets a chance to execute any
29 instructions from the reset vector. This ability is not particularly important
30 on current Calypso hardware with a working and enabled boot ROM, but it was
31 vital on earlier platforms without this boot ROM: if the flash is blank or
32 contains a bad code image, or if RAM is mapped onto the boot chip select
33 instead of flash, allowing the ARM7 core to execute garbage out of reset is
34 bad, whereas having a "reset and hold still" ability allows guaranteed reliable
35 recovery and bootstrapping from a blank or bricked state. As explained later
36 in this article, this "reset and hold still" maneuvre is executed by first
37 giving the target a test reset pulse (which unstoppably blows away all prior hw
38 state), then immediately (the timing is critical) performing certain
39 manipulations via the JTAG scan chain - thus the bundling of the XDS_RESET
40 signal with JTAG is important.
41
42 EMU0 and EMU1 signals
43 =====================
44
45 In addition to the 4 standard JTAG signals TCK, TDI, TDO and TMS, the Calypso
46 provides two TI-proprietary signals called EMU0 and EMU1. (The test reset goes
47 to the Iota ABB, not to the Calypso.) These EMU0 and EMU1 signals are brought
48 out to the 14-pin JTAG connector on TI's D-Sample and E-Sample boards, and also
49 on our FCDEV3B.
50
51 The function of these two signals is completely unknown: all we know is that
52 they are listed as "bidirectional in/out" in the cal000.pdf document, and that
53 same-named signals also exist on TI's general-purpose DSP chips, both C54x and
54 the newer families, where they are also very poorly documented. We don't know
55 what these EMU0/1 signals do on the Calypso, and it is a particular unknown
56 whether they are specific to the DSP part or if the ARM7 part can also make use
57 of them somehow.
58
59 I (Mother Mychaela) previously thought that these signals might facilitate a
60 way to halt the ARM7 core without going through the scan chain, or a different
61 way to halt directly out of reset than the one we ultimately found, but a
62 recent experiment has shown that pulling either or both of these signals low
63 (they are pulled up on target boards) has absolutely no visible effect on ARM7
64 code execution, whether they are pulled low coming out of test reset or while
65 running. Thus until we recover more understanding of what is going on inside
66 the chip, we are going to ignore these two signals and leave them unconnected.
67
68 Iota not included in the JTAG scan chain
69 ========================================
70
71 In addition to the Calypso chip itself (the DBB), the Iota ABB chip also has
72 JTAG pins and could potentially be included in the scan chain. However, this
73 wiring arrangement is not typically used: both on TI's D-Sample board and on
74 our own FCDEV3B (based on Leonardo schematics) the JTAG interface is wired only
75 to the Calypso and not to Iota. The same arrangement has also been found in
76 all historical commercial phones and modems that provide a JTAG interface.
77
78 We don't have any plans to change this arrangement in any of our future designs:
79 in the absence of 100% complete understanding of the internals of both chips,
80 there is no telling what unexpected gotcha may occur if the Iota chip is
81 included in the same scan chain as the Calypso, hence we are not doing that.
82
83 ARM7 and C54x DSP cores
84 =======================
85
86 The regular JTAG scan chain inside the Calypso goes through two TAPs
87 corresponding to the two processor cores. The ARM7 TAP with a 4-bit IR is
88 closer to TDI, and the C54x DSP TAP with an 8-bit IR is closer to TDO. The
89 debug interface to the ARM7 core through its respective TAP is consistent with
90 public ARM7TDMI documentation from ARM except for one important quirk described
91 below, but we know absolutely nothing about the DSP TAP and its debug protocol
92 other than how to put it into BYPASS so we can operate on the ARM.
93
94 It appears from passing references in some TI documents that they did intend to
95 have an ability to debug the Calypso DSP via JTAG "emulation", and TI's CCS
96 software working through TI's XDS510 or XDS560 hardware (the same setup that
97 successfully connects to the ARM7 part of the Calypso) supports C54x targets.
98 However, we have no idea how any potential JTAG access to the DSP would interact
99 with its reset control coming from the ARM or with its power saving modes, and
100 it is very likely that there are some security mechanisms restricting debug
101 access to the DSP (perhaps needing some secret key to unlock it), thus being
102 able to debug the DSP via JTAG is not something we can realistically hope for
103 unless we either buy out the complete chip design from TI or physically
104 reverse-engineer the chip transistor by transistor, both options being equally
105 cost-prohibitive. At our current level of budgetary means, our ability to use
106 the JTAG interface on the Calypso is limited to the ARM7 part, not the DSP.
107
108 Non-standard extension to the ARM7TDMI TAP
109 ==========================================
110
111 We know that TI made at least one non-standard extension to the ARM7TDMI TAP in
112 the Calypso because it implements at least one additional opcode that does not
113 appear in any public documentation from ARM. When connecting to this ARM7
114 target, TI's CCS software working through XDS510 or XDS560 hardware apparently
115 scans a 0xB opcode (4'b1011) through the IR, and then apparently scans 2'b10
116 through the 2-bit DR selected by this opcode. (I said "apparently" because so
117 far the only people who have actually sniffed the JTAG communications produced
118 by the XDS+CCS combo were OsmocomBB people, not anyone from the FreeCalypso
119 team, hence we don't have any authentic knowledge currently.) Experiments with
120 OpenOCD show that the just-described sequence of IR and DR scans with an
121 unknown instruction and an unknown data register is necessary in order to allow
122 halting the ARM7 core: if we try to halt it in the standard ARM7TDMI way (either
123 via DBGRQ or via a catch-all breakpoint unit setup) without doing the magic
124 sequence first, no halt is effected.
125
126 Fortunately though, after we issue the non-understood magic sequence once, all
127 subsequent ARM7TDMI halt/resume manipulations done in the standard way appear
128 to work just fine, no more quirks. The only time when the "halt unlock" magic
129 sequence needs to be repeated is after a reset, which is expected.
130
131 Interaction with the watchdog timer
132 ===================================
133
134 The Calypso chip includes a watchdog timer feature; if this watchdog timer is
135 enabled and allowed to expire, it effects a fairly deep reset of the chip. The
136 Calypso boot ROM code and most firmware designs do a step early on to disable
137 this watchdog, and it is not subsequently re-enabled except to effect a reboot
138 when so desired, but as the ARM7 core first comes out of reset and starts
139 executing instructions from the reset vector (whether ROM or external memory),
140 the watchdog timer is enabled and ticking. This watchdog timer interacts with
141 JTAG as follows:
142
143 1) When the ARM7 core is halted via JTAG, the watchdog timer (if enabled) is
144 NOT stopped or paused, but keeps ticking.
145
146 2) If a watchdog reset occurs while the ARM7 core is halted, everything goes
147 out of whack, consistent with the note in standard ARM7TDMI documentation
148 which says that a reset must not be applied to the core while it is in debug
149 halt state.
150
151 Therefore, if the ARM7 core is to be halted at a time when the watchdog timer
152 is enabled and ticking, the halt operation must be quickly followed by two
153 system bus write operations (mwh command in OpenOCD) to the WATCHDOG_TIM_MODE
154 register, executing the watchdog disable sequence before the timer is allowed
155 to expire while halted.
156
157 JTAG clock speed
158 ================
159
160 It is often stated that the JTAG clock speed must be no greater than 1/6 of the
161 system clock speed when talking to ARM cores, and that JTAG access is blocked
162 when the core goes into a power saving mode with the clock stopped. Neither of
163 these constraints applies to our beloved Calypso though: the stated issues occur
164 in chip designs which internally synchronize JTAG signals including TCK to their
165 system clock, but Calypso and its predecessors don't do that, they use the hard
166 macrocell version of the ARM7TDMI core instead, use TCK directly to clock JTAG-
167 specific logic and perform "hard" clock switching for debug mode.
168
169 According to the available cal000_a.pdf document, the maximum TCK frequency
170 supported by the Calypso is 10 MHz, which also appears to be the only TCK
171 frequency which TI's older XDS510 "emulator" pods can produce without hardware
172 modifications. This 10 MHz TCK frequency can be used no matter what frequency
173 is fed to Calypso's main CLKTCXO clock input or what frequency the ARM7 core is
174 configured to run at, and JTAG keeps working even when the main clock is
175 completely stopped.
176
177 It is possible to halt the Calypso ARM7 core when it is in a sleep mode, even
178 in deep sleep: manipulation of internal scan chain 2 to set DBGRQ is a JTAG-only
179 operation, contained entirely in the TCK clock domain, thus it works even with
180 the main VCXO stopped, and the actual halt occurs on wakeup when the ARM7 core
181 regains its regular clock and sees the internal DBGRQ signal asserted.
182
183 Halting immediately out of reset
184 ================================
185
186 To me (Mother Mychaela) it always seemed evident that the Calypso and its
187 predecessors had to have some way to perform a "reset and hold still" maneuvre,
188 as this capability was absolutely essential for deterministic bootstrapping and
189 recovery of boards before the Calypso boot ROM subsumed that function. However,
190 the exact manipulations required to achieve this effect have remained elusive
191 for a long time until I found the answer in May-June of 2019. The trick is NOT
192 done through EMU0/1 pins like I once thought, and the method used on many other
193 chips involving classic TRST and SRST signals is clearly not applicable to the
194 Calypso given its very different reset structure.
195
196 The answer lies in the clocking architecture of TI GSM chipsets, involving a
197 VCXO that is started and stopped and a 32.768 kHz clock which is always running.
198 When the Calypso starts its boot process in response to the ON_nOFF signal
199 going from low to high (in the XDS-triggered test reset scenario this event
200 immediately follows the release of external reset), the main VCXO is off (i.e.,
201 it hasn't been started yet) and only the 32.768 kHz clock is running. At this
202 point the ARM7 core receives no clock at all (the 32.768 kHz clock is never fed
203 to the ARM7), and the ULPD block (the same block that handles deep sleep) goes
204 through the sequence of first enabling the main VCXO, then waiting for it to
205 stabilize. This sequence takes about 8192 cycles of the slow clock (about
206 250 ms), and only at the completion of this sequence the ARM7 core gets its
207 first clock. But during that 250 ms time window the JTAG logic is out of its
208 reset and functioning, and it can be operated because Calypso JTAG does not
209 depend on the main ARM clock which is stopped.
210
211 The following sequence of steps successfully achieves the effect of resetting
212 the Calypso+Iota chipset and all board-level peripherals that are subservient
213 to it, and halting the Calypso directly at the reset vector before the first
214 instruction is executed:
215
216 1) Give the chipset a test reset pulse via the XDS_RESET line; the exact
217 required duration is not known, but my OpenOCD-based proof of concept gives
218 a 50 ms pulse.
219
220 2) Immediately after releasing the reset or after a short delay (my PoC does a
221 10 ms delay), start exercising the JTAG scan chain, which has been fully
222 reset - it will be responsive at this point.
223
224 3) Perform the "magic" IR and DR scans to enable halting ability, just like we
225 do when we wish to halt an already-running Calypso.
226
227 4) Going through scan chain 2 inside the ARM7TDMI TAP, set the DBGRQ bit.
228 All steps up to this one must happen before Calypso ULPD enables the
229 VCXO-derived clock to the ARM7.
230
231 5) Also going through scan chain 2, poll and wait for DBGACK to get set,
232 indicating that the ARM7TDMI core halted - this event will happen when the
233 core gets its first clocks.
234
235 6) Once the ARM7TDMI core is halted, perform the two mwh operations to the
236 0xFFFFF804 register (WATCHDOG_TIM_MODE) to disable the watchdog, otherwise
237 it will generate another internal reset and mess up the system state.
238
239 We never found any built-in provision in TI's CCS (see below) or any script for
240 CCS that does the above, instead I (Mother Mychaela) found it on my own by
241 thinking about how it could possibly be done, and proved the idea working
242 with an OpenOCD setup presented in the freecalypso-hwlab repository.
243
244 Original official TI tools
245 ==========================
246
247 TI's original and official tool for operating on Calypso JTAG was their Code
248 Composer Studio (CCS) software, working through TI's XDS510 and XDS560
249 "emulator" hardware. The original hardware solution was the XDS510, and I mean
250 the original XDS510 which was an ISA card made by TI themselves, not any of the
251 later "XDS510-class" "emulators" made by companies acting as TI's 3rd-party
252 partners. The next successor to this original XDS510 was the original XDS560,
253 also made by TI themselves and distinct from the later "XDS560-class" devices
254 by TI's 3rd-party partner companies. The original XDS560 is a PCI card rather
255 than ISA, thus a little easier to get working in 2019, and also more readily
256 available on ebay. Both XDS510 and XDS560 consist of a desktop PC card (ISA or
257 PCI) and an active pod, and the pod has a non-detachable target connection cable
258 coming out of it, terminating in a female connector mating with the TI-style
259 14-pin JTAG header. The pod connector fits perfectly to TI's original D-Sample
260 board, but on our FCDEV3B it fails to fit because the JTAG and dual UART headers
261 are too close together. Therefore, anyone who is interested in connecting TI's
262 original XDS510 or XDS560 to an FCDEV3B would need to get some male-to-female
263 jumper wires or make a custom-crimped interposer cable.
264
265 The version of CCS which we found to work with these "emulator" adapters (both
266 XDS510 and XDS560) and with Calypso targets is this one:
267
268 ftp://ftp.freecalypso.org/pub/GSM/TI_tools/CCS/CCS_3.3.83.20_win32.zip
269
270 In order to get this CCS to work with a Calypso target, you will need to create
271 a "custom board" configuration in CCS setup - none of the predefined board
272 configs shipped with CCS will work. To create the needed "custom board" config,
273 select your "emulator" (XDS510 or XDS560), then add an ARM7 target and a
274 TMS320C5400 target in this order, which is the order from TDI to TDO. With this
275 custom config saved, running CCS brings up what they call the Parallel Debug
276 Manager, which supposedly supports coordinated debugging of both ARM and DSP
277 cores. However, I (Mother Mychaela) have not tried connecting to the DSP part,
278 only ARM7; another FreeCalypso community member who also got a working XDS510
279 setup talking to an FCDEV3B did try it, but saw what appears to be garbage. As
280 discussed earlier in this article, we are completely in the blind here, hence
281 this direction is not being seriously explored at the present.
282
283 In order to play with just the ARM7 core, leaving the DSP alone, select the
284 ARM7 target in the Open menu in Parallel Debug Manager - the main CCS debug
285 window will then open, and it will be specific to the ARM7 target. In my own
286 testing all further operations were done from the latter window and its menus.
287
288 Reset with TI's tools
289 ---------------------
290
291 Both XDS510 and XDS560 "emulators" have only one reset output; on TI's general-
292 purpose DSP development boards outside of the GSM Skunkworks division this one
293 reset line was TRST, whereas on D-Sample and Leonardo boards (and on our
294 FCDEV3B) this signal is repurposed to drive Iota nTESTRESET through a clever
295 transistor circuit. TI's general-purpose (non-GSM) DSP chips and boards have
296 internal pull-downs on TRST rather than pull-ups (JTAG logic permanently held
297 down in reset when no "emulator" is connected), hence both XDS510 and XDS560
298 pods drive this signal with an active push-pull driver - which is why Calypso
299 development boards include the special transistor circuit rather than connect
300 the XDS_RESET line (as we call it) directly to internal nTESTRESET.
301
302 Prior to initialization, a "cold" XDS560 pod has its reset output held low,
303 thus the target board will be held down in test reset and will appear completely
304 unresponsive. To initialize the XDS560 and release it from reset, select
305 "Emulator Reset" from the Debug menu. For this operation to succeed, the LDO
306 regulators in the Iota ABB need to be turned on, putting out 2.8 V on the V-IO
307 rail which is used as the target voltage reference by the XDS560 pod, so you
308 will probably need to press either the PWON button or the RESET button on the
309 FCDEV3B initially - and if the green LED stays off after that button press, you
310 know that the board is being held down in test reset by the XDS560 pod. Then
311 do the "Emulator Reset" operation, at which point the green LED will turn on
312 and the board will boot normally. From this point onward, doing a repeated
313 "Emulator Reset" operation causes a low-then-high pulse to be put out on the
314 XDS_RESET line, resetting the board and once again causing it to go through a
315 fresh boot.
316
317 Connecting to the ARM7 core and halting it
318 ------------------------------------------
319
320 Once the XDS560 has been initialized and the target board has been lifted out
321 of test reset with the "Emulator Reset" operation, you can execute the
322 "Connect target" operation, also in the Debug menu. This operation produces a
323 successful halt (I can only guess that this step is the point at which the
324 mysterious 0xB JTAG instruction and the unknown 2-bit register scan are issued,
325 unlocking the halting ability on this modified ARM7TDMI core), but the halt
326 happens at whichever point the ARM7 core happens to be in its code execution,
327 i.e., the generic, non-GSM-specific CCS has no knowledge of the peculiar timing
328 sequence that is required to achieve a halt directly out of reset on the
329 Calypso. It is my (Mychaela's) guess that CCS probably has some scripting
330 ability for more advanced users, and that TI's GSM Skunkworks division used
331 this custom scripting mechanism to do a sequence of {Emulator reset, then
332 connect to target and halt, then execute two register writes to disable the
333 watchdog} with machine rather human timing between the steps. Machine rather
334 than human timing is required in order to hit the 250 ms window between the
335 release of reset and the beginning of ARM core execution, and also to disable
336 the watchdog after the halt via two register writes before it goes off.
337
338 Using OpenOCD on Calypso targets
339 ================================
340
341 Building on top of the work that was done almost a decade earlier by some people
342 in the OsmocomBB camp (they sniffed the magic "halt unlock" sequence from an
343 XDS+CCS setup and gained the ability to halt an already-running Calypso with
344 OpenOCD, albeit without the reset magic) and adding the more in-depth
345 understanding provided by Mother Mychaela, we now have the ability to use
346 OpenOCD with a simple FT2232D adapter (instead of TI's XDS+CCS) to connect to
347 JTAG on TI/FC development boards, both D-Sample and FCDEV3B, gaining the power
348 of Free Software instead of proprietary tools. For the details, please refer
349 to the freecalypso-hwlab repository.