jtag: make out_value const
[fw/openocd] / src / jtag / jtag.h
1 /***************************************************************************
2 *   Copyright (C) 2005 by Dominic Rath                                    *
3 *   Dominic.Rath@gmx.de                                                   *
4 *                                                                         *
5 *   Copyright (C) 2007-2010 Ã˜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 <helper/binarybuffer.h>
27 #include <helper/log.h>
28
29 #ifdef _DEBUG_JTAG_IO_
30 #define DEBUG_JTAG_IO(expr ...) \
31         do { if (1) LOG_DEBUG(expr); } while (0)
32 #else
33 #define DEBUG_JTAG_IO(expr ...) \
34         do { if (0) LOG_DEBUG(expr); } while (0)
35 #endif
36
37 #ifndef DEBUG_JTAG_IOZ
38 #define DEBUG_JTAG_IOZ 64
39 #endif
40
41 /*-----</Macros>-------------------------------------------------*/
42
43 /**
44  * Defines JTAG Test Access Port states.
45  *
46  * These definitions were gleaned from the ARM7TDMI-S Technical
47  * Reference Manual and validated against several other ARM core
48  * technical manuals.
49  *
50  * FIXME some interfaces require specific numbers be used, as they
51  * are handed-off directly to their hardware implementations.
52  * Fix those drivers to map as appropriate ... then pick some
53  * sane set of numbers here (where 0/uninitialized == INVALID).
54  */
55 typedef enum tap_state
56 {
57         TAP_INVALID = -1,
58
59 #if BUILD_ZY1000
60         /* These are the old numbers. Leave as-is for now... */
61         TAP_RESET    = 0, TAP_IDLE = 8,
62         TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
63         TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
64         TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
65         TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
66
67 #else
68         /* Proper ARM recommended numbers */
69         TAP_DREXIT2 = 0x0,
70         TAP_DREXIT1 = 0x1,
71         TAP_DRSHIFT = 0x2,
72         TAP_DRPAUSE = 0x3,
73         TAP_IRSELECT = 0x4,
74         TAP_DRUPDATE = 0x5,
75         TAP_DRCAPTURE = 0x6,
76         TAP_DRSELECT = 0x7,
77         TAP_IREXIT2 = 0x8,
78         TAP_IREXIT1 = 0x9,
79         TAP_IRSHIFT = 0xa,
80         TAP_IRPAUSE = 0xb,
81         TAP_IDLE = 0xc,
82         TAP_IRUPDATE = 0xd,
83         TAP_IRCAPTURE = 0xe,
84         TAP_RESET = 0x0f,
85
86 #endif
87 } tap_state_t;
88
89 /**
90  * Function tap_state_name
91  * Returns a string suitable for display representing the JTAG tap_state
92  */
93 const char *tap_state_name(tap_state_t state);
94
95 /// Provides user-friendly name lookup of TAP states.
96 tap_state_t tap_state_by_name(const char *name);
97
98 /// The current TAP state of the pending JTAG command queue.
99 extern tap_state_t cmd_queue_cur_state;
100
101 /**
102  * This structure defines a single scan field in the scan. It provides
103  * fields for the field's width and pointers to scan input and output
104  * values.
105  *
106  * In addition, this structure includes a value and mask that is used by
107  * jtag_add_dr_scan_check() to validate the value that was scanned out.
108  *
109  * The allocated, modified, and intmp fields are internal work space.
110  */
111 struct scan_field {
112         /// The number of bits this field specifies (up to 32)
113         int num_bits;
114         /// A pointer to value to be scanned into the device
115         const uint8_t* out_value;
116         /// A pointer to a 32-bit memory location for data scanned out
117         uint8_t* in_value;
118
119         /// The value used to check the data scanned out.
120         uint8_t* check_value;
121         /// The mask to go with check_value
122         uint8_t* check_mask;
123
124         /// in_value has been allocated for the queue
125         int allocated;
126         /// Indicates we modified the in_value.
127         int modified;
128         /// temporary storage for performing value checks synchronously
129         uint8_t intmp[4];
130 };
131
132 struct jtag_tap {
133         const char* chip;
134         const char* tapname;
135         const char* dotted_name;
136         int abs_chain_position;
137         /// Is this TAP disabled after JTAG reset?
138         bool disabled_after_reset;
139         /// Is this TAP currently enabled?
140         bool enabled;
141         int ir_length; /**< size of instruction register */
142         uint32_t ir_capture_value;
143         uint8_t* expected; /**< Capture-IR expected value */
144         uint32_t ir_capture_mask;
145         uint8_t* expected_mask; /**< Capture-IR expected mask */
146         uint32_t idcode; /**< device identification code */
147         /** not all devices have idcode,
148          * we'll discover this during chain examination */
149         bool hasidcode;
150
151         /// Array of expected identification codes */
152         uint32_t* expected_ids;
153         /// Number of expected identification codes
154         uint8_t expected_ids_cnt;
155
156         /// Flag saying whether to ignore version field in expected_ids[]
157         bool ignore_version;
158
159         /// current instruction
160         uint8_t* cur_instr;
161         /// Bypass register selected
162         int bypass;
163
164         struct jtag_tap_event_action *event_action;
165
166         struct jtag_tap* next_tap;
167 };
168
169 void jtag_tap_init(struct jtag_tap *tap);
170 void jtag_tap_free(struct jtag_tap *tap);
171
172 struct jtag_tap* jtag_all_taps(void);
173 const char *jtag_tap_name(const struct jtag_tap *tap);
174 struct jtag_tap* jtag_tap_by_string(const char* dotted_name);
175 struct jtag_tap* jtag_tap_by_jim_obj(Jim_Interp* interp, Jim_Obj* obj);
176 struct jtag_tap* jtag_tap_next_enabled(struct jtag_tap* p);
177 unsigned jtag_tap_count_enabled(void);
178 unsigned jtag_tap_count(void);
179
180
181 /*
182  * - TRST_ASSERTED triggers two sets of callbacks, after operations to
183  *   reset the scan chain -- via TMS+TCK signaling, or deasserting the
184  *   nTRST signal -- are queued:
185  *
186  *    + Callbacks in C code fire first, patching internal state
187  *    + Then post-reset event scripts fire ... activating JTAG circuits
188  *      via TCK cycles, exiting SWD mode via TMS sequences, etc
189  *
190  *   During those callbacks, scan chain contents have not been validated.
191  *   JTAG operations that address a specific TAP (primarily DR/IR scans)
192  *   must *not* be queued.
193  *
194  * - TAP_EVENT_SETUP is reported after TRST_ASSERTED, and after the scan
195  *   chain has been validated.  JTAG operations including scans that
196  *   target specific TAPs may be performed.
197  *
198  * - TAP_EVENT_ENABLE and TAP_EVENT_DISABLE implement TAP activation and
199  *   deactivation outside the core using scripted code that understands
200  *   the specific JTAG router type.  They might be triggered indirectly
201  *   from EVENT_SETUP operations.
202  */
203 enum jtag_event {
204         JTAG_TRST_ASSERTED,
205         JTAG_TAP_EVENT_SETUP,
206         JTAG_TAP_EVENT_ENABLE,
207         JTAG_TAP_EVENT_DISABLE,
208 };
209
210 struct jtag_tap_event_action
211 {
212         /// The event for which this action will be triggered.
213         enum jtag_event event;
214         /// The interpreter to use for evaluating the @c body.
215         Jim_Interp *interp;
216         /// Contains a script to 'eval' when the @c event is triggered.
217         Jim_Obj *body;
218         // next action in linked list
219         struct jtag_tap_event_action *next;
220 };
221
222 /**
223  * Defines the function signature requide for JTAG event callback
224  * functions, which are added with jtag_register_event_callback()
225  * and removed jtag_unregister_event_callback().
226  * @param event The event to handle.
227  * @param prive A pointer to data that was passed to
228  *      jtag_register_event_callback().
229  * @returns Must return ERROR_OK on success, or an error code on failure.
230  *
231  * @todo Change to return void or define a use for its return code.
232  */
233 typedef int (*jtag_event_handler_t)(enum jtag_event event, void* priv);
234
235 int jtag_register_event_callback(jtag_event_handler_t f, void *x);
236 int jtag_unregister_event_callback(jtag_event_handler_t f, void *x);
237
238 int jtag_call_event_callbacks(enum jtag_event event);
239
240
241 /// @returns The current JTAG speed setting.
242 int jtag_get_speed(void);
243
244 /**
245  * Given a @a speed setting, use the interface @c speed_div callback to
246  * adjust the setting.
247  * @param speed The speed setting to convert back to readable KHz.
248  * @returns ERROR_OK if the interface has not been initialized or on success;
249  *      otherwise, the error code produced by the @c speed_div callback.
250  */
251 int jtag_get_speed_readable(int *speed);
252
253 /// Attempt to configure the interface for the specified KHz.
254 int jtag_config_khz(unsigned khz);
255
256 /**
257  * Attempt to enable RTCK/RCLK. If that fails, fallback to the
258  * specified frequency.
259  */
260 int jtag_config_rclk(unsigned fallback_speed_khz);
261
262 /// Retreives the clock speed of the JTAG interface in KHz.
263 unsigned jtag_get_speed_khz(void);
264
265
266 enum reset_types {
267         RESET_NONE            = 0x0,
268         RESET_HAS_TRST        = 0x1,
269         RESET_HAS_SRST        = 0x2,
270         RESET_TRST_AND_SRST   = 0x3,
271         RESET_SRST_PULLS_TRST = 0x4,
272         RESET_TRST_PULLS_SRST = 0x8,
273         RESET_TRST_OPEN_DRAIN = 0x10,
274         RESET_SRST_PUSH_PULL  = 0x20,
275         RESET_SRST_NO_GATING  = 0x40,
276 };
277
278 enum reset_types jtag_get_reset_config(void);
279 void jtag_set_reset_config(enum reset_types type);
280
281 void jtag_set_nsrst_delay(unsigned delay);
282 unsigned jtag_get_nsrst_delay(void);
283
284 void jtag_set_ntrst_delay(unsigned delay);
285 unsigned jtag_get_ntrst_delay(void);
286
287 void jtag_set_nsrst_assert_width(unsigned delay);
288 unsigned jtag_get_nsrst_assert_width(void);
289
290 void jtag_set_ntrst_assert_width(unsigned delay);
291 unsigned jtag_get_ntrst_assert_width(void);
292
293 /// @returns The current state of TRST.
294 int jtag_get_trst(void);
295 /// @returns The current state of SRST.
296 int jtag_get_srst(void);
297
298 /// Enable or disable data scan verification checking.
299 void jtag_set_verify(bool enable);
300 /// @returns True if data scan verification will be performed.
301 bool jtag_will_verify(void);
302
303 /// Enable or disable verification of IR scan checking.
304 void jtag_set_verify_capture_ir(bool enable);
305 /// @returns True if IR scan verification will be performed.
306 bool jtag_will_verify_capture_ir(void);
307
308 /** Initialize debug adapter upon startup.  */
309 int  adapter_init(struct command_context* cmd_ctx);
310
311 /// Shutdown the debug adapter upon program exit.
312 int  adapter_quit(void);
313
314 /**
315  * Initialize JTAG chain using only a RESET reset. If init fails,
316  * try reset + init.
317  */
318 int  jtag_init(struct command_context* cmd_ctx);
319
320 /// reset, then initialize JTAG chain
321 int jtag_init_reset(struct command_context* cmd_ctx);
322 int jtag_register_commands(struct command_context* cmd_ctx);
323 int jtag_init_inner(struct command_context *cmd_ctx);
324
325 /**
326  * @file
327  * The JTAG interface can be implemented with a software or hardware fifo.
328  *
329  * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
330  * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
331  * scans.
332  *
333  * Code that is relatively insensitive to the path taken through state
334  * machine (as long as it is JTAG compliant) can use @a endstate for
335  * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
336  * end state and a subsequent jtag_add_pathmove() must be issued.
337  */
338
339 /**
340  * Generate an IR SCAN with a list of scan fields with one entry for
341  * each enabled TAP.
342  *
343  * If the input field list contains an instruction value for a TAP then
344  * that is used otherwise the TAP is set to bypass.
345  *
346  * TAPs for which no fields are passed are marked as bypassed for
347  * subsequent DR SCANs.
348  *
349  */
350 void jtag_add_ir_scan(struct jtag_tap* tap,
351                 struct scan_field* fields, tap_state_t endstate);
352 /**
353  * The same as jtag_add_ir_scan except no verification is performed out
354  * the output values.
355  */
356 void jtag_add_ir_scan_noverify(struct jtag_tap* tap,
357                 const struct scan_field *fields, tap_state_t state);
358 /**
359  * Scan out the bits in ir scan mode.
360  *
361  * If in_bits == NULL, discard incoming bits.
362  */
363 void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits,
364                 tap_state_t endstate);
365
366
367 /**
368  * Set in_value to point to 32 bits of memory to scan into. This
369  * function is a way to handle the case of synchronous and asynchronous
370  * JTAG queues.
371  *
372  * In the event of an asynchronous queue execution the queue buffer
373  * allocation method is used, for the synchronous case the temporary 32
374  * bits come from the input field itself.
375  */
376 void jtag_alloc_in_value32(struct scan_field *field);
377
378 /**
379  * Generate a DR SCAN using the fields passed to the function.
380  * For connected TAPs, the function checks in_fields and uses fields
381  * specified there.  For bypassed TAPs, the function generates a dummy
382  * 1-bit field.  The bypass status of TAPs is set by jtag_add_ir_scan().
383  */
384 void jtag_add_dr_scan(struct jtag_tap* tap, int num_fields,
385                 const struct scan_field* fields, tap_state_t endstate);
386 /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
387 void jtag_add_dr_scan_check(struct jtag_tap* tap, int num_fields,
388                 struct scan_field* fields, tap_state_t endstate);
389 /**
390  * Scan out the bits in ir scan mode.
391  *
392  * If in_bits == NULL, discard incoming bits.
393  */
394 void jtag_add_plain_dr_scan(int num_bits,
395                 const uint8_t *out_bits, uint8_t *in_bits, tap_state_t endstate);
396
397 /**
398  * Defines the type of data passed to the jtag_callback_t interface.
399  * The underlying type must allow storing an @c int or pointer type.
400  */
401 typedef intptr_t jtag_callback_data_t;
402
403 /**
404  * Defines a simple JTAG callback that can allow conversions on data
405  * scanned in from an interface.
406  *
407  * This callback should only be used for conversion that cannot fail.
408  * For conversion types or checks that can fail, use the more complete
409  * variant: jtag_callback_t.
410  */
411 typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
412
413 /// A simpler version of jtag_add_callback4().
414 void jtag_add_callback(jtag_callback1_t, jtag_callback_data_t data0);
415
416
417 /**
418  * Defines the interface of the JTAG callback mechanism.  Such
419  * callbacks can be executed once the queue has been flushed.
420  *
421  * The JTAG queue can be executed synchronously or asynchronously.
422  * Typically for USB, the queue is executed asynchronously.  For
423  * low-latency interfaces, the queue may be executed synchronously.
424  *
425  * The callback mechanism is very general and does not make many
426  * assumptions about what the callback does or what its arguments are.
427  * These callbacks are typically executed *after* the *entire* JTAG
428  * queue has been executed for e.g. USB interfaces, and they are
429  * guaranteeed to be invoked in the order that they were queued.
430  *
431  * If the execution of the queue fails before the callbacks, then --
432  * depending on driver implementation -- the callbacks may or may not be
433  * invoked.
434  *
435  * @todo Make that behavior consistent.
436  *
437  * @param data0 Typically used to point to the data to operate on.
438  * Frequently this will be the data clocked in during a shift operation.
439  * @param data1 An integer big enough to use as an @c int or a pointer.
440  * @param data2 An integer big enough to use as an @c int or a pointer.
441  * @param data3 An integer big enough to use as an @c int or a pointer.
442  * @returns an error code
443  */
444 typedef int (*jtag_callback_t)(jtag_callback_data_t data0,
445                                 jtag_callback_data_t data1,
446                                 jtag_callback_data_t data2,
447                                 jtag_callback_data_t data3);
448
449 /**
450  * Run a TAP_RESET reset where the end state is TAP_RESET,
451  * regardless of the start state.
452  */
453 void jtag_add_tlr(void);
454
455 /**
456  * Application code *must* assume that interfaces will
457  * implement transitions between states with different
458  * paths and path lengths through the state diagram. The
459  * path will vary across interface and also across versions
460  * of the same interface over time. Even if the OpenOCD code
461  * is unchanged, the actual path taken may vary over time
462  * and versions of interface firmware or PCB revisions.
463  *
464  * Use jtag_add_pathmove() when specific transition sequences
465  * are required.
466  *
467  * Do not use jtag_add_pathmove() unless you need to, but do use it
468  * if you have to.
469  *
470  * DANGER! If the target is dependent upon a particular sequence
471  * of transitions for things to work correctly(e.g. as a workaround
472  * for an errata that contradicts the JTAG standard), then pathmove
473  * must be used, even if some jtag interfaces happen to use the
474  * desired path. Worse, the jtag interface used for testing a
475  * particular implementation, could happen to use the "desired"
476  * path when transitioning to/from end
477  * state.
478  *
479  * A list of unambigious single clock state transitions, not
480  * all drivers can support this, but it is required for e.g.
481  * XScale and Xilinx support
482  *
483  * Note! TAP_RESET must not be used in the path!
484  *
485  * Note that the first on the list must be reachable
486  * via a single transition from the current state.
487  *
488  * All drivers are required to implement jtag_add_pathmove().
489  * However, if the pathmove sequence can not be precisely
490  * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
491  * must return an error. It is legal, but not recommended, that
492  * a driver returns an error in all cases for a pathmove if it
493  * can only implement a few transitions and therefore
494  * a partial implementation of pathmove would have little practical
495  * application.
496  *
497  * If an error occurs, jtag_error will contain one of these error codes:
498  *   - ERROR_JTAG_NOT_STABLE_STATE -- The final state was not stable.
499  *   - ERROR_JTAG_STATE_INVALID -- The path passed through TAP_RESET.
500  *   - ERROR_JTAG_TRANSITION_INVALID -- The path includes invalid
501  *     state transitions.
502  */
503 void jtag_add_pathmove(int num_states, const tap_state_t* path);
504
505 /**
506  * jtag_add_statemove() moves from the current state to @a goal_state.
507  *
508  * @param goal_state The final TAP state.
509  * @return ERROR_OK on success, or an error code on failure.
510  *
511  * Moves from the current state to the goal \a state.
512  * Both states must be stable.
513  */
514 int jtag_add_statemove(tap_state_t goal_state);
515
516 /**
517  * Goes to TAP_IDLE (if we're not already there), cycle
518  * precisely num_cycles in the TAP_IDLE state, after which move
519  * to @a endstate (unless it is also TAP_IDLE).
520  *
521  * @param num_cycles Number of cycles in TAP_IDLE state.  This argument
522  *      may be 0, in which case this routine will navigate to @a endstate
523  *      via TAP_IDLE.
524  * @param endstate The final state.
525  */
526 void jtag_add_runtest(int num_cycles, tap_state_t endstate);
527
528 /**
529  * A reset of the TAP state machine can be requested.
530  *
531  * Whether tms or trst reset is used depends on the capabilities of
532  * the target and jtag interface(reset_config  command configures this).
533  *
534  * srst can driver a reset of the TAP state machine and vice
535  * versa
536  *
537  * Application code may need to examine value of jtag_reset_config
538  * to determine the proper codepath
539  *
540  * DANGER! Even though srst drives trst, trst might not be connected to
541  * the interface, and it might actually be *harmful* to assert trst in this case.
542  *
543  * This is why combinations such as "reset_config srst_only srst_pulls_trst"
544  * are supported.
545  *
546  * only req_tlr_or_trst and srst can have a transition for a
547  * call as the effects of transitioning both at the "same time"
548  * are undefined, but when srst_pulls_trst or vice versa,
549  * then trst & srst *must* be asserted together.
550  */
551 void jtag_add_reset(int req_tlr_or_trst, int srst);
552
553 void jtag_add_sleep(uint32_t us);
554
555 int jtag_add_tms_seq(unsigned nbits, const uint8_t *seq, enum tap_state t);
556
557 /**
558  * Function jtag_add_clocks
559  * first checks that the state in which the clocks are to be issued is
560  * stable, then queues up num_cycles clocks for transmission.
561  */
562 void jtag_add_clocks(int num_cycles);
563
564
565 /**
566  * For software FIFO implementations, the queued commands can be executed
567  * during this call or earlier. A sw queue might decide to push out
568  * some of the jtag_add_xxx() operations once the queue is "big enough".
569  *
570  * This fn will return an error code if any of the prior jtag_add_xxx()
571  * calls caused a failure, e.g. check failure. Note that it does not
572  * matter if the operation was executed *before* jtag_execute_queue(),
573  * jtag_execute_queue() will still return an error code.
574  *
575  * All jtag_add_xxx() calls that have in_handler != NULL will have been
576  * executed when this fn returns, but if what has been queued only
577  * clocks data out, without reading anything back, then JTAG could
578  * be running *after* jtag_execute_queue() returns. The API does
579  * not define a way to flush a hw FIFO that runs *after*
580  * jtag_execute_queue() returns.
581  *
582  * jtag_add_xxx() commands can either be executed immediately or
583  * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
584  */
585 int jtag_execute_queue(void);
586
587 /// same as jtag_execute_queue() but does not clear the error flag
588 void jtag_execute_queue_noclear(void);
589
590 /// @returns the number of times the scan queue has been flushed
591 int jtag_get_flush_queue_count(void);
592
593 /// Report Tcl event to all TAPs
594 void jtag_notify_event(enum jtag_event);
595
596
597 /* can be implemented by hw + sw */
598 int jtag_power_dropout(int* dropout);
599 int jtag_srst_asserted(int* srst_asserted);
600
601 /* JTAG support functions */
602
603 /**
604  * Execute jtag queue and check value with an optional mask.
605  * @param field Pointer to scan field.
606  * @param value Pointer to scan value.
607  * @param mask Pointer to scan mask; may be NULL.
608  * @returns Nothing, but calls jtag_set_error() on any error.
609  */
610 void jtag_check_value_mask(struct scan_field *field, uint8_t *value, uint8_t *mask);
611
612 void jtag_sleep(uint32_t us);
613
614 /*
615  * The JTAG subsystem defines a number of error codes,
616  * using codes between -100 and -199.
617  */
618 #define ERROR_JTAG_INIT_FAILED       (-100)
619 #define ERROR_JTAG_INVALID_INTERFACE (-101)
620 #define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
621 #define ERROR_JTAG_TRST_ASSERTED     (-103)
622 #define ERROR_JTAG_QUEUE_FAILED      (-104)
623 #define ERROR_JTAG_NOT_STABLE_STATE  (-105)
624 #define ERROR_JTAG_DEVICE_ERROR      (-107)
625 #define ERROR_JTAG_STATE_INVALID     (-108)
626 #define ERROR_JTAG_TRANSITION_INVALID (-109)
627 #define ERROR_JTAG_INIT_SOFT_FAIL    (-110)
628
629 /**
630  * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
631  * only scans data out. It operates on 32 bit integers instead
632  * of 8 bit, which makes it a better impedance match with
633  * the calling code which often operate on 32 bit integers.
634  *
635  * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
636  *
637  * num_bits[i] is the number of bits to clock out from value[i] LSB first.
638  *
639  * If the device is in bypass, then that is an error condition in
640  * the caller code that is not detected by this fn, whereas
641  * jtag_add_dr_scan() does detect it. Similarly if the device is not in
642  * bypass, data must be passed to it.
643  *
644  * If anything fails, then jtag_error will be set and jtag_execute() will
645  * return an error. There is no way to determine if there was a failure
646  * during this function call.
647  *
648  * This is an inline fn to speed up embedded hosts. Also note that
649  * interface_jtag_add_dr_out() can be a *small* inline function for
650  * embedded hosts.
651  *
652  * There is no jtag_add_dr_outin() version of this fn that also allows
653  * clocking data back in. Patches gladly accepted!
654  */
655
656
657 /**
658  * Set the current JTAG core execution error, unless one was set
659  * by a previous call previously.  Driver or application code must
660  * use jtag_error_clear to reset jtag_error once this routine has been
661  * called with a non-zero error code.
662  */
663 void jtag_set_error(int error);
664 /// @returns The current value of jtag_error
665 int jtag_get_error(void);
666 /**
667  * Resets jtag_error to ERROR_OK, returning its previous value.
668  * @returns The previous value of @c jtag_error.
669  */
670 int jtag_error_clear(void);
671
672 /**
673  * Return true if it's safe for a background polling task to access the
674  * JTAG scan chain.  Polling may be explicitly disallowed, and is also
675  * unsafe while nTRST is active or the JTAG clock is gated off.
676  */
677 bool is_jtag_poll_safe(void);
678
679 /**
680  * Return flag reporting whether JTAG polling is disallowed.
681  */
682 bool jtag_poll_get_enabled(void);
683
684 /**
685  * Assign flag reporting whether JTAG polling is disallowed.
686  */
687 void jtag_poll_set_enabled(bool value);
688
689
690 /* The minidriver may have inline versions of some of the low
691  * level APIs that are used in inner loops. */
692 #include <jtag/minidriver.h>
693
694 #endif /* JTAG_H */