git.sur5r.net Git - openocd/blob - src/jtag/jtag.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 *   This program is free software; you can redistribute it and/or modify  *
   9 *   it under the terms of the GNU General Public License as published by  *
  10 *   the Free Software Foundation; either version 2 of the License, or     *
  11 *   (at your option) any later version.                                   *
  12 *                                                                         *
  13 *   This program is distributed in the hope that it will be useful,       *
  14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  16 *   GNU General Public License for more details.                          *
  17 *                                                                         *
  18 *   You should have received a copy of the GNU General Public License     *
  19 *   along with this program; if not, write to the                         *
  20 *   Free Software Foundation, Inc.,                                       *
  21 *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  22 ***************************************************************************/
  23 #ifndef JTAG_H
  24 #define JTAG_H
  25
  26 #include "types.h"
  27 #include "binarybuffer.h"
  28 #include "log.h"
  29
  30 #include "command.h"
  31
  32
  33 #ifdef _DEBUG_JTAG_IO_
  34 #define DEBUG_JTAG_IO(expr ...)         LOG_DEBUG(expr)
  35 #else
  36 #define DEBUG_JTAG_IO(expr ...)
  37 #endif
  38
  39 #ifndef DEBUG_JTAG_IOZ
  40 #define DEBUG_JTAG_IOZ 64
  41 #endif
  42
  43 /*-----<Macros>--------------------------------------------------*/
  44
  45 /** When given an array, compute its DIMension, i.e. number of elements in the array */
  46 #define DIM(x)                                  (sizeof(x)/sizeof((x)[0]))
  47
  48 /** Calculate the number of bytes required to hold @a n TAP scan bits */
  49 #define TAP_SCAN_BYTES(n)               CEIL(n, 8)
  50
  51 /*-----</Macros>-------------------------------------------------*/
  52
  53
  54
  55 /*
  56  * Tap states from ARM7TDMI-S Technical reference manual.
  57  * Also, validated against several other ARM core technical manuals.
  58  *
  59  * N.B. tap_get_tms_path() was changed to reflect this corrected
  60  * numbering and ordering of the TAP states.
  61  *
  62  * DANGER!!!! some interfaces care about the actual numbers used
  63  * as they are handed off directly to hardware implementations.
  64  */
  65
  66 typedef enum tap_state
  67 {
  68 #if BUILD_ECOSBOARD
  69 /* These are the old numbers. Leave as-is for now... */
  70         TAP_RESET    = 0, TAP_IDLE = 8,
  71         TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
  72         TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
  73         TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
  74         TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
  75
  76         TAP_NUM_STATES = 16, TAP_INVALID = -1,
  77 #else
  78         /* Proper ARM recommended numbers */
  79         TAP_DREXIT2 = 0x0,
  80         TAP_DREXIT1 = 0x1,
  81         TAP_DRSHIFT = 0x2,
  82         TAP_DRPAUSE = 0x3,
  83         TAP_IRSELECT = 0x4,
  84         TAP_DRUPDATE = 0x5,
  85         TAP_DRCAPTURE = 0x6,
  86         TAP_DRSELECT = 0x7,
  87         TAP_IREXIT2 = 0x8,
  88         TAP_IREXIT1 = 0x9,
  89         TAP_IRSHIFT = 0xa,
  90         TAP_IRPAUSE = 0xb,
  91         TAP_IDLE = 0xc,
  92         TAP_IRUPDATE = 0xd,
  93         TAP_IRCAPTURE = 0xe,
  94         TAP_RESET = 0x0f,
  95
  96         TAP_NUM_STATES = 0x10,
  97
  98         TAP_INVALID = -1,
  99 #endif
 100 } tap_state_t;
 101
 102 typedef struct tap_transition_s
 103 {
 104         tap_state_t high;
 105         tap_state_t low;
 106 } tap_transition_t;
 107
 108 //extern tap_transition_t tap_transitions[16];    /* describe the TAP state diagram */
 109
 110
 111 /*-----<Cable Helper API>-------------------------------------------*/
 112
 113 /* The "Cable Helper API" is what the cable drivers can use to help implement
 114  * their "Cable API".  So a Cable Helper API is a set of helper functions used by
 115  * cable drivers, and this is different from a Cable API.  A "Cable API" is what
 116  * higher level code used to talk to a cable.
 117  */
 118
 119
 120 /** implementation of wrapper function tap_set_state() */
 121 void tap_set_state_impl(tap_state_t new_state);
 122
 123 /**
 124  * Function tap_set_state
 125  * sets the state of a "state follower" which tracks the state of the TAPs connected to the
 126  * cable.  The state follower is hopefully always in the same state as the actual
 127  * TAPs in the jtag chain, and will be so if there are no bugs in the tracking logic within that
 128  * cable driver. All the cable drivers call this function to indicate the state they think
 129  * the TAPs attached to their cables are in.  Because this function can also log transitions,
 130  * it will be helpful to call this function with every transition that the TAPs being manipulated
 131  * are expected to traverse, not just end points of a multi-step state path.
 132  * @param new_state is the state we think the TAPs are currently in or are about to enter.
 133  */
 134 #if defined(_DEBUG_JTAG_IO_)
 135 #define tap_set_state(new_state) \
 136         do { \
 137                 LOG_DEBUG( "tap_set_state(%s)", tap_state_name(new_state) ); \
 138                 tap_set_state_impl(new_state); \
 139         } while (0)
 140 #else
 141 static inline void tap_set_state(tap_state_t new_state)
 142 {
 143         tap_set_state_impl(new_state);
 144 }
 145
 146 #endif
 147
 148 /**
 149  * Function tap_get_state
 150  * gets the state of the "state follower" which tracks the state of the TAPs connected to
 151  * the cable.
 152  * @see tap_set_state
 153  * @return tap_state_t - The state the TAPs are in now.
 154  */
 155 tap_state_t tap_get_state(void);
 156
 157 /**
 158  * Function tap_set_end_state
 159  * sets the state of an "end state follower" which tracks the state that any cable driver
 160  * thinks will be the end (resultant) state of the current TAP SIR or SDR operation.  At completion
 161  * of that TAP operation this value is copied into the state follower via tap_set_state().
 162  * @param new_end_state is that state the TAPs should enter at completion of a pending TAP operation.
 163  */
 164 void        tap_set_end_state(tap_state_t new_end_state);
 165
 166 /**
 167  * Function tap_get_end_state
 168  * @see tap_set_end_state
 169  * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation.
 170  */
 171 tap_state_t tap_get_end_state(void);
 172
 173 /**
 174  * Function tap_get_tms_path
 175  * returns a 7 bit long "bit sequence" indicating what has to be done with TMS
 176  * during a sequence of seven TAP clock cycles in order to get from
 177  * state \a "from" to state \a "to".
 178  * @param from is the starting state
 179  * @param to is the resultant or final state
 180  * @return int - a 7 bit sequence, with the first bit in the sequence at bit 0.
 181  */
 182 int tap_get_tms_path(tap_state_t from, tap_state_t to);
 183
 184 /**
 185  * Function tap_move_ndx
 186  * when given a stable state, returns an index from 0-5.  The index corresponds to a
 187  * sequence of stable states which are given in this order: <p>
 188  * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE }
 189  * <p>
 190  * This sequence corresponds to look up tables which are used in some of the
 191  * cable drivers.
 192  * @param astate is the stable state to find in the sequence.  If a non stable
 193  *  state is passed, this may cause the program to output an error message
 194  *  and terminate.
 195  * @return int - the array (or sequence) index as described above
 196  */
 197 int tap_move_ndx(tap_state_t astate);
 198
 199 /**
 200  * Function tap_is_state_stable
 201  * returns true if the \a astate is stable.
 202  */
 203 bool tap_is_state_stable(tap_state_t astate);
 204
 205 /**
 206  * Function tap_state_transition
 207  * takes a current TAP state and returns the next state according to the tms value.
 208  * @param current_state is the state of a TAP currently.
 209  * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface.
 210  * @return tap_state_t - the next state a TAP would enter.
 211  */
 212 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
 213
 214 /**
 215  * Function tap_state_name
 216  * Returns a string suitable for display representing the JTAG tap_state
 217  */
 218 const char* tap_state_name(tap_state_t state);
 219
 220 #ifdef _DEBUG_JTAG_IO_
 221 /**
 222  * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers.
 223  * @param tms_buf must points to a buffer containing the TMS bitstream.
 224  * @param tdi_buf must points to a buffer containing the TDI bitstream.
 225  * @param tap_len must specify the length of the TMS/TDI bitstreams.
 226  * @param start_tap_state must specify the current TAP state.
 227  * @returns the final TAP state; pass as @a start_tap_state in following call.
 228  */
 229 tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf,
 230                 unsigned tap_len, tap_state_t start_tap_state);
 231 #else
 232 static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
 233                 const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state)
 234 {
 235         return start_tap_state;
 236 }
 237 #endif // _DEBUG_JTAG_IO_
 238
 239 /*-----</Cable Helper API>------------------------------------------*/
 240
 241
 242 extern tap_state_t cmd_queue_end_state;         /* finish DR scans in dr_end_state */
 243 extern tap_state_t cmd_queue_cur_state;         /* current TAP state */
 244
 245 typedef void* error_handler_t;  /* Later on we can delete error_handler_t, but keep it for now to make patches more readable */
 246
 247 struct scan_field_s;
 248 typedef int (*in_handler_t)(u8* in_value, void* priv, struct scan_field_s* field);
 249
 250 typedef struct scan_field_s
 251 {
 252         jtag_tap_t* tap;                /* tap pointer this instruction refers to */
 253         int         num_bits;           /* number of bits this field specifies (up to 32) */
 254         u8*         out_value;          /* value to be scanned into the device */
 255         u8*         out_mask;           /* only masked bits care */
 256         u8*         in_value;           /* pointer to a 32-bit memory location to take data scanned out */
 257         /* in_check_value/mask, in_handler_error_handler, in_handler_priv can be used by the in handler, otherwise they contain garbage  */
 258         u8*          in_check_value;    /* used to validate scan results */
 259         u8*          in_check_mask;     /* check specified bits against check_value */
 260         in_handler_t in_handler;        /* process received buffer using this handler */
 261         void*        in_handler_priv;   /* additional information for the in_handler */
 262 } scan_field_t;
 263
 264 enum scan_type {
 265         /* IN: from device to host, OUT: from host to device */
 266         SCAN_IN = 1, SCAN_OUT = 2, SCAN_IO = 3
 267 };
 268
 269 typedef struct scan_command_s
 270 {
 271         int           ir_scan;      /* instruction/not data scan */
 272         int           num_fields;   /* number of fields in *fields array */
 273         scan_field_t* fields;       /* pointer to an array of data scan fields */
 274         tap_state_t   end_state;    /* TAP state in which JTAG commands should finish */
 275 } scan_command_t;
 276
 277 typedef struct statemove_command_s
 278 {
 279         tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
 280 } statemove_command_t;
 281
 282 typedef struct pathmove_command_s
 283 {
 284         int          num_states;    /* number of states in *path */
 285         tap_state_t* path;          /* states that have to be passed */
 286 } pathmove_command_t;
 287
 288 typedef struct runtest_command_s
 289 {
 290         int         num_cycles;     /* number of cycles that should be spent in Run-Test/Idle */
 291         tap_state_t end_state;      /* TAP state in which JTAG commands should finish */
 292 } runtest_command_t;
 293
 294
 295 typedef struct stableclocks_command_s
 296 {
 297         int num_cycles;             /* number of clock cycles that should be sent */
 298 } stableclocks_command_t;
 299
 300
 301 typedef struct reset_command_s
 302 {
 303         int trst;           /* trst/srst 0: deassert, 1: assert, -1: don't change */
 304         int srst;
 305 } reset_command_t;
 306
 307 typedef struct end_state_command_s
 308 {
 309         tap_state_t end_state;   /* TAP state in which JTAG commands should finish */
 310 } end_state_command_t;
 311
 312 typedef struct sleep_command_s
 313 {
 314         u32 us;     /* number of microseconds to sleep */
 315 } sleep_command_t;
 316
 317 typedef union jtag_command_container_u
 318 {
 319         scan_command_t*         scan;
 320         statemove_command_t*    statemove;
 321         pathmove_command_t*     pathmove;
 322         runtest_command_t*      runtest;
 323         stableclocks_command_t* stableclocks;
 324         reset_command_t*        reset;
 325         end_state_command_t*    end_state;
 326         sleep_command_t* sleep;
 327 } jtag_command_container_t;
 328
 329 enum jtag_command_type {
 330         JTAG_SCAN         = 1,
 331         JTAG_STATEMOVE    = 2,
 332         JTAG_RUNTEST      = 3,
 333         JTAG_RESET        = 4,
 334         JTAG_END_STATE    = 5,
 335         JTAG_PATHMOVE     = 6,
 336         JTAG_SLEEP        = 7,
 337         JTAG_STABLECLOCKS = 8
 338 };
 339
 340 typedef struct jtag_command_s
 341 {
 342         jtag_command_container_t cmd;
 343         enum jtag_command_type   type;
 344         struct jtag_command_s*   next;
 345 } jtag_command_t;
 346
 347 extern jtag_command_t* jtag_command_queue;
 348
 349 /* forward declaration */
 350 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;
 351
 352 /* this is really: typedef jtag_tap_t */
 353 /* But - the typedef is done in "types.h" */
 354 /* due to "forward decloration reasons" */
 355 struct jtag_tap_s
 356 {
 357         const char* chip;
 358         const char* tapname;
 359         const char* dotted_name;
 360         int         abs_chain_position;
 361         int         enabled;
 362         int         ir_length;          /* size of instruction register */
 363         u32         ir_capture_value;
 364         u8*         expected;           /* Capture-IR expected value */
 365         u32         ir_capture_mask;
 366         u8*         expected_mask;      /* Capture-IR expected mask */
 367         u32         idcode;             /* device identification code */
 368         u32*        expected_ids;       /* Array of expected identification codes */
 369         u8          expected_ids_cnt;   /* Number of expected identification codes */
 370         u8*         cur_instr;          /* current instruction */
 371         int         bypass;             /* bypass register selected */
 372
 373         jtag_tap_event_action_t* event_action;
 374
 375         jtag_tap_t* next_tap;
 376 };
 377 extern jtag_tap_t* jtag_AllTaps(void);
 378 extern jtag_tap_t* jtag_TapByPosition(int n);
 379 extern jtag_tap_t* jtag_TapByPosition(int n);
 380 extern jtag_tap_t* jtag_TapByString(const char* dotted_name);
 381 extern jtag_tap_t* jtag_TapByJimObj(Jim_Interp* interp, Jim_Obj* obj);
 382 extern jtag_tap_t* jtag_TapByAbsPosition(int abs_position);
 383 extern int         jtag_NumEnabledTaps(void);
 384 extern int         jtag_NumTotalTaps(void);
 385
 386 static __inline__ jtag_tap_t* jtag_NextEnabledTap(jtag_tap_t* p)
 387 {
 388         if (p == NULL)
 389         {
 390                 /* start at the head of list */
 391                 p = jtag_AllTaps();
 392         }
 393         else
 394         {
 395                 /* start *after* this one */
 396                 p = p->next_tap;
 397         }
 398         while (p)
 399         {
 400                 if (p->enabled)
 401                 {
 402                         break;
 403                 }
 404                 else
 405                 {
 406                         p = p->next_tap;
 407                 }
 408         }
 409
 410         return p;
 411 }
 412
 413
 414 enum reset_line_mode {
 415         LINE_OPEN_DRAIN = 0x0,
 416         LINE_PUSH_PULL  = 0x1,
 417 };
 418
 419 typedef struct jtag_interface_s
 420 {
 421         char* name;
 422
 423         /* queued command execution
 424          */
 425         int (*execute_queue)(void);
 426
 427         /* interface initalization
 428          */
 429         int (*speed)(int speed);
 430         int (*register_commands)(struct command_context_s* cmd_ctx);
 431         int (*init)(void);
 432         int (*quit)(void);
 433
 434         /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns
 435          *  a failure if it can't support the KHz/RTCK.
 436          *
 437          *  WARNING!!!! if RTCK is *slow* then think carefully about
 438          *  whether you actually want to support this in the driver.
 439          *  Many target scripts are written to handle the absence of RTCK
 440          *  and use a fallback kHz TCK.
 441          */
 442         int (*khz)(int khz, int* jtag_speed);
 443
 444         /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns
 445          *  a failure if it can't support the KHz/RTCK. */
 446         int (*speed_div)(int speed, int* khz);
 447
 448         /* Read and clear the power dropout flag. Note that a power dropout
 449          *  can be transitionary, easily much less than a ms.
 450          *
 451          *  So to find out if the power is *currently* on, you must invoke
 452          *  this method twice. Once to clear the power dropout flag and a
 453          *  second time to read the current state.
 454          *
 455          *  Currently the default implementation is never to detect power dropout.
 456          */
 457         int (*power_dropout)(int* power_dropout);
 458
 459         /* Read and clear the srst asserted detection flag.
 460          *
 461          * NB!!!! like power_dropout this does *not* read the current
 462          * state. srst assertion is transitionary and *can* be much
 463          * less than 1ms.
 464          */
 465         int (*srst_asserted)(int* srst_asserted);
 466 } jtag_interface_t;
 467
 468 enum jtag_event {
 469         JTAG_TRST_ASSERTED
 470 };
 471
 472 extern char* jtag_event_strings[];
 473
 474 enum jtag_tap_event {
 475         JTAG_TAP_EVENT_ENABLE,
 476         JTAG_TAP_EVENT_DISABLE
 477 };
 478
 479 extern const Jim_Nvp nvp_jtag_tap_event[];
 480
 481 struct jtag_tap_event_action_s
 482 {
 483         enum jtag_tap_event      event;
 484         Jim_Obj*                 body;
 485         jtag_tap_event_action_t* next;
 486 };
 487
 488 extern int jtag_trst;
 489 extern int jtag_srst;
 490
 491 typedef struct jtag_event_callback_s
 492 {
 493         int (*callback)(enum jtag_event event, void* priv);
 494         void*                         priv;
 495         struct jtag_event_callback_s* next;
 496 } jtag_event_callback_t;
 497
 498 extern jtag_event_callback_t* jtag_event_callbacks;
 499
 500 extern jtag_interface_t*      jtag; /* global pointer to configured JTAG interface */
 501
 502 extern int jtag_speed;
 503 extern int jtag_speed_post_reset;
 504
 505 enum reset_types {
 506         RESET_NONE            = 0x0,
 507         RESET_HAS_TRST        = 0x1,
 508         RESET_HAS_SRST        = 0x2,
 509         RESET_TRST_AND_SRST   = 0x3,
 510         RESET_SRST_PULLS_TRST = 0x4,
 511         RESET_TRST_PULLS_SRST = 0x8,
 512         RESET_TRST_OPEN_DRAIN = 0x10,
 513         RESET_SRST_PUSH_PULL  = 0x20,
 514 };
 515
 516 extern enum reset_types jtag_reset_config;
 517
 518 /* initialize interface upon startup. A successful no-op
 519  * upon subsequent invocations
 520  */
 521 extern int  jtag_interface_init(struct command_context_s* cmd_ctx);
 522
 523 /* initialize JTAG chain using only a RESET reset. If init fails,
 524  * try reset + init.
 525  */
 526 extern int  jtag_init(struct command_context_s* cmd_ctx);
 527
 528 /* reset, then initialize JTAG chain */
 529 extern int  jtag_init_reset(struct command_context_s* cmd_ctx);
 530 extern int  jtag_register_commands(struct command_context_s* cmd_ctx);
 531
 532 /* JTAG interface, can be implemented with a software or hardware fifo
 533  *
 534  * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states. TAP_DRSHIFT/IRSHIFT as end states
 535  * can be emulated by using a larger scan.
 536  *
 537  * Code that is relatively insensitive to the path(as long
 538  * as it is JTAG compliant) taken through state machine can use
 539  * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be
 540  * specified as end state and a subsequent jtag_add_pathmove() must
 541  * be issued.
 542  *
 543  */
 544 extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 545 extern int  interface_jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 546 extern void jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 547 extern int  interface_jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 548 extern void jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 549 extern int  interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 550 extern void jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 551 extern int  interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
 552
 553 /* run a TAP_RESET reset. End state is TAP_RESET, regardless
 554  * of start state.
 555  */
 556 extern void jtag_add_tlr(void);
 557 extern int  interface_jtag_add_tlr(void);
 558
 559 /* Do not use jtag_add_pathmove() unless you need to, but do use it
 560  * if you have to.
 561  *
 562  * DANGER! If the target is dependent upon a particular sequence
 563  * of transitions for things to work correctly(e.g. as a workaround
 564  * for an errata that contradicts the JTAG standard), then pathmove
 565  * must be used, even if some jtag interfaces happen to use the
 566  * desired path. Worse, the jtag interface used for testing a
 567  * particular implementation, could happen to use the "desired"
 568  * path when transitioning to/from end
 569  * state.
 570  *
 571  * A list of unambigious single clock state transitions, not
 572  * all drivers can support this, but it is required for e.g.
 573  * XScale and Xilinx support
 574  *
 575  * Note! TAP_RESET must not be used in the path!
 576  *
 577  * Note that the first on the list must be reachable
 578  * via a single transition from the current state.
 579  *
 580  * All drivers are required to implement jtag_add_pathmove().
 581  * However, if the pathmove sequence can not be precisely
 582  * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
 583  * must return an error. It is legal, but not recommended, that
 584  * a driver returns an error in all cases for a pathmove if it
 585  * can only implement a few transitions and therefore
 586  * a partial implementation of pathmove would have little practical
 587  * application.
 588  */
 589 extern void jtag_add_pathmove(int num_states, tap_state_t* path);
 590 extern int  interface_jtag_add_pathmove(int num_states, tap_state_t* path);
 591
 592 /* go to TAP_IDLE, if we're not already there and cycle
 593  * precisely num_cycles in the TAP_IDLE after which move
 594  * to the end state, if it is != TAP_IDLE
 595  *
 596  * nb! num_cycles can be 0, in which case the fn will navigate
 597  * to endstate via TAP_IDLE
 598  */
 599 extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);
 600 extern int  interface_jtag_add_runtest(int num_cycles, tap_state_t endstate);
 601
 602 /* A reset of the TAP state machine can be requested.
 603  *
 604  * Whether tms or trst reset is used depends on the capabilities of
 605  * the target and jtag interface(reset_config  command configures this).
 606  *
 607  * srst can driver a reset of the TAP state machine and vice
 608  * versa
 609  *
 610  * Application code may need to examine value of jtag_reset_config
 611  * to determine the proper codepath
 612  *
 613  * DANGER! Even though srst drives trst, trst might not be connected to
 614  * the interface, and it might actually be *harmful* to assert trst in this case.
 615  *
 616  * This is why combinations such as "reset_config srst_only srst_pulls_trst"
 617  * are supported.
 618  *
 619  * only req_tlr_or_trst and srst can have a transition for a
 620  * call as the effects of transitioning both at the "same time"
 621  * are undefined, but when srst_pulls_trst or vice versa,
 622  * then trst & srst *must* be asserted together.
 623  */
 624 extern void jtag_add_reset(int req_tlr_or_trst, int srst);
 625
 626 /* this drives the actual srst and trst pins. srst will always be 0
 627  * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for
 628  * trst.
 629  *
 630  * the higher level jtag_add_reset will invoke jtag_add_tlr() if
 631  * approperiate
 632  */
 633 extern int  interface_jtag_add_reset(int trst, int srst);
 634 extern void jtag_add_end_state(tap_state_t endstate);
 635 extern int  interface_jtag_add_end_state(tap_state_t endstate);
 636 extern void jtag_add_sleep(u32 us);
 637 extern int  interface_jtag_add_sleep(u32 us);
 638
 639
 640 /**
 641  * Function jtag_add_stable_clocks
 642  * first checks that the state in which the clocks are to be issued is
 643  * stable, then queues up clock_count clocks for transmission.
 644  */
 645 void jtag_add_clocks(int num_cycles);
 646 int  interface_jtag_add_clocks(int num_cycles);
 647
 648
 649 /*
 650  * For software FIFO implementations, the queued commands can be executed
 651  * during this call or earlier. A sw queue might decide to push out
 652  * some of the jtag_add_xxx() operations once the queue is "big enough".
 653  *
 654  * This fn will return an error code if any of the prior jtag_add_xxx()
 655  * calls caused a failure, e.g. check failure. Note that it does not
 656  * matter if the operation was executed *before* jtag_execute_queue(),
 657  * jtag_execute_queue() will still return an error code.
 658  *
 659  * All jtag_add_xxx() calls that have in_handler!=NULL will have been
 660  * executed when this fn returns, but if what has been queued only
 661  * clocks data out, without reading anything back, then JTAG could
 662  * be running *after* jtag_execute_queue() returns. The API does
 663  * not define a way to flush a hw FIFO that runs *after*
 664  * jtag_execute_queue() returns.
 665  *
 666  * jtag_add_xxx() commands can either be executed immediately or
 667  * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
 668  */
 669 extern int            jtag_execute_queue(void);
 670
 671 /* can be implemented by hw+sw */
 672 extern int            interface_jtag_execute_queue(void);
 673 extern int            jtag_power_dropout(int* dropout);
 674 extern int            jtag_srst_asserted(int* srst_asserted);
 675
 676 /* JTAG support functions */
 677 extern void           jtag_set_check_value(scan_field_t* field, u8* value, u8* mask, error_handler_t* in_error_handler);
 678 extern enum scan_type jtag_scan_type(scan_command_t* cmd);
 679 extern int            jtag_scan_size(scan_command_t* cmd);
 680 extern int            jtag_read_buffer(u8* buffer, scan_command_t* cmd);
 681 extern int            jtag_build_buffer(scan_command_t* cmd, u8** buffer);
 682
 683 extern void           jtag_sleep(u32 us);
 684 extern int            jtag_call_event_callbacks(enum jtag_event event);
 685 extern int            jtag_register_event_callback(int (* callback)(enum jtag_event event, void* priv), void* priv);
 686
 687 extern int jtag_verify_capture_ir;
 688
 689 void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
 690
 691 /* error codes
 692  * JTAG subsystem uses codes between -100 and -199 */
 693
 694 #define ERROR_JTAG_INIT_FAILED       (-100)
 695 #define ERROR_JTAG_INVALID_INTERFACE (-101)
 696 #define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
 697 #define ERROR_JTAG_TRST_ASSERTED     (-103)
 698 #define ERROR_JTAG_QUEUE_FAILED      (-104)
 699 #define ERROR_JTAG_NOT_STABLE_STATE  (-105)
 700 #define ERROR_JTAG_DEVICE_ERROR      (-107)
 701
 702
 703 /* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */
 704 #ifdef HAVE_JTAG_MINIDRIVER_H
 705 /* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */
 706 #include "jtag_minidriver.h"
 707 #define MINIDRIVER(a) notused ## a
 708 #else
 709 #define MINIDRIVER(a) a
 710
 711 /* jtag_add_dr_out() is a faster version of jtag_add_dr_scan()
 712  *
 713  * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
 714  *
 715  * num_bits[i] is the number of bits to clock out from value[i] LSB first.
 716  *
 717  * If the device is in bypass, then that is an error condition in
 718  * the caller code that is not detected by this fn, whereas jtag_add_dr_scan()
 719  * does detect it. Similarly if the device is not in bypass, data must
 720  * be passed to it.
 721  *
 722  * If anything fails, then jtag_error will be set and jtag_execute() will
 723  * return an error. There is no way to determine if there was a failure
 724  * during this function call.
 725  *
 726  * Note that this jtag_add_dr_out can be defined as an inline function.
 727  */
 728 extern void interface_jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value,
 729                 tap_state_t end_state);
 730
 731 #endif
 732
 733 static __inline__ void jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value,
 734                 tap_state_t end_state)
 735 {
 736         if (end_state != TAP_INVALID)
 737                 cmd_queue_end_state = end_state;
 738         cmd_queue_cur_state = cmd_queue_end_state;
 739         interface_jtag_add_dr_out(tap, num_fields, num_bits, value, cmd_queue_end_state);
 740 }
 741
 742
 743 #endif /* JTAG_H */