/****************************************************************************** * * Copyright (C) 2013 - 2014 Xilinx, Inc. All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * Use of the Software is limited solely to applications: * (a) running on a Xilinx device, or * (b) that interact with a Xilinx device through a bus or interconnect. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * XILINX CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. * * Except as contained in this notice, the name of the Xilinx shall not be used * in advertising or otherwise to promote the sale, use or other dealings in * this Software without prior written authorization from Xilinx. * ******************************************************************************/ /* * JTAG server interface * * This interface is intended to be a common abstraction of JTAG cable * implementations. * * Interface usage steps: * * 1. Initialize server implementation instance using implementation * specific js_init_*() function. * * 2. Enumerate available ports using js_get_port_descr_list(). * * 3. Open selected port using js_open_port(). * * 4. Optional: get or set properties using js_get_property() or * js_set_property(). * * 5. Optional: enumerate scan chain using js_detect_taps() or * manually. Add nodes for each TAP controller (API TDB). * * 6. Build command sequence(s) object using * js_create_command_sequence(), js_add_state_change(), and * js_add_shift(). * * 7. Run sequence using js_run_command_sequence(). * * 8. Repeat #6 and #7 as needed, possibly deleting or clearing * command sequence objects as needed using * js_delete_command_sequence() and js_clear_command_sequence(). * * 9. Close port using js_close_port(). * * 10. Delete server using js_deinit_server(). */ #ifndef XILSKEY_JS_H #define XILSKEY_JS_H #include #if defined(_MSC_VER) && _MSC_VER < 1600 typedef signed __int8 int8_t; typedef unsigned __int8 uint8_t; typedef signed __int16 int16_t; typedef unsigned __int16 uint16_t; typedef signed __int32 int32_t; typedef unsigned __int32 uint32_t; typedef signed __int64 int64_t; typedef unsigned __int64 uint64_t; #else # include #endif #ifdef __cplusplus extern "C" { #endif /* * IEEE 1149.1 defined dummy idcode value. */ #define JS_DUMMY_IDCODE 0x000000ff typedef struct js_server_struct js_server_t; typedef struct js_port_descr_struct js_port_descr_t; typedef struct js_port_struct js_port_t; typedef struct js_node_struct js_node_t; typedef struct js_command_sequence_struct js_command_sequence_t; /* * JTAG property kinds */ typedef enum { JS_PROP_FREQUENCY } js_property_kind_t; typedef long js_property_value_t; /* * JTAG port description * * This is retrieved by calling js_get_port_descr_list(), and is needed for * js_open_port() to indicate which port to use. */ struct js_port_descr_struct { char manufacturer[64]; char serial[64]; char port[64]; char description[128]; void *handle; }; /* * JTAG port * * This is retrieved by calling js_open_port(). */ struct js_port_struct { /* Server associated with port */ js_server_t *server; /* Node representing the whole scan chain */ js_node_t *root_node; }; /* * JTAG node information * * Nodes typically represent a TAP controller. A node can also * represent a collection of TAP controllers, i.e. the whole scan * chain or a device containing multiple TAP controllers. For scan * chains containing JTAG multiplexers a node can represent the * branches on the multiplexer. */ struct js_node_struct { /* Associated port */ js_port_t *port; /* Node represents one or more TAP controllers */ int is_tap:1; /* Node is a multiplexer (child nodes are branches) */ int is_mux:1; /* Node is a branch on a multiplexer */ int is_branch:1; /* This branch is part of the scan chain */ int is_active:1; /* IDCODE of the TAP (JS_DUMMY_IDCODE if unknown or NA) */ uint32_t idcode; /* Instruction register length in bits */ int irlen; /* Name of node */ const char *name; /* Parent node */ js_node_t **parent; /* Child nodes */ js_node_t **child_list; unsigned int child_count; }; /* * JTAG states * * To simply the interface only a subset of the JTAG states are make * accessible. */ /*typedef enum { JS_RESET, JS_IDLE, JS_SHIFT_DR, JS_PAUSE_DR, JS_SHIFT_IR, JS_PAUSE_IR, JS_STATE_MAX } js_state_t;*/ typedef enum { JS_RESET, JS_IDLE, JS_DRSELECT, JS_DRCAPTURE, JS_DRSHIFT, JS_DREXIT1, JS_DRPAUSE, JS_DREXIT2, JS_DRUPDATE, JS_IRSELECT, JS_IRCAPTURE, JS_IRSHIFT, JS_IREXIT1, JS_IRPAUSE, JS_IREXIT2, JS_IRUPDATE, JS_STATE_MAX } js_state_t; /* * JTAG command sequence object * * Commands are added to this object for later execution. */ struct js_command_sequence_struct { js_node_t *node; }; /*********************************************************************** * JTAG server implementation specific functions ***********************************************************************/ /* * Get list of available JTAG ports supported by this server */ extern int js_get_port_descr_list( js_server_t *server, js_port_descr_t **port_listp); /* * Open a specific JTAG port for this server instance */ extern int js_open_port( js_server_t *server, js_port_descr_t *port_descr, js_port_t **port); /* * Delete server instance */ extern void js_deinit_server( js_server_t *server); /* * Get property value */ extern int js_get_property( js_port_t *port, js_property_kind_t kind, js_property_value_t *valuep); /* * Set property value */ extern int js_set_property( js_port_t *port, js_property_kind_t kind, js_property_value_t value); /* * Execute pending commands */ extern int js_run_command_sequence( js_command_sequence_t *commands); /* * Open a specific JTAG port for this server instance */ extern int js_close_port( js_port_t *port); /*********************************************************************** * JTAG server library functions ***********************************************************************/ /* * Retrieve information about the last error as a string. * * Returns NULL if no error occured since last call to * set_last_error(server, NULL). */ const char *js_get_last_error( js_server_t *server); /* * Set error information */ void js_set_last_error( js_server_t *server, const char *fmt, ...); /* * Allocate command sequence object */ extern js_command_sequence_t *js_create_command_sequence( js_node_t *node); /* * CLear command sequence * * This function allows a command sequence object to be reused for a * difference sequence. */ extern int js_clear_command_sequence( js_command_sequence_t *cmdseq); /* * Delete command sequence */ extern int js_delete_command_sequence( js_command_sequence_t *cmdseq); /* * Adds command to move JTAG state machine to and cycle TCK * times. The argument is only applicable for when * is one of the stable states JS_RESET, JS_IDLE, JS_PAUSE_IR * or JS_PAUSE_DR. */ extern int js_add_state_change( js_command_sequence_t *cmdseq, js_state_t state, unsigned int clocks); /* * Adds command to * 1. move state machine to either JS_SHIFT_IR if ( & * JS_TO_IR) != 0 or JS_SHIFT_DR if ( & JS_TO_IR) == 0, * 2. shift number of bits in from tdi_buffer to TDI and out * from TDO to tdo_buffer, and * 3. move state machine to . * * If is NULL then number of ones if ( & * JS_ONES) != 0 or zeroes if ( & JS_ONES) == 0 are shifted * to TDI. * * If is NULL then TDO bits are ignored. * * Both state transtions are optional if the state machine is * already in the correct state. */ enum { JS_TO_IR = 1, JS_ONES = 2 }; extern int js_add_shift( js_command_sequence_t *cmdseq, unsigned int flags, size_t bits, unsigned char **tdi_buffer, unsigned char **tdo_buffer, js_state_t state); /* * Auto detect TAPs on scan chain. * * This typically involes a reset of the scan chain followed by * reading data registers. * * The result is allocated using malloc() and the caller is resposible * for freeing the buffer when it is no longer needed. */ extern int js_detect_taps( js_port_t *port, uint32_t **resultp); #ifdef __cplusplus } #endif #endif /* XILSKEY_JS_H */