src/jtag/swd.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 /***************************************************************************
   4  *   Copyright (C) 2009-2010 by David Brownell                             *
   5  ***************************************************************************/
   6
   7 #ifndef OPENOCD_JTAG_SWD_H
   8 #define OPENOCD_JTAG_SWD_H
   9
  10 #include <helper/log.h>
  11 #include <target/arm_adi_v5.h>
  12
  13 /* Bits in SWD command packets, written from host to target
  14  * first bit on the wire is START
  15  */
  16 #define SWD_CMD_START   (1 << 0)        /* always set */
  17 #define SWD_CMD_APNDP   (1 << 1)        /* set only for AP access */
  18 #define SWD_CMD_RNW     (1 << 2)                /* set only for read access */
  19 #define SWD_CMD_A32     (3 << 3)                /* bits A[3:2] of register addr */
  20 #define SWD_CMD_PARITY  (1 << 5)        /* parity of APnDP|RnW|A32 */
  21 #define SWD_CMD_STOP    (0 << 6)        /* always clear for synch SWD */
  22 #define SWD_CMD_PARK    (1 << 7)        /* driven high by host */
  23 /* followed by TRN, 3-bits of ACK, TRN */
  24
  25 /*
  26  * The SWD subsystem error codes
  27  */
  28 #define ERROR_SWD_FAIL  (-400)  /** protocol or parity error */
  29 #define ERROR_SWD_FAULT (-401)  /** device returned FAULT in ACK field */
  30
  31 /**
  32  * Construct a "cmd" byte, in lSB bit order, which swd_driver.read_reg()
  33  * and swd_driver.write_reg() methods will use directly.
  34  */
  35 static inline uint8_t swd_cmd(bool is_read, bool is_ap, uint8_t regnum)
  36 {
  37         uint8_t cmd = (is_ap ? SWD_CMD_APNDP : 0)
  38                 | (is_read ? SWD_CMD_RNW : 0)
  39                 | ((regnum & 0xc) << 1);
  40
  41         /* 8 cmd bits 4:1 may be set */
  42         if (parity_u32(cmd))
  43                 cmd |= SWD_CMD_PARITY;
  44
  45         /* driver handles START, STOP, and TRN */
  46
  47         return cmd;
  48 }
  49
  50 /* SWD_ACK_* bits are defined in <target/arm_adi_v5.h> */
  51
  52 /**
  53  * Test if we can rely on ACK returned by SWD command
  54  *
  55  * @param cmd Byte constructed by swd_cmd(), START, STOP and TRN are filtered off
  56  * @returns true if ACK should be checked, false if should be ignored
  57  */
  58 static inline bool swd_cmd_returns_ack(uint8_t cmd)
  59 {
  60         uint8_t base_cmd = cmd & (SWD_CMD_APNDP | SWD_CMD_RNW | SWD_CMD_A32);
  61
  62         /* DPv2 does not reply to DP_TARGETSEL write cmd */
  63         return base_cmd != swd_cmd(false, false, DP_TARGETSEL);
  64 }
  65
  66 /**
  67  * Convert SWD ACK value returned from DP to OpenOCD error code
  68  *
  69  * @param ack
  70  * @returns error code
  71  */
  72 static inline int swd_ack_to_error_code(uint8_t ack)
  73 {
  74         switch (ack) {
  75         case SWD_ACK_OK:
  76                 return ERROR_OK;
  77         case SWD_ACK_WAIT:
  78                 return ERROR_WAIT;
  79         case SWD_ACK_FAULT:
  80                 return ERROR_SWD_FAULT;
  81         default:
  82                 return ERROR_SWD_FAIL;
  83         }
  84 }
  85
  86 /*
  87  * The following sequences are updated to
  88  * ARM(tm) Debug Interface v5 Architecture Specification    ARM IHI 0031E
  89  */
  90
  91 /**
  92  * SWD Line reset.
  93  *
  94  * SWD Line reset is at least 50 SWCLK cycles with SWDIO driven high,
  95  * followed by at least two idle (low) cycle.
  96  * Bits are stored (and transmitted) LSB-first.
  97  */
  98 static const uint8_t swd_seq_line_reset[] = {
  99         /* At least 50 SWCLK cycles with SWDIO high */
 100         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 101         /* At least 2 idle (low) cycles */
 102         0x00,
 103 };
 104 static const unsigned swd_seq_line_reset_len = 64;
 105
 106 /**
 107  * JTAG-to-SWD sequence.
 108  *
 109  * The JTAG-to-SWD sequence is at least 50 TCK/SWCLK cycles with TMS/SWDIO
 110  * high, putting either interface logic into reset state, followed by a
 111  * specific 16-bit sequence and finally a line reset in case the SWJ-DP was
 112  * already in SWD mode.
 113  * Bits are stored (and transmitted) LSB-first.
 114  */
 115 static const uint8_t swd_seq_jtag_to_swd[] = {
 116         /* At least 50 TCK/SWCLK cycles with TMS/SWDIO high */
 117         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 118         /* Switching sequence from JTAG to SWD */
 119         0x9e, 0xe7,
 120         /* At least 50 TCK/SWCLK cycles with TMS/SWDIO high */
 121         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 122         /* At least 2 idle (low) cycles */
 123         0x00,
 124 };
 125 static const unsigned swd_seq_jtag_to_swd_len = 136;
 126
 127 /**
 128  * SWD-to-JTAG sequence.
 129  *
 130  * The SWD-to-JTAG sequence is at least 50 TCK/SWCLK cycles with TMS/SWDIO
 131  * high, putting either interface logic into reset state, followed by a
 132  * specific 16-bit sequence and finally at least 5 TCK/SWCLK cycles with
 133  * TMS/SWDIO high to put the JTAG TAP in Test-Logic-Reset state.
 134  * Bits are stored (and transmitted) LSB-first.
 135  */
 136 static const uint8_t swd_seq_swd_to_jtag[] = {
 137         /* At least 50 TCK/SWCLK cycles with TMS/SWDIO high */
 138         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 139         /* Switching sequence from SWD to JTAG */
 140         0x3c, 0xe7,
 141         /* At least 5 TCK/SWCLK cycles with TMS/SWDIO high */
 142         0xff,
 143 };
 144 static const unsigned swd_seq_swd_to_jtag_len = 80;
 145
 146 /**
 147  * SWD-to-dormant sequence.
 148  *
 149  * This is at least 50 SWCLK cycles with SWDIO high to put the interface
 150  * in reset state, followed by a specific 16-bit sequence.
 151  * Bits are stored (and transmitted) LSB-first.
 152  */
 153 static const uint8_t swd_seq_swd_to_dormant[] = {
 154         /* At least 50 SWCLK cycles with SWDIO high */
 155         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 156          /* Switching sequence from SWD to dormant */
 157         0xbc, 0xe3,
 158 };
 159 static const unsigned swd_seq_swd_to_dormant_len = 72;
 160
 161 /**
 162  * Dormant-to-SWD sequence.
 163  *
 164  * This is at least 8 TCK/SWCLK cycles with TMS/SWDIO high to abort any ongoing
 165  * selection alert sequence, followed by a specific 128-bit selection alert
 166  * sequence, followed by 4 TCK/SWCLK cycles with TMS/SWDIO low, followed by
 167  * a specific protocol-dependent activation code. For SWD the activation code
 168  * is an 8-bit sequence. The sequence ends with a line reset.
 169  * Bits are stored (and transmitted) LSB-first.
 170  */
 171 static const uint8_t swd_seq_dormant_to_swd[] = {
 172         /* At least 8 SWCLK cycles with SWDIO high */
 173         0xff,
 174         /* Selection alert sequence */
 175         0x92, 0xf3, 0x09, 0x62, 0x95, 0x2d, 0x85, 0x86,
 176         0xe9, 0xaf, 0xdd, 0xe3, 0xa2, 0x0e, 0xbc, 0x19,
 177         /*
 178          * 4 SWCLK cycles with SWDIO low ...
 179          * + SWD activation code 0x1a ...
 180          * + at least 8 SWCLK cycles with SWDIO high
 181          */
 182         0xa0, /* ((0x00)      & GENMASK(3, 0)) | ((0x1a << 4) & GENMASK(7, 4)) */
 183         0xf1, /* ((0x1a >> 4) & GENMASK(3, 0)) | ((0xff << 4) & GENMASK(7, 4)) */
 184         0xff,
 185         /* At least 50 SWCLK cycles with SWDIO high */
 186         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 187         /* At least 2 idle (low) cycles */
 188         0x00,
 189 };
 190 static const unsigned swd_seq_dormant_to_swd_len = 224;
 191
 192 /**
 193  * JTAG-to-dormant sequence.
 194  *
 195  * This is at least 5 TCK cycles with TMS high to put the interface
 196  * in test-logic-reset state, followed by a specific 31-bit sequence.
 197  * Bits are stored (and transmitted) LSB-first.
 198  */
 199 static const uint8_t swd_seq_jtag_to_dormant[] = {
 200         /* At least 5 TCK cycles with TMS high */
 201         0xff,
 202         /*
 203          * Still one TCK cycle with TMS high followed by 31 bits JTAG-to-DS
 204          * select sequence 0xba, 0xbb, 0xbb, 0x33,
 205          */
 206         0x75, /* ((0xff >> 7) & GENMASK(0, 0)) | ((0xba << 1) & GENMASK(7, 1)) */
 207         0x77, /* ((0xba >> 7) & GENMASK(0, 0)) | ((0xbb << 1) & GENMASK(7, 1)) */
 208         0x77, /* ((0xbb >> 7) & GENMASK(0, 0)) | ((0xbb << 1) & GENMASK(7, 1)) */
 209         0x67, /* ((0xbb >> 7) & GENMASK(0, 0)) | ((0x33 << 1) & GENMASK(7, 1)) */
 210 };
 211 static const unsigned swd_seq_jtag_to_dormant_len = 40;
 212
 213 /**
 214  * Dormant-to-JTAG sequence.
 215  *
 216  * This is at least 8 TCK/SWCLK cycles with TMS/SWDIO high to abort any ongoing
 217  * selection alert sequence, followed by a specific 128-bit selection alert
 218  * sequence, followed by 4 TCK/SWCLK cycles with TMS/SWDIO low, followed by
 219  * a specific protocol-dependent activation code. For JTAG there are two
 220  * possible activation codes:
 221  * - "JTAG-Serial": 12 bits 0x00, 0x00
 222  * - "Arm CoreSight JTAG-DP": 8 bits 0x0a
 223  * We use "JTAG-Serial" only, which seams more generic.
 224  * Since the target TAP can be either in Run/Test Idle or in Test-Logic-Reset
 225  * states, Arm recommends to put the TAP in Run/Test Idle using one TCK cycle
 226  * with TMS low. To keep the sequence length multiple of 8, 8 TCK cycle with
 227  * TMS low are sent (allowed by JTAG state machine).
 228  * Bits are stored (and transmitted) LSB-first.
 229  */
 230 static const uint8_t swd_seq_dormant_to_jtag[] = {
 231         /* At least 8 TCK/SWCLK cycles with TMS/SWDIO high */
 232         0xff,
 233         /* Selection alert sequence */
 234         0x92, 0xf3, 0x09, 0x62, 0x95, 0x2d, 0x85, 0x86,
 235         0xe9, 0xaf, 0xdd, 0xe3, 0xa2, 0x0e, 0xbc, 0x19,
 236         /*
 237          * 4 TCK/SWCLK cycles with TMS/SWDIO low ...
 238          * + 12 bits JTAG-serial activation code 0x00, 0x00
 239          */
 240         0x00, 0x00,
 241         /* put the TAP in Run/Test Idle */
 242         0x00,
 243 };
 244 static const unsigned swd_seq_dormant_to_jtag_len = 160;
 245
 246 struct swd_driver {
 247         /**
 248          * Initialize the debug link so it can perform SWD operations.
 249          *
 250          * As an example, this would switch a dual-mode debug adapter
 251          * into SWD mode and out of JTAG mode.
 252          *
 253          * @return ERROR_OK on success, else a negative fault code.
 254          */
 255         int (*init)(void);
 256
 257         /**
 258          * Queue a special SWDIO sequence.
 259          *
 260          * @param seq The special sequence to generate.
 261          * @return ERROR_OK if the sequence was queued, negative error if the
 262          * sequence is unsupported.
 263          */
 264         int (*switch_seq)(enum swd_special_seq seq);
 265
 266         /**
 267          * Queued read of an AP or DP register.
 268          *
 269          * @param Command byte with APnDP/RnW/addr/parity bits
 270          * @param Where to store value to read from register
 271          * @param ap_delay_hint Number of idle cycles that may be
 272          * needed after an AP access to avoid WAITs
 273          */
 274         void (*read_reg)(uint8_t cmd, uint32_t *value, uint32_t ap_delay_hint);
 275
 276         /**
 277          * Queued write of an AP or DP register.
 278          *
 279          * @param Command byte with APnDP/RnW/addr/parity bits
 280          * @param Value to be written to the register
 281          * @param ap_delay_hint Number of idle cycles that may be
 282          * needed after an AP access to avoid WAITs
 283          */
 284         void (*write_reg)(uint8_t cmd, uint32_t value, uint32_t ap_delay_hint);
 285
 286         /**
 287          * Execute any queued transactions and collect the result.
 288          *
 289          * @return ERROR_OK on success, Ack response code on WAIT/FAULT
 290          * or negative error code on other kinds of failure.
 291          */
 292         int (*run)(void);
 293
 294         /**
 295          * Configures data collection from the Single-wire
 296          * trace (SWO) signal.
 297          * @param swo true if SWO data collection should be routed.
 298          *
 299          * For example,  some debug adapters include a UART which
 300          * is normally connected to a microcontroller's UART TX,
 301          * but which may instead be connected to SWO for use in
 302          * collecting ITM (and possibly ETM) trace data.
 303          *
 304          * @return ERROR_OK on success, else a negative fault code.
 305          */
 306         int *(*trace)(bool swo);
 307 };
 308
 309 int swd_init_reset(struct command_context *cmd_ctx);
 310
 311 #endif /* OPENOCD_JTAG_SWD_H */