jtag.h

Go to the documentation of this file.

/* SPDX-License-Identifier: GPL-2.0-or-later */
 
/***************************************************************************
*   Copyright (C) 2005 by Dominic Rath                                    *
*   Dominic.Rath@gmx.de                                                   *
*                                                                         *
*   Copyright (C) 2007-2010 Øyvind Harboe                                 *
*   oyvind.harboe@zylin.com                                               *
***************************************************************************/
 
#ifndef OPENOCD_JTAG_JTAG_H
#define OPENOCD_JTAG_JTAG_H
 
#include <helper/binarybuffer.h>
#include <helper/command.h>
#include <helper/log.h>
#include <helper/replacements.h>
 
#ifndef DEBUG_JTAG_IOZ
#define DEBUG_JTAG_IOZ 64
#endif
 
/*-----</Macros>-------------------------------------------------*/
 
typedef enum tap_state {
    TAP_INVALID = -1,
 
    /* 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,
} tap_state_t;
 
#define SRST_DEASSERT   0
#define SRST_ASSERT     1
#define TRST_DEASSERT   0
#define TRST_ASSERT     1
 
const char *tap_state_name(tap_state_t state);
 
tap_state_t tap_state_by_name(const char *name);
 
extern tap_state_t cmd_queue_cur_state;
 
struct scan_field {
    int num_bits;
    const uint8_t *out_value;
    uint8_t *in_value;
 
    uint8_t *check_value;
    uint8_t *check_mask;
};
 
struct jtag_tap {
    char *chip;
    char *tapname;
    char *dotted_name;
    int abs_chain_position;
    bool disabled_after_reset;
    bool enabled;
    int ir_length; 
    uint32_t ir_capture_value;
    uint8_t *expected; 
    uint32_t ir_capture_mask;
    uint8_t *expected_mask; 
    uint32_t idcode; 
    bool has_idcode;
 
    uint32_t *expected_ids;
    uint8_t expected_ids_cnt;
 
    bool ignore_version;
 
    bool ignore_bypass;
 
    uint8_t *cur_instr;
    bool bypass;
 
    uint64_t ir_bypass_value;
 
    struct jtag_tap_event_action *event_action;
 
    struct jtag_tap *next_tap;
    /* 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 {
    enum jtag_event event;
    Jim_Interp *interp;
    Jim_Obj *body;
    /* next action in linked list */
    struct jtag_tap_event_action *next;
};
 
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);
 
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);
 
int jtag_get_trst(void);
int jtag_get_srst(void);
 
void jtag_set_verify(bool enable);
bool jtag_will_verify(void);
 
void jtag_set_verify_capture_ir(bool enable);
bool jtag_will_verify_capture_ir(void);
 
void jtag_set_flush_queue_sleep(int ms);
 
int jtag_init(struct command_context *cmd_ctx);
 
int jtag_init_reset(struct command_context *cmd_ctx);
int jtag_register_commands(struct command_context *cmd_ctx);
int jtag_init_inner(struct command_context *cmd_ctx);
 
void jtag_add_ir_scan(struct jtag_tap *tap,
        struct scan_field *fields, tap_state_t endstate);
void jtag_add_ir_scan_noverify(struct jtag_tap *tap,
        const struct scan_field *fields, tap_state_t state);
void jtag_add_plain_ir_scan(int num_bits, const uint8_t *out_bits, uint8_t *in_bits,
        tap_state_t endstate);
 
void jtag_add_dr_scan(struct jtag_tap *tap, int num_fields,
        const struct scan_field *fields, tap_state_t endstate);
void jtag_add_dr_scan_check(struct jtag_tap *tap, int num_fields,
        struct scan_field *fields, tap_state_t endstate);
void jtag_add_plain_dr_scan(int num_bits,
        const uint8_t *out_bits, uint8_t *in_bits, tap_state_t endstate);
 
typedef intptr_t jtag_callback_data_t;
 
typedef void (*jtag_callback1_t)(jtag_callback_data_t data0);
 
void jtag_add_callback(jtag_callback1_t f, jtag_callback_data_t data0);
 
 
typedef int (*jtag_callback_t)(jtag_callback_data_t data0,
                jtag_callback_data_t data1,
                jtag_callback_data_t data2,
                jtag_callback_data_t data3);
 
void jtag_add_tlr(void);
 
void jtag_add_pathmove(int num_states, const tap_state_t *path);
 
int jtag_add_statemove(tap_state_t goal_state);
 
void jtag_add_runtest(int num_cycles, tap_state_t endstate);
 
void jtag_add_reset(int req_tlr_or_trst, int srst);
 
void jtag_add_sleep(uint32_t us);
 
int jtag_add_tms_seq(unsigned nbits, const uint8_t *seq, enum tap_state t);
 
void jtag_add_clocks(int num_cycles);
 
int jtag_execute_queue(void);
 
void jtag_execute_queue_noclear(void);
 
int jtag_get_flush_queue_count(void);
 
void jtag_notify_event(enum jtag_event);
 
/* can be implemented by hw + sw */
int jtag_power_dropout(int *dropout);
int jtag_srst_asserted(int *srst_asserted);
 
/* JTAG support functions */
 
void jtag_check_value_mask(struct scan_field *field, uint8_t *value, uint8_t *mask);
 
void jtag_sleep(uint32_t us);
 
/*
 * The JTAG subsystem defines a number of error codes,
 * using codes between -100 and -199.
 */
#define ERROR_JTAG_INIT_FAILED       (-100)
#define ERROR_JTAG_INVALID_INTERFACE (-101)
#define ERROR_JTAG_NOT_IMPLEMENTED   (-102)
#define ERROR_JTAG_TRST_ASSERTED     (-103)
#define ERROR_JTAG_QUEUE_FAILED      (-104)
#define ERROR_JTAG_NOT_STABLE_STATE  (-105)
#define ERROR_JTAG_DEVICE_ERROR      (-107)
#define ERROR_JTAG_STATE_INVALID     (-108)
#define ERROR_JTAG_TRANSITION_INVALID (-109)
#define ERROR_JTAG_INIT_SOFT_FAIL    (-110)
 
void jtag_set_error(int error);
int jtag_error_clear(void);
 
bool is_jtag_poll_safe(void);
 
bool jtag_poll_get_enabled(void);
 
void jtag_poll_set_enabled(bool value);
 
bool jtag_poll_mask(void);
 
void jtag_poll_unmask(bool saved);
 
#include <jtag/minidriver.h>
 
__COMMAND_HANDLER(handle_jtag_newtap);
 
#endif /* OPENOCD_JTAG_JTAG_H */