1 /***************************************************************************
2 * Copyright (C) 2005 by Dominic Rath *
3 * Dominic.Rath@gmx.de *
5 * Copyright (C) 2007,2008 Øyvind Harboe *
6 * oyvind.harboe@zylin.com *
8 * Copyright (C) 2009 Zachary T Welch *
9 * zw@superlucidity.net *
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. *
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. *
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 ***************************************************************************/
25 #ifndef OPENOCD_JTAG_INTERFACE_H
26 #define OPENOCD_JTAG_INTERFACE_H
28 #include <jtag/jtag.h>
29 #include <jtag/swim.h>
30 #include <target/armv7m_trace.h>
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
41 /* FIXME: prototype to simplify transition of HLA drivers. To be removed */
42 struct hl_interface_s
;
44 /** implementation of wrapper function tap_set_state() */
45 void tap_set_state_impl(tap_state_t new_state
);
48 * This function sets the state of a "state follower" which tracks the
49 * state of the TAPs connected to the cable. The state follower is
50 * hopefully always in the same state as the actual TAPs in the jtag
51 * chain, and will be so if there are no bugs in the tracking logic
52 * within that cable driver.
54 * All the cable drivers call this function to indicate the state they
55 * think the TAPs attached to their cables are in. Because this
56 * function can also log transitions, it will be helpful to call this
57 * function with every transition that the TAPs being manipulated are
58 * expected to traverse, not just end points of a multi-step state path.
60 * @param new_state The state we think the TAPs are currently in (or
61 * are about to enter).
63 #define tap_set_state(new_state) \
65 LOG_DEBUG_IO("tap_set_state(%s)", tap_state_name(new_state)); \
66 tap_set_state_impl(new_state); \
70 * This function gets the state of the "state follower" which tracks the
71 * state of the TAPs connected to the cable. @see tap_set_state @return
72 * tap_state_t The state the TAPs are in now.
74 tap_state_t
tap_get_state(void);
77 * This function sets the state of an "end state follower" which tracks
78 * the state that any cable driver thinks will be the end (resultant)
79 * state of the current TAP SIR or SDR operation.
81 * At completion of that TAP operation this value is copied into the
82 * state follower via tap_set_state().
84 * @param new_end_state The state the TAPs should enter at completion of
85 * a pending TAP operation.
87 void tap_set_end_state(tap_state_t new_end_state
);
90 * For more information, @see tap_set_end_state
91 * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
93 tap_state_t
tap_get_end_state(void);
96 * This function provides a "bit sequence" indicating what has to be
97 * done with TMS during a sequence of seven TAP clock cycles in order to
98 * get from state \a "from" to state \a "to".
100 * The length of the sequence must be determined with a parallel call to
101 * tap_get_tms_path_len().
103 * @param from The starting state.
104 * @param to The desired final state.
105 * @return int The required TMS bit sequence, with the first bit in the
108 int tap_get_tms_path(tap_state_t from
, tap_state_t to
);
111 * Function int tap_get_tms_path_len
112 * returns the total number of bits that represents a TMS path
113 * transition as given by the function tap_get_tms_path().
115 * For at least one interface (JLink) it's not OK to simply "pad" TMS
116 * sequences to fit a whole byte. (I suspect this is a general TAP
117 * problem within OOCD.) Padding TMS causes all manner of instability
118 * that's not easily discovered. Using this routine we can apply
119 * EXACTLY the state transitions required to make something work - no
122 * @param from is the starting state
123 * @param to is the resultant or final state
124 * @return int - the total number of bits in a transition.
126 int tap_get_tms_path_len(tap_state_t from
, tap_state_t to
);
130 * Function tap_move_ndx
131 * when given a stable state, returns an index from 0-5. The index corresponds to a
132 * sequence of stable states which are given in this order: <p>
133 * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
135 * This sequence corresponds to look up tables which are used in some of the
137 * @param astate is the stable state to find in the sequence. If a non stable
138 * state is passed, this may cause the program to output an error message
140 * @return int - the array (or sequence) index as described above
142 int tap_move_ndx(tap_state_t astate
);
145 * Function tap_is_state_stable
146 * returns true if the \a astate is stable.
148 bool tap_is_state_stable(tap_state_t astate
);
151 * Function tap_state_transition
152 * takes a current TAP state and returns the next state according to the tms value.
153 * @param current_state is the state of a TAP currently.
154 * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
155 * @return tap_state_t - the next state a TAP would enter.
157 tap_state_t
tap_state_transition(tap_state_t current_state
, bool tms
);
159 /** Allow switching between old and new TMS tables. @see tap_get_tms_path */
160 void tap_use_new_tms_table(bool use_new
);
161 /** @returns True if new TMS table is active; false otherwise. */
162 bool tap_uses_new_tms_table(void);
166 * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
167 * @param tms_buf must points to a buffer containing the TMS bitstream.
168 * @param tdi_buf must points to a buffer containing the TDI bitstream.
169 * @param tap_len must specify the length of the TMS/TDI bitstreams.
170 * @param start_tap_state must specify the current TAP state.
171 * @returns the final TAP state; pass as @a start_tap_state in following call.
173 static inline tap_state_t
jtag_debug_state_machine(const void *tms_buf
,
174 const void *tdi_buf
, unsigned tap_len
, tap_state_t start_tap_state
)
176 /* Private declaration */
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
);
180 if (LOG_LEVEL_IS(LOG_LVL_DEBUG_IO
))
181 return jtag_debug_state_machine_(tms_buf
, tdi_buf
, tap_len
, start_tap_state
);
183 return start_tap_state
;
187 * Represents a driver for a debugging interface.
189 * @todo Rename; perhaps "debug_driver". This isn't an interface,
190 * it's a driver! Also, not all drivers support JTAG.
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.
198 struct jtag_interface
{
200 * Bit vector listing capabilities exposed by this driver.
203 #define DEBUG_CAP_TMS_SEQ (1 << 0)
206 * Execute queued commands.
207 * @returns ERROR_OK on success, or an error code on failure.
209 int (*execute_queue
)(void);
213 * Represents a driver for a debugging interface
215 * @todo We need a per-instance structure too, and changes to pass
216 * that structure to the driver. Instances can for example be in
217 * either SWD or JTAG modes. This will help remove globals, and
218 * eventually to cope with systems which have more than one such
219 * debugging interface.
221 struct adapter_driver
{
222 /** The name of the interface driver. */
223 const char * const name
;
225 /** transports supported in C code (NULL terminated vector) */
226 const char * const *transports
;
229 * The interface driver may register additional commands to expose
230 * additional features not covered by the standard command set.
232 const struct command_registration
*commands
;
235 * Interface driver must initialize any resources and connect to a
238 * quit() is invoked if and only if init() succeeds. quit() is always
239 * invoked if init() succeeds. Same as malloc() + free(). Always
240 * invoke free() if malloc() succeeds and do not invoke free()
243 * @returns ERROR_OK on success, or an error code on failure.
248 * Interface driver must tear down all resources and disconnect from
251 * @returns ERROR_OK on success, or an error code on failure.
256 * Control (assert/deassert) the signals SRST and TRST on the interface.
257 * This function is synchronous and should be called after the adapter
258 * queue has been properly flushed.
259 * This function is optional.
260 * Adapters that don't support resets can either not define this function
261 * or return an error code.
262 * Adapters that don't support one of the two reset should ignore the
263 * request to assert the missing signal and eventually log an error.
265 * @param srst 1 to assert SRST, 0 to deassert SRST.
266 * @param trst 1 to assert TRST, 0 to deassert TRST.
267 * @returns ERROR_OK on success, or an error code on failure.
269 int (*reset
)(int srst
, int trst
);
272 * Set the interface speed.
273 * @param speed The new interface speed setting.
274 * @returns ERROR_OK on success, or an error code on failure.
276 int (*speed
)(int speed
);
279 * Returns JTAG maxium speed for KHz. 0 = RTCK. The function returns
280 * a failure if it can't support the KHz/RTCK.
282 * WARNING!!!! if RTCK is *slow* then think carefully about
283 * whether you actually want to support this in the driver.
284 * Many target scripts are written to handle the absence of RTCK
285 * and use a fallback kHz TCK.
286 * @returns ERROR_OK on success, or an error code on failure.
288 int (*khz
)(int khz
, int *jtag_speed
);
291 * Calculate the clock frequency (in KHz) for the given @a speed.
292 * @param speed The desired interface speed setting.
293 * @param khz On return, contains the speed in KHz (0 for RTCK).
294 * @returns ERROR_OK on success, or an error code if the
295 * interface cannot support the specified speed (KHz or RTCK).
297 int (*speed_div
)(int speed
, int *khz
);
300 * Read and clear the power dropout flag. Note that a power dropout
301 * can be transitionary, easily much less than a ms.
303 * To find out if the power is *currently* on, one must invoke this
304 * method twice. Once to clear the power dropout flag and a second
305 * time to read the current state. The default implementation
306 * never reports power dropouts.
308 * @returns ERROR_OK on success, or an error code on failure.
310 int (*power_dropout
)(int *power_dropout
);
313 * Read and clear the srst asserted detection flag.
315 * Like power_dropout this does *not* read the current
316 * state. SRST assertion is transitionary and may be much
317 * less than 1ms, so the interface driver must watch for these
318 * events until this routine is called.
320 * @param srst_asserted On return, indicates whether SRST has
322 * @returns ERROR_OK on success, or an error code on failure.
324 int (*srst_asserted
)(int *srst_asserted
);
327 * Configure trace parameters for the adapter
329 * @param enabled Whether to enable trace
330 * @param pin_protocol Configured pin protocol
331 * @param port_size Trace port width for sync mode
332 * @param trace_freq A pointer to the configured trace
333 * frequency; if it points to 0, the adapter driver must write
334 * its maximum supported rate there
335 * @param traceclkin_freq TRACECLKIN frequency provided to the TPIU in Hz
336 * @param prescaler Pointer to the SWO prescaler calculated by the
338 * @returns ERROR_OK on success, an error code on failure.
340 int (*config_trace
)(bool enabled
, enum tpiu_pin_protocol pin_protocol
,
341 uint32_t port_size
, unsigned int *trace_freq
,
342 unsigned int traceclkin_freq
, uint16_t *prescaler
);
345 * Poll for new trace data
347 * @param buf A pointer to buffer to store received data
348 * @param size A pointer to buffer size; must be filled with
349 * the actual amount of bytes written
351 * @returns ERROR_OK on success, an error code on failure.
353 int (*poll_trace
)(uint8_t *buf
, size_t *size
);
355 /** Low-level JTAG APIs */
356 struct jtag_interface
*jtag_ops
;
358 /** Low-level SWD APIs */
359 const struct swd_driver
*swd_ops
;
361 /* DAP APIs over JTAG transport */
362 const struct dap_ops
*dap_jtag_ops
;
364 /* DAP APIs over SWD transport */
365 const struct dap_ops
*dap_swd_ops
;
368 const struct swim_driver
*swim_ops
;
370 /* FIXME: helper to simplify transition of HLA drivers. To be removed */
371 struct hl_interface_s
*hla_if
;
374 extern const char * const jtag_only
[];
376 int adapter_resets(int assert_trst
, int assert_srst
);
377 int adapter_assert_reset(void);
378 int adapter_deassert_reset(void);
379 int adapter_config_trace(bool enabled
, enum tpiu_pin_protocol pin_protocol
,
380 uint32_t port_size
, unsigned int *trace_freq
,
381 unsigned int traceclkin_freq
, uint16_t *prescaler
);
382 int adapter_poll_trace(uint8_t *buf
, size_t *size
);
384 #endif /* OPENOCD_JTAG_INTERFACE_H */
Linking to existing account procedure
If you already have an account and want to add another login method
you
MUST first sign in with your existing account and
then change URL to read
https://review.openocd.org/login/?link
to get to this page again but this time it'll work for linking. Thank you.
SSH host keys fingerprints
1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=.. |
|+o.. . |
|*.o . . |
|+B . . . |
|Bo. = o S |
|Oo.+ + = |
|oB=.* = . o |
| =+=.+ + E |
|. .=o . o |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)