X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=src%2Fjtag%2Fjtag.h;h=b7ce094d6aeec0f17d6e9ffa639fc70dfa408eed;hb=a0647227439434c4a71470e336ec8715d43d0501;hp=e14d388e3530f2ac3253b00ae7da41b476b5346d;hpb=1812a3535c6a735c7014dd8dc4efc2849a566230;p=openocd.git diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h index e14d388e35..b7ce094d6a 100644 --- a/src/jtag/jtag.h +++ b/src/jtag/jtag.h @@ -195,6 +195,9 @@ typedef struct jtag_interface_s int (*register_commands)(struct command_context_s *cmd_ctx); int (*init)(void); int (*quit)(void); + /* returns JTAG maxium speed for KHz. 0=RTCK. The function returns + a failure if it can't support the KHz/RTCK. */ + int (*khz)(int khz, int *jtag_speed); } jtag_interface_t; @@ -222,6 +225,7 @@ extern enum tap_state end_state; extern enum tap_state cur_state; extern int jtag_speed; +extern int jtag_speed_post_reset; enum reset_types { @@ -237,11 +241,26 @@ enum reset_types extern enum reset_types jtag_reset_config; -/* JTAG subsystem */ +/* initialize JTAG chain using only a TLR reset. If init fails, + * try reset + init. + */ extern int jtag_init(struct command_context_s *cmd_ctx); +/* reset, then initialize JTAG chain */ +extern int jtag_init_reset(struct command_context_s *cmd_ctx); extern int jtag_register_commands(struct command_context_s *cmd_ctx); -/* JTAG interface, can be implemented with a software or hardware fifo */ +/* JTAG interface, can be implemented with a software or hardware fifo + * + * TAP_SD and TAP_SI are illegal end states. TAP_SD/SI as end states + * can be emulated by using a larger scan. + * + * Code that is relatively insensitive to the path(as long + * as it is JTAG compliant) taken through state machine can use + * endstate for jtag_add_xxx_scan(). Otherwise the pause state must be + * specified as end state and a subsequent jtag_add_pathmove() must + * be issued. + * + */ extern void jtag_add_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); extern int interface_jtag_add_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); extern void jtag_add_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); @@ -250,30 +269,24 @@ extern void jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum ta extern int interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); extern void jtag_add_plain_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); extern int interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); -/* execute a state transition within the JTAG standard, but the exact path - * path that is taken is undefined. Many implementations use precisely - * 7 clocks to perform a transition, but it could be more or less - * than that. - * - * The following assertions are made about certain common state moves: - * - * - A state move from Pause-[ID]R to Pause-[ID]R should always go through - * Update-[ID]R and Capture-[ID]R before returning to Pause-[ID]R, otherwise - * there's no way force a register update, if you can't go to Run-Test/Idle for - * some reason. +/* run a TAP_TLR reset. End state is TAP_TLR, regardless + * of start state. + */ +extern void jtag_add_tlr(); +extern int interface_jtag_add_tlr(); +/* Do not use jtag_add_pathmove() unless you need to, but do use it + * if you have to. * - * - A state move from Pause-[ID]R to Shift-[ID]R must not go through - * Update-[ID]R. + * DANGER! If the target is dependent upon a particular sequence + * of transitions for things to work correctly(e.g. as a workaround + * for an errata that contradicts the JTAG standard), then pathmove + * must be used, even if some jtag interfaces happen to use the + * desired path. Worse, the jtag interface used for testing a + * particular implementation, could happen to use the "desired" + * path when transitioning to/from end + * state. * - * - Run-Test/Idle must not be entered unless requested, because R-T/I may have - * side effects. - * - * NB! a jtag_add_statemove() to the current state is not - * a no-operation. - */ -extern void jtag_add_statemove(enum tap_state endstate); -extern int interface_jtag_add_statemove(enum tap_state endstate); -/* A list of unambigious single clock state transitions, not + * A list of unambigious single clock state transitions, not * all drivers can support this, but it is required for e.g. * XScale and Xilinx support * @@ -281,6 +294,15 @@ extern int interface_jtag_add_statemove(enum tap_state endstate); * * Note that the first on the list must be reachable * via a single transition from the current state. + * + * All drivers are required to implement jtag_add_pathmove(). + * However, if the pathmove sequence can not be precisely + * executed, an interface_jtag_add_pathmove() or jtag_execute_queue() + * must return an error. It is legal, but not recommended, that + * a driver returns an error in all cases for a pathmove if it + * can only implement a few transitions and therefore + * a partial implementation of pathmove would have little practical + * application. */ extern void jtag_add_pathmove(int num_states, enum tap_state *path); extern int interface_jtag_add_pathmove(int num_states, enum tap_state *path); @@ -290,16 +312,36 @@ extern int interface_jtag_add_pathmove(int num_states, enum tap_state *path); */ extern void jtag_add_runtest(int num_cycles, enum tap_state endstate); extern int interface_jtag_add_runtest(int num_cycles, enum tap_state endstate); -/* If it fails and one of the error messages below are returned, nothing is - * added to the queue and jtag_execute() won't return an error code. +/* A reset of the TAP state machine can be requested. + * + * Whether tms or trst reset is used depends on the capabilities of + * the target and jtag interface(reset_config command configures this). + * + * srst can driver a reset of the TAP state machine and vice + * versa * - * ERROR_JTAG_RESET_WOULD_ASSERT_TRST - * ERROR_JTAG_RESET_CANT_SRST + * Application code may need to examine value of jtag_reset_config + * to determine the proper codepath + * + * DANGER! Even though srst drives trst, trst might not be connected to + * the interface, and it might actually be *harmful* to assert trst in this case. + * + * This is why combinations such as "reset_config srst_only srst_pulls_trst" + * are supported. + * + * only req_tlr_or_trst and srst can have a transition for a + * call as the effects of transitioning both at the "same time" + * are undefined, but when srst_pulls_trst or vice versa, + * then trst & srst *must* be asserted together. + */ +extern void jtag_add_reset(int req_tlr_or_trst, int srst); +/* this drives the actual srst and trst pins. srst will always be 0 + * if jtag_reset_config & RESET_SRST_PULLS_TRST != 0 and ditto for + * trst. * - * All other error codes will result in jtag_execute_queue() returning - * an error. + * the higher level jtag_add_reset will invoke jtag_add_tlr() if + * approperiate */ -extern int jtag_add_reset(int trst, int srst); extern int interface_jtag_add_reset(int trst, int srst); extern void jtag_add_end_state(enum tap_state endstate); extern int interface_jtag_add_end_state(enum tap_state endstate); @@ -353,8 +395,6 @@ extern int jtag_verify_capture_ir; #define ERROR_JTAG_NOT_IMPLEMENTED (-102) #define ERROR_JTAG_TRST_ASSERTED (-103) #define ERROR_JTAG_QUEUE_FAILED (-104) -#define ERROR_JTAG_RESET_WOULD_ASSERT_TRST (-105) -#define ERROR_JTAG_RESET_CANT_SRST (-106) #define ERROR_JTAG_DEVICE_ERROR (-107)