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