git.sur5r.net Git - 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, 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 tpiu_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 tpiu_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 */