src/jtag/swd.h

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