X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=src%2Fjtag%2Fjtag.h;h=19329447735806bfc481d76a1e616d871344f102;hp=0e9a9302eef70236f0a67b5bf382921b3b08dd88;hb=eabb49b570290f2bcda80a0c591431b7ef240d43;hpb=7de7bc80fcca79e72c45040dc0ff3467e4b10dea diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h index 0e9a9302ee..1932944773 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; @@ -242,7 +245,18 @@ extern enum reset_types jtag_reset_config; extern int jtag_init(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); @@ -251,30 +265,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 * @@ -282,6 +290,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); @@ -291,16 +308,32 @@ 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. + * + */ +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); @@ -354,8 +387,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)