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