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, write to the *
23 * Free Software Foundation, Inc., *
24 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
25 ***************************************************************************/
26 #ifndef OPENOCD_JTAG_INTERFACE_H
27 #define OPENOCD_JTAG_INTERFACE_H
30 * The "Cable Helper API" is what the cable drivers can use to help
31 * implement their "Cable API". So a Cable Helper API is a set of
32 * helper functions used by cable drivers, and this is different from a
33 * Cable API. A "Cable API" is what higher level code used to talk to a
38 /** implementation of wrapper function tap_set_state() */
39 void tap_set_state_impl(tap_state_t new_state);
42 * This function sets the state of a "state follower" which tracks the
43 * state of the TAPs connected to the cable. The state follower is
44 * hopefully always in the same state as the actual TAPs in the jtag
45 * chain, and will be so if there are no bugs in the tracking logic
46 * within that cable driver.
48 * All the cable drivers call this function to indicate the state they
49 * think the TAPs attached to their cables are in. Because this
50 * function can also log transitions, it will be helpful to call this
51 * function with every transition that the TAPs being manipulated are
52 * expected to traverse, not just end points of a multi-step state path.
54 * @param new_state The state we think the TAPs are currently in (or
55 * are about to enter).
57 #if defined(_DEBUG_JTAG_IO_)
58 #define tap_set_state(new_state) \
60 LOG_DEBUG( "tap_set_state(%s)", tap_state_name(new_state) ); \
61 tap_set_state_impl(new_state); \
64 static inline void tap_set_state(tap_state_t new_state)
66 tap_set_state_impl(new_state);
71 * This function gets the state of the "state follower" which tracks the
72 * state of the TAPs connected to the cable. @see tap_set_state @return
73 * tap_state_t The state the TAPs are in now.
75 tap_state_t tap_get_state(void);
78 * This function sets the state of an "end state follower" which tracks
79 * the state that any cable driver thinks will be the end (resultant)
80 * state of the current TAP SIR or SDR operation.
82 * At completion of that TAP operation this value is copied into the
83 * state follower via tap_set_state().
85 * @param new_end_state The state the TAPs should enter at completion of
86 * a pending TAP operation.
88 void tap_set_end_state(tap_state_t new_end_state);
91 * For more information, @see tap_set_end_state
92 * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
94 tap_state_t tap_get_end_state(void);
97 * This function provides a "bit sequence" indicating what has to be
98 * done with TMS during a sequence of seven TAP clock cycles in order to
99 * get from state \a "from" to state \a "to".
101 * The length of the sequence must be determined with a parallel call to
102 * tap_get_tms_path_len().
104 * @param from The starting state.
105 * @param to The desired final state.
106 * @return int The required TMS bit sequence, with the first bit in the
109 int tap_get_tms_path(tap_state_t from, tap_state_t to);
113 * Function int tap_get_tms_path_len
114 * returns the total number of bits that represents a TMS path
115 * transition as given by the function tap_get_tms_path().
117 * For at least one interface (JLink) it's not OK to simply "pad" TMS
118 * sequences to fit a whole byte. (I suspect this is a general TAP
119 * problem within OOCD.) Padding TMS causes all manner of instability
120 * that's not easily discovered. Using this routine we can apply
121 * EXACTLY the state transitions required to make something work - no
124 * @param from is the starting state
125 * @param to is the resultant or final state
126 * @return int - the total number of bits in a transition.
128 int tap_get_tms_path_len(tap_state_t from, tap_state_t to);
132 * Function tap_move_ndx
133 * when given a stable state, returns an index from 0-5. The index corresponds to a
134 * sequence of stable states which are given in this order: <p>
135 * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
137 * This sequence corresponds to look up tables which are used in some of the
139 * @param astate is the stable state to find in the sequence. If a non stable
140 * state is passed, this may cause the program to output an error message
142 * @return int - the array (or sequence) index as described above
144 int tap_move_ndx(tap_state_t astate);
147 * Function tap_is_state_stable
148 * returns true if the \a astate is stable.
150 bool tap_is_state_stable(tap_state_t astate);
153 * Function tap_state_transition
154 * takes a current TAP state and returns the next state according to the tms value.
155 * @param current_state is the state of a TAP currently.
156 * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
157 * @return tap_state_t - the next state a TAP would enter.
159 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
162 * Function tap_state_name
163 * Returns a string suitable for display representing the JTAG tap_state
165 const char* tap_state_name(tap_state_t state);
167 /// Provides user-friendly name lookup of TAP states.
168 tap_state_t tap_state_by_name(const char *name);
170 /// Allow switching between old and new TMS tables. @see tap_get_tms_path
171 void tap_use_new_tms_table(bool use_new);
173 #ifdef _DEBUG_JTAG_IO_
175 * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
176 * @param tms_buf must points to a buffer containing the TMS bitstream.
177 * @param tdi_buf must points to a buffer containing the TDI bitstream.
178 * @param tap_len must specify the length of the TMS/TDI bitstreams.
179 * @param start_tap_state must specify the current TAP state.
180 * @returns the final TAP state; pass as @a start_tap_state in following call.
182 tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
183 unsigned tap_len, tap_state_t start_tap_state);
185 static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
186 const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
188 return start_tap_state;
190 #endif // _DEBUG_JTAG_IO_
192 typedef struct jtag_interface_s
196 /* queued command execution
198 int (*execute_queue)(void);
200 /* interface initalization
202 int (*speed)(int speed);
203 int (*register_commands)(struct command_context_s* cmd_ctx);
207 /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
208 * a failure if it can't support the KHz/RTCK.
210 * WARNING!!!! if RTCK is *slow* then think carefully about
211 * whether you actually want to support this in the driver.
212 * Many target scripts are written to handle the absence of RTCK
213 * and use a fallback kHz TCK.
215 int (*khz)(int khz, int* jtag_speed);
217 /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
218 * a failure if it can't support the KHz/RTCK. */
219 int (*speed_div)(int speed, int* khz);
221 /* Read and clear the power dropout flag. Note that a power dropout
222 * can be transitionary, easily much less than a ms.
224 * So to find out if the power is *currently* on, you must invoke
225 * this method twice. Once to clear the power dropout flag and a
226 * second time to read the current state.
228 * Currently the default implementation is never to detect power dropout.
230 int (*power_dropout)(int* power_dropout);
232 /* Read and clear the srst asserted detection flag.
234 * NB!!!! like power_dropout this does *not* read the current
235 * state. srst assertion is transitionary and *can* be much
238 int (*srst_asserted)(int* srst_asserted);
242 #endif // OPENOCD_JTAG_INTERFACE_H