Catapult JTAG FSM Library

Catapult JTAG FSM Library ( btjfsm.dll or btjfsm.so ) is the library used to develop JTAG specific applications based on Catapult JTAG probes. This library provides rich set of APIs to interact with the cables. The SDK package contains sample application program for reference.

Application Programming Interface

The key parameter for all the APIs are BTJFSM_DEV_HANDLE, which is the handle to the opened Catapult cable.

typedef void* BTJFSM_DEV_HANDLE;

btjfsm_get_lib_version

Returns the version of the Catapult JTAG FSM Library.

EXPORT char* btjfsm_get_lib_version
      (
       void
      );

btjfsm_init_lib

Initialises the JTAG Library. Before calling any APIs, this should be called first to initialise the internal components of the library.

  EXPORT BTJFSM_RET_TYPE btjfsm_init_lib
      (
       void
      );

btjfsm_open_jtag_device

Opens the Catapult Device using valid Identifier. Valid Identifiers are CATAPULT_EJx_IPADDRESS, CATAPULT_EJx_HOST_NAME, CATAPULT_EJx_SERIAL_NUM, CATAPULT_UJx_SERIAL_NUM. Ethernet JTAG Cable can be opened-up using either IP Address ( CATAPULT_EJx_IPADDRESS) or host name of the device ( CATAPULT_EJx_HOST_NAME ). USB JTAG Cable can be opened-up using the serial number of the device ( CATAPULT_UJx_SERIAL_NUM). CATAPULT_EJx_SERIAL_NUM is not supported.

  EXPORT BTJFSM_DEV_HANDLE btjfsm_open_jtag_device
      (
       eJTAGDeviceOpenID OpenIdentifier,
       char* pIDName
      );

btjfsm_close_jtag_device

Closes the Catapult Device. BTJFSM_DEV_HANDLE is the input to this function.

  EXPORT void btjfsm_close_jtag_device
      (
       BTJFSM_DEV_HANDLE hHandle
      );

btjfsm_jtag_reset_idle

Moves the JTAG State to Reset IDLE state.

  EXPORT void btjfsm_jtag_reset_idle
      (
       BTJFSM_DEV_HANDLE hHandle
      );

btjfsm_set_tclk_rate

Sets the TCLK frequency in the Cable.

  EXPORT int btjfsm_set_tclk_rate
      (
       BTJFSM_DEV_HANDLE hHandle,
       unsigned int Frequency
      );

btjfsm_set_debug

Sets the Debug Level. Optionally debug file can be specified to log the traces in a file.

  EXPORT void btjfsm_set_debug
      (
       eDebugLevel DebugLevel,
       const char* pDebugFile
      );
  typedef enum _DebugLevel
  {
      DEBUG_OFF    = 0, /* default level */
      DEBUG_ERR    = 1,
      DEBUG_WARN   = 2,
      DEBUG_INFO   = 4,
      DEBUG_TRACE1 = 5,
      DEBUG_TRACE2 = 6,
      DEBUG_TRACE3 = 7,
      DEBUG_DUMP   = 8,
      DEBUG_MAX    = 8
  }eDebugLevel;

btjfsm_get_jtag_state_from_name

Returns the JTAG State by giving the name in string format . Valid Inputs are “RESET”, “IDLE”, “DRSELECT”, “DRCAPTURE”, “DRSHIFT”, “DREXIT1”,”DRPAUSE”,”DREXIT2”,”DRUPDATE”,”IRSELECT”,”IRCAPTURE”,”IRSHIFT”,”IREXIT1”,”IRPAUSE”,”IREXIT2”, “IRUPDATE” .

EXPORT JTAG_STATE btjfsm_get_jtag_state_from_name

      (
       BTJFSM_DEV_HANDLE hHandle,
       char *name
      );

btjfsm_set_drstop_state

Sets the DR Stop State. This State would be the stop state after DRSHIFT state.

  EXPORT BTJFSM_RET_TYPE btjfsm_set_drstop_state
      (
       BTJFSM_DEV_HANDLE hHandle,
       JTAG_STATE state
      );

btjfsm_set_irstop_state

Sets the IR Stop State. This state would be the stop state after IRSHIFT.

  EXPORT BTJFSM_RET_TYPE btjfsm_set_irstop_state
      (
       BTJFSM_DEV_HANDLE hHandle,
       JTAG_STATE state
      );

btjfsm_goto_jtag_state

Move the Current JTAG State to a particular State.

  EXPORT BTJFSM_RET_TYPE btjfsm_goto_jtag_state
      (
       BTJFSM_DEV_HANDLE hHandle,
       JTAG_STATE state
      );

btjfsm_get_current_jtag_state

Returns the current JTAG State .

  EXPORT JTAG_STATE btjfsm_get_current_jtag_state
      (
       void
      );

btjfsm_jtag_scan

Executes IRSHIFT or DRSHIFT depends upon the current state. Before calling this API, the current state should be moved to IRSHFIT or DRSHIFT.

  EXPORT BTJFSM_RET_TYPE btjfsm_jtag_scan
      (
       BTJFSM_DEV_HANDLE hHandle,
       int count,
       unsigned char *tdi,
       unsigned char *tdo,
       eMovePauseState movePauseState /* FALSE - after the scan the state would be still SHIFT state */
      );                      /* TRUE  - vice versa */

btjfsm_do_wait_cycles

Keeps the JTAG state machine in the specified wait state for given cycle. For example, if the wait state is shiftIR and the number of cycles are 20000, the FSM would be kept in the shiftIR state for 20000 loops.

  EXPORT BTJFSM_RET_TYPE btjfsm_do_wait_cycles
      (
       BTJFSM_DEV_HANDLE hHandle,
       long cycles,
       JTAG_STATE wait_state
      );

btjfsm_do_wait_microseconds

Apply specified delay in microseconds after moving the State to the specified wait state.

  EXPORT BTJFSM_RET_TYPE btjfsm_do_wait_microseconds
      (
       BTJFSM_DEV_HANDLE hHandle,
       long microseconds,
       JTAG_STATE wait_state
      );

btjfsm_log_to_file

Used to log the given IO Data.

  EXPORT void btjfsm_log_to_file
      (
       BTJFSM_DEV_HANDLE hHandle,
       const char* pLogFile
      );

btjfsm_lock_device

Used to lock the device. Useful API when multiple application interacts with the same Cable. On success, this API returns 16 bit signature value or “0” on failure.

msWait in milli seconds. If msWait is passed as “0”, a default value of 2000 msec is set in the library.

  unsigned short EXPORT btjfsm_lock_device
      (
       BTJFSM_DEV_HANDLE hHandle,
       int msWait /* timeout value in milli sec until to get the lock */
      );

btjfsm_unlock_device

In order to unlock the device( Cable ), the 16 bit signature value (lockSignature) which was returned when the btjfsm_lock_device API was invoked has to be passed as a parameter. On success, this API returns 0, otherwise it returns -1 ( Failure ).

  int EXPORT btjfsm_unlock_device
      (
       BTJFSM_DEV_HANDLE hDeviceHandle,
       unsigned short lockSignature
      );

btjfsm_check_health

Execute quick sanity check on the device. Once this API is called for health check, move the JTAG state machine to RESET state.

  EXPORT BTJFSM_RET_TYPE btjfsm_check_health
      (
       BTJFSM_DEV_HANDLE hDeviceHandle,
       unsigned int TestOptions
      );

btjfsm_wait_microseconds_atomic

This API apply atomic delay on the cable. When this API is executed, the current JTAG State should be IRUPDATE or DRUPDATE. Currently Catapult EJ1 supports this API. On success returns BTJFSM_SUCCESS, On failure returns BTJFSM_TCLK_FAILURE, BTJFSM_IO_ERROR,BTJFSM_INVALID_FSM_STATE,BTJFSM_OUT_OF_FREQ.

  EXPORT BTJFSM_RET_TYPE btjfsm_wait_microseconds_atomic
      (
       BTJFSM_DEV_HANDLE hHandle,
       eCatapultDeviceType cableType,
       unsigned int tclkFrequency, //current tclk frequency
       unsigned int usecDelay
      );

Sample Application

This sample application is already part of the SDK package ( Ref. example.c )

int main(int argc, char * argv[]) {

  int             result;
  int             clockSpeed;
  int             dummytdo;
  unsigned int lockHandle = 0;
  /* Initialize ByteTools Catapult JTAG Library */
  if( btjfsm_init_lib() != BTJFSM_SUCCESS )
  {
      fprintf(stderr,"Error: Failed to initialize ByteTools JTAG Library\n");
      return 0;
  }
  /* Setting the default debug level */
  btjfsm_set_debug( DEBUG_ERR, NULL );
  printf("Opening the Catapult Device \n");
  /* Open the Device using known Identifier */
  if( gEthIP == 1 )
  {
      printf("Opening device using ip address : %s\n",gIpAddress );
      gDeviceHandle = btjfsm_open_jtag_device( CATAPULT_EJx_IPADDRESS, gIpAddress );
  }
  else if( gUSBSerialNumber == 1 )
  {
      printf("Opening device using usb serial number\n");
      gDeviceHandle = btjfsm_open_jtag_device( CATAPULT_UJx_SERIAL_NUM, gSerialNumber );
  }
  else
  {
      fprintf(stderr,"Invalid device open option\n");
      return 0;
  }
  if( gDeviceHandle != NULL )
  {
      /* Execute few tests */
      printf("Move the state to Reset IDLE \n");
      btjfsm_jtag_reset_idle( gDeviceHandle );
  }
  if( gDeviceHandle == NULL )
  {
      fprintf(stderr,"Error: Failed to open device\n");
      return 0;
  }
  if( gDeviceHandle != NULL )
  {
      printf("Closing the Catapult Device \n");
      btjfsm_close_jtag_device( gDeviceHandle );
  }
  return 0;

}


Personal Tools