Remove since long deprecated ft2232 driver
[openocd.git] / src / jtag / interface.h
1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
4 * *
5 * Copyright (C) 2007,2008 √ėyvind Harboe *
6 * oyvind.harboe@zylin.com *
7 * *
8 * Copyright (C) 2009 Zachary T Welch *
9 * zw@superlucidity.net *
10 * *
11 * This program is free software; you can redistribute it and/or modify *
12 * it under the terms of the GNU General Public License as published by *
13 * the Free Software Foundation; either version 2 of the License, or *
14 * (at your option) any later version. *
15 * *
16 * This program is distributed in the hope that it will be useful, *
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
19 * GNU General Public License for more details. *
20 * *
21 * You should have received a copy of the GNU General Public License *
22 * along with this program. If not, see <http://www.gnu.org/licenses/>. *
23 ***************************************************************************/
24
25 #ifndef OPENOCD_JTAG_INTERFACE_H
26 #define OPENOCD_JTAG_INTERFACE_H
27
28 #include <jtag/jtag.h>
29 #include <target/armv7m_trace.h>
30
31 /* @file
32 * The "Cable Helper API" is what the cable drivers can use to help
33 * implement their "Cable API". So a Cable Helper API is a set of
34 * helper functions used by cable drivers, and this is different from a
35 * Cable API. A "Cable API" is what higher level code used to talk to a
36 * cable.
37 */
38
39
40 /** implementation of wrapper function tap_set_state() */
41 void tap_set_state_impl(tap_state_t new_state);
42
43 /**
44 * This function sets the state of a "state follower" which tracks the
45 * state of the TAPs connected to the cable. The state follower is
46 * hopefully always in the same state as the actual TAPs in the jtag
47 * chain, and will be so if there are no bugs in the tracking logic
48 * within that cable driver.
49 *
50 * All the cable drivers call this function to indicate the state they
51 * think the TAPs attached to their cables are in. Because this
52 * function can also log transitions, it will be helpful to call this
53 * function with every transition that the TAPs being manipulated are
54 * expected to traverse, not just end points of a multi-step state path.
55 *
56 * @param new_state The state we think the TAPs are currently in (or
57 * are about to enter).
58 */
59 #if defined(_DEBUG_JTAG_IO_)
60 #define tap_set_state(new_state) \
61 do { \
62 LOG_DEBUG("tap_set_state(%s)", tap_state_name(new_state)); \
63 tap_set_state_impl(new_state); \
64 } while (0)
65 #else
66 static inline void tap_set_state(tap_state_t new_state)
67 {
68 tap_set_state_impl(new_state);
69 }
70 #endif
71
72 /**
73 * This function gets the state of the "state follower" which tracks the
74 * state of the TAPs connected to the cable. @see tap_set_state @return
75 * tap_state_t The state the TAPs are in now.
76 */
77 tap_state_t tap_get_state(void);
78
79 /**
80 * This function sets the state of an "end state follower" which tracks
81 * the state that any cable driver thinks will be the end (resultant)
82 * state of the current TAP SIR or SDR operation.
83 *
84 * At completion of that TAP operation this value is copied into the
85 * state follower via tap_set_state().
86 *
87 * @param new_end_state The state the TAPs should enter at completion of
88 * a pending TAP operation.
89 */
90 void tap_set_end_state(tap_state_t new_end_state);
91
92 /**
93 * For more information, @see tap_set_end_state
94 * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
95 */
96 tap_state_t tap_get_end_state(void);
97
98 /**
99 * This function provides a "bit sequence" indicating what has to be
100 * done with TMS during a sequence of seven TAP clock cycles in order to
101 * get from state \a "from" to state \a "to".
102 *
103 * The length of the sequence must be determined with a parallel call to
104 * tap_get_tms_path_len().
105 *
106 * @param from The starting state.
107 * @param to The desired final state.
108 * @return int The required TMS bit sequence, with the first bit in the
109 * sequence at bit 0.
110 */
111 int tap_get_tms_path(tap_state_t from, tap_state_t to);
112
113 /**
114 * Function int tap_get_tms_path_len
115 * returns the total number of bits that represents a TMS path
116 * transition as given by the function tap_get_tms_path().
117 *
118 * For at least one interface (JLink) it's not OK to simply "pad" TMS
119 * sequences to fit a whole byte. (I suspect this is a general TAP
120 * problem within OOCD.) Padding TMS causes all manner of instability
121 * that's not easily discovered. Using this routine we can apply
122 * EXACTLY the state transitions required to make something work - no
123 * more - no less.
124 *
125 * @param from is the starting state
126 * @param to is the resultant or final state
127 * @return int - the total number of bits in a transition.
128 */
129 int tap_get_tms_path_len(tap_state_t from, tap_state_t to);
130
131
132 /**
133 * Function tap_move_ndx
134 * when given a stable state, returns an index from 0-5. The index corresponds to a
135 * sequence of stable states which are given in this order: <p>
136 * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
137 * <p>
138 * This sequence corresponds to look up tables which are used in some of the
139 * cable drivers.
140 * @param astate is the stable state to find in the sequence. If a non stable
141 * state is passed, this may cause the program to output an error message
142 * and terminate.
143 * @return int - the array (or sequence) index as described above
144 */
145 int tap_move_ndx(tap_state_t astate);
146
147 /**
148 * Function tap_is_state_stable
149 * returns true if the \a astate is stable.
150 */
151 bool tap_is_state_stable(tap_state_t astate);
152
153 /**
154 * Function tap_state_transition
155 * takes a current TAP state and returns the next state according to the tms value.
156 * @param current_state is the state of a TAP currently.
157 * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
158 * @return tap_state_t - the next state a TAP would enter.
159 */
160 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
161
162 /** Allow switching between old and new TMS tables. @see tap_get_tms_path */
163 void tap_use_new_tms_table(bool use_new);
164 /** @returns True if new TMS table is active; false otherwise. */
165 bool tap_uses_new_tms_table(void);
166
167 #ifdef _DEBUG_JTAG_IO_
168 /**
169 * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
170 * @param tms_buf must points to a buffer containing the TMS bitstream.
171 * @param tdi_buf must points to a buffer containing the TDI bitstream.
172 * @param tap_len must specify the length of the TMS/TDI bitstreams.
173 * @param start_tap_state must specify the current TAP state.
174 * @returns the final TAP state; pass as @a start_tap_state in following call.
175 */
176 tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
177 unsigned tap_len, tap_state_t start_tap_state);
178 #else
179 static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
180 const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
181 {
182 return start_tap_state;
183 }
184 #endif /* _DEBUG_JTAG_IO_ */
185
186 /**
187 * Represents a driver for a debugging interface.
188 *
189 * @todo Rename; perhaps "debug_driver". This isn't an interface,
190 * it's a driver! Also, not all drivers support JTAG.
191 *
192 * @todo We need a per-instance structure too, and changes to pass
193 * that structure to the driver. Instances can for example be in
194 * either SWD or JTAG modes. This will help remove globals, and
195 * eventually to cope with systems which have more than one such
196 * debugging interface.
197 */
198 struct jtag_interface {
199 /** The name of the JTAG interface driver. */
200 const char * const name;
201
202 /**
203 * Bit vector listing capabilities exposed by this driver.
204 */
205 unsigned supported;
206 #define DEBUG_CAP_TMS_SEQ (1 << 0)
207
208 /** transports supported in C code (NULL terminated vector) */
209 const char * const *transports;
210
211 const struct swd_driver *swd;
212
213 /**
214 * Execute queued commands.
215 * @returns ERROR_OK on success, or an error code on failure.
216 */
217 int (*execute_queue)(void);
218
219 /**
220 * Set the interface speed.
221 * @param speed The new interface speed setting.
222 * @returns ERROR_OK on success, or an error code on failure.
223 */
224 int (*speed)(int speed);
225
226 /**
227 * The interface driver may register additional commands to expose
228 * additional features not covered by the standard command set.
229 */
230 const struct command_registration *commands;
231
232 /**
233 * Interface driver must initialize any resources and connect to a
234 * JTAG device.
235 *
236 * quit() is invoked if and only if init() succeeds. quit() is always
237 * invoked if init() succeeds. Same as malloc() + free(). Always
238 * invoke free() if malloc() succeeds and do not invoke free()
239 * otherwise.
240 *
241 * @returns ERROR_OK on success, or an error code on failure.
242 */
243 int (*init)(void);
244
245 /**
246 * Interface driver must tear down all resources and disconnect from
247 * the JTAG device.
248 *
249 * @returns ERROR_OK on success, or an error code on failure.
250 */
251 int (*quit)(void);
252
253 /**
254 * Returns JTAG maxium speed for KHz. 0 = RTCK. The function returns
255 * a failure if it can't support the KHz/RTCK.
256 *
257 * WARNING!!!! if RTCK is *slow* then think carefully about
258 * whether you actually want to support this in the driver.
259 * Many target scripts are written to handle the absence of RTCK
260 * and use a fallback kHz TCK.
261 * @returns ERROR_OK on success, or an error code on failure.
262 */
263 int (*khz)(int khz, int *jtag_speed);
264
265 /**
266 * Calculate the clock frequency (in KHz) for the given @a speed.
267 * @param speed The desired interface speed setting.
268 * @param khz On return, contains the speed in KHz (0 for RTCK).
269 * @returns ERROR_OK on success, or an error code if the
270 * interface cannot support the specified speed (KHz or RTCK).
271 */
272 int (*speed_div)(int speed, int *khz);
273
274 /**
275 * Read and clear the power dropout flag. Note that a power dropout
276 * can be transitionary, easily much less than a ms.
277 *
278 * To find out if the power is *currently* on, one must invoke this
279 * method twice. Once to clear the power dropout flag and a second
280 * time to read the current state. The default implementation
281 * never reports power dropouts.
282 *
283 * @returns ERROR_OK on success, or an error code on failure.
284 */
285 int (*power_dropout)(int *power_dropout);
286
287 /**
288 * Read and clear the srst asserted detection flag.
289 *
290 * Like power_dropout this does *not* read the current
291 * state. SRST assertion is transitionary and may be much
292 * less than 1ms, so the interface driver must watch for these
293 * events until this routine is called.
294 *
295 * @param srst_asserted On return, indicates whether SRST has
296 * been asserted.
297 * @returns ERROR_OK on success, or an error code on failure.
298 */
299 int (*srst_asserted)(int *srst_asserted);
300
301 /**
302 * Configure trace parameters for the adapter
303 *
304 * @param enabled Whether to enable trace
305 * @param pin_protocol Configured pin protocol
306 * @param port_size Trace port width for sync mode
307 * @param trace_freq A pointer to the configured trace
308 * frequency; if it points to 0, the adapter driver must write
309 * its maximum supported rate there
310 * @returns ERROR_OK on success, an error code on failure.
311 */
312 int (*config_trace)(bool enabled, enum tpio_pin_protocol pin_protocol,
313 uint32_t port_size, unsigned int *trace_freq);
314
315 /**
316 * Poll for new trace data
317 *
318 * @param buf A pointer to buffer to store received data
319 * @param size A pointer to buffer size; must be filled with
320 * the actual amount of bytes written
321 *
322 * @returns ERROR_OK on success, an error code on failure.
323 */
324 int (*poll_trace)(uint8_t *buf, size_t *size);
325 };
326
327 extern const char * const jtag_only[];
328
329 void adapter_assert_reset(void);
330 void adapter_deassert_reset(void);
331 int adapter_config_trace(bool enabled, enum tpio_pin_protocol pin_protocol,
332 uint32_t port_size, unsigned int *trace_freq);
333 int adapter_poll_trace(uint8_t *buf, size_t *size);
334
335 #endif /* OPENOCD_JTAG_INTERFACE_H */