Improve in-source documentation that was causing Doxygen warnings.
[fw/openocd] / 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
30 #ifdef _DEBUG_JTAG_IO_
31 #define DEBUG_JTAG_IO(expr ...)         LOG_DEBUG(expr)
32 #else
33 #define DEBUG_JTAG_IO(expr ...)
34 #endif
35
36 #ifndef DEBUG_JTAG_IOZ
37 #define DEBUG_JTAG_IOZ 64
38 #endif
39
40 /*-----<Macros>--------------------------------------------------*/
41
42 /**
43  * When given an array, compute its DIMension; in other words, the
44  * number of elements in the array
45  */
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  * Defines JTAG Test Access Port states.
55  *
56  * These definitions were gleaned from the ARM7TDMI-S Technical
57  * Reference Manual and validated against several other ARM core
58  * technical manuals.  tap_get_tms_path() is sensitive to this numbering
59  * and ordering of the TAP states; furthermore, some interfaces require
60  * specific numbers be used, as they are handed-off directly to their
61  * hardware implementations.
62  */
63 typedef enum tap_state
64 {
65 #if BUILD_ECOSBOARD
66         /* These are the old numbers. Leave as-is for now... */
67         TAP_RESET    = 0, TAP_IDLE = 8,
68         TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
69         TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
70         TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
71         TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,
72
73         TAP_NUM_STATES = 16, TAP_INVALID = -1,
74 #else
75         /* Proper ARM recommended numbers */
76         TAP_DREXIT2 = 0x0,
77         TAP_DREXIT1 = 0x1,
78         TAP_DRSHIFT = 0x2,
79         TAP_DRPAUSE = 0x3,
80         TAP_IRSELECT = 0x4,
81         TAP_DRUPDATE = 0x5,
82         TAP_DRCAPTURE = 0x6,
83         TAP_DRSELECT = 0x7,
84         TAP_IREXIT2 = 0x8,
85         TAP_IREXIT1 = 0x9,
86         TAP_IRSHIFT = 0xa,
87         TAP_IRPAUSE = 0xb,
88         TAP_IDLE = 0xc,
89         TAP_IRUPDATE = 0xd,
90         TAP_IRCAPTURE = 0xe,
91         TAP_RESET = 0x0f,
92
93         TAP_NUM_STATES = 0x10,
94
95         TAP_INVALID = -1,
96 #endif
97 } tap_state_t;
98
99 /**
100  * Function tap_state_name
101  * Returns a string suitable for display representing the JTAG tap_state
102  */
103 const char* tap_state_name(tap_state_t state);
104
105 /// The current TAP state of the pending JTAG command queue.
106 extern tap_state_t cmd_queue_cur_state;
107 /// The TAP state in which DR scans should end.
108 extern tap_state_t cmd_queue_end_state;
109
110 /**
111  * This structure defines a single scan field in the scan. It provides
112  * fields for the field's width and pointers to scan input and output
113  * values.
114  *
115  * In addition, this structure includes a value and mask that is used by
116  * jtag_add_dr_scan_check() to validate the value that was scanned out.
117  *
118  * The allocated, modified, and intmp fields are internal work space.
119  */
120 typedef struct scan_field_s
121 {
122         /// A pointer to the tap structure to which this field refers.
123         jtag_tap_t* tap;
124
125         /// The number of bits this field specifies (up to 32)
126         int num_bits;
127         /// A pointer to value to be scanned into the device
128         u8* out_value;
129         /// A pointer to a 32-bit memory location for data scanned out
130         u8* in_value;
131
132         /// The value used to check the data scanned out.
133         u8* check_value;
134         /// The mask to go with check_value
135         u8* check_mask;
136
137         /// in_value has been allocated for the queue
138         int allocated;
139         /// Indicates we modified the in_value.
140         int modified;
141         /// temporary storage for performing value checks synchronously
142         u8 intmp[4];
143 } scan_field_t;
144
145 #ifdef INCLUDE_JTAG_INTERFACE_H
146
147 /**
148  * The inferred type of a scan_command_s structure, indicating whether
149  * the command has the host scan in from the device, the host scan out
150  * to the device, or both.
151  */
152 enum scan_type {
153         /// From device to host,
154         SCAN_IN = 1,
155         /// From host to device,
156         SCAN_OUT = 2,
157         /// Full-duplex scan.
158         SCAN_IO = 3
159 };
160
161 /**
162  * The scan_command provide a means of encapsulating a set of scan_field_s
163  * structures that should be scanned in/out to the device.
164  */
165 typedef struct scan_command_s
166 {
167         /// instruction/not data scan
168         bool ir_scan;
169         /// number of fields in *fields array
170         int num_fields;
171         /// pointer to an array of data scan fields
172         scan_field_t* fields;
173         /// state in which JTAG commands should finish
174         tap_state_t end_state;
175 } scan_command_t;
176
177 typedef struct statemove_command_s
178 {
179         /// state in which JTAG commands should finish
180         tap_state_t end_state;
181 } statemove_command_t;
182
183 typedef struct pathmove_command_s
184 {
185         /// number of states in *path
186         int num_states;
187         /// states that have to be passed
188         tap_state_t* path;
189 } pathmove_command_t;
190
191 typedef struct runtest_command_s
192 {
193         /// number of cycles to spend in Run-Test/Idle state
194         int num_cycles;
195         /// state in which JTAG commands should finish
196         tap_state_t end_state;
197 } runtest_command_t;
198
199
200 typedef struct stableclocks_command_s
201 {
202         /// number of clock cycles that should be sent
203         int num_cycles;
204 } stableclocks_command_t;
205
206
207 typedef struct reset_command_s
208 {
209         /// Set TRST output: 0=deassert, 1=assert, -1=no change
210         int trst;
211         /// Set SRST output: 0=deassert, 1=assert, -1=no change
212         int srst;
213 } reset_command_t;
214
215 typedef struct end_state_command_s
216 {
217         /// state in which JTAG commands should finish
218         tap_state_t end_state;
219 } end_state_command_t;
220
221 typedef struct sleep_command_s
222 {
223         /// number of microseconds to sleep
224         u32 us;
225 } sleep_command_t;
226
227 /**
228  * Defines a container type that hold a pointer to a JTAG command
229  * structure of any defined type.
230  */
231 typedef union jtag_command_container_u
232 {
233         scan_command_t*         scan;
234         statemove_command_t*    statemove;
235         pathmove_command_t*     pathmove;
236         runtest_command_t*      runtest;
237         stableclocks_command_t* stableclocks;
238         reset_command_t*        reset;
239         end_state_command_t*    end_state;
240         sleep_command_t* sleep;
241 } jtag_command_container_t;
242
243 /**
244  * The type of the @c jtag_command_container_u contained by a
245  * @c jtag_command_s structure.
246  */
247 enum jtag_command_type {
248         JTAG_SCAN         = 1,
249         JTAG_STATEMOVE    = 2,
250         JTAG_RUNTEST      = 3,
251         JTAG_RESET        = 4,
252         JTAG_PATHMOVE     = 6,
253         JTAG_SLEEP        = 7,
254         JTAG_STABLECLOCKS = 8
255 };
256
257 typedef struct jtag_command_s
258 {
259         jtag_command_container_t cmd;
260         enum jtag_command_type   type;
261         struct jtag_command_s*   next;
262 } jtag_command_t;
263
264 /// The current queue of jtag_command_s structures.
265 extern jtag_command_t* jtag_command_queue;
266
267 extern void* cmd_queue_alloc(size_t size);
268 extern void cmd_queue_free(void);
269
270 extern void jtag_queue_command(jtag_command_t *cmd);
271 extern void jtag_command_queue_reset(void);
272
273 #endif // INCLUDE_JTAG_INTERFACE_H
274
275 typedef struct jtag_tap_event_action_s jtag_tap_event_action_t;
276
277 /* this is really: typedef jtag_tap_t */
278 /* But - the typedef is done in "types.h" */
279 /* due to "forward decloration reasons" */
280 struct jtag_tap_s
281 {
282         const char* chip;
283         const char* tapname;
284         const char* dotted_name;
285         int abs_chain_position;
286         /// Is this TAP enabled?
287         int enabled;
288         int ir_length; /**< size of instruction register */
289         u32 ir_capture_value;
290         u8* expected; /**< Capture-IR expected value */
291         u32 ir_capture_mask;
292         u8* expected_mask; /**< Capture-IR expected mask */
293         u32 idcode;
294         /**< device identification code */
295
296         /// Array of expected identification codes */
297         u32* expected_ids;
298         /// Number of expected identification codes
299         u8 expected_ids_cnt;
300
301         /// current instruction
302         u8* cur_instr;
303         /// Bypass register selected
304         int bypass;
305
306         jtag_tap_event_action_t *event_action;
307
308         jtag_tap_t* next_tap;
309 };
310 extern jtag_tap_t* jtag_AllTaps(void);
311 extern jtag_tap_t* jtag_TapByPosition(int n);
312 extern jtag_tap_t* jtag_TapByString(const char* dotted_name);
313 extern jtag_tap_t* jtag_TapByJimObj(Jim_Interp* interp, Jim_Obj* obj);
314 extern jtag_tap_t* jtag_TapByAbsPosition(int abs_position);
315 extern int jtag_NumEnabledTaps(void);
316 extern int jtag_NumTotalTaps(void);
317
318 static __inline__ jtag_tap_t* jtag_NextEnabledTap(jtag_tap_t* p)
319 {
320         if (p == NULL)
321         {
322                 /* start at the head of list */
323                 p = jtag_AllTaps();
324         }
325         else
326         {
327                 /* start *after* this one */
328                 p = p->next_tap;
329         }
330         while (p)
331         {
332                 if (p->enabled)
333                 {
334                         break;
335                 }
336                 else
337                 {
338                         p = p->next_tap;
339                 }
340         }
341
342         return p;
343 }
344
345
346 enum reset_line_mode {
347         LINE_OPEN_DRAIN = 0x0,
348         LINE_PUSH_PULL  = 0x1,
349 };
350
351 enum jtag_event {
352         JTAG_TRST_ASSERTED
353 };
354
355 extern char* jtag_event_strings[];
356
357 enum jtag_tap_event {
358         JTAG_TAP_EVENT_ENABLE,
359         JTAG_TAP_EVENT_DISABLE
360 };
361
362 extern const Jim_Nvp nvp_jtag_tap_event[];
363
364 struct jtag_tap_event_action_s
365 {
366         enum jtag_tap_event      event;
367         Jim_Obj*                 body;
368         jtag_tap_event_action_t* next;
369 };
370
371 extern int jtag_trst;
372 extern int jtag_srst;
373
374 typedef struct jtag_event_callback_s
375 {
376         int (*callback)(enum jtag_event event, void* priv);
377         void*                         priv;
378         struct jtag_event_callback_s* next;
379 } jtag_event_callback_t;
380
381 extern jtag_event_callback_t* jtag_event_callbacks;
382
383 extern int jtag_speed;
384 extern int jtag_speed_post_reset;
385
386 enum reset_types {
387         RESET_NONE            = 0x0,
388         RESET_HAS_TRST        = 0x1,
389         RESET_HAS_SRST        = 0x2,
390         RESET_TRST_AND_SRST   = 0x3,
391         RESET_SRST_PULLS_TRST = 0x4,
392         RESET_TRST_PULLS_SRST = 0x8,
393         RESET_TRST_OPEN_DRAIN = 0x10,
394         RESET_SRST_PUSH_PULL  = 0x20,
395 };
396
397 extern enum reset_types jtag_reset_config;
398
399 /**
400  * Initialize interface upon startup.  Return a successful no-op upon
401  * subsequent invocations.
402  */
403 extern int  jtag_interface_init(struct command_context_s* cmd_ctx);
404
405 /// Shutdown the JTAG interface upon program exit.
406 extern int  jtag_interface_quit(void);
407
408 /**
409  * Initialize JTAG chain using only a RESET reset. If init fails,
410  * try reset + init.
411  */
412 extern int  jtag_init(struct command_context_s* cmd_ctx);
413
414 /// reset, then initialize JTAG chain
415 extern int  jtag_init_reset(struct command_context_s* cmd_ctx);
416 extern int  jtag_register_commands(struct command_context_s* cmd_ctx);
417
418 /**
419  * @file
420  * The JTAG interface can be implemented with a software or hardware fifo.
421  *
422  * TAP_DRSHIFT and TAP_IRSHIFT are illegal end states; however,
423  * TAP_DRSHIFT/IRSHIFT can be emulated as end states, by using longer
424  * scans.
425  *
426  * Code that is relatively insensitive to the path taken through state
427  * machine (as long as it is JTAG compliant) can use @a endstate for
428  * jtag_add_xxx_scan(). Otherwise, the pause state must be specified as
429  * end state and a subsequent jtag_add_pathmove() must be issued.
430  */
431
432 extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate);
433 /**
434  * The same as jtag_add_ir_scan except no verification is performed out
435  * the output values.
436  */
437 extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state);
438
439
440 /**
441  * Set in_value to point to 32 bits of memory to scan into. This
442  * function is a way to handle the case of synchronous and asynchronous
443  * JTAG queues.
444  *
445  * In the event of an asynchronous queue execution the queue buffer
446  * allocation method is used, for the synchronous case the temporary 32
447  * bits come from the input field itself.
448  */
449 extern void jtag_alloc_in_value32(scan_field_t *field);
450
451 extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
452 /// A version of jtag_add_dr_scan() that uses the check_value/mask fields
453 extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate);
454 extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
455 extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate);
456
457
458 /**
459  * Defines a simple JTAG callback that can allow conversions on data
460  * scanned in from an interface.
461  *
462  * This callback should only be used for conversion that cannot fail.
463  * For conversion types or checks that can fail, use the more complete
464  * variant: jtag_callback_t.
465  */
466 typedef void (*jtag_callback1_t)(u8 *in);
467
468 /// A simpler version of jtag_add_callback4().
469 extern void jtag_add_callback(jtag_callback1_t, u8 *in);
470
471
472 /**
473  * Defines the type of data passed to the jtag_callback_t interface.
474  * The underlying type must allow storing an @c int or pointer type.
475  */
476 typedef intptr_t jtag_callback_data_t;
477
478 /**
479  * Defines the interface of the JTAG callback mechanism.
480  *
481  * @param in the pointer to the data clocked in
482  * @param data1 An integer big enough to use as an @c int or a pointer.
483  * @param data2 An integer big enough to use as an @c int or a pointer.
484  * @param data3 An integer big enough to use as an @c int or a pointer.
485  * @returns an error code
486  */
487 typedef int (*jtag_callback_t)(u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3);
488
489
490 /**
491  * This callback can be executed immediately the queue has been flushed.
492  *
493  * The JTAG queue can be executed synchronously or asynchronously.
494  * Typically for USB, the queue is executed asynchronously.  For
495  * low-latency interfaces, the queue may be executed synchronously.
496  *
497  * The callback mechanism is very general and does not make many
498  * assumptions about what the callback does or what its arguments are.
499  * These callbacks are typically executed *after* the *entire* JTAG
500  * queue has been executed for e.g. USB interfaces, and they are
501  * guaranteeed to be invoked in the order that they were queued.
502  *
503  * If the execution of the queue fails before the callbacks, then --
504  * depending on driver implementation -- the callbacks may or may not be
505  * invoked.  @todo Can we make this behavior consistent?
506  *
507  * The strange name is due to C's lack of overloading using function
508  * arguments.
509  *
510  * @param f The callback function to add.
511  * @param in Typically used to point to the data to operate on.
512  * Frequently this will be the data clocked in during a shift operation.
513  * @param data1 An integer big enough to use as an @c int or a pointer.
514  * @param data2 An integer big enough to use as an @c int or a pointer.
515  * @param data3 An integer big enough to use as an @c int or a pointer.
516  *
517  */
518 extern void jtag_add_callback4(jtag_callback_t f, u8 *in,
519                 jtag_callback_data_t data1, jtag_callback_data_t data2,
520                 jtag_callback_data_t data3);
521
522
523 /**
524  * Run a TAP_RESET reset where the end state is TAP_RESET,
525  * regardless of the start state.
526  */
527 extern void jtag_add_tlr(void);
528
529 /**
530  * Application code *must* assume that interfaces will
531  * implement transitions between states with different
532  * paths and path lengths through the state diagram. The
533  * path will vary across interface and also across versions
534  * of the same interface over time. Even if the OpenOCD code
535  * is unchanged, the actual path taken may vary over time
536  * and versions of interface firmware or PCB revisions.
537  *
538  * Use jtag_add_pathmove() when specific transition sequences
539  * are required.
540  *
541  * Do not use jtag_add_pathmove() unless you need to, but do use it
542  * if you have to.
543  *
544  * DANGER! If the target is dependent upon a particular sequence
545  * of transitions for things to work correctly(e.g. as a workaround
546  * for an errata that contradicts the JTAG standard), then pathmove
547  * must be used, even if some jtag interfaces happen to use the
548  * desired path. Worse, the jtag interface used for testing a
549  * particular implementation, could happen to use the "desired"
550  * path when transitioning to/from end
551  * state.
552  *
553  * A list of unambigious single clock state transitions, not
554  * all drivers can support this, but it is required for e.g.
555  * XScale and Xilinx support
556  *
557  * Note! TAP_RESET must not be used in the path!
558  *
559  * Note that the first on the list must be reachable
560  * via a single transition from the current state.
561  *
562  * All drivers are required to implement jtag_add_pathmove().
563  * However, if the pathmove sequence can not be precisely
564  * executed, an interface_jtag_add_pathmove() or jtag_execute_queue()
565  * must return an error. It is legal, but not recommended, that
566  * a driver returns an error in all cases for a pathmove if it
567  * can only implement a few transitions and therefore
568  * a partial implementation of pathmove would have little practical
569  * application.
570  */
571 extern void jtag_add_pathmove(int num_states, const tap_state_t* path);
572
573 /**
574  * Goes to TAP_IDLE (if we're not already there), cycle
575  * precisely num_cycles in the TAP_IDLE state, after which move
576  * to @a endstate (unless it is also TAP_IDLE).
577  *
578  * @param num_cycles Number of cycles in TAP_IDLE state.  This argument
579  *      may be 0, in which case this routine will navigate to @a endstate
580  *      via TAP_IDLE.
581  * @param endstate The final state.
582  */
583 extern void jtag_add_runtest(int num_cycles, tap_state_t endstate);
584
585 /**
586  * A reset of the TAP state machine can be requested.
587  *
588  * Whether tms or trst reset is used depends on the capabilities of
589  * the target and jtag interface(reset_config  command configures this).
590  *
591  * srst can driver a reset of the TAP state machine and vice
592  * versa
593  *
594  * Application code may need to examine value of jtag_reset_config
595  * to determine the proper codepath
596  *
597  * DANGER! Even though srst drives trst, trst might not be connected to
598  * the interface, and it might actually be *harmful* to assert trst in this case.
599  *
600  * This is why combinations such as "reset_config srst_only srst_pulls_trst"
601  * are supported.
602  *
603  * only req_tlr_or_trst and srst can have a transition for a
604  * call as the effects of transitioning both at the "same time"
605  * are undefined, but when srst_pulls_trst or vice versa,
606  * then trst & srst *must* be asserted together.
607  */
608 extern void jtag_add_reset(int req_tlr_or_trst, int srst);
609
610 extern void jtag_add_end_state(tap_state_t endstate);
611 extern void jtag_add_sleep(u32 us);
612
613
614 /**
615  * Function jtag_add_stable_clocks
616  * first checks that the state in which the clocks are to be issued is
617  * stable, then queues up clock_count clocks for transmission.
618  */
619 void jtag_add_clocks(int num_cycles);
620
621
622 /**
623  * For software FIFO implementations, the queued commands can be executed
624  * during this call or earlier. A sw queue might decide to push out
625  * some of the jtag_add_xxx() operations once the queue is "big enough".
626  *
627  * This fn will return an error code if any of the prior jtag_add_xxx()
628  * calls caused a failure, e.g. check failure. Note that it does not
629  * matter if the operation was executed *before* jtag_execute_queue(),
630  * jtag_execute_queue() will still return an error code.
631  *
632  * All jtag_add_xxx() calls that have in_handler!=NULL will have been
633  * executed when this fn returns, but if what has been queued only
634  * clocks data out, without reading anything back, then JTAG could
635  * be running *after* jtag_execute_queue() returns. The API does
636  * not define a way to flush a hw FIFO that runs *after*
637  * jtag_execute_queue() returns.
638  *
639  * jtag_add_xxx() commands can either be executed immediately or
640  * at some time between the jtag_add_xxx() fn call and jtag_execute_queue().
641  */
642 extern int jtag_execute_queue(void);
643
644 /* same as jtag_execute_queue() but does not clear the error flag */
645 extern void jtag_execute_queue_noclear(void);
646
647 /**
648  * The jtag_error variable is set when an error occurs while executing
649  * the queue.
650  *
651  * This flag can also be set from application code, if an error happens
652  * during processing that should be reported during jtag_execute_queue().
653  *
654  * It is cleared by jtag_execute_queue().
655  */
656 extern int jtag_error;
657
658 static __inline__ void jtag_set_error(int error)
659 {
660         if ((error==ERROR_OK)||(jtag_error!=ERROR_OK))
661         {
662                 /* keep first error */
663                 return;
664         }
665         jtag_error=error;
666 }
667
668
669
670 /* can be implemented by hw+sw */
671 extern int jtag_power_dropout(int* dropout);
672 extern int jtag_srst_asserted(int* srst_asserted);
673
674 /* JTAG support functions */
675
676 /**
677  * Execute jtag queue and check value with an optional mask.
678  * @param field Pointer to scan field.
679  * @param value Pointer to scan value.
680  * @param mask Pointer to scan mask; may be NULL.
681  * @returns Nothing, but calls jtag_set_error() on any error.
682  */
683 extern void jtag_check_value_mask(scan_field_t *field, u8 *value, u8 *mask);
684
685 #ifdef INCLUDE_JTAG_INTERFACE_H
686 extern enum scan_type jtag_scan_type(const scan_command_t* cmd);
687 extern int jtag_scan_size(const scan_command_t* cmd);
688 extern int jtag_read_buffer(u8* buffer, const scan_command_t* cmd);
689 extern int jtag_build_buffer(const scan_command_t* cmd, u8** buffer);
690 #endif // INCLUDE_JTAG_INTERFACE_H
691
692 extern void jtag_sleep(u32 us);
693 extern int jtag_call_event_callbacks(enum jtag_event event);
694 extern int jtag_register_event_callback(int (* callback)(enum jtag_event event, void* priv), void* priv);
695
696 extern int jtag_verify_capture_ir;
697
698 void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e);
699
700 /*
701  * The JTAG subsystem defines a number of error codes,
702  * using codes between -100 and -199.
703  */
704 #define ERROR_JTAG_INIT_FAILED       (-100)
705 #define ERROR_JTAG_INVALID_INTERFACE (-101)
706 #define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
707 #define ERROR_JTAG_TRST_ASSERTED     (-103)
708 #define ERROR_JTAG_QUEUE_FAILED      (-104)
709 #define ERROR_JTAG_NOT_STABLE_STATE  (-105)
710 #define ERROR_JTAG_DEVICE_ERROR      (-107)
711
712 /**
713  * jtag_add_dr_out() is a version of jtag_add_dr_scan() which
714  * only scans data out. It operates on 32 bit integers instead
715  * of 8 bit, which makes it a better impedance match with
716  * the calling code which often operate on 32 bit integers.
717  *
718  * Current or end_state can not be TAP_RESET. end_state can be TAP_INVALID
719  *
720  * num_bits[i] is the number of bits to clock out from value[i] LSB first.
721  *
722  * If the device is in bypass, then that is an error condition in
723  * the caller code that is not detected by this fn, whereas
724  * jtag_add_dr_scan() does detect it. Similarly if the device is not in
725  * bypass, data must be passed to it.
726  *
727  * If anything fails, then jtag_error will be set and jtag_execute() will
728  * return an error. There is no way to determine if there was a failure
729  * during this function call.
730  *
731  * This is an inline fn to speed up embedded hosts. Also note that
732  * interface_jtag_add_dr_out() can be a *small* inline function for
733  * embedded hosts.
734  *
735  * There is no jtag_add_dr_outin() version of this fn that also allows
736  * clocking data back in. Patches gladly accepted!
737  */
738 extern void jtag_add_dr_out(jtag_tap_t* tap,
739                 int num_fields, const int* num_bits, const u32* value,
740                 tap_state_t end_state);
741
742
743 /**
744  * jtag_add_statemove() moves from the current state to @a goal_state.
745  *
746  * This function was originally designed to handle the XSTATE command
747  * from the XSVF specification.
748  *
749  * @param goal_state The final TAP state.
750  * @return ERROR_OK on success, or an error code on failure.
751  */
752 extern int jtag_add_statemove(tap_state_t goal_state);
753
754 #endif /* JTAG_H */