X-Git-Url: https://review.openocd.org/gitweb?a=blobdiff_plain;f=src%2Fjtag%2Fjtag.h;h=a2755022c634675283ce2f27bf17fa619c644b88;hb=def4ed3b2ad6ef039a996b6b680096f15f46da81;hp=ccd17ffea93195ad2cf009752d84950aebb8c7bc;hpb=c860600c6a468f69993de8defe373b85178ff9eb;p=openocd.git diff --git a/src/jtag/jtag.h b/src/jtag/jtag.h index ccd17ffea9..a2755022c6 100644 --- a/src/jtag/jtag.h +++ b/src/jtag/jtag.h @@ -105,164 +105,10 @@ typedef struct tap_transition_s //extern tap_transition_t tap_transitions[16]; /* describe the TAP state diagram */ -/*------------------------------------------------*/ - -/* The "Cable Helper API" is what the cable drivers can use to help implement - * their "Cable API". So a Cable Helper API is a set of helper functions used by - * cable drivers, and this is different from a Cable API. A "Cable API" is what - * higher level code used to talk to a cable. - */ - - -/** implementation of wrapper function tap_set_state() */ -void tap_set_state_impl(tap_state_t new_state); - -/** - * Function tap_set_state - * sets the state of a "state follower" which tracks the state of the TAPs connected to the - * cable. The state follower is hopefully always in the same state as the actual - * TAPs in the jtag chain, and will be so if there are no bugs in the tracking logic within that - * cable driver. All the cable drivers call this function to indicate the state they think - * the TAPs attached to their cables are in. Because this function can also log transitions, - * it will be helpful to call this function with every transition that the TAPs being manipulated - * are expected to traverse, not just end points of a multi-step state path. - * @param new_state is the state we think the TAPs are currently in or are about to enter. - */ -#if defined(_DEBUG_JTAG_IO_) -#define tap_set_state(new_state) \ - do { \ - LOG_DEBUG( "tap_set_state(%s)", tap_state_name(new_state) ); \ - tap_set_state_impl(new_state); \ - } while (0) -#else -static inline void tap_set_state(tap_state_t new_state) -{ - tap_set_state_impl(new_state); -} - -#endif - -/** - * Function tap_get_state - * gets the state of the "state follower" which tracks the state of the TAPs connected to - * the cable. - * @see tap_set_state - * @return tap_state_t - The state the TAPs are in now. - */ -tap_state_t tap_get_state(void); - -/** - * Function tap_set_end_state - * sets the state of an "end state follower" which tracks the state that any cable driver - * thinks will be the end (resultant) state of the current TAP SIR or SDR operation. At completion - * of that TAP operation this value is copied into the state follower via tap_set_state(). - * @param new_end_state is that state the TAPs should enter at completion of a pending TAP operation. - */ -void tap_set_end_state(tap_state_t new_end_state); - -/** - * Function tap_get_end_state - * @see tap_set_end_state - * @return tap_state_t - The state the TAPs should be in at completion of the current TAP operation. - */ -tap_state_t tap_get_end_state(void); - -/** - * Function tap_get_tms_path - * returns a 7 bit long "bit sequence" indicating what has to be done with TMS - * during a sequence of seven TAP clock cycles in order to get from - * state \a "from" to state \a "to". - * @param from is the starting state - * @param to is the resultant or final state - * @return int - a 7 bit sequence, with the first bit in the sequence at bit 0. - */ -int tap_get_tms_path(tap_state_t from, tap_state_t to); - - -/** - * Function int tap_get_tms_path_len - * returns the total number of bits that represents a TMS path - * transition as given by the function tap_get_tms_path(). - * - * For at least one interface (JLink) it's not OK to simply "pad" TMS sequences - * to fit a whole byte. (I suspect this is a general TAP problem within OOCD.) - * Padding TMS causes all manner of instability that's not easily - * discovered. Using this routine we can apply EXACTLY the state transitions - * required to make something work - no more - no less. - * - * @param from is the starting state - * @param to is the resultant or final state - * @return int - the total number of bits in a transition. - */ -int tap_get_tms_path_len(tap_state_t from, tap_state_t to); - - -/** - * Function tap_move_ndx - * when given a stable state, returns an index from 0-5. The index corresponds to a - * sequence of stable states which are given in this order:

- * { TAP_RESET, TAP_IDLE, TAP_DRSHIFT, TAP_DRPAUSE, TAP_IRSHIFT, TAP_IRPAUSE } - *

- * This sequence corresponds to look up tables which are used in some of the - * cable drivers. - * @param astate is the stable state to find in the sequence. If a non stable - * state is passed, this may cause the program to output an error message - * and terminate. - * @return int - the array (or sequence) index as described above - */ -int tap_move_ndx(tap_state_t astate); - -/** - * Function tap_is_state_stable - * returns true if the \a astate is stable. - */ -bool tap_is_state_stable(tap_state_t astate); - -/** - * Function tap_state_transition - * takes a current TAP state and returns the next state according to the tms value. - * @param current_state is the state of a TAP currently. - * @param tms is either zero or non-zero, just like a real TMS line in a jtag interface. - * @return tap_state_t - the next state a TAP would enter. - */ -tap_state_t tap_state_transition(tap_state_t current_state, bool tms); - -/** - * Function tap_state_name - * Returns a string suitable for display representing the JTAG tap_state - */ -const char* tap_state_name(tap_state_t state); - -#ifdef _DEBUG_JTAG_IO_ -/** - * @brief Prints verbose TAP state transitions for the given TMS/TDI buffers. - * @param tms_buf must points to a buffer containing the TMS bitstream. - * @param tdi_buf must points to a buffer containing the TDI bitstream. - * @param tap_len must specify the length of the TMS/TDI bitstreams. - * @param start_tap_state must specify the current TAP state. - * @returns the final TAP state; pass as @a start_tap_state in following call. - */ -tap_state_t jtag_debug_state_machine(const void *tms_buf, const void *tdi_buf, - unsigned tap_len, tap_state_t start_tap_state); -#else -static inline tap_state_t jtag_debug_state_machine(const void *tms_buf, - const void *tdi_buf, unsigned tap_len, tap_state_t start_tap_state) -{ - return start_tap_state; -} -#endif // _DEBUG_JTAG_IO_ - -/*-----------------------------------------------*/ - extern tap_state_t cmd_queue_end_state; /* finish DR scans in dr_end_state */ extern tap_state_t cmd_queue_cur_state; /* current TAP state */ -typedef void* error_handler_t; /* Later on we can delete error_handler_t, but keep it for now to make patches more readable */ - -struct scan_field_s; -typedef int (*in_handler_t)(u8* in_value, void* priv, struct scan_field_s* field); - typedef struct scan_field_s { jtag_tap_t* tap; /* tap pointer this instruction refers to */ @@ -280,6 +126,8 @@ typedef struct scan_field_s u8 intmp[4]; /* temporary storage for checking synchronously */ } scan_field_t; +#ifdef INCLUDE_JTAG_INTERFACE_H + enum scan_type { /* IN: from device to host, OUT: from host to device */ SCAN_IN = 1, SCAN_OUT = 2, SCAN_IO = 3 @@ -287,7 +135,7 @@ enum scan_type { typedef struct scan_command_s { - int ir_scan; /* instruction/not data scan */ + bool ir_scan; /* instruction/not data scan */ int num_fields; /* number of fields in *fields array */ scan_field_t* fields; /* pointer to an array of data scan fields */ tap_state_t end_state; /* TAP state in which JTAG commands should finish */ @@ -350,7 +198,6 @@ enum jtag_command_type { JTAG_STATEMOVE = 2, JTAG_RUNTEST = 3, JTAG_RESET = 4, - JTAG_END_STATE = 5, JTAG_PATHMOVE = 6, JTAG_SLEEP = 7, JTAG_STABLECLOCKS = 8 @@ -365,6 +212,16 @@ typedef struct jtag_command_s extern jtag_command_t* jtag_command_queue; +extern void* cmd_queue_alloc(size_t size); +extern void cmd_queue_free(void); + +extern void jtag_queue_command(jtag_command_t *cmd); +extern void jtag_command_queue_reset(void); + +#include "interface.h" + +#endif // INCLUDE_JTAG_INTERFACE_H + /* forward declaration */ typedef struct jtag_tap_event_action_s jtag_tap_event_action_t; @@ -434,55 +291,6 @@ enum reset_line_mode { LINE_PUSH_PULL = 0x1, }; -typedef struct jtag_interface_s -{ - char* name; - - /* queued command execution - */ - int (*execute_queue)(void); - - /* interface initalization - */ - int (*speed)(int speed); - 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. - * - * WARNING!!!! if RTCK is *slow* then think carefully about - * whether you actually want to support this in the driver. - * Many target scripts are written to handle the absence of RTCK - * and use a fallback kHz TCK. - */ - int (*khz)(int khz, int* jtag_speed); - - /* returns the KHz for the provided JTAG speed. 0=RTCK. The function returns - * a failure if it can't support the KHz/RTCK. */ - int (*speed_div)(int speed, int* khz); - - /* Read and clear the power dropout flag. Note that a power dropout - * can be transitionary, easily much less than a ms. - * - * So to find out if the power is *currently* on, you must invoke - * this method twice. Once to clear the power dropout flag and a - * second time to read the current state. - * - * Currently the default implementation is never to detect power dropout. - */ - int (*power_dropout)(int* power_dropout); - - /* Read and clear the srst asserted detection flag. - * - * NB!!!! like power_dropout this does *not* read the current - * state. srst assertion is transitionary and *can* be much - * less than 1ms. - */ - int (*srst_asserted)(int* srst_asserted); -} jtag_interface_t; - enum jtag_event { JTAG_TRST_ASSERTED }; @@ -515,8 +323,6 @@ typedef struct jtag_event_callback_s extern jtag_event_callback_t* jtag_event_callbacks; -extern jtag_interface_t* jtag; /* global pointer to configured JTAG interface */ - extern int jtag_speed; extern int jtag_speed_post_reset; @@ -538,6 +344,9 @@ extern enum reset_types jtag_reset_config; */ extern int jtag_interface_init(struct command_context_s* cmd_ctx); +/// Shutdown the JTAG interface upon program exit. +extern int jtag_interface_quit(void); + /* initialize JTAG chain using only a RESET reset. If init fails, * try reset + init. */ @@ -561,9 +370,8 @@ extern int jtag_register_commands(struct command_context_s* cmd_ctx); */ extern void jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); /* same as jtag_add_ir_scan except no verify is performed */ -extern void jtag_add_ir_scan_noverify(int num_fields, scan_field_t *fields, tap_state_t state); -extern int interface_jtag_add_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern void jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); +extern void jtag_add_ir_scan_noverify(int num_fields, const scan_field_t *fields, tap_state_t state); +extern void jtag_add_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); /* set in_value to point to 32 bits of memory to scan into. This function * is a way to handle the case of synchronous and asynchronous @@ -573,25 +381,12 @@ extern void jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t e * allocation method is used, for the synchronous case the temporary 32 bits come * from the input field itself. */ - -#ifndef HAVE_JTAG_MINIDRIVER_H extern void jtag_alloc_in_value32(scan_field_t *field); -#else -static __inline__ void jtag_alloc_in_value32(scan_field_t *field) -{ - field->in_value=field->intmp; -} -#endif - - /* This version of jtag_add_dr_scan() uses the check_value/mask fields */ extern void jtag_add_dr_scan_check(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern int interface_jtag_add_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern void jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern int interface_jtag_add_plain_ir_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern void jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); -extern int interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t* fields, tap_state_t endstate); +extern void jtag_add_plain_ir_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); +extern void jtag_add_plain_dr_scan(int num_fields, const scan_field_t* fields, tap_state_t endstate); /* Simplest/typical callback - do some conversion on the data clocked in. @@ -600,12 +395,8 @@ extern int interface_jtag_add_plain_dr_scan(int num_fields, scan_field_t* field * fail, use the jtag_callback_t variant */ typedef void (*jtag_callback1_t)(u8 *in); -#ifndef HAVE_JTAG_MINIDRIVER_H /* A simpler version of jtag_add_callback4 */ extern void jtag_add_callback(jtag_callback1_t, u8 *in); -#else -/* implemented by minidriver */ -#endif /* This type can store an integer safely by a normal cast on 64 and @@ -651,18 +442,15 @@ typedef int (*jtag_callback_t)(u8 *in, jtag_callback_data_t data1, jtag_callback * If the execution of the queue fails before the callbacks, then the * callbacks may or may not be invoked depending on driver implementation. */ -#ifndef HAVE_JTAG_MINIDRIVER_H -extern void jtag_add_callback4(jtag_callback_t, u8 *in, jtag_callback_data_t data1, jtag_callback_data_t data2, jtag_callback_data_t data3); -#else -/* implemented by minidriver */ -#endif +extern void jtag_add_callback4(jtag_callback_t, u8 *in, + jtag_callback_data_t data1, jtag_callback_data_t data2, + jtag_callback_data_t data3); /* run a TAP_RESET reset. End state is TAP_RESET, regardless * of start state. */ extern void jtag_add_tlr(void); -extern int interface_jtag_add_tlr(void); /* Application code *must* assume that interfaces will * implement transitions between states with different @@ -705,8 +493,7 @@ extern int interface_jtag_add_tlr(void); * a partial implementation of pathmove would have little practical * application. */ -extern void jtag_add_pathmove(int num_states, tap_state_t* path); -extern int interface_jtag_add_pathmove(int num_states, tap_state_t* path); +extern void jtag_add_pathmove(int num_states, const tap_state_t* path); /* go to TAP_IDLE, if we're not already there and cycle * precisely num_cycles in the TAP_IDLE after which move @@ -716,7 +503,6 @@ extern int interface_jtag_add_pathmove(int num_states, tap_state_t* path); * to endstate via TAP_IDLE */ extern void jtag_add_runtest(int num_cycles, tap_state_t endstate); -extern int interface_jtag_add_runtest(int num_cycles, tap_state_t endstate); /* A reset of the TAP state machine can be requested. * @@ -742,18 +528,8 @@ extern int interface_jtag_add_runtest(int num_cycles, tap_state_t endstate); */ 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 void jtag_add_end_state(tap_state_t endstate); -extern int interface_jtag_add_end_state(tap_state_t endstate); extern void jtag_add_sleep(u32 us); -extern int interface_jtag_add_sleep(u32 us); /** @@ -762,7 +538,6 @@ extern int interface_jtag_add_sleep(u32 us); * stable, then queues up clock_count clocks for transmission. */ void jtag_add_clocks(int num_cycles); -int interface_jtag_add_clocks(int num_cycles); /* @@ -811,23 +586,21 @@ static __inline__ void jtag_set_error(int error) /* can be implemented by hw+sw */ -extern int interface_jtag_execute_queue(void); extern int jtag_power_dropout(int* dropout); extern int jtag_srst_asserted(int* srst_asserted); /* JTAG support functions */ -struct invalidstruct -{ - -}; /* execute jtag queue and check value and use mask if mask is != NULL. invokes * jtag_set_error() with any error. */ extern void jtag_check_value_mask(scan_field_t *field, u8 *value, u8 *mask); -extern enum scan_type jtag_scan_type(scan_command_t* cmd); -extern int jtag_scan_size(scan_command_t* cmd); -extern int jtag_read_buffer(u8* buffer, scan_command_t* cmd); -extern int jtag_build_buffer(scan_command_t* cmd, u8** buffer); + +#ifdef INCLUDE_JTAG_INTERFACE_H +extern enum scan_type jtag_scan_type(const scan_command_t* cmd); +extern int jtag_scan_size(const scan_command_t* cmd); +extern int jtag_read_buffer(u8* buffer, const scan_command_t* cmd); +extern int jtag_build_buffer(const scan_command_t* cmd, u8** buffer); +#endif // INCLUDE_JTAG_INTERFACE_H extern void jtag_sleep(u32 us); extern int jtag_call_event_callbacks(enum jtag_event event); @@ -848,19 +621,6 @@ void jtag_tap_handle_event(jtag_tap_t* tap, enum jtag_tap_event e); #define ERROR_JTAG_NOT_STABLE_STATE (-105) #define ERROR_JTAG_DEVICE_ERROR (-107) - -/* this allows JTAG devices to implement the entire jtag_xxx() layer in hw/sw */ -#ifdef HAVE_JTAG_MINIDRIVER_H -/* Here a #define MINIDRIVER() and an inline version of hw fifo interface_jtag_add_dr_out can be defined */ -#include "jtag_minidriver.h" -#define MINIDRIVER(a) notused ## a -#else -#define MINIDRIVER(a) a -extern void interface_jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value, - tap_state_t end_state); - -#endif - /* jtag_add_dr_out() is a version of jtag_add_dr_scan() which * only scans data out. It operates on 32 bit integers instead * of 8 bit, which makes it a better impedance match with @@ -886,14 +646,17 @@ extern void interface_jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int * There is no jtag_add_dr_outin() version of this fn that also allows * clocking data back in. Patches gladly accepted! */ -static __inline__ void jtag_add_dr_out(jtag_tap_t* tap, int num_fields, const int* num_bits, const u32* value, - tap_state_t end_state) -{ - if (end_state != TAP_INVALID) - cmd_queue_end_state = end_state; - cmd_queue_cur_state = cmd_queue_end_state; - interface_jtag_add_dr_out(tap, num_fields, num_bits, value, cmd_queue_end_state); -} +extern void jtag_add_dr_out(jtag_tap_t* tap, + int num_fields, const int* num_bits, const u32* value, + tap_state_t end_state); + +/** + * Function jtag_add_statemove + * moves from the current state to the goal \a state. This needs + * to be handled according to the xsvf spec, see the XSTATE command + * description. + */ +extern int jtag_add_statemove(tap_state_t goal_state); #endif /* JTAG_H */