X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=src%2Fjtag%2Fjtag.h;h=b7ce094d6aeec0f17d6e9ffa639fc70dfa408eed;hb=a0647227439434c4a71470e336ec8715d43d0501;hp=df1ca08acf836902fb5d9aa27af864757c4b77fa;hpb=6be6ba715144a316c810698def4a7cd3e9280c8d;p=openocd.git diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h index df1ca08acf..b7ce094d6a 100644 --- a/src/jtag/jtag.h +++ b/src/jtag/jtag.h @@ -195,15 +195,15 @@ 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; enum jtag_event { - JTAG_SRST_ASSERTED, - JTAG_TRST_ASSERTED, - JTAG_SRST_RELEASED, - JTAG_TRST_RELEASED, + JTAG_TRST_ASSERTED }; extern char* jtag_event_strings[]; @@ -225,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 { @@ -240,43 +241,52 @@ 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 */ -extern int jtag_add_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); +/* 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 int jtag_add_dr_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); extern int interface_jtag_add_dr_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); -extern int jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); +extern void jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); extern int interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t *fields, enum tap_state endstate); -extern int jtag_add_plain_dr_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 int 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 * @@ -284,20 +294,58 @@ 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 int jtag_add_pathmove(int num_states, enum tap_state *path); +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); /* go to TAP_RTI, if we're not already there and cycle * precisely num_cycles in the TAP_RTI after which move * to the end state, if it is != TAP_RTI */ -extern int jtag_add_runtest(int num_cycles, enum tap_state endstate); +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); -extern int jtag_add_reset(int trst, int srst); +/* 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 + * + * 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. + * + * the higher level jtag_add_reset will invoke jtag_add_tlr() if + * approperiate + */ extern int interface_jtag_add_reset(int trst, int srst); -extern int jtag_add_end_state(enum tap_state endstate); +extern void jtag_add_end_state(enum tap_state endstate); extern int interface_jtag_add_end_state(enum tap_state endstate); -extern int jtag_add_sleep(u32 us); +extern void jtag_add_sleep(u32 us); extern int interface_jtag_add_sleep(u32 us); @@ -339,7 +387,6 @@ extern int jtag_register_event_callback(int (*callback)(enum jtag_event event, v extern int jtag_verify_capture_ir; - /* error codes * JTAG subsystem uses codes between -100 and -199 */ @@ -348,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)