git.gag.com Git - fw/openocd/blob - 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  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  25  ***************************************************************************/
  26 #ifndef OPENOCD_JTAG_INTERFACE_H
  27 #define OPENOCD_JTAG_INTERFACE_H
  28
  29 /* @file
  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
  34  * cable.
  35  */
  36
  37
  38 /** implementation of wrapper function tap_set_state() */
  39 void tap_set_state_impl(tap_state_t new_state);
  40
  41 /**
  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.
  47  *
  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.
  53  *
  54  * @param new_state The state we think the TAPs are currently in (or
  55  *      are about to enter).
  56  */
  57 #if defined(_DEBUG_JTAG_IO_)
  58 #define tap_set_state(new_state) \
  59         do { \
  60                 LOG_DEBUG( "tap_set_state(%s)", tap_state_name(new_state) ); \
  61                 tap_set_state_impl(new_state); \
  62         } while (0)
  63 #else
  64 static inline void tap_set_state(tap_state_t new_state)
  65 {
  66         tap_set_state_impl(new_state);
  67 }
  68 #endif
  69
  70 /**
  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.
  74  */
  75 tap_state_t tap_get_state(void);
  76
  77 /**
  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.
  81  *
  82  * At completion of that TAP operation this value is copied into the
  83  * state follower via tap_set_state().
  84  *
  85  * @param new_end_state The state the TAPs should enter at completion of
  86  *      a pending TAP operation.
  87  */
  88 void tap_set_end_state(tap_state_t new_end_state);
  89
  90 /**
  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.
  93  */
  94 tap_state_t tap_get_end_state(void);
  95
  96 /**
  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".
 100  *
 101  * The length of the sequence must be determined with a parallel call to
 102  * tap_get_tms_path_len().
 103  *
 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
 107  *      sequence at bit 0.
 108  */
 109 int tap_get_tms_path(tap_state_t from, tap_state_t to);
 110
 111
 112 /**
 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().
 116  *
 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
 122  * more - no less.
 123  *
 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.
 127  */
 128 int tap_get_tms_path_len(tap_state_t from, tap_state_t to);
 129
 130
 131 /**
 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 }
 136  * <p>
 137  * This sequence corresponds to look up tables which are used in some of the
 138  * cable drivers.
 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
 141  *  and terminate.
 142  * @return int - the array (or sequence) index as described above
 143  */
 144 int tap_move_ndx(tap_state_t astate);
 145
 146 /**
 147  * Function tap_is_state_stable
 148  * returns true if the \a astate is stable.
 149  */
 150 bool tap_is_state_stable(tap_state_t astate);
 151
 152 /**
 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.
 158  */
 159 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
 160
 161 /**
 162  * Function tap_state_name
 163  * Returns a string suitable for display representing the JTAG tap_state
 164  */
 165 const char* tap_state_name(tap_state_t state);
 166
 167 /// Provides user-friendly name lookup of TAP states.
 168 tap_state_t tap_state_by_name(const char *name);
 169
 170 /// Allow switching between old and new TMS tables. @see tap_get_tms_path
 171 void tap_use_new_tms_table(bool use_new);
 172
 173 #ifdef _DEBUG_JTAG_IO_
 174 /**
 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.
 181  */
 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);
 184 #else
 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)
 187 {
 188         return start_tap_state;
 189 }
 190 #endif // _DEBUG_JTAG_IO_
 191
 192 typedef struct jtag_interface_s
 193 {
 194         char* name;
 195
 196         /* queued command execution
 197          */
 198         int (*execute_queue)(void);
 199
 200         /* interface initalization
 201          */
 202         int (*speed)(int speed);
 203         int (*register_commands)(struct command_context_s* cmd_ctx);
 204         int (*init)(void);
 205         int (*quit)(void);
 206
 207         /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
 208          *  a failure if it can't support the KHz/RTCK.
 209          *
 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.
 214          */
 215         int (*khz)(int khz, int* jtag_speed);
 216
 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);
 220
 221         /* Read and clear the power dropout flag. Note that a power dropout
 222          *  can be transitionary, easily much less than a ms.
 223          *
 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.
 227          *
 228          *  Currently the default implementation is never to detect power dropout.
 229          */
 230         int (*power_dropout)(int* power_dropout);
 231
 232         /* Read and clear the srst asserted detection flag.
 233          *
 234          * NB!!!! like power_dropout this does *not* read the current
 235          * state. srst assertion is transitionary and *can* be much
 236          * less than 1ms.
 237          */
 238         int (*srst_asserted)(int* srst_asserted);
 239 } jtag_interface_t;
 240
 241
 242 #endif // OPENOCD_JTAG_INTERFACE_H