path: root/src/jtag/jtag.h

/***************************************************************************
*   Copyright (C) 2005 by Dominic Rath                                    *
*   Dominic.Rath@gmx.de                                                   *
*                                                                         *
*   Copyright (C) 2007-2010 Øyvind Harboe                                 *
*   oyvind.harboe@zylin.com                                               *
*                                                                         *
*   This program is free software; you can redistribute it and/or modify  *
*   it under the terms of the GNU General Public License as published by  *
*   the Free Software Foundation; either version 2 of the License, or     *
*   (at your option) any later version.                                   *
*                                                                         *
*   This program is distributed in the hope that it will be useful,       *
*   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
*   GNU General Public License for more details.                          *
*                                                                         *
*   You should have received a copy of the GNU General Public License     *
*   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
***************************************************************************/

#ifndef OPENOCD_JTAG_JTAG_H
#define OPENOCD_JTAG_JTAG_H

#include <helper/binarybuffer.h>
#include <helper/log.h>

#ifdef _DEBUG_JTAG_IO_
#define DEBUG_JTAG_IO(expr ...) \
	do { if (1) LOG_DEBUG(expr); } while (0)
#else
#define DEBUG_JTAG_IO(expr ...) \
	do { if (0) LOG_DEBUG(expr); } while (0)
#endif

#ifndef DEBUG_JTAG_IOZ
#define DEBUG_JTAG_IOZ 64
#endif

/*-----</Macros>-------------------------------------------------*/

/**
 * Defines JTAG Test Access Port states.
 *
 * These definitions were gleaned from the ARM7TDMI-S Technical
 * Reference Manual and validated against several other ARM core
 * technical manuals.
 *
 * FIXME some interfaces require specific numbers be used, as they
 * are handed-off directly to their hardware implementations.
 * Fix those drivers to map as appropriate ... then pick some
 * sane set of numbers here (where 0/uninitialized == INVALID).
 */
typedef enum tap_state {
	TAP_INVALID = -1,

#if BUILD_ZY1000
	/* These are the old numbers. Leave as-is for now... */
	TAP_RESET    = 0, TAP_IDLE = 8,
	TAP_DRSELECT = 1, TAP_DRCAPTURE = 2, TAP_DRSHIFT = 3, TAP_DREXIT1 = 4,
	TAP_DRPAUSE  = 5, TAP_DREXIT2 = 6, TAP_DRUPDATE = 7,
	TAP_IRSELECT = 9, TAP_IRCAPTURE = 10, TAP_IRSHIFT = 11, TAP_IREXIT1 = 12,
	TAP_IRPAUSE  = 13, TAP_IREXIT2 = 14, TAP_IRUPDATE = 15,

#else
	/* Proper ARM recommended numbers */
	TAP_DREXIT2 = 0x0,
	TAP_DREXIT1 = 0x1,
	TAP_DRSHIFT = 0x2,
	TAP_DRPAUSE = 0x3,
	TAP_IRSELECT = 0x4,
	TAP_DRUPDATE = 0x5,
	TAP_DRCAPTURE = 0x6,
	TAP_DRSELECT = 0x7,
	TAP_IREXIT2 = 0x8,
	TAP_IREXIT1 = 0x9,
	TAP_IRSHIFT = 0xa,
	TAP_IRPAUSE = 0xb,
	TAP_IDLE = 0xc,
	TAP_IRUPDATE = 0xd,
	TAP_IRCAPTURE = 0xe,
	TAP_RESET = 0x0f,

#endif
} tap_state_t;

/**
 * Function tap_state_name
 * Returns a string suitable for display representing the JTAG tap_state
 */
const char *tap_state_name(tap_state_t state);

/** Provides user-friendly name lookup of TAP states. */
tap_state_t tap_state_by_name(const char *name);

/** The current TAP state of the pending JTAG command queue. */
extern tap_state_t cmd_queue_cur_state;

/**
 * This structure defines a single scan field in the scan. It provides
 * fields for the field's width and pointers to scan input and output
 * values.
 *
 * In addition, this structure includes a value and mask that is used by
 * jtag_add_dr_scan_check() to validate the value that was scanned out.
 */
struct scan_field {
	/** The number of bits this field specifies */
	int num_bits;
	/** A pointer to value to be scanned into the device */
	const uint8_t *out_value;
	/** A pointer to a 32-bit memory location for data scanned out */
	uint8_t *in_value;

	/** The value used to check the data scanned out. */
	uint8_t *check_value;
	/** The mask to go with check_value */
	uint8_t *check_mask;
};

struct jtag_tap {
	char *chip;
	char *tapname;
	char *dotted_name;
	int abs_chain_position;
	/** Is this TAP disabled after JTAG reset? */
	bool disabled_after_reset;
	/** Is this TAP currently enabled? */
	bool enabled;
	int ir_length; /**< size of instruction register */
	uint32_t ir_capture_value;
	uint8_t *expected; /**< Capture-IR expected value */
	uint32_t ir_capture_mask;
	uint8_t *expected_mask; /**< Capture-IR expected mask */
	uint32_t idcode; /**< device identification code */
	/** not all devices have idcode,
	 * we'll discover this during chain examination */
	bool hasidcode;

	/** Array of expected identification codes */
	uint32_t *expected_ids;
	/** Number of expected identification codes */
	uint8_t expected_ids_cnt;

	/** Flag saying whether to ignore version field in expected_ids[] */
	bool ignore_version;

	/** current instruction */
	uint8_t *cur_instr;
	/** Bypass register selected */
	int bypass;

	struct jtag_tap_event_action *event_action;

	struct jtag_tap *next_tap;
	/* dap instance if some null if no instance , initialized to 0 by calloc*/
	struct adiv5_dap *dap;
	/* private pointer to support none-jtag specific functions */
	void *priv;
};

void jtag_tap_init(struct jtag_tap *tap);
void jtag_tap_free(struct jtag_tap *tap);

struct jtag_tap *jtag_all_taps(void);
const char *jtag_tap_name(const struct jtag_tap *tap);
struct jtag_tap *jtag_tap_by_string(const char* dotted_name);
struct jtag_tap *jtag_tap_by_jim_obj(Jim_Interp* interp, Jim_Obj *obj);
struct jtag_tap *jtag_tap_by_position(unsigned abs_position);
struct jtag_tap *jtag_tap_next_enabled(struct jtag_tap *p);
unsigned jtag_tap_count_enabled(void);
unsigned jtag_tap_count(void);

/*
 * - TRST_ASSERTED triggers two sets of callbacks, after operations to
 *   reset the scan chain -- via TMS+TCK signaling, or deasserting the
 *   nTRST signal -- are queued:
 *
 *    + Callbacks in C code fire first, patching internal state
 *    + Then post-reset event scripts fire ... activating JTAG circuits
 *      via TCK cycles, exiting SWD mode via TMS sequences, etc
 *
 *   During those callbacks, scan chain contents have not been validated.
 *   JTAG operations that address a specific TAP (primarily DR/IR scans)
 *   must *not* be queued.
 *
 * - TAP_EVENT_SETUP is reported after TRST_ASSERTED, and after the scan
 *   chain has been validated.  JTAG operations including scans that
 *   target specific TAPs may be performed.
 *
 * - TAP_EVENT_ENABLE and TAP_EVENT_DISABLE implement TAP activation and
 *   deactivation outside the core using scripted code that understands
 *   the specific JTAG router type.  They might be triggered indirectly
 *   from EVENT_SETUP operations.
 */
enum jtag_event {
	JTAG_TRST_ASSERTED,
	JTAG_TAP_EVENT_SETUP,
	JTAG_TAP_EVENT_ENABLE,
	JTAG_TAP_EVENT_DISABLE,
};

struct jtag_tap_event_action {
	/** The event for which this action will be triggered. */
	enum jtag_event event;
	/** The interpreter to use for evaluating the @c body. */
	Jim_Interp *interp;
	/** Contains a script to 'eval' when the @c event is triggered. */
	Jim_Obj *body;
	/* next action in linked list */
	struct jtag_tap_event_action *next;
};

/**
 * Defines the function signature requide for JTAG event callback
 * functions, which are added with jtag_register_event_callback()
 * and removed jtag_unregister_event_callback().
 * @param event The event to handle.
 * @param prive A pointer to data that was passed to
 *	jtag_register_event_callback().
 * @returns Must return ERROR_OK on success, or an error code on failure.
 *
 * @todo Change to return void or define a use for its return code.
 */
typedef int (*jtag_event_handler_t)(enum jtag_event event, void *priv);

int jtag_register_event_callback(jtag_event_handler_t f, void *x);
int jtag_unregister_event_callback(jtag_event_handler_t f, void *x);

int jtag_call_event_callbacks(enum jtag_event event);


/** @returns The current JTAG speed setting. */
int jtag_get_speed(int *speed);

/**
 * Given a @a speed setting, use the interface @c speed_div callback to
 * adjust the setting.
 * @param speed The speed setting to convert back to readable KHz.
 * @returns ERROR_OK if the interface has not been initialized or on success;
 *	otherwise, the error code produced by the @c speed_div callback.
 */
int jtag_get_speed_readable(int *speed);

/** Attempt to configure the interface for the specified KHz. */
int jtag_config_khz(unsigned khz);

/**
 * Attempt to enable RTCK/RCLK. If that fails, fallback to the
 * specified frequency.
 */
int jtag_config_rclk(unsigned fallback_speed_khz);

/** Retreives the clock speed of the JTAG interface in KHz. */
unsigned jtag_get_speed_khz(void);

enum reset_types {
	RESET_NONE            = 0x0,
	RESET_HAS_TRST        = 0x1,
	RESET_HAS_SRST        = 0x2,
	RESET_TRST_AND_SRST   = 0x3,
	RESET_SRST_PULLS_TRST = 0x4,
	RESET_TRST_PULLS_SRST = 0x8,
	RESET_TRST_OPEN_DRAIN = 0x10,
	RESET_SRST_PUSH_PULL  = 0x20,
	RESET_SRST_NO_GATING  = 0x40,
	RESET_CNCT_UNDER_SRST = 0x80
};

enum reset_types jtag_get_reset_config(void);
void jtag_set_reset_config(enum reset_types type);

void jtag_set_nsrst_delay(unsigned delay);
unsigned jtag_get_nsrst_delay(void);

void jtag_set_ntrst_delay(unsigned delay);
unsigned jtag_get_ntrst_delay(void);

void jtag_set_nsrst_assert_width(unsigned delay);
unsigned jtag_get_nsrst_assert_width(void);

void jtag_set_ntrst_assert_width(unsigned delay);
unsigned jtag_get_ntrst_assert_width(void);

/** @returns The current state of TRST. */
int jtag_get_trst(void);
/** @returns The current state of SRST. */
int jtag_get_srst(void);

/** Enable or disable data scan verification checking. */
void jtag_set_verify(bool enable);
/** @returns True if data scan verification will be performed. */
bool jtag_will_verify(void);

/** Enable or disable verification of IR scan checking. */
void jtag_set_verify_capture_ir(bool enable);
/** @returns True if IR scan verification will be performed. */
bool jtag_will_verify_capture_ir(void);

/** Initialize debug adapter upon startup.  */
int adapter_init(struct command_context *cmd_ctx);

/** Shutdown the debug adapter upon program exit. */
int a