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

Linking to existing account procedure

If you already have an account and want to add another login method you MUST first sign in with your existing account and then change URL to read https://review.openocd.org/login/?link to get to this page again but this time it'll work for linking. Thank you.

SSH host keys fingerprints

1024 SHA256:YKx8b7u5ZWdcbp7/4AeXNaqElP49m6QrwfXaqQGJAOk gerrit-code-review@openocd.zylin.com (DSA)
384 SHA256:jHIbSQa4REvwCFG4cq5LBlBLxmxSqelQPem/EXIrxjk gerrit-code-review@openocd.org (ECDSA)
521 SHA256:UAOPYkU9Fjtcao0Ul/Rrlnj/OsQvt+pgdYSZ4jOYdgs gerrit-code-review@openocd.org (ECDSA)
256 SHA256:A13M5QlnozFOvTllybRZH6vm7iSt0XLxbA48yfc2yfY gerrit-code-review@openocd.org (ECDSA)
256 SHA256:spYMBqEYoAOtK7yZBrcwE8ZpYt6b68Cfh9yEVetvbXg gerrit-code-review@openocd.org (ED25519)
+--[ED25519 256]--+
|=..              |
|+o..   .         |
|*.o   . .        |
|+B . . .         |
|Bo. = o S        |
|Oo.+ + =         |
|oB=.* = . o      |
| =+=.+   + E     |
|. .=o   . o      |
+----[SHA256]-----+
2048 SHA256:0Onrb7/PHjpo6iVZ7xQX2riKN83FJ3KGU0TvI0TaFG4 gerrit-code-review@openocd.zylin.com (RSA)