/*
** XJLink external API for access to JTAG capabilities.
**
** Copyright (c) 2001-2004 XJTAG Ltd.
*/

#ifndef XJAPI_H
#define XJAPI_H

#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#include "jtag.h"


#ifdef __cplusplus
extern "C" {
#endif


#ifdef XJAPI_EXPORTS
#define XJAPI __declspec(dllexport)
#else
#define XJAPI __declspec(dllimport)
#endif

// Pinmap settings.  This enumeration defines the different pinmappings
// available on the hardware.  If the user would like to define their own
// pinmappings then this is done by specifying XJAPI_USERDEFINED and then
// calling XJAPI_SetPinMap() with the specified pinmapping.
typedef enum {
	XJAPI_XJTAG,        // XJTAG default connector
	XJAPI_MULTIICE,     // ARM Multiice connector
	XJAPI_XILINX,       // Xilinx 9 bit connector
	XJAPI_BYTEBLASTER,  // Altera byteblaster connector
	XJAPI_USERDEFINED   // User-defined pinmap
} XJAPI_PINMAP;

// Pin types.  These pin types are used in a call to XJAPI_SetPinMap() if the
// user wants to set a user-defined pin mapping.  The user passes in an array
// of these values, where array[i] is the setting for pin (i+1).
typedef enum {
	XJAPI_DISABLED,     // Pin is disabled
	XJAPI_TDI,          // Test data input pin (data into the target board)
	XJAPI_TDO,          // Test data output pin (data out of the target board)
	XJAPI_TMS,          // Test mode select pin
	XJAPI_TCK,          // Test clock pin
	XJAPI_HIGH,         // Driven high
	XJAPI_LOW           // Driven low
} XJAPI_PIN_TYPE;

// Pin output impedance values.  Currently we can select the following output
// impedances: 35 ohm and 100 ohm.  By default we drive using a 100 ohm output
// impedance, which is suitable for unterminated loads.
typedef enum
{
	XJAPI_DRIVE_HIGH = 35,
	XJAPI_DRIVE_LOW  = 100
} XJAPI_PIN_DRIVE;

// Pin definition.  This structure is used in a user-defined pinmap array.
typedef struct {
	XJAPI_PIN_TYPE pinType; // Type of pin
	int outputImpedance;    // Required output impedance for an output pin
	                        // Ignored for input pins.
} XJAPI_PIN_DEF;

typedef XJAPI_PIN_DEF XJAPI_USER_MAP[20];

// The return values. non-zero is error.
typedef enum {
	XJAPI_SUCCESS = 0,
	XJAPI_ERROR_NOT_INITIALISED,
	XJAPI_ERROR_HARDWARE,
	XJAPI_ERROR_NOLICENSE,
	XJAPI_ERROR_PARAMETER1,
	XJAPI_ERROR_PARAMETER2,
	XJAPI_ERROR_PARAMETER3,
	XJAPI_ERROR_PARAMETER4,
	XJAPI_ERROR_PARAMETER5,
	XJAPI_ERROR_GENERAL,
} XJAPI_ERROR;


// Scan types for XJAPI_Scan and XJAPI_ScanMultiple.
typedef enum {
	XJAPI_SCAN_DR,
	XJAPI_SCAN_IR
} XJAPI_SCAN_TYPE;

// Get last error returns a string for the last error handled.
XJAPI void XJAPI_GetLastError(
	char *buffer,          // Buffer to store string
	unsigned int length    // Maximum length of buffer
);

// Initialise the XJTAG System. Must be called before any other function.
XJAPI void XJAPI_Startup(void);

// Shutdown the XJTAG System. Should be called before the client application
// exits.
XJAPI void XJAPI_Shutdown(void);

// Function to setup the hardware and the pin mapping.
XJAPI XJAPI_ERROR XJAPI_HardwareSetup(
	unsigned int frequency, // The desired frequency in hertz (XJEase will set to the nearest 1Mhz)
	XJAPI_PINMAP pinMap,    // The required pinmapping
	BOOL         powerOn    // Whether the power should be applied to the board
);

// Release the hardware - must be called before exiting.
XJAPI XJAPI_ERROR XJAPI_HardwareRelease();


// Function to set the pin map
//
// This function takes a parameter which is an array of 20 elements,
// corresponding to the 20 pins.  Each value i should be the type of pin (i+1)
// with the exception of the fixed pins:
//
// pin 1  - VCC
// pin 2  - NC
// pin 4  - GND
// pin 20 - GND
//
// Note the array starts at 0 but the pins at 1, so the setting for pin 10
// would be written in array[9].
//
XJAPI XJAPI_ERROR XJAPI_SetPinMap(
	XJAPI_PINMAP     pinMapping,
	XJAPI_USER_MAP  *pinMap,
	BOOL powerOn
);

// Function to set the frequency.
// Valid frequencies range from 100kHz to 1MHz in steps of 100kHz and then
// from 1MHz to 60MHz in steps of 1MHz.
XJAPI XJAPI_ERROR XJAPI_SetFrequency(
	unsigned int frequency   // Desired frequency in Hz
);

// Function to apply TMS reset.
XJAPI XJAPI_ERROR XJAPI_TmsReset(
);

// Function to goto a specific JTAG state.
XJAPI XJAPI_ERROR XJAPI_GotoState(
	JTAG_STATE state
);

// Function to set the final state that the system goes to after a DR or IR scan
// operation.  By default both scans go to the JTAG_IDLE state.
//
XJAPI XJAPI_ERROR XJAPI_SetEndState(
	JTAG_STATE endir,
	JTAG_STATE enddr
);

// Function to clock the JTAG chain a specific number of times.
XJAPI XJAPI_ERROR XJAPI_ClockChain(
	unsigned int count
);

// Function to execute a JTAG DR/IR scan cycle.  Will leave the system in the
// JTAG_IDLE state after the scan, by default, otherwise use XJAPI_SetEndState
// to set.
//
// outData is the data to be shifted out bit 0 of byte 0 first.
// inData is the data shifted in bit 0 of byte 0 is the first bit.
//
XJAPI XJAPI_ERROR XJAPI_Scan(
	XJAPI_SCAN_TYPE scanType,   // Type of scan DR or IR
	unsigned long   length,     // Length of scan in bits
	unsigned long * outData,    // Data to be shifted out
	unsigned long * inData      // Data to be shifted in
);

// Function to implement multiple scanning.  This function is used to scan multiple chains
// of mixed type (DR and IR scans) and of mixed length.
//
// Note on arrays.
// scanTypes, length, outData and inData are all of length nScans.
//
XJAPI XJAPI_ERROR XJAPI_ScanMultiple(
	unsigned long     nScans,       // Total number of scans
	XJAPI_SCAN_TYPE * scanTypes,    // Types of each scan (IR or DR)
	unsigned int    * length,       // Length of each scan
	unsigned long  ** outData,      // Array of pointers to each buffer to be shifted out
	unsigned long  ** inData        // Array of pointers to each buffer to be shifted in
);


#ifdef __cplusplus
}
#endif

#endif /* XJAPI_H */