FreeCalypso > hg > freecalypso-hwlab

comparison doc/Calypso-OpenOCD-Howto @ 63:66879ce73b3e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Calypso-OpenOCD-Howto article written
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 26 Jun 2019 23:04:26 +0000
parents
children 6d02f30e35ad
comparison
equal deleted inserted replaced
62:240221552ecf 63:66879ce73b3e
1 Using OpenOCD to operate on Calypso JTAG: proof of concept
2 ==========================================================
3
4 We have a proof-of-concept OpenOCD configuration for talking to Calypso JTAG
5 based on the theoretical findings described in the Calypso-JTAG-notes document
6 in the freecalypso-docs repository; the present document describes how one can
7 practically use OpenOCD on an FCDEV3B target.
8
9 Choice of JTAG adapter hardware
10 ===============================
11
12 The PoC presented here uses an off-the-shelf unbuffered FT2232D breakout board
13 with a special EEPROM configuration as the JTAG adapter, as described in the
14 Unbuffered-FT2232x-JTAG article. ADBUS0 through ADBUS3 are wired to standard
15 JTAG signals as required by FTDI and ADBUS7 (acting as a GPIO) is wired to the
16 XDS_RESET line on JTAG connector pin 2. This choice of using a generic FT2232D
17 breakout board as opposed to a more purpose-made "professional" JTAG adapter
18 was made deliberately in order to force the user to make a mental shift
19 regarding reset signals: any standard JTAG adapter product will have two reset
20 outputs designated as TRST and SRST, but the XDS_RESET signal on the FCDEV3B
21 does not correspond to either of those. But a generic (non-JTAG-specific)
22 FT2232x breakout board does not have TRST or SRST, it only has ADBUS and ACBUS
23 pins that become GPIOs in MPSSE mode, allowing the user to break out of the
24 TRST and SRST mentality: you just have a bunch of GPIOs, then arbitrarily pick
25 one of those GPIOs and connect it to XDS_RESET, *without* associating it with
26 either TRST or SRST.
27
28 The full set of needed wire connections is thus:
29
30 FT2232D signal FCDEV3B JTAG signal
31 -----------------------------------
32 ADBUS0 TCK (pin 11)
33 ADBUS1 TDI (pin 3)
34 ADBUS2 TDO (pin 7)
35 ADBUS3 TMS (pin 1)
36 ADBUS7 XDS_RESET (pin 2)
37
38 You will also need to connect at least one ground pin, hence 6 wires in total.
39 There is no need to connect the undocumented and non-understood EMU0 and EMU1
40 signals - we don't know what to do with them and we work without them. This
41 wiring arrangement and all functionality described in this article work exactly
42 the same way on both D-Sample and FCDEV3B boards. You will also need to
43 reprogram the EEPROM on the FT2232D board as described in the
44 Unbuffered-FT2232x-JTAG article *before* you connect it to the Calypso target
45 board.
46
47 One can also connect just the 4 JTAG wires, without reset: there are some
48 historical commercial phones and modems on which JTAG lines are accessible, but
49 Iota nTESTRESET is not, or perhaps nTESTRESET is accessible, but you don't feel
50 like replicating the transistor circuit that is required in order to drive it
51 safely - the circuit that is present on development boards, but not on hacked-up
52 phones and modems. In that case you will still be able to halt an already-
53 running Calypso, but of course you won't be able to exercise reset_halt or
54 reset_run operations described below.
55
56 Unpowered FT2232D adapter quirk
57 ===============================
58
59 If you connect the FT2232D board to the FCDEV3B as described above, including
60 the XDS_RESET signal and ground, you will notice the following quirk: if the
61 custom-crimped JTAG cable is connected between the two boards, but the FT2232D
62 board is not plugged into a USB host (has no USB power), the FCDEV3B will be
63 held down in test reset: the green LED will be off, and neither button on the
64 board will do anything. The FCDEV3B will be released from this reset and will
65 boot in test reset mode with the green LED on the moment you plug the FT2232D
66 board into your USB host.
67
68 Running OpenOCD
69 ===============
70
71 With the FT2232D board plugged into your host PC or laptop and programmed with
72 the custom USB ID of 0403:7151, you can run OpenOCD with the custom config file
73 presented in the calypso-jtag directory in this repository:
74
75 openocd -f ft2232d-unbuf-poc.cfg
76
77 Being a proof of concept, this OpenOCD config file does not follow any of the
78 guidelines regarding separation between adapters and targets, but is fully
79 monolithic instead. This config is written to work with openocd-0.10.0
80 (depends on the new ftdi driver), but does NOT use the target/ti_calypso.cfg
81 fragment that has been included in mainline OpenOCD for quite some time: in the
82 Mother's opinion, the latter is bogus. If someone wishes to bring Calypso
83 support in the mainline OpenOCD distribution up to par, I do not have any
84 advice or guidance for you: it is your job, not mine. The present PoC config
85 that is rather antagonistic to mainline OpenOCD, its framework and its
86 guidelines will always remain our standard answer to FreeCalypso customers
87 asking how to make JTAG work.
88
89 When you run OpenOCD as above, the FCDEV3B target needs to be in the running
90 state with the green LED on. OpenOCD will exercise and verify the scan chain,
91 but it won't issue any resets or halts on its own, thus whatever code was
92 running on the board won't be disturbed in any way by the act of running
93 OpenOCD. You can then reset and/or halt the target as desired with our custom
94 commands (Tcl procedures) as described below.
95
96 Halting the Calypso without a reset
97 ===================================
98
99 To halt an already-running Calypso ARM7 core without a reset, stopping it at
100 whatever point it happens to be in its code execution, execute this sequence:
101
102 enable_halt; halt
103
104 The enable_halt step is a custom Tcl procedure added by us, issuing the
105 mysterious 0xB instruction and DR scan that are needed in order to enable halts
106 on TI's modified version of the ARM7TDMI core. Once you have halted as above,
107 you can resume and halt again without needing to re-execute the enable_halt
108 step; the only time when the enable_halt steps will need to be repeated is when
109 the Calypso is reset.
110
111 You can safely halt the Calypso in this manner when the flash is blank and the
112 boot ROM waits forever for a serial download, when you have loaded a RAM image
113 with fc-xram -j and the target is left in loadagent, or when one of our standard
114 firmwares is running; in all of these states the Calypso watchdog timer is
115 disabled. However, if you are going to halt the Calypso when the watchdog timer
116 is running, you will need to execute our wd (watchdog disable) command quickly
117 after the halt, before the watchdog timer is allowed to expire. A simple way
118 would be:
119
120 enable_halt; halt; wd
121
122 The wd command (Tcl procedure) name was deliberately made short so it can be
123 typed quickly with fingers if need be.
124
125 Resetting with or without a halt
126 ================================
127
128 We don't support OpenOCD's standard reset command because we found it too
129 difficult to override its built-in assumptions which are wrong for our Calypso.
130 Instead we have our own reset_halt and reset_run custom commands (Tcl
131 procedures) that replace OpenOCD's standard 'reset halt' and 'reset run',
132 respectively.
133
134 The reset_run command will reset the board without halting the Calypso, letting
135 it boot and run normally. It is equivalent to pressing the RESET button on the
136 board with your finger, except that it also re-initializes OpenOCD's scan scain
137 and "target examination" state which would otherwise get confused.
138
139 The reset_halt command will reset the board and halt the Calypso immediately as
140 it comes out of reset, halting at the reset vector before the first instruction
141 of the boot ROM code (or the first instruction from external memory if operating
142 on a D-Sample board with the boot switch set to external) is executed. The
143 necessary disabling of the watchdog timer (wd procedure call) is already built
144 into the reset_halt Tcl procedure; except for this wd step, all Calypso and Iota
145 registers will be in their most pristine reset state.
146
147 Recovering bricked Compal phones
148 ================================
149
150 Some Mot C1xx phones have Calypso JTAG signals brought out to accessible contact
151 pads, allowing a way to recover from a bricked flash bootloader via JTAG.
152 However, they do not bring out Iota nTESTRESET, instead they bring out a signal
153 which they call DLPWR, which is really Iota RPWON. A procedure similar to our
154 reset_halt would need to be performed as the first step in the recovery
155 sequence, but it would need to be modified to work with DLPWR instead of
156 XDS_RESET. The RPWON aka DLPWR signal will need to be driven with an OC/OD
157 driver (it is internally pulled up to raw VBAT, which is not a safe voltage for
158 standard 3.3V logic), and the switch-on and boot sequence will be triggered
159 when this signal is pulled low, i.e., transitions from high to low. The
160 subsequent release transition (from low back to pull-up high) does not matter,
161 i.e., RPWON may be permanently pulled down as the Calypso boots and runs, very
162 much unlike nTESTRESET or XDS_RESET.
163
164 It will be up to you to design whatever circuit you wish to use to produce an
165 OC/OD driver that can be triggered from OpenOCD, but connecting RPWON aka DLPWR
166 directly to an FT2232x I/O pin is not acceptable. Copying the circuit from
167 TI/FC development boards that propagates XDS_RESET into nTESTRESET won't work:
168 this circuit only works when the V-IO regulator is already on, but RPWON is not
169 a reset and will need to be triggered when the chipset is fully "cold".
170
171 You will also need to figure out the appropriate timing. You will need to
172 insert a certain delay between RPWON assertion and the 'jtag arp_init' step in
173 our reset_halt procedure: the VRPC state machine in the Iota chip will do a
174 bunch of work between sensing a low on RPWON and releasing the Calypso from
175 reset via ON_nOFF, and until then the JTAG scan chain won't work. But the
176 delay cannot be too long either, or you won't halt the Calypso before it starts
177 executing bogus code from the phone's bricked flash.
178
179 Once you do get a working reset_halt variant, the following steps will be
180 straightforward:
181
182 1) Run fc-loadtool -h compal -c none /dev/ttyXXX on the serial port connected
183 to the phone's headset jack;
184
185 2) Enable the boot ROM and jump to it with these commands:
186
187 mwh 0xFFFFFB10 0x100
188 resume 0
189
190 The boot ROM will run while fc-loadtool is sending its beacons, fc-loadtool
191 will load and run loadagent, and you can then recover the flash.